If you’re not yet using source control with your Xcode projects, it’s something you want to seriously consider before a project you’re working on hits serious trouble. Setting up source control is easy when you create a new project (just tick the box in the project set up window), but figuring out how to add it to projects you’ve already created is a bit more challenging. In this post we’ll look at the ‘why’ and the ‘how’ of adding source control to an existing project.

Why?
In most normal applications, ‘Command-S’, Versions, Time Machine or other back up will save your hide when you either lose a document or realise a whole bunch of recent changes are something of a disaster. Recovering or reverting a document are mechanisms Apple has put a lot of time and effort into since Lion first appeared (changes I haven’t always been a fan of…).

However, these mechanisms do not work well with Xcode due to the complex and deep links between files in an Xcode build. If you’ve ever tried to go back to an earlier version of an Xcode project or undo some change from last week, and ended up with a headache, you’ll know what I’m talking about.

That’s what snapshots are for, you say? Yes, maybe. When they work. But in my experience snapshots themselves get lost, corrupted, or simply fail to restore.

Moreover, source control has other benefits aside from recovery and reversion that neither snapshots or any other mechanism provide. It’s primary purpose is to allow you to develop parallel but different versions of your project at the same time (a process known as ‘forking’). What if you want to experiment with adding some new feature, but don’t want to risk making changes right across your code that would be needed to try it out? What if you want to create one version of your project for one set of users and another one for others, or one version for an earlier OS X iteration and another for the current release?

How?
Let’s get down to the nitty gritty. Let’s assume you’re convinced you want to add source control to your current project. The first thing you’ll need to do is install git if you haven’t already. If you’re not sure, open Terminal and enter

git --version

If you get back a version number, continue on to the next step. If not, you’ll need to install git first. Follow the instructions for doing that here and then return to this post.

Once git is installed, here’s the steps for adding source control to your existing repository:


1. Locate the project folder
Select the project in the sidebar on the right, and click the little ‘Open in Finder’ arrow on the right.

Once you’ve got the parent folder open in ‘Finder’, quit Xcode.


2. Open Terminal and switch to the project’s parent folder
Click on the project’s parent folder icon in Finder and drag it to a Terminal.app window. Hit ‘control-A’ on your keyboard to move the cursor to the beginning of the line and type ‘cd’. Press ‘return’ to complete the command.

I always like to do a quick ‘ls’ to double check I’m in the folder I think I am, and that it contains what I think it does.

3. Initialize, Add, & Commit
Next, we’re going to hit a series of Terminal commands, one after the other. Press ‘return’ on your keyboard after each one:

git init
git add .
git commit -m "Initial commit"

Notice that there’s a period after a space on the end of the second command. Don’t forget to include it.


4. Confirm your local repository
Reopen Xcode, and hit the ‘Source Control’ menu. You should now see the options are active.

Congratulations! You just added a local repository to your project. You can now go ahead and start creating branches (‘forking’) by choosing the Source Control > master > menu item.

You’ll notice that when you make changes in your Xcode project, an ‘M’ (‘modified) will appear next to the files that have been changed. When you’re happy that these are changes that you’re going to keep, use Source Control > Commit. Full documentation on how to use the various features of source control are available in Xcode’s documentation.


5. Add a remote repository
Local repositories are great, and may be enough for your needs, but for ultimate protection (such as against disk loss or failure), you might want to add remote back up. To do that, you’ll need an account with a service like GitHub or Bitbucket. My own personal preference is Bitbucket, largely because they allow you to have private repositories on a free account. Steps for adding your existing project to a remote repository can be found on your chosen service’s website. If you’re using Bitbucket, the general method is first create a new repository on the Bitbucket site and copy the link. Then, enter each of the following in Terminal, replacing the dummy text in square brackets with your actual values (remove the square brackets, too).

cd [path to your repo]
git remote add origin [url to your repository]
git push -u origin --all
git push -u origin --tags

After that, re-open your project in Xcode and you should be all set up. Check by ensuring the remote path is shown in Source Control > –> master > Configure…