Department of Engineering

Version control

Whether you're working on documentation or programs it's useful to keep previous versions. If you're working in a team, or if you're producing alternative versions, development might branch. Managing all this manually can become tedious and error-prone. Fortunately, several suites of programs are available to help automate the task. Here we'll mention RCS, CVS, GIT, Subversion (SVN) and Mercurial (which are all installed on the teaching system).

RCS

Command-line based. Type "man rcsintro" for an introduction. Here are the edited highlights. Suppose you're working on a file called f.c. Typing

    mkdir  RCS

creates a folder for the rcs commands to use.

    ci  f.c

"checks in" the current version - you'll need to enter a comment. You'll find that f.c disappears. If you want to edit f.c, you "check it out" using

    co  -l  f.c

You can now edit the file. Having changed the file you can type

    rcsdiff  f.c

to see what modifications have been made. Type

    ci  f.c

and you'll see

   new revision: 1.2; previous revision: 1.1

- you'll need to enter another comment. Typing

   rlog f.c

gives a history of changes made. You can make branches, check out earlier versions or even merge 2 branches of development.

CVS

Concurrent Versions System - a development from RCS that supports projects (modules) rather than just individual files, and lets you keep the archive on a distant machine. See http://www.cvshome.org/ for details. In the example here, we'll just use a local repository. The following lines create a directory for CVS to use. A CVSROOT environmental variable is created, which will be used by CVS commands to find the default repository.

mkdir ~/CVS
CVSROOT=~/CVS
export CVSROOT
cvs init

Suppose your source is in a folder called wdir. Then

   cd wdir
   cvs import -m "Imported sources" myprog none start

(the last 2 arguments don't seem to matter much) will create a module called myproj with the "Imported sources" comment attached. If you go to some other directory you can practise some cvs commands.

    cvs checkout myprog 

extracts the files, creating a myprog folder.

    cvs rls myprog

will list the files comprising the myprog module. If you change the files and do

   EDITOR=emacs  cvs commit myprog

it will open emacs so that you can add comments (without the EDITOR=emacs bit it will open an editor called vi). When you've saved comments, you'll see something like

   /homes/users/g/tpl/CVS/myprog/f1.c,v  <--  myprog/f1.c
   new revision: 1.2; previous revision: 1.1
   /homes/users/g/tpl/CVS/myprog/f2.c,v  <--  myprog/f2.c
   new revision: 1.2; previous revision: 1.1

Then

   cvs rlog myprog

will show a list of revisions with comments.

git

git is used by Linux developers. CVS users may want to read git for CVS users . Type git help -a at the command line to get a list of supported commands.

Subversion (SVN)

The original aim of Subversion was to be a replacement for CVS, and it was designed as such. The interface to Subversion is similar to CVS, though subversion has a few notable differences to the way in which it operates:

• Commits are Atomic. Unless all changes can be put in the repository nothing is commited.
• It handles unix like symlinks. Symlinks can be store in the repository useful for releasing from a checkout.
• The revision number of every file is updated on each commit. Helpful when wanting to revert (update) to a particular version.
• Tagging and brancing are 'cheap'. a branch or tag version can be created by 'copying' the files into a suitably named directory
• Concise status command.
• Ability to handle merges. Helpful when there are multiple branches of development.

To set up a repository on the teaching system select a directory on the teaching system where all members of the development group have read/write access (e.g. a project's directory).

Change to this directory, and create a new repository:

you@tsmachine:~>cd /some_project_directory
you@tsmachine:/some_project_directory>mkdir SVN
you@tsmachine:/some_project_directory>svnadmin create SVN

Before working with the repository decide on the repository layout. A possible one is:

projectname/trunk
projectname/branches
projectname/tags

Where projectname/trunk is where the majority of the work is done, branches and tags are to be used to store what they describe.

To import existing files into the repository e.g.

~developer1/ourcode
~developer1/ourcode/bar.c
~developer1/ourcode/foo.c

as the main project source, issue the import command with your new repository as the target e.g.:

you@tsmachine:~>svn import -m"put a commit message here" ~developer1/ourcode file:///some_project_directory/SVN/projectname/trunk/
Adding         bar.c
Adding         foo.c

NB this will not create a directory called 'ourcode' under trunk/; if you wish to do this append 'ourcode' to the end of the target.

To list the contents of the repository issue the list command:

you@tsmachine:~>svn list file:///some_project_directory/SVN/projectname
bar.c
foo.c

Development is done in a seperate directory, possible one drectory for each developer. e.g. ~/sandbox. To work with your files you first need to do a check out:

you@tsmachine:~>mkdir sandbox
you@tsmachine:~>cd sandbox
you@tsmachine:~/sandbox>svn co file:///some_project_directory/SVN/projectname/trunk
A	trunk/bar.c
A	trunk/foo.c

After making changes to a file (e.g. you've just modified foo.c) you can check it in so that others have access: To see which files you have changed view their status:

you@tsmachine:~/sandbox>svn status trunk
M	trunk/foo.c

Then to commit the the changes and supply a check in message:

you@tsmachine:~/sandbox>svn commit -m"some changes were made - fixed bug etc" trunk/foo.c
Sending        trunk/foo.c
Transmitting file data .
Committed revision 2.

Another developer can then see your changes after they do an update of their sandbox:

developer1@tsmachine:~/sandbox>svn update trunk
U	trunk/foo.c
Updated to revision 2.

If this developer had also made changes to this file they may see a conflict:

developer1@tsmachine:~/sandbox>svn update trunk
C	trunk/foo.c
Updated to revision 2.

Here they need to edit the file to resolve the issue.

To view file histories use the log command:

developer1@tsmachine:~/sandbox>svn log trunk

will show a list of revisions with comments. To recover / revert back to a particular version you can call update with the revision number you wish to revert back to e.g.;

developer1@tsmachine:~/sandbox>svn update -r1 trunk

As your sandbox doesn't require constant communication with the repository until you action it (update, commit ...) It also possible for you to work with your sources on a non-teaching system linux machine via ssh. To achieve thei replace file:///some_project_directory/SVN/ with svn+ssh://crsid@tsmachine/some_project_directory/SVN/

A full guide to Subversion can be found here. For further details see: http://subversion.tigris.org/ and CVS to SVN Crossover Guide

Mercurial

Mercurial is command-line-based (the command to use is hg). You may find the Quickstart sheet useful.