svnserve the people

If you consider yourself a programmer, especially one that works on a number of codes for a single project or on multiple projects which you update from time to time, then you must definitely know and use Subversion (svn) or something like it. Subversion is well-known in the open source community and is used on many open source projects such as: Apache Software Foundation, KDE, GNOME, Free Pascal, GCC, Python, Ruby, and Samba to name a few. That being said, what in the world are you waiting for? Go on using svn and get going/coding.

This post is about how to quickly use svn to get copies of codes or files from any svn repository on the web or even on your own LAN. The post also tackles how to quickly set up your own svn server or repository so you can start accessing your codes in an organized manner anywhere, as long as you have network connection. This post is by no means exhaustive and is only meant for quick do-it-yourself svn server/client setup. Resources at the end of this post are highly recommended for further or in-depth reading.

As a client

Client for svn means you are just getting files or uploading them from an already established svn repository/server. First, the most helpful svn command that one needs to learn is this line:

$svn help

which should give you this output or something very close to it:

usage: svn <subcommand> [options] [args]
Subversion command-line client, version 1.4.6.
Type ‘svn help <subcommand>’ for help on a specific subcommand.
Type ‘svn –version’ to see the program version and RA modules
or ‘svn –version –quiet’ to see just the version number.

Most subcommands take file and/or directory arguments, recursing
on the directories. If no arguments are supplied to such a
command, it recurses on the current directory (inclusive) by default.

Available subcommands:
add
blame (praise, annotate, ann)
cat
checkout (co)
cleanup
commit (ci)
copy (cp)
delete (del, remove, rm)
diff (di)
export
help (?, h)
import
info
list (ls)
lock
log
merge
mkdir
move (mv, rename, ren)
propdel (pdel, pd)
propedit (pedit, pe)
propget (pget, pg)
proplist (plist, pl)
propset (pset, ps)
resolved
revert
status (stat, st)
switch (sw)
unlock
update (up)

Subversion is a tool for version control.
For additional information, see http://subversion.tigris.org/

Now, in order to get a copy of the code (or part of the code if you wish) in an existing svn repository (e.g. the svn for GCC) you simply enter the following (assuming of course you have svn installed, which shouldn’t be a problem in most operating systems, especially Linux distributions, nowadays):

$svn checkout svn://gcc.gnu.org/svn/gcc/trunk gcc

The previous command gets the code from the GCC trunk (the main branch/working version of a program/project) and copies it to your local storage space (hard disk etc.) under the directory gcc. From the output of svn help shown above, the option checkout or co can be used interchangeably, among others. Now if you have a working copy from an svn repository and there are updates from the repository, all you have to do to update your local copy is to go into the directory where you saved your svn copy of the codes from the repository (in this case, gcc) and enter:

$svn update

And for each updated item/code from the repository (repo) a line will start with a character reporting the action taken. These characters have the following meaning:

A – Added
D – Deleted
U – Updated
C – Conflict
G – Merged

Also, to get more information on a specific svn option such as update or checkout, you can use

$svn help command

where you substitute command for the command you want more info to. If you have your own repo or if you’re say a programmer and you have write access to an svn repo so you can upload your updated part of the code, you can simply go to the directory of your svn copy and enter:

$cp <code/s to copy> <directory where my svn copy is>

then to add the code/s to the version control management of svn:

$svn add <code/s copied>

and finally,

$svn commit -m “your message here for this specific commit”

Which commits or “uploads” your code to the svn repo, so that your changes will be reflected in the svn repo and others will get their copies of the changes you’ve made. You must have a commit message in between the two “ marks, since it’s required. You can also omit the -m and the message, but svn will open for you your default text editor so you can enter your commit message there. I personally prefer the second one since I can view the files I edited before committing them. Other useful svn commands where you can get useful information (and are worth looking into) include status, info, diff, and list, which can also be used if you are handling the svn server.

To view the svn logs you or others committed, just enter the command

$svn log

In case you make a mistake after committing your log, and you want to edit that log, the command

$svn propedit svn:log –revprop -rX

will do it for you. X in this case is the revision/log number that you want to edit. However, before a client can go on changing/editing logs, the svn server/administrator should allow the revision change hook (specifically the pre-revprop-change). This will be discussed in the server section below.

Lastly, to change your system’s default svn text editor (which is usually vi or emacs), enter the following:

export SVN_EDITOR=/path/to/preferred/editor

and then change the path accordingly.

As a server

To quickly setup an svn server for LAN/Internet access, enter the following:

