sccs Subcommands

Checking Files In and Out

The following subcommands are useful when retrieving versions or checking in changes.

Checking Out a File for Editing: sccs edit

To edit a source file, you must check it out first using sccs edit. (The sccs edit command is equivalent to using the -c option to sccs get.)

SCCS responds with the delta ID of the version just retrieved, and the delta ID it assigna when you check in your changes.

$ sccs edit program.c
1.1
new delta 1.2
87

You can then edit it using a text editor. If a writable copy of the file is present, sccs edit issues an error message; it does not overwrite the file if anyone has write access to it.

Checking in a New Version: sccs delta

Having first checked out your file and completed your edits, you can check in the changes using sccs delta.

Checking a file in is also referred to as making a delta. Before checking in your updates, SCCS prompts you for comments. These typically include a brief summary of your changes.

$ sccs delta program.c
comments?

Comments should be meaningful, since you may return to the file one day.

You can extend the comment to an additional input line by preceding the NEWLINE with a backslash:

$ sccs delta program.c
comments? corrected typo in widget(), \ 
null pointer in n_crunch()
1.2
5 inserted 
3 deleted
84 unchanged

SCCS responds by noting the SID of the new version, and the numbers of lines inserted, deleted and unchanged. Changed lines count as lines deleted and inserted. SCCS removes the working copy. You can retrieve a read-only version using sccs get.

Think ahead before checking in a version. Creating deltas after each minor edit can become excessive. On the other hand, leaving files checked out for so long that you forget about them can inconvenience others.

It is important to check in all changed files before compiling or installing a module for general use. A good technique is to:

• Edit the files you need.

• Make all necessary changes and tests.

• Compile and debug the files until you are satisfied.

• Check them in, retrieve read-only copies with get.

• Recompile the module.

Retrieving a Version: sccs get

To get the most recent version of a file, use the command:

sccs get filename

For example:

$ sccs get program.c
1.2
86

retrieves program.c, and reports the version number and the number of lines retrieved. The retrieved copy of program.c has permissions set to read-only.

Do not change this copy of the file, since SCCS does not create a new delta unless the file has been checked out. If you force changes into the retrieved copy, you may lose them the next time someone performs an sccs get or an sccs edit on the file.

Reviewing Pending Changes: sccs diffs

Changes made to a checked-out version, which are not yet checked in, are said to be pending. When editing a file, you can find out what your pending changes are using sccs diffs. The diffs subcommand uses diff(1) to compare your working copy with the most recently checked-in version.

