The Project Revision Control System

Introduction

The Project Revision Control System, PRCS, is the front end to a set of tools that (like CVS) provide a way to deal with sets of files and directories as an entity, preserving coherent versions of the entire set.

Abstractly, PRCS presents you ("the user") with the abstraction of named projects that have multiple (project) versions, each of which is a set of files, arranged into a directory subtree. A project is the collection of all project versions of that project. Each project version contains one distinguished file, called the (project) version descriptor, in the top directory of the subtree, which contains a description of the files included in that particular version. For a project named `P', this file has the name `P.prj' (and so is also called a "`.prj' file"). The operations provided allow you to perform the following actions:

In addition, you may add and subtract the files contained in a new project version, or move files from one subdirectory to another by editing the working copy of the `.prj' file before checking in the new version. See section Descriptors.

PRCS keeps all checked-in project versions in a projects repository. See section Repository. At any given time, you fix a prevailing repository by setting the environment variable PRCS_REPOSITORY (which defaults to `$HOME/PRCS'), and do not explicitly mention it in any commands. In general, you should modify the projects repository only with the prcs command or other designated utilities, or the results will be unpredictable.

PRCS uses the approach found in CVS (Concurrent Version System): unlike version control systems such as RCS and SCCS, PRCS locks projects in the repository only while it is actually running (in order to make operations on projects atomic). One simply checks in new versions as desired; the system will warn you if others have made parallel changes to the major version of the project you are working on that may have to be merged with changes you have made.

