Source control is something thought to be geared more towards developers and those doing more traditional computer science-type programming, especially when working in a team environment. Source control is also an invaluable tool for web designers and developers alike.

Source control comes in many flavours — the two most popular and widely used systems being CVS (Concurrent Versions System) and Subversion, a successor to CVS which significantly improves on the major gripes most people have with the CVS source control system.

The problem with both is mostly from the aspect of approachability. Once you get the hang of them, it becomes natural and there will be times when you wonder how you ever survived without it, but until then, using, and more so, setting up your own source control system is a daunting task.

First steps: pick one. Your best bet is Subversion as it has been gaining in popularity and is under active development in the open-source world. Ask anyone doing serious development in Ruby on Rails for example and I’d bet 10 out of 10 times they’ll say they’re using Subversion.

If you’re a lucky developer working on Mac OS X, getting up and running with Subversion is trivial provided you have a handle on a few basic Unix commands. In this mini tutorial, I’ll walk you through installing Subversion, creating a new repository and importing a project. Ready to get started?

Step 1: Installing Subversion

We can cheat here and go the quick route using an installer package created by Martin Ott of The Coding Monkeys, the fine folks behind SubEthaEdit. Once you’ve downloaded and un-zipped the .pkg installer file, double-click the installer and run through the setup screens. Subversion will be installed into /usr/local which is where you want it since it won’t mess with anything in the core Mac OS X install.

The Subversion binaries are installed in /usr/local/bin. Of interest are svn, svnadmin and svnserve. The first two are your administrative tools for interacting with Subversion, the the svnserve binary (application) will allow you to run your own Subversion server that you can work from.

At this point you should have Subversion installed.

Step 2: Customize Your $PATH

