6    Revision Control: Managing Source Files with RCS or SCCS

This chapter describes how to keep your program or documentation source files well organized by using a version control system. A version control system automates the storage, retrieval, logging, identification, and merging of document revisions. Version control is most useful for text that is revised frequently, such as programs, documentation, graphics, papers, and so on. The Digital UNIX operating system provides the following two version control systems with slightly different features:

• Revision Control System (RCS)

• Source Code Control System (SCCS)

This chapter introduces basic version control concepts, describes how to use the RCS and SCCS commands and utilities, and provides more advanced information about using each system. Examples in this chapter describe a hypothetical kit for a product called "Orpheus Authoring Tools." The example kit is considered to be one of several Orpheus products. Because this particular kit is a document builder, the kit name is abbreviated as DCB and the main project directory is dcb_tools.

6.1    Overview of Revision Control

Using the Revision Control System (RCS) or the Source Code Control System (SCCS) lets you keep your source files in a common library and maintain control over them. Both systems provide easy-to-use, command-line interfaces. Knowing the basic commands lets you check in the source file to be modified into a version control file that contains all of the revisions of that source file. When you want to check out a version control file for editing, the system retrieves the revision or revisions you specify from the library and creates a working file for you to use.

Using more advanced interface commands lets you do the following:

• Identify the current status of any file, including the name of the person editing it.

• Reconstruct earlier versions of your files. For each version, the system stores the changes made to produce that version, the name of the person making the changes, and the reasons for the changes.

• Prevent the problems that can occur when two people change a file at the same time without each other's knowledge.

• Maintain multiple branch versions of your files. Branched versions can be merged back into the original sequence if desired.

• Protect files from unauthorized modification.

• RCS also allows for release and configuration control. Revisions can be assigned symbolic names and marked according to the "state" of the file (for example, released, stable, experimental, and so on).

Depending on your development environment and unique revision control requirements, you can select either RCS or SCCS as your version control system. Your choice depends on the amount of security and versatility you require. Table 6-1 summarizes some of the more widely used features of each system. docroff: ignoring superfluous symbol sccs_rcs_features

Table 6-1: Features of RCS and SCCS

6.2    Version Control Concepts

RCS and SCCS store files in a reserved directory, called a version control library. The contents of each source file are stored as a single version control file (called an RCS-file in RCS or an s-file in SCCS). A version control file contains the original file (called a g-file in SCCS) together with all the changes, or deltas, that have been applied to it. Each delta is described by text telling who made the change and why. The change information itself is stored in the form of marked lines of text. Every line that is deleted or changed is marked as deleted but is not actually removed. New lines can be either edited versions of old lines or completely new material inserted at the appropriate places and marked. Your version control system can reconstruct any version of the file by applying all the deletions and additions for versions up to the desired version and by ignoring all later versions.

In RCS, RCS-files are identified by the suffix ,v added to their names; for example, attr,v would be the RCS-file for the source file named attr.

In SCCS, s-files are identified by the prefix s. added to their names; for example, s.attr would be the s-file for the source file named attr. Figure 6-1 illustrates the contents of a typical version control file. RCS and SCCS files contain the same kinds of information, but their organization is different.

Figure 6-1: Contents of a Version Control File

A version identification number is applied to a particular revision of the version control file. In SCCS, this number is called an SID. The identification number for SCCS can contain up to four elements; RCS provides for additional elements. The first two elements are the release number and the level number within that release, and the third and fourth represent the same items of information (called the branch and the sequence) for a branched version of the file. (See Section 6.3.) Release identification numbers begin at 1. Level identification numbers within a release begin at .1 and advance by .1, so that the first version of a file is 1.1, the second version is 1.2, and so on. Figure 6-4 (in Section 6.3) illustrates the numbering sequence for one file's deltas.

A version control library is a directory in which all the version control files for a given project are stored. When you retrieve a file from the library, both RCS and SCCS provide a locking mechanism that prevents two people from accessing the file at the same time. File locking is discussed in detail in the following sections.

