So you want to get Subversion running on your mac, complete with nifty finder integration?  Good, welcome to the wonderful world of revision control.

This little ditty will assume that you have an SVN repository to connect to already, and all you need is the client-side tools.  If this is not the case, then move on.

First, what exactly is version control?

That is a valid question, and one that I get pretty often when I am talking about CVS, SVN or Arch.  In short revision control breaks down like this:

1. A central location to house your source code.  This could be HTML and PHP files, or C++.
2. Version control allows you to maintain multiple versions of a file.  Each of these is a "revision".  In essence you change a "p" to a "q" in your file and upload that to your server, your revision control system will identify that there is a change and create a new "revision".  This does not destroy your previous file, it merely adds a new "version" of that file.
3. Version Control allows you to fall back to an older version of a file if needed.  In our case we actually wanted that "p" to be a "p", not a "q".  We are able to revert to that older file, but also have the newer file that might contain other bits that were changed that are still valid, at our fingertips.

Go that?  Excellent, moving on.

Working with Version Control

So now that we have established what version control is, how do we use it?  For basic operation there are only a few command we really need to know:

1. co: check out, this downloads the current or highest revision from the repository to our local machine.
2. diff: this checks our local file(s) and those on the remote server for differences.
3. add: if we have created a new file that is not on the server, you use add to tell SVN to upload it to the remote server on the next commit.
4. delete: we almost never use delete with SVN, the entire idea of revision control is to never lose anything.  That being said there are times that this command is useful.  Files marked for delete are removed at the next commit.
5. commit: we use commit when you are ready to send your local changes to the remote server, creating a new revision.

There are a number of other commands, such as mkdir (create a new directory) and blame (assign blame to someone for a screwup... one of my favorites.) but those outlined above are the most used.

Setting SVN up on your Mac.

The easiest way to install SVN is by browsing to the binary downloads page and scrolling down until you find MacOS X.  You will want the second link, the one that does not rely on Fink.  Grab the 1.2.1 (or whatever is the newest) binary from the Metissian page and install it.

After the installer has run its course you now have a running SVN client on your mac.  Next we have to decide how we are going to access that SVN client.

There are two ways to use SVN on your MacOS X box, either through the terminal or through a third party GUI based solution.  I will not cover the terminal in depth since for most of us a Finder integrated solution is superior.  But for the sake of completeness here are a few brief notes.

SVN via Terminal

First of course we need to launch the Terminal application located at /Applications/Utilities/Termimal.app.  Once the terminal is running, we need to choose a location for our files downloaded from the remote server.

Let's say we are going to use /Users/yourname/checkouts/.  First we need to navigate to Users/yourname/ and create the checkouts directory:

MyMac:~ yourname$ cd /Users/yourname/ MyMac:~ yourname$ mkdir checkouts

You should now be able to navigate to your users folder via the Finder and see the newly created checkouts folder.  Now we hop back to the terminal and move into that directory and call SVN for the first time:

MyMac:~ yourname$ cd /checkouts/ MyMac:~ yourname$ svn co svn.theremoteserver.com/wooga

Congratulations, you have just performed your first SVN command.  Anytime you interface with SVN via the terminal you begin with svn, then you tell svn what you want to do, in this case we said co and we know from earlier that this means Check Out.  So if all went well you should now have a folder inside of checkouts called wooga and inside this folder we have our files, ready and waiting for editing.

You can now edit those files with any app you wish.  Once you have saved your changes locally all you need to do is go back to the Terminal and navigate to /Users/username/checkouts/wooga and enter:

MyMac:~ yourname$ svn diff MyMac:~ yourname$ svn commit

Running diff is not required, but it is a good idea to make sure that you are aware of all the files you have changed.  The Terminal window should show you SVN adding (A), updating (U) or deleting (D) files, based on what changes you have made locally.

And that is it for the Terminal.  More information can be found at Subversion Forum.

SVN via The Finder

This is, for most of us, the most natural method of interacting with SVN on our Macs.  By downloading and installing scplugin from tigris, we can fully integrate SVN into the Finder.

After downloading and installing the plugin, there will now be a new contextual menu when you right-click/control-click in the Finder labeled Subversion.  If you open that submenu you will see all the commands you have at your disposal.

To replicate our steps above via the Finder we would simply:

1. open a new finder window
2. navigate to our user folder
3. right-click/control-click and select New Folder from the contextual menu, and name it checkouts
4. navigate to checkouts, and right-click/control-click and select Checkout from the Subversion contextual menu.
5. You will be prompted to specify the URI of the repository, enter it and make sure that the "Checkout to local path" is correct
6. click Checkout, sit back and relax.

And that is all there is to Checking out via scplugin and the Finder.  Next you would open and edit files, and then go back to the Finder to run Diff and Commit which are both found via the Subversion contextual menu.

That is it really.  If you install scplugin you will notice that files that you are interacting with will have green checkmarks on them, or blue pluses, or red exclamation points.  This is normal.  The green checkmark means that you local copy is in sync with the remote copy; the blue plus means the file has been added and is ready for Commit and the red exclamation point means that the local copy and the remote copy are out of sync, most likely due to changes you have made locally.