Where PRCS differs from CVS (and, indeed, other source-code control systems of the author's acquaintance) is in its attempt to provide a particularly simple model to the user. A project is a collection of files, period. Although the current implementation of PRCS actually uses RCS in its implementations, none of the details of RCS are of any consequence to the user.

Acknowledgements

PRCS is somewhat unusual in that I wrote the bulk of this reference manual before implementation started. I am greatly indebted to Josh MacDonald for condensing it from vaporware into real software, and to the Berkeley PATH project and its sponsors for initially paying his way.

Definitions

Emphasized terms within a definition are defined later in this section.

Label
A sequence of characters used as a project name or a major version name. It may consist of any sequence of alphanumeric characters, and characters from
    # % ^ - _ + = : , .
that does not begin with a hyphen, equal-sign, or period.

String constant
A string (sequence) of 0 or more characters enclosed in quotation marks (`"'). The sequence may contain any characters, including format effectors like tabs and newline, as long as any quotation marks and backslashes (`\') in it are stropped with a backslash. For example,

"In DOS, you write this \"C:\\BIN\\FOO\""

Project
A named collection of project versions. The name may be any label.

Project version
(Or version where there is no ambiguity). A directory tree of files. The topmost directory contains a file called the project-version descriptor. Every project version has a version name.

Project repository (or `repository')
A directory containing a collection of project versions each with a unique version name, and possibly some additional administrative information.

Major version name
Part of a version name. See section Version Names and Specifiers.

Minor version name
Part of a version name. See section Version Names and Specifiers.

Version name
A denotation for version within a project. It consists of a major version name and a minor version name, separated by a period. See section Version Names and Specifiers.

Version specifier
A denotation used in the -r argument to various PRCS subcommands to indicate one or more versions of a given project. See section Version Names and Specifiers.

Project-version descriptor
A file containing information about project version. It always has the base name `P.prj', where P is the project name. These files may also be called "descriptors" or "`.prj' files." See section Descriptors.

Working (sub)directory
Working version
Working files
The term "working version" refers to a copy of a project version or to a directory tree of files that are intended to become a project version. The individual files are called working files. The root of a working version's directory structure is called a working directory; it and directories under it are called "working subdirectories." The project version descriptor goes in the working directory.

Ancestor version
Each time a working version of a project is checked in, prcs checkin records a project version from which it was derived (in the Parent-Version attribute of the descriptor). This establishes a chain of project versions, each being a modification of one before. A project version P0 is an ancestor of version P1, if one can reach P0 from P1 by zero or more steps along this chain (thus, P1 is an ancestor of itself). See section Parent-Version and Descends-From attributes.

Keyword
A project version's files may contain instances of PRCS keywords, which prcs checkin replaces with appropriate text depending on the keyword (such as the time and date of checkin, the login of the account that checks in a version of a file, the name of the file, or the name of the project). See section Keywords.

Internal File Identifier (or File Identifier)
A parenthesized string that serves as a unique identifier for a version of a file in the repository. Internal file identifiers are used in the lists of files that appear in project-version descriptors. See section Files attribute.

Basic Use

For an overview of the entire process of project source-code maintenance with PRCS, read the sections below in order. It uses a continuing example of a project called P1.

Creating a repository

Before you can use PRCS at all, you must establish a PRCS repository (a directory). PRCS will create and initialize the repository if it does not exist the first time you attempt to use it. PRCS takes the name of the repository from the environment variable PRCS_REPOSITORY, which must be defined before running PRCS (if undefined, it defaults to `$HOME/PRCS').

For example, to have a repository named `PRCS_FILES' in your home directory, execute

% setenv PRCS_REPOSITORY ~/PRCS_FILES

in the C-shell or

$ export PRCS_REPOSITORY
$ PRCS_REPOSITORY=${HOME2/PRCS_FILES

in the Bourne shell. You may want to put this command into your .cshrc or .profile initialization file. In the rest of this document, we will assume that PRCS_REPOSITORY is properly defined.

When you first run PRCS after having set this environment variable, it will create directory `PRCS_FILES' in your home directory, assuming it does not already exist. If you attempt to run PRCS with PRCS_REPOSITORY set to a directory not in the right format, it will report an error.

Once your repository is established, you should generally be careful not to modify it except through PRCS, except that changing the group, protections, or name of the repository is harmless.

Starting a new project

To create the first version of a completely new project named P1, go to the desired working directory and use the following command:

% prcs checkout P1

Assuming there is no prior project P1, the only result of this command is to create a working file `P1.prj' in the current directory; the projects directory and its contents are not modified. In `P1.prj', you will initially find the following lines:

;; -*- Lisp -*-
(Created-By-Prcs-Version 0 13 8)
(Project-Description "")
(Project-Version P1 0 0)
(Parent-Version -*- -*- -*-)
(Descends-From -*- -*- -*-)
(Version-Log "Empty project.")
(New-Version-Log "")
(Checkin-Time "Sun, 31 Dec 1995 01:54:11 -0700")
(Checkin-Login jmacd)
(Populate-Ignore ())
(Files
; This is a comment.  Fill in files here.
; For example:  (prcs/checkout.cc ())
)

The second line identifies the project version from which these files came: in this case from a version 0.0 of the project named P1. Minor version 0 exists implicitly for every major version of a project; it is empty, containing no files and a standard project descriptor, as shown above. The third line indicates the (in this case, nonexistent) version from which version 0.0 was derived.

Adding files to a project

When you create working files, say main.c and doc/foobar.1, you can add them to the version of P1 you are creating by editing the Files entry of `P1.prj' to look like this:

(Files
  (main.c ())
  (doc/foobar.1 ())
)

The Files list identifies the names of the files as they appear relative to the working directory in which you start. The empty lists after each name contain information indicating where these files came from in the repository; since these are new files, the lists are empty to indicate that your files did not come from the repository, but are new. The information in these lists has a format internal to PRCS, and you need not worry about it. Even though the project descriptor `P1.prj' itself is not explicitly listed in the Files list, it is implicitly considered one of the files in the project.

When you have many files to add to the Files list--as for example when you have an existing directory structure full of files that you wish to bring under version control--it is inconvenient to do so by hand. PRCS can add them for you automatically with the command

% prcs populate P1

which finds all files in the current directory and its subdirectories and adds them to the Files list in `P1.prj'. At this point, you can edit `P1.prj' to remove files that you don't want to save (e.g., compiled object files or backup files).

Adding version commentary

It is a good idea at this point to add some commentary to the `.prj' file before check-in:

(Project-Description "Sample PRCS Project")
(New-Version-Log "checkin main.c and doc/foobar.1")

The Project-Description information, by default, is carried over from version to version of a project (so that you usually won't change it after the first version). The New-Version-Log becomes the Version-Log upon check-in and any old version log from a prior version is deleted. Thus, you may use the Version-Log entries of the checked-in versions for any notes about the reasons for the new version or its contents. You can use use newlines in the string constants used to hold the commentary, and make them arbitrarily long. See section Definitions.

Checking in a version

To check in a new project version of project P1, use the command

% prcs checkin P1

If there is only one `.prj' file in the current directory, you may even leave off the P1 argument. This command looks at the file `P1.prj' to find out the major version of P1 from which the current working files were copied and adds a new minor version to it. In this case, since `P1.prj' records no major version name, PRCS uses the default major version name, `0'. Thus, this check-in will create version 0.1 (minor version 1 of major version 0) of P1. The command prcs checkin modifies `P1.prj', before checking it in, to look something like this:

;; -*- Lisp -*-
(Created-By-Prcs-Version 0 13 8)
(Project-Description "Sample PRCS Project")
(Project-Version P1 0 1)
(Parent-Version P1 0 0)
(Descends-From -*- -*- -*-)
(Version-Log "checkin main.c and doc/foobar.1")
(New-Version-Log "")
(Checkin-Time "Sun, 31 Dec 1995 02:10:24 -0700")
(Checkin-Login jmacd)
(Populate-Ignore ())
(Files
  (main.c (P1/0_main.c 1.1 644))
  (doc/foobar.1 (P1/0_foobar.1 1.1 644))
)

As you can see, PRCS has added the version identification, a timestamp, a record of the account performing the checkin, and some internal identification information about the two files now in the project. It has also changed the New-Version-Log declaration to the Version-Log (which is removed when you modify this version and check-in a new one).

Your working directory now contains copies of the files in version 0.1 of P1. You might now add a new working file, say `header.h', and modify `main.c'. You add the line

  (header.h ())

to the Files list. You will also want to create a New-Version-Log entry and perform another checkin. The new version (0.2) of `P1.prj' might now contain

;; -*- Lisp -*-
(Created-By-Prcs-Version 0 13 8)
(Project-Description "Sample PRCS Project")
(Project-Version P1 0 2)
(Parent-Version P1 0 1)
(Descends-From -*- -*- -*-)
(Version-Log "")
(New-Version-Log "")
(Checkin-Time "Sun, 31 Dec 1995 02:13:00 -0700")
(Checkin-Login jmacd)
(Populate-Ignore ())
(Files
  (main.c (P1/0_main.c 1.2 644))
  (doc/foobar.1 (P1/0_foobar.1 1.1 644))
  (header.h (P1/0_header.h 1.1 644))
)

The files of version 0.2 of P1 have now been saved; you may destroy the working directory and later restore it with prcs checkout.

It is not necessary to check in all your working files. By providing a list of files and directories after the project specifier, you can limit the working files considered to those listed:

% prcs checkin P1 doc

copies only the working files in doc into the new version of P1; for other files listed in `P1.prj', PRCS uses the versions identified by the internal file identifiers in the Files list of `P1.prj'. Thus, if these identifiers are unchanged in your working `P1.prj' file since it was checked out, the same files versions that they identify will be used in the new version of P1 (the working versions, however, may differ in the values of certain keywords. See section Keywords.)

Checking out a version

The command prcs checkout creates working copies of the files (and directories) in a project version, usually rooted in the current working directory. For example,

% prcs checkout -r0.1 P1

checks out version 0.1 (minor version 1 of major version 0) of project P1, creating the subdirectory doc, if needed. If you didn't specify a major version name when you created the project it defaulted to '0' and this is the initial version with no files. You needn't be quite so specific in specifying the version:

% prcs checkout -r1 P1
or
% prcs checkout -r1.@ P1

checks out the latest minor version of major version 1 of P1. If you use only numerals for your major versions, you may even leave off the -r altogether to get the latest version checked into the repository.

It is not necessary to check out an entire version at once; you may specify selected directories or files instead. For example

% prcs checkout -r0.2 P1 main.c header.h

checks out just the file main.c from version 0.2 of P1, and

% prcs checkout -r0.1 P1 doc

checks out the doc directory (and all files contained in and below it) from version 0.1 of P1.

Comparing versions

If you have modified a working file, say main.c, and want to see how it differs from the file from which it was checked out, use

% prcs diff P1 main.c

By specifying versions, you can perform other comparisons. To compare the working version of main.c with that in version 0.1:

% prcs diff -r0.1 P1 main.c

To compare main.c in versions 0.1 and 0.3:

% prcs diff -r0.1 -r0.3 P1 main.c

To compare the working version of main.c with the latest in version 0:

% prcs diff -r0.@ P1 main.c

In place of `main.c', you may use any list of files and directories; each will be compared with files from the indicated versions. Mentioning a directory causes comparison of all files under that directory. Leaving off the file name list (e.g.,

% prcs diff P1
% prcs diff -r0.1 P1
% prcs diff -r0.@ P1

) performs the comparison for all files in the project versions.

The output of prcs diff indicates differences between files, and also cases where a file is present in one version (or working version) but not another.

If you have a working version that you have been modifying, you may have added files to it that are not yet reflected in the project descriptor (`.prj' file). Normally, prcs diff will ignore these files. To get a full comparison, you must first add these additional file names to the working project descriptor (see section Adding files to a project). If you don't really intend to add these files immediately, you can save and restore the original working project descriptor:

% cp P.prj tmp-P.prj
% prcs populate P
% prcs diff
 ... output from diff
% mv tmp-P.prj P.prj

or (if you haven't touched the project descriptor since checking it out), you can simply restore the project descriptor:

% prcs populate P
% prcs diff
 ... output from diff
% prcs checkout P P.prj

Merging into working files

After modifying the working files created by checking out the then-latest version of P1 (1.15, let us say), you may try to check them back in and discover that other minor versions of P1 version 1 have been added since 1.15 (prcs checkin will tell you this, and prcs diff or prcs merge -n will give details).

One way to deal with these differences is to merge the contents of your working files with the new version in the repository:

% prcs merge P1

By default, the checked-in version used by this command is the latest minor revision of the major revision of P1 indicated in your working `.prj' file (for this example, let's say version 1.17). The command prcs merge will prompt you for what action you want to take in cases where there are changes between the latest version and the version from which you checked out the working files.

The merge does not create and check in a new version; it merely updates your working files. It will also update your `P1.prj' file to indicate that it came from the version specified--implicitly or explicitly--by the merge subcommand, and you may perform a check-in as a new version.

Creating a new major version

Successive checkins will produce a sequence of minor versions of the same major version of a project. The major version name is useful for indicating such things as releases of a piece of software or "branches" of a project on which development will proceed independently. To create a new major version, specify it during check-in with the -r option. For example, to convert your working files into the first minor version of a new branch of project P1 called `MyBranch', use the command

% prcs checkin -rMyBranch P1

Modify at will; your modifications will be part of major version `MyBranch', and will be invisible to others using the repository unless they specifically ask for that major version. To merge back into the main branch (or any other), just use `prcs diff' and `prcs merge', as above:

% prcs merge -r0.@ P1

To copy an entire checked-in version into a new major version, use a sequence of commands like the following.

% prcs checkout -r0.@ P1 P1.prj
% prcs checkin -r1 P1 P1.prj

Only the project-version descriptor actually gets checked out and in. Because the file list for `P1.prj' remains unchanged, the two versions share all the same files (except for those files that contain certain keywords. See section Keywords.)

Summary of really basic use

The simplest possible use of PRCS is just to use it to keep a single thread of project versions, thus allowing you to "roll back" at any time, and allowing multiple people to do maintenance on a single system simultaneously.

To start things off with a new project, P1, type

% prcs checkout P1

in the working directory where you are developing your project. (If you haven't yet established a repository, PRCS will create one.) If the project was already underway before you created a PRCS project for it, you will probably want to start off by bringing your existing files under version control. To do so, type

% prcs populate P1

Edit the file `P1.prj' to remove any files you don't want to control (like `.o' files, back-up files, and executables). You can also specify the list of files "in the population" on the command line. The files in any directories in this list will be included recursively. In effect, specifying no files is equivalent to specifying "." (the current directory).

% prcs populate P1 file1 file2

Whenever you want to checkpoint your project, type

% prcs checkin

from the root working directory (the one with `P1.prj' in it). If someone else has checked in files in the meantime, you will be notified of discrepancies, which you can handle by typing

% prcs merge

from the root working directory and (after it's done), editing the files.

Whenever it comes time to begin working on a deposited version of the project, you can go to a clean directory and check out the latest version with

% prcs checkout P1

Make your modifications and check back in as before.

Running PRCS

{Command} prcs subcommand [option ...] operands

First checks for the existence of a PRCS repository, and prompts you to create one if there is none present. If the environment variable PRCS_REPOSITORY is set, it is taken as the name of the repository. Otherwise, PRCS looks for a directory called `PRCS' in your home directory. For descriptions of the possible subcommands, see section Subcommands.

Version Names and Specifiers

Every version in a repository has a version name, which is unique within that version's project. A version name consists of a major version name and a minor version name, separated by a period. The major version name may be any valid label. The minor version name is always a positive integer numeral, without leading 0's. The -r option specifies versions within a project by a version specifier.

A version specifier has a form similar to that of a version name: M.N, where M is a major version name and N is a minor version name. Certain values for M and N have special meanings:

Subcommands

In subcommand descriptions, arguments appearing in square brackets ([]) are optional. An argument followed by `...' indicates "one or more".

Options have both a short form (hyphen followed by one letter) and a long form (introduced by two hyphens). Certain options, defined in the first subsection below, are standard: valid on all commands. Other options are listed with the individual subcommands to which they apply, with their long forms in parentheses.

Specifying Projects

A project operand identifies the name of the project to be acted on (a simple label, denoted P below), the name of the project-version descriptor file (`P.prj'), and a root working directory (denoted D below). In the usual case, project is just the name of a project (a simple label), in which case P is project and D is the current directory (`.'). The full story is as follows:

Some subcommands allow you to omit the project operand. In those cases, it defaults to the current directory (`.'), so that by the preceding rules, there must be a single `.prj' file in the current directory, which then implicitly supplies the project name.

When the directory D determined by these rules is not the current working directory `.', the effect is as follows:

Specifying Files and Directories

The file-or-dir operands restrict a subcommand to operate only on specific files within a project version. Each must be the name of a file or directory in the relevant project version. A directory operand stands for all files under that directory (i.e., in it or, recursively, under its subdirectories). The default file-or-dir operand is the working directory specified by the project operand (see section Specifying Projects). Usually, this is simply the current directory (`.'), specifying everything under the everything under the project directory.

Options

This section collects definitions of options used in PRCS subcommands. Many options have both a short form (e.g., -f) and a GNU-format long form (e.g., --force); in these cases, the long form is listed immediately below the short form. In the descriptions below, a Standard option is one that is legal on all subcommands, and an Option is valid on one or more subcommands.

{Option} {--all}

Used in prcs execute to indicate that the specified command is to be executed just once, with all files as arguments.

{Option} -d

{Long Form} {--delete}

Tells PRCS to perform some optional deletion action. Used by prcs populate to indicate that files that are not present in a working directory are to be removed from the Files list.

{Standard Option} -f

{Long Form} {--force}

Force: resolve what would normally be interactive queries in some fixed way, depending on the subcommand, assuring that PRCS will never use the standard input.

{Option} -F

{Long Form} {--family}

Normally, subcommands that compare files in two versions (diff and merge) use the names of the files to pair up the files. With the `-F' option, these subcommands will pair files up according to the families of their internal file identifiers (See section Files attribute, for a description of internal-file families).

{Standard Option} -h

{Standard Option} -H

{Long Form} {--help}

Prints out help very similar to the contents of this section.

{Option} -i

{Long Form} {--immediate}

Causes certain actions to occur immediately during execution of a command. For prcs uncompress, causes the files in a project to be uncompressed on the spot, rather than incrementally as they are needed.

{Option} -k

{Long Form} {--keywords}

Causes prcs diff to compare keywords, instead of stripping them before comparison.

{Standard Option} -l

{Long Form} {--long-format}

{Standard Option} -L

{Long Form} {--long-long-format}

Various long formats, depending on the subcommand.

{Option} {--match} pattern

Used in prcs execute that the names or options attached to files to be executed must match pattern.

{Standard Option} -n

{Long Form} {--no-action}

Indicates that the command is to report what would happen in the absence of `-n', without changing working files or the repository.

{Option} -N

{Long Form} {--new}

In prcs diff, produces comparisons against empty ("new") files where a file is missing in one of the versions being compared.

{Option} {--not} pattern

Used in prcs execute that the names or options attached to files to be executed must not match pattern.

{Standard Option} -q

{Long Form} {--quiet}

Suppress normal informational messages.

{Option} -p

{Long Form} {--preserve}

Preserve permissions on files that are checked out, ignoring any standard protections the user may have set for newly-created files (as by the file mode creation mask in UNIX).

{Option} {--pre}

Used in prcs execute to indicate that directories are to be listed in pre-order: directory names first, then their non-directory contents, then subdirectories.

{Option} -r version

{Long Form} {--revision=version}

Identifies a version of a project. The version is a version specifier. See section Version Names and Specifiers. The space between `-r' and version is optional.

{Standard Option} -R directory

{Long Form} {--repository=directory}

Use directory as the repository, ignoring the value of the PRCS_REPOSITORY environment variable.

{Option} -u

{Long Form} {--unlink}

When PRCS writes a working file, it generally does so by overwriting any existing file of that name. With this option, however, if the file to be written is a symbolic link, that link is removed and a new file is created. Thus, the file that was orginally linked to is unchanged.

{Standard Option} -v

{Long Form} {--version}

Prints the version of PRCS and exits.

{Option} -z

{Long Form} {--compress}

Indicates that a command should perform (de)compression.

Prcs checkout

{Command} {prcs checkout} [option ...] [project [file-or-dir ...]]

ADDITIONAL OPTIONS: `-r', `-p', `-u'

Create a working copy of a version of the specified files and directories in project rooted in the current directory (creating any subdirectories that don't exist). You may use the option `-r' to select a version. The default major and minor version specifiers are both @.

You will be warned when a check-out would change the contents of an existing working file, and interactively given the choice of replacing the file with the version being checked out, or leaving the existing file alone. Existing working files that do not differ from corresponding project files are not modified (their changed and modified dates do not change). The `-f' option will cause checkout to overwrite all files that differ without asking.

When PRCS overwrites a working file that is a symbolic link, then (unless the :symlink option is specified for that file), it will overwrite the file that the link references, without changing the link itself. With the `-u' option, PRCS will instead remove the link and create a new file.

If a working project-version descriptor for project exists, then the project-version descriptor is treated as an ordinary file for purposes of check-out. A check-out with a non-defaulted file-or-dir list that does not contain the descriptor therefore leaves the descriptor unchanged.

Files that are checked out are restored to the protections recorded for them at check-in time, usually modified (on UNIX systems) by the user's file mode creation mask (see the UNIX manual entry for umask(1)). With the `-p' option, this mask is ignored, and the command restores the files' protections to exactly their state at check-in.

Returns a status code of 0 if all goes well, and non-zero if there are errors.

Prcs populate

{Command} {prcs populate} [option ...] [project [file-or-dir ...]]

ADDITIONAL OPTIONS: `-d'

Add each file in the file-or-dir list to the Files list of the `.prj' file identified by project, without modifying the repository. For each directory in file-or-dir, recursively adds all files in that directory structure (or the directory itself, if it is empty). The file-or-dir operand list defaults to the current directory.

Without the `-d' option, any files already in the Files list remain there unchanged. With `-d', populate will prompt you about removing files from the Files list that are listed there as appearing under one of the directories given in the file-or-dir list, but are not found in the working directory. With `-d' and `-f', it will remove them silently.

For example, suppose the file `P.prj' lists files `C', `D1/A', `D1/B', `D2/A', `D2/B'. Suppose a working directory contains files `A', `D1/B', and `D2/B'. Then the command

prcs populate -d P

would remove files `C', `D1/A', and `D2/A' from the Files list of `P.prj', and add file `A'. For the same initial `P.prj' file, the command

prcs populate -d P D1

would remove `D1/A' from `P.prj', and would add nothing.

New files are added with null internal file identifiers. Populate attempts to fill in the :symlink and :directory options. It also applies a heuristic test to each file added to guess whether it is a non-text file; for each file it judges to be a non-text file, it includes the :no-keywords option for that file (see section Files attribute).

Prcs checkin

{Command} {prcs checkin} [option ...] [project [file-or-dir ...]]

ADDITIONAL OPTIONS: `-r'

Create a new version of the specified project in the repository. Copy all files listed in the Files attribute of the descriptor (`project.prj'), taking those specified in file-or-dir operands and the descriptor itself from the working files. Also, modify the descriptor to reflect the contents of the new version. See section Descriptors.

If file-or-dir arguments are provided, they must name files and directories listed in the Files attribute. Only those working files are checked in; other files listed in the project descriptor are carried over from the file versions listed for them in the Files attribute. It is an error for these other files to have null internal file identifiers in the `.prj' file.

A check-in records the access protection on each file (reading it from the working file). It records symbolic links with the :symlink option and empty directories with a :directory option. You could have, for example, a Files attribute as follows:

(Files
  (empty () :directory)        ; an empty directory
  (pointer () :symlink)        ; a symbolic link
  (realfile () :no-keywords)   ; the only real file in the list
)

PRCS reads the contents of a symbolic link from the link at check-in time. It is thus wise to use relative pathnames inside the project. PRCS issues a warning whenever a symbolic link points to a file not contained in the project. Directories with a :directory option need not be actually empty, but this ensures their creation at checkout. It is an error to have a :no-keywords option in the same file as a :symlink, or :directory option.

The new version will have the latest minor version number for the specified major version. The `-r' option may specify a major version; any minor version specified is ignored. The `-r' option defaults to `-r.@', thus taking the major version from the `.prj' file.

PRCS will warn you if you if the minor version number recorded in the `.prj' file is not the latest for its major version, and will abort the checkin unless the `-f' is present.

Returns a status code of 0 if all goes well, and non-zero if there are errors.

Prcs diff

{Command} {prcs diff} [option ...] [project [file-or-dir ...]] [-- [diff-option ...]]

ADDITIONAL OPTIONS: `-F', `-r' (once or twice), `-k', `-N'

Compare the (partial) contents of two repository versions of a project or of a repository version and a working version. When file-or-dir arguments are present, they restrict comparison to the specified files or subdirectory trees. The project argument may be defaulted if there is a single file with extension `.prj' in the current working directory, in which case PRCS takes its name (without `.prj') as the project name.

The options may specify zero, one, or two versions (using `-r' options). Specifying no `-r' options is equivalent to supplying the single option `-r.', the version from which the current working directory was checked out. A `-r' option that specifies only a major version (leaving off the minor version and its preceding period) implicitly has a minor version of @. When one version specifier is given, the files in the indicated version are compared to the working files. The command's output notes any discrepancies in the contents of identically-named files, or in files present in one version but not the other. Two version specifiers cause the same comparison, but between two checked-in versions of the project.

Normally, diff canonicalizes keyword instances in the files it compares, removing the keyword values and leaving just the keyword name. As a result, two different versions of a file that differ only in their keyword values will compare as equal. The `-k' option causes diff to compare keyword values as well.

If a file is present only in one of the project versions being compared, diff will normally just announce that such a file occurs only in one of the versions. With the `-N' option, it will produce the same output it would if it instead treated the non-existent version as an empty file. This is useful when producing patch files that include new files as well as changed ones. Its effect is essentially the same as that of the same option in GNU diff when it compares directories.

Normally, files in the two versions being compared are paired by their names. When `-F' is specified, the files are instead paired by the internal-file families of the their internal file identifiers (see See section Files attribute, for a description of internal-file families). When this option is present, the names in the file-or-dir operand refer to file names in the first named version when `-r' is listed twice, and to the working version, otherwise.

The diff-options, if provided, are any options acceptable to GNU diff.

Returns a status code of 0 if there were no differences, 1 if there were differences, and 2 if there were problems.

Prcs merge

{Command} {prcs merge} [option ...] [project [file-or-dir ...]]

ADDITIONAL OPTIONS: `-F', `-r', `-u'

Find differences between working files and those of the selected version of project, and (unless `-n' is specified) try to modify the working files to reconcile them. The default major and minor versions are `-r.@'.

More precisely, the comparison takes place between three versions of project: the working version (called PW in what follows), the common version (PC) and the selected version (PS). PW consists of the files listed in the working version of the descriptor and included in the file-or-dir operands, which default to all files listed in the descriptor. PS is the version identified by the (possibly defaulted) `-r' option. If the nearest common ancestor of PS and PW exists, then that is PC (see section Parent-Version and Descends-From attributes). Otherwise, PC is taken to be the empty version with the same major version identifier as PW and minor version number 0.

Normally, the files in the three versions are matched up by name. The `-F' option changes this behavior, and matches up files that have the same internal-file family (see section Files attribute). The names in the file-or-dir option refer to files in version PW.

A prcs merge will report discrepancies and (unless `-n' is specified) take actions as directed. The possible actions are as follows.

n
Do nothing.

a
Add the file from PS to PW.

r
Replace the working file with the file from PS.

d
Delete the file from PW.

m
Merge the file from PS with that from PW, inserting markers into the merged working file to show where the changes in PW (relative to PC) and those in the version from PS overlap. If the file from PC is missing, then an empty file is used for its contents. In general, you will have to edit the working file to resolve the discrepancies. If the versions in PS and PW are identical aside from keyword values, merging has no effect.

?
Print summary of options.

h
Print explanatory help message.

v
View differences between PS, PC, and PW (there is further prompting for which you want compared).

The `-f' option causes default actions to each discrepancy (see below). Otherwise, PRCS will ask the user to specify one of the possible actions. All of the actions except n modify the descriptor, either to remove the file from the Files list, or to modify its internal file identifier to the one from PS.

Like prcs diff, prcs merge canonicalizes files to strip keyword values before comparing them for discrepancies (see section Prcs diff). In the descriptions that follow, saying that files are "equivalent" means that they are identical when canonicalized.

PRCS detects the following discrepancies:

When PRCS overwrites a working file that is a symbolic link, then (unless the :symlink option is specified for that file), it will overwrite the file that the link references, without changing the link itself. With the `-u' option, PRCS will instead remove the link and create a new file.

Prcs rekey

{Command} {prcs rekey} [option ...] [project [file-or-dir ...]]

ADDITIONAL OPTIONS: `-u'

Replace keywords in the selected files, according to the version named in the project file. Files whose contents would not change under keyword substitution are not modified. With the `-n' option, simply reports files that will change as a result of keyword replacement. See section Keywords.

When PRCS overwrites a working file that is a symbolic link, then (unless the :symlink option is specified for that file), it will overwrite the file that the link references, without changing the link itself. With the `-u' option, PRCS will instead remove the link and create a new file.

You can use this command to update keywords in working files after performing a prcs checkin, which does not modify keyword values.

Prcs info

{Command} {prcs info} [option ...] [project [file-or-dir ...]]

ADDITIONAL OPTIONS: `-r'

Print information about versions of the named project. For each version listed, prints the project name, major and minor version identifiers, date and time checked in, and the user who checked in the version. With the `-l' option, also prints out the version logs and each project description. With `-L', also prints out the files constituting the version; the file-or-dir options in this case restrict the files or directories that are listed.

The `-r' option is special in this command in that it may contain any of the shell filename-generation pattern characters defined for the Bourne shell, sh: *, which matches any string of 0 or more characters; ?, which matches any single character; [...], which matches any of the enclosed characters; and [!...], which matches any character except one of the enclosed characters. These special pattern characters must be escaped to get them past the shell. The default for both the major and minor versions is *. The `-r' option is still interpreted as a separate major and minor version; that is, `-rFoo.*' matches `Foo.1', but not `Foo.Bar.1'.

Prcs admin

{Command} {prcs admin} subfunction [option ...] [operand ...]

Perform various administrative subfunctions that generally have no effect on the abstract state of the repository. The available functions are as follows.

{Subfunction} compress [project]

Encourages PRCS to save space in storing the data for project, even at the expense of slower processing. This command may take some time to execute. Interrupting it in the middle is safe, although it may lead to somewhat erratic space-saving behavior.

{Subfunction} uncompress [option] [project]

ADDITIONAL OPTIONS: `-i'

Encourages PRCS to save time in processing commands against project, even at the expense of using more space--perhaps considerably more. With the `-i' option, PRCS will immediately expand the entire representation of project. Without the `-i' option, PRCS will increase its use of space only as needed. If disk space should run out, PRCS will leave the repository in a correct state.

{Subfunction} access [project]

With the optional operand, interactively sets read and write permissions to all versions of project, in the repository, and (on systems that provide it) sets the group to which the files belong. This command allows the owner of a project in a repository to restrict the access that others have to its contents. One can specify that these files may only be read or may not be accessed at all.

Without a project operand, interactively sets read and write permissions to the repository itself, both for members of the repository directory's group, and for all other users. One must have at least read access to the repository to look at or check in any project (in addition to having appropriate access to the project itself). You must have write access to the repository to create new projects in it.

{Subfunction} rebuild [option ...] [project]

Rebuilds internal repository data on project, possibly removing file storage for deleted project versions and verifying the integrity of all project versions. With the `-l' option, reports deletions. Unless there has been damage to the repository, this command generally has no visible effect on the notional contents of the repository.

{Subfunction} init project

Create a new project in the repository containing no (non-empty) versions. Performing a prcs checkout on a non-existent project creates a blank working project descriptor without modifying the repository. The first prcs checkin for that project then creates a new entry in the repository. Normally, no other explicit initialization for the project's entry in the repository is necessary. However, with this method it is impossible to perform a prcs access before the first check-in, because there is no record of the new project in the repository. With prcs init, you can create a repository entry (containing no versions) that you can modify with prcs access.

Printing and Checking the Configuration

{Command} {prcs config}

Print out all compiled-in values and their values, possibly altered by environment variables or command-line arguments. Also verifies that the executables named by $RCS_PATH, or its compiled-in default, are valid and checks their version numbers to see that they are not outdated.

Moving and Copying Projects

Sometimes, it is desirable to package up and move or copy an entire PRCS project, rather than a single version of a project (discussed elsewhere in section Importing Project Versions.) One can move an entire repository using the usual UNIX tools for copying, moving, distributing, and packaging directories. For individual projects, it is preferable to use the package and unpackage subcommands in order to insure that all of PRCS's internal structure is maintained.

{Command} {prcs package} project packagedfile

ADDITIONAL OPTIONS: `-r', `-z'

Creates a plain file named packagedfile, containing all the data in project. A value of `-' for packagedfile denotes the standard output. With `-z', the output file is compressed (in gzip format).

{Command} {prcs unpackage} packagedfile

The project project must not exist in the repository, and the file packagedfile must have been created by prcs package (with or without the `-z' option). Creates project in the repository to be a copy of the project from which packagedfile was created. A value of `-' for packagedfile denotes the standard input. With `-n', it merely reports the name of the project that would be added.

Prcs execute

{Command} {prcs execute} [option ...] [project [file-or-dir ...]] [-- command [arg ...]]

ADDITIONAL OPTIONS: `-r', `--pre', `--all', `--pipe' `--match pattern', `--not pattern'

Execute `command arg ...,' suitably modified as described below, for the name of each file and directory in file-or-dir in the specified version, filtered by any `--match' and `--not' operators as described below. This elaborate command is intended to facilitate efficient, open-ended extension of the functions of PRCS.

With the `--all' option, command is executed once. Otherwise, it is executed once per file name.

The pattern options filter the selected files. To be selected, the entry in the Files attribute for a given file must satisfy the `--match' pattern (if any) and not satisfy the `--not' pattern, if any. Each pattern is a regular expression; an entry satisfies the pattern if either the name or any of the `:' options matches the pattern.

For each execution of command, PRCS first replaces the following strings wherever they appear in command and in each arg:

{2
Replaced by the name of the file. With the `--all' option, replaced by the sequence of all selected file names, separated by "unquoted blanks" (that is, blanks that divide the replacement string into separate arguments).

{options2
Replaced by a string consisting of all colon-options applicable to the file (see section Files attribute), separated by "quoted blanks" (that is, blanks that do not divide the replacement string into separate arguments). Each directory that does not carry a :symlink option is listed with a :directory option, whether or not it appears separately in the Files attribute. With the `--all' option, all of these colon-option strings are concatenated together, with the strings for different files separated by unquoted blanks.

{file2
The name of a file containing the contents of the appropriate version of the file. Unless the internal file identifier is null (which can only happen when there is no `-r' option, so that the working version is specified), this is the name of a temporary file containing a checked-out copy of the appropriate version, which is deleted after command completes. With a null internal file identifier, {file2 is the same as {2. It is the empty string for a directory or a file carrying the :symlink option. With the `--all' option, all of these file names are concatenated together, separated by unquoted blanks.

(In contexts where curly braces are special to your shell, you will have to escape them.) After these substitutions, PRCS invokes command, which must be an executable file. It looks for command in the same directories as the shell (using the PATH environment variable). When `--' and what follows are omitted, they default to

-- /bin/echo {2

which simply echoes the names of all files and directories in the selected version, one per line.

One small glitch: prcs execute uses the current directory in effect when it is invoked as the current directory seen by command. This is true, even when the project operand specifies a subdirectory. For example,

% cd /usr/users/foo
% prcs execute D/P -- pwd

will print `/usr/users/foo' once for each file listed in `/usr/users/foo/D/P.prj', and not `/usr/users/foo/D', as the general description of the project operand might otherwise suggest (see section Specifying Projects).

If the `--pipe' option is present, then the contents of the file (as would be contained in the file named by `{file2') is supplied as the standard input. The `--pipe' and `--all' options are incompatible. Any arg whose replacement contains unquoted blanks (introduced by the `--all' option) is divided at those blanks into separate arguments (even in the case where substitution results in a null string, that null string will be broken out as a separate argument). Each of the resulting arguments, is passed directly to the program specified by command as a single string, with no further processing by any shell.

With the `--all' option, PRCS will invoke command only once. The order of the lists of arguments replacing each pattern in command is consistent, so that, for example, the options for the first file name in the replacement for `{2' is the first string in the replacement for `{options2'. For example, if a project contains the files `A', `B/Q', and `B/R', then

prcs execute --all . -- foo -a{2-b "{options2"

will execute (in effect) the single command

foo -aA B/Q B/R B-b "" "" "" ":directory"

With the `--pre' (for pre-order) option the directory name is listed first, then the non-directory file names within that directory, then the subdirectories and their contents. Otherwise, subdirectories and their contents are listed first, then the names of its non-directory files, then the name of the directory itself.

With `-n', the command prints the commands that will be executed without actually executing them.

Deleting Project Versions

{Command} {prcs delete} `-r' version project

Delete the indicated version of project. It will no longer be possible to retrieve the given version. Therefore, this is a command that you should use very sparingly, if at all.

Deleting a version does not necessarily release the space used by the files it contains, since these may be mentioned in other versions. At various times, PRCS will note what space can actually be released and do so.

Minor version numbers increase monotonically, regardless of deletions, and are never re-used.

Repository

The projects repository is a directory that stores the checked-in copies of some set of projects. You usually specify it to PRCS by setting the PRCS_REPOSITORY environment variable, or by using the `-R' (`--repository') option. It defaults to `$HOME/PRCS'.

The precise contents of the repository--the relationship between the files that appear there and the abstract set of version contents presented by PRCS---is deliberately left undefined. You should not count on it being stable from release to release.

Auxiliary Data

To increase the speed of checkin and other subcommands, PRCS maintains redundant information, both in the repository and in working directories. Specifically, you may find files with names such as `.P.prcs_aux' in your working directory, which contain information that allow PRCS to make a quick, heuristic determination of which files you have modified from their repository versions. It is safe to remove (but not to modify) these auxiliary files.

Descriptors

A project-version descriptor is a file that defines the contents of the project. For project with name P, the project-version descriptor (or just `descriptor') is called `P.prj' and is kept at the root of the project directory tree. When you check in a project, the project descriptor indicates what files need to be included, which have keywords that need to be expanded, and from which previous versions of the those files (if any) the working files were derived. A prcs checkin then creates and checks in an updated descriptor file.

The sections below detail the syntax of the project descriptor file and the standard attribute entries that may appear in it.

Descriptor entry syntax

The syntax of the project descriptor file is slight variant on Lisp. It consists of `S-expressions' (this is the terminology established by Lisp, so we'll use it here). In general, an S-expression has one of the following forms

label
string constant
(s-exprs)

Where `s-exprs' is (recursively) a sequence of 0 or more s-expressions, separated from each other by whitespace and optionally separated from the surrounding parentheses by whitespace (`whitespace' is any non-empty sequence of blanks, tabs, form feeds, and newlines). We've described the syntax of labels and string constants elsewhere (see section Definitions).

You may include comments in the descriptor; these consist of a semicolon (outside of a string) followed by all characters up to and not including the next newline or the end of the file. Comments have no effect on the behavior of PRCS and are copied from one version of a project descriptor to the next.

The non-nested S-expressions that appear in a descriptor (those that aren't part of some larger expression) each start with an attribute name (a label). The valid attribute names are described in the following sections.

Project-Version attribute

{Attribute} Project-Version P M N

This indicates that the descriptor is (or is modified from) the descriptor for version M.N of project P. M must be a valid major version name and N must be a valid minor version name (see section Version Names and Specifiers). The prcs checkin command sets the Project-Version of the checked-in descriptor. See section Version Names and Specifiers.

Project-Description attribute

{Attribute} Project-Description string-constant

This attribute is intended to provide a title or short description of the project. By default, prcs checkin leaves it undisturbed.

For example,

(Project-Description "Sample PRCS Project")

Version-Log and New-Version-Log attributes

{Attribute} Version-Log string-constant

{Attribute} New-Version-Log string-constant

The version log is stored with the descriptor of each version of a project. A prcs checkin initializes it from the New-Version-Log attribute, removing any existing Version-Log attribute, and setting the New-Version-Log to the empty string. The version log is intended to describe the changes made in this version from its predecessor, or to contain other comments about it.

For example,

(Version-Log "Added header.h")
(New-Version-Log "Modified main.c")

Checkin-Time and Checkin-Login attributes

{Attribute} Checkin-Time time-specifier

{Attribute} Checkin-Login label

These attributes record the login of the user performing the PRCS check-in that created this version and the time at which it was performed. They are set by prcs checkin.

For example,

(Checkin-Time "Sun, 12 Jun 1994 20:00:00 -0700")
(Checkin-Login hilfingr)

Files attribute

{Attribute} Files (file1 (internal-file-id1) options1) ...

Each of the 0 or more arguments of the Files attribute denotes one of the constituents of a version. The file arguments give the pathnames of files relative to some root directory. The internal-file-id arguments contain information used by PRCS to identify versions of individual files.

If F is one of the file arguments, then no component of F may be `.' or `..'. Unless one of the options listed for F is :directory (see below), no other file argument in the Files attribute may begin with `F/'.

The precise format of an internal file identifier is not defined, and is subject to change whenever PRCS is revised. Two properties, however, are guaranteed:

The options arguments denote 0 or more labels indicating special properties of the file. At the moment, four are defined.

:no-keywords
indicates that keywords in the file are not to be expanded.

:symlink
indicates the file is a symbolic link, which will be recorded at checkin and reproduced at checkout.

:directory
indicates that the file is a directory, which will be created, if necessary, at checkout. This is useful for having empty directories in your project.

:tag=label
records label as a piece of user-defined information about the file. PRCS does not interpret label; its main use is for filtering in the prcs execute subcommand (see section Prcs execute). There may be any number of :tag options attached to a file.

The project descriptor (`.prj' file) is not explicitly included in the Files attribute. Nevertheless, it is implicitly one of the files in each project version.

For example,

(Files
  (empty () :directory)        ; an empty directory
  (pointer () :symlink)        ; a symbolic link
  (realfile () :no-keywords)   ; the only real file in the list
)

Populate-Ignore attribute

{Attribute} Populate-Ignore (pattern1 ...)

This attribute is used to inform prcs populate of files that it should not add to the Files list of the project descriptor. It is included as a convenience; you can accomplish the same effect by editing the Files list after running populate.

Each of the pattern arguments is a regular expression (as used by grep). Any path name that prcs populate finds that matches one or more pattern arguments is not added to the Files list (existing names on the list are not affected).

For example, the following filters out object (`.o') files, library archive (`.a') files, core files, files generated by TeX, Postscript (`.ps') files that occur in subdirectory `doc', Emacs backup files, and the executable file `a.out':

(Populate-Ignore ("\\.o$" "\\.a$" "~$" "^a.out$" "^core$" 
                  "\\.dvi$" "\\.aux$" "\\.log"
                  "^doc/.*\\.ps"))

Merge-Parents attribute

{Attribute} Merge-Parents (version (file-action) ...) ...

{Attribute} New-Merge-Parents (version (file-action) ...) ...

The prcs merge command uses the New-Merge-Parents attribute to record the history of updates to each file. Each version indicates a selected version that was merged into the working files, and each file-action records what action (delete, add, replace, merge, no action) merge took for each file. This information is useful in preventing confusion when the user interrupts a merge operation and then re-executes the merge. The precise format of the file-actions is unspecified at the moment.

The prcs checkin command copies any New-Merge-Parents attribute in the working project descriptor into a Merge-Parents attribute in the new (checked-in) project descriptor. It discards any existing Merge-Parents attribute in the working file.

Parent-Version and Descends-From attributes

These attributes track the history of a project version, recording the names of one or two versions from which it was derived. They both have the syntax of Project-Version.

{Attribute} Parent-Version P M N

This has the same form as the Project-Version attribute (see section Project-Version attribute), except that for an initial version (unrelated to any prior version), each of P, M, and N is -*-. The Parent-Version defines the ancestors of a version in the repository as follows:

Given two versions in a repository, any version that is an ancestor to both is called a common ancestor. The common ancestor that is least distant from either is called the nearest common ancestor.

Each prcs checkin sets Parent-Version to name one of the versions from which the newly checked-in version is derived. In the usual, simple case, where one checks in a sequence of versions with the same major version name, prcs checkin simply copies the old Project-Version attribute in the working project descriptor (called WV below) to the Parent-Version in the new descriptor.

In the general case, we are checking in a version whose name is to be TV ("target version"). Suppose that TV' is the last minor version with the same major version name as TV. Then,

{Attribute} Descends-From P M N

The Parent-Version attribute records one source for the contents of a version (see section Parent-Version and Descends-From attributes). In some cases, however, this does not tell the entire story. If the Parent-Version (as computed above) differs from WV, then prcs checkin records WV in the Descends-From attribute. Otherwise, it records no Descends-From attribute, or sets a null Descends-From attribute (in which P, M, and N are -*-).

Keywords

Files in a project may contain instances of keywords that (in effect) prcs checkin will replace with certain information. Conceptually, upon checkin, each keyword instance in every file of the project (not just those listed in the checkin subcommand) is updated as described below with the value of its keyword in the new project version. As a performance consideration, however, this is implemented in such a way that partial checkins only have to examine the files that are listed in the checkin subcommand (see section Keywords and File Identifiers).

There are two forms of keyword instance: simple and formatted. A simple keyword instance has one of the forms

$keyword$
$keyword: data$

This syntax is strict: PRCS does not recognize a keyword when there is whitespace on either side (separating it from the dollar sign that precedes it or the dollar sign or colon that follows). There may not be newlines anywhere in the keyword instance. If the keyword is one that PRCS recognizes, other than Format, prcs checkin replaces the instance with an instance of the second form, with the data part depending on the particular keyword. Formatted keyword instances allow a more flexible replacement format.

Recognized Keywords

PRCS understands the following keywords. Others are ignored (their instances are left unchanged). Instances of the Source and ProjectHeader keywords change whenever the file is moved from one directory to another within a project. Instances of Project, ProjectDate, ProjectAuthor, ProjectMajorVersion, ProjectMinorVersion, ProjectVersion, and ProjectHeader can change even when the file containing them does not, since they depend on the project, not the file. These keywords are known collectively as project-related keywords.

Author
The login of the user who created this checked-in version of the file. Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword.

Date
The date and time at which this version of the file was checked in. Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword.

Basename
The base name of the file, as it appears in the Files attribute.

Revision
A notation that serves as a revision number for this file (it is independent of the project's version number, and changes only when the file changes). Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword.

Id
A standard header combining the Basename, Revision, Date, and Author.

Source
The full name of the file, as a pathname relative to the root of the project's directory tree.

Project
The name of the project containing the file version.

ProjectDate
The date and time the project containing this file version was checked in.

ProjectAuthor
The login name of the user who checked in the project version containing this file version.

ProjectMajorVersion
The major version name of the project version containing this file version.

ProjectMinorVersion
The minor version name (a number) of the project version containing this file version.

ProjectVersion
The complete version designator for this project version. It has the form M.N, where M is the major project-version name and N is the minor project-version name.

ProjectHeader
A standard header combining the Project, ProjectVersion, ProjectDate, and ProjectAuthor.

Formatted Keyword Instances

Sometimes, you want keyword replacement data to appear without the leading $keyword: and trailing `$'. A formatted keyword instance allows this. An appearance in your file of

$Format: "string"$
string

will cause prcs checkin to replace the next line of the source file (i.e., the line after the second `$') with string, after first making modified keyword substitutions in it. Specifically, each instance of $keyword$ in string (for which keyword is one of the recognized keywords) is replaced by just the data that would be placed to the right of the `:' in a simple keyword instance. The Format instance itself is not altered--only the subsequent line. For example, if a file in a project contains

/* $Format: "static char* version = \"$ProjectVersion$\";"$ */
static char* version = "x.x";

then the version of the file checked in for version 1.2 of the project will contain

/* $Format: "static char* version = \"$ProjectVersion$\";"$ */
static char* version = "1.2";

The format string may not contain newlines. It may contain quotation marks if they are stropped with a backslash, as in the example above. In general, the backslash quotes the succeeding character. Any keyword instances on a list after a Format instance are ignored (that is, they are left unchanged by keyword substitution). Any nested instance of Format is also left unchanged.

Keywords and File Identifiers

The actual content of a working file upon checkout depends on two things: the internal file identifier recorded for it and the contents of the project descriptor. The internal file identifier designates a particular "raw" file contents stored in the repository that never changes once it is first created. The checked out file consists of this contents modified by keyword replacement. If the same file identifier is used for two files in two different projects, the checked-out working files will differ in the values supplied for these keywords. This is a subtle point, but it is significant when you copy a file identifier from one project to another.

For example, suppose that file F in version 1.2 of project P contains the line

/* $ProjectVersion: 1.2$ */

and that its entry in the Files attribute of P.prj is

    (F (P/0_F 1.1))

If you decide to rename F to G for the next version of P, you can do so by changing its line in the Files attribute to

    (G (P/0_F 1.1))

When you check the project back in, creating version 1.3, this same line will be retained as its file identifier (assuming, that is, you made no changes to G or its former incarnation, F). However, in version 1.3 of P, G will contain

/* $ProjectVersion: 1.3$ */

That is, PRCS actually performs all keyword replacement on check-out (think of it as lazy replacement). It only makes a user-visible difference in the handling of internal identifiers. It also has a considerable effect on the performance of partial checkins (those that contain a list of specific files and directories to check in, and copy all unmentioned files from file identifiers listed in the Files attribute). Because PRCS does not have to examine the files excluded from the file list for keywords, it can process them very quickly.

Subprojects

You can use PRCS to "bundle together" a set of projects (so that they may be released together, for example). Suppose that P is the name you want to give to the (new) combined project, with P1, P2, and P3 the names of the subprojects. To create the initial version of P, take the following steps.

  1. Go into a directory that is to serve as the working directory for P.

  2. Use prcs checkout to create a `.prj' file for P.

  3. For each subproject, Pi, create a subdirectory Pi, and in that subdirectory, execute the command
    % prcs checkout -r... Pi Pi.prj
    
    (replacing `...' with the appropriate version specifier). This checks out the `.prj' file for Pi into Pi.

  4. Modify the Files entry for P to list the `.prj' files for the Pi.

  5. Check in P.

To create a working copy of this version of P (including working copies of all its subprojects' files), use the following (Bourne shell) commands (I'll assume that 0.1 is the version name for P).

$ prcs checkout -r0.1 P
$ for i in P1 P2 P3; do
>   (cd $i; prcs checkout $i)
> done

Obvious modifications of this procedure will serve to create updated versions of P.

With a little care, we can automate this process a bit further. Suppose that we establish a convention that we tag each subproject descriptor file in the Files list of P:

(Files
  ...
  (P1 (...) :tag=project)
  (P2 (...) :tag=project)
  (P3 (...) :tag=project)
  ...
)

This allows a general-purpose version of the checkout procedure above, one that does not require that we remember the names of all the subprojects:

% prcs execute -r0.1 P --match :tag=project -- prcs checkout {2 

Importing Project Versions

PRCS allows you to create a sequence of project versions out of a sequence of releases of a source directory tree. You may want to do this, for example, if you are installing successive versions of some system imported from elsewhere and wish to be able to retrieve old versions, while still saving space by storing only the changes between successive versions. (See section Moving and Copying Projects, if you want to move or copy an entire project from one repository to another.)

Tracking imported versions

The process is simple. For concreteness, let us use the name P as the project name. For the first imported version, we create P and populate it with the first version of the imported source files. In the directory that contains the imported files, use the commands

% prcs checkout P
% prcs populate P
# Edit P.prj #
% prcs checkin P

The editing of `P.prj' might consist of setting the Project-Description and New-Version-Log attributes, and possibly adding :no-keywords options to some files.

When you receive a new release of P, place it in a directory structure and, at the top directory of that structure, use the commands

% prcs checkout P P.prj
% prcs populate -d P
# Edit P.prj #
% prcs checkin P

With the `-d' option, the prcs populate command will add any new files found in the working directory, but not listed in `P.prj', and will remove any files listed in `P.prj', but not present in the working directory. Again, you will probably want to edit the New-Version-Log attribute.

Imported software sources often have their own version designations, and you may want to have the PRCS major version identifiers include all or part of these designations. Suppose the first such imported release is called 1.0-beta. In the working directory containing this release, you might type

% prcs checkout -r1.0-beta.0 P
% prcs populate P
# Edit P.prj #
% prcs checkin P

On receiving a new release from outside, say 1.1-beta, you would put it under a working directory and, from that directory, issue the commands

% prcs checkout -r1.0-beta. P P.prj
% prcs populate -d P
# Edit P.prj #
% prcs checkin -r1.1-beta. P

Keeping parallel local versions

Sometimes, you will have local modifications or enhancements to a piece of imported software, and want to bring your local version up to date with successive parallel releases of the imported software. To do this, use the procedure above for keeping the imported releases. Put your own local releases in another major version, let's say Local. To start with, you'll use the initial imported release:

% prcs checkout -rV P P.prj
# Edit the project #
% prcs checkin -rLocal P.prj

Here, V is whatever PRCS version number you have assigned to the vendor's (the imported) version. Continue making your local modifications in major revision Local. When a new external release comes in, first make sure the most recent version of your local version is checked in. Then put the new imported version into a fresh directory structure, populate a project file, and check it in as outlined above. For concreteness, let's say that your most recent local version is designated Local.5, and the newly-checked-in imported version is designated Vendor.3.

In the working directory for Vendor.3 (which you have just checked in), issue the command

% prcs merge -rLocal.@ -n P

to see where the discrepancies are (or use prcs diff), and use

% prcs merge -rLocal.@ P

to merge in the revisions since the last external release with the local changes since the last release. Edit the files to resolve conflicts, and edit `P.prj' as usual. Finally, check the result back in with

% prcs checkin -rLocal P

which will create version Local.6. Because of the particular choice of project versions that was modified, the parent version of Local.6 will be Vendor.3.

This is not the only possible procedure for handling parallel versions, but it does insure that the common version used for merging (see section Prcs merge) is reasonably close to both the new imported version and the latest local version. This point is worth a little discussion, as another illustration of how merging works. If you were instead to create a working directory containing version Local.5 and then perform

# Warning: problematic example follows; DON'T do it this way! #
% prcs merge -rVendor.@ P      
... various edits ...
% prcs checkin -rLocal P

the parent version of Local.6 would be Local.5. If you did this consistently for all new vendor versions, the nearest common ancestor of a new Vendor version and the current Local version would be Vendor.1 (which is where Local.1 comes from). As a result, each time you merged a new Vendor version into the latest Local version, prcs merge would flag all conflicts between all the Local changes since Local.1 and all the Vendor changes since Vendor.1. Doing things as we suggested here, on the other hand, causes the nearest common ancestor between a new Vendor version (say Vendor.4) and the latest Local version to be the previous Vendor version (say Vendor.3), so that only new merge conflicts that arise since Vendor.3 have to be handled during merging.

Handling renaming

Sometimes, you will find it desirable to rename the files you import and re-arrange their directory structure in your local version. You probably don't want to perform this restructuring on the Vendor branch of the project, but if you perform it only on the Local branch, then prcs merge and prcs diff will become confused by the differing names in the two versions (actually, "useless" is a better description than "confused") unless you take some precautions.

The concept of an internal-file family (see section Files attribute) was introduced for this purpose. Initially, you will create your first local version like this:

% prcs checkout -rV P P.prj
# Rename files #
# Edit P.prj to change the names in the Files attribute so 
# as to correspond to your renaming.
% prcs checkin -rLocal P.prj

Editing `P.prj' here consists simply in changing the file names, not the internal file identifiers. For example, if the file `doc/mogrify.1' in branch V is to be called `man/mogrify2.1' in the Local branch, then you would rename the file:

% mkdir man
% mv doc/mogrify.1 man/mogrify2.1

and then you would edit the line for `doc/mogrify.1' in `P.prj', which might read

  (doc/mogrify.1 (P/0_foobar.1 1.1 644))

originally, into

  (man/mogrify2.1 (P/0_foobar.1 1.1 644))

The internal file identifier, therefore, records the correspondence between `doc/mogrify.1' in the V branch and `man/mogrify2.1' in the Local branch. When either of these files is updated and checked in, its new internal file identifier will be in the same internal-file family; thus the correspondence between the files is not lost.

You may now perform meaningful comparisons and merges between the the local and vendor versions by specifying the `-F' (`--family') option to prcs diff or prcs merge:

% prcs merge -rLocal.@ -F P

Environment Variables

Certain information that PRCS needs is not likely to be the same for different users and installations, and is inconvenient or inappropriate to specify with every command. In such cases, PRCS takes the information from environment variables, where they are defined, and uses some implementation-defined default otherwise. Here is a listing of the environment variables that PRCS queries, and their meanings.

{Environment Variable} PRCS_REPOSITORY

Path to the repository. Defaults to `$HOME/PRCS'. See section Repository.

{Environment Variable} PRCS_LOGQUERY

When defined, query user at checkin for a New-Version-Log, if one is missing from the project file. See section Version-Log and New-Version-Log attributes.

{Environment Variable} RCS_PATH

A colon-separated list of additional directory paths in which to search for utility programs, including those that are part of RCS, the Revision Control System. The current implementation of PRCS uses RCS to implement part of its functions (although in general, this fact is transparent to the user). Since there is no universally standard place to install RCS, its location is one of PRCS's configuration parameters. Any utilities that PRCS cannot find in the RCS_PATH directories it looks for in an installation-specific place.

GNU General Public License

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

    Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

    You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

  3. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

    1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

    2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

    3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

    These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

    Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

    In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

    1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

    2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

    3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

    The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

    If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

  6. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

  7. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

  8. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

    If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

    It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

    This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

  10. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

    Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

  11. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

    NO WARRANTY

  12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

  13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and an idea of what it does.
Copyright (C) 19yy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c' 
for details.

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written 
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.