Short introduction to Subversion

The goal of the Subversion project is to build a version control system that is a compelling replacement for CVS in the open source community [Subversion].

Installation

Subversion can be downloaded from http://subversion.apache.org/. For Microsoft Windows, there exists a GUI-Application called TortoiseSVN. This tool integrates into the Windows Explorer and can be used via the context menu (right mouse click). Both Subversion and TortoiseSVN are available with an installer. If you are using Linux, check whether your Linux distribution already provides the subversion package for you.

Moreover, you can integrate Subversion with your IDE (integrated development environment). Netbeans has integrated support for Subversion – see “Versioning” menu or “Tools – Plugins” in case you did not install the appropriate plugin. For Eclipse, you can install the Subclipse plugin.

Usage

This short introduction to the use of Subversion concentrates on the commandline client (svn) of Subversion. Please map these information for TortoiseSVN by yourself as the commands are titled mostly the same way in TortoiseSVN’s context menu. Moreover, only the part of working with an already set up repository is described but not how to setup and administrate a Subversion repository.

The first thing to do is to check-out the repository to your own computer by using the “svn checkout” command. Afterwards, you can start working on the code. A short overview of the most important commands is provided below.

CommandDescription
svn helpLists available svn commands
svn help COMMANDProvides a description of the specified command.
svn checkoutInitial checkout of a svn repository. Typically called in the following way:
svn checkout –username USERNAME URL DIRECTORY_FOR_CHECKOUT
where USERNAME and URL will be provided to you by the owner of the repository, the DIRECTORY_FOR_CHECKOUT is the name of local directory on your computer.
svn statusProvides a status overview of the local repository – lists added, modified, deleted and unknown files
svn updateUpdates the local repository to the latest version of the server.
svn add FILE…Adds the specified file(s) to the repository – will be transfered to the server at the next time svn commit is called.
svn rm FILE…Removes the specified file(s) from the repository – will be removed from the server the next time svn commit is called.
svn mv FROM TORenames/relocates a file/directory from FROM to TO.
svn revert FILE…Removes any changes on the specified files performed since the last “svn update” (or “svn checkout”).
svn commitCommit in the sources from the local repository to the server.
Please follow the principles provided below for commiting to the repository: Specify an appropriate log message every time you commit so that other developers know what you have changed. Before you commit resources into a repository, run “svn update” and check whether everything still works as expected, e.g. running “ant clean dist test” cleanly compiles your sources and the test cases execute without errors.
svn diffDisplay the differences between two versions – the modifications since the last “svn update” by default.
svn cleanupRecursively cleans up the working copy, removing locks, resuming unfinished operations, etc. Call this if requested by the output of another svn command or if you are uncertain whether your working copy is clean.

For further details on subversion see the book Version Control with Subversion

Important notes for version control

Concurrent Changes

Don’t overwrite concurrent changes: If you checked out the sources from a repository, please work on these sources directly. If you proceed the following wrong way:

  1. Check out the sources, e.g. to MY_DIR
  2. Copy the files to some other directory, e.g. OTHER_DIR
  3. Run “svn update” within MY_DIR to bring up your repository to the latest version
  4. Copy your changed sources back from OTHER_DIR to MY_DIR
  5. Run “svn commit” within MY_DIR

concurrent updates, e.g. bugfixes by other developers, will not be detected and at some point in time you will certainly overwrite concurrent updates of other developers who won’t be very happy with the fact that you voided their efforts.

Hence, proceed as follows:

  1. Check out the sources, e.g. to MY_DIR
  2. Modify the sources in place (within MY_DIR or some subdirectory)
  3. Run “svn update” within MY_DIR
  4. If “svn update” reports conflicts, resolve them
  5. Check whether everything compiles again and run “svn commit” within MY_DIR to check in all the changed sources at once.

Undo Changes

If you discover that you committed something wrong (e.g. at revision 305) that should never have been committed and want to undo it, you can perform that by calling "svn merge -r N:M SOURCE [WCPATH]" where N is the revision you wrongly commited and M is the revision before, source may be and URL or working copy item, the WCPATH is a working copy path that may be omitted in which case “.” is assumed. For example, you just committed revision 305 and want to undo it. In the easiest case, you just perform “svn merge -r 305:304 .” within the root directory of your development tree. After you verified that this command produced your desired results, you have to svn commit your changes.

If you have not yet commited your changes, you can simply svn revert your local changes (see svn help revert).