How to use Subversion

This is a guide detailing the use of Subversion (SVN) in COMP 520. It contains critical course-specific information as well as instructions that are more generally useful.

1. What is SVN?

Subversion is a version control system. It allows users to keep track of changes made to any type of electronic data, which are typically source code, web pages or design documents. It does this with the help of a repository, an SVN server, and an SVN client.

Reasons to use SVN:

Concurrent development: developers can work concurrently. Your code cannot be overwriten silently when your colleague tries to add his or her code to the same file. Furthermore, your changes are committed atomically, which means that if you try to commit changes to two different files A and B to the repository at the same time as another project member, only one of you will succeed and you will not end up with a situation where one person commits A and the other commits B. As far as this course is concerned, SVN stops you from having to email files around.
Easy distribution of updates: we provide you with access to the course website which contains all public course material, and all you have to do to follow along is svn up and svn log. At the same time, since all class members share the same repository, we can also follow the progress of individual students and project groups. Finally, if you want to work on files both at home and at school this makes managing them extremely easy.
Version control: the system creates a new revision every time you commit files, which means you can always roll back safely. You can also request a diff of what changed in a particular revision, or a range of revisions. You can also see a log of who changed what, as well as who changed which individual lines in a file.
Other reasons: See the official documention, Version Control with Subversion. You must read chapters 1 and 2 for this course.

2. Getting Started

In order for us to provide you with access to the class repository, you must send us a DSA ssh public key. This is one half of a public/private key pair that you create and it allows for secure remote repository access without password authentication. If you already have an ssh key pair you can skip this next step.

      $ ssh-keygen -t dsa
      Generating public/private dsa key pair.
      Enter file in which to save the key (/home/users/chris/.ssh/id_dsa): 
      Enter passphrase (empty for no passphrase): 
      Enter same passphrase again: 
      Your identification has been saved in /home/users/chris/.ssh/id_dsa.
      Your public key has been saved in /home/users/chris/.ssh/id_dsa.pub.
      The key fingerprint is:
      ab:3c:ce:d3:61:1e:37:75:02:f9:9e:9f:ba:d9:b6:58 chris@localhost

Hit enter at all of the prompts. If you already have an ssh key pair and want to use a different one for this course then you should choose a different location to save the file. In that case, you can set the environment variable SVN_SSH to ssh -i /path/to/your/private/key/id_dsa. If you enter a password, you will get annoyed at having to authenticate for each repository access and will end up wanting to use the ssh-agent tool.

In the instructions that follow, we will use `whoami` for your CS username, which if entered on a school machine will actually expand to that name in place. Of course, you can just type your actual username instead.

After you have your key pair, create a copy of your public key with your CS username in place of id_dsa:

      $ cp .ssh/id_dsa.pub `whoami`.pub

and send this file as an attachment to your TA. They will add it to the .ssh/authorized_keys file for the course account and you will then have repository access.

3. Basic Operations

This section surveys the fundamental operations that you will need for day-to-day use of SVN.

3.1 Check Out

The first thing you should do is to check out the files from the remote class repository to your local working copy:

 
      $ mkdir cs520
      $ cd cs520
      $ svn co svn+ssh://cs520@svn.cs.mcgill.ca/2012/students/`whoami` `whoami`

This creates a directory `whoami` which is identical to your CS username as a subdirectory of cs520. It is your personal student repository, and you will use it to check in all of your individual assignments. You can rename it to whatever you like, Subversion does not care. Next, you should check out the course website:

      $ svn co svn+ssh://cs520@svn.cs.mcgill.ca/2012/public_html public_html

This directory contains all of the course information and all of the source code and binaries that you need. Again, you can rename it to whatever you like. Finally, after we assign group numbers then you will have access to a folder shared between all members of your group. With your group number in place of X:

      $ svn co svn+ssh://cs520@svn.cs.mcgill.ca/2012/groups/group-X group-X

will create that group directory for you. You will use this to check in all group assignments and your course project.

After checking out, you can add, modify or delete files in the local working copy, and nothing will be changed in the repository or visible to anybody else until you commit or check in.

3.2 Update

Every time you start working, it is a good idea to make sure your local working copies contain the latest version. This requires the svn update or svn up command:

      $ cd cs520
      $ cd `whoami`
      $ svn up
      $ cd ../public_html
      $ svn up
      $ cd ../group-X
      $ svn up

Of course, you can also just do:

      $ cd cs520
      $ svn up `whoami` public_html group-X

This command recursively updates all files and sub-directories in all working copies. If you encounter a conflict as indicated by C, you should refer to the Subversion documentation for details on how to resolve it.

3.3 Diff

After you update and begin modifying files, you will often want to check the difference between your version and the repository version:

      $ svn diff

This provides a unified diff between your version and the latest repository version on stdout, using exactly the same format as diff -u. You can also use

svn
      diff

to look at the changes between two specific revisions. For instance:

      $ svn diff -r2:3

will show you what changed in the repository between revisions 2 and 3. Finally, although svn diff operates on the current directory . by default, you can also specify a particular file, directory, or some local or remote URI.

It is a very good idea to run svn diff before committing your changes.

3.4 Commit

Once finished your local work, your changes will not appear in the repository until you commit them or check them in:

      
      $ svn ci

Here, svn ci is an alias for

svn
      commit

. The svn binary will attempt to open an editor for you to leave a log message, and you can control which editor is opened through use of the EDITOR environment variable. For example, on my system:

      export EDITOR='emacs -nw'

