This is prcs.info, produced by makeinfo version 4.0 from prcs.texi.

   This file describes PRCS, the Project Revision Control System.

   Copyright (C) 1994, 1996, 1997 by Paul N. Hilfinger.  All rights
reserved.

   We distribute PRCS under the terms of the GNU General Public
License, Version 2, which we have included with this release in the
file named `COPYING', and in the "Copying" section of this manual.  As
indicated in the License, we provide the program "as is" without
warranty of any kind, either expressed or implied, without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

INFO-DIR-SECTION Version Control
START-INFO-DIR-ENTRY
* PRCS: (prcs).           The Project Revision Control System.
END-INFO-DIR-ENTRY


File: prcs.info,  Node: diff,  Next: merge,  Prev: checkin,  Up: Subcommands

Prcs diff
=========

 - Command: prcs diff [option ...] [project [file-or-dir ...]] [--
          [diff-option ...]]
     ADDITIONAL OPTIONS: `-r' (once or twice), `-k', `-N', `-P'

     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.

     Files in the two versions being compared are paired by their names
     and their internal-file families (see *Note Files attribute::, for
     a description of internal-file families).  That is, PRCS will
     assume that two files in the different versions correspond if they
     have the same name or the same internal-file family.  This makes
     it possible to have conflicts (for example, when one switches the
     names of two files in a project descriptor); in those cases PRCS
     will ask the user to resolve the conflict.

     The DIFF-OPTIONS, if provided, are any options acceptable to GNU
     `diff'. *Note (diff)Top::.  The environment variable
     `PRCS_DIFF_OPTIONS', if set, supplies a default set of whitespace
     separated DIFF-OPTIONS.

     If the FILE-OR-DIR is defaulted and `-P' is not supplied, or if
     FILE-OR-DIR contains the project descriptor, PRCS outputs
     differences between project descriptors.

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


File: prcs.info,  Node: merge,  Next: rekey,  Prev: diff,  Up: Subcommands

Prcs merge
==========

 - Command: prcs merge [option ...] [project [file-or-dir ...]]
     ADDITIONAL OPTIONS: `-r', `-u', `-s'

     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 is the working version specified in the checked-out descriptor
     and consists of all files listed therein.  PS is the version
     against which PRCS will reconcile changes, identified by the
     (possibly defaulted) `-r' option.  A common version is chosen
     according to the following algorithm:

     Each version, including the working version, has a list of parent
     versions.  The parent versions establish an ancestry graph that is
     directed and contains no cycles.  A version is an ancestor of
     another if it can be reached by following zero or more parents
     (see *Note Parent-Version attribute:: and *Note Merge-Parents
     attribute::).  PC is chosen from the set of all versions that are
     ancestors of PW and PS.  If amongst this intersection, there
     exists a unique nearest common ancestor, then it is PC.  If there
     is no such version, PRCS will complain and ask the user for help.

     Files in the three versions are matched up both by name and by
     internal-file family (*note Files attribute::).  That is, PRCS
     will assume that two files in different versions correspond if
     they have the same name or the same internal-file family.  This
     makes it possible to have conflicts (for example, when one
     switches the names of two files in a project descriptor); in those
     cases PRCS will ask the user to resolve the conflict.

     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 (*note
     diff::).  In the descriptions that follow, saying that files are
     "equivalent" means that they are identical when canonicalized.

     PRCS detects the following discrepancies:

        * Files present in PC and absent in PW.  The default action is
          `n'.  That is, the files are assumed to be obsolete,
          regardless of their status in PS.

        * Files present in PC and PW, and absent in PS.  The default
          action is `d'.  That is, the files are assumed to be obsolete.

        * Files present in PC, PS, and PW, equivalent in PC and PW, and
          different in PS.  The default action is `r'.  That is, the
          version in PS is assumed to be most up-to-date.

        * Files present in PC, PS, and PW, and different in all three.
          The default action is `m'.  There have been independent
          changes in both PW and PS.

        * Files absent in PC, and different in PW and PS.  The default
          action is `m'.

        * Files absent in PC and PW, and present in PS. The default
          action is `a'.

        * PRCS takes no action in other cases, and does not prompt the
          user.

     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.

     Whenever PRCS is going to replace a working file as a result of one
     of the actions above, it first moves the original file into the
     `obsolete' directory and gives it a unique name.

     A partial merge takes place when not all files in the three
     versions are considered for merging.  This can happen if a merge
     is aborted or the FILE-OR-DIR option limits the files under
     consideration.  When this happens, PRCS records which files have
     been merged and their names in the working project's
     New-Merge-Parents attribute (*note Merge-Parents attribute::).

     A merge is considered _complete_ when each file in each version has
     been considered once.  A complete merge may be achieved by several
     partial merges.  To prevent reconsidering the same file more then
     once, PRCS will not consider any set of files containing a file
     that was already considered in a previous merge against the same
     selected version unless the `-s' option is specified.

     In general, the `-s' option allows the user to turn off all the
     safety features built into `prcs merge'.  It will allow a user to
     merge files more than once, override the choice of an effective
     working version, restart a complete merge, and start a new merge
     without completing a previous merge.

     By default, PRCS uses the GNU diff3 command to perform 2- or 3-way
     file merges when you choose the `m' action (*note (diff)top::).  It
     is possible, however, to supply your own merge command.  By
     setting the `PRCS_MERGE_COMMAND' environment variable to a program
     name, PRCS will call the named command instead of diff3 (*note
     Environment Variables::).



