This is cssc.info, produced by makeinfo version 4.1 from cssc.texi. INFO-DIR-SECTION Miscellaneous START-INFO-DIR-ENTRY * cssc: (cssc). The GNU work-alike replacement for SCCS. END-INFO-DIR-ENTRY This file documents the the GNU `cssc' package for working with SCCS files. Copyright (C) 1997,1998,1999,2000,2001,2002 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: cssc.info, Node: Top, Next: Overview, Up: (dir) This file documents the the GNU `CSSC' package, which is a work-alike for the traditional Unix SCCS suite. This is edition 1.05, for CSSC Version 0.14alpha-pl1. * Menu: * Overview:: Preliminary information. * Interface:: How to use the suite. * Invoking Programs:: How to run the individual CSSC programs. * Filenames:: Names of files used by CSSC. * File Format:: Description of the SCCS file format * Interoperability:: Interoperating with other versions of SCCS. * Environment:: How environment variables affect CSSC. * Incomplete:: Missing Features. * Year 2000 Issues:: Status of CSSC with regard to the Millennium. * Testing:: How to run the test suite and write new cases. * Problems:: Reporting bugs. * Copying:: How you can copy and share `CSSC'. * BSD Code:: Parts of the code are from BSD. * Glossary:: Definition of some terms relating to CSSC. * Concept Index:: Index of concepts.  File: cssc.info, Node: Overview, Next: Interface, Prev: Top, Up: Top Overview ******** The GNU CSSC program is designed to be a compatible replacement for the traditional Unix SCCS suite. This documentation is horrendously incomplete since this package is still under development. While it is strongly suggested that new projects not use this package, sometimes existing projects require the use of SCCS files. While conversion to other formats is possible, this is also sometimes impractical. See the documentation for CVS and RCS. *Note What is CVS?: (cvs)What is CVS?. See also the manual pages for RCS. GNU CSSC is published under the GNU General Public License, which is designed to protect your rights, as the user of this program. You have the right to modify this program, and distribute it. You also have responsibilities to those to whom you distribute copies, as detailed in the license. *Note GNU General Public License: Copying. GNU CSSC was originally based on the public-domain package MySC, which was written by Ross Ridge. The enhancement work was done by James Youngman. The `sccs' program itself and its accompanying documentation `sccs.me' and `sccs.1' were written by Eric Allman, and are covered by the BSD license (*note BSD Code::).  File: cssc.info, Node: Interface, Next: Invoking Programs, Prev: Overview, Up: Top How to use the suite ******************** By far the easiest way to use CSSC (or indeed SCCS) is to use VC-mode in GNU Emacs. *Note Version Systems: (emacs)Version Systems. If you can't use VC-mode, the BSD command `sccs' is a good interface to the SCCS suite (and hence CSSC). Other than that, you will need to use each of the programs in the suite individually.  File: cssc.info, Node: Invoking Programs, Next: Filenames, Prev: Interface, Up: Top Invoking CSSC programs ********************** The menu items are arranged in approximate order of frequency of use, except `admin', which is first because you have to use it to start with. * Menu: * admin:: Creating and administering SCCS files. * sccs:: A more helpful front-end from BSD. * get:: Checking-out a version for compilation or editing. * delta:: Checking-in a revised version. * what:: Identifying versions of files. * sccsdiff:: Finding the changes between two revisions. * unget:: When it all goes horribly wrong... * prs:: Displaying the revision history of a file. * sact:: Show which SCCS files are being edited. * rmdel:: Expunging changes or backing out of a check-in. * cdc:: Changing revision comments after the fact. * prt:: Printing the delta table of a file. * comb:: Creating a shell archive of an SCCS file. * help:: Unimplemented hints on obscure error messages. * val:: Validating an SCCS file for integrity.  File: cssc.info, Node: admin, Next: cdc, Up: Invoking Programs `admin' ======= To create an SCCS archive of a source file `foo.c', do admin -ifoo.c s.foo.c This creates the archive file `s.foo.c' and initialises it with the current contents of your source file, `foo.c'. If you use Emacs as your editor, you can just use `C-x v i' instead. Another frequently-used option is `-b', which indicates that the file is to be treated as a binary file rather than as text. You might want to do this because the file actually contains binary data, or just characters that have other meanings within an SCCS file, for example `^A', the character whose code is 1. `-aXXX' Add user or group XXX to the list of those authorised to check revisions in (that is, use `get -e' and `delta'). Users must be specified by name and groups by numeric ID. This feature is often used in conjunction with a setuid installation of the `sccs' driver program (*note sccs::). This is not a good idea because the CSSC suite is not secure (*note Known Problems::). `-b' Ensure that the file is encoded as a binary file. This option only works in conjunction with the `-n' or `-i' options. This option is not available if binary file support is turned off (*note Interoperability::) though this can be re-enabled if necessary with an environment variable (*note Environment::). `-dF' Delete flag F from the flags present in the file (*note Flags::). `-eXXX' Erase the specified user or group from the list of those authorised to check revisions in or out. `-fF[XXX]' Add the flag F (with optional value XXX) to the file's flags (*note Flags::). For example, `-fv/tmp/checkit' sets the MR-validation flag to `/tmp/checkit'. `-h' Check the SCCS file. The exit value will be 0 if the file is valid, and not 0 otherwise. Warning messages may be emitted, indicating things that may or may not be wrong (e.g. time apparently going backwards), but if no actual errors are encountered, the exit value will still be zero. The genuine SCCS suite invokes `val' (*note val::) to perform this validation, but at the moment, `admin' only checks the checksum. This option is silently incompatible with all the other options; the specified SCCS files will not be modified by `admin' if the `-h' flag is used. `-iFOO' Initialise the SCCS file with the contents of the file FOO. If no argument is given, read from standard input. This implies the `-n' option. `-mMR-LIST' When initialising a file, add the specified list of MR numbers (*note Modification Request Numbers::) to the delta commentary for the initial version. This list can be empty. The specified MRs are validated according to the setting of the V flag, which should be set (*note Flags::). If the V flag is set but has no value (i.e. is set to the empty string), validation silently succeeds. If the V flag is not set, the `-m' option causes `delta' to fail. `-n' Create a new SCCS file. Unless `-i' is also used, the new file will contain control information but the body will be initially empty. `-rN' Set the initial release number to N. The initial level within that release is always 1. Some versions of SCCS allow you to specify actual an actual SID here (for example `1.2' or `1.8.2.1'). CSSC also allows this, but emits a warning. If you use this option, you must also use the `-i' option or the `-n' option. If the initial SID you specify is not on the trunk, some tools will fail to work with the resulting file. `-tDESC' Read in descriptive text for this file from `DESC'. This replaces any existing description. If no argument, remove any existing description (this is illegal if `-i' or `-n' is used). `-V' Display version information. `-yADAYADA' When initialising a file, set the comment for that delta to ADAYADA. If the option is given just as `-y', the comment is recorded as empty. The following word in the argument list is not used as the comment. _Note that this behaviour is different to most Unix programs, but is the same as the behaviour of traditional SCCS_. `-z' Fix the checksum information. The SCCS file is still validated by CSSC; apart from possibly having an incorrect checksum, the s-file must be valid. If you use this option on an SCCS file which really is invalid, then the attempt may fail or _silently write out a valid but incorrect file_. Use this option with _extreme_ care.  File: cssc.info, Node: Flags, Next: Modification Request Numbers, Up: admin SCCS file flags --------------- Flags are set and cleared with the `admin' program. *Note admin::. Boolean Flags ............. `b' Enable branch deltas: this enables the `-b' option of get (*note get::). `e' This flag indicates that the file controlled by this SCCS file is a binary file, and hence the body of the SCCS file is uuencoded. This flag can only be set with the `-b' option of `admin' at the time the file is created (or if admin takes it upon itself to set this flag automatically), and cannot be unset. The circumstances under which this can happen are discussed in *Note Interoperability::. `i' Make `get' and `delta' exit unsuccessfully when the `Warning: No id keywords' message is issued. `j' Enables concurrent updates: if you try to get a revision for editing, this normally fails if another user already has the file locked. Setting the `j' flag overrides this. `n' Create empty releases when the `-r' option to `get' is used to skip releases. These empty releases can later serve as branch points. Other Flags ........... `c' Set the release ceiling. Releases higher than the ceiling cannot be checked out. `f' Set the release floor. Releases lower then the release floor cannot be checked out. `d' Set the default delta which is used when the `get' command is given without the `-r' option. The default behaviour for `get' is defined in *Note get::. `l' Set the locked release list. These releases cannot be checked out with `get -e'. The special value `a' denotes all releases. `q' Sets the value substituted for the `%Q%' keyword as described in *Note Keyword Substitution::. This flag is referred to in the output of SCCS as `csect name', and is variously referred to here as that, or the "user flag" or the "Q flag". `m' Sets the overridden value for the `%M%' keyword as described in *Note Keyword Substitution::. `t' Sets the value for the `%Y%' keyword as described in *Note Keyword Substitution::. `v' Sets the name of the program used to validate MR (modification request) numbers; MRs are described in *Note Modification Request Numbers::. This flag can be set to the empty string, in which case MRs are allowed and the validation silently succeeds without any program being run.  File: cssc.info, Node: Modification Request Numbers, Prev: Flags, Up: admin Modification Request Numbers ---------------------------- MRs are identifiers that can be specified when checking in a revision using `delta' (or even using `admin', when creating a file). If the `v' ("validate") flag is set, the user running `delta' is prompted for MR numbers as well as revision comments. If this flag is not set, no validation is performed and no MR numbers are prompted for. If the `-m' option is given on the command line for `delta', the user is not prompted. MR numbers are not required by CSSC to be actual numbers; they may contain any non-whitespace printable characters; other implementations may not be so flexible. MR numbers are frequently used to tie code revisions to other things, for example engineering change management documents or bug-tracking databases. If your change management systems are computer-based, you can use the validation program to ensure that the offered MR number is valid and that the calling user is allowed to change the file. The first argument passed to the validation program is the name of the g-file and the following arguments are the MR numbers offered. The validating program should return zero if all the MR numbers are acceptable. One might think that it would be useful to associate the MR number with the action of checking out for a modification (`get -e'), but this is not possible with SCCS. If you want to do that kind of thing, you must use a more advanced system, for example GNU CVS.  File: cssc.info, Node: cdc, Next: comb, Prev: admin, Up: Invoking Programs `cdc' ===== The `cdc' command allows you to add comments to the commentary for a particular delta in an SCCS file. Any delta in the file (other than ones removed with `rmdel') can be modified. If a comment is not specified on the command line, comments are accepted via standard input. If the special argument name `-' is being used, this means that a list of files to operate on is being read from standard input, and therefore the `-y' option is mandatory in this case. The new comments are prepended to the existing comment for that delta, followed by a line of the form `*** CHANGED *** yy/mm/dd hh:mm:ss who'. This is followed by the original comment. Comments cannot be removed using `cdc', but they can be added. Only three options are supported:- `-mMR-LIST' The specified (space-separated) list of MRs is added to the MR-list for the relevant delta. If more than one MR number is to be added, the whole option should be quoted, to protect the spaces. If an MR is prefixed with an exclamation mark (`!'), then the indicated delta is removed from the existing list of MRs for the delta. The file comment is modified to indicate what MRs have been removed. If an MR to be removed is in fact not present in any case, this is silently ignored. and the comment is not updated for that MR. If you do not also want to add to the comment for the delta, specify an empty comment option (that, is, a bare `-y'). `-rSID' This indicates which delta is to be changed. It must refer to an existing delta in the file, which has not been removed with `rmdel'. `-yCOMMENT' This option introduces a comment to be added to the commentary for the specified SID. If more than one line is needed, it is a good idea to enclose the option in quotation marks to ensure that the shell includes them in the argument passed to `cdc'. An empty `-y' option can be used to indicate that the commentary for this delta is not to be modified (this is only useful when the `-m' option is used). If the `-y' option is not given, the user is prompted for comments.  File: cssc.info, Node: comb, Next: delta, Prev: cdc, Up: Invoking Programs `comb' ====== This program is not yet implemented or documented in the manual, there are no tests for it in the test suite yet, but it is part of SCCS so it will eventually be implemented.  File: cssc.info, Node: delta, Next: get, Prev: comb, Up: Invoking Programs `delta' ======= The `delta' command is used to add a new revision to the ones already stored in an SCCS file. Before being able to do this you need to run `get -e' to check the file out for editing. A new revision is created by the `delta' program. These revisions are each identified by a unique "SID". A SID looks like `1.2.3.4', where the four numbers are the "release", "level", "branch" and "sequence" numbers. New revisions on the main sequence (the "trunk") have no branch or sequence numbers and so just have two number components (`1.2', for example). When a new version is checked in, `delta' usually prompts for comments describing the changes just made. At this point you can enter any comments, separating lines with backslash-newline pairs. An unescaped newline terminates the comment, allowing operation to continue. Sometimes, running `delta' results in the creation of a branch in the SCCS file; this is controlled by the `get' command at the time the file is checked out for editing (*note branches::). The `delta' program checks to see if you are authorised to check in a delta to this file. The list of authorised users can be maintained with the `admin' program (*note admin::). If the MR-validation flag (*note Flags::) is set, you must also supply a valid MR-number in order to be able to check in your change. * Menu: * Basic Usage: delta usage. Frequently-used `delta' commands * Options: delta options. Full list of options  File: cssc.info, Node: delta usage, Next: delta options, Up: delta Basic usage for `delta' ----------------------- Although there are several valid command-line options for `delta', they are not frequently used; the most common usage of delta is delta SCCS/s.umsp.c and this command simply applies the changes to the file `umsp.c' to the SCCS file which tracks it. Though it is possible to specify the comment and MR-number for this change using command-line options, it's more common to type them when prompted, unless `delta' is being driven by another program; either way, it's unusual to specify options for `delta' on the command line. Note that the filename you specify on the command line is that of the SCCS file, not the filename of the working file. The BSD wrapper program, sccs(1), will guess the correct filename for you, but this doesn't happen unless you do actually invoke it (`sccs delta umsp.c' for example).  File: cssc.info, Node: delta options, Prev: delta usage, Up: delta Options for `delta' ------------------- `-gSID-LIST' The specified list of deltas are to be ignored when the version being checked in is retrieved using `get'. The list is a list of SIDs separated by commas, or can contain ranges of SIDs (these are indicated by a dash). Untested. `-mMR-LIST' Specify the indicated list of MR numbers (separated by spaces) for this change (*note Modification Request Numbers::). If the V flag (*note Flags::) is set, `delta' will prompt for MR numbers if none are given on the command line. If the V flag has a non-empty value, as opposed to just being set, then the supplied list of MR numbers will be verified using that program. The requested delta will not be made if this validation fails (the validation program returns a nonzero exit status). When the V flag is set, deltas _must_ be checked in using this flag. If you are using Emacs's vc-mode, you can do this by setting the variable VC-CHECKIN-FLAGS to `"-m2677"' if the MR with which you are working is numbered 2677, for example. `-n' If this option is given, the edited file is not deleted once processing has succeeded. The edited file is referred to as the "g-file", since it is the file which was previously "gotten" by the `get' command. `-p' Display the differences between the old and new versions of the file during processing. The output of `diff' is echoed on the standard output. Untested. `-r' If several versions are checked out, the `-r' command-line option is used to specify which checked-out version this change is in reference to. When `get' is used to check out a version for editing, it announces two SIDs:- 3.1 new delta 3.2 402 lines One identifies the version forming the basis of the change, and the other specifies the SID that the new version will be assigned once it is checked in again. Either of these two SIDs (in this case, 3.1 or 3.2) can be used for the `-r' option of `delta'. Untested. `-s' Suppress warning or confirmation messages. Error messages go to standard error. Untested. `-y' Specify a comment for the revision log. This option is usually quoted to protect the spaces contained in it. An empty comment can be specified by just using a naked `-y'. If this option is not given on the command line, `delta' will prompt the user for a comment.  File: cssc.info, Node: get, Next: help, Prev: delta, Up: Invoking Programs `get' ===== The `get' command is to retrieve previous revisions from an SCCS file. With the `-e' option, it also locks the gotten revision so that a modified version can be checked in later using `delta'. * Menu: * Basic Usage: get usage. Frequently-used `get' commands * Options: get options. Full list of options. * Branches: branches. How branches are made. * Keywords: Keyword Substitution. Keyword Substitution * Included Excluded and Ignored deltas:: Here Be Dragons...  File: cssc.info, Node: get usage, Next: get options, Up: get Basic Usage for `get' --------------------- There are very few common basic usage patterns for `get'. Below, `s.foo.c' denotes the name of any existing SCCS file. `get s.foo.c' Get a copy of the most recent trunk revision of `s.foo.c' into the file `foo.c'. `get -Gbar s.foo.c' Get a version from `s.foo.c', into `bar' rather than the default `foo.c'. The file produced by `get' is often referred to as the "g-file". `get -r1.3 s.foo.c' Get revision 1.3 from `s.foo.c' into `foo.c'. The `-G' option can be used to set the name of the gotten file. `get -p s.foo.c' Get the most recent trunk revision, and print it on standard output. The `-r' option could also be used to specify some other revision. Unless you specify the `-k' or `-e' option, the retrieved file will be created read-only.  File: cssc.info, Node: get options, Next: branches, Prev: get usage, Up: get Options for `get' ----------------- Full description of options `-aN' Retrieve the version corresponding to the delta sequence number N. Mainly for use by other programs in the suite. `-b' Create a new branch when the resulting file is checked back in. Used with the `-e' option. If the `-e' option is not given, or if the `b' (branch) flag is not set in the SCCS file, this option has no effect; a branch is not made. If the version to be checked out for editing has a successor, a branch is created whether or not the `-b' flag is present (*note branches: branches.). `-cwhen' Get the version that was current at the time specified by when. The format of the argument is [cc]yy[mm[dd[hh[mm[ss]]]]]. Any fields omitted (except "cc") assume their maximum possible values so that if you specify `-c92', you get the latest version which was available in the year 1992. It is possible to give four digits for the year as a CSSC-specific extension, but only if none of the other fields are omitted. If only two digits are used and the resulting value is less than 69, the year is assumed to be in the twenty-first century (*note prs options:: and *Note Year 2000 Issues::). `-D' Turns on debugging output, indicating what is going on as the SCCS file is read. This option may go away or have its behaviour change in the near future. `-e' Indicates that the retrieved version is for editing. When checked back in the resulting file will have a new revision number. The retrieved file is writable, and keyword substitution does not take place. A "p-file" is created; this file contains information about what versions of the s-file are being edited, and by whom. Unless the `j' flag is set (*note Flags::), `get -e' will fail if someone else already has the file locked. If the list of authorised users in the SCCS file is not empty, you must be in that list in order to use this option. `-g' Do a dry-run, showing what version would be retrieved, but don't actually get the file. This is sometimes done by scripts, just to test the exit status. `-GFOO' Name the gotten file `FOO', instead of the default name. `-iLIST' Include the deltas for the listed SIDs. See also `-x'. `-k' Avoid doing keyword substitution (*note Keyword Substitution::). This is assumed when `-e' is specified. The gotten file is writable. `-l' Unsupported. `-lp' Unsupported. `-m' Prepend to each line of the result the SID corresponding to the `delta' which introduced this line to the file. `-n' Precede each line of output with the module name, before any SID added with the `-m' option. `-p' Write the result to the standard output, rather than to a file. `-rX' Retrieve version X, rather than the default. `-s' Run silently. `-t' Get the "top" delta for the indicated release. The default behaviour of `get' is to get the highest revision on the trunk. The `-t' option only modifies this behaviour in the situation where the topmost trunk revision is a branch point. In this case, the `-t' option causes the topmost revision on this branch to be retrieved. In other words, the `-t' option removes the restriction that the retrieved version should be on the trunk. This option is used by `comb' (*note comb::) and by the driver program `sccs' from BSD (*note sccs::). `-V' Show version information. `-wXXX' When performing keyword substitution (*note Keyword Substitution::), use XXX rather than `%Z%%M% %I%' as the substitution value for %W%. `-xLIST' Exclude the indicated deltas from the result. Deltas are indicated by specifying the SID at which they arrived in the file.  File: cssc.info, Node: branches, Next: Keyword Substitution, Prev: get options, Up: get Making Branches --------------- Normally, editing revision 1.1 of a file produces revision 1.2. Editing that produces revision 1.3, and so on. Sometimes, however, we need to make a change to an earlier version which has already been superseded. This might happen, for example, when a bug has been reported in a released version of a file; a rapid bug-fix is required, but you're in the middle of working towards a new release. A viable strategy is to make a branch at the previously-released version, modify that to fix the bug (and release this bug-fix). Meanwhile, development can be continued along the "main trunk", and the same bug-fix can be incorporated in this, ready for the next release later on. When you check out a version of a file for editing, CSSC tells you what the SID of the new version will be. For normal progress along the trunk, the "level number" is incremented. This is the second numeric element of the SID. In general, a SID is composed of four numbers `R.L.B.S', where "R" stands for "Release", "L" stands for "Level", "B" stands for "Branch", and "S" stands for "Sequence number" (not the same as the sequence numbers produced in the output of `prt'). Trunk revisions have only two components; you can think of the branch and sequence numbers as being zero. Non-trunk revisions have four components. When a branch is created from an existing SID, the release and level numbers are copied, the branch number is set to the lowest unused value for that release and level, and the sequence number is set to one. Hence the first branch from version 1.1 will be version 1.1.1.1, and if a branch is made from that, its SID will be 1.1.2.1. Branches are made from any given version when that version already has a successor. For example, a `get -e' on version 1.1 will result in a branch (1.1.1.1) if version 1.2 exists, and a `get -e' on version 1.2.1.1 will result in a branch (1.2.2.1) if version 1.2.1.2 exists. If the "enable branches" flag is set, it is also possible to make branches for revisions that do not have successors. This is done with the `-b' flag of `get'.  File: cssc.info, Node: Keyword Substitution, Next: Included Excluded and Ignored deltas, Prev: branches, Up: get Keyword Substitution -------------------- Keyword substitution is performed unless the `-k' option or the `-e' option is given to `get'. *Note what:: contains a keyword substitution example. The keywords are all of the form `%x%' where x stands for an upper-case letter, one of: A Expands to the same as `%Z% %Y% %M% %I% %Z%'. B The branch number of the gotten version C Current line in the output file D The date at the time the file was gotten, in the form yy/mm/dd. The year is always represented as two digits but this is not ambiguous since the two-digit year is no later than 2068 (*note Year 2000 Issues::). E The date that the newest delta in the gotten file was applied, yy/mm/dd. The year is always represented as two digits but this is not ambiguous since the two-digit year is no later than 2068 (*note Year 2000 Issues::). F Name of the SCCS file, for example `s.foo.c'. G As for %E%, but in the US format mm/dd/yy. H As for %D%, but in the US format mm/dd/yy. I Expands to the same as %R%.%L%.%B%.%S%, that is, the SID of the retrieved version. L The level number of the retrieved version. M Module name: the value of the `m' (module) flag, or the base name of the SCCS file with the `s.' removed if the module flag is unset. P Full name of the SCCS file. Q Value of the `q' flag. The `q' flag has no other purpose, and can be set with `admin -fqfoo'. *Note Flags::. R Release number of the retrieved version. S Sequence number of the retrieved version. T Current time (hh:mm:ss) when the file was retrieved, see %D% and %H%. W Expands to %Z% %M% %I% or the argument for the `-w' flag, if given. Y Value of the `t' (module type) flag. Z The literal string `@(#)'. *Note what::.  File: cssc.info, Node: Included Excluded and Ignored deltas, Prev: Keyword Substitution, Up: get Included, Excluded and Ignored deltas ===================================== This section describes how included, excluded and ignored deltas are handled by CSSC. Little documentation is available on how SCCS handles this, and so while this section describes how CSSC works, it may in fact not be an accurate description of how CSSC _should_ work. If you spot a defect in this section (or of course any other section) of the CSSC manual, please report this as a bug (*note Problems::). The Usual Case -------------- The usual case is where none of the deltas in the SCCS file has any included, excluded or ignored deltas. All the lines in the body of the SCCS file are there because they were first inserted by a particular delta. All of these lines are copied through to the gotten file, unless they are deleted by a later delta. For example if an SCCS file contains deltas 1.1 and 1.2, then all the lines from delta 1.2 will be included, and all the lines from delta 1.1 which are not deteled in version 1.2 are also included. Included Deltas --------------- Normally the contents of the gotten delta is included in the output, along with all the non-deleted lines of its ancestors. However, a delta can also specify that some other delta should be included. This really only makes a difference when there is a branch in the file. For example, if delta 1.5 includes 1.3.1.5, then the gotten file will include the contents of versions 1.1 through to 1.5, plus the contents of the 1.3.1 branch up to and including 1.3.1.5. Lines which were (say) added in 1.2 but delted in 1.3.1.1 will not appear in the output, since we have included a delta that deletes them. Excluded Deltas --------------- Excluding a delta is, unsurprisingly, more or less the opposite of including one. The exclusion of a delta supercedes the inclusion of a delta. One might specify, for example, that delta 1.6 should exclude delta 1.5 (for example to back out of any changes it made). Exclusion can also be used to reverse the effect of an inclusion. Suppose that delta 1.6 in the example from the section above excludes 1.3.1.5, then 1.6 will include the contents of deltas 1.1 through to 1.4, plus the contents of delta 1.5 itself, but it will not include the data from the 1.3.1 branch that would have been used if we had gotten delta 1.5. Ignored Deltas -------------- Ignored deltas are "silent"; that is, lines which are added by a delta which is (explicitly or implcitly) included will not appear in the gotten file. Conversely, lines deleted by an ignored delta will still appear in the gotten file.  File: cssc.info, Node: help, Next: prs, Prev: get, Up: Invoking Programs `help' ====== This module is not implemented, and it probably will never be, because it exists to translate the sometimes obscure error messages produced by (genuine) SCCS. These messages come with identifying codes (like "(ge4)"); one might type `help ge4' to translate an obscure message into a more readable message detailing what has gone wrong. The problem with this approach is that it results in a program called `help' on the user's path. When a naive user types `help' they are probably not looking for an explanation of an obscure message from SCCS. In fact, `help' is in any case a shell builtin for GNU Bash. Explanations of any obscure or unusual error messages belong in this manual, and so no `sccs-help' program is provided or planned.  File: cssc.info, Node: prs, Next: prt, Prev: help, Up: Invoking Programs `prs' ===== The `prs' command (mnemonic: "print revision summary") prints information about an SCCS file in a user-defined format. There are options for selecting which deltas are reported on; selection is possible by check-in time or by SID. The format of the output can also be specified on the command line. All parts of an SCCS file can be dumped with `prs'. Those parts which appear once per delta can be uniquely identified by SID or by time. Typical uses for `prs' are * Producing an audit trail of who changed what, and why, for example for a software release report, or for ISO 9000 documentation. * Discovering how a particular piece of code became broken, and deducing which change broke it. The `get -m' command is also useful for this, see *Note Options for `get': get options. * Listing all changes made on Friday afternoons, as a preparation for extra checking. * Menu: * Basic Usage: prs usage. Frequently-used `prs' commands * Options: prs options. Full list of options * Keywords: Data Keywords. Data Keyword Substitution  File: cssc.info, Node: prs usage, Next: prs options, Up: prs Basic Usage for `prs' --------------------- Here are some examples of the use of prs, with explanations of what they do. `prs s.myfile.c' Show information about all the versions of `myfile.c'. `prs SCCS' Show information about all the SCCS files in the directory `SCCS'. `prs -e -d:P: s.main.c | sort -u' Show which users have made changes to main.c. `prs -l -c`date +%y%m%d --date "last week"` SCCS' Examine all the SCCS files in the directory `SCCS'. Show any deltas that have been created since last week.  File: cssc.info, Node: prs options, Next: Data Keywords, Prev: prs usage, Up: prs Options for `prs' ----------------- `-a' Include even removed deltas in the output. Removed deltas have a type "R", as output by the :DT: keyword. `-c[CC]YYMMDDHHMMSS' Specifies the time of the "cutoff". When this option is given, the delta selected by `prs' is the last one checked in before the cutoff. As usual, any fields left unspecified in the cutoff are given the maximum legal value (for example, the seconds field defaults to 59). The fields can be separated by any non-numeric character, for example `-c97/11/02-11:25:42'. As an extension specific to CSSC, if the argument contains more than twelve (12) digits, and the first four characters are all digits, it is assumed that a four-digit year form has been used. This means that you can say `-c1997/11/02-11:25:42' to mean the same as the above. In line with the X/Open CAE Specification, Commands and Utilities (version 2, September 1994, pages 588 and 361), if the century field is _not_ given and the year is less than 69, it is assumed to be a year in the twenty-first century. The X/Open document does not mandate a four-digit year specifier, but it would not make sense to apply this rule if a four-digit year is specified. *Note Year 2000 Issues::. This behaviour is usually not the one required, and hence the `-e' or `-l' options are specified too. `-dFORMAT' This specifies the data format for the output. Because the default output format is sensible, this is typically used either in a shell script which will process the output further, or by a human to retrieve information which is not shown by default. See *Note Data Keywords:: for the various keywords that can be used. Any characters in the data format which are not part of a keyword are output as well. If one specifies the `-d' option, `prs' by default only gives information about the latest delta. To restore the default behavior of showing all the deltas, use the `-e' option as well. `-e' Makes the `-c' option select deltas created at or earlier than the specified time. Makes the `-r' option select deltas before and including the one specified by the indicated SID. `-l' As the `-e' option, but select only later deltas rather than earlier ones. `-rSID' Specifies the SID for which information is provided. If blank, the latest delta is selected.  File: cssc.info, Node: Data Keywords, Prev: prs options, Up: prs Data Keywords for the `-d' option of `prs' ------------------------------------------ Global Keywords ............... These keywords expand to the same thing, no matter which version is being examined. Many of these are SCCS file flags (*note Flags::). `:BD:' Emits the body of the SCCS file, that is, the part containing all the delta information. Note that since this is dumped verbatim, it contains control characters. If you want a more readable format, consider using the `-b' option of `prt' (*note prt options::). `:BF:' Indicates the setting (`yes' or `no') of the branch flag. `:CB:' Indicates the value of the release number ceiling flag. `:Ds:' The default SID to check out (See *Note Flags:: and *Note get::). `:F:' Name of the SCCS file. `:FB:' Indicates the value of the release floor boundary flag. `:FD:' File descriptive text (*note admin::). `:FL:' List of SCCS file flags. `:J:' Value (`yes' or `no') of the joint-edit flag. `:KF:' Value (`yes' or `no') of the keyword-warning flag (*note admin::). `:LK:' Value of the locked-releases flag. `:M:' The module name (the value of the `m' flag). `:MF:' The value (`yes' or `no') of the MR validation flag (*note delta::). `:MP:' The value of the MR validation program flag (*note delta::). This is usually the name of an executable file. `:ND:' The value of the null-delta (`n') flag (`yes' or `no'). `:Q:' The value of the (user-defined) Q flag (arbitrary one-line text). `:PN:' The full path name of the SCCS file. `:UN:' List of users authorised to make deltas to this file (one per line). This list can be modified with the use of the options `-a' and `-e' of `admin'; if this list is empty, any user is allowed to use `delta' on this file (subject to the usual file permissions checks made by the operating system). However, in this case the `UN' data keyword somewhat curiously expands to `none'. `:Y:' Value of the module-type flag. The `:BD:', `:FD:', `:FL:' and `:UN:' keywords from this section may expand to strings containing newlines. Version-specific Keywords ......................... These keywords expand to data that is specific to a particular version. `:A:' Expands to `:Z::Y: :M: :I::Z:', useful for `what'. `:B:' Branch number of SID `:C:' Comments for this delta. These may extend over several lines. `:D:' Date (yy/mm/dd) that this version was checked in. Expands to `:Dy:/:Dm:/:Dd:'. The year is always represented as two digits but is not ambiguous since the two-digit year is no later than 2068 (*note Year 2000 Issues::). `:Dd:' Day-of-month on which the delta was checked in (two digits). `:Dg:' Sequence numbers of ignored deltas (separated by white space). `:DI:' Expands to `:Dn:/:Dx:/:Dg:' (sequence numbers included/excluded/ignored). `:DL:' Expands to `:Li:/:Ld:/:Lu:' (lines inserted/deleted/unchanged). `:Dm:' Month when this version as checked in (two digits). `:Dn:' Sequence numbers of included deltas (separated by white space). `:DP:' Sequence number of the delta that precedes this one. `:DS:' Sequence number of this delta. `:Dt:' Expands to `:DT: :I: :D: :T: :P: :DS: :DP:'. `:DT:' Delta type: `R' (removed) or `D' (normal). `:Dx:' Sequence numbers of excluded deltas (separated by white space). `:Dy:' Year when this version was checked in. The year is always represented as two digits but is not ambiguous since the two-digit year is no later than 2068 (*note Year 2000 Issues::). `:GB:' The body for this version, as distinct from the body of the SCCS file itself, which is obtained with `:BD:'. Keyword expansion will be performed in the same way as if `get' had been used. `:I:' The SID of this version. `:L:' The level component of the SID (that is, the second number). `:Ld:' Number of lines deleted in this version, with respect to its predecessor. `:Li:' Number of lines inserted in this version, with respect to its predecessor. `:Lu:' Number of lines unchanged in this version, with respect to its predecessor. `:MR:' The MR numbers specified when this delta was created. `:P:' Perpetrator: the login name of the user who created this delta. `:R:' The release number of the SID (the first number). `:S:' The sequence number of the SID. Don't confuse this with the delta sequence numbers (*note Delta Table::), which are internal identifiers for deltas which are output by the keywords :DI:, :Dn:, :Dx: and :Dg:. `:T:' Time that this version was checked in (`:Th:::Tm:::Ts:'). `:Th:' Hours component of check-in time (`:T:'). `:Tm:' Minutes component of check-in time (`:T:'). `:Ts:' Seconds component of check-in time (`:T:'). `:W:' Shorthand for `:Z::M::I:', suitable for `what' (*note what::). `:Z:' Expands to `@(#)' (*note what::). The `:C:', `:GB:' and `:MR:' keywords from this section may expand to strings containing newlines.  File: cssc.info, Node: prt, Next: rmdel, Prev: prs, Up: Invoking Programs `prt' ===== The `prt' command provides information about an SCCS file without modifying it. There are many options, though the default behaviour is usually appropriate. It is possible to select what revisions to print information on, by SID or by date. Some SCCS implementations lack the `prt' command, though none lack the `prs' command (*note prs::) which is otherwise quite similar. * Menu: * Basic usage: prt usage. Frequently-used `prt' commands * Options: prt options. Full list of options * Output format: prt output. The format of `prt''s output  File: cssc.info, Node: prt usage, Next: prt options, Up: prt Basic usage for `prt' --------------------- The output provided by `prt' when no options are given is sufficient most of the time, and so it's common to use it without any options:- prt s.umsp.c If you require more detail, the `-e' ("everything") option produces more detail:- prt -e s.umsp.c As usual, any argument that is the name of a directory causes all SCCS files in that directory to be processed; the special argument `-' indicates that a list of SCCS files are to be read from `prt''s standard input.  File: cssc.info, Node: prt options, Next: prt output, Prev: prt usage, Up: prt Options for `prt' ----------------- `-a' "All deltas"; this means that the output will include "removed" deltas. Removed deltas exist after `rmdel' has been used to remove a delta. `-b' Print the body of the SCCS file. This is printed in a readable format. The control character `^A' (Control-A, ASCII code 1) which starts some lines of an SCCS file is printed as three asterisks, `***'. Lines that do not start with the control character are indented by one tab stop. For encoded (binary) files, the encoded form of the file data is printed (this is what actually appears in the SCCS file itself). If you want to extract the actual body of the SCCS file, use the `:BD:' keyword of `prs' (*note Data Keywords::. `-d' Print information about the deltas in the file, as opposed to information about the SCCS file itself (for example the authorised users). This is the default behaviour. The default behaviour is turned off by the `-b', `-f', `-t' and `-u' flags, but specifying `-d' on the command line again will ensure that the delta information is printed. `-e' "Everything"; Means the same as `-i -u -f -t -d'. `-c[CC]YYMMDDHHMMSS' Specifies the time of the "cutoff". When this option is given, `prt' stops printing delta information when it reaches a SID at least as old as the cutoff. As usual, any fields left unspecified in the cutoff are given the maximum legal value (for example, the seconds field defaults to 59). The fields can be separated by any non-numeric character, for example `-c97/11/02-11:25:42'. As an extension specific to CSSC, if the argument contains more than twelve (12) digits, and the first four characters are all digits, it is assumed that a four-digit year form has been used. This means that you can say `-c1997/11/02-11:25:42' to mean the same as the above. In line with the X/Open CAE Specification, Commands and Utilities (version 2, September 1994, pages 588 and 361), if the century field is _not_ given and the year is less than 69, it is assumed to be a year in the twenty-first century. The X/Open document does not mandate a four-digit year specifier, but it would not make sense to apply this rule if a four-digit year is specified. *Note Year 2000 Issues::. The `-c' and `-r' options are mutually exclusive. `-f' Print the flags of the SCCS file (*note Flags::). `-i' Print the serial numbers of included, excluded, and ignored deltas. `-r[CC]YYMMDDHHMMSS' Specifies a cutoff, as with the `-c' option, but with the opposite sense; that is, nothing is printed for deltas that are more recent than the indicated time. The `-c' and `-r' options are mutually exclusive. `-s' Print only a summary line for each delta (that is, the MR list and comments and so on are omitted). `-t' Print the text description of the SCCS file, as set by `admin -t' (*note admin::). `-u' Print the list of users and group IDs authorised to make deltas, one per line. `-ySID' Print only information for deltas as new as the specified SID. If the argument part is empty, that is, the option used is simply `-y', the most recent delta is selected. The oder in which delta information is stored within the SCCS file is such that the SID selected by this option will be the last one printed. If the `-y' option is used in conjunction with either the `-c' or the -Y option, processing stops when either condition (date or SID match) is satisfied.