From Documentation
Jump to: navigation, search

Why Version Control

It is common that one has several versions of the same code that evolves constantly during the course of development. Quite often most people will be versioning their files manually with numbers indicating different versions, so that they can roll back and forth to the versions they need. While for small projects or if you do not have many files to organize this might not sound too bad, having an automatic, efficient way of versioning the files and projects your are working on will greatly help you get things better organized.

There are many revision control software out there that helps you to achieve the goal. A common feature that most people find useful is the version control software helps you to keep track of changes you made to the files. Instead of having dozens of copies of the same file scattered in your working directory, you work only on one copy. Once a while after you make changes to a file, you "check in" the file and then continue on to make new modifications if you want. By checking-in a file, the version control software locks in the changes you made internally in a place usually called "repository". If you later want to "roll back" to a version, say, that you had worked on until last month, you can retrieve the exact old files from what have been checked in. Also, a version control system is very useful for group projects. Each group member can work on the same set of files simultaneously. With the version control in place, group members can retrieve, update and merge files in a safe, manageable way.

The open source project Subversion ( or SVN provides a compelling option for people who want to do things better. The SVN works in a client-server framework. Files that are under version control are stored on the server, which could be on a remote computer or on the same computer one's using, and one works on the "working" versions of the files in the directories, often called "sandbox". For instance, assume you have a project, called "simulation", which has source files and data in the directory simulation in your home directory ~/simulation. With SVN, you have a set of "replicated" copies of simulation stored on the server, corresponding to different versions of the source and data sets during your development.

On SHARCNET systems, each PI has a repository for his or her group accessed using a SHARCNET account, and permissions are set so that only members of the group may access it. The diagrams below illustrate the scenarios of how one can manage files under development


Figure 1. One has files in SHARCNET home account (working copies) and in the repository.


Figure 2. One has files on both SHARCNET and his/her desktop, and stores them in the repository.

The URL to each PI's repository is at

svn co

where pi_username is the username of your PI. Please note: SHARCNET repositories are not saved on backed up storage, so there is the possibility that they could be irretrievably lost. It is a good idea to check your repository out periodically to a location where you can ensure that the data is safe.

The following sessions briefly describe how to use SVN to retrieve, create and modify your projects. It is assumed that that you are using SVN under UNIX and you have SVN client installed on your local machine.

Retrieving Existing Projects

To start with, you may want to create a separate directory in your home directory, often also called "sand box" on your local computer. In the following example, you create a directory named repo, which resembles the repository tree repo and settings particular for your group, for example, jsmith

svn co

And hereafter we would assume that your login name is you and you belong to a group jsmith (which is your PI's username). Your first time access will be prompted for your SHARCNET username and password.You may also get a certificate warning, which you will have to accept:

[you@bl125:~/projects]% svn co
Error validating server certificate for '':
 - The certificate is not issued by a trusted authority. Use the
    fingerprint to validate the certificate manually!
Certificate information:
 - Hostname:
 - Valid: from Mar  6 20:09:38 2008 GMT until Mar  6 20:09:38 2009 GMT
 - Issuer: SHARCNET, London, Ontario, CA
 - Fingerprint: 6d:a2:b9:62:60:9f:bb:d5:60:7c:ca:ba:84:50:42:44:82:4a:94:e2
(R)eject, accept (t)emporarily or accept (p)ermanently? p
Authentication realm: <>
Password for 'you': 

This will create an entire tree repo in your home directory. If the attempt failed, you will need to contact the system administrator for assistance.

If you only want to check out the content in a particular directory, say, simulation, that already exists in the remote repository, then, your can use command

svn co

This will result in the directory tree repo/simulation being created or updated in your home directory on your local machine.

Once you have your local copy of repo, if you want to check out any contents under repo you will not need the URL as show above, but an update. For example, if you have a subdirectory simula08 under repo as shown below and it is only the content in viz that you wish to check out:

          |          |        |
     /simula07     /misc     /test
 |        |      |
/c    /fortran /viz

you may just do the following

cd repo/simula07
svn update

To see the details for SVN client commands, see the man pages of SVN.

Importing A New Project Tree to Repo Root

To add a new project "stats" to the repository, use the following command

svn import stats

It will add the directory "stats" with all the contents to the repository root.

Extracting A Unversioned Copy

Projects (folders) under revision control with Subversion have a hidden directory .svn in each subdirectory containing the information used by Subversion. If you want a copy of the project, for example, project1, with such files removed, you can use the following command

svn export

This command will download the directory project1 from the repository to the local computer, with those system generated files .svn removed. If you want to name it differently, you can use the command directly

svn export project1_copy

On your computer, in the currently directly, the downloaded folder will be named project1_copy.

Adding New Files or Directories to A Project

If you are adding new files to a project, you will use the following commands

svn add file1 [, file2 [,...[, fileN]]]
svn commit

The commit command option commits the changes you hae made - new files are added to the project in the repository.

If you are adding a new project, say, foo, which contains a number of files and directories, then the command

svn add foo
svn commit

will add all the contents contained in foo to the repository.

Deleting Files from A Project

Removing files from a project can be done with the following commands

svn del file1 [, file2 [,...[, fileN]]]
svn commit

You can delete an entire directory foo with the command

svn del foo
svn commit

The commit command option flushes out the entire directory foo in the repository as well.

Renaming A File or Directory

To rename a file, run the following command

svn ren oldfile newfile
svn commit

This command (with the current version of Subversion) in fact involves two operations: it makes a copy of the original one rename it and delete the old one.

Modifying A Project

After you have made changes to a project, for example, you modified the file "fun.f90", you want to keep a version of it. To check in a file, use the following command

svn update
svn commit fun.f90

Note if you are working on a group projects and other group members are working on the same set of files and data, it is important that you perform an update operation first to sync up your sandbox with the repository to reflect any changes possibly made by others before you make any changes. After you enter the commit command, you will then be prompted with an opened file in an editor (set through the environment SVN_EDITOR=vim, for instance), for remarks, which will look like this:

--This line, and those below, will be ignored--

M    simulation/fun.f90

Up to this point, only the local copy of "fun.f90" has changed. After you save the file, the modified file "fun.f90" will be dropped to the repository.

If you quit from editing the file, nothing will be changed in the repository.

When Working on Different Computers

Suppose you have done some development on your laptop and you have saved your files in the repository, and now you are on a different computer and you want to "copy" those files. What you should do is to retrieve the files from the repository - to "check out" changes - rather than copy files directly from your laptop.

To retrieve files from the repository, see the descriptions above.

Now suppose you have two copies of a project, say, projectX, on both your laptop and SHARCNET system, and you will alternate to work on both. Assume you have made changes on your laptop and saved in the repository and now you are on a SHARCNET system. The first thing you should do is to update the local copy of projectX by running command

svn update

so that the files in it are up to date before you start working on local files. The logic here is you want to work on the files that you have just modified on another computer.

After you finish your work on a computer, it is strongly recommended that you save the changes to the repository - to "check in" the changes - by running command

svn commit

Listing Revisions of A File

Suppose you have a source Fortran source file simula.f90. Along the way of development, you have made a number of major and minor changes. To show the revision history of this file, use command

 svn log simula.f90

The following is the output, with revision logs separated by dash lines.

 r30 | bge | 2010-02-18 13:05:26 -0500 (Thu, 18 Feb 2010) | 2 lines
 Added use parameters.
 r27 | bge | 2009-11-30 00:40:50 -0500 (Mon, 30 Nov 2009) | 2 lines
 Fixed a bug that caused FPE: a(i)/b(i-1) should be a(i)/b{i).
 r24 | bge | 2009-11-05 01:26:40 -0500 (Thu, 05 Nov 2009) | 2 lines
 Checked in a working version.

Note that revision numbers in Subversion are not per file, but for the entire repository. So for two consecutive revisions of a file, there could be a big difference between the revision numbers.

Getting An Old Revision of A File

In a working directory, you can retrieve a versioned file, say, foo from the repository using command

svn update foo

This will place the latest version of foo in the working directory.

Sometimes, if you want to "roll back" to a previous version, for example, set back two revisions from revision 30 to revision 24 as shown in "Listing Revisions of A File", you may use the -r or --revision option

svn update -r 24 foo

This will synchronize the current working copy of foo to revision 24, thus you obtain a copy of an older version of foo.

Further Reading

  • Manual pages for SVN (available on any cluster using the following command: man svn)
  • Subversion FAQ