158

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?
Eric Galluzzo
  • 3,191
  • 1
  • 20
  • 20
Artem Abramov
  • 4,701
  • 4
  • 27
  • 38
  • 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! – Artem Abramov Nov 16 '13 at 03:27
  • 1
    Minor suggested changes: "Apple has introduced a new", "An example file is here:". There's a mismatched quote in question 1. – Sofi Software LLC Nov 19 '13 at 02:14
  • 3
    I always refer to the github/gitignore repo to know which files should be ignored -> https://github.com/github/gitignore/blob/master/Objective-C.gitignore – eliocs Jun 04 '14 at 10:22

5 Answers5

109

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.

Ben Collins
  • 20,538
  • 18
  • 127
  • 187
Chris Hanson
  • 54,380
  • 8
  • 73
  • 102
  • 8
    If it was not meant to be shared Apple would store it in `.xcuserdata` so it should be included. – Joshcodes Oct 11 '13 at 15:25
  • 1
    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. – Pascal Oct 12 '13 at 16:43
  • 4
    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. – Chris Hanson Oct 13 '13 at 00:54
  • 72
    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 OurCompanyAPI to 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. – Herr Grumps Nov 11 '13 at 12:41
  • Since your argument are quite weighty your answer was chosen as "Correct". Thank you for contribution! – Artem Abramov Mar 24 '14 at 11:56
  • 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. – Mr Rogers Mar 25 '14 at 22:58
  • 7
    When we check in this file, all my co-workers get a different IDESourceControlProjectIdentifier ... so our .xccheckout get modified with each commit. -_- – Cœur Mar 31 '14 at 11:41
  • @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_. – Tom Dalling Apr 21 '14 at 07:39
  • 1
    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. http://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 http://openradar.appspot.com/radar?id=5282732867321856). What a mess – danyowdee Jul 31 '14 at 22:03
  • 9
    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. – eonil Aug 28 '14 at 11:56
  • @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 http://stackoverflow.com/questions/26539047/switching-machines-xcode-6-keeps-wanting-me-to-modify-xccheckout – Bradley Thomas Oct 29 '14 at 12:55
  • if you use ssh_config to handle hostnames then the git repo url will change for multiple developers – Andrew Aug 27 '15 at 13:14
  • 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. – Alex Zavatone Aug 31 '16 at 15:55
63

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.

Community
  • 1
  • 1
Berik
  • 7,816
  • 2
  • 32
  • 40
  • 1
    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 Aug 30 '13 at 18:51
  • Follow-up: I'm using a .gitignore from [Adam](http://stackoverflow.com/users/153422/adam) from this [question](http://stackoverflow.com/questions/49478/git-ignore-file-for-xcode-projects). It's available as a [gist](https://gist.github.com/3786883) and it has some description of xcshareddata folder contents. – Mark Edington Aug 30 '13 at 19:05
  • @[Mark](http://stackoverflow.com/users/26219/mark-edington): It ignores the `project.xcworkspace/`. That might be oke for now, but I would not count on that for new Xcode versions. – Berik Sep 03 '13 at 11:13
  • The current version of github's `.gitignore` contains the `*.xccheckout`. Use [that one](https://github.com/github/gitignore/blob/master/Objective-C.gitignore) – Berik Sep 25 '13 at 13:14
  • 6
    This answer is incorrect, and GitHub's standard `.gitignore` that it provides to developers should **not** specify `*.xccheckout` – Chris Hanson Oct 09 '13 at 00:07
  • 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. – Chris Hanson Oct 11 '13 at 18:07
  • 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! – Jack Nutting Oct 28 '13 at 19:33
  • I'm utterly confused. The latest standard .gitignore for Objective-C on [Github](https://github.com/github/gitignore/blob/master/Objective-C.gitignore) 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. – johnnieb Oct 21 '14 at 16:52
  • 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 https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/xcode_guide-continuous_integration/PublishYourCodetoaSourceRepository/PublishYourCodetoaSourceRepository.html (no xccheckout in gitignore, at end of document). Also, xccheckout is in xcshareddata… – Frizlab Nov 30 '14 at 14:01
  • 2
    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. – Pascal Apr 23 '15 at 21:52
  • @Frizlab, can you re-post your comment with this updated link: https://developer.apple.com/library/content/documentation/IDEs/Conceptual/xcode_guide-continuous_integration/PublishYourCodetoaSourceRepository.html – Cœur Apr 05 '18 at 07:21
38

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.

Tim Band
  • 576
  • 4
  • 4
  • 1
    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) – Juan Carlos Méndez Sep 09 '15 at 16:06
20

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.

Community
  • 1
  • 1
Calrion
  • 3,202
  • 1
  • 28
  • 30
  • 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 – Carlos Ricardo Jan 27 '17 at 22:47
3

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.

Abizern
  • 146,289
  • 39
  • 203
  • 257