bitsccs(1)

NAME

BITSCCS - introduction to the BITMOVER version of SCCS

DESCRIPTION

BITSCCS is a low level interface to revision control. For a higher level interface, please see the bitkeeper(1) man page.

The BITSCCS source control system manages multiple revisions of files. It is modeled after the ATT SCCS system, with features added from RCS, as well as extensions found in neither predecessor. BITSCCS automates the storing, retrieval, logging, identification, and merging of revisions. BITSCCS is useful for text that is revised frequently, for example programs, documentation, HTML files, graphics, papers, and form letters.

The basic user interface is extremely simple, and is identical that of RCS (SCCS commands are supported as well). Only two commands are needed: ci(1) and co(1). ci, short for ``check in'', deposits the contents of a file into an archival file called an SCCS file, or ``s. file''. An SCCS file contains all revisions of a particular file. co, short for ``check out'', retrieves revisions from an SCCS file.

Functions of BITSCCS

=>

Store and retrieve multiple revisions of text. BITSCCS saves all old revisions in a space efficient way. Changes no longer destroy the original, because the previous revisions remain accessible. Revisions can be retrieved according to ranges of revision numbers, symbolic names, dates, authors, and states.

=>

Maintain a complete history of changes. BITSCCS logs all changes automatically. Besides the text of each revision, BITSCCS stores the author, the date and time (including timezone) of check-in, the pathname of the file, the hostname (and domain name) on which the change was made, and a log message summarizing the change. The logging makes it easy to find out what happened to a module, without having to compare source listings or having to track down colleagues.

=>

Maintain a tree of revisions. BITSCCS can maintain separate lines of development for each module. It stores a tree structure that represents the ancestral relationships among revisions. Release 2 of BITSCCS will have expanded support for this feature.

=>

Merge revisions and resolve conflicts. Two separate lines of development of a module can be coalesced by merging. If the revisions to be merged affect the same sections of code, BITSCCS alerts the user about the overlapping changes. The smoosh(1) command is useful for merging.

=>

Control releases and configurations. Revisions can be assigned symbolic names and marked as released, stable, experimental, etc. With these facilities, configurations of modules can be described simply and directly.

=>

Automatically identify each revision with name, revision number, creation time, author, etc. The identification is like a stamp that can be embedded at an appropriate place in the text of a revision. The identification makes it simple to determine which revisions of which modules make up a given configuration. With the addition of hostnames and pathnames, each revision is globally unique, a useful feature for distributed source management.

=>

Minimize disk space. BITSCCS needs little extra space for the revisions (only the differences). If intermediate revisions are deleted, the corresponding deltas are compressed accordingly. Release 2 of BITSCCS will support gzip-ed SCCS files for even less disk usage.

Comparison to RCS and SCCS

=>

Features. BITSCCS is a superset of RCS and SCCS. BITSCCS added the RCS features not found in SCCS. Conversion of RCS files to BITSCCS SCCS files loses no information (this includes tags and arbitrarily complex revision histories).

=>

Compatibility BITSCCS is 100% file format compatible with ATT SCCS. New features have been added as new flags; the old SCCS programs quietly ignore, but preserve, new flags. BITSCCS is not file format compatible with RCS, but it is feature compatible. Features such as symbolic tags, file state, etc., have been added to BITSCCS. Re-implementations of the most commonly used RCS commands are also provided.

=>

Performance. One frequently voiced concern is that SCCS is slower than RCS. That was true in ATT SCCS but is not true in BITSCCS. BITSCCS can get any delta in constant time, most recent deltas are extracted in the same time as RCS, and all other deltas are extracted in less time than RCS. However, both tools can perform all operations in less time than it takes to read the file from disk, making the performance differences somewhat meaningless. It is true that RCS can get top of trunk without reading the entire file, resulting in less disk traffic. SCCS reads the entire file because it checksums the entire file before completing any operations. The checksum is used to insure file integrity; RCS has no similar facility.

Getting Started with BITSCCS

Before trying these examples, you will need to reset your path. This is because both the BITSCCS system and the RCS system have commands with the same name. If you are running in Bourne compatible shell, such as bash, then do this

	PATH=/usr/bitsccs:$PATH
	hash -r

If you are using a C compatible shell, such as csh, then do this

	set path = ( /usr/bitsccs $path )
	rehash

Suppose you have a file foo.c that you wish to put under control of BITSCCS. Invoke the check-in command

	ci -i foo.c

This command creates an SCCS directory, creates an SCCS file SCCS/s.foo.c in the SCCS directory, stores foo.c into it as revision 1.1, and deletes foo.c.

