This page is devoted to getting a subversion user up to speed. It is NOT designed to cover subversion admin basics.
The authorative documentation for Subversion is located at http://svnbook.red-bean.com/
Table of Contents
Note to Subversion users on SEEGrid
When reading documentation on subversion, keep in mind that our repositories are stored on www.seegrid.csiro.au, and accessable via https://www.seegrid.csiro.au/subversion/repository_name
which uses webdav/https.
We recommend users external to CSIRO to use the TortoiseSVN
client mentioned below, since it can handle proxies AND https.
Note some of the older proxies CANNOT handle the DeltaV protocol used by WebDAV - please ask your administrator to upgrade your proxy software.
TBD: insert step-by-step instruction here to check out a the xmml repository (or some other sample repository).
Version Control Concepts
What is Version Control
Version control is the name given to the processes and techniques used to keep track of evolving assets. In particular tracking the changes of computer data files, whether it is source code or a electronic document. It can be used as an collaboration tool, to assist multiple contributors edit a single file in an orderly manner.
What version control software are out there?
The most popular one in use is CVS (Concurrent Version Control System). It is an open sourced project, hence free as well. Some of the more well known commercial packages includes BitKeeper
, used by Linus to hold the Linux kernel repository, and ClearCase
, used by many large companies such as Motorola.
Subversion is relatively new onto the scene, only going to version 1.0 in early 2004. It attempts to address the deficiencies in CVS; the main one of which is its inability to track directories structures. Subversion also attemts to leverage some of the more wide spread standards that have since establish themselves after the creation of CVS, such as providing access over WebDAV
/http instead of its own propriety protocols.
Branching vs Copying
Situation 1 - Copying
You have a model describing a mine site. You want to do several tests with it, including adding a fault in one case, and changing the composition of some of the rocks in another. It might seem sensible to "branch" your model at this point, using Subversion's branching mechanism to keep track of the two separate model. However this will be the WRONG
thing to do. You should copy
your model instead (
). By copying your model, each of the new model has the same version history up until the split, but since the two models are now quite distinct (they represents different situations) this is reflected in the repository by being two separate set of files (with the same origin).
Situation 2 - Branching
You have a model of a mine site, on which you and several of your collegues are working on. You need to add new features into the model, and this process will take several days to do. During this time you want to check your model into version control regularly (because there are many subfeatures marking logical times at which to check in the model). Furthermore, until the feature is fully integrated into the model, the model will be in a inconsistent state. By creating a branch
for your modifications, you can enjoy the benefits of version control (multiple revisions, revision history logs, etc) without "polluting" the trunk
version of the model with inconsistent states. When you finally finished adding the feature, the branch
could then be merged
back into the trunk
, thus exposing the new feature.
The concept of branching is Subversion is very specific. In a version control system, you branch your files when on one hand you need to work on your files by changing them, and on the other hand you need to keep them stable. It is assumed that the branch will eventually be merged
back into the trunk. Tools are provided to assist in merging.
Branching implies that files are related beyond as simple common ancestry. There is an implicit idea that they (in whole or in parts) will eventually be merged
If your files need to change into multiple different versions, the correct thing to do is to make copies of the files. This will reflect the fact that the files are different. Important (note to CVS users):
Don't simply copy your files and start working on them. Use
instead, this way the version history is keep for all the different versions of the file. You could also see from the version information when the various files split off from the one common ancestry.
Starting on a Project
Importing New Source
source into a repository when you have a lot of files you want to add to the repository, already laid out in a directory structure that you are happy with. This usually happens at the start of a project, when you have a set of files you want to start your repository with.
svn import [PATH] [URL]
PATH is the directory on your local file system that you want to import into the repository,
URL is the repository location.
Conceptually, an import
is very similar to and add
, they both add files/directories to your repository. The differences are -
svn import lets your specific exactly how your local path is related to the remote repository,
svn add does not. Hence, if you don't have an existing repository already checked out, you must use import as svn will not know which repository to use if you used add.
svn add has revert functionality,
svn import does not. Basically an import immediately adds the files to the respository, whereas add does not until you do a
svn commit, thus giving you a chance to discard your additions.
Checking Out Existing Source
from a repository when you want to start working on a project which already have a populated repository. When you checkout
a repository, you are effectively taking a copy of the repository and storing it on your local filesystem.
svn checkout [URL]
With subversion, to work on files/directories in a respository you firstly must make a local copy of the files. checkout
is one of the main method to obtain such a copy.
If the repository has changed (ie someone else checked in some work, or maybe you checked in some work from your home pc), then you need to bring you local copy up-to-date with the repository copy. This is done by an update
From within the "top" directory of your repository -
svn update [PATH]
if you wish to only update a subdirectory of your local copy, you can do the update
from within that directory.
When you do an update
, the subversion client will automatically download copies of all the files that have changed since you last checked out the files. The subversion client will report with a list of files that have changed. One of the following situation could occur -
U file was updated form the server.
A file was added to your working copy.
D file was deleted from your working copy.
R file was replaced in your working copy. What this usually means is that file was deleted, then another file has been added back into the repository with exactly the same name/ location. Note to CVS users Unlike CVS, Subversion considers the new file to be different to the old one, and hence their version history will not be a continuation each other.
G a "safe" mer*G*e has occurred. This means that a change in the file has occurred in both your local copy as well as the servers copy, HOWEVER they occur in different locations (lines) of the file and was "safely" merged.
- Note that subversion automatically distinguishes between binary files and text files, thus will won't merge binary files.
- Also note, what subversion considers to be safe is that no changes occurs in both files on the same line. This is usally acceptable for programming source files, but if it is a document, I recommend at least giving the document a cursory examination to make sure that it still makes sense.
- Note to CVS users This is equivalent to a CVS Merge.
C a "conflict" during a merge has occurred. It means that changes occurred on the same line in both of the copies. You will have to manually resolve the changes before the update is considered successful. See the section on merging and conflicts for more details.
- Note to CVS users This is equivalent to a CVS Conflict.
Adding a directory or file
When you have a new file/ directory to add to the repository.
svn add [FILE]
Registers a new file/ directory with the repository. Note that if the file is a copy of another file in the repository, you should consider
instead of add
Deleting a directory or file
a file from the repository when you no longer need it. Note that the history and the file is still retrievable (via previous versions), it just no longer gets checked out by default.
svn delete [FILE]
Copying a directory or file
When you have a file that you want to create different versions of, for different purposes, consider using copy
svn copy [FILE SRC] [FILE DEST]
for more details. Copying
is basically an excellent way to create a group of files that all have a common ancestry, but have seens split to serve different purposes.
Note to CVS users:
You should use
instead of just copying a file and doing a
. This preserves the common history for all the new versions of files.
Moving a directory or file
You want to rename a file in the respository.
svn move [FILE SRC] [FILE DEST]
If you delete
a file and then add it back to the repository under a different name, you will lose the history associated with the file. By using a
you could preserve the history when changing the name.
Merging and Conflicts
When merging two different branches (or branch back to trunk), make sure you read and understand the following section - http://svnbook.red-bean.com/svnbook/book.html#svn-ch-4-sect-4.1
- Get a local copy of one of the branches you want to merge.
- Find out all the revisions of the other branch (usually first revision of branch orig:HEAD is sufficent).
svn merge --revision branchorig:HEAD http://...../path/to/other/branch
NOTE: If you are using tortoiseSVN make sure the
fields both list the branch you are merging from. Or else you will try to do a 3 way merge - and who knows what happens then!
Examing Your Copy
Status, Differences and Reverting
Accessing Older Versions and MetaData
Specific (GUI) Clients
This is my (RobertCheung
) recommended GUI client if you are using MS-Windows. It integrates nicely with your file explorer (you right click to call up the menu) and the client itself is fairly robust and stable. It is the only GUI client that I know that could handle a https connection via a proxy (instead of a direct connection). To be honest, if you cannot use TortoiseSVN
, I recommend not to use anything else but the command line client. (All the other GUI clients so far are pretty poor in my opinion).
For most part, everything that you can do with the command line svn client, there is a corresponding command in TortoiseSVN
by right clicking on the file/directory. The only exception is "svn moving"/"svn copying" a file, in which case its less intuitively accessed by right-click-and-drag
Moving files are effectively a copy operation followed by a delete operation. To do this easily in TortoiseSVN
, you select the files you want to move and right-click-and-drag
it to where you want it. This will pop-up a menu with some options. Select the "Move files in subversion to here" option and then commit.