Xcode and SVN

When setting up Xcode to use Subversion (SVN) as its Source Code Management (SCM) system for a new project, I encountered a few hiccups. Nothing too major, and I’m sure that some of them were due to my unfamiliarity with Xcode, but I thought it would be worthwhile to post some notes on my experience.

Environment

These comments apply to Xcode 3.1.2, on Mac OS X 10.5.6, using SVN for source control. YMMV even if you’re in exactly the same environment, of course.

Global Ignores

Xcode stores two kinds of files in its PROJECTNAME.xcodeproj administrative directories: The project file, in a project.pbxproj file, and per-user preferences, in USERNAME.mode1v3 and USERNAME.pbxuser files. (Apparently, a USERNAME.mode2v3 file also appears sometimes.) The project file should go under source control, but I feel that the per-user preferences should not.

To tell SVN to ignore the per-user preferences, edit the ~/.subversion/config file. (You may need to run the svn command (from the shell prompt) once to create the ~/.subversion directory.) Uncomment the global-ignores line in this file, and append the entries “*.mode1v3” and “*.pbxuser”. The final line should look something like this:

global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store *.mode1v3 *.pbxuser

Create a Project

The first step in placing an Xcode project under source control is to (if necessary) create the project in Xcode. If you’ve already got a project set up, you can skip this step.

Remove Build Directories

Next, you should remove any “build” directories associated with the project. (You don’t want to clutter SVN up with all that junk, and you’re going to import the entire project tree in the next step.) The location of the “build” directories can be found on the “General” tab of the project settings dialog (Project->Edit Project Settings) in the “Place Build Products In:” and “Place Intermediate Build Products In:” items.

A quick rm -R -f should do the trick. (This stuff will be re-created the next time you build.) Naturally, if you’ve never built, the directories may not exist, and you can skip this step.

Import

Now you want to add the project to source control for the first time. (This assumes you’re creating a new project, and not simply checking out an existing one.) Open a shell prompt, cd into the project directory, and run svn import, like so:

svn import https://machine.domain.com/repository/project/trunk

where the URL is appropriate for your SVN setup. (Parent directories will be created as necessary.)

Checkout

Now, the most counter-intuitive part: You must delete the project directory from your local disk, s.t. you can check it out from SVN. (SVN won’t overwrite an existing directory during a checkout.) Move into the parent of the project, and rm -R -f the directory you just imported.

Now, use the svn co command:

svn co https://machine.domain.com/repository/project/trunk project_dir

where the URL is the one you just imported, and project_dir is the one you just deleted.

Configure the Project in Xcode

In Xcode, open the project you just checked out. Go to the “General” tab of the project settings dialog (Project->Edit Project Settings) and select the appropriate SVN repository from the drop-down in the “SCM Repository:” item. If no appropriate SVN repository is listed (i.e. you haven’t configured one yet), choose the “Configure SCM Repositories…” item, and add one in the displayed dialog. (Use the ‘+’ button in the Xcode Preferences/SCM/Repositories dialog to add a new SVN repository. Fill in the Name, URL, User, and Password fields; the others will populate automatically.)

The notion of an “appropriate” SVN repository is a little fuzzy; since the project root already has a .svn subdirectory (which specifies the repository, path, etc.) and since your login credentials are cached in the ~/.subversion directory, I think that the real point of the project’s “SCM Repository:” item is to tell Xcode what kind of SCM system you’re using, rather than specifically where the repository lives. Nevertheless, I guess you want to point the project to the root of the relevant SVN repository, just to be safe.

Ignore the Build Directory

You’ll want SVN to ignore the “build” directories associated with the project. Assuming that these directories are underneath the root project directory (that’s typical; if they’re not, you can skip this step) you should open a shell prompt and cd to the project root. Create a file named “i.txt” which lists the relative pathnames of the “build” directories, one per line. Then run the following commands:

svn propset svn:ignore . -F i.txt
svn commit -m "Ignoring build directories"
svn update

and then delete the i.txt file. BTW, in a typical configuration, the i.txt file will simply consist of a single line, containing only the word “build”. (The default project configuration uses a single subdirectory, named “build”, for both final and intermediate build products, and locates this directory immediately underneath the project root.)

Care and Feeding

At this point, your project is under SVN version control. You can control SVN from the SCM menu in Xcode. I’d only add two remarks:

Diff vs. Compare: In various menus, Xcode offers you the option to either “Diff” or “Compare” files. “Diff” commands yield SVN-style diff reports, while “Compare” commands yield (nicer?) GUI reports. Other than that, the commands seem to do the same things.

Xcode’s “Repositories” Dialog: This guide has relied upon the svn command in parts. Xcode has a repository management dialog (accessible as SCM->Repositories) that looks like it might be able to handle some of those steps. Unfortunately, I’ve never been able to get that dialog to do what I want. The svn utility, OTOH, does exactly what I want, so I don’t cover the GUI here. Perhaps you’ll find the GUI more useful than I did, however.