A brief introducton to subversion

Preface

The main idea of subversion is that there is a central server which manages the repository containing all files. In order to work with those files you have to get a copy of them (this will be your working copy). In contrast to e.g. Dropbox subversion keeps track of older versions of your files and is designed for a concurrent work flow where multiple people work with the same files in parallel. Every version of the whole directory known to subversion is called a revision and has an associated revision number.

Command line and GUI-clients

The following describes the command line client. There are also gui-clients where you can click instead of typing. However the commands will look the same and it's good to have some idea about their meaning.

Getting your working copy

To get a copy you need to do a checkout from the server using the address of the repository.

svn checkout [repo] [name]    (short version: svn co ...)

After asking for your credentials (username+password) this will place a working copy under the given [name]. This copy and your local changes will never be updated/uploaded/synchronized to the server automatically.

Staying up-to-date

Since others may work on the same stuff and send their versions to the server it is important to keep your copy up-to-date using

svn update      (short version: svn up)

This will get the most recent version from the server and update your working copy accordingly. Since this will only update the current directory prefer to do this in the main directory of your working copy. If you have local changes subversion will try to merge them with the version from the server. This will work if your changes and those of others are in different files or different places of the same file. If the latter is not the case you will have a conflict. Then subversion will ask what to do and the best answer will be to postpone the resolution (more on this below).

Publishing your work

If you've done some changes that you'd like to publish to the server for your coworkers you can do this using

svn commit [-m"message"] [file1 file2 ...]  (short version: svn ci ...)

Omitting the file names will send all modified files to the server. If subversion finds that your copy is not up-to-date it will ask you to update before committing. So there will never be conflicts on the server. If you successfully committed your changes the server will generate a new revision containing your version as the most recent one.

The message should briefly describe what your change was about, e.g. "Add theorem on bla..." or "Make all text pink since I like this more". Omitting the message will open an editor for you to enter it. If you find your self in the seemingly nerdy VI-editor you may exit it using :q! and retry giving the message on the command line.

Adding new files

If you added new files they will not be tracked by subversion automatically. You have to manually ask for this using 

svn add [file1 file2 ...]

This will register them and allow to commit them afterwards.

Resolving conflicts

If subversion tells you that there's a conflict when trying to update it will ask what to do. It this case it's the best to answer that the resolution should be postponed. Then subversion will put both versions of the conflicting region (yours and the one from the server) in the corresponding file of your working copy marked by

<<<<<<< .mine
+Your version of the text here.
+=======
+Servers version of the text here.
+>>>>>>> .r42

Here r42 will be the revision number of the most recent version from the server.

Furthermore the file is internally marked as conflicting which prohibits committing it. Now its up to you to manually merge the changes and remove the markers. To support you in doing so, subversion will also create new files named foo.mine foo.r42 containing your and the servers version of the file foo. If you successfully resolved the conflict you have to call

svn resolve --accept working [file]

This will remove the conflict marker, remove the foo.mine and foo.rXXX files, and mark the file as locally modified. Then you can commit the merged version as usual.

Good practice

Here are some rules of thumb that help to reduce the probability of conflicts or other problems considerably:

  1. For a file foo tracked by subversion never ever do the following (unless there is a really good reason):

    cp foo /USBSTICK/foo       # copy file somewhere else
edit /USBSTICK/foo         # edit file somewhere else
svn update                 # update working copy
cp /USBSTICK/foo foo       # copy back to working copy: really bad!

    This is the root of all evil and will almost surely destroy someones changes. Side note: Not knowing how else to resolve a conflict is not a good reason.

  2. Update often (at least before editing a file).
  3. Follow rule 1 and 2
  4. Commit often.
  5. Use helpful commit messages instead of "Update", "My changes", "New version",...

Why does XYZ not work?

If something does not work as expected the status information will often help to find the problem:

svn status    (short version: svn stat)

This will give you a list of files and indicate the status per file using a letter. The most common are

You can also do

svn status -u

This will also ask the server for new versions and put a "*" in front of all files that have been modified on the server and would be updated on svn up. This will not do the update or change any file.

Getting more information

If you need some more help on a single command you can always ask subversion for it using

svn help [command]

This will also tell you more on possible options. If you want to dive deeper into version management using subversion there is the subversion book which is freely available online as html and pdf.