Files in the SCCS directory are called SCCS files or . "s. files" (pronounced ``S dot files''; the others are called working files, or . gfiles for ``gotten files.''

If ci complains with the message

	foo.c not checked in, use -i flag.

then you forgot to tell the system that you wanted to create a new SCCS file; retry with the -i flag (i for initialize).

To get back the working file foo.c in the previous example, use the check-out command

	co  foo.c

This command extracts the latest revision from the SCCS file and writes it into foo.c. If you want to edit foo.c, you must lock it as you check it out with the command

	co  \-l  foo.c

You can now edit foo.c. If you had tried to edit foo.c without locking it, your editor should have warned you that the file is read only.

Locking assures that you, and only you, can check in the next update, and avoids nasty problems if several people work on the same file. Even if a revision is locked, it can still be checked out for reading, compiling, etc. All that locking prevents is a "check-in" by anybody but the locker.

Suppose after some editing you want to know what changes that you have made. The command

	diffs  foo.c

tells you the difference between the most recently checked-in version and the working file.

You can check the file back in by invoking

	ci  foo.c

This increments the revision number properly. If ci tells you

	Clean foo.c (no diffs)

then you have tried to check in a file that you didn't modify. If you really wanted a revision with no changes (which is fine), then use the -f flag (the force flag).

On the subject of cleaning, the clean command can be used to clean all files which have been locked but not edited. Just say

	clean

and it will warn about each file that has been modified, but remove the file (and associated lock) for all unchanged files.

Note that clean automatically came up with a list of files to clean, there was no explicit list. All commands in BITSCCS have this feature, see the section below on file name expansion for more details.

To view the revision history of a file, try

	prs file

Suppose you have a software product that is ready for alpha testing. You're going to ship this product your customers, and you are going to continue bug fixing, performance enhancements, etc. In order to track problems, you would like to remember which revisions of the files in the alpha. You can mark the files like so

	admin -sAlpha:

That says put the tag Alpha on the highest numbered revision of each file in the SCCS directory. Note that the highest existing revision is used; you almost certainly want to run clean and/or ci before tagging the files.

Once you have tagged the files, you can use the tag just like a revision number. For example, to see what you've done since the alpha, you can say

	diffs -rAlpha

For the SCCS fans out there, the standard SCCS command interfaces are also available. To check in a file, you can use ci but you can also use delta. These two commands do the same thing

	ci foo.c
	delta foo.c

For the most part, the two are just different command line interfaces to the same idea. There are some differences, consult the man pages for more information. In particular, users writing conversion scripts will want to look closely at delta(1) which has extensive support for such problems.

To check out a file using the SCCS command, try

	get foo.c		# same as co foo.c
	get -e foo.c	# same as co -l foo.c

It may seem redundant to have both versions, but the RCS commands are well known, quicker to type, etc. The SCCS commands are frequently built into Makefile rules (and sometimes into the fingers of old time Unix hackers).

Key word expansion

BITSCCS support both SCCS style and RCS style keywords. A keyword is a well known string that is replaced, in an unlocked & checked out file, with some information about the file. Examples include the file name, the date, the author of the revision, the revision number, etc.

Suppose you wanted to have some information in the file like so:

	/*
	 * Version 1.5 of foo.c by lm@bitmover.com
	 */

To do this, lock the file, edit it, and make the comment look like:

	/*
	 * Version %\I% of %\M% by %\@%
	 */

Since RCS is in widespread use, BITSCCS supports RCS keywords. However, to get RCS keywords, the R flag must be set in the SCCS file. You can use admin to set the flag; the conversion tool, rcs2sccs, sets this flag automatically.

A special sort of symbol is frequently added to source code for identification in the field. Typical usage is something like

	static char *what = "%\W%";

which will expand to

	static char *what = "@(#)foo.c	1.1";

in an unlocked file.

There is a command, what(1), that looks through (binary) files for these strings and prints them. This can be useful to get revision information in the field.

To learn more about keywords, consult the get(1) man page for SCCS keywords, and the sccs-co(1) man page for RCS keywords.

File name expansion

All commands in BITSCCS expand file names identically. The complex expansion is the result of trying to support both the ATT SCCS command interface and the more user friendly BITSCCS command interface. ATT SCCS commands insisted that files were specified as s.foo or SCCS/s.foo but never just foo. BITSCCS allows either specification, with foo implying a corresponding SCCS/s.foo.

In the following list of expansion methods, the first one that works is the one that is used, so order is important.

If a directory is specified, and dir/SCCS exists, then the implied list is dir/SCCS/s.*.

If a directory is specified, and dir/SCCS does not exist, then the implied list is dir/s.*.

If no directory and no files are specified, and ./SCCS exists, then the implied list is SCCS/s.*.

If no directory and no files are specified, and ./SCCS does not exist, then the implied list is s.*.

A list of SCCS files is passed through unchanged.

A list of regular files, which have corresponding SCCS/s.files, just converts the file names to s.files.

Note one major difference from ATT SCCS. The original SCCS get command would place the g.file in the current working directory, regardless of the path to the s.file. For example,

	$ get /foo/bar/blech/s.foo

would place the file in ./foo, not /foo/bar/foo. BITSCCS does not follow this convention, the g.files are placed next to the s.files, with one exception: if the s.file is in a SCCS directory, the g.file is placed in the parent directory. That one exception makes most old scripts work. However, the -G option to get can be used to force the name of the g.file to be anything you want.

Certain commands may choose to override the default file name expansion mechanism. One example is the clean(1) command, when used with the -u option which unedits files, even those files with modifications. This is a safety mechanism which can be overridden by explicitly listing the files rather than counting on automatic expansion of s.*, etc.