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/

...

^ - 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.  

Ignoring Files

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

You will probably 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 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 you really 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 Folder from SVN

You can checkout structure nodes as directories on your local file systemMost commonly, you will checkout folders from SVN to local directories using a command such as this.

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/

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

This command ignores (always?) your working copy and always looks at the folder on the server.

Update Working Copy from Repository

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

The entire local An entire 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.

...

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!

...

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.

Merging Changes

...

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

This command can also be used to make copies of files.

svn cp -m "Copying my file." myfile.java myfile_v2.java

Or to copy a file into a folder.

svn cp -m "Copying my file." myfile.java some/dir

When copying a file into a folder, the folder must already exist in the repository (or have been added using the add command)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.

...