Usually, but not always, the library is given the name RCS or SCCS, depending on the system you use. Figure 6-2 and Figure 6-3 illustrate how a project's directory tree might appear with the RCS or SCCS library placed below the project's main directory.

Figure 6-2: A Typical RCS Library

Figure 6-2 shows three RCS-files. When a file is checked out of the library for editing, RCS correlates all the deltas and delivers a copy of the specified version, as illustrated here with the attr file. RCS also edits the RCS-file to insert the name of the person checking out the file. This information is stored in the $Locker$ keyword. See Section 6.5.2 for more information about using keywords in RCS.

RCS differs from SCCS in that file locking is enforced at checkin time. A file can be checked out by more than one person, but only the first person to check it out (the one holding the lock) can check it back in to the library. Even if a revision is locked, it can still be checked out for reading, compiling, and so on. Locking ensures that only one developer at a time can check in the next update of the file. In other words, locking prevents a checkin by anybody but the locker (the first person to check out the file).

If your RCS-file is private and you will be the only person making revisions to it, you can turn off the strict locking feature of RCS. When a file is checked back in, RCS removes the user's name from the $Locker$ keyword. If strict locking is turned off, the owner of the file does not need to have a lock for checkin, but all others do. Use the following commands to turn strict locking off and on:

%  rcs -U filename

and

%  rcs -L filename

For more detailed information on file locking, refer to Section 6.5.3, Section 6.5.5, and the co(1) reference page.

Figure 6-3: A Typical SCCS Library

Figure 6-3 shows three s-files and one other file, named p.attr, in the SCCS library. When a file is checked out of the library for editing, SCCS correlates all the deltas and delivers a copy of the specified version, as illustrated here with the attr file. SCCS also creates a lock file, called a p-file. If another person tries to check out the same file for editing, SCCS reports that the file is being edited and refuses to give access to the second person. A p-file has the letter p added as a prefix to its name. When a file is checked back in to the library, SCCS removes the p-file.

6.3    Managing Multiple Versions of Files

Usually, file versions progress in a straight line, with only one current version. In this case, file identification numbers contain two elements and progress by steps of .1, so that the first version number applied to a file is 1.1 and the eighth, for example, is 1.8.

Projects running in parallel to develop new versions of the same basic program can use the same version control file. As the different versions are put into the library, a tree develops. For example, suppose two teams begin development on separate versions of a file or module, starting from the most recent revision.

As the two development streams continue, a complex tree of deltas can be created, as illustrated in Figure 6-4.

Figure 6-4: A Version Control File's Tree of Deltas

To get or edit a file from one of the branches, you must specify its branch number. Figure 6-4 shows a tree for a version control file that consists of a main trunk (contains revisions numbers 1.1, 1.2, 1.3, and so on) and branches. For the delta numbers shown, the first two elements reflect the version number from which it is branched, and the second two elements reflect the new element's version number.

As an example, suppose the two development teams are working with revision number 1.2 of a file. Both RCS and SCCS will allocate a number of 1.3 to the first team to access the file. For the second team, the version control system will create a delta numbered 1.2.1.1. Because this is the first delta along this 1.2 branch, the last two elements of this version number are shown as 1.1.

As the two versions are developed, they can themselves be branched from; for example, a programmer might branch a new file from revision number 1.2.1.3 after revision number 1.2.1.4 has been created.

For more information and specific examples on branching in RCS and SCCS, see Section 6.5.5 and Section 6.6.5.

6.4    Creating a Version Control Library

Once you have selected the version control system you want to use for your development project, you should create a directory in which you will place the RCS or SCCS files. Depending on the size and complexity of your development project, you might want to involve your system administrator, who can help you determine ownership and protection settings for the directory and source files.

When setting up your directory, you might want to assign ownership of the directory to the rcs or sccs user ID and set its permissions to prevent users other than rcs or sccs from writing to it. This method provides good security in that only RCS or SCCS can directly manipulate the files in the library.