$svnadmin create myrepos

And change myrepos to your desired project directory name. Next, we create the typical svn directory layout (typical since there’s no rule from stopping you to change your directory layout, it’s just that the layout I’ll be mentioning is the usual layout convention widely used by developers):

$svn mkdir file:///home/f/temp/myrepos/trunk \

file:///home/f/temp/myrepos/branch \

file:///home/f/temp/myrepos/tags \

-m “initial layout of project codes”

(/home/f/temp/myrepos is the absolute path of my svn repo in this example) Where the trunk directory holds the main branch/version of your code/project, the branch directory holds the codes of your project wherein you considered altering a large part of it, or perhaps an extra/spin-off project from your main project/trunk. The tags directory usually holds the “snapshots” or milestones of your code/project in certain parts or history of its development, such as stable releases/versions, etc.

To check what you just did or to check any part of your svn repo, use:

$svn list file://URL

where you change URL to an absolute path in your sytem, such as /home/f/temp/myrepos/. The previous command gives the following output:

branch/
tags/
trunk/

If I have a directory named project_codes, with files

$ ls
index.php lib.h main.c

To add these codes to my svn repo under the trunk directory, and thus under svn’s version control management, I can use:

$ svn import ../project_codes/ file:///home/f/temp/myrepos/trunk \
-m “importing my project codes to svn trunk repo”

which outputs:

Adding ../project_codes/main.c
Adding ../project_codes/lib.h
Adding ../project_codes/index.php

Committed revision 2.

And to check, use list again:

$ svn list file:///home/f/temp/myrepos/trunk
index.php
lib.h
main.c

as usual, you can use the commands shown in svn help to administer your svn repo, never forgetting the syntax for the svn repo directory (svn command fiile://URL, where URL is an absolute path).

Lastly, there are 3 ways to serve your svn repo onto a network or to the Internet, but the ones I’ll be mentioning here are the easiest ones to setup, and most probably the ones in widest usage, and aren’t the least bit insecure (security-wise). But first, enter your svn repo directory, then into the conf directory to edit the file svnserve.conf. Make sure that the following lines are uncommented (without a ‘#’ at the beginning of the line):

anon-access = read
password-db = passwd

Where anon-access tells svn to let anonymous svn clients of your repo to be able to read only the files, not write over them (other valid values for this are write, and none). When you want your users to enter passwords before gaining access to your repo, password-db gets the users and their corresponding passwords from the file passwd under the conf directory. The passwd file is worth taking a look and has a very easy user management syntax. Under the [users] heading in the file passwd, it’s simply:

username = password

svnserve

svnserve (svnserve –help for some help or man svnserve for more info) is a lightweight server that allows svn clients to connect to your repo. You can use svnserve as a stand-alone background server or daemon process using:

$svnserve -d -r path

wherein path is a path to your root svn repo, in my case it’s /home/f/temp/myrepos.

svn over ssh

To include encryption (and security) into your svn repo transfers, you can tunnel svn access commands over ssh. This technique doesn’t actually need an svnserve running on the machine which houses the svn repo you want to access. The reason is that ssh first connects you to svn repo machine, then executes the svnserve command afterwords, so the process essentially logs you in via ssh and then runs svn commands for you (which of course allows you to do a lot more than just connect to the svn repo). To tunnel svn over ssh:

$svn checkout svn+ssh://user@host/path

wherein user is your user login to that svn repo machine, host is the hostname or IP address of the svn repo, and path is the absolute path to your svn repo on that host/machine. Once you manage to connect, you will be prompted with your password for that host/machine, not the password in the passwd file of the svn repo machine. Your succeeding transactions will require you to enter your password, with the benefit that your transfers to and from the svn repo machine are now encrypted.

Lastly, to allow editing of logs, in the directory /myrepository/hooks/, remove the file extension of the file/s with a .tmpl extension in order enable that hook, then make that file executable. In the svn client portion above, once the hook pre-revprop-change has been enabled, svn users can now edit their logs in case they made mistakes after committing, for example.

Comments and suggestions are highly welcome, as long as they’re in a calm and ruly way (^)__(^).

References and further reading:

• The O’Reilly book on subversion, free for download in various formats
• D. Berlin, G. Rooney, Practical Subversion, 2nd ed., Apress, 2006
• IBM developer works page about subversion, introducing a graphical plug-in for the Eclipse IDE
• more info on hooks, specifically the pre-revprop-change hook

Tags: subversion, svn, version control