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

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?

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.

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.

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.

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.

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.