...

...

...

...

Development with Subversion

...

This page is currently being reformatted and rewritten.

...

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

Subversion Versions

The version of Subversion (no pun intended) is important because older versions are not compatible with newer ones, meaning you cannot checkout a project with say 1.8 and then use a 1.6 client on it.  This is because the metadata formats used to track local files changes with minor release numbers in incompatible ways. 

You can use this command to upgrade your local copy from an older client to the newer one.

cd sandbox; svn upgrade .

You should also make sure that your IDE's Subversion library is compatible with the command line client (covered in Project Development in Eclipse).

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.

master copy

The master copy refers to the current version of a file on the SVN server, as opposed to a local copy on your computer.

commit

Executing a commit will push your changes to one or more files or directories to the remote repository, making the master copy match your current local copy of those files.

revision

A revision in SVN is a globally unique identifier, starting with 'r', that tags 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.  (SVN actually tracks revisions globally rather than on a per file basis.)

URL

URLs in SVN are used to identify paths on the remote server.  These will have svn as the protocol.   (SVN supports other protocols as well such as https.)

For example, 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

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 node of the remote repository such as svn://svn.freehep.org/hps/.  This is similar to the root node in a file system.

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.

tag

This is a copy of the code at a certain point in time, usually 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

Merging will combine together the contents of two nodes.  This usually occurs when a branch should be reintegrated into the trunk or another branch.

revert

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

...

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

...

Here is a full list of these status codes.

...

Listing 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

The ls command is similar to the equivalent Unix command.  It can be used to list directory contents.

This is an example of listing contents of a relative path.

svn ls trunk/parent

This command can also be used with absolute SVN URLs.

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

Synchronizing your copy with the remote repository

The up command is used to synchronize your local of files and directories with the remote repository.

Assuming you are in a local working directory, this command will pull all updates from the server.

svn up .

Adding files to the repository

The add command is used to add new files to the repository.

svn add sandbox/castle.txt

This command does not actually push the files to the server but schedules this to occur.  A commit must be executed in order actually perform the addition of the files.

The command can also be used on directories, in which case the default behavior is that all files under the directory will be added too.  (Make sure this is actually what you want before committing!)

Deleting files from the repository

Files can be deleted from the repository using the rm command.

svn rm sandbox/castle.txt

 Similar to how adding files works, the deletion will not occur until you commit.

Committing local changes

In order to update the master copy of any file or directory on the server, a commit must be performed first.

This is an example of committing a local file.

svn commit -m "Add castle to sandbox." sandbox/castle.txt

Though this command can be executed without any arguments, it is a good idea to always list explicitly the files you want to include in your commit.  Otherwise, every file which is modified locally will be part of the commit, which you may not want.

Copying files or directories

Files can be copied so that their revision history is kept.

svn cp sandbox/castle.txt sandbox/citadel.txt

A commit is required to perform this action once it is scheduled.

Moving files

Moving files or directories is very similar to copying or deleting.

svn mv sandbox/castle.txt sandbox/citadel.txt

This command will schedule a deletion of the first file and an addition of the second, copying the revision history from the first to the second.  A commit must be executed to perform this command once it is scheduled.

Making a branch

Branching is actually a special case of copying where a structure node is copied to a new location and then development is performed on this new copy.  This is a basic way for developers to "fork" the code in an organized fashion so that any potentially disruption changes are kept isolated from the trunk until the code is made stable and working again.

This is an example of making a branch.

svn cp -m "Making a new HPS Java branch for some reason." ^/projects/hps/java/trunk ^/projects/hps/java/branches/HPSJAVA-123

The name of the branch is 'HPSJAVA-123' to reference a JIRA item.  This is just a dummy name.  In actuality, it should be a real JIRA item.  This allows someone to understand the purpose of that branch from its name.

Performing a merge

Merging is the process of including changes from one node in the repository into another.  After working on a branch, for instance, you will usually at some point want to integrate the changes make on the branch back into the trunk.

Using the above example branch, the following is the equivalent merge operation.

svn merge ^/projects/hps/java/branches/hps-java_HPSJAVA-123/ ^/projects/hps/java/trunk

In general, unless very minor changes were made to the code on the branch, you should always communicate with the other developers about plans for merging and what the state of the trunk will be after the merge is performed.

After a merge, the changes (additions, deletions, etc.) are only made to the local copy and must still be committed, using the usual commit command.

Making a tag

Creating tags in SVN is actually just another case of copying nodes.  In fact, there is no good way to actually make a read-only, fixed copy of the files at any given time in SVN, so tags are essentially a convention and not something that is actually supported!  Once a tag is made of the code, it should generally not be modified.  (That's what the trunk and branches are for.)

This is a (dummy) example of making a tag of the whole trunk.

svn cp -m "Making a bogus tag of the trunk." ^/projects/hps/java/trunk ^/projects/hps/java/tags/hps-java-1.2.3

The versions in actual tags within the HPS repository will correspond to releases made using Maven and Jenkins.

Reverting changes 

Sometimes you may want to revert a local file which will replace it with the equivalent file from the server.

For instance, this command will revert a single local file to its master copy, removing any changes you have made on it locally.

svn revert sandbox/castles.txt

The command will execute immediately unlike an addition or deletion.

You can also revert entire nodes recursively, which will replace all changes in and under that node with the master copy.

svn revert sandbox --recursive

You should be careful when reverting entire nodes, as this will completely clobber any changes you have made.

Using revert results in changes to your local copy that are not recoverable e.g. all your local edits will be removed.  So be careful when using this command.

Miscellaneous Tips and Warnings

• Do not checkout SVN URLs into some other project that is already managed by Subversion.  This has the potential to create some serious issues when executing Subversion commands, and it will also confuse you. 
• Do not modify files that are in tags of the code.  All changes should be made on branches or the trunk.  Tags should be 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 cannot be easily 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 doing complex tasks like merging, use the --dry-run argument like svn --dry-run merge to see what will happen without the command actually being executed. 
• Do not be overly dependent on your IDE for executing Subversion commands.  Always make sure to have a compatible SVN command line client available. 
• At the beginning of the work day, you should generally do a quick svn up on any modules you will be working on in order to synchronize the working copy with the repository.  This will make sure you do not cause conflicts by modifying a file that someone has already made conflicting 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

Additional Resources

• The Version Control with Subversion Online Book is a fantastic and thorough resource for all things Subversion. 
• The Apache Subversion Website is the official home of Subversion and has various useful links and resources.
• If you have specific questions related to SVN and HPS software development, the best resource is the Software Mailing List where you can feel free to ask questions, even ones you might consider fairly basic.
• Finally, should you have specific questions or comments about this page, please add a comment to the comments section.  (You must have privileges to edit HPS Confluence pages to do this.)

...