means that svn will open the command line interface to Emacs in the current terminal. You should always leave a meaningful log message. For example, if we were to check in changes to the current document at this very moment we might write:

      * Expand on SVN instructions.
      --This line, and those below, will be ignored--

      M    howtosvn.html

For each individual thing that changed in your commit, create a new bullet point preceded by "* ". This makes it much easier for you, your collaborators, and your instructor and TA to follow along. If you do not save the file, svn will prompt you to

a)bort, c)ontinue,
      e)dit

. This lets you back out of a commit if you realize you are missing something. As an alternative to editing a file, you can also specify a log message on the command line:

      $ svn ci -m "* Expand on SVN instructions."

However, given that opening an editor is both fast and much safer in that it provides you with a list of modifications to review, it is best to leave this option for non-interactive scripted use.

If you want to check in individual files or directories rather than the current working copy and all files and directories it contains, simply pass them to svn ci.

3.5 Add

The following command:

      
      $ svn add <file>

adds new files or directories to your working copy. They will not appear in the repository until you run

svn
      ci

. Note that you can disable the recursion when adding directories with the -N flag.

3.6. Copy/Move/Delete

These three commands work similarly to the Unix commands cp, mv, and rm.

3.6.1 svn cp

      $ svn cp <src> <dest>

svn cp will also add the destination file or directory to the working copy. The advantage of this command is that it maintains version history from before the copy, and that it requires almost no extra storage space in the repository. For example, assume there is a directory called joos/a- that is a subdirectory of the public_html directory for this course that contains some source code you wish to modify for an assignment, and that the instructor has asked you to place your modified source code in group-X/joos/scanparse. In that case, you need simply enter:

      $ mkdir group-X/joos                                # make sure parent dir exists
      $ svn add group-X/joos                              # add empty parent directory
      $ svn ci group-X/                                   # commit empty parent directory
      $ svn cp public_html/joos/a- group-X/joos/scanparse # create copy of source code
      $ svn ci                                            # check in copy of source code

In fact, svn cp is really the mechanism for creating branches with SVN.

If we want to see what you have changed, we need simply ask svn diff for all changes between your initial svn cp command and your current state.

3.6.2 svn mv

      $ svn mv <src> <dest>

svn mv can either be used to rename files and directories, or to move files or directories to different directories while keeping the same name. In doing so, it maintains version history.

3.6.3 svn rm

      $ svn rm <file>

svn rm deletes the file or directory from the working copy, as you might expect.

Important: Like svn add, these three commands just tell SVN that you want to copy/move/delete files, and you have to run svn ci afterwards to commit your change. It is a good habit to commit immediately after you add/copy/move/delete files.

3.7 Retrieve Log

If you want to look at the repository history, Subversion provides a detailed log upon request:

      $ svn log | less

If you want to see full paths that are changed, pass the -v option:

      $ svn log -v | less

You can also specify individual files if you are not interested in the entire log for the current directory.

4. Less frequently used commands

Of course, there are actually many other commands, several of which are quite useful, including svn status, svn revert, svn cleanup,

svn
      merge

, and svn resolved. When things go wrong, and they will go wrong, these commands are there to help you out. In fact, there is actually a built-in command to teach you about them:

      $ svn help
      usage: svn <subcommand> [options] [args]
      Subversion command-line client, version 1.4.3.
      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/

If anything is confusing, then again, the Subversion documention is excellent. We are also happy to help you if you send us a precise and accurate description of your problem or if you come and see us during our office hours.

5. Recommend Editing Cycle

Although you are free to use SVN as you wish, this is an editing cycle that works very well:

      svn up           # update
      svn log | less   # see details of update if there was one
      while (change not implemented correctly)
        while (program does not compile)
          edit files   # implement change
          make         # try compiling
        make check     # run automatic tests
      svn diff         # review changes
      svn ci           # commit

For source code, the time between commits should be small. Ideally, each commit makes an incremental and self-contained improvement. If you avoid checking in things that do not work, you will save yourself and others headaches in the future.

Of course, you may run into conflicts and other problems, in which case you should refer to the excellent Subversion documentation.

6. Other Advice

Do not check in generated source code or binaries.
Do not worry about repository disk space: copies are cheap and commits are incremental so you should use svn cp and svn ci liberally.
If you check something in, you must run svn up before that change becomes visible to svn log and other operations that examine history.
If the prospect of your working copy being deleted scares you, it is probably time to commit.

7. SVN GUI Clients

If you are not used to Unix and the command line interface, life may be easier if you have a GUI client and do not need to type commands in a console. However, at the same time, this course is an excellent opportunity to improve on your command line abilities, a skill that will serve you well for years to come.

Under Windows, you can try TortoiseSVN, an SVN client that integrates commands into your right-click context menu. It is fairly easy to install and use.

For Linux, there is eSVN, although it is apparently not as stable as TortoiseSVN.

A cross-platform solutions is SubClipse, an Eclipse plugin that does the same job. You can find very clear instructions on how to install this plugin here: http://subclipse.tigris.org/install.html.

SubClipse tip: Using "Synchronize with repository" rather than "Update" will show you more detail when you want to update your local working copy.

Finally, if you are looking to use SVN in your own projects, you may be interested in Trac, an integrated bug tracking, wiki, and version control system.

8. References

Official homepage: http://subversion.tigris.org/
Official documention: Version Control with Subversion
Wikipedia entry: Subversion software
TortoiseSVN homepage: http://tortoisesvn.tigris.org/
eSVN homepage: http://zoneit.free.fr/esvn/index.php
SubClipse homepage: http://subclipse.tigris.org/
Trac homepage: http://trac.edgewall.org/

Maintained by Chris Pickett [HOME]