File: prcs.info,  Node: rekey,  Next: info,  Prev: merge,  Up: Subcommands

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. *Note 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.


File: prcs.info,  Node: info,  Next: changes,  Prev: rekey,  Up: Subcommands

Prcs info
=========

 - Command: prcs info [option ...] [project [file-or-dir ...]]
     ADDITIONAL OPTIONS: `-r', `--sort'

     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, their attributes, and their
     unkeyed MD5 checksum;  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'.

     The `--sort=TYPE' option sets the type of sorting that the info
     command should use. If TYPE is `date', versions are sorted by
     individual version date, otherwise the default, `version', is to
     sort by major version creation date.


File: prcs.info,  Node: changes,  Next: admin,  Prev: info,  Up: Subcommands

Prcs changes
============

 - Command: prcs changes [option ...] [project [file-or-dir ...]]
     ADDITIONAL OPTIONS: `-r' (once or twice), `-l'

     The changes subcommand helps you find what versions modify a
     specific file or files.  For example, suppose you fixed a bug a
     long time ago and now it shows up again in the current version.
     You would like to know what project versions modify a certain file
     so you can find out who undid your bug-fix and blame them!

     Like `prcs diff', 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, only that version is scanned
     for changes.  Two version specifiers cause a range of versions to
     be scanned.  In the two version case, one version must be an
     ancestor of the other, and reversing the order of the two versions
     will reverse the order of the output.

     When FILE-OR-DIR arguments are present, they restrict the change
     report to the specified files or subdirectory trees.  Otherwise all
     files are reported.

     For each specified version that modifies a file (in the reporting
     set) relative to one of its parent versions, `changes' prints the
     project name, major and minor version identifiers, date and time
     checked in, and the user who checked in the version.  Then it
     prints the parent version and a listing of all the selected files
     that were modified, including: addition, deletion, rename, type
     change, symlink change, or version change.  For regular files,
     `changes' also prints the number of lines added and removed by the
     modification.  If a project version does not modify any of the
     selected files, nothing is printed.

     When the `-l' option is present, `changes' also prints the
     version-log associated with each version.



File: prcs.info,  Node: admin,  Next: config,  Prev: changes,  Up: Subcommands

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
     out 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'.

 - Subfunction: pdelete project
     Deletes a repository entry, permanently removing all versions and
     data from the repository.


 - Subfunction: pinfo
     Lists all projects in the repository.


 - Subfunction: prename project
     Renames a repository entry, similar to renaming during `prcs
     unpackage'.



File: prcs.info,  Node: config,  Next: package and unpackage,  Prev: admin,  Up: Subcommands

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.


File: prcs.info,  Node: package and unpackage,  Next: execute,  Prev: config,  Up: Subcommands

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 *Note 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: `-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 [project]
     Creates PROJECT in the repository to be a copy of the project from
     which PACKAGEDFILE was created.  The file PACKAGEDFILE must have
     been created by `prcs package' (with or without the `-z' option).
     If PROJECT is omitted, it defaults to the name of the project from
     which PACKAGEDFILE was created. If PROJECT exists in the
     repository, the user is prompted to delete the old copy from the
     repository.  A value of `-' for PACKAGEDFILE denotes the standard
     input.  With `-n', it merely reports the name of the project that
     would be added.

     If PROJECT differs from the original name as stored in
     PACKAGEDFILE, the project is renamed.  Renaming a project revises
     the history of the project; the result is as if the project had
     always been named PROJECT, with one exception: When checked out,
     project descriptor will have a comment inserted making note of the
     original project name.


File: prcs.info,  Node: execute,  Next: delete,  Prev: package and unpackage,  Up: Subcommands

