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
(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
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.

If you enjoy my content, please consider supporting me on Ko-fi. In return you can browse this whole site without any pesky ads! More details here.

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) 🙂

Leave a Comment!

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