Should *.xccheckout files in Xcode5 be ignored under VCS?

Question

Apple has introduced a new project-related type of file in Xcode 5: "xccheckout".

This file is located in the ".xcodeproj/project.xcworkspace/xcshareddata/" directory, and it seems that it is related to the project's version control system.

An example file is here: http://pastebin.com/5EP63iRa

I suppose that this type of file should be ignored under VCS, but I'm not sure.

So here are the questions:

1. Should "xccheckout" be ignored?
2. What is its purpose?

Solution 1

You should check in an Xcode 5 .xccheckout file; in general, files in xcshareddata should be committed.

An .xccheckout file contains metadata about what repositories are used in a workspace. For a single project in a single repository that doesn't make much difference. But if you're using a workspace that has multiple projects from different repositories, the presence of an .xccheckout file in the workspace allows Xcode to know what all of the components that make up a workspace are and where to get them.

Solution 2

The *.xccheckout file contains VCS metadata, and should therefore not be checked into the VCS.

On the other hand: checking in this file will probably not create merge difficulties or other problems.

If you want to ignore this file (which I recommend) you should add this line to your project's .gitignore:

*.xccheckout

Abizern's solution will not work for projects inside a workspace. Because, when you use a workspace, the path to the *.xccheckout file will be: <workspace-name>.xcworkspace/xcshareddata/<workspace-name>.xcchekout. And it actually ignores more than you would want.

Edit: This file exists for managing Xcode's knowledge of the possibly many VCS systems in your project, see Chris Hanson answer. For > 99% of the projects the .xccheckout file is configuration overkill.

Solution 3

It depends. The file contains references to the remote repository you are using. If you are using a centralized VCS such as Perforce or Subversion, everyone's remote repository will be the same and so you can and should check the file in.

If you are using a distributed VCS such as Mercurial or git, but using it as though it were a CVCS (in other words, everyone cloned from a shared repository directly to their personal workspace on their machine) then you still might want to check it in.

However, if you are using a DVCS with everyone having their own remote clone, for example using GitHub in it's standard usage pattern, you DO NOT want to check this file in. If you did then your Pull Requests will be asking for your repository settings to get copied into everyone else's xccheckout file, but your repository settings will be different from everyone else's because you are all using different remote repositories.

Solution 4

Yes, the Project.xccheckout file should be committed to your repository. Xcode uses this file to tell others who open the workspace the entire list of source control repositories used by the workspace and the location of the working copy relative to the workspace, whether those repositories are Git, SVN, or both.

When you open the workspace, Xcode uses the Project.xccheckout file to notify the user that there are other repositories forming part of the workspace, and asks which should be checked out. When checking out additional repositories, Xcode places the working copies in the same workspace-relative folder structure as they were when the Project.xccheckout file was generated.

As Chris Hanson said, it probably doesn't matter for a single-repository, one-project workspace, but for more complex affairs it'll be very handy indeed.

You can find out more about this in the WWDC 2013 session video Understanding Source Control in Xcode; the relevant portion starts at about 15 minutes.

Solution 5

This is what I have in my .gitignore for Xcode.

#Xcode
*.xcuserstate
project.xcworkspace/
xcuserdata/

It keeps anything that relates to the local state of the way the projects looks for me out of the repository.

The xccheckout file is under here so it is not tracked on my system by default.

Xcode has gotten better and separating out what needs to be shared and what needs to be kept locally. For example; these lines will ignore the default build schemes, which is fine because you can mark specific build schemes as shared, and they are put in a directory that is not ignored.

Breakpoints are ignored, but you can mark specific breakpoints as being shared across projects and they are also placed in a directory that is not ignored.

View more solutions

Comments

[Artem Abramov]

This question tends to be quite relevant; thus I'd like it to be more grammatically and syntactically correct. If you're native English speaker or you're extremely proficient in English I'd like to ask for a help in checking my language. Thank you!

[Sofi Software LLC]

Minor suggested changes: "Apple has introduced a new", "An example file is here:". There's a mismatched quote in question 1.

[eliocs]

I always refer to the github/gitignore repo to know which files should be ignored -> github.com/github/gitignore/blob/master/Objective-C.gitignor‌​e

[Mark Edington]

It would be terrific if you could expand on this statement "it actually ignores more than you would want". Specifically, some examples of other files that go into that folder that should be checked in.

[Mark Edington]

Follow-up: I'm using a .gitignore from Adam from this question. It's available as a gist and it has some description of xcshareddata folder contents.

[Berik]

@Mark: It ignores the project.xcworkspace/. That might be oke for now, but I would not count on that for new Xcode versions.

[Berik]

The current version of github's .gitignore contains the *.xccheckout. Use that one

[Chris Hanson]

This answer is incorrect, and GitHub's standard .gitignore that it provides to developers should not specify *.xccheckout

[Joshcodes]

If it was not meant to be shared Apple would store it in .xcuserdata so it should be included.

[Chris Hanson]

