2008-03-30

Sysadmin Sunday: Subversion

Sorry for the recent lack of Sysadmin Sunday posts. I don't always have good Sysadmin content thought up. Sometimes I do, but I don't have time to actually set up an environment to demonstrate it. Sometimes I don't even have time to get around to writing much of anything.

So, we're back this week with a tutorial on setting up Subversion, a revision control system that, in my opinion, is much better and user-friendly than other revision control systems (such as CVS). You'll see me (and many others) casually use "SVN" when referencing Subversion. You can use subversion to synchronize directories (folders) across different workstations, to collaborate changes on large documentation or programming projects, or to simply have a revision control and change rollback system for your files. It works with binary and text, but can take up a lot of hard drive space on the server for large or frequently-changing data sets.

Installation
Initially installing Subversion varies on the platform and package management system available. I am installing subversion on Ubuntu Gutsy Gibbon Server Edition. Here, it's as simple as:
$ sudo apt-get install subversion

On FreeBSD 6.3, I got it installed using pkg_add as well, with no problems.
$ sudo pkg_add -r subversion

Subversion packages are available for many platforms, but if you wish to build it from source, the documentation is quite good.

HiR Reading Room
Of particular note is the O'Reilly and Associates book: Version Control with Subversion. It is free and open source, so it's also available to read in its entirety on the web. I personally liked it enough that I bought the paperback book, as I dealt with subversion on a daily basis at my last full-time job. If you'll be doing a lot with Subversion, this is a great book to have around as a reference guide.

Please note that I'm not dealing with any encryption whatsoever, so you should probably make sure that your svn server isn't accessible from the Internet. Being behind a private firewall or cheap router will work for testing this at home. Read the book for information on securing SVN with ssh or using better authentication options. There's even a web-based SVN Server, which allows your users to browse the repository with a browser while using all of the flexibility and authentication modules at Apache web server's disposal. All of that and plenty more is covered in this book.

Starting svnserve
First, make a directory to keep the repositories in. A repository is simply a directory on the SVN server where data is stored. I chose /var/svn/repositories.
$ sudo mkdir -p /var/svn/repositories

Then, we need to start our svnserve daemon. As I mentioned before, there are several ways to run SVN. Just starting a vanilla svnserve daemon is the easiest way but not always the best way. For the purposes of this demonstration, I will keep it simple.

Place "svnserve -d -r /var/svn/repositories" (or whatever repository root you chose) in the startup scripts, usually in /etc/rc.local. Either reboot, or run "[sudo] svnserve -d -r /var/svn/repositories" from the command line to start it. This restricts svn to exporting only the contents of /var/svn/repositories.

Your first repository
Let's set up our first repository. On the SVN Server, run the following. You may choose whatever you wish for the repository name, but it has to be under the repository root you defined when you started svnserve.
$ sudo svnadmin create /var/svn/repositories/hir-test/

You should create a username and a password by editing the "svnserve" and "passwd" files in the "conf" directory under the repository you just created. Keep in mind that passwords are all in plaintext for this example. It's not really the best way to do things, but it is the simplest.

$ vi /var/svn/repositories/hir-test/conf/svnserve.conf
un-comment the following lines:
anon-access = read
auth-access = write
password-db = passwd


$ vi /var/svn/repositories/hir-test/conf/passwd
Add a line like the following to the end of the file to define your username and password:
axon = setecastronomy

Now, go to a client computer (or simply access it locally but through the svn:// url scheme) and use SVN to check out the repository:
[axon@floaty-fbsd ~]$ svn checkout svn://axon@192.168.0.108/hir-test/
[axon@floaty-fbsd ~]$ cd hir-test
[axon@floaty-fbsd ~/hir-test]$ ls -la

total 8
drwxr-xr-x 3 axon axon 512 Mar 29 21:37 .
drwxr-xr-x 20 axon axon 2560 Mar 29 21:38 ..
drwxr-xr-x 6 axon axon 512 Mar 29 21:37 .svn

Copy a file into the repository, or make a new file. Your choice. Then use "svn stat" to see the status of the files in the directory.
[axon@floaty-fbsd ~/hir-test]$ cp ~/internet-resume.doc .
[axon@floaty-fbsd ~/hir-test]$ svn stat
? internet-resume.doc

SVN doesn't recognize the file, hence the "?" before the file name. We must first add the file with "svn add"
[axon@floaty-fbsd ~/hir-test]$ svn add internet-resume.doc
A (bin) internet-resume.doc
[axon@floaty-fbsd ~/hir-test]$ svn stat
A internet-resume.doc

At this point, SVN is aware of the file, but it still hasn't uploaded it to the svn server. If we go to another machine and check out the repository, it will still be empty. (sorry, I used the DNS name in this example but it's the same server as 192.168.0.108)
axon@hosting:~$ svn checkout svn://axon@lampdev.labs.h-i-r.net/hir-test
Checked out revision 0.
axon@hosting:~$ cd hir-test/
axon@hosting:~/hir-test$ ls -la
total 12
drwxr-xr-x 3 axon axon 4096 2008-03-29 16:52 .
drwxr-xr-x 5 axon axon 4096 2008-03-29 16:52 ..
drwxr-xr-x 6 axon axon 4096 2008-03-29 16:52 .svn
Back on the client machine where we added the file, though, use "svn commit" to update the central repository on the SVN server. You should always commit with a message saying what changes were made. use --message for that. It should then prompt for your password.

[axon@floaty-fbsd ~/hir-test]$ svn commit --message "added my resume"
Authentication realm: 2c608312-9cd3-44f0-b88e-356728a5cc35
Password for 'axon': setecastronomy (not shown on screen)
Adding (bin) internet-resume.doc
Transmitting file data .
Committed revision 1.

Now, whenever you check out the repository elsewhere, the files will be in sync. Use svn update to refresh your local repository to the latest version:
axon@hosting:~/hir-test$ svn update
A internet-resume.doc
Updated to revision 1.
axon@hosting:~/hir-test$ ls
internet-resume.doc

When you delete, copy or move files within a local copy of the repository, it's best (practically mandatory) to use svn delete (svn rm), svn copy (svn cp), and svn move (svn mv) for these tasks, respectively.

So far, the commands we've covered the following for client machines. This should be enough to get you up and running.
svn checkout svn://[user@]host/repo-name - Checks out a local copy of the repository
svn update - Refreshes the local repository
svn add - Adds version control to new files in the local copy of the repository
svn commit --message "test message" - Updates the central repository
svn delete
filename - remove a file from the local repository
svn rm filename - same as above
svn copy filename1 filename2 - make a copy of a file within the repo.
svn cp filename1 filename2 - same as above
svn move filename1 filename2 - move a file from one place to another in the repo.
svn mv filename1 filename2 - same as above

There is also a windows shell extension available, called TortoiseSVN. This puts a TortoiseSVN menu in the list when you right-click while browsing files on Windows. From here, you can check out, update, add, commit and manipulate repositories right from within Windows.

blog comments powered by Disqus