Prcs execute
============

 - Command: prcs execute [option ...] [project [file-or-dir ...]] [--
          command [arg ...]]
     ADDITIONAL OPTIONS: `-r', `-P', `--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.  Each directory, whether or not explicitly named in the
     project, is included once, either in pre- or post-order.

     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:

    `{}'
          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).

    `{options}'
          Replaced by a string consisting of all colon-options
          applicable to the file (*note Files attribute::), separated
          by "quoted blanks" (that is, blanks that do not divide the
          replacement string into separate arguments).  If a directory
          is not explicitly named in the project file, it is listed
          with a `:implicit-directory' option, whether or not it
          appears separately in the Files attribute.  These directories
          appear whether or not the files containing them were on the
          command line (otherwise, it would be impossible to get just
          the directories).  The project file is included with the
          `:project-file' attribute.  With the `--all' option, all of
          these colon-option strings are concatenated together, with
          the strings for different files separated by unquoted blanks.

    `{file}'
          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, `{file}' is the same as
          `{}'.  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 {}

     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
     (*note Specifying Projects::).  This allows you to do something
     like the following:

          % ln -s . P-1.0
          % tar -cvf P-1.0.tar `prcs execute --not :.*directory P-1.0`

     for making tarfiles containing all files in a project in an
     appropriately named subdirectory for distribution.

     If the `--pipe' option is present, then the contents of the file
     (as would be contained in the file named by `{file}') 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 `{}' is the first string in the
     replacement for `{options}'.  For example, if a project contains
     the files `A', `B/Q', and `B/R', then

          prcs execute --all . -- foo -a{}-b "{options}"

     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.


File: prcs.info,  Node: delete,  Prev: execute,  Up: Subcommands

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.


File: prcs.info,  Node: Repository,  Next: Descriptors,  Prev: Subcommands,  Up: Top

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.


File: prcs.info,  Node: Descriptors,  Next: Keywords,  Prev: Repository,  Up: Top

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.

* Menu:

* Descriptor entry syntax::
* Project-Version attribute::
* Project-Description attribute::
* Version-Log and New-Version-Log attributes::
* Checkin-Time and Checkin-Login attributes::
* Files attribute::
* Populate-Ignore attribute::
* Merge-Parents attribute::
* Parent-Version attribute::
* Project-Keywords attribute::


File: prcs.info,  Node: Descriptor entry syntax,  Next: Project-Version attribute,  Prev: Descriptors,  Up: Descriptors

Descriptor entry syntax
-----------------------

   The syntax of the project descriptor file is a 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 (*note
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.


File: prcs.info,  Node: Project-Version attribute,  Next: Project-Description attribute,  Prev: Descriptor entry syntax,  Up: Descriptors

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 (*note
     Version Names and Specifiers::).  The `prcs checkin' command sets
     the Project-Version of the checked-in descriptor.  *Note Version
     Names and Specifiers::.


File: prcs.info,  Node: Project-Description attribute,  Next: Version-Log and New-Version-Log attributes,  Prev: Project-Version attribute,  Up: Descriptors

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")


File: prcs.info,  Node: Version-Log and New-Version-Log attributes,  Next: Checkin-Time and Checkin-Login attributes,  Prev: Project-Description attribute,  Up: Descriptors

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")


File: prcs.info,  Node: Checkin-Time and Checkin-Login attributes,  Next: Files attribute,  Prev: Version-Log and New-Version-Log attributes,  Up: Descriptors

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)


