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: prcs merge, Next: prcs rekey, Prev: prcs diff, Up: Subcommands Prcs merge ========== - Command: prcs merge [OPTION ...] [PROJECT [FILE-OR-DIR ...]] ADDITIONAL OPTIONS: `-F', `-r', `-u' Find differences between working files and those of the selected version of PROJECT, and (unless `-n' is specified) try to modify the working files to reconcile them. The default major and minor versions are `-r.@'. More precisely, the comparison takes place between three versions of PROJECT: the working version (called PW in what follows), the common version (PC) and the selected version (PS). PW consists of the files listed in the working version of the descriptor and included in the FILE-OR-DIR operands, which default to all files listed in the descriptor. PS is the version identified by the (possibly defaulted) `-r' option. If the nearest common ancestor of PS and PW exists, then that is PC (*note Parent-Version and Descends-From attributes::.). Otherwise, PC is taken to be the empty version with the same major version identifier as PW and minor version number 0. Normally, the files in the three versions are matched up by name. The `-F' option changes this behavior, and matches up files that have the same internal-file family (*note Files attribute::.). The names in the FILE-OR-DIR option refer to files in version PW. A `prcs merge' will report discrepancies and (unless `-n' is specified) take actions as directed. The possible actions are as follows. `n' Do nothing. `a' Add the file from PS to PW. `r' Replace the working file with the file from PS. `d' Delete the file from PW. `m' Merge the file from PS with that from PW, inserting markers into the merged working file to show where the changes in PW (relative to PC) and those in the version from PS overlap. If the file from PC is missing, then an empty file is used for its contents. In general, you will have to edit the working file to resolve the discrepancies. If the versions in PS and PW are identical aside from keyword values, merging has no effect. `?' Print summary of options. `h' Print explanatory help message. `v' View differences between PS, PC, and PW (there is further prompting for which you want compared). The `-f' option causes default actions to each discrepancy (see below). Otherwise, PRCS will ask the user to specify one of the possible actions. All of the actions except `n' modify the descriptor, either to remove the file from the Files list, or to modify its internal file identifier to the one from PS. Like `prcs diff', `prcs merge' canonicalizes files to strip keyword values before comparing them for discrepancies (*note prcs diff::.). In the descriptions that follow, saying that files are "equivalent" means that they are identical when canonicalized. PRCS detects the following discrepancies: * Files present in PC and absent in PW. The default action is `n'. That is, the files are assumed to be obsolete, regardless of their status in PS. * Files present in PC and PW, and absent in PS. The default action is `d'. That is, the files are assumed to be obsolete. * Files present in PC, PS, and PW, equivalent in PC and PW, and different in PS. The default action is `r'. That is, the version in PS is assumed to be most up-to-date. * Files present in PC, PS, and PW, and different in all three. The default action is `m'. There have been independent changes in both PW and PS. * Files absent in PC, and different in PW and PS. The default action is `m'. * Files absent in PC and PW, and present in PS. The default action is `a'. * PRCS takes no action in other cases, and does not prompt the user. When PRCS overwrites a working file that is a symbolic link, then (unless the `:symlink' option is specified for that file), it will overwrite the file that the link references, without changing the link itself. With the `-u' option, PRCS will instead remove the link and create a new file.  File: prcs.info, Node: prcs rekey, Next: prcs info, Prev: prcs merge, Up: Subcommands Prcs rekey ========== - Command: prcs rekey [OPTION ...] [PROJECT [FILE-OR-DIR ...]] ADDITIONAL OPTIONS: `-u' Replace keywords in the selected files, according to the version named in the project file. Files whose contents would not change under keyword substitution are not modified. With the `-n' option, simply reports files that will change as a result of keyword replacement. *Note Keywords::. When PRCS overwrites a working file that is a symbolic link, then (unless the `:symlink' option is specified for that file), it will overwrite the file that the link references, without changing the link itself. With the `-u' option, PRCS will instead remove the link and create a new file. You can use this command to update keywords in working files after performing a `prcs checkin', which does not modify keyword values.  File: prcs.info, Node: prcs info, Next: prcs admin, Prev: prcs rekey, Up: Subcommands Prcs info ========= - Command: prcs info [OPTION ...] [PROJECT [FILE-OR-DIR ...]] ADDITIONAL OPTIONS: `-r' Print information about versions of the named project. For each version listed, prints the project name, major and minor version identifiers, date and time checked in, and the user who checked in the version. With the `-l' option, also prints out the version logs and each project description. With `-L', also prints out the files constituting the version; the FILE-OR-DIR options in this case restrict the files or directories that are listed. The `-r' option is special in this command in that it may contain any of the shell filename-generation pattern characters defined for the Bourne shell, `sh': `*', which matches any string of 0 or more characters; `?', which matches any single character; `[...]', which matches any of the enclosed characters; and `[!...]', which matches any character except one of the enclosed characters. These special pattern characters must be escaped to get them past the shell. The default for both the major and minor versions is `*'. The `-r' option is still interpreted as a separate major and minor version; that is, `-rFoo.*' matches `Foo.1', but not `Foo.Bar.1'.  File: prcs.info, Node: prcs admin, Next: prcs config, Prev: prcs info, Up: Subcommands Prcs admin ========== - Command: prcs admin SUBFUNCTION [OPTION ...] [OPERAND ...] Perform various administrative subfunctions that generally have no effect on the abstract state of the repository. The available functions are as follows. - Subfunction: compress [PROJECT] Encourages PRCS to save space in storing the data for PROJECT, even at the expense of slower processing. This command may take some time to execute. Interrupting it in the middle is safe, although it may lead to somewhat erratic space-saving behavior. - Subfunction: uncompress [OPTION] [PROJECT] ADDITIONAL OPTIONS: `-i' Encourages PRCS to save time in processing commands against PROJECT, even at the expense of using more space--perhaps considerably more. With the `-i' option, PRCS will immediately expand the entire representation of PROJECT. Without the `-i' option, PRCS will increase its use of space only as needed. If disk space should run out, PRCS will leave the repository in a correct state. - Subfunction: access [PROJECT] With the optional operand, interactively sets read and write permissions to all versions of PROJECT, in the repository, and (on systems that provide it) sets the group to which the files belong. This command allows the owner of a project in a repository to restrict the access that others have to its contents. One can specify that these files may only be read or may not be accessed at all. Without a PROJECT operand, interactively sets read and write permissions to the repository itself, both for members of the repository directory's group, and for all other users. One must have at least read access to the repository to look at or check in any project (in addition to having appropriate access to the project itself). You must have write access to the repository to create new projects in it. - Subfunction: rebuild [OPTION ...] [PROJECT] Rebuilds internal repository data on PROJECT, possibly removing file storage for deleted project versions and verifying the integrity of all project versions. With the `-l' option, reports deletions. Unless there has been damage to the repository, this command generally has no visible effect on the notional contents of the repository. - Subfunction: init PROJECT Create a new project in the repository containing no (non-empty) versions. Performing a `prcs checkout' on a non-existent project creates a blank working project descriptor without modifying the repository. The first `prcs checkin' for that project then creates a new entry in the repository. Normally, no other explicit initialization for the project's entry in the repository is necessary. However, with this method it is impossible to perform a `prcs access' before the first check-in, because there is no record of the new project in the repository. With `prcs init', you can create a repository entry (containing no versions) that you can modify with `prcs access'.  File: prcs.info, Node: prcs config, Next: prcs package and prcs unpackage, Prev: prcs admin, Up: Subcommands Printing and Checking the Configuration ======================================= - Command: prcs config Print out all compiled-in values and their values, possibly altered by environment variables or command-line arguments. Also verifies that the executables named by `$RCS_PATH', or its compiled-in default, are valid and checks their version numbers to see that they are not outdated.  File: prcs.info, Node: prcs package and prcs unpackage, Next: prcs execute, Prev: prcs config, Up: Subcommands Moving and Copying Projects =========================== Sometimes, it is desirable to package up and move or copy an entire PRCS project, rather than a single version of a project (discussed elsewhere in *Note Importing Project Versions::.) One can move an entire repository using the usual UNIX tools for copying, moving, distributing, and packaging directories. For individual projects, it is preferable to use the `package' and `unpackage' subcommands in order to insure that all of PRCS's internal structure is maintained. - Command: prcs package PROJECT PACKAGEDFILE ADDITIONAL OPTIONS: `-r', `-z' Creates a plain file named PACKAGEDFILE, containing all the data in PROJECT. A value of `-' for PACKAGEDFILE denotes the standard output. With `-z', the output file is compressed (in gzip format). - Command: prcs unpackage PACKAGEDFILE The project PROJECT must not exist in the repository, and the file PACKAGEDFILE must have been created by `prcs package' (with or without the `-z' option). Creates PROJECT in the repository to be a copy of the project from which PACKAGEDFILE was created. A value of `-' for PACKAGEDFILE denotes the standard input. With `-n', it merely reports the name of the project that would be added.  File: prcs.info, Node: prcs execute, Next: prcs delete, Prev: prcs package and prcs unpackage, Up: Subcommands Prcs execute ============ - Command: prcs execute [OPTION ...] [PROJECT [FILE-OR-DIR ...]] [-- COMMAND [ARG ...]] ADDITIONAL OPTIONS: `-r', `--pre', `--all', `--pipe' `--match PATTERN', `--not PATTERN' Execute `COMMAND ARG ...,' suitably modified as described below, for the name of each file and directory in FILE-OR-DIR in the specified version, filtered by any `--match' and `--not' operators as described below. This elaborate command is intended to facilitate efficient, open-ended extension of the functions of PRCS. With the `--all' option, COMMAND is executed once. Otherwise, it is executed once per file name. The PATTERN options filter the selected files. To be selected, the entry in the Files attribute for a given file must satisfy the `--match' pattern (if any) and not satisfy the `--not' pattern, if any. Each pattern is a regular expression; an entry satisfies the pattern if either the name or any of the `:' options matches the pattern. For each execution of COMMAND, PRCS first replaces the following strings wherever they appear in COMMAND and in each ARG: `{}' Replaced by the name of the file. With the `--all' option, replaced by the sequence of all selected file names, separated by "unquoted blanks" (that is, blanks that divide the replacement string into separate arguments). `{options}' Replaced by a string consisting of all colon-options applicable to the file (*note Files attribute::.), separated by "quoted blanks" (that is, blanks that do not divide the replacement string into separate arguments). Each directory that does not carry a `:symlink' option is listed with a `:directory' option, whether or not it appears separately in the Files attribute. With the `--all' option, all of these colon-option strings are concatenated together, with the strings for different files separated by unquoted blanks. `{file}' The name of a file containing the contents of the appropriate version of the file. Unless the internal file identifier is null (which can only happen when there is no `-r' option, so that the working version is specified), this is the name of a temporary file containing a checked-out copy of the appropriate version, which is deleted after COMMAND completes. With a null internal file identifier, `{file}' is the same as `{}'. It is the empty string for a directory or a file carrying the `:symlink' option. With the `--all' option, all of these file names are concatenated together, separated by unquoted blanks. (In contexts where curly braces are special to your shell, you will have to escape them.) After these substitutions, PRCS invokes COMMAND, which must be an executable file. It looks for COMMAND in the same directories as the shell (using the PATH environment variable). When `--' and what follows are omitted, they default to -- /bin/echo {} which simply echoes the names of all files and directories in the selected version, one per line. One small glitch: `prcs execute' uses the current directory in effect when it is invoked as the current directory seen by COMMAND. This is true, even when the PROJECT operand specifies a subdirectory. For example, % cd /usr/users/foo % prcs execute D/P -- pwd will print `/usr/users/foo' once for each file listed in `/usr/users/foo/D/P.prj', and not `/usr/users/foo/D', as the general description of the PROJECT operand might otherwise suggest (*note Specifying Projects::.). If the `--pipe' option is present, then the contents of the file (as would be contained in the file named by `{file}') is supplied as the standard input. The `--pipe' and `--all' options are incompatible. Any ARG whose replacement contains unquoted blanks (introduced by the `--all' option) is divided at those blanks into separate arguments (even in the case where substitution results in a null string, that null string will be broken out as a separate argument). Each of the resulting arguments, is passed directly to the program specified by COMMAND as a single string, with no further processing by any shell. With the `--all' option, PRCS will invoke COMMAND only once. The order of the lists of arguments replacing each pattern in COMMAND is consistent, so that, for example, the options for the first file name in the replacement for `{}' is the first string in the replacement for `{options}'. For example, if a project contains the files `A', `B/Q', and `B/R', then prcs execute --all . -- foo -a{}-b "{options}" will execute (in effect) the single command foo -aA B/Q B/R B-b "" "" "" ":directory" With the `--pre' (for pre-order) option the directory name is listed first, then the non-directory file names within that directory, then the subdirectories and their contents. Otherwise, subdirectories and their contents are listed first, then the names of its non-directory files, then the name of the directory itself. With `-n', the command prints the commands that will be executed without actually executing them.  File: prcs.info, Node: prcs delete, Prev: prcs execute, Up: Subcommands Deleting Project Versions ========================= - Command: prcs delete `-r' VERSION PROJECT Delete the indicated version of PROJECT. It will no longer be possible to retrieve the given version. Therefore, this is a command that you should use very sparingly, if at all. Deleting a version does not necessarily release the space used by the files it contains, since these may be mentioned in other versions. At various times, PRCS will note what space can actually be released and do so. Minor version numbers increase monotonically, regardless of deletions, and are never re-used.  File: prcs.info, Node: Repository, Next: Descriptors, Prev: Subcommands, Up: Top Repository ********** The projects repository is a directory that stores the checked-in copies of some set of projects. You usually specify it to PRCS by setting the `PRCS_REPOSITORY' environment variable, or by using the `-R' (`--repository') option. It defaults to `$HOME/PRCS'. The precise contents of the repository--the relationship between the files that appear there and the abstract set of version contents presented by PRCS--is deliberately left undefined. You should not count on it being stable from release to release. Auxiliary Data -------------- To increase the speed of `checkin' and other subcommands, PRCS maintains redundant information, both in the repository and in working directories. Specifically, you may find files with names such as `.P.prcs_aux' in your working directory, which contain information that allow PRCS to make a quick, heuristic determination of which files you have modified from their repository versions. It is safe to remove (but not to modify) these auxiliary files.  File: prcs.info, Node: Descriptors, Next: Keywords, Prev: Repository, Up: Top Descriptors *********** A project-version descriptor is a file that defines the contents of the project. For project with name P, the project-version descriptor (or just `descriptor') is called `P.prj' and is kept at the root of the project directory tree. When you check in a project, the project descriptor indicates what files need to be included, which have keywords that need to be expanded, and from which previous versions of the those files (if any) the working files were derived. A `prcs checkin' then creates and checks in an updated descriptor file. The sections below detail the syntax of the project descriptor file and the standard attribute entries that may appear in it. * Menu: * Descriptor entry syntax:: * Project-Version attribute:: * Project-Description attribute:: * Version-Log and New-Version-Log attributes:: * Checkin-Time and Checkin-Login attributes:: * Files attribute:: * Populate-Ignore attribute:: * Merge-Parents attribute:: * Parent-Version and Descends-From attributes::  File: prcs.info, Node: Descriptor entry syntax, Next: Project-Version attribute, Prev: Descriptors, Up: Descriptors Descriptor entry syntax ----------------------- The syntax of the project descriptor file is slight variant on Lisp. It consists of `S-expressions' (this is the terminology established by Lisp, so we'll use it here). In general, an S-expression has one of the following forms LABEL STRING CONSTANT (S-EXPRS) Where `S-EXPRS' is (recursively) a sequence of 0 or more s-expressions, separated from each other by whitespace and optionally separated from the surrounding parentheses by whitespace (`whitespace' is any non-empty sequence of blanks, tabs, form feeds, and newlines). We've described the syntax of labels and string constants elsewhere (*note Definitions::.). You may include comments in the descriptor; these consist of a semicolon (outside of a string) followed by all characters up to and not including the next newline or the end of the file. Comments have no effect on the behavior of PRCS and are copied from one version of a project descriptor to the next. The non-nested S-expressions that appear in a descriptor (those that aren't part of some larger expression) each start with an attribute name (a label). The valid attribute names are described in the following sections.  File: prcs.info, Node: Project-Version attribute, Next: Project-Description attribute, Prev: Descriptor entry syntax, Up: Descriptors Project-Version attribute ------------------------- - Attribute: Project-Version P M N This indicates that the descriptor is (or is modified from) the descriptor for version M.N of project P. M must be a valid major version name and N must be a valid minor version name (*note Version Names and Specifiers::.). The `prcs checkin' command sets the Project-Version of the checked-in descriptor. *Note Version Names and Specifiers::.  File: prcs.info, Node: Project-Description attribute, Next: Version-Log and New-Version-Log attributes, Prev: Project-Version attribute, Up: Descriptors Project-Description attribute ----------------------------- - Attribute: Project-Description STRING-CONSTANT This attribute is intended to provide a title or short description of the project. By default, `prcs checkin' leaves it undisturbed. For example, (Project-Description "Sample PRCS Project")  File: prcs.info, Node: Version-Log and New-Version-Log attributes, Next: Checkin-Time and Checkin-Login attributes, Prev: Project-Description attribute, Up: Descriptors Version-Log and New-Version-Log attributes ------------------------------------------ - Attribute: Version-Log STRING-CONSTANT - Attribute: New-Version-Log STRING-CONSTANT The version log is stored with the descriptor of each version of a project. A `prcs checkin' initializes it from the New-Version-Log attribute, removing any existing Version-Log attribute, and setting the New-Version-Log to the empty string. The version log is intended to describe the changes made in this version from its predecessor, or to contain other comments about it. For example, (Version-Log "Added header.h") (New-Version-Log "Modified main.c")  File: prcs.info, Node: Checkin-Time and Checkin-Login attributes, Next: Files attribute, Prev: Version-Log and New-Version-Log attributes, Up: Descriptors Checkin-Time and Checkin-Login attributes ----------------------------------------- - Attribute: Checkin-Time TIME-SPECIFIER - Attribute: Checkin-Login LABEL These attributes record the login of the user performing the PRCS check-in that created this version and the time at which it was performed. They are set by `prcs checkin'. For example, (Checkin-Time "Sun, 12 Jun 1994 20:00:00 -0700") (Checkin-Login hilfingr)  File: prcs.info, Node: Files attribute, Next: Populate-Ignore attribute, Prev: Checkin-Time and Checkin-Login attributes, Up: Descriptors Files attribute --------------- - Attribute: Files (FILE1 (INTERNAL-FILE-ID1) OPTIONS1) ... Each of the 0 or more arguments of the Files attribute denotes one of the constituents of a version. The FILE arguments give the pathnames of files relative to some root directory. The INTERNAL-FILE-ID arguments contain information used by PRCS to identify versions of individual files. If F is one of the FILE arguments, then no component of F may be `.' or `..'. Unless one of the options listed for F is `:directory' (see below), no other FILE argument in the Files attribute may begin with `F/'. The precise format of an internal file identifier is not defined, and is subject to change whenever PRCS is revised. Two properties, however, are guaranteed: * If a particular internal file identifier describes a file in one project-version descriptor, it can be copied verbatim as the internal file identifier for a file (possibly with a different name) in another project-version descriptor for the same project in the same repository. It will denote a file with the same contents, aside possibly from the values of certain keywords (*note Keywords::.). As a result, it is possible to copy an entire project version to another (with another version number) without checking out the files, simply by copying the Files attribute of the project-version descriptor. Likewise, if you wish to change the name of a file from one version to another, you should reflect the change in the working version of the project descriptor, keeping its internal file identifier unchanged. * Each non-null internal file identifier belongs to an "internal-file family". If a working file has a non-null internal file identifier, then a `prcs checkin' will assign it an internal file identifier (possibly unchanged from that of the working version) in the same internal-file family. If a working file has a null internal file identifier (`()'), `prcs checkin' will put it in a new internal-file family, otherwise unpopulated. Internal file families are useful for certain kinds of version comparisons and merges. The OPTIONS arguments denote 0 or more labels indicating special properties of the file. At the moment, four are defined. `:no-keywords' indicates that keywords in the file are not to be expanded. `:symlink' indicates the file is a symbolic link, which will be recorded at checkin and reproduced at checkout. `:directory' indicates that the file is a directory, which will be created, if necessary, at checkout. This is useful for having empty directories in your project. `:tag=LABEL' records LABEL as a piece of user-defined information about the file. PRCS does not interpret LABEL; its main use is for filtering in the `prcs execute' subcommand (*note prcs execute::.). There may be any number of `:tag' options attached to a file. The project descriptor (`.prj' file) is not explicitly included in the Files attribute. Nevertheless, it is implicitly one of the files in each project version. For example, (Files (empty () :directory) ; an empty directory (pointer () :symlink) ; a symbolic link (realfile () :no-keywords) ; the only real file in the list )  File: prcs.info, Node: Populate-Ignore attribute, Next: Merge-Parents attribute, Prev: Files attribute, Up: Descriptors Populate-Ignore attribute ------------------------- - Attribute: Populate-Ignore (PATTERN1 ...) This attribute is used to inform `prcs populate' of files that it should not add to the Files list of the project descriptor. It is included as a convenience; you can accomplish the same effect by editing the Files list after running populate. Each of the PATTERN arguments is a regular expression (as used by `grep'). Any path name that `prcs populate' finds that matches one or more PATTERN arguments is not added to the Files list (existing names on the list are not affected). For example, the following filters out object (`.o') files, library archive (`.a') files, core files, files generated by TeX, Postscript (`.ps') files that occur in subdirectory `doc', Emacs backup files, and the executable file `a.out': (Populate-Ignore ("\\.o$" "\\.a$" "~$" "^a.out$" "^core$" "\\.dvi$" "\\.aux$" "\\.log" "^doc/.*\\.ps"))  File: prcs.info, Node: Merge-Parents attribute, Next: Parent-Version and Descends-From attributes, Prev: Populate-Ignore attribute, Up: Descriptors Merge-Parents attribute ----------------------- - Attribute: Merge-Parents (VERSION (FILE-ACTION) ...) ... - Attribute: New-Merge-Parents (VERSION (FILE-ACTION) ...) ... The `prcs merge' command uses the New-Merge-Parents attribute to record the history of updates to each file. Each VERSION indicates a selected version that was merged into the working files, and each FILE-ACTION records what action (delete, add, replace, merge, no action) `merge' took for each file. This information is useful in preventing confusion when the user interrupts a merge operation and then re-executes the merge. The precise format of the FILE-ACTIONS is unspecified at the moment. The `prcs checkin' command copies any New-Merge-Parents attribute in the working project descriptor into a Merge-Parents attribute in the new (checked-in) project descriptor. It discards any existing Merge-Parents attribute in the working file.  File: prcs.info, Node: Parent-Version and Descends-From attributes, Prev: Merge-Parents attribute, Up: Descriptors Parent-Version and Descends-From attributes ------------------------------------------- These attributes track the history of a project version, recording the names of one or two versions from which it was derived. They both have the syntax of Project-Version. - Attribute: Parent-Version P M N This has the same form as the Project-Version attribute (*note Project-Version attribute::.), except that for an initial version (unrelated to any prior version), each of P, M, and N is `-*-'. The Parent-Version defines the "ancestors" of a version in the repository as follows: * A version is an ancestor of itself. * The Parent-Version attribute of a version names an ancestor of that version. * Ancestry is transitive: any ancestor of one of V's ancestors is also an ancestor of V. The number of Parent-Version attributes that must be traversed to find an ancestor of V is called the "distance" of that ancestor from V. Given two versions in a repository, any version that is an ancestor to both is called a "common ancestor". The common ancestor that is least distant from either is called the "nearest common ancestor". Each `prcs checkin' sets Parent-Version to name one of the versions from which the newly checked-in version is derived. In the usual, simple case, where one checks in a sequence of versions with the same major version name, `prcs checkin' simply copies the old Project-Version attribute in the working project descriptor (called WV below) to the Parent-Version in the new descriptor. In the general case, we are checking in a version whose name is to be TV ("target version"). Suppose that TV' is the last minor version with the same major version name as TV. Then, * If the New-Merge-Parents attribute is null, then the new Parent-Version is set to the nearest common ancestor version of WV and TV', if any, and otherwise to WV. *Note Merge-Parents attribute::. * If the New-Merge-Parents attribute is non-null, then the new Parent-Version is set to the most recent common ancestor of the last New-Merge-Parents version and TV', if any, and otherwise to WV. - Attribute: Descends-From P M N The Parent-Version attribute records one source for the contents of a version (*note Parent-Version and Descends-From attributes::.). In some cases, however, this does not tell the entire story. If the Parent-Version (as computed above) differs from WV, then `prcs checkin' records WV in the Descends-From attribute. Otherwise, it records no Descends-From attribute, or sets a null Descends-From attribute (in which P, M, and N are `-*-').  File: prcs.info, Node: Keywords, Next: Subprojects, Prev: Descriptors, Up: Top Keywords ******** Files in a project may contain instances of keywords that (in effect) `prcs checkin' will replace with certain information. Conceptually, upon checkin, each keyword instance in every file of the project (not just those listed in the checkin subcommand) is updated as described below with the value of its keyword in the new project version. As a performance consideration, however, this is implemented in such a way that partial checkins only have to examine the files that are listed in the checkin subcommand (*note Keywords and File Identifiers::.). There are two forms of keyword instance: simple and formatted. A simple keyword instance has one of the forms $KEYWORD$ $KEYWORD: DATA$ This syntax is strict: PRCS does not recognize a keyword when there is whitespace on either side (separating it from the dollar sign that precedes it or the dollar sign or colon that follows). There may not be newlines anywhere in the keyword instance. If the keyword is one that PRCS recognizes, other than `Format', `prcs checkin' replaces the instance with an instance of the second form, with the data part depending on the particular keyword. Formatted keyword instances allow a more flexible replacement format. * Menu: * Recognized Keywords:: Keywords that PRCS knows about, and their meanings * Formatted Keyword Instances:: How to get keyword replacement data inserted without the usual surroundings * Keywords and File Identifiers:: Subtle details about keyword replacement semantics.  File: prcs.info, Node: Recognized Keywords, Next: Formatted Keyword Instances, Prev: Keywords, Up: Keywords Recognized Keywords =================== PRCS understands the following keywords. Others are ignored (their instances are left unchanged). Instances of the Source and ProjectHeader keywords change whenever the file is moved from one directory to another within a project. Instances of Project, ProjectDate, ProjectAuthor, ProjectMajorVersion, ProjectMinorVersion, ProjectVersion, and ProjectHeader can change even when the file containing them does not, since they depend on the project, not the file. These keywords are known collectively as "project-related keywords". Author The login of the user who created this checked-in version of the file. Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword. Date The date and time at which this version of the file was checked in. Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword. Basename The base name of the file, as it appears in the Files attribute. Revision A notation that serves as a revision number for this file (it is independent of the project's version number, and changes only when the file changes). Changes in a file due solely to project-related keyword replacement do not affect the value of this keyword. Id A standard header combining the Basename, Revision, Date, and Author. Source The full name of the file, as a pathname relative to the root of the project's directory tree. Project The name of the project containing the file version. ProjectDate The date and time the project containing this file version was checked in. ProjectAuthor The login name of the user who checked in the project version containing this file version. ProjectMajorVersion The major version name of the project version containing this file version. ProjectMinorVersion The minor version name (a number) of the project version containing this file version. ProjectVersion The complete version designator for this project version. It has the form M.N, where M is the major project-version name and N is the minor project-version name. ProjectHeader A standard header combining the Project, ProjectVersion, ProjectDate, and ProjectAuthor.  File: prcs.info, Node: Formatted Keyword Instances, Next: Keywords and File Identifiers, Prev: Recognized Keywords, Up: Keywords Formatted Keyword Instances =========================== Sometimes, you want keyword replacement data to appear without the leading `$keyword:' and trailing `$'. A formatted keyword instance allows this. An appearance in your file of $Format: "STRING"$ STRING will cause `prcs checkin' to replace the next line of the source file (i.e., the line after the second `$') with STRING, after first making modified keyword substitutions in it. Specifically, each instance of `$KEYWORD$' in STRING (for which KEYWORD is one of the recognized keywords) is replaced by just the data that would be placed to the right of the `:' in a simple keyword instance. The `Format' instance itself is not altered--only the subsequent line. For example, if a file in a project contains /* $Format: "static char* version = \"$ProjectVersion$\";"$ */ static char* version = "x.x"; then the version of the file checked in for version 1.2 of the project will contain /* $Format: "static char* version = \"$ProjectVersion$\";"$ */ static char* version = "1.2"; The format string may not contain newlines. It may contain quotation marks if they are stropped with a backslash, as in the example above. In general, the backslash quotes the succeeding character. Any keyword instances on a list after a `Format' instance are ignored (that is, they are left unchanged by keyword substitution). Any nested instance of `Format' is also left unchanged.  File: prcs.info, Node: Keywords and File Identifiers, Prev: Formatted Keyword Instances, Up: Keywords Keywords and File Identifiers ============================= The actual content of a working file upon checkout depends on two things: the internal file identifier recorded for it and the contents of the project descriptor. The internal file identifier designates a particular "raw" file contents stored in the repository that never changes once it is first created. The checked out file consists of this contents modified by keyword replacement. If the same file identifier is used for two files in two different projects, the checked-out working files will differ in the values supplied for these keywords. This is a subtle point, but it is significant when you copy a file identifier from one project to another. For example, suppose that file F in version 1.2 of project P contains the line /* $ProjectVersion: 1.2$ */ and that its entry in the Files attribute of P.prj is (F (P/0_F 1.1)) If you decide to rename F to G for the next version of P, you can do so by changing its line in the Files attribute to (G (P/0_F 1.1)) When you check the project back in, creating version 1.3, this same line will be retained as its file identifier (assuming, that is, you made no changes to G or its former incarnation, F). However, in version 1.3 of P, G will contain /* $ProjectVersion: 1.3$ */ That is, PRCS actually performs all keyword replacement on check-out (think of it as lazy replacement). It only makes a user-visible difference in the handling of internal identifiers. It also has a considerable effect on the performance of partial checkins (those that contain a list of specific files and directories to check in, and copy all unmentioned files from file identifiers listed in the Files attribute). Because PRCS does not have to examine the files excluded from the file list for keywords, it can process them very quickly.  File: prcs.info, Node: Subprojects, Next: Importing Project Versions, Prev: Keywords, Up: Top Subprojects *********** You can use PRCS to "bundle together" a set of projects (so that they may be released together, for example). Suppose that P is the name you want to give to the (new) combined project, with P1, P2, and P3 the names of the subprojects. To create the initial version of P, take the following steps. 1. Go into a directory that is to serve as the working directory for P. 2. Use prcs checkout to create a `.prj' file for P. 3. For each subproject, Pi, create a subdirectory Pi, and in that subdirectory, execute the command % prcs checkout -r... Pi Pi.prj (replacing `...' with the appropriate version specifier). This checks out the `.prj' file for Pi into Pi. 4. Modify the Files entry for P to list the `.prj' files for the Pi. 5. Check in P. To create a working copy of this version of P (including working copies of all its subprojects' files), use the following (Bourne shell) commands (I'll assume that 0.1 is the version name for P). $ prcs checkout -r0.1 P $ for i in P1 P2 P3; do > (cd $i; prcs checkout $i) > done Obvious modifications of this procedure will serve to create updated versions of P. With a little care, we can automate this process a bit further. Suppose that we establish a convention that we tag each subproject descriptor file in the Files list of P: (Files ... (P1 (...) :tag=project) (P2 (...) :tag=project) (P3 (...) :tag=project) ... ) This allows a general-purpose version of the checkout procedure above, one that does not require that we remember the names of all the subprojects: % prcs execute -r0.1 P --match :tag=project -- prcs checkout {}