To make working in the Terminal easier, we should tell your shell of choice (typically Bash), where to look for executable programs such as the Subversion binaries. To do this, you need to create a file in your home directory (eg. /Users/your-user-name named one of bash_login, bash_profile or bashrc.

In order for the file to be recognized by the shell as a configuration file it needs to be saved with a period (.) at the beginning of the file name. To create the file, open up your text editor (TextMate or BBEdit will do fine) and add the following:

export PATH="/usr/local/bin:/usr/local/sbin:$PATH"

When you’re done, save the file. Remember to prefix the file name with a period: .bash_profile, for example. You’ll need to open a new Terminal window for the change to be loaded. You can test that things are working by typing sv and press Tab. If the name auto-completes, you’re good to go.

Step 3: Setting Up A Repository

We’re now ready to create a new repository. This is where our files will be stored. This is not where we directly interact with and modify files though, but where data is pulled from and committed to when we make changes. If it’s not all clear, it hopefully will be shortly.

Open a new Terminal window (you can find the Terminal application in the Applications/Utilities folder on your computer). Type the following command:

sudo mkdir -p /usr/local/svn

This will create a new folder named ‘svn’ in /usr/local after you’ve entered your administrative password which you will be asked for. This will be our Subversion repository. If you’d rather use a different location, feel free to change the path. For example, an external drive or in your Home directory.

Assuming you followed the above, you’ll need to change the group ownership on the ‘svn’ directory in order to be able to write to it. To do this, type the following at a new prompt in the Terminal:

sudo chgrp -R admin /usr/local/svn

This changes the group associated with the main folder and recursively down into the folder to the admin group in Mac OS X. As long as you belong to that group, then you should be able to write to that folder.

Step 4: Create a New Project in Subversion

We’re now ready to create our first project in Subversion. This will get us our initial setup from which to work from. As an example, let’s say we’re creating a new blog for a client named “Metropolis & Co.”. We might name the project metropolis_blog. To create the new project, back in the Terminal, enter the following:

sudo svnadmin create /usr/local/svn/metropolis_blog

If all is successful, you should be returned to a new prompt in the Terminal.

Step 5: Securing Our Project

The next thing you might want to do is secure access to your project, especially if you’re working in a team environment with different people on different machines or in different places. There’s a bunch of different things you could do here and I’m going to keep it simple for now. Just the basics — controlling read/write access and adding usernames and passwords.

In order for multiple people to interact with your new Subversion repository, you need to run svnserve on the system you ran through the previous steps on. So, before we start up the server, we need to configure the access details which can be done on a per-project level. So in our case, we want to edit the settings for our ‘metropolis_blog’ project.

In the Terminal, switch to the project directory by going to:

cd /usr/local/svn/metropolis_blog

In that folder you should find a series of directories and files. Right now we’re only interested in the conf directory’s contents.

cd conf

or

cd /usr/local/svn/metropolis_blog/conf

In the conf folder you will find three files: authz, passwd and svnserve.conf. We won’t look at the authz file now, and instead start by editing the passwd file:

sudo pico svnserve.conf

You can read through the usage notes in the file, but the basics of what we want to do here is enable read-only access anonymously and make write-access require a username/password which we will specify next. To do this simply change the matching lines in the svnserve.conf file by removing the preceding hash mark (thereby uncommenting the lines).

anon-access = read  
auth-access = write  
password-db = passwd

If you wanted, you could create a new password file in a different location and point to it in the file, but in this case, we’ll just use the defaults. Save the file by pressing Control-O and then Control-X to quit the pico editor. If you have TextMate installed you could alternatively edit these files with it.

Next, let’s create two user accounts for which we’ll grant write access to the repository. In the Terminal, type:

sudo pico passwd

Using the examples already present in the passwd file, add a couple new username/password combinations. For example:

user1 = password1  
user2 = password2

These are obviously crummy account credentials. I trust you to come up with something a bit tougher to figure out. When you’re done, press Control-O and then Control-X to save and quit.

We’re now ready to start up our Subversion server and import some files into our project.

Step 6: Start the Subversion Server Daemon

Starting the background daemon process for Subversion built-in server is as simple as running:

sudo /usr/local/bin/svnserve 
--daemon --root /usr/local/svn

Here we’re telling the daemon to run as the root user on the system, run as a daemon (background process) and use our repository (the —root here indicates the root of the repository, not the root user in Mac OS X which is simply implied by executing the command with sudo).

If you check in the Activity Monitor application on Mac OS X, you should see the svnserve process listed. If so, you’re set to go to the next step.

Step 7: Importing Files into our Project

Now let’s create a fictitious project structure which we can import into our project. On your Desktop, create a new folder called import. Inside that folder create three subdirectories named trunk, branches and tags. We’ll use this as the base for our import.

Once those folders have all been created, in the Terminal, type:

cd ~/Desktop/import && sudo svn import . 
file:///usr/local/svn/metropolis_blog -m "initial checkin"

Assuming all goes well, you should see some output in the Terminal indicating that your folders were added along with a revision number. Now is where the fun starts. Now we need to test that we actually, really did commit something to Subversion.

Step 8: Sanity Check

To verify that we did in fact commit something into our repository, the best way to do a sanity check is to check it back out somewhere. So let’s do that, make a quick change and commit the change back to Subversion.

To check out your project into a working directory (often called a ‘sandbox’), do the following in the Terminal:

svn co svn://localhost/metropolis_blog ~/Desktop/my_checkout

This should checkout the contents of the project into a new folder called my_checkout on the Desktop. If it worked you should see a nice confirmation message in the Terminal and find a new folder on your Desktop named my_checkout with the previously imported folders inside. Cool, eh?

Now we want to create a new file, add it to our repository and then commit the file into the repository. You can add and remove files to your hearts content with Subversion, but until you commit the changes you don’t actually affect the repository, only your local working sandbox.

So create a new file in your favourite text editor. In this case, let’s create a file called readme.txt inside the trunk subfolder. Now back in the Terminal we’re going to add the file and then commit it to Subversion (press Return after each line).

cd ~/Desktop/my_checkout/trunk  
touch readme.txt  
svn add readme.txt  
svn commit -m "adding readme.txt file"

As usual, Subversion should provide you with some feedback indicating whether your new file was added or not. If so, you’ll see a new revision number. At this point you’ve got a nice little development environment setup for source control for your projects. And now that we’ve done our sanity check, you can safely delete the import folder you started with.

If this was helpful or if you have any comments or corrections, please feel free to leave them. I do have another small piece to add to this tutorial but which will be included separately in the next day or so.

*Updated on March 4, 2007 to add details for customizing your $PATH variable in the Terminal.