File: prcs.info,  Node: Files attribute,  Next: Populate-Ignore attribute,  Prev: Checkin-Time and Checkin-Login attributes,  Up: Descriptors

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:

        * If a particular internal file identifier describes a file in
          one project-version descriptor, it can be copied verbatim as
          the internal file identifier for a file (possibly with a
          different name) in another project-version descriptor for the
          same project in the same repository.  It will denote a file
          with the same contents, aside possibly from the values of
          certain keywords (*note Keywords::).  As a result, it is
          possible to copy an entire project version to another (with
          another version number) without checking out the files,
          simply by copying the Files attribute of the project-version
          descriptor.  Likewise, if you wish to change the name of a
          file from one version to another, you should reflect the
          change in the working version of the project descriptor,
          keeping its internal file identifier unchanged.

        * Each non-null internal file identifier belongs to an
          "internal-file family".  If a working file has a non-null
          internal file identifier, then a `prcs checkin' will assign
          it an internal file identifier (possibly unchanged from that
          of the working version) in the same internal-file family.  If
          a working file has a null internal file identifier (`()'),
          `prcs checkin' will put it in a new internal-file family,
          otherwise unpopulated.  Internal-file families are useful for
          certain kinds of version comparisons and merges.

     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 (*note 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
          )


File: prcs.info,  Node: Populate-Ignore attribute,  Next: Merge-Parents attribute,  Prev: Files attribute,  Up: Descriptors

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"))


File: prcs.info,  Node: Merge-Parents attribute,  Next: Parent-Version attribute,  Prev: Populate-Ignore attribute,  Up: Descriptors

Merge-Parents attribute
-----------------------

 - Attribute: Merge-Parents (MERGED-AGAINST-VERSION
     EFFECTIVE-WORKING-VERSION COMPLETE (FILE-ACTION) ...) ...

 - Attribute: New-Merge-Parents (MERGED-AGAINST-VERSION
     EFFECTIVE-WORKING-VERSION COMPLETE (FILE-ACTION) ...) ...

     The `prcs merge' command uses the New-Merge-Parents attribute to
     record the history of updates to each file.  Each
     MERGED-AGAINST-VERSION indicates a selected version that was
     merged into the working files, each EFFECTIVE-WORKING-VERSION
     indicates the effective working version used to select the common
     version, COMPLETE indicates whether the merge against
     MERGED-AGAINST-VERSION was completed, 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 FILE-ACTIONS entries contain data recording each merge action
     that takes place.  Since the filenames in each merge action need
     not be the same (*note Files attribute::), PRCS records each of up
     to three filenames for each merge action or an empty list (`()')
     where a file was not present.  In addition, PRCS records which
     action was taken on each set of files.

     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.

     Each merge-parent in a checked-in version is considered as a parent
     version.  Similarly, each new-merge-parent in a working version is
     considered as a parent version (*note Parent-Version attribute::).


File: prcs.info,  Node: Parent-Version attribute,  Next: Project-Keywords attribute,  Prev: Merge-Parents attribute,  Up: Descriptors

Parent-Version attribute
------------------------

   This attribute, along with the Merge-Parents attribute described
above, tracks the history of a project version: Parent-Version records
the version from which a project version originally descended, and
Merge-Parents records versions against which it was merged.

 - Attribute: Parent-Version P M N
     This has the same form as the Project-Version attribute (*note
     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:

        * A version is an ancestor of itself.

        * The Parent-Version attribute of a version names an ancestor
          of that version.

        * Each element in the Merge-Parent list names an ancestor of
          that version.

        * Ancestry is transitive: any ancestor of one of V's ancestors
          is also an ancestor of V.  The number of Parent-Version or
          Merge-Parent entries that must be traversed to find an
          ancestor of V is called the "distance" of that ancestor from
          V.

     Given two versions in a repository, any version that is an
     ancestor to both is called a "common ancestor".  A common ancestor
     whose distance from both is minimal is called a "nearest common
     ancestor".  It is possible for there to be more than one nearest
     common ancestor.  If so, commands attempting to determine the
     nearest common ancestor will either abort or ask the user for help.

     Each `prcs checkin' sets Parent-Version to name the Project-Version
     attribute of the version from which the newly checked-in version
     is derived.  Additionally, it sets the New-Merge-Parents attribute
     to the Merge-Parents attribute.


File: prcs.info,  Node: Project-Keywords attribute,  Prev: Parent-Version attribute,  Up: Descriptors

Project-Keywords attribute
--------------------------

 - Attribute: Project-Keywords (KEYWORD VALUE) ...
     The Project-Keywords attributes allows the user to define new
     keywords and their values, which will behave exactly like the
     builtin keywords (*note Keywords::).  Each KEYWORD must be unique
     and must not match one of the builtin keywords.  All files
     contained in the project version described by a descriptor
     containing a Project-Keywords list will be keyed with each
     KEYWORD.  Each VALUE is either a label or a string and may not
     contain a newline character.  For example, you could include such
     project meta-data as state labels, release labels, and version
     numbers:

          (Project-Keywords (ReleaseMajorVersion 1)
                            (ReleaseMinorVersion 1)
                            (ReleaseMicroVersion 0)
                            (ReleaseVersion "$ReleaseMajorVersion$.$ReleaseMinorVersion$.$ReleaseMicroVersion$"))
                            (ProjectState "Release")
                            (RealAuthor "Josh")) ; in case the login doesn't
                                                 ; provide enough information.


File: prcs.info,  Node: Keywords,  Next: Subprojects,  Prev: Descriptors,  Up: Top

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 (*note 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.

* Menu:

* Recognized Keywords::           Keywords that PRCS knows about, and
                                      their meanings
* Recursive Keyword Replacement:: Keywords are replaced recursively
* Formatted Keyword Instances::   How to get keyword replacement data
                                      inserted without the usual surroundings
* Keywords and File Identifiers:: Subtle details about keyword replacement
                                      semantics.


File: prcs.info,  Node: Recognized Keywords,  Next: Recursive Keyword Replacement,  Prev: Keywords,  Up: Keywords

Recognized Keywords
===================

   PRCS understands the following built-in keywords, in addition to any
declared in the Project-Keywords attribute.  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.