If you are going to use the sccs command, the library's directory should be named SCCS, as illustrated in Figure 6-3. If the library directory is not named SCCS, you must use the -d option with the sccs command to access files in the library. (See Table 6-8.) For RCS, the directory should be named RCS; otherwise, you must specify a complete path (absolute or relative) to the RCS-file.

6.5    Using RCS

The RCS system provides a set of UNIX commands that assist in the task of version control for your text files. It is designed for both production and development environments where flexibility and file access control are high priorities. In production environments, access controls can detect update conflicts and prevent overlapping changes. In fast-changing development environments, where such strong controls may not be appropriate, users can easily modify the controls to suit individual project needs.

The RCS system comprises a set of independent commands. Table 6-2 lists the RCS commands provided with Digital UNIX. The sections following the table provide more information on some of these commands. Refer to the appropriate reference page for additional information on the available command options.

Table 6-2: Summary of RCS Command Functions

6.5.1    Placing New Files in an RCS Library

You can use the ci command to place new files in a library. The following example assumes that you are in the library's parent directory and want to add the attr file to the library:

%  ci attr

RCS/attr,v  <---- attr
initial revision: 1.1
enter description, terminate with ^D or '.':
>> Orpheus Authoring Tools attr command
>>^D
done

The ci command creates the RCS-file attr,v and stores attr in it as revision 1.1. The command prompts you for a description, which should be a synopsis of the contents of the file. All later checkin commands will prompt you for a log entry, which should summarize the changes you made.

You can enter a series of files in a single operation. For example:

%  ci attr docbld dcb.ch-intro

6.5.2    Recording File-Indentification Information with RCS

The RCS system provides a syntax for including keywords or ID markers in source files to provide file-identification information. An ID marker consists of a keyword enclosed within dollar signs ($). When you retrieve a file from the RCS library, RCS expands the keyword by replacing it with the appropriate information, such as the file name or revision number.

RCS lets you use keyword markers anywhere in your file as literal strings or comments to identify a revision. For example, if you place the marker $Header$ into your text file, RCS (with the co command) will replace this keyword with the following information:

$Header: filename revision_number date time author state$

Table 6-3 lists the RCS keywords and their corresponding values.

Table 6-3: RCS ID Keywords

The ident command finds and extracts keywords from any file, even object files and dumps. It searches the files you specify for all occurrences of the pattern $keyword:...$. For example, suppose the C program myfile.c contains the following information:

char resid [] = "$Header: Header information$"

The command ident will print the following:

myfile.c : $Header: Header information$

For more detailed information on using keywords in RCS, refer to the co(1) reference page.

6.5.3    Getting Files from an RCS Library

To retrieve a file revision from an RCS-file, check it out of the RCS library by using the co command. The co command retrieves a revision from the RCS-file and stores it in a corresponding working file.

Revisions of an RCS-file can be checked out locked or unlocked. Locking a revision prevents overlapping updates. When you check out a file for reasons other than editing (reading or processing, for example), the revision need not be locked. (A revision checked out for editing and later checkin must normally be locked.) For example:

%  cd /usr/projects/dcb_tools
%  co -u attr

RCS/attr,v ----> attr
revision 1.6 (unlocked)
done

This command creates a copy of the most recent version of the RCS-file (with keyword information included) and places it in your current directory (/usr/projects/dcb_tools in this example). The -u option prevents RCS from locking the file. To get a copy of any earlier version, use the -r option. For example, to retrieve version 1.5 of a file that is now at version 1.8, you would use a command like the following:

%  cd /usr/projects/dcb_tools
%  co -r1.5 attr

RCS/attr,v ----> attr
revision 1.5
done

You can also retrieve a series of files with a single co command. For example:

%  co attr unstamp

RCS/attr,v ----> attr
revision 1.5
done

 

RCS/unstamp,v ----> unstamp
revision 1.2
done

6.5.4    Checking Edited Files Back into an RCS Library

To replace one or more edited files, use the ci command. This command places the contents of each working file in the corresponding RCS-file. Usually, RCS checks whether the revision to be deposited in the library is different from the preceding one, and alerts the user.

