This summary gives an impression of the typical use of the svn command. In fact, svn is an important command of the programme called Subversion. Subversion is a programme for version control: it keeps track of the changes made to of (preferably text) files by different users and tries to incorporate all those changes in a central repository, usually somewhere on a server. When using text files, Subversion can diff and merge files to take into account changes made by different users to the same text file. Hence, Subversion is ideal for source code of e.g. computer programmes or LaTeX. Since svn is the most-used command (on the client side), the name svn is often used as a pars pro toto for Subversion.
Before getting started
If you’re sure you want to use svn, skip to the next section.
If you’re looking into version-control systems (VCSs) or source-control managers (SCMs), and haven’t decided on which program to use yet, then consider these alternatives for svn:
- bzr (Bazaar): can do basically anything svn can, and more. Aimed at user friendliness and ease of use. You can even use bzr on a svn repository. See Basic Bazaar for scientists for an introduction.
- git: can do much more than bzr, but has a steeper learning curve. Cons: sooo many features… Pros: sooo many features!
I used svn for a couple of years, was afraid to make the move to git because of the overwhelming load of features, and in the end used bzr as a stepping stone to make the transition from svn -> bzr -> git.
Checking out a working copy
The first action you need to take (after installing the Subversion client and getting an account from your system administrator for the Subversion server) is to check out the repository from the server to your local machine (client). The local copy of a repository is called a working copy.
svn checkout --username <user_name> svn://server.name.ext/repository_name/
This will ask for your password, and create a new directory repository_name in the directory from which you executed the command. This new directory contains the repository. You will have to do this only once, and since Subversion stores your password, this is the only time you should need it. The trailing slash in the URL may be important.
The directory repository_name usually contains three subdirectories. It is customary to store the main line of the repository in the directory repository_name/trunk/. Whenever you are in the directory repository_name or one of its subdirectories and execute the svn command, the programme ‘understands’ that the command applies to that repository. You have to be in the directory of a repository for most svn commands to work.
Default work cycle
It is important to realise that you should use the svn directory as your working directory. Copying files to a different working directory in order to edit (and compile or use) them there, and copying back when you’re satisfied will in many cases result in undoing the work of your collaborators, which they usually tend not to appreciate too much.
Before you start working on the code, alwaysupdate to make sure you start from the latest version:
and look at the screen output. If it contains one or more labels C, there is a conflict (i.e. multiple people edited the same line and svn doesn’t know how to combine them) and you should look at the files carefully before you start editing!
Edit your code. If multiple people are working on the same files at the same time, make sure you do regular commits to and updates from the server to avoid conflicts. The more frequent your exchanges with the server, the smaller the changes and the more easily they are merged. In that case, always do an update before a commit (this way Subversioncan merge changes somebody else made with your working copy):
svn update svn commit -m 'One-line comment'
(replace One-line comment with a short, descriptive comment of your changes (and use the single quotes). If you do a commit and get an ‘out-of-date’ warning, do an update first.
A conflict arises when two different people have changed the same line. In order to allow Subversion to merge code more easily, it is strongly advised to use many short lines (created by hard returns rather than wrapping by your text editor) in stead of a few long ones. This is automatically the case for computer code, but is important to keep in mind when using e.g. LaTeX. The longer lines are, the harder it will be to merge changes and the more time you will waste in manually resolving conflicts.
At the end of your working day/session, commit your code once more:
svn update svn commit -m 'One-line comment'
To summarise the work cycle:
svn update edit your code test your code svn update check svn output for conflicts svn commit -m 'One-line comment' svn update #In my case, my commit doesn't show up in the log otherwise
(For more information, see Basic work cycle in the Subversion book).
Some more svn commands
To check the status of your working copy versus the server, type:
svn status -uv
The most common symbols that show changes (either for status, or when doing updates or commits) are:
- ?: file not in version control (suppress these with svn status -quv)
- M: modified
- A: added
- D: deleted
- C: conflict
- *: newer version exists on server
(see the svn book for more symbols).
To add a file to the repository or delete a file from it, use:
svn add <file name> svn del <file name>
The fact that files need to be added in order to be under version control, rather than taking any file in the directory of the working copy, is very useful. If a file text.tex is under version control, you can change it, LaTeX it until it looks good, and the svn commit command will only commit text.tex, not text.aux, text.log, etc.
To check the log of past changes (the one-line comments given to commit with -m):
To see the changes between your working copy and the version you last updated, either for one file or for all files under version control:
svn diff <file name> svn diff
To get help on the options of a specific command, e.g. svn log, type:
svn help log