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.