SVN Basics

This page includes explanations of terms and commands for Subversion or SVN.

Terminology

URL - a resource locator used for some SVN commands; in the case of Subversion these look like 'svn://repo/path/to/something'

relative path - a general file system term but for this tutorial it means the relative path to a file or directory in the working copy, as opposed to a full URL

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

remote repository - the remote copy of the code etc. maintained by the Subversion server

repository root - the base URL of the 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.

structure node - any part of the repository under the root, which can be conceptualized as a directory on a file system, with the repository root as the "/" or root directory.

working copy - your copy of an SVN module including local changes

revision - a globally unique number to the repository tagging the state of the repository after a commit (including add, delete, etc.)

commit - push your changes to the repository, making a new global revision

revision - a global revision number tagging the state of the repository after a commit.

trunk - the remote repository's current revision, similar to "HEAD" in CVS terminology

tag - a copy of the trunk from some certain point in time, which should not be modified once created; usually kept in a node called 'tags'

branch - a fork of the trunk (or some other version of the code) which is for development and can be modified after it is created; usually kept in a node called 'branches'

merge - combining together two copies of (usually) the same node in order to merge their changes

revert - clobber your local changes in the working copy and replace with the current copy in the remote repository

Global config for ignoring files

Typically in most coding projects, there are local files which will be created by an IDE or other tool which should always be ignored by SVN.

These can be configured on a directory basis in the repository but an easier method is adding them to your Subversion config file, typically found at ~/.subversion/config

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

These are some of the settings I use:

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

These will apply to all subversion directories and files so make sure that the files you include here really would never be checked into version control.

Commands

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

Text written like this indicates a  Subversion command that can be executed from your terminal.

Note that some (most) arguments to these commands like path/to/file are completely bogus and should be replaced by valid files in your working copy or the remote repository (depending on the command).

Checkout a structure node

svn co svn://repo/some/dir

Show information about the repository

This command will print out general repository information like your current revision # and the repository root.

svn info

Check the status of your local working copy

This command will list all your changes and additions in the local working copy:

svn status

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

M = locally modified

? = not tracked by Subversion

A = added

D = deleted

etc.

Check the SVN docs for a full list of all these commands.

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.

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