Retrieve Previous Versions

Source Code Control System (SCCS)
=================================

Introduction
~~~~~~~~~~~~
The Source Code Control System (SCCS) is a tool for controlling changes
to text files.  It is usually used with source code and documentation
of software systems.


SCCS looks after your files for you.  Using it, you can:

o  store, update and retrieve any previous version of a text file;

o  control who is allowed to update a file;

o  identify the version number of a file that has been retrieved;

o  record who made each change, when, where and why.


The problem
~~~~~~~~~~~
Why do we need to retrieve previous versions anyway?  Software
professionals often need to look at an old version of some software,
perhaps to see whether it too had a bug that has been found in the
latest version.  With little files we could keep old versions but there
quickly comes a limit to that.  For instance, my `bu' command only
allows five versions to be kept.  Clearly, with large files and suites
of files, it would be unworkable to keep separate versions of the whole
system.

The solution
~~~~~~~~~~~~
SCCS solves the problem by keeping only the original file and all the
separate sets of changes that have been made to it.  You decide which
version you want and SCCS applies the appropriate sets of changes to
the original file to produce the version you needed.


Since SCCS only looks after text files, it makes use of many of Unix's
text processing tools.  Indeed, some of them are not much use without
SCCS.  For instance the diff command produces editing commands that can
be used to convert one (earlier) file into another (later) version.
Here is typical output from diff showing the differences between `date'
and `date2':

     $ diff date date2
     1c1,3
     < Wed Mar 29 14:42:19 BST 2000
     ---
     > rhubarb
     > Wed March 29 14:42:19 BST 2000
     > Wed Mar 29 14:42:40 BST 2000
     $


Two level interface
~~~~~~~~~~~~~~~~~~~
SCCS is a complex suite of programs.  It can be used most simply with
the `sccs' command; this is an interface to many lower level programs.
Users often simply use the high level interface but sometimes to access
all the power of SCCS, the lower level stuff has to be used.


Starting
~~~~~~~~
Here we set up a one line, dummy C++ program and introduce it to SCCS:

     $ date > dummy.C
     $ echo 'SCCS ID is %I%' >> dummy.C
     $ date >> dummy.C
     $ ls
     dummy.C
     $ sccs create dummy.C
     
     dummy.C:
     1.1
     3 lines
     $ ls -F
     ,dummy.C    SCCS/       dummy.C
     $ ls -l
     total 6
     -rw-------   1 cmsps    cms           73 Mar 31 11:21 ,dummy.C
     drwx------   2 cmsps    cms          512 Mar 31 11:22 SCCS
     -r--------   1 cmsps    cms           73 Mar 31 11:22 dummy.C
     $

As you can see, SCCS has created a directory where it keeps its files.
The original file has been made read-only.  The `,dummy.C' is a backup
version and we can delete it:

     $ rm ,dummy.C
     $

Inside the SCCS directory we have:

     $ ls -l SCCS
     total 2
     -r--------   1 cmsps    cms          223 Mar 31 11:22 s.dummy.C
     $ more SCCS/s.dummy.C
     h12287
     s 00003/00000/00000
     d D 1.1 00/03/31 11:22:01 cmsps 1 0
     c date and time created 00/03/31 11:22:01 by cmsps
     e
     u
     U
     f e 0
     t
     T
     I 1
     Fri Mar 31 11:21:43 BST 2000
     SCCS ID is %I%
     Fri Mar 31 11:21:51 BST 2000
     E 1
     $

The `s.dummy.C' is known as the s-file; it contains the original
version and some housekeeping information.  Later it will also contain
all the updates to the file.

Deltas
~~~~~~
Changes to a file in SCCS custody are known as deltas.  They have
numbers of the form n.m where n is the release number and m is the
level number.  You can see the 1.1 at the start of the s-file.

Now that our file is being looked after by SCCS, we can delete our
version of dummy.C:

     $ rm dummy.C
     rm: remove `dummy.C', overriding mode 0400? y
     $


We can do that because we can get it back from SCCS (along with the
,file) with this:

     $ sccs get dummy.C
     1.1
     3 lines
     $ ls -l
     total 6
     -rw-------   1 cmsps    cms           73 Mar 31 11:21 ,dummy.C
     drwx------   2 cmsps    cms          512 Mar 31 11:22 SCCS
     -r--------   1 cmsps    cms           73 Mar 31 11:25 dummy.C
     $

Keywords
~~~~~~~~
Keywords are values that are put into the source file for the sole
purpose of ending up in the executable so that it can tell users its
name and revision number.  SCCS inserts the correct values for the
keywords by expanding textual place markers when it recreates the
sources.  For instance, `%I%' is replaced with the SCCS delta ID.
Here is the file we just got from SCCS:

     $ more dummy.C
     Fri Mar 31 11:21:43 BST 2000
     SCCS ID is 1.1
     Fri Mar 31 11:21:51 BST 2000
     $

