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

...

similar to their file system analogs.

Terminology

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

remote repository - the remote copy of the code on the Subversion server; often abbreviated 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.or sometimes called the "remote repository"

working copy - your local copy of an SVN module from the folder within a repository, including any local changes you have madetrunk - the remote repository's current, main revision of a project

structure node - a container within a repository that can have files in it or another structure node; similar to a directory in a file system

folder - aka structure node; also sometimes used to refer to directories in the local working copy that represent the local copy of these folders

global revision - every repository has a global revision which tags its current  contents and is incremented after each commit; in Subversion commands these will always start with 'r' as in 'r1234'

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

trunk - the remote repository's current, main revision of a project; usage of this term is only by convention as it usually just refers to a certain folder called trunk in the repository

revision - globally unique number in the repository starting with "r" that tags the entire state of the repository after a commit

...

relative path - the relative path to a file or directory in the working copy (as opposed to a full URL); many svn commands can use relative paths from within a working copy and not just absolute URLs

repository root - the base URL of the repository such as svn://svn.freehep.org/hps/

head revision - the most recent global revision of the repository

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

Repository Structure

SVN Repositories may contain many code projects.  

These are separated by different folders in the repository, usually under the root directory, but potentially in any sub-folder.

project1
project2
project3
[etc.]

Each project folder will typically have three sub-folders.

project1
    trunk
    branches
    tags

trunk should contain the main development branch of the code.  Most user commits will happen on trunk.

branches contains folders that are copies of the trunk, or some other folder, made by users; these represent development branches of the code that are eventually merged back into trunk or abandoned.

tags contains copies of the trunk that should not (really ever) be modified; typically, these are made when releasing software versions by a build tool or script.

SVN Client

The primary way to interact with a Subversion repository is through the svn command in a command terminal.

You can check if you have this installed on the terminal by typing

svn

Should the command not be found, then it would be a good idea to install it.

If you are using Linux, this is almost certainly already installed for you by your distro.

Otherwise, you could try installing it (e.g. for Yum users).

yum install subversion

On OSX, it should be bundled with the Xcode development tools which you can get in the app store.

Ignoring Files

Typically, you You will probably 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 that should be ignored to the config file at ~/.subversion/config which should have been created by Subversion in your working directory(if it does not exist then execute the svn command in a terminal).

These are the settings I use for global ignoressome example settings.

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 copyfilter will apply when using the status command and ignored files will not be considered by add, etc..

Commands

All commands described below assume you are in a terminal using bash on Linux or a similar Unix OS; also (mostly) assumed is , most of these commands assume that the current local directory is working directory in the command terminal represents an SVN structure node that has been checkout checked out of the repository.  

Most of the arguments used for these example commands are completely bogus and, depending on the command, should be replaced by valid paths to files in your working copy or the remote repository (should you actually want to execute those commands!).

If you really want to experiment with some of the more advanced commands (branching, merging, copying, etc.) you might think about setting up your own test repository as doing this kind of stuff on an actual production repository if you are just testing or fooling around is not polite.

Checkout a Structure NodeFolder from SVN

Most commonly, you will checkout folders from SVN to local directories using a command such as thisYou can checkout structure nodes as directories on your local file system.

svn co svn://example.org/repo/some/dir

svn:// is the protocol for communicating with the SVN server.

example.org is the host name of the server.

repo is the name of the SVN repository (servers can have multiple repositories).

some/dir is a folder in the repository.

You may checkout the entire repository.

svn co svn://example.org/repo/

But it is probably not a good ideaThis 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 representing its status.  The meaning of these abbreviation is fully described here.

Show

...

Changes in Working Copy

You can use the diff command to show changes between the repository and your working copy.

svn diff | less

This will display the changes in diff format between working copy files and the repository.

You can also specify a file or dir

svn diff some/file/or/dir

Show Folder Contents

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

...

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

Update Working Copy

You should periodically update This command ignores (always?) your working copy from the repository to keep it up to date.and always looks at the folder on the server.

Update Working Copy from Repository

An entire The entire local working copy can be updated by executing a command like this.

...

svn up some/dir some/file another/file

You should periodically update your working copy from the repository to keep it up to date.

Add Files

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

...

These changes will 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 in the repository when you commit.

When you execute the rm command, Subversion will not by default leave a local copy of the file and so will delete it immediately!

Commit Local Changes

This command is used to commit your local changes to the repository, including deletions, changes and additions which have been done on the working copy.

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.

Files must be explicitly added or deleted in order to be included in a commit using the add or rm sub-commands (described above).

Any changes to files that SVN knows about in the working copy will be included in the commit automatically.

Copy Files

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

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

...

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

Merging Changes

Merging can be done in different ways, and a complete summary is beyond the scope of this tutorial.involves combining changes from one version of the repository with another.  

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 When working on 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).

, you will periodically want to merge from trunk to your branch.

cd my-hps-java-branch; svn merge ^/java/trunk

Similarly, you eventually will want to merge back into trunk from the branch once you are done with it.

cd hps-java-trunk; svn merge ^/java/branches/my-hps-java-branch

Merging can also be used to undo bad commits.

See for examplesSee 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

...

This page shows the full syntax for the merge command.

Making a Branch

Creating a development branch is done using the copy command to copy the current version of the trunk into a branches folder.

svn cp -m "Creating development branch." ^/projects/java/trunk ^/projects/java/branches/my-dev-branch

Now my-dev-branch will be a complete copy of trunk at the time when it was copied.

Making a Tag

Tagging is actually performed by using the copy command.

svn cp -m "Creating a tag." ^/projects/hps/java/trunk ^/projects/hps/java/tags/mytag

Typically, tags are not created by hand but through an automated build/release system.

Tags are only by convention in SVN as the directories are typically not made read-only.  If you are checking out and modifying something with tags in its path, you're probably doing it wrong.

Reverting Local Changes

You can replace a file in your working copy with the repository's current version using a command like this.

svn revert path/to/broken/local/file

You can also recursively revert entire directories and their sub-directories should you really want to revert a lot of changes.

svn revert -R path/to/some/dir

You will want to be careful with this, as you can easily lose your work if it is has not been committed yet and gets reverted!

Warnings and Tips

• Do not checkout an SVN project into another , local working copy of a Subversion structure node.SVN project.  This has the potential to create some serious issues when executing Subversion commands, and it will also confuse youconfuse both you and the Subversion client (and repository).
  
  
• Do not checkout and modify tags of the code.  By convention, a directory node representing a tag in SVN, usually with "tag" someplace in the tags" as one of the sub-directories in its path, should not be modified once it is 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 outcomesub-directories.  You may not want this, so it is better to explicitly list files when adding them.
  
  
• 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 with that commit includedstripped out.  So please double check that you are adding only the files which that are intended to be included.  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 firstso you can verify that the status is correct.
  
  
• 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 your IDE for using 's Subversion plugin.  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. You should also be careful of certain GUI commands for adding files, as they will often include many files in the commit that you do not want (which is why typically it is preferable to list out all files that should be in a commit or add them individually).
  
  
• 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.  Also, the longer you wait between updates, the more chance that you have changes in your working copy which are not compatible with the repository's version.
  
  
• 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.

...