Introduction to Revision Control

Course Handout: (last update Wednesday, 17-Mar-2010 13:37:58 EDT)


These notes may be found at http://www.dartmouth.edu/~rc/classes/revision_control. The online version has many links to additional information and may be more up to date than the printed notes

Introduction to Revision Control

The goals of this class are to enable you to:

Assumptions

It is assumed that you are already familiar with command line tools and editing files in Unix/Linux/OSX environment.

Example commands are shown like this. Output from commands is shown like this
Optional items are shown in brackets, [ like this ]

Some descriptions in these notes have more detail available, and are denoted like this:

More details of this item would appear here. The printed notes include all of the additional information

Permission is granted to download and use these notes and example scripts, as long as all copyright notices are kept intact. Some of the examples are taken from texts or online resources which have granted permission to redistribute.

These notes are updated from time to time. The "development" set of notes are http://northstar-www.dartmouth.edu/~richard/classes/revision_control (Dartmouth only)

Richard Brittain, Dartmouth College.
© 2007 Dartmouth College.

Best viewed with ANY browser Powered by Vi

Table of Contents

1.The Problem
2.Version Control - the filesystem approach
3.Revision Control - the solution
4.Revision Control - some options
5.Uses for Revision Control
6.Revision Control as a backup system
7.Revision Control - general concepts
8.Revision Control - RCS
9.RCS ci command
10.RCS co command
11.RCS keyword substitution
12.RCS Keyword list
13.Other RCS commands
14.Problems with RCS
15.CVS - Concurrent Version System
16.Revision Control with Subversion
17.SVN svn command
18.References

(1)

The typical problem

Does this look familiar ?
-rw-r--r--   1 richard  richard   8172 Sep 19 16:53 simulation.f
-rw-r--r--   1 richard  richard   8172 Sep 19 16:53 #simulation.f#
-rw-r--r--   1 richard  richard   8156 Sep 19 14:38 simulation.f~
-rw-r--r--   1 richard  richard   9312 Sep 17 12:01 simulation.f.old
-rw-r--r--   1 richard  richard   9320 Feb 21  2006 simulation.f.bak
-rw-r--r--   1 richard  richard   8905 Sep 16  2005 simulation.f.orig
-rw-r--r--   1 richard  richard   8678 Dec 13  2006 simulation.f.from-Cornell
Or maybe this ?
-rw-r--r--   1 richard  richard   8172 Sep 19 16:53 simulation.f
-rw-r--r--   1 richard  richard   9312 Sep 17 12:01 simulation.f.2007.09.17
-rw-r--r--   1 richard  richard   9320 Feb 21  2006 simulation.f.2006.02.21

(2)

Version Control - the filesystem approach

Some operating systems have tried to help this problem with versioning filesystems. e.g.
-rw-r--r--   1 richard  richard   8172 Sep 19 16:53 simulation.f;7
-rw-r--r--   1 richard  richard   8172 Sep 19 16:53 simulation.f;6
-rw-r--r--   1 richard  richard   8156 Sep 19 14:38 simulation.f;5
-rw-r--r--   1 richard  richard   9312 Sep 17 12:01 simulation.f;4
-rw-r--r--   1 richard  richard   9320 Feb 21  2006 simulation.f;3
-rw-r--r--   1 richard  richard   8905 Sep 16  2005 simulation.f;2
-rw-r--r--   1 richard  richard   8678 Dec 13  2006 simulation.f;1
This was widely used in DEC's VMS operating system. Emulated versioning filesystems are available for Linux, but in general this doesn't work

(3)

Wouldn't it be nice

if we had a system that

This has been widely available since the 1980s, as both free and commercial software.

So use it

(4)

