Introduction to Revision Control
Course Handout: (last update 17 March 2010)
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:
- Recognize the neccessity of revision control
- Place individual files under RCS control
- Check out, modify and check-in files
- Place project directories under Subversion control
- Check out, modify, update and commit files and directories under SVN control
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.
Table of Contents
(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
- quickly becomes confusing
- saves every version of a file, not just working or meaningful versions
- uses lots of disk space
(3)
Wouldn't it be nice
if we had a system that
- stored revisions of a file on demand
- stored comments on each revision
- allowed checking out any previous revision
- displayed the differences between any pair of revisions
- manage multiple lines of development
- resolve access conflicts between developers
- automatically identifies compiled programs with embedded revision numbers
- doesn't require changes to the way you edit/compile your files
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)
- Similar goals to SCCS, but open source. Stores differences in a more efficient way
- Still on every Unix/Linux system. Installed on OSX with Xcode tools
- Very mature code
- Strict locking to prevent conflicts
- Great for individual files and small projects
- Doesn't meet the needs of large, distributed projects
CVS (Concurrent Versions System)
- Layered on top of RCS (originally)
- Relaxes strict locking and uses a modify and merge model
- Introduces a client-server model for distributed operation
Subversion (SVN)
- Complete rewrite of CVS, but sticking to the same goals
- Tracks directories, not just files
- Tracks arbitrary metadata
- Repository is a real database
- All access, local or remote, is through the client-server model
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
- Traditional source code for software projects (C, C++, Fortran, Java etc.)
- Makefiles and other configuration files for managing projects
- Shell scripts, perl scripts, python etc.
- Application specific interpreted code: SAS, IDL MATLAB
- System Configuration files
- Access control
- Firewall configuration
- Web server configuration (httpd.conf)
- Database configuration
- Mail server configuration
- System logging configuration
- LaTeX documents
- HTML documents, Style Sheets, Javascript
(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
- Initially Check-in a file to the Revision Control system
- Check-out the file to get a working copy to use (compile, or edit).
By default, you get the most recent version.
- Check-in the file when it is in a state that you decide is worth saving.
- System stores the differences, and optional comments and other tags or state information
- System stores the username and a timestamp
- The new version automatically gets an incremented revision number
- Some systems lock the file on Check-out if you intend to edit the file, otherwise you
get a read-only copy. Merging of changes is normally not needed if locking is used.
- Other systems do not lock files. You modify your working copy, then try to commit
your changes. If the file has been updated by another user while you were working on it, you must
merge your changes
- The files need contain no special content in order to use revision control, but
- it is useful to embed identification tags as comments (in whatever language sytax applies)
- identification tags are dynamically updated on Check-out to reflect the revision state of that copy
- tags can be placed into code as strings to be compiled into the executable
- examples of tags are Revision Number, Author, Date, Source.
- It is possible to check out older versions of a file, make changes, and check in a revision to
that version, so creating a branch to the revision tree.
(8)
RCS - Revision Control System
- Walter Tichy at Purdue, from 1982 onward.
- Very stable code, still in use
- Single file management, with strict locking to guard against conflicting updates
- 8+ commands, but in practice only ci (Check-in) and co (Check-out)
are needed frequently.
- Each controlled file has a corresponding RCS file with the suffix ",v"
- RCS files can live in the same directory, or in an "RCS/" subdirectory (recommended)
- The most recent version of the file is stored verbatim, for fast retrieval. All older
versions are internally stored as reverse deltas.
(9)
The RCS "ci" command
ci
(check-in) is used to
- Initially create the RCS file (prompts for a description of the file)
- Checks in the current working file as the latest revision (prompts for a description of the
changes since the last revision)
- Removes the working copy!
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
- Extract the latest revision of the file and create a new working copy
- Extract any previous revision which exists
- Lock the file and extract a writeable copy for editing. Other users
will be able to check out read-only copies, but not modify or check in
new versions until the lock is released
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
[an error occurred while processing this directive]
(last update 17 March 2010) ©Dartmouth College
http://www.dartmouth.edu/~rc/classes/revision_control