Development with Subversion

This page is a detailed primer on how to use Subversion for software development. 

It includes definitions of basic terminology plus explanations and examples of basic commands.

Terminology

Here are some basic terms with which you should be familiar in order to understand the rest of this guide.

version control

Version control is the management of changes to code or other documents from a central tool or service.  Subversion is one example of a version control tool.

SVN

The term "SVN" (note all caps) is often used more-or-less interchangeably as an abbreviation of "Subversion".  (The capitalization makes no sense as it isn't an acronym but this is common usage!)

svn

The Subversion command line client is executed from a shell with the "svn" (note lower-case) command.  (This is not to be confused with SVN in all upper case!)

remote repository

The remote repository, often just abbreviated as the "repo", is the remote, master copy of the code which is maintained by the Subversion server.

checkout

Copying the remote repository's version of a file or module to your local computer.

working copy

A working copy is your local version of any SVN module or file from the remote repository.  Executing an svn checkout will create a local copy of a file or directory.

commit

Executing a commit will push your changes on one or more files or directories to the remote repository.

revision

A revision in SVN is a globally unique number identifying the state of the repository at some particular time.  Every commit will create a new revision.  The revision numbers are numbered sequentially from 1 to however many revisions have been created.

URL

URLs in SVN are used to identify paths on the remote server which has the master copy of the source code.  In the case of Subversion, these will have svn:// as the protocol. 

For example, svn://svn.freehep.org/hps is the URL for the HPS Subversion repository.

relative path

A relative path is a general file system term, but for this tutorial it means the relative path to a file or directory in the working copy of the source code on your computer.

For instance, a relative path in your local copy of might be tracking/pom.xml which points to the POM file for the tracking module.

In general, if you execute svn commands within a local directory that is tracked by Subversion, they will be interpreted correctly.

repository root

The base URL of the remote repository such as svn://svn.freehep.org/hps/.

The "^" character can be used to specify the repository root for any command that accepts a Subversion URL.

trunk

By convention, the "trunk" refers to the mainline development branch on a project.  This is quite similar to "HEAD" from CVS terminology

structure node

Any part of the repository under the root.  Structure nodes can be conceptualized as a sub-directory on a file system, with the repository root as the root directory.

tag

This is a copy of some directory at a certain point in time like when a release is made.  By convention, a tag should not be modified once created.  They are usually kept in a node called 'tags'.

branch

This is a fork of the trunk, or even of another branch, which is for development and can be modified after it is created.  Branches are usually kept in a node called 'branches'.

merge

To merge means combining together two nodes in order to merge their changes together.

revert

To revert means clobbering your local changes in the working copy and replacing them with the current copy from the remote repository.

Ignoring Files

Typically, there are local files which will be created by an IDE or other tool which should always be ignored by SVN.  Oftentimes test output and other files will litter an SVN directory as well.

An easy way to ignore files is by adding them to your Subversion config file, typically found at ~/.subversion/config.

There should be a line in this file which says "global-ignores" which can be un-commented and then modified. 

These are the settings I use for HPS projects.

global-ignores = target *.class *.jar *.diff x.x *.log .classpath .project .settings *.tar.gz .cproject gmon.out *.slcio .dependencies

These ignore settings will apply to all Subversion directories and files.

Commands

All commands below assume that you are in a command shell like bash on Linux and that the current directory is a local working copy of a structure node that has been checked out of the repository.

Checking out a structure node

The svn co or svn checkout command is used to make a local copy of a remote file.

For instance, you can checkout the entire HPS Java trunk.

svn co svn://svn.freehep.org/hps/java/trunk

By default, all sub-nodes will be checked out recursively.

You cannot actually checkout a single file from SVN, only structure nodes.

Showing information about local files and nodes

The svn info command will print out useful information about your working copy.

For instance, this is the result of that command executed on my copy of the HPS Java trunk.

[$] svn info
Path: .
Working Copy Root Path: /u1/projects/eclipse/luna/java_workspace/hps-java_trunk
URL: svn://svn.freehep.org/hps/java/trunk
Relative URL: ^/java/trunk
Repository Root: svn://svn.freehep.org/hps
Repository UUID: 044bc1e2-196f-4772-ab28-abfd6a072e98
Revision: 1275
Node Kind: directory
Schedule: normal
Last Changed Author: lcdprod
Last Changed Rev: 1272
Last Changed Date: 2014-10-22 16:44:16 -0700 (Wed, 22 Oct 2014)

By default svn info will look at the current working directory but it can also take a directory or file as an argument.

svn info parent/pom.xml
svn info parent

Showing status of local files

You can use the svn info command to show the status of local files compared to their remote versions on the server.

From the root directory of your working copy, this command will show all changes that have been made to the node.

svn status

This command will return a list of files and directories that are different from their remote copies.

Each file will have a letter next to it indicating its status, such as:

M =locally modified

? = not tracked

A = added but not committed

D = deleted but not committed

etc.

Here is a full list of these status codes.

Show node contents

svn ls some/relative/path/

or

svn ls svn://repo/some/path/

Synchronize your copy with the remote repository

svn up

Add files to the repository

This command can be used to add files:

svn add rel/path/to/file1 rel/path/to/file2

These will then be pushed to the remote repository when you execute a commit.

Delete files from the repository

This command can be used to delete files:

svn rm rel/path/to/file1 rel/path/to/file2

The deletion will occur when you commit.

Deleting Files

To delete files use this command:

svn rm /path/to/file

You also need to perform a commit to delete the files in the repository and not just the local copy.

Commit changes

This command is used to commit your local changes to the repository:

svn commit -m "committing some stuff" [optional/path/to/file1] [optional/path/to/file2]

The list of files or directories to commit is optional, but it is usually a good idea to include it.

Copy file or directory from one place to another

svn cp src/dir/or/file target/dir/or/file

Create a directory in the repository

svn mkdir path/to/dir

Perform a merge

Merge a branch into the trunk:

svn merge ^/projects/foo/branches/v01-02-03/ ^/projects/foo/trunk

This is an advanced command so don't use it unless you know what you're doing.

Same command which just prints what would happen:

svn merge ^/projects/foo/branches/v01-02-03/ ^/projects/foo/trunk

After a merge, the changes are made to the local copy and must still be committed, using the usual commit command.

Make a branch

svn cp m "making a branch" ^/projects/foo/trunk ^/projects/foo/branches/foo-dev

Make a tag

svn cp -m "making a tag" ^/projects/foo/trunk ^/projects/foo/tags/foo-1.2.3

Reverting changes  

svn revert path/to/broken/local/file

Setting properties

Files can have properties on them.  This can be used to alter the behavior of Subversion.

For instance, this command will cause all files with the .log extension to be ignored in the current directory.

svn propset svn:ignore "*.log" .

Tips and Warnings

Do not EVER checkout an SVN project into another Subversion structure node.  This has the potential to create some serious issues when executing Subversion commands, and it will also confuse you.

Do not checkout and modify tags of the code.  All changes must be made on branches or the trunk so that the remote repository can be updated.  Tags are considered 'frozen' once made.

Be careful when using 'svn add' on a directory, as by default it will add ALL files and subdirectories under that directory, which may not be your intended outcome.  (see next item)

Be careful when using 'svn add' and 'svn commit' without any arguments or with directories, either from the command line or from the top-level in your IDE e.g. the infamous Team > Commit from an Eclipse project.  This may cause many files to be added to the repository that should not actually be tracked and will subsequently need to be removed.  Once a file is added, it is tracked 'forever' by the repository and not deleted, even though it might then be removed in the trunk and subsequent revisions.  So please double check that you are adding only the files which are intended.  Before making a large or complicated commit, first use 'svn status' in your working copy to see what files will be committed or run 'svn --dry-run commit'.

When executing more complex commands such as 'svn merge' use the '--dry-run' argument like 'svn --dry-run merge' to see what will happen without the command actually being executed.

Do not be too dependent on the IDE for using Subversion.  Make sure to have a compatible SVN command line client available e.g. where the SVN minor version number is the same as your IDE's "connector" version (Eclipse), so that you are able to execute shell commands.  This can be a pain to setup properly when using Eclipse, so the preferred method of keeping these tools compatible is installing the version of the connector from Eclipse that matches your existing command line client ( e.g. 1.6, 1.7 etc.).

At the beginning of the work day, do an 'svn up' in order to synchronize your working copy with the repository.  This will make sure you do not cause conflicts by modifying a file that someone has already made changes to in the repository.

Do not develop code in your working copy for an extended period of time without committing it, provided of course that checking it in does not cause a compilation or test case failure.  This is especially true if there is the possibility that someone else is working on the same file.  When possible, prefer checking in your work at the end of each day, or, at a minimum, the end of every week.

If there are files that are always generated by your project's build which should not be put into version control, consider adding these file names to the ignore list for the project's directory, as covered here: http://stackoverflow.com/questions/86049/how-do-i-ignore-files-in-subversion