Some of the players

  • SCCS (Source Code Control System) - AT&T proprietary software, distributed with many commercial versions of Unix

  • RCS (Revision Control System) - Walter Tichy; Purdue University (1985)
  • CVS (Concurrent Versions System)
  • Subversion (SVN)
  • Lots of commercial products too...

    Some of the commercial products are specifically oriented towards source code control and are integrated to some extent with other development tools (editors, compilers, debuggers). This may make them better at managing software projects, but at the cost of loss of generality. The open-source tools discussed here may be used for any text files and so can be used in many contexts.

    (5)

    Possible Uses

    (6)

    Revision Control as a backup system

    Revision control tools are NOT a substitute for a real backup system. However, they are very useful at protecting against human error (user whoopsies) in editing files, and are worth using even if only for that function alone.

    (7)

    General Concepts

    Work flow

    (8)

    RCS - Revision Control System

    (9)

    The RCS "ci" command

    ci (check-in) is used to Some of the frequently used options:
    -u
    Update -- the working file is checked in and a readonly copy is immediately checked out again for use
    -l
    Lock -- the working file is checked in and immediately checked out again as a locked, writeable copy, for further editing.
    -r rev
    Check in the specified rev instead of taking the default next revision number.
    -n Name
    Assigns symbolic name Name to this revision, e.g. "V2 final"

    (10)

    The RCS "co" command

    co (check-out) is used to Some of the frequently used options:
    -l
    Lock -- the working file is checked out writeable, and a lock is placed in the RCS file.
    -rrev
    Check out the specified rev instead of taking the default highest revision number.
    -nName
    Check out the revision named by the symbolic Name
    -ddate
    Check out the revision whose checkin date/time is less than or equal to date. The date can be given in a very flexible format.

    (11)

    RCS keyword substitution

    Strings of the form $keyword$ or $keyword:... are replaced with the form $keyword:value$ when a file is checked out. These are typically placed in comments or literal strings. The format for a "comment" is derived from the syntax of the line containing the keyword -- RCS does not know the syntax of any particular programming language
    e.g.
    Fortran:
      C Fortran program last modified by $Author$ on $Date$
    
      C Fortran program last modified by $Author:richard$ on $Date:2006/02/02 21:38:40$
    $
    

    C/C++:
      /*
       * $Header$
       *
       */
      static char *rcsid="$Header$";
       
      /*
       * $Header: /home/richard/projects/simulation/RCS/main.c,v 1.18 2006/02/02 21:38:40 richard Exp richard $"
       *
       */
       static char *rcsid="$Header: /home/richard/projects/simulation/RCS/main.c,v 1.18 2006/02/02 21:38:40 richard Exp richard $";
    

    Shell, perl etc.:
      #!/bin/sh
      # $Header$
      #
      # Revision history:
      # $Log$
    
      #!/bin/sh
      # $Header: /afs/northstar/ufac/richard/projects/class-web-builder/RCS/buildhtml,v 1.18 2006/02/02 21:38:40 richard Exp richard $
      #
      # Revision history:
      # $Log: buildhtml,v $
      # revision 1.2
      # date: 2003/10/30 17:27:06;  author: richard;  state: Exp;  lines: +9 -69
      # Added processing of  tags with optional material.
      # ----------------------------
      # revision 1.1
      # date: 2003/10/30 17:21:57;  author: richard;  state: Exp;
      # Initial revision
    

    (12)

    RCS keywords

    $Author$
    Login name of the user who checked in the revision
    $Date$
    Timestamp of the checkin of this revision
    $Locker$
    Login name of the user who locked this revision (if locked)
    $Name$
    Symbolc name used to tag this revision
    $RCSfile$
    Name of the RCS file, without path
    $Revision$
    The revision number assigned
    $Source$
    Full pathname of the RCS file
    $State$
    State assigned to this revision (e.g. experimental, stable, released)
    $Header$
    Equivalent to $Source$ $Revision$ $Date$ $Author$ $State$ $Locker$
    $Id$
    Equivalent to $RCSfile$ $Revision$ $Date$ $Author$ $State$ $Locker$
    $Log$
    The log message supplied with the revision when it was checked in. These accumulate to form a revision history, but old log entries are not replaced on each checkout.

    (13)

    Other RCS commands

    rcs
    Change RCS file attributes. Edit the user access list; lock or unlock specific revisions; change locking policy; replace log messages; deletes unwanted revisions
    rlog
    display log messages and other information about RCS files
    rcsdiff
    Compare the current working file to the latest revision in RCS, or compare different revisions in RCS
    ident
    Search for all instances of $keyword: text $ in a file (source or executable)
    rcsmerge
    Incorprate the changes between two revisions of an RCS file into the working file. A warning is given if the files differ in overlapping lines
    rcsclean
    Clean up by unlocking and removing working files which were checked out but not modified.

    (14)

    Problems with RCS

    • All developers need direct access to the RCS files (symlinks work, NFS and AFS work)

    • Unix file permissions apply, in addition to access control lists in the RCS file

    • Group write permission can be tricky to set up

    • Files can still be accidentally overwritten, unless setuid tools are used

    • Makefiles have default rules to check out the latest version from RCS if a source file is missing - but building a consistent older version of a program can sometimes be tricky.

    • No provision to track changes to directories, binary files

    • When there are multiple developers, the strict locking policy quickly becomes burdensome

    (15)

    CVS - Concurrent Version System

    • Layered on top of RCS

    • Relaxes strict locking

    • Multiple developers can modify the same file, and changes are merged on check-in

    • Introduced a client-server model

    • Operations are:
      Check-out
      Get a working copy of one or more files
      Update
      Fetch updated files from the repository, if they have been modified by other developers
      Merge
      Merge your changes with new version if needed (may need manual resolution)
      Commit
      Submit your modified files to the repository (but only if no update is needed)

    • If learning for the first time, skip CVS - use SVN.

    (16)

    Subversion

    • CollabNet, Inc, developed Subversion starting in 2000 as part of a collaboration software suite

    • Had been using CVS, but were hampered by deficiencies in CVS

    • Designed to be very similar to CVS in concept

    • Tracks changes to files and also directories and directory hierarchies

    • Tracks arbitrary metadata

    • Uses a client-server model.
      • local access to Subversion Repository
      • svn:// protocol for client-server operation (can be SSH tunnelled)
      • http:// protocol, layered on top of WebDAV (uses Apache modules)

    • All data are stored in a server database repository

    (17)

    SVN - the "svn" command

    svn is used for all interactions with Subversion in the normal workflow
    svn import directory file:///usr/local/svn/repos/projectname
    Copy an unversioned tree of files into an existing project repository (which must have been created already with svnadmin
    svn checkout file:///usr/local/svn/repos/projectname
    Check out a working copy of the directory tree housed at the named repository (think of it as a virtual filesystem) and place it in the current directory
    svn update
    Bring your working copy into sync with the latest revision in the repository
    svn status
    Show the status of the working copy with respect to the latest revision in the repository
    svn diff
    Show the differences between the working copies and the latest version (retrieved by update). Differences are presented in a format that can by used by patch
    svn commit
    Send all changes to the repository. A log message must be supplied.

    (18)

    References, Resources, Man pages etc.

    Man pages

    The standard man pages for rcs and svn are quite complete, but not easy to learn from.
    • ci RCS Check-in
    • co RCS Check-out
    • rcs RCS administrative functions
    • rcsdiff Show differences between RCS revisions
    • rlog Show RCS revision log
    • ident Show RCS identification tags in source files or executables

    • svn subversion client
    • svnadmin subversion administrative functions

    Published papers

    Books

    Online Resources




    Introduction to Revision Control: Course Handout
    (last update   Wednesday, 17-Mar-2010 13:37:58 EDT)  ©Dartmouth College     http://www.dartmouth.edu/~rc/classes/revision_control