This is Info file prcs.info, produced by Makeinfo-1.64 from the input file prcs.texi. This file describes PRCS, the Project Revision Control System. Copyright (C) 1994, 1996 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.  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 prcs 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 prcs checkin::. * Search for differences between a project version and working files or between the files in two versions of a project. *Note prcs 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 editting 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 prcs merge::. * Print out information about the versions of a project contained in the repository (*note prcs 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 project version from which it was derived (in the Parent-Version attribute of the descriptor). This establishes a chain of project versions, each being a modification of one before. A project version P0 is an ancestor of version P1, if one can reach P0 from P1 by zero or more steps along this chain (thus, P1 is an ancestor of itself). *Note Parent-Version and Descends-From attributes::. Keyword A project version's files may contain instances of PRCS keywords, which `prcs checkin' replaces with appropriate text depending on the keyword (such as the time and date of checkin, the login of the account that checks in a version of a file, the name of the file, or the name of the project). *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 0 13 8) (Project-Description "") (Project-Version P1 0 0) (Parent-Version -*- -*- -*-) (Descends-From -*- -*- -*-) (Version-Log "Empty project.") (New-Version-Log "") (Checkin-Time "Sun, 31 Dec 1995 01:54:11 -0700") (Checkin-Login jmacd) (Populate-Ignore ()) (Files ; This is a comment. Fill in files here. ; For example: (prcs/checkout.cc ()) ) The second line identifies the project version from which these files came: in this case from a version 0.0 of the project named P1. Minor version 0 exists implicitly for every major version of a project; it is empty, containing no files and a standard project descriptor, as shown above. The third line indicates the (in this case, nonexistent) version from which version 0.0 was derived.  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 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) (Descends-From -*- -*- -*-) (Version-Log "checkin main.c and doc/foobar.1") (New-Version-Log "") (Checkin-Time "Sun, 31 Dec 1995 02:10:24 -0700") (Checkin-Login jmacd) (Populate-Ignore ()) (Files (main.c (P1/0_main.c 1.1 644)) (doc/foobar.1 (P1/0_foobar.1 1.1 644)) ) As you can see, PRCS has added the version identification, a timestamp, a record of the account performing the checkin, and some internal identification information about the two files now in the project. It has also changed the New-Version-Log declaration to the Version-Log (which is removed when you modify this version and check-in a new one). Your working directory now contains copies of the files in version 0.1 of P1. You might now add a new working file, say `header.h', and modify `main.c'. You add the line (header.h ()) to the Files list. You will also want to create a New-Version-Log entry and perform another checkin. The new version (0.2) of `P1.prj' might now contain ;; -*- Lisp -*- (Created-By-Prcs-Version 0 13 8) (Project-Description "Sample PRCS Project") (Project-Version P1 0 2) (Parent-Version P1 0 1) (Descends-From -*- -*- -*-) (Version-Log "") (New-Version-Log "") (Checkin-Time "Sun, 31 Dec 1995 02:13:00 -0700") (Checkin-Login jmacd) (Populate-Ignore ()) (Files (main.c (P1/0_main.c 1.2 644)) (doc/foobar.1 (P1/0_foobar.1 1.1 644)) (header.h (P1/0_header.h 1.1 644)) ) The files of version 0.2 of P1 have now been saved; you may destroy the working directory and later restore it with `prcs checkout'. It is not necessary to check in all your working files. By providing a list of files and directories after the project specifier, you can limit the working files considered to those listed: % prcs checkin P1 doc copies only the working files in doc into the new version of P1; for other files listed in `P1.prj', PRCS uses the versions identified by the internal file identifiers in the Files list of `P1.prj'. Thus, if these identifiers are unchanged in your working `P1.prj' file since it was checked out, the same files versions that they identify will be used in the new version of P1 (the working versions, however, may differ in the values of certain keywords. *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 * prcs checkout:: Creating a working copy of a project version from the repository * prcs populate:: Using the files in a working directory to compose a Files list in a `.prj' file * prcs checkin:: Depositing a new project version in the repository * prcs diff:: Finding differences between a checked-in project version and working files * prcs merge:: Merging a checked-in project version into working files * prcs rekey:: Replacing keywords in working files * prcs info:: Printing information about a project's versions and their files Less-common Commands * prcs admin:: Various administrative functions that have no abstract effect on projects * prcs config:: Printing information about built-in or environmental parameters of PRCS * prcs package and prcs unpackage:: Moving and copying entire projects between repositories * prcs execute:: General-purpose command for performing an arbitrary action on all files in a project version * prcs 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 everything under the project directory.  File: prcs.info, Node: Options, Next: prcs 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. - Option: -F - Long Form: --family Normally, subcommands that compare files in two versions (`diff' and `merge') use the names of the files to pair up the files. With the `-F' option, these subcommands will pair files up according to the families of their internal file identifiers (*Note Files attribute::, for a description of internal-file families). - Standard Option: -h - Standard Option: -H - Long Form: --help Prints out help very similar to the contents of this section. - Option: -i - Long Form: --immediate Causes certain actions to occur immediately during execution of a command. For `prcs uncompress', causes the files in a project to be uncompressed on the spot, rather than incrementally as they are needed. - Option: -k - Long Form: --keywords Causes `prcs diff' to compare keywords, instead of stripping them before comparison. - Standard Option: -l - Long Form: --long-format - Standard Option: -L - Long Form: --long-long-format Various long formats, depending on the subcommand. - Option: --match PATTERN Used in `prcs execute' that the names or options attached to files to be executed must match PATTERN. - Standard Option: -n - Long Form: --no-action Indicates that the command is to report what would happen in the absence of `-n', without changing working files or the repository. - Option: -N - Long Form: --new In `prcs diff', produces comparisons against empty ("new") files where a file is missing in one of the versions being compared. - Option: --not PATTERN Used in `prcs execute' that the names or options attached to files to be executed must not match PATTERN. - Standard Option: -q - Long Form: --quiet Suppress normal informational messages. - Option: -p - Long Form: --preserve Preserve permissions on files that are checked out, ignoring any standard protections the user may have set for newly-created files (as by the file mode creation mask in UNIX). - Option: --pre Used in `prcs execute' to indicate that directories are to be listed in pre-order: directory names first, then their non-directory contents, then subdirectories. - Option: -r VERSION - Long Form: --revision=VERSION Identifies a version of a project. The VERSION is a version specifier. *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. - Option: -u - Long Form: --unlink When PRCS writes a working file, it generally does so by overwriting any existing file of that name. With this option, however, if the file to be written is a symbolic link, that link is removed and a new file is created. Thus, the file that was orginally linked to is unchanged. - Standard Option: -v - Long Form: --version Prints the version of PRCS and exits. - Option: -z - Long Form: --compress Indicates that a command should perform (de)compression.  File: prcs.info, Node: prcs checkout, Next: prcs populate, Prev: Options, Up: Subcommands Prcs checkout ============= - Command: prcs checkout [OPTION ...] [PROJECT [FILE-OR-DIR ...]] ADDITIONAL OPTIONS: `-r', `-p', `-u' Create a working copy of a version of the specified files and directories in PROJECT rooted in the current directory (creating any subdirectories that don't exist). You may use the option `-r' to select a version. The default major and minor version specifiers are both `@'. You will be warned when a check-out would change the contents of an existing working file, and interactively given the choice of replacing the file with the version being checked out, or leaving the existing file alone. Existing working files that do not differ from corresponding project files are not modified (their changed and modified dates do not change). The `-f' option will cause checkout to overwrite all files that differ without asking. When PRCS overwrites a working file that is a symbolic link, then (unless the `:symlink' option is specified for that file), it will overwrite the file that the link references, without changing the link itself. With the `-u' option, PRCS will instead remove the link and create a new file. If a working project-version descriptor for PROJECT exists, then the project-version descriptor is treated as an ordinary file for purposes of check-out. A check-out with a non-defaulted FILE-OR-DIR list that does not contain the descriptor therefore leaves the descriptor unchanged. Files that are checked out are restored to the protections recorded for them at check-in time, usually modified (on UNIX systems) by the user's file mode creation mask (see the UNIX manual entry for umask(1)). With the `-p' option, this mask is ignored, and the command restores the files' protections to exactly their state at check-in. Returns a status code of 0 if all goes well, and non-zero if there are errors.  File: prcs.info, Node: prcs populate, Next: prcs checkin, Prev: prcs checkout, Up: Subcommands Prcs populate ============= - Command: prcs populate [OPTION ...] [PROJECT [FILE-OR-DIR ...]] ADDITIONAL OPTIONS: `-d' Add each file in the FILE-OR-DIR list to the Files list of the `.prj' file identified by PROJECT, without modifying the repository. For each directory in FILE-OR-DIR, recursively adds all files in that directory structure (or the directory itself, if it is empty). The FILE-OR-DIR operand list defaults to the current directory. Without the `-d' option, any files already in the Files list remain there unchanged. With `-d', populate will prompt you about removing files from the Files list that are listed there as appearing under one of the directories given in the FILE-OR-DIR list, but are not found in the working directory. With `-d' and `-f', it will remove them silently. For example, suppose the file `P.prj' lists files `C', `D1/A', `D1/B', `D2/A', `D2/B'. Suppose a working directory contains files `A', `D1/B', and `D2/B'. Then the command prcs populate -d P would remove files `C', `D1/A', and `D2/A' from the Files list of `P.prj', and add file `A'. For the same initial `P.prj' file, the command prcs populate -d P D1 would remove `D1/A' from `P.prj', and would add nothing. New files are added with null internal file identifiers. Populate attempts to fill in the `:symlink' and `:directory' options. It also applies a heuristic test to each file added to guess whether it is a non-text file; for each file it judges to be a non-text file, it includes the `:no-keywords' option for that file (*note Files attribute::.).  File: prcs.info, Node: prcs checkin, Next: prcs diff, Prev: prcs populate, Up: Subcommands Prcs checkin ============ - Command: prcs checkin [OPTION ...] [PROJECT [FILE-OR-DIR ...]] ADDITIONAL OPTIONS: `-r' Create a new version of the specified project in the repository. Copy all files listed in the Files attribute of the descriptor (`PROJECT.prj'), taking those specified in FILE-OR-DIR operands and the descriptor itself from the working files. Also, modify the descriptor to reflect the contents of the new version. *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. PRCS issues a warning whenever a symbolic link points to a file not contained in the project. Directories with a `:directory' option need not be actually empty, but this ensures their creation at checkout. It is an error to have a `:no-keywords' option in the same file as a `:symlink', or `:directory' option. The new version will have the latest minor version number for the specified major version. The `-r' option may specify a major version; any minor version specified is ignored. The `-r' option defaults to `-r.@', thus taking the major version from the `.prj' file. PRCS will warn you if you if the minor version number recorded in the `.prj' file is not the latest for its major version, and will abort the checkin unless the `-f' is present. Returns a status code of 0 if all goes well, and non-zero if there are errors.  File: prcs.info, Node: prcs diff, Next: prcs merge, Prev: prcs checkin, Up: Subcommands Prcs diff ========= - Command: prcs diff [OPTION ...] [PROJECT [FILE-OR-DIR ...]] [-- [DIFF-OPTION ...]] ADDITIONAL OPTIONS: `-F', `-r' (once or twice), `-k', `-N' Compare the (partial) contents of two repository versions of a project or of a repository version and a working version. When FILE-OR-DIR arguments are present, they restrict comparison to the specified files or subdirectory trees. The PROJECT argument may be defaulted if there is a single file with extension `.prj' in the current working directory, in which case PRCS takes its name (without `.prj') as the project name. The OPTIONs may specify zero, one, or two versions (using `-r' options). Specifying no `-r' options is equivalent to supplying the single option `-r.', the version from which the current working directory was checked out. A `-r' option that specifies only a major version (leaving off the minor version and its preceding period) implicitly has a minor version of `@'. When one version specifier is given, the files in the indicated version are compared to the working files. The command's output notes any discrepancies in the contents of identically-named files, or in files present in one version but not the other. Two version specifiers cause the same comparison, but between two checked-in versions of the project. Normally, `diff' canonicalizes keyword instances in the files it compares, removing the keyword values and leaving just the keyword name. As a result, two different versions of a file that differ only in their keyword values will compare as equal. The `-k' option causes `diff' to compare keyword values as well. If a file is present only in one of the project versions being compared, `diff' will normally just announce that such a file occurs only in one of the versions. With the `-N' option, it will produce the same output it would if it instead treated the non-existent version as an empty file. This is useful when producing patch files that include new files as well as changed ones. Its effect is essentially the same as that of the same option in GNU `diff' when it compares directories. Normally, files in the two versions being compared are paired by their names. When `-F' is specified, the files are instead paired by the internal-file families of the their internal file identifiers (see *Note Files attribute::, for a description of internal-file families). When this option is present, the names in the FILE-OR-DIR operand refer to file names in the first named version when `-r' is listed twice, and to the working version, otherwise. The DIFF-OPTIONS, if provided, are any options acceptable to GNU `diff'. Returns a status code of 0 if there were no differences, 1 if there were differences, and 2 if there were problems.