Also, because the ci command deletes your working files during checkin, you may want to use either the -l option or the -u option to preserve your working files by performing an implicit checkout operation. This is desirable if you want to save the current revisions and continue editing.

6.5.5    Working with Multiple Versions of Files

Section 6.3 provides an overview of branching concepts in a version control system. The following discussion provides specific examples that illustrate how RCS handles branching of multiple files.

RCS arranges file revisions in a tree of deltas. Each file in a revision tree contains the following kinds of information: a revision number, a checkin time and date, the author's identification, a log entry, a state, and the actual text. All of these file attributes are determined at the time the revision is checked in to the library. The "state" attribute indicates the status of the revision, which is set to "experimental" during checkin, but which can be later changed to "stable" or "released."

The ci command creates a revision tree with a root revision that is usually numbered 1.1. Unless you specify a revision number explicitly, ci assigns new revision numbers by incrementing the level number of the previous revision (1.2, 1.3, 1.4, and so on). To begin a new release, use the following command:

%  ci -r2.1 unstamp

or

%  ci -r2 unstamp

This action assigns the number 2.1 to the new revision. Checking in the file to the library without the -r option automatically assigns the numbers 2.2, 2.3, and so on, to the later revisions of the file.

Suppose two development teams begin development on separate releases of the unstamp command, beginning from revision number 1.2. At this point, both teams can check out the latest revision by using the co command with the -l option as follows:

%  co -l unstamp

After editing the file, the first team can check in the file by using the ci command, and will be alerted by RCS that the new revision number is 1.3. For example:

%  ci unstamp

RCS/unstamp,v  <---- unstamp
new revision 1.3; previous revision 1.2
enter log message:
(terminate with a ^D or single '.')
>> Changed defaults check.
>>^D
done

However, if the second team tries to check in the file with the same action, RCS will issue the following message:

RCS/unstamp,v <----- unstamp
ci error: no lock set by user-name

At this point, the second team can create a branch by using the ci command as follows:

%  ci -r1.3.1 unstamp

This action results in a branch with revision number 1.3.1.1. To continue development along this branch, the second team should use the current branch revision number on all subsequent checkouts of the file. For example:

%  co -r1.3.1.1 unstamp

Creating new branches in RCS is accomplished through the use of the ci command; to continue development along a particular branch, use the -r option with the co command.

The preceding discussion describes how RCS handles revisions of individual files; the system also lets you work with groups (or sets) of files that you specify. See Section 6.5.8 for more information on working with file configurations in RCS.

6.5.6    Displaying Differences in RCS Files

You can examine an RCS-file for differences between versions with the rcsdiff command.

The rcsdiff command runs diff to compare two revisions of each RCS-file given. For example, to find the differences between the latest version of the attr file (1.8, being edited to become 1.9) and the immediately preceding version (1.7), you would use the following command:

%  rcsdiff -r1.7 attr

=====================================
RCS file: RCS/attr,v
retrieving revision 1.7
diff -r1.7 attr
31d30
< # and is version linked to the docbld command

To check the differences between versions 1.3 and 1.4 of the attr file, you would use the following command:

%  rcsdiff -r1.3 -r1.4 attr

====================================
RCS file: RCS/attr,v
retrieving revision 1.3
retrieving revision 1.4
diff -r1.3 -r1.4
5a6
< uts=-04
---
> uts=-05

6.5.7    Reporting Revision Histories of RCS Files

Use the rlog command to examine the revision history of a file. For example, the rlog command provides you with the following detailed information:

%  rlog unstamp

RCS file:        RCS/unstamp,v;  Working file:     unstamp
head:            1.2
branch:
locks:           ;  strict
access list:
symbolic names:
comment leader:  "#  "
total revisions: 2;    selected revisions: 2
description:
unstamp source file
_________________________
revision 1.2
date: 92/06/09 15:51:16;  author:gunther;  state:Exp;  lines
added/del:
Fixed copyright notice
_________________________
revision 1.1
date: 92/06/09 15:49:16;  author:gunther;  state:Exp;
Initial revision