$ sccs diffs program.c
------ program.c ------ 
37c37 
<		      if (((cmd_p - cmd) + 1) == l_lim) { 
--- 
>	      	if (((cmd_p - cmd) - 1) == l_lim) { 

Most of the options to diff can be used. To invoke the -c option to diff, use the -C argument to sccs diffs.

Deleting Pending Changes: sccs unedit

sccs unedit backs out pending changes. This comes in handy if you damage the file while editing it and want to start over. unedit removes the checked-out version, unlocks the history file, and retrieves a read-only copy of the most recent version checked in. After using unedit, it is as if you had not checked out the file at all. To resume editing, use sccs edit to check the file out again. (See also "Repairing a Writable Copy: sccs get -k -G ".)

Combining delta and get: sccs delget

sccs delget combines the actions of delta and get. It checks in your changes and then retrieves a read-only copy of the new version. However, if SCCS encounters an error during the delta, it does not perform the get. When processing a list of file names, delget applies all the deltas it can, and if errors occur, omits all of the get actions.

Combining delta and edit: sccs deledit

sccs deledit performs a delta followed by an edit. You can use this to check in a version and immediately resume editing.

Retrieving a Version by SID: sccs get -r

The -r option allows you to specify the SID to retrieve:

$ sccs get -r1.1 program.c
1.1
87 

Retrieving a Version by Date and Time: sccs get -c

In some cases, you do not know the SID of the delta you want, but you do know the date on (or before) it was checked in. You can retrieve the latest version checked in before a given date and time using the -c option and a date-time argument of the form:

-cyy [mm [dd [hh [mm [ss ]]]]]

For example:

$ sccs get -c880722120000 program.c
1.2
86

retrieves whatever version was current as of July 22, 1988 at 12:00 noon. Trailing fields can be omitted (defaulting to their highest legal value), and punctuation can be inserted in the obvious places; for example, the above line could be written as:

sccs get -c"88/07/22 12:00:00" program.c

---

Note -

Year 2000 issue. SCCS continues to use a two-digit year representation in the date format. Sun has adopted the proposed specification (XCU5) from the X/Open group that states that values of "yy" from 69 through 99 are to be interpreted as 1969 through 1999 respectively, and values of "yy" from 00 through 68 are to be interpreted as 2000 through 2068 respectively.

---

Repairing a Writable Copy: sccs get -k -G

Without checking out a new version, sccs get -k -Gfilename retrieves a writable copy of the text, and places it in the file specified by `-G'. This can be useful when you want to replace or repair a damaged working copy using diff and your editor.

Incorporating Version-Dependent Information by Using ID Keywords

As mentioned above, SCCS allows you to include version-dependent information in a checked-in version through the use of ID keywords. These keywords, which you insert in the file, are automatically replaced by the corresponding information when you check in your changes. SCCS ID keywords take the form:

%C%

where C is an uppercase letter.

For instance, %I% expands to the SID of the most recent delta. %W% includes the filename, the SID, and the unique string @(#) in the file. This string is searched for by the what command in both text and binary files (allowing you to see from which source versions a file or program was built). The %G% keyword expands to the date of the latest delta. Other ID keywords and the strings they expand to are listed in Table 5-1.

---

Note -

Defining a string in this way allows version information to be compiled into the C object file. If you use this technique to put ID keywords into header (.h) files, use a different variable in each header file. This prevents errors from attempts to redefine the (static) variables.

---

To include version dependent information in a C program, use a line such as:

static char SccsId[ ] = "%W%\t%G%";

If the file were named program.c, this line would expand to the following when version 1.2 is retrieved:

static char SccsId[ ] = "@(#)program.c 1.2 08/29/80";

Since the string is defined in the compiled program, this technique allows you to include source-file information within the compiled program, which the what command can report:

$ cd /usr/ucb
$ what sccs 
sccs
sccs.c 1.13 88/02/08 SMI

For shell and similar scripts, you can include ID keywords within comments:

#	%W%		%G% 
.  .  .

If you check in a version containing expanded keywords, the version-dependent information will no longer be updated. To alert you to this situation, SCCS gives you the warning:

No Id Keywords (cm7)

when a get, edit, or create finds no ID keywords.

Making Inquiries

The following subcommands are useful for inquiring about the status of a file or its history.

Seeing Which Version Has Been Retrieved: The what Command

Since SCCS allows you (or others) to retrieve any version in the file history, there is no guarantee that a working copy present in the directory reflects the version you want. The what command scans files for SCCS ID keywords. It also scans binary files for keywords, allowing you to see from which source versions a program was compiled.

$ what program.c program 
program.c:
      program.c 1.1 88/07/05 SMI; 
program: 
     	program.c 1.1 88/07/05 SMI;

In this case, the file contains a working copy of version 1.1.

Determining the Most Recent Version: sccs get -g

To see the SID of the latest delta, you can use sccs get -g:

$ sccs get -g program.c
1.2

In this case, the most recent delta is 1.2. Since this is more recent than the version reflected by what in the example above, you would probably want to use get for the new version.

Determining Who Has a File Checked Out: sccs info

To find out what files are being edited, type:

sccs info

This subcommand displays a list of all the files being edited, along with other information, such as the name of the user who checked out the file. Similarly, you can use

sccs check

which silently returns a non-zero exit status if anything is being edited. This can be used within a makefile to force make(1S) to halt if it should find that a source file is checked out.

If you know that all the files you have checked out are ready to be checked in, you can use the following to process them all:

sccs delta 'sccs tell -u'

tell lists only the names of files being edited, one per line. With the -u option, tell reports only those files checked out to you. If you supply a username as an argument to -u, sccs tell reports only the files checked out to that user.

Displaying Delta Comments: sccs prt

sccs prt produces a listing of the version log, also referred to as the delta table, which includes the SID, time and date of creation, and the name of the user who checked in each version, along with the number of lines inserted, deleted, and unchanged, and the commentary:

$ sccs prt program.c
D 1.2		80/08/29 12:35:31						pers		2	1	00005/00003/00084 
corrected typo in widget(), 
null pointer in n_crunch()

D 1.1		79/02/05 00:19:31						zeno		1	0	00087/00000/00000 
date and time created 80/06/10 00:19:31 by zeno

To display only the most recent entry, use the -y option.

Updating a Delta Comment: sccs cdc

If you forget to include something important in a comment, you can add the missing information using:

sccs cdc -r sid

The delta must be the most recent (or the most recent in its branch, see "Branches "). Also, you must either be the user who checked the delta in, or you must own and have permission to write on both the history file and the SCCS subdirectory. When you use cdc, SCCS prompts for your comments and inserts the new comment you supply:

$ sccs cdc -r1.2 program.c
comments? also taught get_in() to handle control chars

The new commentary, as displayed by prt, looks like this:

$ sccs prt program.c
D 1.2		80/08/29 12:35:31							pers		2	1	00005/00003/00084
also taught get_in() to handle control chars 
*** CHANGED *** 88/08/02 14:54:45 pers
corrected typo in widget(),
null pointer in n_crunch()

D 1.1		79/02/05 00:19:31 						zeno		1	0	00087/00000/00000 
date and time created 80/06/10 00:19:31 by zeno 

Comparing Checked-In Versions: sccs sccsdiff

To compare two checked-in versions, use the following to see the differences between delta 1.1 and delta 1.2.

$ sccs sccsdiff -r1.1 -r1.2 program.c

Displaying the Entire History: sccs get -m -p

If you want to see a listing of all changes made to the file and the delta in which each was made, you can use the -m and -p options to get:

$ sccs get -m -p program.c
1.2 
1.2 #define L_LEN 256 
1.1
1.1 #include <stdio.h>
1.1
.  .  .  
84

To find out what lines are associated with a particular delta, you can pipe the output through grep(1V):

$ sccs get -m -p program.c | grep '^1.2'

You can also use -p by itself to send the retrieved version to the standard output, rather than to the file.

Creating Reports: sccs prs -d

You can use the prs subcommand with the -d dataspec option to derive reports about files under SCCS control. The dataspec argument offers a rich set of data keywords that correspond to portions of the history file. Data keywords take the form:

:X :

and are listed in Table 5-3. There is no limit to the number of times a data keyword can appear in the dataspec argument. A valid dataspec argument is a (quoted) string consisting of text and data keywords. prs replaces each recognized keyword with the appropriate value from the history file.

The format of a data keyword value is either simple, in which case the expanded value is a simple string, or multiline, in which case the expansion includes RETURN characters.

A TAB is specified by `\t' and a RETURN by `\n'.

Here are some examples:

$ sccs prs -d"Users and/or user IDs for :F: are:\n:UN:" program.c 
Users and/or user IDs for s.program.c are:
zeno
pers
$ sccs prs -d"Newest delta for :M:: :I:.  Created :D: by :P:." -r program.c 
Newest delta for program.c: 1.3.  Created 88/07/22 by zeno.

Deleting Committed Changes

Replacing a Delta: sccs fix

Occasionally, a delta is checked in that contains small bugs, such as typographical errors, that need correcting but that do not require entries in the file audit trail. Or, perhaps the comment for a delta is incomplete or in error, even when the text is correct. In either case, you can make additional updates and replace the version log entry for the most recent delta using sccs fix:

$ sccs fix -r 1.2 program.c

This checks out version 1.2 of program.c. When you check the file back in, the current changes replaces delta 1.2 in the history file, and SCCS prompts for a (new) comment. You must supply an SID with -r. Also, the delta that is specified must be a leaf (most recent) delta.

Although the previously-checked-in delta 1.2 is effectively deleted, SCCS retains a record of it, marked as deleted, in the history file.

Before using sccs fix it is a good idea to make a copy of the current version.

Removing a Delta: sccs rmdel

To remove all traces of the most recent delta, you can use the rmdel subcommand. You must specify the SID using -r. In most cases, using fix is preferable to rmdel, since fix preserves a record of "deleted" delta, while rmdel does not (refer to sccs rmdel(1) for more information).

Reverting to an Earlier Version

To retrieve a writable copy of an earlier version, use get -k. This can be useful when you need to back track past several deltas.

To use an earlier delta as the basis for creating a new one:

1. Check out the file as you normally would (using sccs edit).

2. Retrieve a writable copy of an earlier "good" version (giving it a different file name) using get -k:

   sccs get -k -r sid -Goldname filename
   

   The -Goldname filename option specifies the name of the newly retrieved version.

3. Replace the current version with the older "good" version:

   mv oldname filename

4. Check the file back in.

   In some cases, it may be simpler just to exclude certain deltas. Or refer to "Branches " for information on how to use SCCS to manage divergent sets of updates to a file.

Excluding Deltas from a Retrieved Version

Suppose that the changes that were made in delta 1.3 aren't applicable to the next version, 1.4. When you retrieve the file for editing, you can use the -x option to exclude delta 1.3 from the working copy:

$ sccs edit -x1.3 program.c

When you check in delta 1.5, that delta will include the changes made in delta 1.4, but not those from delta 1.3. In fact, you can exclude a list of deltas by supplying a comma-separated list to -x, or a range of deltas, separated with a dash. For example, if you want to exclude 1.3 and 1.4, you could use:

$ sccs edit -x1.3,1.4 program.c

or

$ sccs edit -x1.3-1.4 program.c

In this example SCCS excludes the range of deltas from 1.3 to the current highest delta in release 1:

$ sccs edit -x 1.3-1 program.c

In certain cases when using -x there will be conflicts between versions; for example, it may be necessary to both include and delete a particular line. If this happens, SCCS displays a message listing the range of lines affected. Examine these lines carefully to see if the version SCCS derived is correct.

Since each delta (in the sense of "a set of changes") can be excluded at will, it is most useful to include a related set of changes within each delta.

Combining Versions: sccs comb

The comb subcommand generates a Bourne shell script that, when run, constructs a new history file in which selected deltas are combined or eliminated. This can be useful when disk space is at a premium.

---

Note -

In combining several deltas, the comb-generated script destroys a portion of the file's version log, including comments.

---

The -psid option indicates the oldest delta to preserve in the reconstruction. Another option,

-c sid-list

allows you to specify a list of deltas to include. sid-list is a comma-separated list; you can specify a range between two SIDs by separating them with a dash ('-') in the list. -p and -c are mutually exclusive. The -o option attempts to minimize the number of deltas in the reconstruction.

The -s option produces a script that compares the size of the reconstruction with that of the original. The comparison is given as a percentage of the original the reconstruction would occupy, based on the number of blocks in each.

---

Note -

When using comb, it is a good idea to keep a copy of the original history file on hand. While comb is intended to save disk space, it does not always work. In some cases, it is possible that the resulting history file might be larger than the original.

---

If no options are specified, comb preserves the minimum number of ancestors needed to preserve the changes made so far.