Essentials of Using Subversion

You will need to know a few basic commands to work with Subversion. This document does not cover Subversion entirely. More in-depth discussion about Subversion and its capabilities can be found at the following locations:

http://www.abbeyworkshop.com/howto/misc/svn01/

http://svnbook.red-bean.com/

svn checkout

This is the first command you'll need to know. This tells Subversion to check out the repository at a given location. Below is an example of the how this command is used:

svn checkout http://linux.aspbooks.org/svn/300/working ./

This command will checkout the repository of all files located on the ASPCS server for volume number 300 to the current working directory on the local computer. For example, if the directory I was in when I ran this command was /home/editors/asp300 then the repository files would be placed in /home/editors/asp300. Once you have checked out the files from the repository, you are now ready to make necessary changes to the manuscript.

svn update

This command is run from within the directory that the manuscript was checked out to. From our example shown in svn checkout, the directory would be /home/editors/asp300. This command contacts the repository of the manuscript files located on the ASPCS server and checks for any updates that have been made to the repository and updates your local copy to match. An example of its use follows:

svn update

This command should be run periodically (perhaps daily) to ensure your working copy is current. This command will not send your changes to the repository, nor will it erase the changes you've made to your local copy. The svn update command outputs information about what was done to bring your local copy up to date. The output is slightly coded. For example, if a file in the repository of the manuscript has changed the output would be something like this:

U aspvolume.tex

The U means that the file was updated. Other possible notifications are:

A added
D deleted
U updated
C conflict
G merged

It is important to watch for the last two notifications. The C indicates that the file listed next to the C has a conflict. A conflict happens when a change has been made on your local copy and the repository in the same location of that file. These conflicts need to be resolved before proceeding with the editing of the manuscript. A discussion on how to resolve a conflict can be found at http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.tour.cycle.resolve.

The last notification, G, should be noted as a possible (although not likely) problem file. A merged file results when your local working copy differs from the file in the repository, but the differences were found in different locations of the file, so Subversion merged the two copies.

svn commit

Once a few changes have been made, update the Subversion repository of the book so that others working on the manuscript can have your changes as well. This is done quite simply with svn commit. The command should be run, like all others, from the local directory that contains the manuscript files. Below is an example of its execution:

svn commit -m "Fixed spelling in article.tex"

The first two words (“svn commit”) of this example should be relatively clear. We are telling Subversion to commit the changes made in the local copy to the repository. The next two parts require a little explaining. When a commit is made to the repository, it is necessary to leave a message describing the changes made since the last commit. This is to help others working on the manuscript to know what work has been done on it. The last two parts of the above example show how to leave this message.

Additional Reading

While these commands are the necessary commands to know, there are many others that one might find useful. If you type svn help, it will give information about the different commands available and how to use them. The websites listed above are also great resources on Subversion.