Note the type and amount of information that is available to you using the rlog command. RCS prints the following information for each RCS-file:

• RCS-file name

• Working file name

• Head (the number of the latest revision on the trunk)

• Default branch

• Access list

• Locks on the file

• Symbolic names (if any)

• Suffix

• Total number of revisions

• Number of revisions selected for printing

• Descriptive text

This information is followed by entries for the selected revisions in reverse chronological order for each branch. If entered without specifying options, rlog prints complete information for the file you select. See the rlog(1) reference page for more information on using options to restrict the output of the rlog command.

6.5.8    Configuration Control Concepts

A configuration in RCS refers to a group or set of file revisions, in which each revision comes from a different file revision group. File revisions can be selected (checked out) according to certain criteria. You can check out sets of files from an RCS library based on the following selection criteria:

• Default selection

  You can choose the latest revision of all files by default. For example, the following command retrieves the latest revision on the default branch of each RCS-file in the library:
  

  %  co *,v
  

• Release-based selection

  You can also specify a release or branch number to select the latest revision in that release or branch. For example, the following command retrieves the latest revision with release number 2 from each RCS-file:
  

  %  co -r2 *,v
  

• State and author-based selection

  You can select files according to state attributes. For example, suppose you want to retrieve the latest revision with release number 2 whose state attribute is "Released." This can be accomplished by issuing the following command:
  

  %  co -r2 -sReleased *,v
  

  You can also select a revision by author, by using the -w option.

• Date-based selection

  You can also select revisions by date. Suppose a release of an entire system was completed and current as of June 15, at 2:00 p.m. The following command checks out all files of that release, with the -d option specifying the cutoff date as June 15:
  

  %  co -d "June 15,2:00 pm" *,v
  

• Name-based selection (using symbolic names)

  You can assign symbolic names to revisions and branches. In large systems and development efforts, a single release number or date may not be sufficient to collect all the appropriate revisions from all groups.

  For example, suppose you need to combine release 2 of one subsystem with release 10 of another. Most likely, the creation dates of these revisions will be different, so passing a single revision number or date to the co command will not be appropriate in this case. Using symbolic revision names can help solve this problem; each RCS-file can contain a set of symbolic names that are mapped to the numeric revision numbers.

  For instance, suppose you set the symbolic name IFT2 to release number 2 in the file attr,v and to revision number 10.2 in unstamp,v. In this case, a single co command retrieves the latest revision of release 2 from attr,v and revision 10.2 from unstamp,v as follows:
  

  %  co -rIFT2 attr,v unstamp,v
  

  You can use the rcsfreeze command to assign a symbolic revision name to a set of RCS-files that form a configuration. To assign a unique symbolic revision name to the most recent revision of each RCS-file of the main trunk, use the rcsfreeze command each time a new version is checked in. For more information on assigning symbolic names to RCS-files, refer to the rcsfreeze(1) reference page.

  For large software development efforts, the ability to retrieve all revisions with one command makes configuration management an organized and efficient task.

6.6    Using SCCS

The SCCS system is composed of several independent commands, each of which can be used independently. The sccs command is a unified interface that simplifies the usage of the most common SCCS commands and provides several additional functions by combining the operations of multiple commands. It does not support all of the functions of the individual commands.

Each form of the sccs command includes the keyword sccs and the name of one function, such as edit, followed by options and the names of the file or files to be manipulated. Table 6-4 lists the sccs commands. The sections following the table provide more information on some of these commands. In these discussions, command options are omitted except where required. Commands that are also individual low level commands are indicated in the table. The complete list of individual commands is summarized in Table 6-9; for detailed information on their use, along with descriptions of their options, refer to their individual reference pages.

Table 6-4: Summary of sccs Command Functions

6.6.1    Placing New Files in an SCCS Library

You can use the sccs create command to place new files in a library. The following example assumes that you are in the library's parent directory and want to add the attr file to the library:

%  sccs create attr

attr:
1.1
141 lines

