Page History

...

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.

Subversion uses a file system paradigm for its concepts.  So many file system terms like copying, deleting, moving, etc. are similarly applicable to SVN repositories.  

Some concepts such as merging have no analog in file system terms.

Terminology

You will need to become familiar with some basic terminology to understand the basics of SVN.

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 often 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.to "repo"

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

trunk - the remote repository's current, main revision of a project

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

revision - a global revision number tagging the globally unique number in the repository starting with "r" that tags the entire 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 called tags

branch - a copy of the the trunk or some other structure node which represents a development fork of the code; usually kept in a node called branches under  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

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)

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.

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 that should be ignored to the config file at ~/.subversion/config which should have been created by Subversion in your working directory.

These are the settings I use for thisglobal ignores.

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 so make sure that yo ureally want these patterns to always be ignored in your working copy.

Commands

All commands described below assume you are in a terminal using bash on Linux or a similar Unix OS; also (mostly) 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.

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

Checkout a Structure Node

You can checkout structure nodes as directories on your local file system.

svn co svn://repo/some/dir

This will work for the root repository URL or any sub-node within it.

Show Working Copy Information

...

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 abbreviationsrepresenting its status.  The meaning of these abbreviation is fully described here.

Show Repository Contents

...

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

Update Working Copy

Periodically, you will need to pull changes to the repository into working copy You should periodically update your working copy from the repository to keep it up to date.

You can update your The entire local working copy can be updated by executing this command from its root directorya command like this.

cd hps-java-trunk; 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

...

This command can be used to add files :to the repository.

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

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

Delete

...

Files

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.

...

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:, including deletions, changes and additions.

svn commit -m "committing some stuff"

...

 path/to/file1

...

 optional/path/to/file2

...

Usually it is good to include a list of files that should be specifically affected by the commit.  Otherwise, you may inadvertently commit changes.

Copy Files

Similar to how a file system works, files can be copied.  In Subversion, this will essentially "fork" the file from the source version of it.

Here is an example of making a copy of a file with a new name.

svn cp some/file1 another/file2

This copies the file file1 to file2 in another directory.

Or a directory may also be used as the target, which will keep the file's original name.

svn cp some/file1 another/dir

Create a Directory

There are two ways to make a directory in a Subersion project.

Firstly, you may create a directory locally and then add it.

cd some-svn-project; mkdir newdir; svn add newdir

Or you can execute a command which will affect the remote repository directly.

svn mkdir path/to/newdir

In both cases, you will need to commit in order for these changes to be pushed to the repository.

...

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

Merging can be done in different ways, and a complete summary is beyond the scope of this tutorial.

Two different types of merges will be covered here, though this is far from covering all the ways in which this command can be used.

Merge a branch into the trunk:

...