Subversion is a tool which allows you to save code changes and then step back through the changes at a later date, or revert back to previous changes if things go wrong. It provides the following benefits:

• Mistakes matter less - you can always go back
• More than one person can work on the same code, without conflicts
• If you work on more than one machine you can save the code in a central location
• Loads more on the subversion website

If you do all your development on one machine and work alone, then you can get away with installing Subversion on your local machine (make sure you back everything up though!), this tutorial is aimed at you.

This tutorial is aimed mainly at Leopard users, who have Subversion pre-installed, but if you are using Tiger and have managed to install Subversion yourself it will work for you too.

Setting up the SVN Repository area on OS X

SVN comes preinstalled on OS X, but there is a little more work to be done before you can use it properly.

Open up terminal, and start by creating the folder that will hold your applications repositories:

Change ownership of this folder to www so it can be accessed through the web browser and the svn system will work:

Go into the apache conf area and edit svn.conf:

Enter the text

Save the text

Restart Apache:

Setting up a repository into OS X

Now we have our svn area set up, lets imagine we want to create a repository for a project, perhaps one we’ve already been working on before (although this will work even if you haven’t yet started).

First we want to create a sample set of folders which can be used time and time again to set up the default folder structure of the SVN repository. Choose a location on your system - I’ve done it in /Library/WebServer/Documents, and create the folder svn_default and within that /trunk, /branches and /tags. You can do this from terminal using the following commands:

Now we need to create your repository in the svn area we set up recently. Enter the following into terminal, substituting appname for the name of your app:

Check everything worked by going to http://localhost/svn/appname/.
You should see a webpage with a heading of Revision 0: /

Now you need to give the www authority to change files, so stick this into terminal

Next we want to create our default file system inside the SVN repository, so put the following into terminal:

You should see the following output:

Take a look at http://localhost/svn/appname, the heading should now say Revision 1, and you will see links showing the filesystem you added.

Now you want to put the working version of your app into the trunk folder. In my case, the app i want to add is in the Documents folder, and thats also going to be the place I want to continue working on it. Put the following into terminal, where /Library/WebServer/Documents/appname links to the location of your app.

You should now see all the files adding into the SVN repositiory, and at http://localhost/svn/appname you should be able to click on the Trunk link and see the files.

Now all the files are in the SVN, you need to check them out for the first time in order to start working on them.If you, like me, want to work on the same folder as the one you just uploaded from, you will need to remove that folder before continuing.

Then go to the directory above the one you want to work with - so instead of appname (which should no longer be in Documents anyway), go to Documents.

Then checkout the files

Now you should see the files in the appname folder. Well done, you can now make changes to files and use the commands listed below to add the changes and retrieve them from the SVN system.

Working with SVN repositories on OS X

Now you have a working repository you can use various commands to save and retrieve code changes.

You first must always navigate to the folder you set up in terminal, so following the above example it would be

Get the latest code

When you start work you should update to get any changes made, if more than one person is making changes to the code.

Find differences you made since the last commit

After updating, you might change some files, to find out what files you changed run

To find out exact changes run

Set a file back to how it was before

You’ve changed a file, but haven’t commited, and you don’t like what you’ve done. You can easily go back to the last committed copy by typing the following:

where path/to/file is the path from but not including appname. e.g. if I made an error in appname/path/to/file.php I would use the above path

Saving changes

After making all your changes you can save them back into the repository with the following command:

Adding a group of new files

When you add new files to a project they won’t automatically get added by Subversion. You can either add them one by one using

or try

Removing files

To remove a file or folder from your project, don’t just delete it from your local file system. Instead do this:

That marks them for deletion and removes it from the local file system, when you next commit, they will be deleted from the svn repository:

Tagging a version of your code

If you are happy with a version of your code and want to take a snapshot to make it easier to roll back should problems arise with the next version, you can create a copy with a tag. Remember the tags folder we created, thats a good place to put these tagged versions. Users can then download them from here, and not worry about small changes you may have made since.

To do this:

svn copy http://localhost/svn/appname/trunk http://localhost/svn/appname/tags/release-1.0 -m "Tagging the 1.0 release of the 'appname' project."

Creating a Branch

If you want to make a branch to continue working on a project, perhaps in a different way to before, a branch should be created.

To create a branch

svn copy http://localhost/svn/appname/trunk http://localhost/svn/appname/branches/branch1 -m "new branch"

We’re done

Thats enough to get started, for more information download the free Subversion book.