Do not include the prefix s. in the file name you specify; SCCS applies it automatically.

You can enter a series of files in a single operation. For example:

%  sccs create attr docbld dcb.ch-intro

After creating the s-file in the library, the sccs create command adds a comma as a prefix to the name of the original file; for example, attr becomes ,attr. This action preserves the original g-file with its keywords (if any) unexpanded. Then SCCS fetches a copy of the file by using a get command; this fetched version is ready for distribution.

You can also insert files in the library with the sccs admin -i command, using the following syntax:

sccs admin -i [ path/ ] input-file [ path/ ] s-filename

For example:

%  sccs admin -iunstamp unstamp

The name path/input-file specifies the input file. Regardless of the name of this file, the s-file will be named s.s-filename. Do not include any white space between the -i option and path/input-file. Do not include the prefix s. in s-filename; SCCS applies it automatically. Using the admin -i command avoids the renaming of the original g-file and the fetching of a version with expanded keywords. See Section 6.6.8 for more information on using the admin command.

You can use the admin -i option to enter several files with a short shell script; the following command-line example is implemented in csh:

%  foreach x (attr docbld dcb.ch-intro)
?  sccs admin -i$x $x
?  end

6.6.2    Recording File-Identification Information with SCCS

The SCCS system provides a syntax for including ID keywords in source files to provide file-identification information. An ID keyword consists of a single letter enclosed within percent signs (%). When you retrieve a file for any purpose other than editing, SCCS expands each ID keyword by replacing it with the appropriate information, such as the SID or the file name. Table 6-5 lists the SCCS ID keywords.

Table 6-5: SCCS ID Keywords

