Using Subversion with Xcode 3.0

When you’re coding a huge project in Xcode, and you’ve written all of this awesome stuff, it’s almost done, and the big release is coming soon, that’s when the worst happens:

  1. The hard drive that had all of your code on it dies suddenly
  2. You didn’t have a backup in TimeMachine
  3. Files become corrupted
  4. You remove some important code, or overwrite it, accidentally – and save over your only copy; and you don’t know how you’ll ever manage to rewrite those thousands of lines of code over again
  5. All of the above

This is where Subversion (called “SVN” for short) comes in handy.

What does it do? Well, in addition to storing a backup copy of your files, it is a “version control” system. This means that every time you upload a new/changed copy of something, it’s saved as a new revision of the file, not replacing the existing. All of those revisions are kept, so if you need to “roll back” to a previous version, you only need to tell the “repository” which version you want.

In practice, it’s not quite that simple. Subversion is mostly a console-based, text-only application, which is difficult for the average user. I’m holding out hope that “Versions” (a Mac SVN client) will show up soon, but it’s been in “coming soon” mode for a while. svnX is another Cocoa-based option, but difficult to use.

Fortunately, since version 1.5, Xcode has offered built-in support for Subversion. It wasn’t until more recently that they got the kinks worked out. Sure, you can use SVN for other types of files – images, binaries, and other bits of data, but code is the best use – you can “merge” changes in the text itself between revisions.

One thing that is important to note: you’ll need a “host” for your SVN repository. This can be your local machine (works on any Mac, Linux, or Windows box), but it’s easiest to find a server provider on the web somewhere. That allows for other people to access it (if needed), and it’s a safe, off-site backup. I’m using it to keep multiple computers “synced” with the latest copy of code.

I can recommend VersionShelf as a host; I’ve been using them for a little bit (still in my 30-day trial). There are others out there – if you know of a better one, please note it in the comments.

Once you create a repository, you must upload the project the first time using the console or some other safe SVN client. Xcode doesn’t work for the initial upload. You’ll then need to download a “working copy” from the repository to begin using SVN properly.

How to upload (you’ll need to understand basic Unix terminal commands for this part):

(if you haven’t already, you’ll need to install the SVN client – get it here)

  1. Open Terminal from /Applications/Utilities/
  2. Type svn import localpath subversionpath -m "Initial import", where localpath is the directory containing your Xcode project that you wish to upload, and the subversionpath is the destination directory of your subversion repository that you set up

It will most likely ask for your password. Once that’s done, you’ll need to re-download the files that you just uploaded, so that they’re set as a “working copy”.

Fortunately, you can do this with Xcode.

  1. Open Xcode, and click “Preferences” under the “Xcode menu…
  2. Choose the “SCM” tab.
  3. Click the addition sign button under the “Repositories” list to create a new entry.
  4. Type any name you want in the “Name” field, and type in the information your SVN provider gave you for the URL, user, and password fields. Xcode should be able to fill in the boxes in between, usually.
  5. Click OK.
  6. If the “Repositories” window doesn’t appear, get it from the “SCM” menu.
  7. Choose your new repository from the list. You should see a file browser… file the folder that you just uploaded. Click it, and click the “Checkout” button in the toolbar.
  8. It will ask you where to save it. I don’t recommend overwriting the old copy – put it somewhere else for safe keeping.

Once you’ve downloaded the new copy, you will from then on work with it – don’t use your old one. SVN makes some hidden changes to the files to make them work for versioning.

Using SCM in Xcode - changes in file list Now when you edit and save files, you’ll see letters on the left side of the “Groups & Files” list in Xcode, marking directories and files. “M” means modifications have been made to your local “working copy” that you must “commit” to the repository. “U” means the repository has been updated, and you’ll need to update your now out-of-date local working copy.

Xcode SCM menu You can use the “Commit” and “Update” commands (when you have files selected in the Groups & Files list) in the “SCM” menu in Xcode to download or upload changes to/from the repository.

For more on Subversion, and how it works, check out the free online book from O’Reily.

I’m exploring automated builds (and exporting those builds to a template DMG automatically), and I’ll see if I can come up with a tutorial once I figure it out.


Comments have been disabled for this post