Subversion Quick Reference

The best resources are the home page and the free online version of the O'Reilly book Version Control with Subversion.

Subversion is a centralized version control system. There is a single central repository running on a Subversion server, containing many projects. Creation of projects and access control of users to projects is done by the sysadmin.

Subversion comes with Fedora Linux and most other Linux distributions. On Mac OS X it can be installed via Fink. A Mac OS X graphical client is svnX. Under Windows Subversion can be installed as a command-line client as part of Cygwin, or with the native TortoiseSVN client that integrates with Windows Explorer.

Checking out a project for the first time

To access a project stored in a Subversion repository it must first be checked out. Assume that we have a project named proj stored on the server https://lagrange.mechse.illinois.edu/svn/. Then we should run:

svn checkout https://lagrange.mechse.illinois.edu/svn/proj

This will make a directory called proj containing the latest copy of the project files. You may need to provide a username and password, which can be obtained from the sysadmin (email sysadm@lagrange.mechse.illinois.edu). Your Subversion username and password are not the same as those used to log on directly to the machines.

The update/edit/commit cycle

The standard usage pattern with Subversion is:

• Update: Run svn update in the proj directory. This brings changes from the central repository to your local copy. You should do this frequently to ensure that you stay current with changes that other people are making. The single upper-case characters in the left-most column indicate the type of update that was done to each file. The only thing to watch for here is the C character, which indicates that a conflict occured between changes that another user made and some of your changes. See below on dealing with this.
• Edit: Make your changes to the files, including resolving any conflicts from the last update.
• Commit: Run svn commit in the proj directory. This sends your changes back to the central repository so that other people can access them. It is a good idea to fill in the commit messages file with meaningful comments, so that later it is possible to track back through the version history.

The Subversion collaboration model works best when everyone updates and commits frequently. Always update before starting an editing session, and always commit once you are finished working for the day, or even more frequently.

Dealing with conflicts

If you see a C character for a file after running svn update or svn status then it indicates a conflict in that file. This occurs if both another user and you have edited the same portion of a file and Subversion was unable to automatically merge the changes.

In the event of a conflict there will be four files:

• filename is Subversion's best attempt at merging your local changes with the repository copy. Conflicts in the file are bracketed by <<<<<< and >>>>>>.
• filename.mine is the copy of filename as it existed in your directory before you did the update.
• filename.rOLDREV is the copy of filename that you last checked out before editing it.
• filename.rNEWREV is the copy of filename that you just checked out, containing the other user's changes.

You need to use the contents of these files to update your copy of filename to include all of the changes from both you and the other users, adding or discarding changes as you wish. You then must run:

svn resolved <filename>

This tells Subversion that the conflict is resolved, and so it will let you commit again.

Other useful commands

• svn help will list possible commands and give detailed information.
• svn status will show the current status of all files, and what would happen if a commit was done. Use svn help status to see the list of symbols and their meanings.
• svn add <filename> will add a new file to those which Subversion knows about and stores in the repository. The file will not be sent to the repository until the next svn commit is run.
• svn delete <filename> will remove a file and stop Subversion from tracking it. The actual deletion from the repository will not occur until the next svn commit is run.
• svn copy <filename> <new_filename> will copy a file and add the new file to Subversion. The new file will not be sent to the repository until the next svn commit is run.
• svn move <filename> <new_filename> will rename a file. The rename will not be done in the repository until the next svn commit is run.

Properties (binary files and EOL characters)

Each file in a Subversion repository has properties associated with it, which are arbitrary versioned metadata. To list, set or delete properties on a file do:

svn proplist --verbose <filename> svn
propset <property_name> <property_value> <filename> svn
propdel <property_name> <filename>

After you have set or deleted a property you must svn commit to send the change to the repository.

While you can set arbitrary properties on files, there are a number of properties which will change how Subversion behaves. The most important are:

• svn:mime-type controls how Subversion deals with the file. In particular, if this property is set to application/octet-stream then subversion will treat the file as binary, and not perform text-based merging on it. Subversion will try to automatically set this property when you add a file if it detects it as binary. Sometimes (particularly with PDF files) it will fail, and then you need to manually run:

     svn propset svn:mime-type application/octet-stream <filename>
   

• svn:eol-style controls how end-of-line characters are handled in the file. If it is set to CRLF, LF or CR then the file will always be forced to use the given EOL characters, irrespective of the platform that the file was updated or committed from. If this property is set to native then the file will be seen with the native EOL characters on each platform, and Subversion will store the file in the repository with LF EOL characters.
• svn:executable controls whether a file is executable (has the x permission bit set on UNIX). If it is set to * then the file is executable, and if the property is not set then the file is not executable. This can be set or cleared with:

     svn propset svn:executable '*' <filename> # set executable bit
     svn propdel svn:executable <filename> # clear executable bit