SCCS handles ID keywords anywhere in a file. The purpose of the SCCS what command is to find and display expanded ID keywords in a file. The what command searches for lines containing the string @(#), which is generated by the %Z% keyword or the %W% shorthand keyword, and displays those lines. For example:

%  what /usr/bin/attr

/usr/bin/attr:
        attr 1.8 of 4/15/92

The line displayed in this example is part of a shell script and was coded as follows:

# SCCSID: %Z%%M% %I% of %G%

If your file does not contain ID keywords, SCCS reports that fact when you put the file in the library and when you retrieve it. You can set the file's i flag to specify that this condition will be a fatal error. (See Section 6.6.8 for a description of file flags.) The purpose of the i flag is to prevent a delta command from merging a g-file with expanded keywords (or with no keywords) with the s-file.

6.6.3    Getting Files from an SCCS Library

There are two reasons to get files from an SCCS library: for any use except editing, such as distribution, or for editing.

You can edit a file as part of the straight-line progress of its version history, or you can create a branching tree. Section 6.6.5 describes how to create a tree wherein multiple parallel versions are stored together in the same s-file.

6.6.3.1    Getting Files for Purposes Other Than Editing

For any use except editing, you get SCCS files with the sccs get command. For example:

%  cd /usr/projects/dcb_tools
%  sccs get attr

1.8
126 lines

This command creates a copy of the most recent version of the s-file with SCCS keywords expanded (see Table 6-5) and places it in your current directory (/usr/projects/dcb_tools in this example). To get a copy of any earlier version, use the -rSID option. For example, to retrieve version 1.5 of a file that is now at version 1.8, you would use a command like the following:

%  cd /usr/projects/dcb_tools
%  sccs get -r1.5 attr

1.5
128 lines

See Section 6.6.5 for information on managing more complex trees of SCCS files.

You can use the -p option to retrieve a file and write it to standard output instead of implicitly creating a g-file with the same name as the s-file. See the get(1) reference page for more information.

6.6.3.2    Getting Files for Editing

To edit a file, check it out of the library with the sccs edit command. For example:

%  sccs edit attr

1.8
new delta 1.9
126 lines

This command creates a copy of the most recent version of the s-file with SCCS keywords unexpanded (see Table 6-5) and places it in your directory for editing. The command also creates a p-file identifying the person who checked out the file for editing.

You can check on the status of files with the sccs info command. For example:

%  sccs info

unstamp: is being edited: 1.4 1.5 gunther 92/09/07 10:42:19

You can also use the get -e command to retrieve a file for editing.

6.6.3.3    Managing Multiple Files and New Releases

You can retrieve a series of files with a single get or edit command. For example:

%  sccs get attr unstamp

SCCS/s.attr:
1.8
126 lines

 

SCCS/s.unstamp:
1.2
55 lines

If you specify the name SCCS instead of one or more file names, SCCS retrieves every s-file in the library.

To create a new release of a file, you fetch it using the -r option to specify the new release number in the sccs edit command. For example, the following command initiates Release 2 of the docbld file:

%  sccs edit -r2 SCCS

SCCS/s.docbld:
1.50
new delta 2.1
1042 lines

 

SCCS/s.dcb_defaults:
1.50
new delta 2.1
63 lines

 

SCCS/s.dcb_diag.sed:
1.50
new delta 2.1
188 lines

6.6.4    Checking Edited Files Back into an SCCS Library

To replace a file in the library you have edited, use the sccs delta command. SCCS prompts you for a comment. For example:

%  sccs delta attr
Comments? (^D to end)
Changed defaults check.  Now looks only for "flc="
[Ctrl/D]

1.9
4 inserted
4 deleted
124 unchanged

If you specify the name SCCS instead of one or more file names, SCCS performs a delta on every s-file in the library. Coupled with a similar edit command, this function is useful for sets of files that must be kept in version synchronization even when not all of them are edited. SCCS asks for comments only once and applies the same comment to each file.

The sccs delget and sccs deledit commands perform a delta followed by a get or an edit operation respectively.

6.6.5    Working with Multiple Versions of Files

Section 6.3 provides an overview of branching concepts in a version control system. The following section provides specific examples that illustrate how SCCS handles branching of multiple versions of files.

Suppose two development teams begin development on separate versions of the unstamp file, beginning from SID 1.2. To enable branching, run the sccs admin -fb command as follows:

%  sccs admin -fb unstamp

The first team uses an edit command to create version 1.3 as follows:

%  sccs edit unstamp

1.2
new delta 1.3
55 lines

The second team uses an edit -b command to create a branch as follows:

%  sccs edit -b unstamp

1.2
new delta 1.2.1.1
55 lines

Consider now a tree for the unstamp file with a main trunk and branches numbered 1.2.1, 1.2.2, and 1.3.1. To get the latest version from branch 1.2.2 for distribution, you would use the following command:

%  sccs get -r1.2.2 unstamp

1.2.2.1
55 lines

As an SCCS tree becomes more complex, ensuring that you have the latest delta for editing can become cumbersome because you must know the delta you want to retrieve. You can use the -t option to the sccs get and sccs edit commands to specify the absolute latest delta regardless of its SID.

You can merge a branched SCCS file back into the main trunk by using the sccs edit -i command and by specifying the version or versions you want to merge. For example, the following command creates version 1.5 of the unstamp command, including all the deltas in the range from 1.2.1.1 to 1.2.1.3. The deltas are correlated so that the result is the accumulation of all specified changes.

%  sccs edit -i1.2.1.1-1.2.1.3 unstamp

Included:
1.2.1.1
1.2.1.2
1.2.1.3
1.4
new delta 1.5
55 lines

6.6.6    Displaying Differences in SCCS Files

You can examine an SCCS file for differences between versions with either the sccs diffs command or the sccsdiff command, depending on what forms of the file are available.

The sccs diffs command compares the g-file with the specified version of the s-file. For example, to find the differences between the latest version of the attr file (1.8, being edited to become 1.9) and the immediately preceding version (1.7) you would use the following command:

%  sccs diffs -r1.7 attr

 

------- attr -------
31d30
< #     and is version-linked to the docbld command

To check the differences between versions 1.3 and 1.4 of the attr file, you would use the following command:

%  sccs sccsdiff -r1.3 -r1.4 SCCS/s.attr

< uts=-04
---
> uts=-05

As this example shows, you can enter a pathname for the s-file itself. Because of this design, you can use this command from any directory instead of having to change to the directory containing the SCCS library.

6.6.7    Reporting Revision Histories of SCCS Files

Use the sccs prs command to examine the revision history of a file. For example:

%  sccs prs unstamp

SCCS/s.unstamp:

 

D 1.2 92/09/20 11:23:36 gunther 2 1      00000/00006/00055  [1]
MRs:                                 [2]
COMMENTS:                                
Fixed copyright notice      

 


 

D 1.1 92/09/19 09:39:11 gunther 1 0      00061/00000/00000
MRs:
COMMENTS:
date and time created 92/09/19 09:39:11 by gunther

The D, MRs, and COMMENTS keywords indicated by callouts in this display are part of the complete set of SCCS keywords. Use the sccs help command to display a list of the keywords and their meanings.

1. The D keyword marks delta information. The two numbers after gunther (the programmer's user name) indicate the new and old revision levels. The slash-separated numbers indicate the numbers of lines added, deleted, and left unchanged. [Return to example]

2. The keyword MRs lists major revisions; the major revision is the first element of a file's SID. [Return to example]

Use the sccs get -m command to retrieve a copy of the file with SID numbers added as a prefix to each line. A file retrieved in this way shows you what delta produced every line in the retrieved version. Keep in mind that a given delta can be overlaid by later deltas; you might need to use the -r option to find particular changes.

6.6.8    Performing Administrative Functions

The sccs admin command performs several administrative functions. Each function is specified by an option to the admin command, as described in Table 6-6.

Note

Your system administrator can set permissions so that only the administrator can use the admin command.

Table 6-6: SCCS admin Command Options

Caution

Using the val and admin -z commands to repair damaged s-files is risky and should be left to your system administrator or to a designated SCCS librarian.

The flags for the admin -f and admin -d options are described in Table 6-7.

Table 6-7: Flags for the admin Command

For example, the following command uses the contents of an existing text file to create an s-file beginning at SID 2.1 and identified with a comment. The s-file's i flag is set. The command places the resulting s-file in the SCCS library under the user's working directory.

%  sccs admin -iunstamp -fi -r2 -y"Initial release" unstamp

This example does not destroy the original file.

6.6.9    Using SCCS Options

The sccs command supports the options listed in Table 6-8. These options must include the SCCS function command keyword as shown in the examples in the table. Do not include any space between the options and their arguments.

Table 6-8: SCCS Command Options

1.8
126 lines

6.6.10    Summary of Individual SCCS Commands

Table 6-9 provides a brief description of the individual SCCS commands. Some of these commands are not supported by the sccs command. Refer to the appropriate command's reference page for more detailed information.

Table 6-9: Individual SCCS Commands

Caution

Using the val and admin -z commands to repair damaged s-files is risky and should be left to your system administrator or to a designated SCCS librarian.

6.7    Functional Comparison of RCS and SCCS Commands

Table 6-10 provides a brief comparison of the operations of RCS and SCCS and the commands that are used to achieve similar functions. Refer to the reference pages for detailed information on using the individual commands.

Table 6-10: Functional Comparison: RCS and SCCS Commands

Tasks	RCS Command	SCCS Commands
Create a new file from your original.	ci file	sccs create file sccs admin -isfile gfile admin -ipath/sfile gfile
Get a copy of a file with expanded keywords.	co -u file	sccs get file get file
Get a copy of a file with unexpanded keywords.		sccs get -k file get -k file
Check out a file.	co -l file	sccs edit file get -e file
Check in an edited file.	ci file	sccs delta file delta file
Show revision histories of a file.	rlog file	sccs prs file prs file
Examine differences between file revisions.	rcsdiff -rrev file	sccs diffs -rrev file sccsdiff -rrev -rrev file
Merge file revisions.	rcsmerge -rrevs file	sccs edit -irevs file
Find identifying information.	ident	sccs what what
Perform administrative tasks.	rcs	admin
Clean up your directory. (Remove unchanged files.)	rcsclean	sccs clean