As you see, the ID has been filled in.  If all we wanted to do with the
file was compile it, we could do so and, if were proper C++ or
whatever, the ID would end up in the executable.  SCCS can extract all
the keywords from any executable:

    $ sccs what /usr/ccs/bin/sccs
    /usr/ccs/bin/sccs:
            sccs.c 1.2 2/27/90
            SunOS 5.6 Generic 02/01/97
    $


Getting a file to change it
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The more interesting case arises when we want to edit the file.  To do
so we use:

     $ sccs edit dummy.C
     1.1
     new delta 1.2
     3 lines
     $ ls -l
     total 6
     -rw-------   1 cmsps    cms           73 Mar 31 11:21 ,dummy.C
     drwx------   2 cmsps    cms          512 Mar 31 11:36 SCCS
     -rw-------   1 cmsps    cms           73 Mar 31 11:36 dummy.C
     $

Notice that this time, the file is writable.  Note also that the delta
has increased.


Only one human editor at once
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SCCS is designed for use by teams of people working on large projects.
Obviously, SCCS would not let another team member (or even the same
one) get the file for editing while it is checked out.  Otherwise, one
set of changes would be lost.  For example:

     $ sccs edit dummy.C
     ERROR [SCCS/s.dummy.C]: writable `dummy.C' exists (ge4)
     $


SCCS keeps track
~~~~~~~~~~~~~~~~
Because SCCS has to keep track of what is happening, it can tell us
about files being modified:

     $ sccs check
     dummy.C: being edited: 1.1 1.2 cmsps 00/03/31 11:36:02
     $

Other team members can use the command to find who took the module
out to work on it.


Editing
~~~~~~~
We can now edit the file:

     $ date >> dummy.C
     $

Usually we would make many changes.


How big is a delta?
~~~~~~~~~~~~~~~~~~~
Usually, a delta is many edits.  Enough to change the file, correct the
compilation errors, fix the logic errors and get a new, working, tested
version of the module.  A delta is not just one edit.


Relinquishing control
~~~~~~~~~~~~~~~~~~~~~
When we have finished with the file, we give it back into SCCS's care:

     $ sccs delta dummy.C
     comments? All singin', all dancin'                     
     1.2
     1 inserted
     0 deleted
     3 unchanged
     $

As you would expect SCCS keeps track of what is happening:

     $ sccs info 
     Nothing being edited
     $


Getting an old version
~~~~~~~~~~~~~~~~~~~~~~
Getting an old version is simple, it is done like this:

     $ sccs get -r 1.1 dummy.C
     1.1
     3 lines
     $


Checking the history
~~~~~~~~~~~~~~~~~~~~
Checking the modification history is accomplished thus:

     $ sccs prt dummy.C

     SCCS/s.dummy.C:

     D 1.2   00/03/31 11:38:24 cmsps 2 1     00001/00000/00003
     All singin', all dancin'

     D 1.1   00/03/31 11:22:01 cmsps 1 0     00003/00000/00000
     date and time created 00/03/31 11:22:01 by cmsps
     $

Examining the differences
~~~~~~~~~~~~~~~~~~~~~~~~~
Getting the differences between the version we have and the latest SCCS
version is fairly simple:

     $ sccs diffs dummy.C

     ------- dummy.C -------
     2c2
     < SCCS ID is %I%
     ---
     > SCCS ID is 1.1
     4d3
     < Fri Mar 31 11:38:07 BST 2000
     $

Understanding the differences takes a bit of practice!


We can easily look at the changes between two separate versions:

     $ sccs sccsdiff -r 1.1 -r 1.2 dummy.C
     3a4
     > Fri Mar 31 11:38:07 BST 2000
     $


And we can use the -m and -p options along with grep to see the lines
added in delta 1.2:

     $ sccs get -m -p dummy.C | grep '^1.2'
     1.2
     4 lines
     1.2     Fri Mar 31 11:38:07 BST 2000
     $


Project teams
~~~~~~~~~~~~~
As you would expect with a tool of this nature, it works seamlessly
with make and can be networked.  Make has built-in rules telling it how
to get the latest version of the source code from SCCS.  SCCS also
works seamlessly across a network so that project team members can work
separately but keep one set of source files.


Other facilities
~~~~~~~~~~~~~~~~
You can:

     cancel an edit command.

     cancel and fix a faulty delta.

     "branch" a new version from an old version for an experiment
     that needs a more stable base than the current version.

     merge a branch back into the "main trunk".


So What?
~~~~~~~~
Properly managed software engineering needs good tools.  Modern users
often prefer GUI tools but SCCS is worth knowing as many modern source
code control systems use the same ideas and terminology as SCCS.  And
SCCS does work!