Overview

This is intended to serve as a basic introduction to the Subversion source code repository tool.  Basic terminology will be provided along with examples of commands.

Terminology

version control - the management of changes to code or other files using a central tool or service (Subversion being one example)

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

relative path - the relative path to a file or directory in the working copy (as opposed to a full URL)

remote repository - the remote copy of the code on the Subversion server; also abbreviated as "repo"

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 from the repository, including any local changes you have made

revision - a globally unique number in the repository tagging the entire state of the repository after a commit

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, main revision of a project

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

branch - a copy of the trunk or some other structure node which represents a development fork of the code; usually kept in a node called branches under the project's directory in the repository

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

revert - undo local, uncommitted changes in the working copy and replace with them with the current copy from the repo

Ignoring Files

Typically, you will want to configure the SVN client to ignore certain types of files that you might have in your working copy but do not want to be visible.

You can add global file patterns to ignore to the config at ~/.subversion/config

These are the settings I use for this.

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

The patterns will apply to all SVN nodes.

Commands

All commands described below assume you are in a terminal using bash on Linux or similar Unix OS; also assumed is that the current local directory is an SVN 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 Working Copy Information

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

svn info

This command will list detailed information about changes and additions to your local working copy compared with the repository.

svn status

Each file listed with this command will have a letter next to it.

M = locally modified
? = not tracked by Subversion
A = added
D = deleted
[etc.]

Check the SVN documentation for a full list of all these abbreviations.

Show Repository Contents

You can list the contents of a directory on the server using this command in your working copy.

cd my-working-copy; svn ls some/relative/path/

Or you may also use a URL in which case the command need not be executed within a working copy.

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

Update Working Copy

Periodically, you will need to pull changes to the repository into working copy to keep it up to date.

You can update your entire local working copy by executing this command from its root directory.

svn up

The command may also be executed with files or directories to limit the local files that are affected.

svn up some/dir some/file another/file

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.

Delete 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 Local 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 Files

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

Create a Directory

svn mkdir path/to/dir

Merge Changes

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.

You can also use merge to undo commits (or series of commits).

See for example:

http://stackoverflow.com/questions/13330011/how-to-revert-an-svn-commit

Make a branch

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

Making a Tag

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

Reverting Changes to Working Copy

svn revert path/to/broken/local/file

Warnings and Tips

• Do not checkout an SVN project into another, local working copy of a 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.  By convention, a directory representing a tag in SVN, usually with "tag" someplace in the path, should not be modified once created.  Changes should only be made on branches or the trunk.
  
  
• Be careful when using 'svn add' on a directory.  When used without file arguments, the svn add command will include all files all files and subdirectories under that directory into the commit, which may not be your intended outcome.
  
  
• Be careful when using 'svn add' and 'svn commit' without any arguments or with directories.  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 never really deleted unless the repository is rebuilt without that commit included.  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 use the -dry-run argument with commit to check first.
  
  
• Use the '--dry-run' argument before executing complex or dangerous commands.  This will show you 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.).
  
  
• Update your working copy regularly.  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.  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.
  
  
• Use branches when making an extensive set of complex changes to the trunk.  This will ensure that the trunk is not broken by committing unstable code, and it will also allow you to commit changes that "break everything" without affecting anyone else using the trunk.