Tuesday, August 18, 2009

Subversion isn't just for coders and programmers...I know because I'm not one. I've begun to use it lately for many things, such as, backing up Nagios configurations, documents, and pretty much anything text based. I don't know why I didn't start using it sooner, but none the less, here I am. This document quickly explains how to install, configure, and use subversion locally, as well as across Apache on a network. For complete and complex configurations and installations seek the documentation provided. There is plenty of well written documentation on the subject, that far exceeds my knowlegde of the tool. This just helps get you started quickly, for those like me that just like to jump in head first into new things.

Subversion: http://subversion.tigris.org/Version Control with Subversion: http://svnbook.red-bean.com/

3. Installation

[root@lucifer ~]# yum install mod_dav_svn subversion

The first thing to do is to install the packages I mentioned above. If you don't have Apache installed already, it'll go ahead and drag that down as well.

When you install from yum, there's a longer list than the two packages above that will automatically resolve themselves. Some other things will be installed automatically. Depending on your packages, your mileage may vary.

4. Configurations

4.1. Apache

Before you delve into the deep end, you need to ensure Apache is set up first. I'm assuming this is a virgin installation, so if you already have Apache things going...be careful what you change. I'm also going to explain setting this up with basic password protection. You can easily let this out, however, if you want to allow access to the repos from everyone.

First thing is make sure you open up /etc/httpd/conf/httpd.conf and at least change the ServerName directive. If you need more help or more complex configurations, then consult the Apache docs please.

The location is what Apache will pass in the URL bar. For instance: http://yourmachine/repos points to the SVNPath that you have specified. My examples are just that, so feel free to put things where you want. Make sure you save the file when you are finished editing.

Next we have to actually create the password file that you specified in the previous step. Initially you'll use the -cm arguments. This creates the file and also encrypts the password with MD5. If you need to add users make sure you simply use the -m flag, and not the -c after the initial creation.

Go test out whether or not you can access your repository from a web browser: http://yourmachine/repos. You should get a popup box asking for a username and password. If so, type in your credentials and you should be displayed with a Revision 0:/ page. If so, that's it for setting up a repo. If you want multiple repos, check out the docs from the links provides above. This sets up one repository and shows you how to start using them. Speaking of, let's move on to just that.

5. Using Subversion

5.1. Layout Your Repo

If all went well above, you're now ready to start using the repository that you created. Subversions svn tool is the command line client that you will use to talk to the database. To see the use of the tool:

[root@lucifer ~] svn --help

The most common arguments you will most likely be using are: svn import, svn commit (ci), and svn checkout (co). With these you will initially import files into your repository with import, you'll check them out to work on them with checkout, and you'll commit the changes back into the database with commit. It's pretty simple once you see them in use a few times.

Before I continue I'd like to explain about directory structure layouts. Almost all of the documentation talks about creating a certain layout for your directories. They specifically mention about making sure you have a branches, tags, and trunk underneath the root directory structure, where trunk holds all your files. For instance:

The book explains why in a bit more detail, and I mainly don't bother using this type of layout...because I'm not doing coding and maintaining "projects" per se. I'm mainly using it to store configuration files, and text items that aren't as complex. Set things up for whatever works for you.

As an example, I'm going to just create some dummy directories and throw some files in them. This is from the actual SVN server. Play along.

Now, just to check it out across the web browser: http://yourmachine/repos. You'll get whatever you have imported showing up to peruse. Once you upload your original layout from the local SVN server, you're now free to use it remotely on another machine. As long as you are connecting to the Subversion server with the user account(s) that you created earlier. Let's give it a shot.

The nice thing about this then, is that you can delete all of the directories that you just checked out on your machine. The only reason you checked them out, was to edit them, and then send them back up the line. Web browse to your server to check out the different files.

5.5. Adding/Deleting Items

Now this is all fine and dandy, but how do you add more files to an already existing repo directory? Easy, with the add argument. Go ahead and checkout your latest and greatest, copy a file over to a directory, add, then commit the changes.

To delete items simply use delete instead of add. Commit your changes back up, and you're good to go. It's as simple as that. Go back over to your web browser again and you'll notice the revision number should say 3. You'll be able to click through the files to pick our your differences as well.

5.6. Reverting Back

Ok, this is all great but how do I revert back to an older revision...isn't this the point of Subversion? Yep, it's easy. If you're not sure as to what revision you're at...check out the log command. This is why you put a message in every commit. Short and to the point, but enough information to ring a bell that you perhaps forgot about.

You'll get a nice complete list of revision numbers along with the comments, like I mentioned above. This allows you to pick which revision you want to check back out now.

[me@mylappy ~] svn co -r 1 http://yoursvnserver/repos/mytestproj

This command will drag down revision number 1.

6. Access control lists

Usually, you don't want to give every user access to every repository. You can restrict repository access per user by using ACLs. ACLs can be enabled with the AuthzSVNAccessFile file option, which takes a file name as its parameter. For instance:

You can then create /etc/svn-acl-conf. This file consist of sections of the following form:

[reponame:repopath]user = access

Where access can be r (read), rw (read-write), or empty (no access at all). The default ACL is to give users no access to a repository. Suppose that there is a repository named framework to which you would like to give john read access, and joe read and write access. You could then add the following section:

[framework:/]john = rjoe = rw

It is also possible to create groups in a section named groups, groups are then prefixed with the 'at' sign (@) in the access control lists. For instance:

[groups]staff = joe, george

[framework:/]john = r@staff = rw

If you would like to make all repositories readable to all users, you can add a section for the root directory of every repository:

[/]* = r

7. Afterthought

This is only a very very small part of the power of what Subversion can offer you. This quick guide will get you going, and show you how to use it a bit to understand how it's working. You can do all kinds of things with the Subversion tools, so make sure you check the docs out to learn about different options that might assist you in your tasks. Also remember that the Apache installation might be overkill for your needs. You can completely use the Subversion tools locally on a machine by specifying file:///path/to/repo, instead of my examples across Apache as http://yoursvnserver/repos/whatever. From what I read, many folks use it on their local boxes just to keep their minds straight for huge projects and configurations file. Good luck