See my own answer below. Everything in xcshareddata is intended to be checked in, I list the reasons for xccheckout files to be checked in specifically.

[Pascal]

I wonder why Apple chose to do this as all this information is contained in .git and .gitmodules. Maybe this makes it work if you're not using submodules and only use Xcode for version control. Oh, or so that it's consistent no matter which VCS you use.

[Chris Hanson]

As I said in my answer, the xccheckout file contains information for all repositories used in a workspace. That's the case regardless of what SCM system they use - such a workspace can be in svn or git, and its projects can be in a mix of svn and git repositories.

[Jack Nutting]

I'm really puzzled by why Berik says that Chris Hanson's answer is correct, then immediately states the exact opposite! Berik, I think you need to clarify what you mean by this answer. Currently it's analogous to "Doctors say that smoking is dangerous, and they are correct. Tobacco is harmful, and therefore you should continue smoking." Does not compute!

[Herr Grumps]

It looks like xccheckout contains keys and names which are specific to each developer's machine... As soon as I run xcode it changes some keys in the file, and it changes something called IDESourceControlWCCName from <string>OurCompanyAPI</string> to <string>our_company_api/string> - the latter being the name I used when cloning the repo. If this file is supposed to be shared, then Apple have done a pretty poor job.

[Artem Abramov]

Since your argument are quite weighty your answer was chosen as "Correct". Thank you for contribution!

[ArpitM]

I'm on a project that's currently using SVN. I'm on a branch and the .xccheckout file has been updated for my branch URL. Do I simply not merge that portion into our main line? What a mess.

[Cœur]

When we check in this file, all my co-workers get a different IDESourceControlProjectIdentifier ... so our .xccheckout get modified with each commit. -_-

[Tom Dalling]

@HerrGrumps +1. If you're using github and pull requests, xccheckout will always be wrong. The git repo URL will be the repo getting pulled from (each user's personal repo), not the repo getting pulled into.

[danyowdee]

While all fine and dandy in theory, I have yet to see this Xcode feature working consistently, and reliably. Every time I tried to use it, it ended in me, and my colleagues cursing the attempt (e.g. openradar.appspot.com/radar?id=6446716249178112 which appears to be fixed, now). The last such attempt was today, July 31 2014. Xcode6-beta4 is pretty much ignoring that file altogether, while Xcode5 will happily delete the entries of optional working copies unless you use Xcode5 for all your SCM operations (see openradar.appspot.com/radar?id=5282732867321856). What a mess

[eonil]

Regardless of what Apple originally intended for, the .xccheckout files are causing some insane issues on Xcode 6 beta, and I decided to remove them from VCS. Seem to be related to some caching bug, and I believe Xcode can regenerate them from VCS automatically, for each time.

[johnnieb]

I'm utterly confused. The latest standard .gitignore for Objective-C on Github excludes *.xccheckout. It would be awesome if someone in the community could come with a definitive answer. Apple's lack of documentation on this is appalling.

[Bradley Thomas]

@Tom_Dalling so does that mean that if I'm using git to pull on my office and home machine, I just have to live with always checking in a new xccheckout file that flip flops between two configs? See my question here stackoverflow.com/questions/26539047/…

[Frizlab]

The .xccheckout file should be in your VCS. I'm trying to use Xcode's 6 continuous integration on a project with submodules, and I have the xccheckout file in my gitignore. I'm pretty sure it doesn't work because of this (can't test for sure right now). The closest thing I found resembling a documentation from Apple was this developer.apple.com/library/ios/documentation/IDEs/Conceptua‌​l/… (no xccheckout in gitignore, at end of document). Also, xccheckout is in xcshareddata…

[Pascal]

After including this file in my repos since it has been introduced, I have recently started to remove it from all my repos. This thing is creating merge conflicts all the time, mostly in projects that include my own frameworks as submodules. And then I gain nothing from this file since I use git for submodule management. Nice try, Apple, thanks, but no thanks.

[Andrew]

if you use ssh_config to handle hostnames then the git repo url will change for multiple developers

[Juan Carlos Méndez]

This answer seems to me the best. Checking them in was causing unnecessary chattiness on the diffs for our team commits. I add to .gitignore the following to keep them out: */.xcworkspace/xcshareddata/*.xccheckout I still don't understand why Apple chose to redundantly store this information that anyway is in the .git folder (my only guess is to make things work consistently across VCS)

[Alex Zavatone]

I am assuming that this means that .xcscmblueprint files MUST also be checked in? If not, then why not? I've got the xcscmblueprint tree conflict in Xcode 7 now trying to merge back to our master and had a hell week when others on the team ignored it.

[Carlos Ricardo]

This file is only useful if you use Xcode for SCM, otherwise, you don't need that file at all. And even less if you work with git forks, in that case, the repo path will be unique per developer

[Cœur]

@Frizlab, can you re-post your comment with this updated link: developer.apple.com/library/content/documentation/IDEs/…