Regular Backups!

If you value your peace of mind, you will have already bought a few external hard drives, and backed up your computer on a regular(ish) basis. If you haven’t, and you own a mac, go to Shirt Pocket Software and download Super Duper, I can wait.

Setting Up an SVN Repository

Ok, now that’s out of the way, here are the indicators that you need to set up your own version control system…

• You work on any information that is important to you.
• You work on multiple projects on multiple computers, and it can be hard to keep everything straight.
• You work on software, or web pages, or documents where it would be beneficial to be able to recover to older versions.
• You’d like to track (exactly) what you did (with diffs), and when you did it.

If any of these sound like you, then you probably already realize that you could benefit from a version control system. Here’s why it can be much easier than you think:

• Mac OS X Leopard comes with a version control system called Subversion already installed! (Even if you didn’t install developer tools.)
• Subversion, or svn for short, is super easy to set up.
• Lots of common programs, such as NetBeans and TextMate, already support Subversion directly.
• Subversion can be used easily from the command line.
• As with most Unix tools, subversion works great over the network, including ssh, and has Windows clients too, like TortoiseSVN.
• Subversion is Open Source software and can be built from sources. Barring hardware and software failures, you will never lose access to code, data and information that you entrust to Subversion.

With all those reasons to install version control, you should be persuaded! If you aren’t, please post in the comments and let me know why. Seriously.

And without further, prevarication, prognostication or procrastination, here are the steps you need to set up a basic Subversion repository, and check in your first few folders:

Decide where you want your repository.
The repository stores everything that you check-in, and tracks it by version. You could put the repository in your home folder, or on an external drive, but for simplicity, I’ll assume you have admin rights and we’ll put in in ‘/’.

The command to create your repository is:

svnadmin create /svnrepo

where ‘svnrepo’ is whatever name you want. I wanted something easy to remember, and quick to type.

Edit the configuration file and password file.
The default setup is to have read access for guest or anonymous, and write access for the logged-in user.

Edit the following lines in /svnrepo/conf/svnserve.conf to fix the access permissions.

anon-access = none
auth-access = write

Now you have to manually add passwords to the file /svnrepo/conf/passwd. Add lines like the examples,

yourname = yourpassword

and save the file. ESC :wq if you are in vi.

Setup an editor for Subversion.
Before you can interact with Subversion, you must setup an editor for Subversion to use to allow you to input import and check-in comments. Add the following command to your ~/.profile:

export SVN_EDITOR=vi

Of course, you could pick any editor that you’re comfortable with!

Import a Project.
Now you are ready to import your first folder into Subversion! As an example, you might want to import your Documents folder, or your Sites folder. In this example, I’ll import my Sites folder, on the same machine as the svn repository, assuming my Subversion repository is at /svnrepo.

svn import Sites file:///svnrepo/Sites

Subversion will bring up your editor. Type a line that describes the import. Since we are local, the Sites folder and contents will be imported to your repository. Note that the URL in the above command starts with file://.

Start the Subversion server.
We’ll start a server to allow you to access the repository across your network. Type the following command:

svnserve -d

This starts the server. Now you will be able to do a ‘check-out’ of the files in your server to any other machine on your network! Let’s do another import first, but across the network. Type the following (but replace my folder with your folder, my username with your svn username, my ip with your ip, my repository with your repository…):

svn import PDFs svn://jonathan@192.168.0.3/svnrepo/PDFs

You should be able to understand the command now. svn import is the main command. PDFs is the folder we want to import to the repository. svn://jonathan@192.168.0.3/svnrepo/PDFs is the (take a deep breath) file protocol, user name, ip address, repository base, repository folder (phew!) that we want the files to be placed under.

After giving a check-in comment, and your password, the PDFs folder, or whatever you specified will be imported to your server.

Getting a folder listing from Subversion.
It would be cruel to leave you without a means of at least getting a file listing. Here’s the ‘ls’ of Subversion:

svn ls file:///svnrepo
svn ls file:///svnrepo/Path

Checking out files from Subversion
To get files out of Subversion, and copy them under the folder ‘WorkArea’, it’s easy:

cd ~/WorkArea
svn co file:///svnrepo/PDFs PDFs

Specifying the folder as the last part of the command makes Subversion create that folder if it doesn’t already exist. If you only want the files copied into the current folder, replace PDFs, in this example, with ‘.’.

Even if you just imported a folder to Subversion, and you want to track some changes that you are about to make, you must check-out the folder so that Subversion can create some files that allow the files to be checked back in correctly when you are done.

Updating the files in the repository after changes
Once you have made some changes, it’s easy to push the changes back to Subversion. Don’t worry! Any changes you made can be rolled back, and you can recover older versions at any time. Save your work! Here’s how:

Go to the parent of the folder that you checked-out, and type:

svn commit PDFs

Subversion will display an editor and wait for a check-in comment. Describe your changes. When you quit the editor, your changes will copied into the Subversion repository.

You should practice all these commands until you are comfortable with them.

Well, that’s it for now! Take it easy and post if you’d like me to do more on this topic, or if you have other feedback. Good luck with Subversion.