How to place an existing Xcode project under Version Control with Git (and ignore files you don’t want to track)

- by

Usually when you create a new Xcode Project you can choose to setup a new Git repository. This is the best and easiest way to track your changes. However if you have a project that is not under version control you can create a Git repository retrospectively.

This is fairly straightforward using the Terminal app on your Mac (under Applications / Utilities):

  • cd into the directory where your project resides
  • then initialize an empty repository (git init)
  • and add the entire directory to it (git add .)
  • commit your changes (git commit -m “initial commit)

So far so good. However Mac has a hidden directory called .DS_Store in every directory – we may not want to track that. Plus, every time you make a minor UI change in Xcode (such as open a group in the file explorer or something that is not relevant to your actual code) Xcode tracks this change in a file called UserInterfaceState.xcuserstate, and we definitely do NOT want to track that.

To tell Git that we don’t want those two things, we’ll amend our previous instructions a bit:

  • cd into the directory where you project resides
  • create a file called .gitignore
  • add each file or directory on a new line
  • then create, add and commit your files to Git

Let’s assume my project is called MyProject, then the steps are as follows:

cd MyProject
vi .gitignore

(add the following lines to that file)
# ignore these files
.DS_Store
MyProject.xcodeproj/project.xcworkspace/xcuserdata/myusername.xcuserdatad/UserInterfaceState.xcuserstate
(save and exit vi by pressing SHIFT-Z-Z)

git init
git add .
git commit -m "initial commit, omitting several files"

If you have already committed all your files and forgot to setup the .gitignore file you must manually remove the files/directories you don’t want from being tracked. This is how you’d do that:

git rm --cached .DS_Store
git rm --cached # ignore these files
.DS_Store
MyProject.xcodeproj/project.xcworkspace/xcuserdata/myusername.xcuserdatad/UserInterfaceState.xcuserstate
git commit -m "removing files I no longer want"

Replace myusername with your own system user name obviously, and MyProject with the actual folder in which your project resides.

4 thoughts on “How to place an existing Xcode project under Version Control with Git (and ignore files you don’t want to track)”

  1. Well done! this is a very useful post.
    One question though:
    Isn’t the derived data folder stored separately in ~/Library/Developer/Xcode/ ?
    If so, it would not be included in GIT commits anyway, so why adding it to .gitignore?

  2. Hi Arik, I must pass I’m afraid – perhaps this is a question for @adamgit whom I’ve forked the gist from. I was mainly concerned with the interface state since it’s system dependant: if were to I checkout my project on a different system, the interface state doesn’t necessarily look great with another screen resolution. The gist helped prevent confusing Xcode on another system.

    Mind you, that was 2 years ago – perhaps Apple have started fixing things by now (we live in hope) 🙂

Add your voice!

This site uses Akismet to reduce spam. Learn how your comment data is processed.