Blog Post

Using Subversion with Xcode 3.0

Stay on Top of Enterprise Technology Trends

Get updates impacting your industry from our GigaOm Research Community
Join the Community!

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.

21 Responses to “Using Subversion with Xcode 3.0”

  1. rhimbo

    If I install my repository locally on my Mac, do I need to have an svn server daemon running? What process controls access to the “server” when I execute “client” svn commands, either from the command line or from Xcode?


  2. Colin Caufield

    I successfully followed all of the steps up until #7, and then things fell apart. Although the SCM section of the XCode Preferences tells me everything is working, the Repositories browser always fails with the following message:

    – list https://[email protected]/PyCathode
    –Error: 175002 (RA layer request failed) Description: REPORT request failed on ‘https://[email protected]/PyCathode’
    –Error: 175002 (RA layer request failed) Description: REPORT of ‘https://[email protected]/PyCathode’: Could not parse response status line. (

    The funny thing is, invoking svn from the command line never causes problems.

    There are other postings about this problem on the net, but no solutions.

    Can anyone help? Thanks.

  3. nullPtr

    We use Its cheap, fast, and has lots of features. Plus, 45-day free trial, so if you’re on a shorter project, its effectively free.

  4. You can use Eclipse + Subclipse plugin to do the subversion working copy setup then follow the XCode steps above. That way you can use Eclipse as another SVN GUI. The Subclipse plugin is very good and is a lot like the Tortoise SVN client on windows. Then you can use the eclipse project to look up file history/compare/show anotation/merge/branch (Eclipse’s show annotation is very useful).

  5. bwise

    How do you deal with xcode project files. If two people make changes to the project at all, the project file will change. Then there is no nice way to merge the files right?

    This is blocking us from using svn on xcode projects and its a major pain.

  6. If you are using local svn repository for your personal use following repository configuration might help while adding it to xcode.

    URL: file:///Path/To/Local/Repository
    Scheme: file
    Host: [leave blank]
    Path: /Path/To/Local/Repository
    Port: [leave blank]
    User: [leave blank]
    Password: [leave blank]

    Btw, xcode 3.0 did allow me to import my initial code into my local repository.

  7. A note for users of non-English environments: Xcode 2.5, and probably later versions too, parses the text output from Subversion and expects data in English. To work around this, create a shell script, e.g., with the following code:

    export LANG=en_GB.UTF-8
    export LC_ALL=$LANG
    /sw/bin/svn “[email protected]
    exit $?

    It is possible to tell Xcode which binary to use for svn, have a look around in the dialogs in the version you uses and point Xcode to your shell script.