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: Top,  Prev: (dir),  Up: (dir)

   This document describes PRCS, the Project Revision Control System.
PRCS is intended to provide source-code control for coherent sets of
files, such as entire directory subtrees, as opposed to individual
files.  Its purpose is similar to that of SCCS, RCS, and CVS, but
(according to its author, at least), it is much simpler than any of
those systems.  The Introduction and Basic Use sections should allow
most users to make productive use of the system.

* Menu:

* Introduction::     An overview of PRCS's functionality
* Definitions::      Basic concepts and definitions of terms
* Basic Use::        Examples of simple use of PRCS, sufficient
                        for many users
* Running PRCS::     Format of the PRCS command
* Version Names and Specifiers::
                     How versions are labeled and specified in
                        subcommands.
* Subcommands::      Detailed descriptions of the individual subcommands
* Repository::       About the Projects Repository, which contains all
                        the checked-in source files.
* Descriptors::      project-version descriptor (`.prj') files
* Keywords::         Automatic keyword substitution for placing version
                        and date stamps or other identification in files
* Subprojects::      How to manage hierarchical structures of projects
* Importing Project Versions::
                     How to use PRCS to maintain releases of
                        source directories from outside, possibly with
                        local modifications
* Environment Variables::
                     Specifying configuration parameters used by PRCS.
* Copying::          The GNU Public License gives you permission to
                        redistribute PRCS on certain terms; it also
                        explains that there is no warranty.


File: prcs.info,  Node: Introduction,  Next: Definitions,  Prev: Top,  Up: Top

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:

   * Create a copy of the directory tree (or a part of it) for a given
     project version.  The files in such a copy are called "working
     files" and the root directory for these working files is called a
     "working directory".  This process is called "checking-out" the
     version (or the working files).  You may select a project version
     to check out by its version number. Modifying the working files
     has no effect on the project version they came from.  *Note
     checkout::.

   * Create a new project version (and a new project, for the first
     version) from working files, or from some mix of working files and
     the files in a another project version.  This is called
     "checking-in" the version (or the working files).  Before any
     check-in, PRCS checks to see if there have been other
     modifications to files in this project and warns you of conflicts
     and discrepancies.  *Note checkin::.

   * Search for differences between a project version and working files
     or between the files in two versions of a project.  *Note diff::.

   * Insert changes that occurred between two project versions into
     working files.  This process is called "merging" because its
     purpose is to combine changes you have made to a set of working
     files with changes that others have made in the meantime.  It
     changes only the working files, because in general they will need
     editing to reconcile places where the two sets of changes conflict.
     The resulting merged files are marked with distinctive lines
     indicating places where the two sets of changes that are being
     combined differ from each other.  One typically edits the merged
     files to reconcile the differences, and then checks in a new
     version.  *Note merge::.

   * Print out information about the versions of a project contained in
     the repository (*note info::).

   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.  *Note Project-Version Descriptors: Descriptors.

   PRCS keeps all checked-in project versions in a "projects
repository".  *Note Projects Repository: 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.


File: prcs.info,  Node: Definitions,  Next: Basic Use,  Prev: Introduction,  Up: Top

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_. *Note Version Names and Specifiers::.

Minor version name
     Part of a _version name_. *Note 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.
     *Note 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.  *Note 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."  *Note
     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 list of project versions from which it was
     derived (in the Parent-Version and Merge-Parents attributes of the
     descriptor).  This establishes a graph of project versions, each
     being derived from its parents.  A project version P0 is an
     ancestor of version P1, if one can reach P0 from P1 by zero or
     more steps along this directed, acyclic ancestry graph (thus, P1
     is an ancestor of itself).  See *Note Parent-Version attribute::,
     *Note Merge-Parents attribute::, and *Note merge::.

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). *Note 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.  *Note Files attribute::.


File: prcs.info,  Node: Basic Use,  Next: Running PRCS,  Prev: Definitions,  Up: Top

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.

* Menu:

* Creating a repository::
* Starting a new project::
* Adding files to a project::
* Adding version commentary::
* Checking in a version::
* Checking out a version::
* Comparing versions::
* Merging into working files::
* Creating a new major version::
* Summary of really basic use::


File: prcs.info,  Node: Creating a repository,  Next: Starting a new project,  Prev: Basic Use,  Up: Basic Use

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=${HOME}/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.


File: prcs.info,  Node: Starting a new project,  Next: Adding files to a project,  Prev: Creating a repository,  Up: Basic Use

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 1 1 0)
     (Project-Description "")
     (Project-Version P1 0 0)
     (Parent-Version -*- -*- -*-)
     (Version-Log "Empty project.")
     (New-Version-Log "")
     (Checkin-Time "Sun, 31 Dec 1995 01:54:11 -0700")
     (Checkin-Login jmacd)
     (Populate-Ignore ())
     (Project-Keywords)
     (Files
     ; This is a comment.  Fill in files here.
     ; For example:  (prcs/checkout.cc ())
     )
     (Merge-Parents)
     (New-Merge-Parents)

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.


File: prcs.info,  Node: Adding files to a project,  Next: Adding version commentary,  Prev: Starting a new project,  Up: Basic Use

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


File: prcs.info,  Node: Adding version commentary,  Next: Checking in a version,  Prev: Adding files to a project,  Up: Basic Use

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 newlines in the string constants used to hold the commentary,
and make them arbitrarily long.  *Note String Constants: Definitions.


File: prcs.info,  Node: Checking in a version,  Next: Checking out a version,  Prev: Adding version commentary,  Up: Basic Use

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)
     (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))
     )
     (Merge-Parents)
     (New-Merge-Parents)

   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)
     (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))
     )
     (Merge-Parents)
     (New-Merge-Parents)

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. *Note Keywords::.)


File: prcs.info,  Node: Checking out a version,  Next: Comparing versions,  Prev: Checking in a version,  Up: Basic Use

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.


File: prcs.info,  Node: Comparing versions,  Next: Merging into working files,  Prev: Checking out a version,  Up: Basic Use

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


File: prcs.info,  Node: Merging into working files,  Next: Creating a new major version,  Prev: Comparing versions,  Up: Basic Use

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.


File: prcs.info,  Node: Creating a new major version,  Next: Summary of really basic use,  Prev: Merging into working files,  Up: Basic Use

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. *Note Keywords::.)


File: prcs.info,  Node: Summary of really basic use,  Prev: Creating a new major version,  Up: Basic Use

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.


File: prcs.info,  Node: Running PRCS,  Next: Version Names and Specifiers,  Prev: Basic Use,  Up: Top

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


File: prcs.info,  Node: Version Names and Specifiers,  Next: Subcommands,  Prev: Running PRCS,  Up: Top

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:

   * A null major version name means "as given in the working
     project-version descriptor for the specified project"

   * If a null major version name is supplied, a null minor version
     name also means "as given in the working project-version
     descriptor for the specified project." Otherwise, a null minor
     version name (as in "Foo.") is illegal.

   * `@' means "the latest in the repository (or 0 if none)."  When `@'
     is used for the major version, it indicates the numerically
     largest major version name (of the given project) among all those
     major version names that are non-negative integers with no leading
     zeroes.

   * The minor version component of a version specifier (and its leading
     period) may be omitted unless the major version component contains
     a period.  If omitted, the default value depends on the subcommand.


File: prcs.info,  Node: Subcommands,  Next: Repository,  Prev: Version Names and Specifiers,  Up: Top

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.

* Menu:

* Specifying Projects::    How to indicate what project a subcommand
                               is to operate on
* Specifying Files and Directories::
                           How to restrict a subcommand to particular
                               files or directories within a version
* Options::                A compendium of options used by the subcommands

Major Commands

* checkout::       Creating a working copy of a project version
                            from the repository
* populate::       Using the files in a working directory to compose
                            a Files list in a `.prj' file
* depopulate::     Removing elements from the Files list in a `.prj'
                            file
* checkin::        Depositing a new project version in the repository
* diff::           Finding differences between a checked-in project
                            version and working files
* merge::          Merging a checked-in project version into
                            working files
* rekey::          Replacing keywords in working files
* info::           Printing information about a project's versions
                            and their files
* changes::        Printing information about what files were changed in
                            a range of project versions.

Less-common Commands

* admin::          Various administrative functions that have no
                            abstract effect on projects
* config::         Printing information about built-in or environmental
                            parameters of PRCS
* package and unpackage::
                        Moving and copying entire projects between
                            repositories
* execute::        General-purpose command for performing an arbitrary
                            action on all files in a project version
* delete::         Removing all trace of a project version from a
                            repository


File: prcs.info,  Node: Specifying Projects,  Next: Specifying Files and Directories,  Prev: Subcommands,  Up: Subcommands

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:

   * PROJECT denotes a directory.  In this case root working directory,
     D, is PROJECT.  D must contain a single project descriptor,
     `P.prj'.

   * Otherwise, if PROJECT has the form `D/P.prj' (or `P.prj'), then P
     is the project name and D (or `.') is the root working directory.

   * Otherwise, PROJECT has the form `D/P' (or P), in which case P is
     the project name and D (or `.') is the root working directory.

   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:

   * Each of the file and directory operands (*note Specifying Files
     and Directories::) must begin with `D/'.

   * The effect of the command is the same as if the prefix `D/' had
     been removed from all the file and directory options and the
     project operand, replacing any occurrences of D itself with `.',
     and the resulting command then executed in directory D.


File: prcs.info,  Node: Specifying Files and Directories,  Next: Options,  Prev: Specifying Projects,  Up: Subcommands

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 (*note Specifying
Projects::).  Usually, this is simply the current directory (`.'),
specifying everything under the project directory.


File: prcs.info,  Node: Options,  Next: checkout,  Prev: Specifying Files and Directories,  Up: Subcommands

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.

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

 - Standard Option: -j number
 - Long Form: --jobs=NUMBER
     Allows PRCS to spawn up to NUMBER child processes at once.  Almost
     always, 2 or 3 will result in faster operations and higher machine
     load.  Experimentation will yield the best results.

 - 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' to indicate that the names of the files to
     be processed, or the options attached to them, 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.  If
     you intend to use the -N option and later apply the diffs you
     should make sure to always use one of the context diff formats.
     See the PRCS_DIFF_OPTIONS environment variable *Note Environment
     Variables::.

 - Option: --no-keywords
     Causes `prcs populate' to add all files with the :no-keywords
     attribute.

 - Option: --not pattern
     Used in `prcs execute' to indicate that the names of files to be
     processed, or the options attached to them, must not match PATTERN.

 - Option: --pipe
     Causes `prcs execute' to supply file data as the standard input.

 - Option: -p
 - Long Form: --preserve, -@b{-}preserve-permissions, -@b{-}permissions
     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: -P
 - Long Form: --exclude-project-file
     Prevent situations where the project file may be treated as an
     ordinary file.  For example, this causes `prcs diff' not to output
     changes in the project files of each version.

 - Standard Option: --plain-format
     Turns off PRCS's default formatting of its output, which is to
     break lines at the screen width and surround filenames with single
     quotes.  Setting the PRCS_PLAIN_FORMAT environment variable has
     the same effect (*note Environment Variables::).

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

 - Standard Option: -q
 - Long Form: --quiet
     Suppress normal informational messages.

 - Option: -r version
 - Long Form: --revision=VERSION
     Identifies a version of a project.  The VERSION is a version
     specifier. *Note 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.

 - Standard Option: -s
 - Long Form: --skilled-merge
     Turn off most of the safety features of `prcs merge', allowing a
     skilled user finer control over the process.  *Note merge::.

 - Option: --sort=TYPE
     Set the type of sorting for the info command to perform on its
     output.  The two valid values for TYPE are `version' and `date'.
     The default is VERSION.

 - Option: -u
 - Long Form: --unlink
     When PRCS writes a working file or the project file, it generally
     does so by replacing 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 originally linked to is unchanged.

 - Standard Option: -v
 - Long Form: --version
     Prints the version of PRCS and exits.

 - Option: --version-log=NEW VERSION LOG
     Causes `prcs checkin' to set the Version-Log on the command line.
     You will be prompted if there is an existing New-Version-Log
     already.  This option overrides the PRCS_LOGQUERY environment
     variable.

 - Option: -z
 - Long Form: --compress
     Indicates that a command should perform (de)compression.


File: prcs.info,  Node: checkout,  Next: populate,  Prev: Options,  Up: Subcommands

Prcs checkout
=============

 - Command: prcs checkout [option ...] [project [file-or-dir ...]]
     ADDITIONAL OPTIONS: `-r', `-p', `-u', `-P'

     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.  Further, if the `-P' option is
     supplied, the project descriptor will not be created at all.

     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.


File: prcs.info,  Node: populate,  Next: depopulate,  Prev: checkout,  Up: Subcommands

Prcs populate
=============

 - Command: prcs populate [option ...] [project [file-or-dir ...]]
     ADDITIONAL OPTIONS: `-d', `-u', `--no-keywords'

     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 (*note
     Files attribute::).



File: prcs.info,  Node: depopulate,  Next: checkin,  Prev: populate,  Up: Subcommands

Prcs depopulate
===============

 - Command: prcs depopulate [option ...] [project [file-or-dir ...]]
     ADDITIONAL OPTIONS: `-u'

     Remove each file in the  FILE-OR-DIR list from the Files list of
     the `.prj' file identified by PROJECT, without modifying the
     repository.  For each directory in FILE-OR-DIR, recursively removes
     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, but since removing all files is probably not
     something the user wants to do, it queries first if no FILE-OR-DIR
     is supplied.



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

Prcs checkin
============

 - Command: prcs checkin [option ...] [project [file-or-dir ...]]
     ADDITIONAL OPTIONS: `-r', `-u', `-j', `--version-log'

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

     Let LV denote the last minor version on the branch being checked
     into.  A checkin is considered "safe" if the nearest common
     ancestor of LV and the working version is LV (*note Parent-Version
     attribute::).  This is to insure that the version being checked in
     is a descendant of the version at the head of the branch before
     checkin.  Otherwise, changes at the head of the branch are
     clobbered.  Unless the `-f' option is present, PRCS will warn you
     if a checkin is not safe and allow you to abort.

     With `-l' present, PRCS will list which files are modified,
     inserted, deleted, or renamed, relative to the real working
     version prior to checkin.  With `-L', PRCS will list all these
     changes in addition to listing which files are unmodified.

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

