Version Control Software for Non-Developers

Note: Windows users read on. I’m not leaving you out today! Unless you’re running Windows 95, 98, or Me. Of course if you are then you were left behind years ago.

First, let’s define what I mean when I say “version control software”. What I’m talking about is software that keeps all of our documents for us, allows us to check them out, make changes, then check them back in. When we check a document back in it should remember the changes from one version to the next and allow us to pull out a copy of the document at any stage. That’s a very high-level explanation, but it will certainly do for our purposes today.

Second, let’s determine why you would want to do this. As I mentioned in the lead-in for this article, if you’ve ever accidentally deleted a document, made changes to the wrong document, or otherwise wished you owned a time machine this plan is for you. Of course this isn’t the best use of a time machine; buying GE stock at it’s inception would be a better use, for instance.

There are lots of different version control systems available today including CVS, Subversion, RCS, SCCS, SourceSafe, Perforce, PVCS, and more. Of course we’re only going to discuss open source packages here. CVS is the most widely used as near as I can tell, but Subversion seems to be gaining ground quickly. Subversion, or svn as it’s called it on occassion, is what we use in house and what I’ll recommend for use here. You can find them on the web at http://subversion.tigris.org/.

One of it’s biggest advantages is that the book is free, literally. As a matter of fact it can be found at http://svnbook.red-bean.com/. You can view it in html or you can download it as a pdf. The book is also published by O’Reilly in case you just have to have a bound copy. As a side note, O’Reilly is one of the finest publishers of computer books around. I’ve rarely been upset after purchasing one of their books.

So you’ve decided this all sounds good. Great, let’s get started. First we need to get a copy of Subversion that will run on your system. Simply go to Tigris’ web site here http://subversion.tigris.org/project_packages.html and get the one that matches your system. There isn’t a major OS that doesn’t have packages available. Next, install it. If you aren’t capable of installing software on your machine without my help then the rest of this article is going to be impossible, so stop now. Before going any further you need to decide where you want to have your documents stored and where you want the repository information stored. Make a note for yourself.
Now let’s initialize our repository. Windows users will have to translate the paths yourselves, see the Subversion book.

svnadmin create /path/to/repository

That was easy. Now we’ll add your documents directory to the repository.

svn import /path/to/your/documents file:///path/to/repository -m “initial import”

Ok, now we have our documents checked in to our repository. Now we want to rename the documents directory. Don’t delete it, we don’t want to be over confident. Now create a new directory with the name you wanted to use for your documents directory. Finally, we do a checkout:

svn checkout file:///path/to/repository /path/to/your/documents/

Ok, now we have a directory that is basically looks just like our documents directory did before. Seems pointless, right? Well read on.

Now here’s where the rubber meets the road. You can make changes to any documents you want, add new documents, and remove documents with impunity. Sounds too good to be true? It is, to a point. In order for all of this to be effective you need to check the documents back in to the repository. The more frequently you do, the more versions you can get back out. To check your documents in, or “commit” them in Subversion parlance, run this command from the root of your documents folder:

svn commit

And that’s it. To see what you’ve changed since the last time you committed, you can run:

svnadmin diff

Now, does this save you from having to do backups? No. If your drive fails you’ve still lost all of your documents. You MUST back up your repository to a remote and non-destructible medium of some sort just like with any other important files.

Now before you go too far to fast you need to know something. If you want to add, move, copy, or delete files from your repository you need to use some special svn commands. Namely add, move, copy. and delete. So, to create a new document simply create it how you normally would, then after you’re done go to the command line and run:

svn add /path/to/new/file

The same holds true for moving, copying, and deleting files. You have to tell Subversion what you’re doing so that it can keep track of those changes. So all this command line stuff a little daunting? There are several graphical clients to help you manage your directory. You can find a laundry list of tools at http://scm.tigris.org/.

Conclusion? Wait just a minute! You said something about sharing across machines! Correct. And for that I recommend you read chapter 6 of the book. After all, the book is free so there’s no point in reprinting it here. Suffice it to say you can set up Subversion to read from a repository over the network using it’s own protocol, svn. If the information is sensitive you can even run svn over ssh to encrypt it.

Hopefully you’ve seen how simple and effective using version control software is for developers and non-developers alike. This concludes our whirlwind tour. Thanks for joining me, and happy committing.