home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / rcs57pc1.zip / doc / rcs.info (.txt) < prev    next >
GNU Info File  |  1996-11-08  |  200KB  |  4,184 lines

  1. This is Info file rcs.inf, produced by Makeinfo-1.63 from the input
  2. file vc.txi.
  3.    This file documents the Revision Control System (RCS).
  4.    Permission is granted to make and distribute verbatim copies of this
  5. manual provided the copyright notice and this permission notice are
  6. preserved on all copies.
  7.    Permission is granted to copy and distribute modified versions of
  8. this manual under the conditions for verbatim copying, provided that
  9. the entire resulting derived work is distributed under the terms of a
  10. permission notice identical to this one.
  11.    Permission is granted to copy and distribute translations of this
  12. manual into another language, under the above conditions for modified
  13. versions, except that this permission notice may be stated in a
  14. translation approved by the Foundation.
  15.    Copyright (C) 1982, 1988, 1989 Walter F. Tichy.
  16.    Copyright (C)  1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
  17.    Copyright (C)  1996 Karl Heinz Marbaise
  18. File: rcs,  Node: Top,  Up: (dir)
  19.    This manual(Edition 1.0) documents version 5.7 of the Revision
  20. Control System (RCS).
  21. * Menu:
  22.    - About the manual -
  23. * About::               About the manul.
  24. * AboutDesc::           Informations about that manual.
  25. * Versions::            Versions of the troff/nroff manuals.
  26. * BugReport::           Bugs? suggestions?
  27.    - RCS - A System for Version Control -
  28. * VersionControl::      RCS - A System for Version Control.
  29. * Introduction::        Introduction to RCS.
  30. * StartRCS::            Getting started with RCS.
  31. * Identification::      Automatic Identification.
  32. * RevisionTree::        The RCS Revision Tree.
  33. * Branches::            When are branches needed?.
  34. * Deltas::              Revisions are represented as deltas.
  35. * Controversial::       Locking: A Controversial Issue.
  36. * Configuration::       Configuration Management.
  37. * Functions::           RCS Selection Functions.
  38. * MAKERCS::             Combining MAKE and RCS.
  39. * Statistics::          Usage Statistics.
  40. * Survey::              Survey of Version Control Tools.
  41.    - rcsintro - introduction to RCS commands -
  42. * rcsIntroduction::     Introduction to RCS commands.
  43. * rcsintroDesc::        Introduction to `RCS'.
  44. * rcsintroFunc::        Functions of `RCS'.
  45. * rcsintroStart::       Getting started with `RCS'.
  46. * rcsintroAutoIdent::   Automatic identification.
  47.    - Synopsis of RCS Operations -
  48. * Synopsis::            Synopsis of RCS Operations.
  49.    - ci - check in RCS revsisions -
  50. * CheckIn::             ci - check in RCS revsisions.
  51. * ciIntro::             Introduction to `ci'.
  52. * ciEnv::               Environment which can change
  53.                         the behaviour of `ci' and
  54.                         other RCS commands.
  55. * ciFileModes::         File modes.
  56. * ciFiles::             Files.
  57. * setuid use::          Using of uid.
  58. * ciExamples::          Examples.
  59. * ciDiag::              Diagnostic output of `ci'.
  60. * ciOptions::           command line options of `ci'.
  61.    - co - check out RCS revsisions -
  62. * CheckOut::            co - check out RCS revsisions
  63. * coIntro::             Introduction to `co'.
  64. * coOptions::           command line options of `co'.
  65. * coKeyword::           Keyword expansion and valid keywords.
  66. * coEnv::               Environment which can change
  67.                         the behaviour of `co' and
  68.                         other RCS commands.
  69. * coFileModes::         File modes.
  70. * coFiles::             Files.
  71. * coDiag::              Diagnostic output of `co'.
  72. * coLimits::            Limits.
  73.    - rcs - change RCS file attributes -
  74. * rcs::                 rcs - change RCS file attributes.
  75. * rcsIntro::            Introduction to `rcs'.
  76. * rcsOptions::          command line options of `rcs'.
  77. * rcsCompatibility::    Compatibility between RCS Versions.
  78. * rcsFiles::            Files.
  79. * rcsEnv::              The Environment which can change the
  80.                         behaviour of much of the RCS commands.
  81. * rcsDiag::             Diagnostic output of `rcs'.
  82. * rcsBugs::             Bugs.
  83.    - ident - identify RCS keyword strings in files -
  84. * ident::               ident - identify RCS keyword strings in files.
  85. * identIntro::          Introduction to `rcs'.
  86. * identOptions::        command line options of `rcs'.
  87. * identKeywords::       Keywords.
  88.    - rcsclean - clean up working files -
  89. * rcsclean::            rcsclean - clean up working files.
  90. * rcscleanIntro::       Introduction to `rcsclean'.
  91. * rcscleanOptions::     command line options of `rcsclean'.
  92. * rcscleanExamples::    Examples in using `rcsclean'.
  93. * rcscleanFiles::       Files.
  94. * rcscleanEnv::         The Environment which can change the
  95.                         behaviour of much of the RCS commands.
  96. * rcscleanDiag::        Diagnostic output of `rcsclean'.
  97. * rcscleanBugs::        Bugs.
  98.    - rcsdiff - compare RCS revisions -
  99. * rcsdiff::             rcsdiff - compare RCS revisions.
  100. * rcsdiffIntro::        Introduction to `rcsdiff'.
  101. * rcsdiffOptions::      command line options of `rcsdiff'.
  102. * rcsdiffExamples::     Examples in using `rcsdiff'.
  103. * rcsdiffEnv::          The Environment which can change the
  104.                         behaviour of much of the RCS commands.
  105. * rcsdiffDiag::         Diagnostic output of `rcsdiff'.
  106.    - rcsmerge - merge RCS versions -
  107. * rcsmerge::            rcsmerge - merge RCS versions.
  108. * rcsmergeIntro::       Introduction to `rcs'.
  109. * rcsmergeOptions::     command line options of `rcs'.
  110. * rcsmergeExamples::    Examples of `rcsmerge'.
  111. * rcsmergeEnv::         The Environment which can change the
  112.                         behaviour of much of the RCS commands.
  113. * rcsmergeDiag::        Diagnostic output of `rcs'.
  114.    - rlog - print log messages and other information about RCS files -
  115. * rlog::                rlog - print log messages and other
  116.                         information about RCS files.
  117. * rlogIntro::           Introduction to `rlog'.
  118. * rlogOptions::         command line options of `rlog'.
  119. * rlogExamples::        Examples.
  120. * rlogEnv::             The Environment which can change the
  121.                         behaviour of much of the RCS commands.
  122. * rlogDiag::            Diagnostic output of `rlog'.
  123. * rlogBugs::            Bugs.
  124.    - merge - three-way file merge -
  125. * merge::               merge - three-way file merge.
  126. * mergeIntro::          Introduction to `merge'.
  127. * mergeOptions::        command line options of `merge'.
  128. * mergeDiag::           Diagnostic output of `merge'.
  129. * mergeBugs::           Bugs.
  130.    ----------- Appendencies -----------
  131.    - Appendix A -
  132. * AppendixA::           Format of RCS file.
  133.    - Appendix B -
  134. * AppendixB::           Books and related manuals.
  135. * Feldman::             GNU - Make.
  136. * Hunt::                GNU - diff.
  137. * Rochkind::            SCCS.
  138. * Tichy::               Design and implementation of RCS.
  139. * Leblang::             Computer-Aided Software Engineering.
  140. * Glasser::             The Evolution of a Source Code Control
  141.                         System.
  142. * Brown::               The Clear/Caster System.
  143. * Habermann::           A Software Development Control System.
  144. * DEC::                 Code Management System.
  145. * Lampson::             Practical Use of a Polymorphic Applicative
  146.                         Language.
  147. * Tichy1::              A Data Model for Programming Support
  148.                         Environments and its Application.
  149. * Heckel::              A Technique for Isolating Differences
  150.                         Between Files.
  151. * Tichy2::              The String-to-String Correction Problem
  152.                         with Block Moves.
  153. * Index::               Concept Index.
  154. File: rcs,  Node: About,  Next: VersionControl,  Up: Top
  155. About the manual
  156. ****************
  157. * Menu:
  158. * AboutDesc::           Informations about that manual.
  159. * Versions::            Versions of the troff/nroff manuals.
  160. * BugReport::           Bugs? suggestions?
  161. File: rcs,  Node: AboutDesc,  Next: Versions,  Up: Top
  162. Description
  163. ===========
  164.    These 'texinfo' files are hand converted out of the troff/nroff
  165. files, which came with the RCS system.
  166.    This has done by hand, cause there does not exist a converter which
  167. is able to convert (nroff/troff) into GNU's 'texinfo' format (I know
  168. one, which is able to do the other way,'texinfo' to nroff).
  169.    The main reason for doing such a stupid work, is to have the opinion
  170. to convert the 'texinfo' into OS/2-IPF format.  This conversion is done
  171. by using a converter which has some problems but the result is
  172. acceptable.
  173.    The next possibility is to get a well printed manual, using TeX(I
  174. use emTeX myself).
  175.    This is the first Edition of this manual, so don't be angry about
  176. the cryptic node names within the 'texinfo' file.  That's the only way
  177. to have unique node names for alle command line options.  And by the
  178. way this is the only way to make reference to command line options of
  179. every command.
  180.    The next thing is to make this manual a little more readable, that
  181. means not to double subsection with command line options on every
  182. command (rlog, rcs, rcsdiff, ...).  The way out of this dilemma is to
  183. discribe these options within a chapter 'overall options' or 'global
  184. options' which can be used on every command(rlog, rcs, rcsdiff...).
  185. But this will be done in the next edition, if you like it.
  186.    If you like to make a printed manual yourself, you have to TeX it
  187. with the 'texinfo' macro package(V2.185), it also works with version
  188. 2.150 of the package. It should also work with edition 2 of the
  189. 'texinfo' macro package.
  190. File: rcs,  Node: Versions,  Next: BugReport,  Prev: AboutDesc,  Up: Top
  191. Versions
  192. ========
  193.    If you found newer versions of troff/nroff manual then please mail
  194. to me.
  195.    Here are the exact RCS-versions of the troff/roff pages for checking:
  196.    * Identification of the "RCS - A System for Version Control" manual
  197.      part (rcs.ms):
  198.           $Id: rcs.ms,v 5.4 1995/06/01 16:23:43 eggert Exp $
  199.    * Identification of the ci manual part(ci.1):
  200.           $Id: ci.1,v 5.17 1995/06/16 06:19:24 eggert Exp $
  201.    * Identification of the co manual part(co.1):
  202.           $Id: co.1,v 5.13 1995/06/01 16:23:43 eggert Exp $
  203.    * Identification of the rcs manual part(rcs.1):
  204.           $Id: rcs.1,v 5.13 1995/06/05 08:28:35 eggert Exp $
  205.    * Identification of the ident manual part(ident.1):
  206.           $Id: ident.1,v 5.4 1993/11/09 17:40:15 eggert Exp $
  207.    * Identification of the rcsclean manual part(rcsclean.1):
  208.           $Id: rcsclean.1,v 1.12 1993/11/03 17:42:27 eggert Exp $
  209.    * Identification of the rcsdiff  manual part(rcsdiff.1):
  210.           $Id: rcsdiff.1,v 5.5 1993/11/03 17:42:27 eggert Exp $
  211.    * Identification of the rcsmerge  manual part(rcsmerge.1):
  212.           $Id: rcsmerge.1,v 5.6 1995/06/01 16:23:43 eggert Exp $
  213.    * Identification of the rlog manual part(rlog.1):
  214.           $Id: rlog.1,v 5.9 1995/06/16 06:19:24 eggert Exp $
  215.    * Identification of the merge manual part(merge.1):
  216.           $Id: merge.1,v 5.7 1995/06/01 16:23:43 eggert Exp $
  217. File: rcs,  Node: BugReport,  Prev: Versions,  Up: Top
  218. Bugs?, suggestions?
  219. ===================
  220.    If you think you have found a bug within this manual, you could write
  221. by electronic mail a report.
  222.    Also, if you have suggestions for this manual.  Changes of chapters,
  223. sections and so on.
  224.    Do you have good examples for this manual?
  225.    Or what else you like.
  226.    Please write to me:
  227.      Karl Heinz Marbaise
  228.      Alt-Haarenerstr. 237
  229.      52080 Aachen (Germany)
  230.      
  231.      e-mail: KHMarbaise@p69.ks.fido.de
  232. File: rcs,  Node: VersionControl,  Next: rcsIntroduction,  Prev: About,  Up: Top
  233. RCS-A System for Version Control
  234. ********************************
  235.                             Walter F. Tichy
  236.                     Department of Computer Sciences
  237.                            Purdue University
  238.                      West Lafayette, Indiana 47907
  239.    An important problem in program development and maintenance is
  240. version control, i.e., the task of keeping a software system consisting
  241. of many versions and configurations well organized.  The Revision
  242. Control System (RCS) is a software tool that assists with that task.
  243. RCS manages revisions of text documents, in particular source programs,
  244. documentation, and test data. It automates the storing, retrieval,
  245. logging and identification of revisions, and it provides selection
  246. mechanisms for composing configurations. This paper introduces basic
  247. version control concepts and discusses the practice of version control
  248. using RCS.  For conserving space, RCS stores deltas, i.e., differences
  249. between successive revisions.  Several delta storage methods are
  250. discussed. Usage statistics show that RCS's delta storage method is
  251. space and time efficient. The paper concludes with a detailed survey of
  252. version control tools.
  253.    Keywords: configuration management, history management, version
  254. control, revisions, deltas.
  255.    An earlier version of this paper was published in `Software-Practice
  256. & Experience, 7 (July 1985), 637-654.'
  257. * Menu:
  258. * Introduction::        Introduction to RCS.
  259. * StartRCS::            Getting started with RCS.
  260. * Identification::      Automatic Identification.
  261. * RevisionTree::        The RCS Revision Tree.
  262. * Branches::            When are branches needed?.
  263. * Deltas::              Revisions are represented as deltas.
  264. * Controversial::       Locking: A Controversial Issue.
  265. * Configuration::       Configuration Management.
  266. * Functions::           RCS Selection Functions.
  267. * MAKERCS::             Combining MAKE and RCS.
  268. * Statistics::          Usage Statistics.
  269. * Survey::              Survey of Version Control Tools.
  270. File: rcs,  Node: Introduction,  Next: StartRCS,  Up: VersionControl
  271. Introduction
  272. ============
  273.    Version control is the task of keeping software systems consisting
  274. of many versions and configurations well organized.  The Revision
  275. Control System (RCS) is a set of UNIX commands that assist with that
  276. task.
  277.    RCS' primary function is to manage revision groups. A revision group
  278. is a set of text documents, called revisions, that evolved from each
  279. other. A new revision is created by manually editing an existing one.
  280. RCS organizes the revisions into an ancestral tree.  The initial
  281. revision is the root of the tree, and the tree edges indicate from
  282. which revision a given one evolved. Besides managing individual
  283. revision groups, RCS provides flexible selection functions for composing
  284. configurations. RCS may be combined with MAKE (*Note Feldman::),
  285. resulting in a powerful package for version control.
  286.    RCS also offers facilities for merging updates with customer
  287. modifications, for distributed software development, and for automatic
  288. identification. Identification is the `stamping' of revisions and
  289. configurations with unique markers. These markers are akin to serial
  290. numbers, telling software maintainers unambiguously which configuration
  291. is before them.
  292.    RCS is designed for both production and experimental environments.
  293. In production environments, access controls detect update conflicts and
  294. prevent overlapping changes. In experimental environments, where strong
  295. controls are counterproductive, it is possible to loosen the controls.
  296.    Although RCS was originally intended for programs, it is useful for
  297. any text that is revised frequently and whose previous revisions must
  298. be preserved.  RCS has been applied successfully to store the source
  299. text for drawings, VLSI layouts, documentation, specifications, test
  300. data, form letters and articles.
  301.    This paper discusses the practice of version control using RCS.  It
  302. also introduces basic version control concepts, useful for clarifying
  303. current practice and designing similar systems.  Revision groups of
  304. individual components are treated in the next three sections, and the
  305. extensions to configurations follow.  Because of its size, a survey of
  306. version control tools appears at the end of the paper.
  307. File: rcs,  Node: StartRCS,  Next: Identification,  Prev: Introduction,  Up: VersionControl
  308. Getting started with RCS
  309. ========================
  310.    Suppose a text file `f.c' is to be placed under control of RCS.
  311. Invoking the check-in command
  312.      ci  f.c
  313.    creates a new revision group with the contents of `f.c' as the
  314. initial revision (numbered 1.1) and stores the group into the file
  315. `f.c,v'. Unless told otherwise, the command deletes `f.c'. It also asks
  316. for a description of the group. The description should state the common
  317. purpose of all revisions in the group, and becomes part of the group's
  318. documentation. All later check-in commands will ask for a log entry,
  319. which should summarize the changes made. (The first revision is
  320. assigned a default log message, which just records the fact that it is
  321. the initial revision.)
  322.    Files ending in `,v' are called RCS files (v stands for Rersions);
  323. the others are called working files. To get back the working file `f.c'
  324. in the previous example, execute the check-out command:
  325.      co  f.c
  326.    This command extracts the latest revision from the revision group
  327. `f.c,v' and writes it into `f.c'. The file `f.c' can now be edited and,
  328. when finished, checked back in with `ci':
  329.      ci  f.c
  330.    `Ci' assigns number 1.2 to the new revision.  If `ci' complains with
  331. the message
  332.      ci error: no lock set by <login>
  333.    then the system administrator has decided to configure RCS for a
  334. production environment by enabling the `strict locking feature'. If
  335. this feature is enabled, all RCS files are initialized such that
  336. check-in operations require a lock on the previous revision (the one
  337. from which the current one evolved).  Locking prevents overlapping
  338. modifications if several people work on the same file. If locking is
  339. required, the revision should have been locked during the check-out by
  340. using the option `-l':
  341.      co -l  f.c
  342.    Of course it is too late now for the check-out with locking, because
  343. `f.c' has already been changed; checking out the file again would
  344. overwrite the modifications. (To prevent accidental overwrites, `co'
  345. senses the presence of a working file and asks whether the user really
  346. intended to overwrite it.  The overwriting check-out is sometimes
  347. useful for backing up to the previous revision.) To be able to proceed
  348. with the check-in in the present case, first execute
  349.      rcs  -l  f.c
  350.    command retroactively locks the latest revision, unless someone else
  351. locked it in the meantime.  In this case, the two programmers involved
  352. have to negotiate whose modifications should take precedence.
  353.    If an RCS file is private, i.e., if only the owner of the file is
  354. expected to deposit revisions into it, the strict locking feature is
  355. unnecessary and may be disabled. If strict locking is disabled, the
  356. owner of the RCS file need not have a lock for check-in. For safety
  357. reasons, all others still do.  Turning strict locking off and on is
  358. done with the commands:
  359.      rcs  -U  f.c   and rcs  -L  f.c
  360.    These commands enable or disable the strict locking feature for each
  361. RCS file individually. The system administrator only decides whether
  362. strict locking is enabled initially.
  363.    To reduce the clutter in a working directory, all RCS files can be
  364. moved to a subdirectory with the name `RCS'. RCS commands look first
  365. into that directory for RCS files. All the commands presented above
  366. work with the `RCS' subdirectory(1). without change.
  367.    It may be undesirable that `ci' deletes the working file.  For
  368. instance, sometimes one would like to save the current revision, but
  369. continue editing. Invoking
  370.      ci  -l  f.c
  371.    checks in `f.c' as usual, but performs an additional check-out with
  372. locking afterwards.  Thus, the working file does not disappear after
  373. the check-in. Similarly, the option `-u' does a check-in followed by a
  374. check-out without locking.  This option is useful if the file is needed
  375. for compilation after the check-in. Both options update the
  376. identification markers in the working file (see below).
  377.    Besides the operations `ci' and `co', RCS provides the following
  378. commands:
  379. `ident'
  380.      extract identification markers
  381. `rcs'
  382.      change RCS file attributes
  383. `rcsclean'
  384.      remove unchanged working files (optional)
  385. `rcsdiff'
  386.      compare revisions
  387. `rcsfreeze'
  388.      record a configuration (optional)
  389. `rcsmerge'
  390.      merge revisions
  391. `rlog'
  392.      read log messages and other information in RCS files
  393.    A synopsis of these commands appears in the Appendix.
  394.    ---------- Footnotes ----------
  395.    (1)  Pairs of RCS and working files can actually be specified in 3
  396. ways: a) both are given, b) only the working file is given, c) only the
  397. RCS file is given. If a pair is given, both files may have arbitrary
  398. path prefixes; RCS commands pair them up intelligently
  399. File: rcs,  Node: Identification,  Next: RevisionTree,  Prev: StartRCS,  Up: VersionControl
  400. Automatic Identification
  401. ------------------------
  402.    RCS can stamp source and object code with special identification
  403. strings, similar to product and serial numbers. To obtain such
  404. identification, place the marker
  405.      $Id$
  406.    into the text of a revision, for instance inside a comment.  The
  407. check-out operation will replace this marker with a string of the form
  408.      $Id:  filename  revisionnumber  date  time  author state  locker $
  409.    This string need never be touched, because `co' keeps it up to date
  410. automatically. To propagate the marker into object code, simply put it
  411. into a literal character string.  In C, this is done as follows:
  412.      static char rcsid[] = "$Id$";
  413.    The command `ident' extracts such markers from any file, in
  414. particular from object code.  `Ident' helps to find out which revisions
  415. of which modules were used in a given program. It returns a complete
  416. and unambiguous component list, from which a copy of the program can be
  417. reconstructed.  This facility is invaluable for program maintenance.
  418.    There are several additional identification markers, one for each
  419. component of $Id$. The marker
  420.      $Log$
  421.    has a similar function.  It accumulates the log messages that are
  422. requested during check-in.  Thus, one can maintain the complete history
  423. of a revision directly inside it, by enclosing it in a comment.  Figure
  424. 1 is an edited version of a log contained in revision 4.1 of the file
  425. `ci.c'.  The log appears at the beginning of the file, and makes it
  426. easy to determine what the recent modifications were.
  427.      /*
  428.       * $Log: ci.c,v $
  429.       * Revision 4.1  1983/05/10 17:03:06  wft
  430.       * Added option -d and -w, and updated assignment of date, etc.
  431.       * to new delta. Added handling of default branches.
  432.       *
  433.       * Revision 3.9  1983/02/15 15:25:44  wft
  434.       * Added call to fastcopy() to copy remainder of RCS file.
  435.       *
  436.       * Revision 3.8  1983/01/14 15:34:05  wft
  437.       * Added ignoring of interrupts while new RCS file is renamed;
  438.       * avoids deletion of RCS files by interrupts.
  439.       *
  440.       * Revision 3.7  1982/12/10 16:09:20  wft
  441.       * Corrected checking of return code from diff.
  442.       * An RCS file now inherits its mode during the first ci from the
  443.       * working file, except that write permission is removed.
  444.       */
  445.           Figure 1.  Log entries produced by the marker $Log$
  446.    Since revisions are stored in the form of differences, each log
  447. message is physically stored once, independent of the number of
  448. revisions present. Thus, the $Log$ marker incurs negligible space
  449. overhead.
  450. File: rcs,  Node: RevisionTree,  Next: Branches,  Prev: Identification,  Up: VersionControl
  451. The RCS Revision Tree
  452. =====================
  453.    RCS arranges revisions in an ancestral tree. The `ci' command builds
  454. this tree; the auxiliary command `rcs' prunes it. The tree has a root
  455. revision, normally numbered 1.1, and successive revisions are numbered
  456. 1.2, 1.3, etc.  The first field of a revision number is called the
  457. `release number' and the second one the `level number'.  Unless given
  458. explicitly, the `ci' command assigns a new revision number by
  459. incrementing the level number of the previous revision. The release
  460. number must be incremented explicitly, using the `-r' option of `ci'.
  461. Assuming there are revisions 1.1, 1.2, and 1.3 in the RCS file `f.c,v',
  462. the command
  463.      ci  -r2.1  f.c       or       ci  -r2  f.c
  464.    assigns the number 2.1 to the new revision. Later check-ins without
  465. the `-r' option will assign the numbers 2.2, 2.3, and so on. The
  466. release number should be incremented only at major transition points in
  467. the development, for instance when a new release of a software product
  468. has been completed.
  469. File: rcs,  Node: Branches,  Next: Deltas,  Prev: RevisionTree,  Up: VersionControl
  470. When are branches needed?
  471. -------------------------
  472.    A young revision tree is slender: It consists of only one branch,
  473. called the trunk. As the tree ages, side branches may form.  Branches
  474. are needed in the following 4 situations.
  475.   1. Temporary fixes
  476.      Suppose a tree has 5 revisions grouped in 2 releases, as
  477.      illustrated in Figure 2. Revision 1.3, the last one of release 1,
  478.      is in operation at customer sites, while release 2 is in active
  479.      development.
  480.      Now imagine a customer requesting a fix of a problem in revision
  481.      1.3, although actual development has moved on to release 2.  RCS
  482.      does not permit an extra revision to be spliced in between 1.3 and
  483.      2.1, since that would not reflect the actual development history.
  484.      Instead, create a branch at revision 1.3, and check in the fix on
  485.      that branch. The first branch starting at 1.3 has number 1.3.1,
  486.      and the revisions on that branch are numbered 1.3.1.1, 1.3.1.2,
  487.      etc. The double numbering is needed to allow for another branch at
  488.      1.3, say 1.3.2. Revisions on the second branch would be numbered
  489.      1.3.2.1, 1.3.2.2, and so on. The following steps create branch
  490.      1.3.1 and add revision 1.3.1.1:
  491.           co -r1.3 f.c     -- check out revision 1.3
  492.           edit f.c         -- change it
  493.           ci  -r1.3.1  f.c -- check it in on branch 1.3.1
  494.      This sequence of commands transforms the tree of Figure 2 into the
  495.      one in Figure 3. Note that it may be necessary to incorporate the
  496.      differences between 1.3 and 1.3.1.1 into a revision at level 2.
  497.      The operation `rcsmerge' automates this process (see the Appendix).
  498.   2. Distributed development and customer modifications
  499.      Assume a situation as in Figure 2, where revision 1.3 is in
  500.      operation at several customer sites, while release 2 is in
  501.      development. Customer sites should use RCS to store the
  502.      distributed software. However, customer modifications should not
  503.      be placed on the same branch as the distributed source; instead,
  504.      they should be placed on a side branch. When the next software
  505.      distribution arrives, it should be appended to the trunk of the
  506.      customer's RCS file, and the customer can then merge the local
  507.      modifications back into the new release. In the above example, a
  508.      customer's RCS file would contain the following tree, assuming
  509.      that the customer has received revision 1.3, added his local
  510.      modifications as revision 1.3.1.1, then received revision 2.4, and
  511.      merged 2.4 and 1.3.1.1, resulting in 2.4.1.1.
  512.      This approach is actually practiced in the CSNET project, where
  513.      several universities and a company cooperate in developing a
  514.      national computer network.
  515.   3. Parallel development
  516.      Sometimes it is desirable to explore an alternate design or a
  517.      different implementation technique in parallel with the main line
  518.      development.  Such development should be carried out on a side
  519.      branch.  The experimental changes may later be moved into the main
  520.      line, or abandoned.
  521.   4. Conflicting updates
  522.      A common occurrence is that one programmer has checked out a
  523.      revision, but cannot complete the assignment for some reason.  In
  524.      the meantime, another person must perform another modification
  525.      immediately.  In that case, the second person should check-out the
  526.      same revision, modify it, and check it in on a side branch, for
  527.      later merging.
  528.      Every node in a revision tree consists of the following
  529.      attributes: a revision number, a check-in date and time, the
  530.      author's identification, a log entry, a state and the actual text.
  531.      All these attributes are determined at the time the revision is
  532.      checked in. The state attribute indicates the status of a
  533.      revision. It is set automatically to `experimental' during
  534.      check-in. A revision can later be promoted to a higher status, for
  535.      example `stable' or `released'.  The set of states is user-defined.
  536. File: rcs,  Node: Deltas,  Next: Controversial,  Prev: Branches,  Up: VersionControl
  537. Revisions are represented as deltas
  538. -----------------------------------
  539.    For conserving space, RCS stores revisions in the form of deltas,
  540. i.e., as differences between revisions. The user interface completely
  541. hides this fact.
  542.    A delta is a sequence of edit commands that transforms one string
  543. into another.  The deltas employed by RCS are line-based, which means
  544. that the only edit commands allowed are insertion and deletion of
  545. lines. If a single character in a line is changed, the edit scripts
  546. consider the entire line changed. The program `diff' produces a small,
  547. line-based delta between pairs of text files. A character-based edit
  548. script would take much longer to compute, and would not be
  549. significantly shorter.
  550.    Using deltas is a classical space-time tradeoff: deltas reduce the
  551. space consumed, but increase access time. However, a version control
  552. tool should impose as little delay as possible on programmers.
  553. Excessive delays discourage the use of version controls, or induce
  554. programmers to take shortcuts that compromise system integrity. To gain
  555. reasonably fast access time for both editing and compiling, RCS
  556. arranges deltas in the following way.  The most recent revision on the
  557. trunk is stored intact. All other revisions on the trunk are stored as
  558. reverse deltas. A reverse delta describes how to go backward in the
  559. development history: it produces the desired revision if applied to the
  560. successor of that revision. This implementation has the advantage that
  561. extraction of the latest revision is a simple and fast copy operation.
  562. Adding a new revision to the trunk is also fast: `ci' simply adds the
  563. new revision intact, replaces the previous revision with a reverse
  564. delta, and keeps the rest of the old deltas. Thus, `ci' requires the
  565. computation of only one new delta.
  566.    Branches need special treatment.  The naive solution would be to
  567. store complete copies for the tips of all branches. Clearly, this
  568. approach would cost too much space.  Instead, RCS uses `forward' deltas
  569. for branches.  Regenerating a revision on a side branch proceeds as
  570. follows.  First, extract the latest revision on the trunk; secondly,
  571. apply reverse deltas until the fork revision for the branch is
  572. obtained; thirdly, apply forward deltas until the desired branch
  573. revision is reached.  Figure 5 illustrates a tree with one side branch.
  574. Triangles pointing to the left and right represent reverse and forward
  575. deltas, respectively.
  576.    Although implementing fast check-out for the latest trunk revision,
  577. this arrangement has the disadvantage that generation of other
  578. revisions takes time proportional to the number of deltas applied.  For
  579. example, regenerating the branch tip in Figure 5 requires application
  580. of five deltas (including the initial one).  Since usage statistics
  581. show that the latest trunk revision is the one that is retrieved in 95
  582. per cent of all cases (see the section on usage statistics), biasing
  583. check-out time in favor of that revision results in significant
  584. savings. However, careful implementation of the delta application
  585. process is necessary to provide low retrieval overhead for other
  586. revisions, in particular for branch tips.
  587.    There are several techniques for delta application. The naive one is
  588. to pass each delta to a general-purpose text editor. A prototype of RCS
  589. invoked the UNIX editor `ed' both for applying deltas and for expanding
  590. the identification markers.  Although easy to implement, performance
  591. was poor, owing to the high start-up costs and excess generality of
  592. `ed'.  An intermediate version of RCS used a special-purpose,
  593. stream-oriented editor. This technique reduced the cost of applying a
  594. delta to the cost of checking out the latest trunk revision.  The
  595. reason for this behavior is that each delta application involves a
  596. complete pass over the preceding revision.
  597.    However, there is a much better algorithm.  Note that the deltas are
  598. line oriented and that most of the work of a stream editor involves
  599. copying unchanged lines from one revision to the next. A faster
  600. algorithm avoids unnecessary copying of character strings by using a
  601. `piece table'. A piece table is a one-dimensional array, specifying how
  602. a given revision is `pieced-together' from lines in the RCS file.
  603. Suppose piece table `PTr' represents revision `r'. Then `PTr[i]'
  604. contains the starting position of line `i' of revision `r'.
  605. Application of the next delta transforms piece table `PTr' into
  606. `PTr+1'.  For instance, a delete command removes a series of entries
  607. from the piece table.  An insertion command inserts new entries, moving
  608. the entries following the insertion point further down the array.  The
  609. inserted entries point to the text lines in the delta. Thus, no I/O is
  610. involved except for reading the delta itself. When all deltas have been
  611. applied to the piece table, a sequential pass through the table looks up
  612. each line in the RCS file and copies it to the output file, updating
  613. identification markers at the same time. Of course, the RCS file must
  614. permit random access, since the copied lines are scattered throughout
  615. that file.  Figure 6 illustrates an RCS file with two revisions and the
  616. corresponding piece tables.
  617.    The piece table approach has the property that the time for applying
  618. a single delta is roughly determined by the size of the delta, and not
  619. by the size of the revision.  For example, if a delta is 10 per cent of
  620. the size of a revision, then applying it takes only 10 per cent of the
  621. time to generate the latest trunk revision.  (The stream editor would
  622. take 100 per cent.)
  623.    There is an important alternative for representing deltas that
  624. affects performance.  `SCCS', a precursor of RCS, uses `interleaved'
  625. deltas. A file containing interleaved deltas is partitioned into blocks
  626. of lines. Each block has a header that specifies to which revision(s)
  627. the block belongs.  The blocks are sorted out in such a way that a
  628. single pass over the file can pick up all the lines belonging to a
  629. given revision.  Thus, the regeneration time for all revisions is the
  630. same: all headers must be inspected, and the associated blocks either
  631. copied or skipped.  As the number of revisions increases, the cost of
  632. retrieving any revision is much higher than the cost of checking out
  633. the latest trunk revision with reverse deltas.  A detailed comparison of
  634. `SCCS's' interleaved deltas and RCS's reverse deltas can be found in
  635. Reference 4. This reference considers the version of RCS with the
  636. stream editor only.  The piece table method improves performance
  637. further, so that RCS is always faster than SCCS, except if 10 or more
  638. deltas are applied.
  639.    Additional speed-up for both delta methods can be obtained by
  640. caching the most recently generated revision, as has been implemented
  641. in `DSEE' With caching, access time to frequently used revisions can
  642. approach normal file access time, at the cost of some additional space.
  643. File: rcs,  Node: Controversial,  Next: Configuration,  Prev: Deltas,  Up: VersionControl
  644. Locking: A Controversial Issue
  645. ==============================
  646.    The locking mechanism for RCS was difficult to design. The problem
  647. and its solution are first presented in their `pure' form, followed by
  648. a discussion of the complications caused by `real-world' considerations.
  649.    RCS must prevent two or more persons from depositing competing
  650. changes of the same revision. Suppose two programmers check out
  651. revision 2.4 and modify it.  Programmer A checks in a revision before
  652. programmer B. Unfortunately, programmer B has not seen A's changes, so
  653. the effect is that A's changes are covered up by B's deposit. A's
  654. changes are not lost since all revisions are saved, but they are
  655. confined to a single revision(1).
  656.    This conflict is prevented in RCS by locking. Whenever someone
  657. intends to edit a revision (as opposed to reading or compiling it), the
  658. revision should be checked out and locked, using the `-l' option on
  659. `co'.  On subsequent check-in, `ci' tests the lock and then removes it.
  660. At most one programmer at a time may lock a particular revision, and
  661. only this programmer may check in the succeeding revision. Thus, while
  662. a revision is locked, it is the exclusive responsibility of the locker.
  663.    An important maxim for software tools like RCS is that they must not
  664. stand in the way of making progress with a project. This consideration
  665. leads to several weakenings of the locking mechanism. First of all,
  666. even if a revision is locked, it can still be checked out.  This is
  667. necessary if other people wish to compile or inspect the locked
  668. revision while the next one is in preparation.  The only operations
  669. they cannot do are to lock the revision or to check in the succeeding
  670. one.  Secondly, check-in operations on other branches in the RCS file
  671. are still possible; the locking of one revision does not affect any
  672. other revision.  Thirdly, revisions are occasionally locked for a long
  673. period of time because a programmer is absent or otherwise unable to
  674. complete the assignment.  If another programmer has to make a pressing
  675. change, there are the following three alternatives for making progress:
  676.    - find out who is holding the lock and ask that person to release it;
  677.    - check out the locked revision, modify it, check it in on a branch,
  678.      and merge the changes later;
  679.    - break the lock.  Breaking a lock leaves a highly visible trace,
  680.      namely an electronic mail message that is sent automatically to
  681.      the holder of the lock, recording the breaker and a commentary
  682.      requested from him. Thus, breaking locks is tolerated under
  683.      certain circumstances, but will not go unnoticed.  Experience has
  684.      shown that the automatic mail message attaches a high enough
  685.      stigma to lock breaking, such that programmers break locks only in
  686.      real emergencies, or when a co-worker resigns and leaves locked
  687.      revisions behind.
  688.    If an RCS file is private, i.e., when a programmer owns an RCS file
  689. and does not expect anyone else to perform check-in operations, locking
  690. is an unnecessary nuisance. In this case, the `strict locking feature'
  691. discussed earlier may be disabled, provided that file protection is set
  692. such that only the owner may write the RCS file. This has the effect
  693. that only the owner can check-in revisions, and that no lock is needed
  694. for doing so.
  695.    As added protection, each RCS file contains an access list that
  696. specifies the users who may execute update operations.  If an access
  697. list is empty, only normal UNIX file protection applies.  Thus, the
  698. access list is useful for restricting the set of people who would
  699. otherwise have update permission.  Just as with locking, the access
  700. list has no effect on read-only operations such as `co'.  This approach
  701. is consistent with the UNIX philosophy of openness, which contributes
  702. to a productive software development environment.
  703.    ---------- Footnotes ----------
  704.    (1)  Note that this problem is entirely different from the atomicity
  705. problem. Atomicity means that concurrent update operations on the same
  706. RCS file cannot be permitted, because that may result in inconsistent
  707. data. Atomic updates are essential (and implemented in RCS), but do not
  708. solve the conflict discussed here.
  709. File: rcs,  Node: Configuration,  Next: Functions,  Prev: Controversial,  Up: VersionControl
  710. Configuration Management
  711. ========================
  712.    The preceding sections described how `RCS' deals with revisions of
  713. individual components; this section discusses how to handle
  714. configurations. A configuration is a set of revisions, where each
  715. revision comes from a different revision group, and the revisions are
  716. selected according to a certain criterion. For example, in order to
  717. build a functioning compiler, the `right' revisions from the scanner,
  718. the parser, the optimizer and the code generator must be combined.
  719. `RCS', in conjunction with `MAKE', provides a number of facilities to
  720. effect a smooth selection.
  721. File: rcs,  Node: Functions,  Next: MAKERCS,  Prev: Configuration,  Up: VersionControl
  722. RCS Selection Functions
  723. -----------------------
  724.    - Default selection
  725.      During development, the usual selection criterion is to choose the
  726.      latest revision of all components.  The `co' command makes this
  727.      selection by default.  For example, the command
  728.           co  *,v
  729.      retrieves the latest revision on the default branch of each RCS
  730.      file in the current directory. The default branch is usually the
  731.      trunk, but may be set to be a side branch. Side branches as
  732.      defaults are needed in distributed software development, as
  733.      discussed in the section on the RCS revision tree.
  734.    - Release based selection
  735.      Specifying a release or branch number selects the latest revision
  736.      in that release or branch. For instance,
  737.           co  -r2  *,v
  738.      retrieves the latest revision with release number 2 from each RCS
  739.      file. This selection is convenient if a release has been completed
  740.      and development has moved on to the next release.
  741.    - State and author based selection
  742.      If the highest level number within a given release number is not
  743.      the desired one, the state attribute can help.  For example,
  744.           co  -r2  -sReleased  *,v
  745.      retrieves the latest revision with release number 2 whose state
  746.      attribute is `Released'. Of course, the state attribute has to be
  747.      set appropriately, using the `ci' or `rcs' commands.  Another
  748.      alternative is to select a revision by its author, using the `-w'
  749.      option.
  750.    - Date based selection
  751.      Revisions may also be selected by date. Suppose a release of an
  752.      entire system was completed and current on March 4, at 1:00 p.m.
  753.      local time.  Then the command
  754.           co  -d'March 4, 1:00 pm LT'  *,v
  755.      checks out all the components of that release, independent of the
  756.      numbering. The `-d' option specifies a `cutoff date', i.e., the
  757.      revision selected has a check-in date that is closest to, but not
  758.      after the date given.
  759.    - Name based selection
  760.      The most powerful selection function is based on assigning
  761.      symbolic names to revisions and branches. In large systems, a
  762.      single release number or date is not sufficient to collect the
  763.      appropriate revisions from all groups. For example, suppose one
  764.      wishes to combine release 2 of one subsystem and release 15 of
  765.      another. Most likely, the creation dates of those releases differ
  766.      also. Thus, a single revision number or date passed to the `co'
  767.      command will not suffice to select the right revisions.  Symbolic
  768.      revision numbers solve this problem. Each RCS file may contain a
  769.      set of symbolic names that are mapped to numeric revision numbers.
  770.      For example, assume the symbol `V3' is bound to release number 2
  771.      in file `s,v', and to revision number 15.9 in `t,v'. Then the
  772.      single command
  773.           co  -rV3  s,v  t,v
  774.      retrieves the latest revision of release 2 from `s,v', and
  775.      revision 15.9 from `t,v'. In a large system with many modules,
  776.      checking out all revisions with one command greatly simplifies
  777.      configuration management.
  778.      Judicious use of symbolic revision numbers helps with organizing
  779.      large configurations.
  780.      A special command, `rcsfreeze', assigns a symbolic revision number
  781.      to a selected revision in every RCS file. `rcsfreeze' effectively
  782.      freezes a configuration. The assigned symbolic revision number
  783.      selects all components of the configuration. If necessary,
  784.      symbolic numbers may even be intermixed with numeric ones.  Thus,
  785.      `V3.5' in the above example would select revision 2.5 in `s,v' and
  786.      branch 15.9.5 in `t,v'.
  787.      The options `-r', `-s', `-w' and `-d' may be combined.  If a
  788.      branch is given, the latest revision on that branch satisfying all
  789.      conditions is retrieved; otherwise, the default branch is used.
  790. File: rcs,  Node: MAKERCS,  Next: Statistics,  Prev: Functions,  Up: VersionControl
  791. Combining MAKE and RCS
  792. ----------------------
  793.    MAKE (*Note Feldman::) is a program that processes configurations.
  794. It is driven by configuration specifications recorded in a special
  795. file, called a `Makefile'. MAKE avoids redundant processing steps by
  796. comparing creation dates of source and processed objects. For example,
  797. when instructed to compile all modules of a given system, it only
  798. recompiles those source modules that were changed since they were
  799. processed last.
  800.    MAKE has been extended with an auto-checkout feature(1) for RCS.*
  801. When a certain file to be processed is not present, MAKE attempts a
  802. check-out operation. If successful, MAKE performs the required
  803. processing, and then deletes the checked out file to conserve space.
  804. The selection parameters discussed above can be passed to MAKE either
  805. as parameters, or directly embedded in the Makefile.  MAKE has also
  806. been extended to search the subdirectory named `RCS' for needed files,
  807. rather than just the current working directory. However, if a working
  808. file is present, MAKE totally ignores the corresponding RCS file and
  809. uses the working file. (In newer versions of MAKE distributed by AT&T
  810. and others, auto-checkout can be achieved with the rule DEFAULT,
  811. instead of a special extension of MAKE. However, a file checked out by
  812. the rule DEFAULT will not be deleted after processing.  `Rcsclean' can
  813. be used for that purpose.)
  814.    With auto-checkout, RCS/MAKE can effect a selection rule especially
  815. tuned for multi-person software development and maintenance. In these
  816. situations, programmers should obtain configurations that consist of
  817. the revisions they have personally checked out plus the latest checked
  818. in revision of all other revision groups. This schema can be set up as
  819. follows.
  820.    Each programmer chooses a working directory and places into it a
  821. symbolic link, named `RCS', to the directory containing the relevant
  822. RCS files. The symbolic link makes sure that `co' and `ci' operations
  823. need only specify the working files, and that the Makefile need not be
  824. changed. The programmer then checks out the needed files and modifies
  825. them. If MAKE is invoked, it composes configurations by selecting those
  826. revisions that are checked out, and the rest from the subdirectory
  827. `RCS'. The latter selection may be controlled by a symbolic revision
  828. number or any of the other selection criteria. If there are several
  829. programmers editing in separate working directories, they are insulated
  830. from each other's changes until checking in their modifications.
  831.    Similarly, a maintainer can recreate an older configuration by
  832. starting to work in an empty working directory. During the initial MAKE
  833. invocation, all revisions are selected from RCS files. As the
  834. maintainer checks out files and modifies them, a new configuration is
  835. gradually built up. Every time MAKE is invoked, it substitutes the
  836. modified revisions into the configuration being manipulated.
  837.    A final application of RCS is to use it for storing Makefiles.
  838. Revision groups of Makefiles represent multiple versions of
  839. configurations. Whenever a configuration is baselined or distributed,
  840. the best approach is to unambiguously fix the configuration with a
  841. symbolic revision number by calling `rcsfreeze', to embed that symbol
  842. into the Makefile, and to check in the Makefile (using the same
  843. symbolic revision number).  With this approach, old configurations can
  844. be regenerated easily and reliably.
  845.    ---------- Footnotes ----------
  846.    (1)  This auto-checkout extension is available only in some versions
  847. of MAKE, e.g. GNU MAKE.
  848. File: rcs,  Node: Statistics,  Next: Survey,  Prev: MAKERCS,  Up: VersionControl
  849. Usage Statistics
  850. ================
  851.    The following usage statistics were collected on two DEC VAX-11/780
  852. computers of the Purdue Computer Science Department.  Both machines are
  853. mainly used for research purposes.  Thus, the data reflect an
  854. environment in which the majority of projects involve prototyping and
  855. advanced software development, but relatively little long-term
  856. maintenance.
  857.    For the first experiment, the `ci' and `co' operations were
  858. instrumented to log the number of backward and forward deltas applied.
  859. The data were collected during a 13 month period from Dec. 1982 to Dec.
  860. 1983. Table I summarizes the results.
  861.      Oper.  !   Total  !Total deltas!mean deltas! Operations  !Branch 
  862.             !operations!   applied  !  applied  !with >1 delta!operations
  863.      -------+----------+------------+-----------+-------------+----------
  864.      co     !     7867 !    9320    !    1.18   !   509 (6%)  ! 203 (3%)
  865.      ci     !     3468 !    2207    !    0.64   !    85 (2%)  !  75 (2%)
  866.      ci & co!    11335 !   11527    !    1.02   !   594 (5%)  ! 278 (2%)
  867.       
  868.       
  869.              Table I.  Statistics for `co' and `ci' operations
  870. The first two lines show statistics for check-out and check-in; the
  871. third line shows the combination. Recall that `ci' performs an implicit
  872. check-out to obtain a revision for computing the delta. In all measures
  873. presented, the most recent revision (stored intact) counts as one
  874. delta.  The number of deltas applied represents the number of passes
  875. necessary, where the first `pass' is a copying step.
  876.    Note that the check-out operation is executed more than twice as
  877. frequently as the check-in operation. The fourth column gives the mean
  878. number of deltas applied in all three cases. For `ci', the mean number
  879. of deltas applied is less than one. The reasons are that the initial
  880. check-in requires no delta at all, and that the only time `ci' requires
  881. more than one delta is for branches. Column 5 shows the actual number
  882. of operations that applied more than one delta. The last column
  883. indicates that branches were not used often.
  884.    The last three columns demonstrate that the most recent trunk
  885. revision is by far the most frequently accessed. For RCS, check-out of
  886. this revision is a simple copy operation, which is the absolute minimum
  887. given the copy-semantics of `co'.  Access to older revisions and
  888. branches is more common in non-academic environments, yet even if
  889. access to older deltas were an order of magnitude more frequent, the
  890. combined average number of deltas applied would still be below 1.2.
  891. Since RCS is faster than SCCS until up to 10 delta applications, reverse
  892. deltas are clearly the method of choice. .PP The second experiment,
  893. conducted in March of 1984, involved surveying the existing RCS files
  894. on our two machines.  The goal was to determine the mean number of
  895. revisions per RCS file, as well as the space consumed by them. Table II
  896. shows the results. (Tables I and II were produced at different times
  897. and are unrelated.)
  898.                !Total RCS!  Total  !Mean     !Means size!Mean size!Overhead
  899.                ! files   !revisions!revisions!RCS files !revisions!
  900.      ----------+---------+---------+---------+----------+---------+--------
  901.      All Files !    8033 !   11133 !   1.39  !   6156   !  5585   !  1.10
  902.      Files with!    1477 !    4578 !   3.10  !   8074   !  6041   !  1.34
  903.      >= 2 delta!         !         !         !          !         !
  904.       
  905.       
  906.                      Table II. Statistics for RCS files
  907. The mean number of revisions per RCS file is 1.39.  Columns 5 and 6
  908. show the mean sizes (in bytes) of an RCS file and of the latest
  909. revision of each RCS file, respectively. The `overhead' column contains
  910. the ratio of the mean sizes. Assuming that all revisions in an RCS file
  911. are approximately the same size, this ratio gives a measure of the
  912. space consumed by the extra revisions.
  913.    In our sample, over 80 per cent of the RCS files contained only a
  914. single revision. The reason is that our systems programmers routinely
  915. check in all source files on the distribution tapes, even though they
  916. may never touch them again. To get a better indication of how much
  917. space savings are possible with deltas, all measures with those files
  918. that contained 2 or more revisions were recomputed.  Only for those
  919. files is RCS necessary. As shown in the second line, the average number
  920. of revisions for those files is 3.10, with an overhead of 1.34. This
  921. means that the extra 2.10 deltas require 34 per cent extra space, or 16
  922. per cent per extra revision. Rochkind(*Note Rochkind::) measured the
  923. space consumed by SCCS, and reported an average of 5 revisions per
  924. group and an overhead of 1.37 (or about 9 per cent per extra revision).
  925. In a later paper, Glasser (*Note Glasser::) observed an average of 7
  926. revisions per group in a single, large project, but provided no
  927. overhead figure. In his paper on DSEE , Leblang (*Note Leblang::)
  928. reported that delta storage combined with blank compression results in
  929. an overhead of a mere 1-2 per cent per revision. Since leading blanks
  930. accounted for about 20 per cent of the surveyed Pascal programs, a
  931. revision group with 5-10 members was smaller than a single cleartext
  932. copy.
  933.    The above observations demonstrate clearly that the space needed for
  934. extra revisions is small.  With delta storage, the luxury of keeping
  935. multiple revisions online is certainly affordable. In fact, introducing
  936. a system with delta storage may reduce storage requirements, because
  937. programmers often save back-up copies anyway.  Since back-up copies are
  938. stored much more efficiently with deltas, introducing a system such as
  939. RCS may actually free a considerable amount of space.
  940. File: rcs,  Node: Survey,  Prev: Statistics,  Up: VersionControl
  941. Survey of Version Control Tools
  942. ===============================
  943.    The need to keep back-up copies of software arose when programs and
  944. data were no longer stored on paper media, but were entered from
  945. terminals and stored on disk. Back-up copies are desirable for
  946. reliability, and many modern editors automatically save a back-up copy
  947. for every file touched. This strategy is valuable for short-term
  948. back-ups, but not suitable for long-term version control, since an
  949. existing back-up copy is overwritten whenever the corresponding file is
  950. edited.
  951.    Tape archives are suitable for long-term, offline storage. If all
  952. changed files are dumped on a back-up tape once per day, old revisions
  953. remain accessible.  However, tape archives are unsatisfactory for
  954. version control in several ways.  First, backing up the file system
  955. every 24 hours does not capture intermediate revisions. Secondly, the
  956. old revisions are not online, and accessing them is tedious and
  957. time-consuming. In particular, it is impractical to compare several old
  958. revisions of a group, because that may require mounting and searching
  959. several tapes. Tape archives are important fail-safe tools in the event
  960. of catastrophic disk failures or accidental deletions, but they are
  961. ill-suited for version control. Conversely, version control tools do
  962. not obviate the need for tape archives.
  963.    A natural technique for keeping several old revisions online is to
  964. never delete a file. Editing a file simply creates a new file with the
  965. same name, but with a different sequence number. This technique,
  966. available as an option in DEC's VMS operating system, turns out to be
  967. inadequate for version control. First, it is prohibitively expensive in
  968. terms of storage costs, especially since no data compression techniques
  969. are employed. Secondly, indiscriminately storing every change produces
  970. too many revisions, and programmers have difficulties distinguishing
  971. them.  The proliferation of revisions forces programmers to spend much
  972. time on finding and deleting useless files. Thirdly, most of the
  973. support functions like locking, logging, revision selection, and
  974. identification described in this paper are not available.
  975.    An alternative approach is to separate editing from revision
  976. control. The user may repeatedly edit a given revision, until freezing
  977. it with an explicit command. Once a revision is frozen, it is stored
  978. permanently and can no longer be modified. (In RCS, freezing a
  979. revisions is done with `ci'.) Editing a frozen revision implicitly
  980. creates a new one, which can again be changed repeatedly until it is
  981. frozen itself. This approach saves exactly those revisions that the
  982. user considers important, and keeps the number of revisions manageable.
  983. IBM's CLEAR/CASTER (*Note Brown::), AT&T's SCCS (*Note Rochkind::),
  984. CMU's SDC (*Note Habermann::), and DEC's CMS (*Note DEC::), are
  985. examples of version control systems using this approach. CLEAR/CASTER
  986. maintains a data base of programs, specifications, documentation and
  987. messages, using deltas. Its goal is to provide control over the
  988. development process from a management viewpoint. SCCS stores multiple
  989. revisions of source text in an ancestral tree, records a log entry for
  990. each revision, provides access control, and has facilities for uniquely
  991. identifying each revision. An efficient delta technique reduces the
  992. space consumed by each revision group. SDC is much simpler than SCCS
  993. because it stores not more than two revisions.  However, it maintains a
  994. complete log for all old revisions, some of which may be on back-up
  995. tape. CMS, like SCCS, manages tree-structured revision groups, but
  996. offers no identification mechanism.
  997.    Tools for dealing with configurations are still in a state of flux.
  998. SCCS, SDC and CMS can be combined with MAKE or MAKE-like programs.
  999. Since flexible selection rules are missing from all these tools, it is
  1000. sometimes difficult to specify precisely which revision of each group
  1001. should be passed to MAKE for building a desired configuration. The
  1002. Xerox Cedar system (*Note Lampson::) provides a `System Modeller' that
  1003. can rebuild a configuration from an arbitrary set of module revisions.
  1004. The revisions of a module are only distinguished by creation time, and
  1005. there is no tool for managing groups. Since the selection rules are
  1006. primitive, the System Modeller appears to be somewhat tedious to use.
  1007. Apollo's DSEE (*Note Leblang::) is a sophisticated software engineering
  1008. environment. It manages revision groups in a way similar to SCCS and
  1009. CMS. Configurations are built using `configuration threads'. A
  1010. configuration thread states which revision of each group named in a
  1011. configuration should be chosen.  A configuration thread may contain
  1012. dynamic specifiers (e.g., `choose the revisions I am currently working
  1013. on, and the most recent revisions otherwise'), which are bound
  1014. automatically at build time. It also provides a notification mechanism
  1015. for alerting maintainers about the need to rebuild a system after a
  1016. change.
  1017.    RCS is based on a general model for describing
  1018. multi-version/multi-configuration systems (*Note Tichy1::). The model
  1019. describes systems using AND/OR graphs, where AND nodes represent
  1020. configurations, and OR nodes represent version groups.  The model gives
  1021. rise to a suit of selection rules for composing configurations, almost
  1022. all of which are implemented in RCS. The revisions selected by RCS are
  1023. passed to MAKE for configuration building. Revision group management is
  1024. modelled after SCCS. RCS retains SCCS's best features, but offers a
  1025. significantly simpler user interface, flexible selection rules,
  1026. adequate integration with MAKE and improved identification. A detailed
  1027. comparison of RCS and SCCS appears in Reference 4.
  1028.    An important component of all revision control systems is a program
  1029. for computing deltas. SCCS and RCS use the program `diff' (*Note
  1030. Rochkind::), which first computes the longest common substring of two
  1031. revisions, and then produces the delta from that substring. The delta
  1032. is simply an edit script consisting of deletion and insertion commands
  1033. that generate one revision from the other.
  1034.    A delta based on a longest common substring is not necessarily
  1035. minimal, because it does not take advantage of crossing block moves.
  1036. Crossing block moves arise if two or more blocks of lines (e.g.,
  1037. procedures) appear in a different order in two revisions.  An edit
  1038. script derived from a longest common substring first deletes the
  1039. shorter of the two blocks, and then reinserts it.  Heckel (*Note
  1040. Heckel::) proposed an algorithm for detecting block moves, but since
  1041. the algorithm is based on heuristics, there are conditions under which
  1042. the generated delta is far from minimal.  DSEE uses this algorithm
  1043. combined with blank compression, apparently with satisfactory overall
  1044. results. A new algorithm that is guaranteed to produce a minimal delta
  1045. based on block moves appears in Reference 13. A future release of RCS
  1046. will use this algorithm.
  1047.    `Acknowledgements':
  1048.      Many people have helped make RCS a success by contributed
  1049.      criticisms, suggestions, corrections, and even whole new commands
  1050.      (including manual pages). The list of people is too long to be
  1051.      reproduced here, but my sincere thanks for their help and
  1052.      goodwill goes to all of them.
  1053. File: rcs,  Node: rcsIntroduction,  Next: Synopsis,  Prev: VersionControl,  Up: Top
  1054. Introduction to RCS commands
  1055. ****************************
  1056. * Menu:
  1057. * rcsintroDesc::      Introduction to `RCS'.
  1058. * rcsintroFunc::      Functions of `RCS'.
  1059. * rcsintroStart::     Getting started with `RCS'.
  1060. * rcsintroAutoIdent:: Automatic identification.
  1061. File: rcs,  Node: rcsintroDesc,  Next: rcsintroFunc,  Prev: rcsIntroduction,  Up: rcsIntroduction
  1062. Description
  1063. ===========
  1064.    The  Revision  Control System (RCS) manages multiple revisions of
  1065. files.  RCS  automates  the  storing,  retrieval, logging,
  1066. identification, and merging of revisions.  RCS is useful for text that
  1067. is revised  frequently,  for  example programs,  documentation,
  1068. graphics, papers, and form letters.
  1069.    The basic user interface is extremely simple.  The  novice only
  1070. needs  to  learn two commands: `ci' and `co'.  `ci', short for "check
  1071. in", deposits the contents of a file into an archival file called an
  1072. RCS file.  An RCS file contains all revisions of a particular file.
  1073. `co', short for  "check out", retrieves revisions from an RCS file.
  1074. File: rcs,  Node: rcsintroFunc,  Next: rcsintroStart,  Prev: rcsintroDesc,  Up: rcsIntroduction
  1075. Functions of RCS
  1076. ================
  1077.    * Store and retrieve multiple revisions of text.  RCS saves all old
  1078.      revisions in a space  efficient  way. Changes no longer destroy
  1079.      the original, because the previous revisions  remain accessible.
  1080.      Revisions can  be  retrieved  according to ranges of revision
  1081.      numbers,  symbolic  names,  dates,   authors,   and states.
  1082.    * Maintain  a  complete history of changes.  RCS logs all changes
  1083.      automatically.   Besides  the  text  of each  revision, RCS stores
  1084.      the author, the date and time of check-in, and a log message
  1085.      summarizing the change.  The logging makes it easy to find out
  1086.      what happened to a module,  without  having  to  compare source
  1087.      listings or having to track down colleagues.
  1088.    * Resolve access conflicts.  When two  or  more  programmers wish
  1089.      to  modify  the  same revision, RCS alerts the programmers and
  1090.      prevents  one  modification from corrupting the other.
  1091.    * Maintain  a  tree  of  revisions.  RCS can maintain separate lines
  1092.      of development for each module.   It stores  a tree structure that
  1093.      represents the ancestral relationships among revisions.
  1094.    * Merge revisions and resolve conflicts.   Two  separate lines  of
  1095.      development of a module can be coalesced by merging.  If the
  1096.      revisions to  be  merged affect  the  same  sections of code, RCS
  1097.      alerts the user about the overlapping changes.
  1098.    * Control releases and configurations.  Revisions can be assigned
  1099.      symbolic names and marked as released, stable, experimental, etc.
  1100.      With these  facilities, configurations  of modules can be
  1101.      described simply and directly.
  1102.    * Automatically identify  each  revision  with  name, revision
  1103.      number,  creation time, author, etc.  The identification is like a
  1104.      stamp that can be embedded at  an appropriate place in the text of
  1105.      a revision. The identification makes  it  simple  to  determine
  1106.      which  revisions  of  which modules make up a given configuration.
  1107.    * Minimize secondary storage.  RCS needs little extra space for the
  1108.      revisions (only the differences).  If intermediate revisions are
  1109.      deleted, the corresponding deltas are compressed accordingly.
  1110. File: rcs,  Node: rcsintroStart,  Next: rcsintroAutoIdent,  Prev: rcsintroFunc,  Up: rcsIntroduction
  1111. Getting Started with RCS
  1112. ========================
  1113.    Suppose  you  have  a  file `f.c' that you wish to put under control
  1114. of RCS.  If you have not already done so, make  an RCS directory with
  1115. the command
  1116.      mkdir  RCS
  1117.    Then invoke the check-in command
  1118.      ci  f.c
  1119.    This  command  creates  an  RCS file in the RCS directory, stores
  1120. `f.c' into it as revision 1.1, and deletes `f.c'.   It also  asks  you
  1121. for a description.  The description should be a synopsis of the contents
  1122. of  the  file.   All  later check-in  commands  will ask  you  for a
  1123. log entry, which should summarize the changes that you made.
  1124.    Files in the RCS directory are called RCS files; the  others are
  1125. called  working  files.  To get back the working file f.c in the
  1126. previous example, use the  check-out  command
  1127.      co  f.c
  1128.    This  command  extracts  the  latest revision from the RCS file and
  1129. writes it into `f.c'.  If you want to edit `f.c', you must lock it as
  1130. you check it out with the command
  1131.      co  -l  f.c
  1132.    You can now edit `f.c.'
  1133.    Suppose  after  some editing you want to know what changes that you
  1134. have made.  The command
  1135.      rcsdiff  f.c
  1136.    tells  you  the  difference  between  the  most   recently
  1137. checked-in  version  and  the working file.  You can check the file
  1138. back in by invoking
  1139.      ci  f.c
  1140.    This increments the revision number properly.
  1141.    If ci complains with the message
  1142.      ci error: no lock set by `your name'
  1143.    then you have tried to check in a file even though you did not lock
  1144. it when you checked it out.  Of course, it is too late now to do the
  1145. check-out with locking, because another check-out  would  overwrite
  1146. your modifications.  Instead, invoke
  1147.      rcs  -l  f.c
  1148.    This command will lock the latest revision for you, unless somebody
  1149. else  got  ahead  of you already.  In this case, you'll have to
  1150. negotiate with that person.
  1151.    Locking assures that you, and only you, can check  in  the next
  1152. update,  and avoids nasty problems if several people work on the same
  1153. file.  Even if a revision is  locked,  it can still be checked out for
  1154. reading, compiling, etc.  All that locking prevents is a `check-in'  by
  1155. anybody  but  the locker.
  1156.    If  your  RCS  file  is private, i.e., if you are the only person
  1157. who is going to deposit revisions into  it,  strict locking  is not
  1158. needed and you can turn it off.  If strict locking is turned off, the
  1159. owner of the RCS file need  not have  a  lock  for check-in; all others
  1160. still do.  Turning strict locking off and on is done with the commands
  1161.      rcs  -U  f.c     and     rcs  -L  f.c
  1162.    If you don't want to clutter your working  directory  with RCS
  1163. files, create a subdirectory called RCS in your work- ing directory,
  1164. and move all your  RCS  files  there.   RCS commands  will  look  first
  1165. into  that  directory to find needed files.  All the commands
  1166. discussed above will still work,  without  any modification.
  1167. (Actually, pairs of RCS and working files can be specified in three
  1168. ways: (a) both are  given,  (b)  only the working file is given, (c)
  1169. only the RCS file is given.  Both RCS  and  working  files  may have
  1170. arbitrary  path  prefixes; RCS commands pair them up intelligently.)
  1171.    To avoid the deletion of the working file during  check-in (in  case
  1172. you  want  to  continue  editing or compiling), invoke
  1173.      ci  -l  f.c     or     ci  -u  f.c
  1174.    These commands check in  `f.c'  as  usual,  but  perform  an
  1175. implicit check-out.  The first form also locks the checked in revision,
  1176. the second one doesn't.  Thus, these  options save  you one check-out
  1177. operation.  The first form is useful if you want to continue editing,
  1178. the second one if you just  want  to read the file.  Both update the
  1179. identification markers in your working file (see below).
  1180.    You can give ci the number you want assigned to a  checked in
  1181. revision.  Assume all your revisions were numbered 1.1, 1.2, 1.3, etc.,
  1182. and you would like  to  start  release  2.  The command
  1183.      ci  -r2  f.c     or     ci  -r2.1  f.c
  1184.    assigns the number 2.1 to the new revision.  From then on, ci will
  1185. number the subsequent  revisions  with  2.2,  2.3, etc.  The
  1186. corresponding co commands
  1187.      co  -r2  f.c     and     co  -r2.1  f.c
  1188.    retrieve the latest revision numbered 2.`x' and the revision 2.1,
  1189. respectively.  co without a revision  number  selects the  latest
  1190. revision on the `trunk', i.e. the highest revision with a number
  1191. consisting of two fields.  Numbers with more  than  two fields are
  1192. needed for branches.  For example, to start a branch at revision 1.3,
  1193. invoke
  1194.      ci  -r1.3.1  f.c
  1195.    This command starts a branch numbered 1 at  revision  1.3, and
  1196. assigns  the number 1.3.1.1 to the new revision.  For more information
  1197. about branches, see *Note rcsOptb::.
  1198. File: rcs,  Node: rcsintroAutoIdent,  Prev: rcsintroStart,  Up: rcsIntroduction
  1199. Automatic Identification
  1200. ========================
  1201.    RCS can put special strings for identification  into  your source
  1202. and  object  code.  To obtain such identification, place the marker
  1203.      $Id$
  1204.    into your text, for instance inside a comment.   RCS  will replace
  1205. this marker with a string of the form
  1206.      $Id:  filename revision date time author state $
  1207.    With such a marker on the first page of each  module,  you can
  1208. always  see with which revision you are working.  RCS keeps the markers
  1209. up to date automatically.  To  propagate the  markers  into  your
  1210. object code, simply put them into literal character strings.  In C,
  1211. this is done as follows:
  1212.      static char rcsid[] = "$Id$";
  1213.    The  command  ident  extracts  such markers from any file, even
  1214. object code and dumps.  Thus, ident lets you find out which revisions
  1215. of which modules were used in a given program.
  1216.    You may also find it useful to put the marker  $Log$  into your
  1217. text, inside a comment.  This marker accumulates the log messages that
  1218. are requested  during  check-in.   Thus, you  can  maintain  the
  1219. complete  history  of  your  file directly inside it.  There are
  1220. several additional  identification markers; see *Note coKeyword:: for
  1221. details.
  1222. File: rcs,  Node: Synopsis,  Next: CheckIn,  Prev: rcsIntroduction,  Up: Top
  1223. Synopsis of RCS Operations
  1224. **************************
  1225.    * ci - check in revisions
  1226.      `Ci' stores the contents of a working file into the corresponding
  1227.      RCS file as a new revision.  If the RCS file doesn't exist, `ci'
  1228.      creates it.  `Ci' removes the working file, unless one of the
  1229.      options `-u' or `-l' is present.  For each check-in, `ci' asks for
  1230.      a commentary describing the changes relative to the previous
  1231.      revision.
  1232.      `Ci' assigns the revision number given by the `-r' option; if that
  1233.      option is missing, it derives the number from the lock held by the
  1234.      user; if there is no lock and locking is not strict, `ci'
  1235.      increments the number of the latest revision on the trunk.  A side
  1236.      branch can only be started by explicitly specifying its number
  1237.      with the `-r' option during check-in.
  1238.      `Ci' also determines whether the revision to be checked in is
  1239.      different from the previous one, and asks whether to proceed if
  1240.      not.  This facility simplifies check-in operations for large
  1241.      systems, because one need not remember which files were changed.
  1242.      The option `-k' searches the checked in file for identification
  1243.      markers containing the attributes revision number, check-in date,
  1244.      author and state, and assigns these to the new revision rather
  1245.      than computing them.  This option is useful for software
  1246.      distribution: Recipients of distributed software using RCS should
  1247.      check in updates with the `-k' option.  This convention guarantees
  1248.      that revision numbers, check-in dates, etc., are the same at all
  1249.      sites.
  1250.    * co - check out revisions
  1251.      `Co' retrieves revisions according to revision number, date,
  1252.      author and state attributes.  It either places the revision into
  1253.      the working file, or prints it on the standard output.  `Co'
  1254.      always expands the identification markers.
  1255.    * ident - extract identification markers
  1256.      `Ident' extracts the identification markers expanded by `co' from
  1257.      any file and prints them.
  1258.    * rcs - change RCS file attributes
  1259.      `Rcs'is an administrative operation that changes access lists,
  1260.      locks, unlocks, breaks locks, toggles the strict-locking feature,
  1261.      sets state attributes and symbolic revision numbers, changes the
  1262.      description, and deletes revisions.  A revision can only be
  1263.      deleted if it is not the fork of a side branch.
  1264.    * rcsclean - clean working directory
  1265.      `Rcsclean' removes working files that were checked out but never
  1266.      changed.  (1)
  1267.    * rcsdiff - compare revisions
  1268.      `Rcsdiff' compares two revisions and prints their difference,
  1269.      using the UNIX tool `diff'.  One of the revisions compared may be
  1270.      checked out.  This command is useful for finding out about changes.
  1271.    * rcsfreeze - freeze a configuration
  1272.      `Rcsfreeze' assigns the same symbolic revision number to a given
  1273.      revision in all RCS files.  This command is useful for accurately
  1274.      recording a configuration.
  1275.    * rcsmerge - merge revisions
  1276.      `Rcsmerge' merges two revisions, `rev1' and `rev2', with respect
  1277.      to a common ancestor.  A 3-way file comparison determines the
  1278.      segments of lines that are (a) the same in all three revisions, or
  1279.      (b) the same in 2 revisions, or (c) different in all three.  For
  1280.      all segments of type (b) where `rev1' is the differing revision,
  1281.      the segment in `rev1' replaces the corresponding segment of `rev2'.
  1282.      Type (c) indicates an overlapping change, is flagged as an error,
  1283.      and requires user intervention to select the correct alternative.
  1284.    * rlog - read log messages
  1285.      `Rlog' prints the log messages and other information in an RCS
  1286.      file.
  1287.    ---------- Footnotes ----------
  1288.    (1)  The `rcsclean' and `rcsfreeze' commands are optional and are
  1289. not always installed.
  1290. File: rcs,  Node: CheckIn,  Next: CheckOut,  Prev: Synopsis,  Up: Top
  1291. ci - check in RCS revisions
  1292. ***************************
  1293. * Menu:
  1294. * ciIntro::      Introduction to `ci'.
  1295. * ciOptions::    command line options of `ci'.
  1296. * ciFileNaming:: File naming.
  1297. * ciExamples::   Examples.
  1298. * ciFileModes::  File modes.
  1299. * ciFiles::      Files.
  1300. * setuid use::   Using of uid.
  1301. * ciEnv::        Environment which can change
  1302.                  the behaviour of `ci' and
  1303.                  other RCS commands.
  1304. * ciDiag::       Diagnostic output of `ci'.
  1305. File: rcs,  Node: ciIntro,  Next: ciOptions,  Up: CheckIn
  1306. ci description
  1307. ==============
  1308.    `ci' stores new revisions into RCS files. Each pathname matching an
  1309. RCS suffix is taken to be an RCS file. All others are assumed to be
  1310. working files containing new revisions. `ci' deposits the contents of
  1311. each working file into the corresponding RCS file. If only a working
  1312. file is given, `ci' tries to find the corresponding RCS file in an RCS
  1313. subdirectory and then in the working file's directory. For more
  1314. details, *Note ciFileNaming:: below.
  1315.    For `ci' to work, the caller's login must be on the access list,
  1316. except if the access list is empty or the caller is the superuser or
  1317. the owner of the file. To append a new revision to an existing branch,
  1318. the tip revision on that branch must be locked by the caller.
  1319. Otherwise, only a new branch can be created.  This restriction is not
  1320. enforced for the owner of the file if non-strict locking is used (see
  1321. *Note rcs::). A lock held by someone else can be broken with the `rcs'
  1322. command.
  1323.    Unless the `-f' option is given, `ci' checks whether the revision to
  1324. be deposited differs from the preceding one. If not, instead of
  1325. creating a new revision `ci' reverts to the preceding one. To revert,
  1326. ordinary `ci' removes the working file and any lock; `ci -l' keeps and
  1327. `ci -u' removes any lock, and then they both generate a new working file
  1328. much as if `co -l' or `co -u' had been applied to the preceding
  1329. revision. When reverting, any `-n' and `-s' options apply to the
  1330. preceding revision.
  1331.    For each revision deposited, `ci' prompts for a log message.  The
  1332. log message should summarize the change and must be terminated by
  1333. end-of-file or by a line containing `.' by itself. If several files are
  1334. checked in `ci' asks whether to reuse the previous log message. If the
  1335. standard input is not a terminal, `ci' suppresses the prompt and uses
  1336. the same log message for all files(Option `-m' of `ci', *Note ciOptm::).
  1337.    If the RCS file does not exist, `ci' creates it and deposits the
  1338. contents of the working file as the initial revision (default number:
  1339. `1.1' ). The access list is initialized to empty.  Instead of the log
  1340. message, `ci' requests descriptive text (Option `-t' of `ci', *Note
  1341. ciOptt::) below).
  1342.    The number `rev' of the deposited revision can be given by any of
  1343. the options `-f', `-i', `-I', `-j', `-k', `-l', `-M', `-q', `-r' or `-u'
  1344. `rev' can be symbolic, numeric, or mixed.  Symbolic names in `rev' must
  1345. already be defined; see the Option `-n' (*Note ciOptn::) and `-N'
  1346. (*Note ciOptNu::) options for assigning names during checkin.
  1347.    If `rev' is `$', `ci' determines the revision number from keyword
  1348. values in the working file.
  1349.    If `rev' begins with a period, then the default branch (normally the
  1350. trunk) is prepended to it. If `rev' is a branch number followed by a
  1351. period, then the latest revision on that branch is used.
  1352.    If `rev' is a revision number, it must be higher than the latest one
  1353. on the branch to which `rev' belongs, or must start a new branch.
  1354.    If `rev' is a branch rather than a revision number, the new revision
  1355. is appended to that branch.  The level number is obtained by
  1356. incrementing the tip revision number of that branch.  If `rev'
  1357. indicates a non-existing branch, that branch is created with the
  1358. initial revision numbered `rev .1.'
  1359.    If `rev' is omitted, `ci' tries to derive the new revision number
  1360. from the caller's last lock.  If the caller has locked the tip revision
  1361. of a branch, the new revision is appended to that branch. The new
  1362. revision number is obtained by incrementing the tip revision number. If
  1363. the caller locked a non-tip revision, a new branch is started at that
  1364. revision by incrementing the highest branch number at that revision. The
  1365. default initial branch and level numbers are `1.'.
  1366.    If `rev' is omitted and the caller has no lock, but owns the file
  1367. and locking is not set to  `strict', then the revision is appended to
  1368. the default branch (normally the trunk; see the option `-b' of `rcs'
  1369. *Note rcsOptb::).
  1370.    Exception: On the trunk, revisions can be appended to the end, but
  1371. not inserted.
  1372. File: rcs,  Node: ciOptions,  Next: ciFileNaming,  Prev: ciIntro,  Up: CheckIn
  1373. Command line options of ci
  1374. ==========================
  1375.    Overview off all options which can be given to
  1376.    `Synopsis': ci [options] file ...
  1377.    `ci'.
  1378. * Menu:
  1379. * ciOptr::     -r Revision
  1380. * ciOptl::     -l lock a revision.
  1381. * ciOptu::     -u unlock a revision.
  1382. * ciOptf::     -f force a deposit.
  1383. * ciOptk::     -k search for keyword values.
  1384. * ciOptq::     -q quiet mode
  1385. * ciOpti::     -i initial
  1386. * ciOptj::     -j just check in
  1387. * ciOptIu::    -I interacitve mode
  1388. * ciOptd::     -d date
  1389. * ciOptMu::    -M
  1390. * ciOptm::     -m log message
  1391. * ciOptn::     -n symbolic name
  1392. * ciOptNu::    -N replace an existing symbolic name
  1393. * ciOpts::     -s set state
  1394. * ciOptt::     -t discription
  1395. * ciOptTu::    -T modification time
  1396. * ciOptw::     -w login
  1397. * ciOptV::     -V Version of RCS; Emulate RCS Version
  1398. * ciOptx::     -x Suffixes
  1399. * ciOptz::     -z Time zoone for output.
  1400. File: rcs,  Node: ciOptr,  Next: ciOptl,  Up: ciOptions
  1401. Check in revision
  1402. -----------------
  1403. `-r`rev''
  1404.      Check in revision rev.
  1405.      The bare `-r' option (without any revision) has an unusual meaning
  1406.      in `ci'. With other RCS  commands, a bare `-r' option specifies
  1407.      the most recent revision on the default branch, but with `ci', a
  1408.      bare `-r' option reestablishes the default behavior of releasing a
  1409.      lock and removing the working file, and is used to override any
  1410.      default `-l' or `-u' options established by shell aliases or
  1411.      scripts.
  1412. File: rcs,  Node: ciOptl,  Next: ciOptu,  Prev: ciOptr,  Up: ciOptions
  1413. lock a revision
  1414. ---------------
  1415. `-l[`rev']'
  1416.      works like `-r', except it performs an additional `co-l' for the
  1417.      deposited revision.  Thus, the deposited revision is immediately
  1418.      checked out again and locked. This is useful for saving a revision
  1419.      although one wants to continue editing it after the checkin.
  1420. File: rcs,  Node: ciOptu,  Next: ciOptf,  Prev: ciOptl,  Up: ciOptions
  1421. unlock a revision
  1422. -----------------
  1423. `-u[`rev']'
  1424.      works like `-l', except that the deposited revision is not locked.
  1425.      This lets one read the working file immediately after checkin.
  1426.      The `-l', bare `-r', and `-u' options are mutually exclusive and
  1427.      silently override each other. For example, `ci -u -r' is
  1428.      equivalent to `ci -r' because bare `-r' overrides `-u'.
  1429. File: rcs,  Node: ciOptf,  Next: ciOptk,  Prev: ciOptu,  Up: ciOptions
  1430. force a deposit
  1431. ---------------
  1432. `-f[`rev']'
  1433.      forces a deposit; the new revision is deposited even it is not
  1434.      different from the preceding one.
  1435. File: rcs,  Node: ciOptk,  Next: ciOptq,  Prev: ciOptf,  Up: ciOptions
  1436. keyword values
  1437. --------------
  1438. `-k[`rev']'
  1439.      searches the working file for keyword values to determine its
  1440.      revision number, creation date, state, and author (see *Note
  1441.      CheckOut::), and assigns these values to the deposited revision,
  1442.      rather than computing them locally. It also generates a default
  1443.      login message noting the login of the caller and the actual
  1444.      checkin date. This option is useful for software distribution.  A
  1445.      revision that is sent to several sites should be checked in with
  1446.      the `-k' option at these sites to preserve the original number,
  1447.      date, author, and state. The extracted keyword values and the
  1448.      default log message can be overridden with the options `-d', `-m',
  1449.      `-s', `-w', and any option that carries a revision number.
  1450. File: rcs,  Node: ciOptq,  Next: ciOpti,  Prev: ciOptk,  Up: ciOptions
  1451. quiet
  1452. -----
  1453. `-q[`rev']'
  1454.      quiet mode; diagnostic output is not printed. A revision that is
  1455.      not different from the preceding one is not deposited, unless `-f'
  1456.      is given.
  1457. File: rcs,  Node: ciOpti,  Next: ciOptj,  Prev: ciOptq,  Up: ciOptions
  1458. initial check in
  1459. ----------------
  1460. `-i[`rev']'
  1461.      initial checkin; report an error if the RCS file already exists.
  1462.      This avoids race conditions in certain applications.
  1463. File: rcs,  Node: ciOptj,  Next: ciOptIu,  Prev: ciOpti,  Up: ciOptions
  1464. just check in
  1465. -------------
  1466. `-j[`rev']'
  1467.      just checkin and do not initialize; report an error if the RCS
  1468.      file does not already exist.
  1469. File: rcs,  Node: ciOptIu,  Next: ciOptd,  Prev: ciOptj,  Up: ciOptions
  1470. interactive mode
  1471. ----------------
  1472. `-I[`rev']'
  1473.      interactive mode; the user is prompted and questioned even if the
  1474.      standard input is not a terminal.
  1475. File: rcs,  Node: ciOptd,  Next: ciOptMu,  Prev: ciOptIu,  Up: ciOptions
  1476. `-d[`date']'
  1477.      uses `date' for the checkin date and time. The `date' is specified
  1478.      in free format as explained in `co' (*Note CheckOut::).  This is
  1479.      useful for lying about the checkin date, and for `-k' if no date
  1480.      is available. If `date' is empty, the working file's time of last
  1481.      modification is used.
  1482. File: rcs,  Node: ciOptMu,  Next: ciOptm,  Prev: ciOptd,  Up: ciOptions
  1483. modification time
  1484. -----------------
  1485. `-M[`rev']'
  1486.      Set the modification time on any new working file to be the date
  1487.      of the retrieved revision. For example, `ci -d -M -u f' does not
  1488.      alter `f' 's modification time, even if `f''s contents change due
  1489.      to keyword substitution. Use this option with care; it can confuse
  1490.      `MAKE'.
  1491. File: rcs,  Node: ciOptm,  Next: ciOptn,  Prev: ciOptMu,  Up: ciOptions
  1492. log message
  1493. -----------
  1494. `-m[`msg']'
  1495.      uses the string `msg' as the log message for all revisions checked
  1496.      in. By convention, log messages that start with `#' are comments
  1497.      and are ignored by programs like GNU Emacs's `vc' package. Also,
  1498.      log messages that start with `{ clumpname }' (followed by white
  1499.      space) are meant to be clumped together if possible, even if they
  1500.      are associated with different files; the `{ clumpname }' label is
  1501.      used only for clumping, and is not considered to be part of the
  1502.      log message itself.
  1503. File: rcs,  Node: ciOptn,  Next: ciOptNu,  Prev: ciOptm,  Up: ciOptions
  1504. symbolic name
  1505. -------------
  1506. `-n[`name']'
  1507.      assigns the symbolic name `name' to the number of the checked-in
  1508.      revision. `ci' prints an error message if `name' is already
  1509.      assigned to another number.
  1510. File: rcs,  Node: ciOptNu,  Next: ciOpts,  Prev: ciOptn,  Up: ciOptions
  1511. replace symbolic name
  1512. ---------------------
  1513. `-N[`name']'
  1514.      same as `-n', except that it overrides a previous assignment of
  1515.      `name'.
  1516. File: rcs,  Node: ciOpts,  Next: ciOptt,  Prev: ciOptNu,  Up: ciOptions
  1517. states
  1518. ------
  1519. `-s[`state']'
  1520.      sets the state of the checked-in revision to the identifier
  1521.      `state'. The default state is `Exp'.
  1522. File: rcs,  Node: ciOptt,  Next: ciOptTu,  Prev: ciOpts,  Up: ciOptions
  1523. description
  1524. -----------
  1525. `-t`file''
  1526.      writes descriptive text from the contents of the named `file' into
  1527.      the RCS file, deleting the existing text.  The `file' cannot begin
  1528.      with `-'.
  1529. `-t-`string''
  1530.      Write descriptive text from the `string' into the RCS file,
  1531.      deleting the existing text.
  1532.      The `-t' option, in both its forms, has effect only during an
  1533.      initial checkin; it is silently ignored otherwise.
  1534.      During the initial checkin, if `-t' is not given, `ci' obtains the
  1535.      text from standard input, terminated by end-of-file or by a line
  1536.      containing `.' by itself. The user is prompted for the text if
  1537.      interaction is possible; see optiom `-I' of `ci'(*Note ciOptIu::).
  1538.      For backward compatibility with older versions of RCS, a bare `-t'
  1539.      option is ignored.
  1540. File: rcs,  Node: ciOptTu,  Next: ciOptw,  Prev: ciOptt,  Up: ciOptions
  1541. modification time
  1542. -----------------
  1543.      Set the RCS file's modification time to the new revision's time if
  1544.      the former precedes the latter and there is a new revision;
  1545.      preserve the RCS file's modification time otherwise. If you have
  1546.      locked a revision, `ci' usually updates the RCs file's
  1547.      modification time to the current time, because the lock is stored
  1548.      in the RCS file and removing the lock requires changing the RCS
  1549.      file. This can create an RCS file newer than the working file in
  1550.      one of two ways: first, `ci -M' can create a working file with a
  1551.      date before the current time; second, when reverting to the
  1552.      previous revision the RCS file can change while the working file
  1553.      remains unchanged. These two cases can cause excessive
  1554.      recompilation caused by a `MAKE' dependency of the working file on
  1555.      the RCS file. The `-T' option inhibits this recompilation by lying
  1556.      about the RCS file's date. Use this option with care; it can
  1557.      suppress recompilation even when a checkin of one working file
  1558.      should affect another working file associated with the same RCS
  1559.      file. For example, suppose the RCS file's time is 01:00, the
  1560.      (changed) working file's time is 02:00, some other copy of the
  1561.      working file has a time of 03:00, and the current time is 04:00.
  1562.      Then `ci -d -T' sets the RCS file's time to 02:00 instead of the
  1563.      usual 04:00; this causes `MAKE' to think (incorrectly) that the
  1564.      other copy is newer than the RCs file.
  1565. File: rcs,  Node: ciOptw,  Next: ciOptV,  Prev: ciOptTu,  Up: ciOptions
  1566. login
  1567. -----
  1568. `-w`login''
  1569.      uses `login' for the author field of the deposited revision.
  1570.      Useful for lying about the author, and for `-k' if no author is
  1571.      available.
  1572. File: rcs,  Node: ciOptV,  Next: ciOptx,  Prev: ciOptw,  Up: ciOptions
  1573. version and emulation
  1574. ---------------------
  1575.      Print RCS's version number.
  1576. `-V`n''
  1577.      Emulate RCS version `n'. *Note coOptV::
  1578. File: rcs,  Node: ciOptx,  Next: ciOptz,  Prev: ciOptV,  Up: ciOptions
  1579. suffixes
  1580. --------
  1581. `-x`suffixes''
  1582.      specifies the suffixes for RCS files. A nonempty suffix matches
  1583.      any pathname ending in the suffix. An empty suffix matches any
  1584.      pathname of the form `RCS/path' or `path1/RCS/path2'. The `-x'
  1585.      option can specify a list of suffixes separated by `.' For
  1586.      example, `-x,v/' specifies two suffixes: `,v' and the empty
  1587.      suffix. If two or more suffixes are specified, they are tried in
  1588.      order when looking for an RCS file; the first one that works is
  1589.      used for that file.  If no RCS file is found but an RCS file can
  1590.      be created, the suffixes are tried in order to determine the new
  1591.      RCS file's name.  The default for `suffixes' is
  1592.      installation-dependent; normally it is `,v/' for hosts like Unix
  1593.      that permit commas in filenames, and is empty (i.e. just the empty
  1594.      suffix) for other hosts.
  1595. File: rcs,  Node: ciOptz,  Prev: ciOptx,  Up: ciOptions
  1596. time zoone
  1597. ----------
  1598. `-z`zoone''
  1599.      specifies the date output format in keyword substitution, and
  1600.      specifies the default time zone for `date' in the `-d`date''
  1601.      option. The `zoone' should be empty, a numeric UTC offset, or the
  1602.      special string `LT' for local time. The default is an empty
  1603.      `zoone', which uses the traditional RCS format of UTC without any
  1604.      time zone indication and with slashes separating the parts of the
  1605.      date; otherwise, times are output in ISO 8601 format with time
  1606.      zone indication. For example, if local time is January 11, 1990,
  1607.      8pm Pacific Standard Time, eight hours west of UTC, then the time
  1608.      is output as follows:
  1609.           `Option'   `time output'
  1610.           `-z'       `1990/01/11 04:00:00'       (default)
  1611.           `-zLT'     `1990-01-11 20:00:00-0800'
  1612.           `-z+0530'  `1990-01-11 09:30:00+0530'
  1613.      This option does not affect dates stored in RCS files, which are
  1614.      always UTC.
  1615. File: rcs,  Node: ciFileNaming,  Next: ciExamples,  Prev: ciOptions,  Up: CheckIn
  1616. FILE NAMING
  1617. ===========
  1618.    Pairs of RCS files and working files can be specified in three ways
  1619. (see also the example section).
  1620.   1. Both the file and the working file are given.  The RCS pathname is
  1621.      of the form `path1/workfileX' and the working pathname is of the
  1622.      form `path2/workfile' where `path1/' and `path2/' are (possibly
  1623.      different or empty) paths, `workfile' is a filename, and `X' is an
  1624.      RCs suffix. If `X' is empty, `path1/' must start with `RCS/' or
  1625.      must contain `/RCS/'.
  1626.   2. Only the RCS file is given.  Then the working file is created in
  1627.      the current directory and its name is derived from the name of the
  1628.      RCS file by removing `path1/' and the suffix `X'.
  1629.   3. Only the working file is given. Then `ci' considers each RCS
  1630.      suffix `X' in turn, looking for an RCS file of the form
  1631.      `path2/RCS/workfileX' or (if the former is not found and `X' is
  1632.      nonempty) `path2/workfileX'.
  1633.    If the RCS file is specified without a path in 1) and 2), `ci' looks
  1634. for the RCS file first in the directory `./RCS' and then in the current
  1635. directory.
  1636.    `ci' reports an error if an attempt to open an RCS file fails for an
  1637. unusual reason, even if the RCS file's pathname is just one of several
  1638. possibilities. For example, to suppress use of RCS commands in a
  1639. directory `d' , create a regular file named `d/RCS' so that casual
  1640. attempts to use RCS commands in `d' fail because `d/RCS' is not a
  1641. directory.
  1642. File: rcs,  Node: ciExamples,  Next: ciFileModes,  Prev: ciFileNaming,  Up: CheckIn
  1643. Examples
  1644. ========
  1645.    Suppose `,v' is an RCS suffix and the current directory contains a
  1646. subdirectory `RCS' with an RCS file `io.c,v'. Then each of the
  1647. following commands check in a copy of `io.c' into `RCS/io.c,v' as the
  1648. latest revision, removing `io.c'.
  1649.      ci  io.c
  1650.      ci  RCS/io.c,v
  1651.      ci  io.c,v
  1652.      ci  io.c RCS/io.c,v
  1653.      ci  io.c io.c,v
  1654.      ci  RCS/io.c,v  io.c
  1655.      ci  io.c,v  io.c
  1656.    Suppose instead that the empty suffix is an RCS suffix and the
  1657. current directory contains a subdirectory `RCS' with an RCS file
  1658. `io.c'. The each of the following commands checks in a new revision.
  1659.      ci  io.c
  1660.      ci  RCS/io.c
  1661.      ci  io.c  RCS/io.c
  1662.      ci  RCS/io.c  io.c
  1663. File: rcs,  Node: ciFileModes,  Next: ciFiles,  Prev: ciExamples,  Up: CheckIn
  1664. File Modes
  1665. ==========
  1666.    An RCS file created by `ci' inherits the read and execute
  1667. permissions from the working file.  If the RCS file exists already,
  1668. `ci' preserves its read and execute permissions.  `ci' always turns off
  1669. all write permissions of RCS files.
  1670. File: rcs,  Node: ciFiles,  Next: setuid use,  Prev: ciFileModes,  Up: CheckIn
  1671. Files
  1672. =====
  1673.    Temporary files are created in the directory containing the working
  1674. file, and also in the temporary directory (*Note ciEnv:: under *Note
  1675. coEnv::). A semaphore file or files are created in the directory
  1676. containing the RCS file. With a nonempty suffix, the semaphore names
  1677. begin with the first character of the suffix; therefore, do not specify
  1678. an suffix whose first character could be that of a working filename.
  1679. With an empty suffix, the semaphore names end with `_' so working
  1680. filenames should not end in `_'
  1681.    `ci' never changes an RCS or working file. Normally, `ci' unlinks
  1682. the file and creates a new one; but instead of breaking a chain of one
  1683. or more symbolic links to an RCS file, it unlinks the destination file
  1684. instead. Therefore, `ci' breaks any hard or symbolic links to any
  1685. working file it changes; and hard links to RCS files are ineffective,
  1686. but symbolic links to RCS files are preserved.
  1687.    The effective user must be able to search and write the directory
  1688. containing the RCS file. Normally, the real user must be able to read
  1689. the RCS and working files and to search and write the directory
  1690. containing the working file; however, some older hosts cannot easily
  1691. switch between real and effective users, so on these hosts the
  1692. effective user is used for all accesses. The effective user is the same
  1693. as the real user unless your copies of `ci' and `co' have setuid
  1694. privileges. As described in the next section, these privileges yield
  1695. extra security if the effective user owns all RCS files and
  1696. directories, and if only the effective user can write RCS directories.
  1697.    Users can control access to RCS files by setting the permissions of
  1698. the directory containing the files; only users with write access to the
  1699. directory can use RCS commands to change its RCS files. For example, in
  1700. hosts that allow a user to belong to several groups, one can make a
  1701. group's RCS directories writable to that group only. This approach
  1702. suffices for informal projects, but it means that any group member can
  1703. arbitrarily change the group's RCS files, and can even remove them
  1704. entirely. Hence more formal projects sometimes distinguish between an
  1705. RCS administrator, who can change the RCS files at will, and other
  1706. project members, who can check in new revisions but cannot otherwise
  1707. change the RCS files.
  1708. File: rcs,  Node: setuid use,  Next: ciEnv,  Prev: ciFiles,  Up: CheckIn
  1709. Setuid use
  1710. ==========
  1711.    To prevent anybody but their RCS administrator from deleting
  1712. revisions, a set of users can employ setuid privileges as follows.
  1713.    * Check that the host supports RCS setuid use.  Consult a
  1714.      trustworthy expert if there are any doubts.  It is best if the
  1715.      `seteuid' system call works as described in Posix 1003.1a Draft 5,
  1716.      because RCS can switch back and forth easily between real and
  1717.      effective users, even if the real user is `root'.  If not, the
  1718.      second best is if the `setuid' system call supports saved setuid
  1719.      (the `_POSIX_SAVED_IDS' behavior of Posix 1003.1-1990); this fails
  1720.      only if the real or effective user is `root'.  If RCS detects any
  1721.      failure in setuid, it quits immediately.
  1722.    * Choose a user `A' to serve as RCS administrator for the set of
  1723.      users.  Only `A' can invoke the `rcs' command on the users' RCS
  1724.      files.  `A' should not be `root' or any other user with special
  1725.      powers.  Mutually suspicious sets of users should use different
  1726.      administrators.
  1727.    * Choose a pathname `B' to be a directory of files to be executed by
  1728.      the users.
  1729.    * Have `A' set up `B' to contain copies of `ci' and `co' that are
  1730.      setuid to `A' by copying the commands from their standard
  1731.      installation directory `D' as follows:
  1732.           mkdir `B'
  1733.           cp `D'/c[io] `B'
  1734.           chmod go-w,u+s `B'/c[io]
  1735.    * Have each user prepend `B' to their path as follows:
  1736.           PATH=`B':$PATH; export PATH # ordinary shell
  1737.           set path=(`B' $path)        # C - shell
  1738.    * Have `A' create each RCS directory `R' with write access only to
  1739.      `A' as follows:
  1740.           mkdir `R'
  1741.           chmod go-w `R'
  1742.    * If you want to let only certain users read the RCS files, put the
  1743.      users into a group `G', and have `A' further protect the RCs
  1744.      directory as follows:
  1745.           chgrp `G'  `R'
  1746.           chmod g-w, o-rwx  `R'
  1747.    * Have `A' copy old RCS files (if any) into `R', to ensure that `A'
  1748.      owns them.
  1749.    * An RCS file's access list limits who can check in and lock
  1750.      revisions.  The default access list is empty, which grants checkin
  1751.      access to anyone who can read the RCS file.  If you want limit
  1752.      checkin access, have `A' invoke `rcs -a' on the file; see *Note
  1753.      rcs:: In particular, `rcs -e -a`A'' limits access to just `A'.
  1754.    * Have `A' initialize any new RCS files with `rcs -i' before initial
  1755.      checkin, adding the `-a' option if you want to limit checkin
  1756.      access.
  1757.    * Give setuid privileges only to `ci', `co', and `rcsclean'; do not
  1758.      give them to `rcs' or to any other command.
  1759.    * Do not use other setuid commands to invoke RCS commands; setuid is
  1760.      trickier than you think!
  1761. File: rcs,  Node: ciEnv,  Next: ciDiag,  Prev: setuid use,  Up: CheckIn
  1762. Environment
  1763. ===========
  1764. `RCSINIT'
  1765.      options prepended to the argument list, separated by spaces.  A
  1766.      backslash escapes spaces within an option.  The `RCSINIT' options
  1767.      are prepended to the argument lists of most RCS commands. Useful
  1768.      `RCSINIT' options include `-q', `-V', `-x' and `-z'.
  1769. `TMPDIR'
  1770.      Name of the temporary directory.  If not set, the environment
  1771.      variables `TMP' and `TEMP' are inspected instead and the first
  1772.      value found is taken; if none of them are set, a host-dependent
  1773.      default is used, typically `/tmp'.
  1774. File: rcs,  Node: ciDiag,  Prev: ciEnv,  Up: CheckIn
  1775. Diagnostics
  1776. ===========
  1777.    For each revision, `ci' prints the RCS file, the working file, and
  1778. the number of both the deposited and the preceding revision. The exit
  1779. status is zero if and only if all operations were successful.
  1780. File: rcs,  Node: CheckOut,  Next: rcs,  Prev: CheckIn,  Up: Top
  1781. co - check out RCS revisions
  1782. ****************************
  1783. * Menu:
  1784. * coIntro::      Introduction to `co'.
  1785. * coOptions::    command line options of `co'.
  1786. * coKeyword::    Keyword expansion and valid keywords.
  1787. * coFileModes::  File modes.
  1788. * coFiles::      Files.
  1789. * coEnv::        Environment which can change
  1790.                  the behaviour of `co' and
  1791.                  other RCS commands.
  1792. * coDiag::       Diagnostic output of `co'.
  1793. * coLimits::     Limits.
  1794. File: rcs,  Node: coIntro,  Next: coOptions,  Up: CheckOut
  1795. co description
  1796. ==============
  1797.    `co' retrieves a revision from each RCS file and stores it into the
  1798. corresponding working file.
  1799.    Pathnames matching an RCS suffix denote RCS files; all others denote
  1800. working files. Names are paired as explained in *Note ciIntro::.
  1801.    Revisions of an RCS file can be checked out locked or unlocked.
  1802. Locking a revision prevents overlapping updates.  A revision checked
  1803. out for reading or processing (e.g., compiling) need not be locked.  A
  1804. revision checked out for editing and later checkin must normally be
  1805. locked.  Checkout with locking fails if the revision to be checked out
  1806. is currently locked by another user.  (A lock can be broken with `rcs'
  1807. *Note rcs::). Checkout with locking also requires the caller to be on
  1808. the access list of the RCS file, unless he is the owner of the file or
  1809. the superuser, or the access list is empty. Checkout without locking is
  1810. not subject to accesslist restrictions, and is not affected by the
  1811. presence of locks.
  1812.    A revision is selected by options for revision or branch number,
  1813. checkin date/time, author, or state. When the selection options are
  1814. applied in combination, `co' retrieves the latest revision that
  1815. satisfies all of them. If none of the selection options is specified,
  1816. `co' retrieves the latest revision on the default branch (normally the
  1817. trunk, see the `-b' option of *Note rcs::). A revision or branch number
  1818. can be attached to any of the options  `-f', `-I', `-l', `-M', `-p',
  1819. `-q', `-r' or `-u'. The options `-d' (date), `-s'(state), and `-w'
  1820. (author) retrieve from a single branch, the `selected' branch, which is
  1821. either specified by one of `-f', ..., `-u', or the default branch.
  1822.    A `co' command applied to an RCS file with no revisions creates a
  1823. zero-length working file. `co' always performs keyword substitution
  1824. (see below).
  1825. File: rcs,  Node: coOptions,  Next: coKeyword,  Prev: coIntro,  Up: CheckOut
  1826. Command line options of co
  1827. ==========================
  1828.    Overview off all options which can be given to `co'
  1829.    `Synopsis': co [options] file ...
  1830. * Menu:
  1831. * coOptr::     -r Revision
  1832. * coOptl::     -l lock a revision.
  1833. * coOptu::     -u unlock a revision.
  1834. * coOptf::     -f Force overwriting working file
  1835. * coOptk::     -k Keyword strings; Substitution and so on.
  1836. * coOptp::     -p Output to standard out.
  1837. * coOptq::     -q Quiet mode.
  1838. * coOptI::     -I Interactive mode.
  1839. * coOptd::     -d Check out by date/time.
  1840. * coOptM::     -M Modification time.
  1841. * coOpts::     -s set state.
  1842. * coOptT::     -T preserve Modification time.
  1843. * coOptw::     -w check out by user.
  1844. * coOptj::     -j Joining revisions.
  1845. * coOptV::     -V Version; Emulation of RCS Version.
  1846. * coOptx::     -x Suffixes.
  1847. * coOptz::     -z Time zone.
  1848. File: rcs,  Node: coOptr,  Next: coOptl,  Up: coOptions
  1849. Check out revision
  1850. ------------------
  1851. `-r`rev''
  1852.      retrieves the latest revision whose number is less than or equal
  1853.      to `rev'. If `rev' indicates a branch rather than a revision, the
  1854.      latest revision on that branch is retrieved. If `rev' is omitted,
  1855.      the latest revision on the default branch (see the `-b' option of
  1856.      *Note rcs::) is retrieved. If `rev' is `$', `co' determines the
  1857.      revision number from keyword values in the working file.
  1858.      Otherwise, a revision is composed of one or more numeric or
  1859.      symbolic fields separated by periods. If `rev' begins with a
  1860.      period, then the default branch (normally the trunk) is prepended
  1861.      to it. If `rev' is a branch number followed by a period, then the
  1862.      latest revision on that branch is used. The numeric equivalent of
  1863.      a symbolic field is specified with the `-n' option of the commands
  1864.      *Note ciOptn:: and *Note rcsOptn::.
  1865. File: rcs,  Node: coOptl,  Next: coOptu,  Prev: coOptr,  Up: coOptions
  1866. Lock revision
  1867. -------------
  1868. `-l`rev''
  1869.      same as `-r', except that it also locks the retrieved revision for
  1870.      the caller.
  1871. File: rcs,  Node: coOptu,  Next: coOptf,  Prev: coOptl,  Up: coOptions
  1872. Unlock revision
  1873. ---------------
  1874. `-l`rev''
  1875.      same as `-r', except that it unlocks the retrieved revision if it
  1876.      was locked by the caller.  If `rev' is omitted, `-u' retrieves the
  1877.      revision locked by the caller, if there is one; otherwise, it
  1878.      retrieves the latest revision on the default branch.
  1879. File: rcs,  Node: coOptf,  Next: coOptk,  Prev: coOptu,  Up: coOptions
  1880. Force overwriting working file
  1881. ------------------------------
  1882. `-f`rev''
  1883.      forces the overwriting of the working file; useful in connection
  1884.      with `-q'.  *Note coFileModes::
  1885. File: rcs,  Node: coOptk,  Next: coOptp,  Prev: coOptf,  Up: coOptions
  1886. Keyword strings
  1887. ---------------
  1888. `-kkv'
  1889.      Generate keyword strings using the default form, e.g.  `$Revision
  1890.      : 5.12 $' for the `Revision' keyword. A locker's name is inserted
  1891.      in the value of the `Header', `Id', and `Locker' keyword strings
  1892.      only as a file is being locked, i.e. by `ci -l' and `co -l'. This
  1893.      is the default.
  1894. `-kkvl'
  1895.      Like `-kkv', except that a locker's name is always inserted if the
  1896.      given revision is currently locked.
  1897. `-kk'
  1898.      Generate only keyword names in keyword strings; omit their values.
  1899.      See *Note coKeyword:: below. For example, for the `Revision'
  1900.      keyword, generate the string `$Revsion$' instead of `$Revision:
  1901.      5.12 $'. This option is useful to ignore differences due to
  1902.      keyword substitution when comparing different revisions of a file.
  1903.      Log messages are inserted after `$Log$' keywords even if `-kk' is
  1904.      specified, since this tends to be more useful when merging changes.
  1905. `-ko'
  1906.      Generate the old keyword string, present in the working file just
  1907.      before it was checked in.  For example, for the `Revision'
  1908.      keyword, generate the string `$Revision: 1.1 $' instead of
  1909.      `$Revision: 5.12 $' if that is how the string appeared when the
  1910.      file was checked in.  This can be useful for file formats that
  1911.      cannot tolerate any changes to substrings that happen to take the
  1912.      form of keyword strings.
  1913. `-kb'
  1914.      Generate a binary image of the old keyword string. This acts like
  1915.      `-ko', except it performs all working file input and output in
  1916.      binary mode. This makes little difference on Posix and Unix hosts,
  1917.      but on DOS-like hosts one should use `rcs -i -kb' to initialize an
  1918.      RCS file intended to be used for binary files.  Also, on all
  1919.      hosts, *Note rcsmerge:: normally refuses to merge files when `-kb'
  1920.      is in effect.
  1921. `-kv'
  1922.      Generate only keyword values for keyword strings. For example, for
  1923.      the `Revision' keyword, generate the string `5.12' instead of
  1924.      `$Revision: 5.12 $' This can help generate files in programming
  1925.      languages where it is hard to strip keyword delimiters like
  1926.      `$Revision: $' from a string.  However, further keyword
  1927.      substitution cannot be performed once the keyword names are
  1928.      removed, so this option should be used with care. Because of this
  1929.      danger of losing keywords, this option cannot be combined with
  1930.      `-l', and the owner write permission of the working file is turned
  1931.      off; to edit the file later, check it out again without `-kv'.
  1932. File: rcs,  Node: coOptp,  Next: coOptq,  Prev: coOptk,  Up: coOptions
  1933. Print on standard output
  1934. ------------------------
  1935. `-p`rev''
  1936.      prints the retrieved revision on the standard output rather than
  1937.      storing it in the working file. This option is useful when `co' is
  1938.      part of a pipe.
  1939. File: rcs,  Node: coOptq,  Next: coOptI,  Prev: coOptp,  Up: coOptions
  1940. Quiet mode
  1941. ----------
  1942. `-q`rev''
  1943.      quiet mode; diagnostics are not printed.
  1944. File: rcs,  Node: coOptI,  Next: coOptd,  Prev: coOptq,  Up: coOptions
  1945. Interactive Mode
  1946. ----------------
  1947. `-I`rev''
  1948.      interactive mode; the user is prompted and questioned even if the
  1949.      standard input is not a terminal.
  1950. File: rcs,  Node: coOptd,  Next: coOptM,  Prev: coOptI,  Up: coOptions
  1951. Checkout by date/time
  1952. ---------------------
  1953. `-d`date''
  1954.      retrieves the latest revision on the selected branch whose checkin
  1955.      date/time is less than or equal to `date'.  The date and time can
  1956.      be given in free format.  The time zone `LT' stands for local time;
  1957.      other common time zone names are understood.  For example, the
  1958.      following `date's are equivalent if local time is January 11,
  1959.      1990, 8pm Pacific Standard Time, eight hours west of Coordinated
  1960.      Universal Time (UTC):
  1961.           8:00 pm lt
  1962.           4:00 AM, Jan. 12, 1990             default is UTC
  1963.           1990-01-12 04:00:00+00             ISO 8601 (UTC)
  1964.           1990-01-11 20:00:00-08             ISO 8601 (local time)
  1965.           1990/01/12 04:00:00                traditional RCS format
  1966.           Thu Jan 11 20:00:00 1990 LT        output of ctime(3) + LT
  1967.           Thu Jan 11 20:00:00 PST 1990       output of date(1)
  1968.           Fri Jan 12 04:00:00 GMT 1990
  1969.           Thu, 11 Jan 1990 20:00:00 -0800    Internet RFC 822
  1970.           12-January-1990, 04:00 WET
  1971.            
  1972.            
  1973.      Most fields in the date and time can be defaulted. The default
  1974.      time zone is normally UTC, but this can be overridden by the `-z'
  1975.      option. The other defaults are determined in the order year,
  1976.      month, day, hour, minute, and second (most to least significant).
  1977.      At least one of these fields must be provided.  For omitted fields
  1978.      that are of higher significance than the highest provided field,
  1979.      the time zone's current values are assumed. For all other omitted
  1980.      fields, the lowest possible values are assumed. For example,
  1981.      without `-z', the date `20', `10:30' defaults to 10:30:00 UTC of
  1982.      the 20th of the UTC time zone's current month and year. The
  1983.      date/time must be quoted if it contains spaces.
  1984. File: rcs,  Node: coOptM,  Next: coOpts,  Prev: coOptd,  Up: coOptions
  1985. Modification time
  1986. -----------------
  1987. `-M`rev''
  1988.      Set the modification time on the new working file to be the date
  1989.      of the retrieved revision.  Use this option with care; it can
  1990.      confuse `make'.
  1991. File: rcs,  Node: coOpts,  Next: coOptT,  Prev: coOptM,  Up: coOptions
  1992. State
  1993. -----
  1994. `-s`state''
  1995.      retrieves the latest revision on the selected branch whose state
  1996.      is set to `state'.
  1997. File: rcs,  Node: coOptT,  Next: coOptw,  Prev: coOpts,  Up: coOptions
  1998. Preserve Modification time
  1999. --------------------------
  2000.      Preserve the modification time on the RCS file even if the RCS
  2001.      file changes because a lock is added or removed. This option can
  2002.      suppress extensive recompilation caused by a `make' dependency of
  2003.      some other copy of the working file on the RCS file. Use this
  2004.      option with care; it can suppress recompilation even when it is
  2005.      needed, i.e. when the change of lock would mean a change to
  2006.      keyword strings in the other working file.
  2007. File: rcs,  Node: coOptw,  Next: coOptj,  Prev: coOptT,  Up: coOptions
  2008. Checked in by user
  2009. ------------------
  2010. `-w`login''
  2011.      retrieves the latest revision on the selected branch which was
  2012.      checked in by the user with login name `login'. If the argument
  2013.      `login' is omitted, the caller's login is assumed.
  2014. File: rcs,  Node: coOptj,  Next: coOptV,  Prev: coOptw,  Up: coOptions
  2015. Joining revisions
  2016. -----------------
  2017. `-j`joinlist''
  2018.      generates a new revision which is the join of the revisions on
  2019.      `joinlist'. This option is largely obsoleted by `rcsmerge' (*Note
  2020.      rcsmerge::) but is retained for backwards compatibility.
  2021.      The `joinlist' is a comma-separated list of pairs of the form
  2022.      `rev2 : rev3', where `rev2' and `rev3' are (symbolic or numeric)
  2023.      revision numbers. For the initial such pair, `rev1' denotes the
  2024.      revision selected by the above options `-f', ..., `-w'. For all
  2025.      other pairs, `rev1' denotes the revision generated by the previous
  2026.      pair.  (Thus, the output of one join becomes the input to the
  2027.      next.)
  2028.      For each pair, `co' joins revisions `rev1' and `rev3' with respect
  2029.      to `rev2'. This means that all changes that transform `rev2' into
  2030.      `rev1' are applied to a copy of `rev3'. This is particularly
  2031.      useful if `rev1' and `rev3' are the ends of two branches that have
  2032.      `rev2' as a common ancestor.  If `rev1 < rev2 < rev3' on the same
  2033.      branch, joining generates a new revision which is like `rev3', but
  2034.      with all changes that lead from `rev1' to `rev2' undone. If
  2035.      changes from `rev2' to `rev1' overlap with changes from `rev2' to
  2036.      `rev3', `co' reports overlaps as described in `merge'.
  2037.      For the initial pair, `rev2' can be omitted.  The default is the
  2038.      common ancestor. If any of the arguments indicate branches, the
  2039.      latest revisions on those branches are assumed. The options `-l'
  2040.      and `-u' lock or unlock `rev1'.
  2041. File: rcs,  Node: coOptV,  Next: coOptx,  Prev: coOptj,  Up: coOptions
  2042. Version, Emulate RCS Version
  2043. ----------------------------
  2044.      Print RCS's version number.
  2045. `-V`n''
  2046.      Emulate RCS version `n', where `n' can be `3', `4', or `5'. This
  2047.      can be useful when interchanging RCS files with others who are
  2048.      running older versions of RCS. To see which version of RCS your
  2049.      correspondents are running, have them invoke `rcs -V'; this works
  2050.      with newer versions of RCS. If it doesn't work, have them invoke
  2051.      `rlog' (*Note rlog::) on an RCS file; if none of the first few
  2052.      lines of output contain the string `branch:' it is version 3; if
  2053.      the dates' years have just two digits, it is version 4; otherwise,
  2054.      it is version 5. An RCS file generated while emulating version 3
  2055.      loses its default branch. An RCS revision generated while
  2056.      emulating version 4 or earlier has a time stamp that is off by up
  2057.      to 13 hours. A revision extracted while emulating version 4 or
  2058.      earlier contains abbreviated dates of the form `yy/mm/dd' and can
  2059.      also contain different white space and line prefixes in the
  2060.      substitution for $Log$.
  2061. File: rcs,  Node: coOptx,  Next: coOptz,  Prev: coOptV,  Up: coOptions
  2062. Suffixes
  2063. --------
  2064. `-x`suffixes''
  2065.      Use `suffixes' to characterize RCS files.  *Note ciOptx:: for
  2066.      details.
  2067. File: rcs,  Node: coOptz,  Prev: coOptx,  Up: coOptions
  2068. Time Zoone
  2069. ----------
  2070. `-z`zoone''
  2071.      *Note ciOptz:: for details.
  2072. File: rcs,  Node: coKeyword,  Next: coFileModes,  Prev: coOptions,  Up: CheckOut
  2073. Keyword Substitution
  2074. ====================
  2075.    Strings of the form `$keyword$' and `$keyword : ...$' embedded in
  2076. the text are replaced with strings of the form `$keyword:value$' where
  2077. `keyword' and `value' are pairs listed below.  Keywords can be embedded
  2078. in literal strings or comments to identify a revision.
  2079.    Initially, the user enters strings of the form `$keyword$'.  On
  2080. checkout, `co' replaces these strings with strings of the form
  2081. `$keyword:value$'.  If a revision containing strings of the latter form
  2082. is checked back in, the value fields will be replaced during the next
  2083. checkout. Thus, the keyword values are automatically updated on
  2084. checkout. This automatic substitution can be modified by the `-k'
  2085. options.
  2086.    Keywords and their corresponding values:
  2087. `$Author$'
  2088.      The login name of the user who checked in the revision.
  2089. `$Date$'
  2090.      The date and time the revision was checked in.  With `-z`zone'' a
  2091.      numeric time zone offset is appended; otherwise, the date is UTC.
  2092. `$Header$'
  2093.      A standard header containing the full pathname of the RCS file, the
  2094.      revision number, the date and time, the author, the state, and the
  2095.      locker (if locked). With `-z`zone'' a numeric time zone offset is
  2096.      appended to the date; otherwise, the date is RCS.
  2097. `$Id$'
  2098.      Same as `$Header$', except that the RCS filename is without a path.
  2099. `$Locker$'
  2100.      The login name of the user who locked the revision (empty if not
  2101.      locked).
  2102. `$Log$'
  2103.      The log message supplied during checkin, preceded by a header
  2104.      containing the RCS filename, the revision number, the author, and
  2105.      the date and time. With `-z`zone'' a numeric time zone offset is
  2106.      appended; otherwise, the date is UTC. Existing log messages are
  2107.      `not' replaced. Instead, the new log message is inserted after
  2108.      `$Log: ... $'. This is useful for accumulating a complete change
  2109.      log in a source file.
  2110.      Each  inserted  line is prefixed by the string that prefixes the
  2111.      `$Log$' line.  For example, if the `$Log$' line is `"// $Log:
  2112.      tan.cc $"', RCS prefixes each line of the log with "// ".  This
  2113.      is useful  for  languages  with  comments  that  go  to the end of
  2114.      the line.  The convention for other languages is to use a `"  *
  2115.      "'  prefix inside a multiline comment.  For example, the initial
  2116.      log comment  of  a  C  program conventionally is of the following
  2117.      form:
  2118.           /*
  2119.            * $Log$
  2120.            */
  2121.      For  backwards compatibility with older versions of RCS, if the
  2122.      log prefix is `/*' or  `(*' surrounded  by optional white space,
  2123.      inserted log lines contain a space instead of `/' or `('; however,
  2124.      this  usage  is obsolescent and should not be relied on.
  2125. `$Name$'
  2126.      The symbolic name used to check out the revision, if any. For
  2127.      example, `"co -rJoe"' generates `"$Name: Joe $"'.  Plain `co'
  2128.      generates just `"$Name:  $"'
  2129. `$RCSFile$'
  2130.      The name of the RCS file without a path.
  2131. `$Revsion$'
  2132.      The revision number assigned to the revision.
  2133. `$Source$'
  2134.      The full pathname of the RCS file.
  2135. `$State$'
  2136.      The state assigned to the revision with the `-s' option of `rcs'
  2137.      or `ci'.
  2138.    The following characters in keyword values are represented by escape
  2139. sequences to keep keyword strings well-formed.
  2140.      `char'    `escape sequence'
  2141.      tab            \t
  2142.      newline        \n
  2143.      space          \040
  2144.      $              \044
  2145.      \              \\
  2146. File: rcs,  Node: coFileModes,  Next: coFiles,  Prev: coKeyword,  Up: CheckOut
  2147. File Modes
  2148. ==========
  2149.    The working file inherits the read and execute permissions from the
  2150. RCS file.  In addition, the owner  write  permis- sion  is turned  on,
  2151. unless  `-kv'  is  set or the file is checked out unlocked and locking
  2152. is  set  to  strict (*Note rcs::).
  2153.    If a file with the name of the working file exists already and has
  2154. write permission, `co' aborts the  checkout,  asking beforehand  if
  2155. possible.  If the existing working file is not writable or `-f' is
  2156. given, the working file  is  deleted without asking.
  2157. File: rcs,  Node: coFiles,  Next: coEnv,  Prev: coFileModes,  Up: CheckOut
  2158. Files
  2159. =====
  2160.    `co' accesses files much as `ci' does, except that it does not need
  2161. to read the working file unless a revision number of `$' is specified.
  2162. File: rcs,  Node: coEnv,  Next: coDiag,  Prev: coFiles,  Up: CheckOut
  2163. Environment
  2164. ===========
  2165. `RCSINIT'
  2166.      options prepended to the argument list, separated by spaces.  See
  2167.      *Note ciEnv:: for details.
  2168. File: rcs,  Node: coDiag,  Next: coLimits,  Prev: coEnv,  Up: CheckOut
  2169. Diagnostics
  2170. ===========
  2171.    The RCS pathname, the working pathname, and  the  revision number
  2172. retrieved  are  written  to the diagnostic output.  The exit status is
  2173. zero if and only if all operations were successful.
  2174. File: rcs,  Node: coLimits,  Prev: coDiag,  Up: CheckOut
  2175. Limits
  2176. ======
  2177.    Links to the RCS and working files are not preserved.
  2178. File: rcs,  Node: rcs,  Next: ident,  Prev: CheckOut,  Up: Top
  2179. rcs - change RCS file attributes
  2180. ********************************
  2181. * Menu:
  2182. * rcsIntro::            Introduction to `rcs'.
  2183. * rcsOptions::          command line options of `rcs'.
  2184. * rcsCompatibility::    Compatibility between RCS Versions.
  2185. * rcsFiles::            Files.
  2186. * rcsEnv::              The Environment which can change the
  2187.                         behaviour of much of the RCS commands.
  2188. * rcsDiag::             Diagnostic output of `rcs'.
  2189. * rcsBugs::             Bugs.
  2190. File: rcs,  Node: rcsIntro,  Next: rcsOptions,  Up: rcs
  2191. Description
  2192. ===========
  2193.    RCS  creates new RCS files or changes attributes of existing ones.
  2194. An RCS  file  contains  multiple  revisions  of text,  an access list,
  2195. a change log, descriptive text, and some control attributes.  For rcs
  2196. to  work,  the  caller's login  name  must  be  on  the  access list,
  2197. except if the access list is empty, the caller is the owner of the  file
  2198. or the superuser, or the `-i' option is present.
  2199.    Pathnames  matching  an  RCS  suffix denote RCS files; all others
  2200. denote  working  files.   Names  are   paired   as explained  in  *Note
  2201. ciIntro::.   Revision  numbers  use  the syntax described in *Note
  2202. ciIntro::.
  2203. File: rcs,  Node: rcsOptions,  Next: rcsCompatibility,  Prev: rcsIntro,  Up: rcs
  2204. Command line options of rcs
  2205. ===========================
  2206.    Overview off all options which can be given to `rcs'
  2207.    `Synopsis': rcs [options] file ...
  2208. * Menu:
  2209. * rcsOpti::        -i Initialize.
  2210. * rcsOpta::        -a Login names.
  2211. * rcsOptAu::       -A Append access list.
  2212. * rcsOpte::        -e Erase login names.
  2213. * rcsOptb::        -b Set default branch.
  2214. * rcsOptc::        -c Set comment leader.
  2215. * rcsOptk::        -k Keyword substitution.
  2216. * rcsOptl::        -l Lock revision.
  2217. * rcsOptu::        -u unlock revision.
  2218. * rcsOptLu::       -L Set strict locking.
  2219. * rcsOptUu::        -U set non-strict locking.
  2220. * rcsOptm::        -m Replace message.
  2221. * rcsOptMu::       -M Do not send mail.
  2222. * rcsOptn::        -n Associate symbolic name(tag).
  2223. * rcsOptNu::       -N Override symbolic name.
  2224. * rcsOpto::        -o Delete revisions.
  2225. * rcsOptq::        -q Quiet mode.
  2226. * rcsOptIu::       -I Interactive mode.
  2227. * rcsOpts::        -s Set state.
  2228. * rcsOptt::        -t Discription.
  2229. * rcsOptTu::       -T Modification time.
  2230. * rcsOptV::        -V Version; Emulation of RCS Version.
  2231. * rcsOptx::        -x Suffixes.
  2232. * rcsOptz::        -z Time zone.
  2233. File: rcs,  Node: rcsOpti,  Next: rcsOpta,  Up: rcsOptions
  2234. Initialize RCS File
  2235. -------------------
  2236.      Create and initialize a new RCS file,  but  do  not deposit  any
  2237.      revision.  If the RCS file has no path prefix, try to place it
  2238.      first into the subdirectory `./RCS', and then into the current
  2239.      directory.  If the RCS file already exists, print an error message.
  2240. File: rcs,  Node: rcsOpta,  Next: rcsOptAu,  Prev: rcsOpti,  Up: rcsOptions
  2241. Append Login names
  2242. ------------------
  2243. `-a`logins''
  2244.      Append the login  names  appearing  in  the  comma-separated list
  2245.      `logins' to the access list of the RCS file.
  2246. File: rcs,  Node: rcsOptAu,  Next: rcsOpte,  Prev: rcsOpta,  Up: rcsOptions
  2247. Append Access list
  2248. ------------------
  2249. `-A`oldfile''
  2250.      Append the access list of  `oldfile' to  the  access list of the
  2251.      RCS file.
  2252. File: rcs,  Node: rcsOpte,  Next: rcsOptb,  Prev: rcsOptAu,  Up: rcsOptions
  2253. Erase Login names
  2254. -----------------
  2255. `-e`logins''
  2256.      Erase  the  login  names  appearing  in  the comma- separated list
  2257.      `logins' from the access list  of  the RCS  file.   If `logins' is
  2258.      omitted, erase the entire access list.
  2259. File: rcs,  Node: rcsOptb,  Next: rcsOptc,  Prev: rcsOpte,  Up: rcsOptions
  2260. Default branch
  2261. --------------
  2262. `-b`rev''
  2263.      Set the default branch to `rev'.  If `rev' is  omitted, the
  2264.      default  branch  is reset to the (dynamically) highest branch on
  2265.      the trunk.
  2266. File: rcs,  Node: rcsOptc,  Next: rcsOptk,  Prev: rcsOptb,  Up: rcsOptions
  2267. Coment leader
  2268. -------------
  2269. `-c`string''
  2270.      Set the comment leader to `string'.  An  initial `ci', or an `rcs
  2271.      -i' without `-c', guesses the comment leader from the suffix of the
  2272.      working filename.
  2273.      This option is obsolescent, since RCS normally uses the  preceding
  2274.      `$Log$' line's prefix when inserting log lines during checkout
  2275.      (*Note coIntro::).  However, older  versions  of  RCS  use  the
  2276.      comment  leader instead of the `$Log$' line's prefix, so if you
  2277.      plan to  access a file with both old and new versions of RCS, make
  2278.      sure its comment leader matches its `$Log$' line prefix.
  2279. File: rcs,  Node: rcsOptk,  Next: rcsOptl,  Prev: rcsOptc,  Up: rcsOptions
  2280. Keyword substitution
  2281. --------------------
  2282. `-k`subst''
  2283.      Set the default keyword substitution to `subst'.  The effect of
  2284.      keyword  substitution  is  described  in *Note coKeyword::. Giving
  2285.      an explicit `-k' option to co, `rcsdiff', and `rcsmerge'
  2286.      overrides this  default.  Beware `rcs -kv',  because  `-kv'  is
  2287.      incompatible with `co -l'. Use `rcs -kkv' to restore the normal
  2288.      default  keyword substitution.
  2289. File: rcs,  Node: rcsOptl,  Next: rcsOptu,  Prev: rcsOptk,  Up: rcsOptions
  2290. Lock revision
  2291. -------------
  2292. `-l`rev''
  2293.      Lock  the revision with number `rev'.  If a branch is given, lock
  2294.      the latest revision on that branch.  If `rev' is  omitted,  lock
  2295.      the latest revision on the default  branch.   Locking   prevents
  2296.      overlapping changes.   If  someone else already holds the lock,
  2297.      the lock is broken as with `rcs -u' (see below).
  2298. File: rcs,  Node: rcsOptu,  Next: rcsOptLu,  Prev: rcsOptl,  Up: rcsOptions
  2299. Unlock revisions
  2300. ----------------
  2301. `-u`rev''
  2302.      Unlock the revision with number `rev'. If  a  branch is given,
  2303.      unlock  the  latest  revision  on  that branch.  If `rev' is
  2304.      omitted, remove the latest  lock held by the caller.  Normally,
  2305.      only the locker of a revision can unlock it.  Somebody else
  2306.      unlocking  a revision  breaks the lock. This causes a mail message
  2307.      to be sent to the original locker. The  message contains  a
  2308.      commentary  solicited  from  the breaker.  The commentary is
  2309.      terminated  by  end-of-file or by a line containing `.' by itself.
  2310. File: rcs,  Node: rcsOptLu,  Next: rcsOptUu,  Prev: rcsOptu,  Up: rcsOptions
  2311. Strict Locking
  2312. --------------
  2313.      Set  locking  to `strict'.  Strict locking means that the owner of
  2314.      an RCS file is not exempt from locking for  checkin.  This option
  2315.      should be used for files that are shared.
  2316. File: rcs,  Node: rcsOptUu,  Next: rcsOptm,  Prev: rcsOptLu,  Up: rcsOptions
  2317. Locking non-strict
  2318. ------------------
  2319.      Set  locking  to  non-strict.   Non-strict  locking means  that
  2320.      the  owner  of  a file need not lock a revision for checkin.  This
  2321.      option  should  `not' be used  for  files  that are shared.
  2322.      Whether default locking is strict  is  determined  by  your  system
  2323.      administrator, but it is normally strict.
  2324. File: rcs,  Node: rcsOptm,  Next: rcsOptMu,  Prev: rcsOptUu,  Up: rcsOptions
  2325. Replace log message
  2326. -------------------
  2327. `-m`rev':`msg''
  2328.      Replace revision `rev''s log message with `msg'.
  2329. File: rcs,  Node: rcsOptMu,  Next: rcsOptn,  Prev: rcsOptm,  Up: rcsOptions
  2330. Do not send Mail
  2331. ----------------
  2332.      Do  not  send  mail  when  breaking somebody else's lock.  This
  2333.      option is not meant for casual use;  it is  meant  for  programs
  2334.      that  warn users by other means, and invoke `rcs -u' only as a
  2335.      low-level lock-breaking operation.
  2336. File: rcs,  Node: rcsOptn,  Next: rcsOptNu,  Prev: rcsOptMu,  Up: rcsOptions
  2337. Symbolic name
  2338. -------------
  2339. `-n`name'[:[`rev']]'
  2340.      Associate the symbolic name `name' with the branch or revision
  2341.      `rev'.  Delete the symbolic name if  both: and `rev' are omitted;
  2342.      otherwise, print an error message if `name' is  already
  2343.      associated  with  another number.   If `rev' is symbolic, it is
  2344.      expanded before association.  A `rev' consisting of a  branch
  2345.      number followed by a . stands for the current latest revision in
  2346.      the branch.  A : with an empty  `rev' stands for  the  current
  2347.      latest  revision  on the default branch,   normally   the   trunk.
  2348.        For   example,
  2349.           rcs -n`name': RCS/*
  2350.      associates `name' with the current latest revision of all the
  2351.      named  RCS  files;  this contrasts  with
  2352.           rcs -n`name':$ RCS/*
  2353.      which associates `name' with the revision numbers extracted
  2354.      from  keyword strings in the corresponding working files.
  2355. File: rcs,  Node: rcsOptNu,  Next: rcsOpto,  Prev: rcsOptn,  Up: rcsOptions
  2356. Override Symbolic name
  2357. ----------------------
  2358. `-N`name'[:[`rev']]'
  2359.      Act  like  `-n', except override any previous assignment of `name'.
  2360. File: rcs,  Node: rcsOpto,  Next: rcsOptq,  Prev: rcsOptNu,  Up: rcsOptions
  2361. Delete revisions
  2362. ----------------
  2363. `-o`range''
  2364.      deletes ("outdates") the revisions given by  `range'.  A  range
  2365.      consisting  of  a  single revision number means that  revision.
  2366.      A  range  consisting  of  a branch  number  means  the  latest
  2367.      revision on that branch.  A range of the form ``rev1':`rev2'' means
  2368.      revisions `rev1' to `rev2' on the same branch, `:`rev'' means from
  2369.      the beginning of the branch containing `rev' up to  and including
  2370.      `rev', and `rev:' means from revision `rev' to the end of the
  2371.      branch containing `rev' . None of  the outdated  revisions  can
  2372.      have branches or locks.
  2373. File: rcs,  Node: rcsOptq,  Next: rcsOptIu,  Prev: rcsOpto,  Up: rcsOptions
  2374. Quiet mode
  2375. ----------
  2376.      Run quietly; do not print diagnostics.
  2377. File: rcs,  Node: rcsOptIu,  Next: rcsOpts,  Prev: rcsOptq,  Up: rcsOptions
  2378. Interactive
  2379. -----------
  2380.      Run interactively, even if the  standard  input  is not a terminal.
  2381. File: rcs,  Node: rcsOpts,  Next: rcsOptt,  Prev: rcsOptIu,  Up: rcsOptions
  2382. States
  2383. ------
  2384. `-s`state':[`rev']'
  2385.      Set  the  state  attribute  of  the revision `rev' to `state'.  If
  2386.      `rev' is a branch number, assume the  latest revision  on  that
  2387.      branch.  If `rev' is omitted, assume the latest revision on the
  2388.      default  branch.  Any  identifier  is acceptable for `state' .  A
  2389.      useful set of states is Exp (for experimental), Stab  (for
  2390.      stable), and Rel (for released).  By default, *Note ciOpts:: sets
  2391.      the state of a revision to Exp.
  2392. File: rcs,  Node: rcsOptt,  Next: rcsOptTu,  Prev: rcsOpts,  Up: rcsOptions
  2393. Descriptive Text
  2394. ----------------
  2395. `-t`file''
  2396.      Write descriptive text from  the  contents  of  the named `file'
  2397.      into the RCS file, deleting the existing text.  The `file'
  2398.      pathname cannot begin with  `-'.  If `file' is  omitted,  obtain
  2399.      the  text from standard input, terminated by end-of-file or by a
  2400.      line  containing.  by itself.  Prompt for the text if interaction
  2401.      is possible; see `-I' *Note rcsOptIu::.  With  `-i',  descriptive
  2402.      text is obtained even if `-t' is not given.
  2403. `-t-`string''
  2404.      Write descriptive text from the `string' into the RCS file,
  2405.      deleting the existing text.
  2406. File: rcs,  Node: rcsOptTu,  Next: rcsOptV,  Prev: rcsOptt,  Up: rcsOptions
  2407. Modification Time
  2408. -----------------
  2409.      Preserve the modification  time  on  the  RCS  file unless a
  2410.      revision is removed.  This option can sup- press extensive
  2411.      recompilation caused by  a  `make' dependency  of some copy of the
  2412.      working file on the RCS file.  Use this option with care; it  can
  2413.      suppress recompilation  even  when it is needed, i.e.  when a
  2414.      change to the RCS file would mean  a  change to keyword strings in
  2415.      the working file.
  2416. File: rcs,  Node: rcsOptV,  Next: rcsOptx,  Prev: rcsOptTu,  Up: rcsOptions
  2417. Version
  2418. -------
  2419.      Print RCS's version number.
  2420. `-V`n''
  2421.      Emulate RCS version `n'.  See *Note coOptV:: for details.
  2422. File: rcs,  Node: rcsOptx,  Next: rcsOptz,  Prev: rcsOptV,  Up: rcsOptions
  2423. Suffixes
  2424. --------
  2425. `-x`suffixes''
  2426.      Use `suffixes' to characterize RCS files. See *Note ciOptx::.
  2427. File: rcs,  Node: rcsOptz,  Prev: rcsOptx,  Up: rcsOptions
  2428. Time Zone
  2429. ---------
  2430. `-z`zone''
  2431.      Use `zone' as the default time zone.  This option has no  effect;
  2432.      it  is  present for compatibility with other RCS commands.
  2433. File: rcs,  Node: rcsCompatibility,  Next: rcsFiles,  Prev: rcsOptions,  Up: rcs
  2434. Compatibility
  2435. -------------
  2436.    The `-b`rev'' option generates an  RCS  file  that  cannot  be
  2437. parsed by RCS version 3 or earlier.
  2438.    The  `-k`subst'' options  (except  `-kkv') generate an RCS file that
  2439. cannot be parsed by RCS version 4 or earlier.
  2440.    Use rcs `-V`n'' to make an RCS file acceptable to RCS  version `n'
  2441. by discarding information that would confuse version `n'.
  2442.    RCS version 5.5  and  earlier  does  not  support  the  `-x' option,
  2443. and requires a `,v' suffix on an RCS pathname.
  2444. File: rcs,  Node: rcsFiles,  Next: rcsEnv,  Prev: rcsCompatibility,  Up: rcs
  2445. Files
  2446. -----
  2447.    rcs accesses files much as `ci' does, except that it uses the
  2448. effective user for all accesses, it does not write the working  file
  2449. or its directory, and it does not even read
  2450. File: rcs,  Node: rcsEnv,  Next: rcsDiag,  Prev: rcsFiles,  Up: rcs
  2451. Environment
  2452. ===========
  2453. `RCSINIT'
  2454.      options prepended to the argument list, separated by spaces.  See
  2455.      *Note ciEnv:: for details.
  2456. File: rcs,  Node: rcsDiag,  Next: rcsBugs,  Prev: rcsEnv,  Up: rcs
  2457. Diagnostics
  2458. ===========
  2459.    The RCS pathname and the revisions outdated are written to the
  2460. diagnostic  output.   The  exit status is zero if and only if all
  2461. operations were successful.
  2462. File: rcs,  Node: rcsBugs,  Prev: rcsDiag,  Up: rcs
  2463.    A catastrophe (e.g. a system crash) can cause RCS to leave behind  a
  2464. semaphore file that causes later invocations of RCS to claim that the
  2465. RCS file is in use.   To  fix  this, remove  the semaphore file.  A
  2466. semaphore file's name typically begins with `,' or ends with `_'.
  2467.    The separator for revision ranges in the `-o' option used to be  `-'
  2468. instead of `:', but this leads to confusion when symbolic names
  2469. contain `-'.  For backwards compatibility `rcs -o' still  supports  the
  2470. old  - separator, but it warns about this obsolete use.
  2471.    Symbolic names need not refer  to  existing  revisions  or branches.
  2472. For example, the `-o' option does not remove symbolic names for the
  2473. outdated revisions; you must use `-n' to remove the names.
  2474. File: rcs,  Node: ident,  Next: rcsclean,  Prev: rcs,  Up: Top
  2475. ident - identify RCS keywords
  2476. *****************************
  2477. * Menu:
  2478. * identIntro::       Introduction to `rcs'.
  2479. * identOptions::     command line options of `rcs'.
  2480. * identKeywords::    Keywords.
  2481. File: rcs,  Node: identIntro,  Next: identOptions,  Up: ident
  2482. Description
  2483. ===========
  2484.    Ident   searches   for   all   instances  of  the  pattern
  2485. `$keyword: text $' in the named files or, if  no  files  are named, the
  2486. standard input.
  2487.    These  patterns are normally inserted automatically by the RCS
  2488. command `co' (*Note coKeyword::), but can also be inserted manually.
  2489. The option `-q'(*Note identOptq::)  suppresses  the warning given if
  2490. there are no patterns in a file.  The option `-V'(*Note identOptV::)
  2491. prints ident's  version number.
  2492.    ident  works  on  text  files  as well as object files and dumps.
  2493. For example, if the C program in f.c contains:
  2494.      #include <stdio.h>
  2495.      static char const rcsid[] =
  2496.          "$Id: f.c,v 5.4 1993/11/09  17:40:15  eggert  Exp $";
  2497.      int main() { return printf("%s\n", rcsid) == EOF; }
  2498.    and f.c is compiled into f.o, then the command
  2499.      ident  f.c  f.o
  2500.    will output
  2501.      f.c:
  2502.          $Id: f.c,v 5.4 1993/11/09 17:40:15 eggert Exp $
  2503.      f.o:
  2504.          $Id: f.c,v 5.4 1993/11/09 17:40:15 eggert Exp $
  2505.    If a C program defines a string like rcsid above but  does not  use
  2506. it,  `lint'  may complain, and some C compilers will optimize away the
  2507. string.  The most reliable solution is  to  have the program use the
  2508. rcsid string, as shown in the example above.
  2509.    ident finds all instances of the `$keyword: text $' pattern, even
  2510. if `keyword' is not actually an RCS-supported keyword.  This gives you
  2511. information about nonstandard keywords like `$XConsortium$'.
  2512. File: rcs,  Node: identOptions,  Next: identKeywords,  Prev: identIntro,  Up: ident
  2513. Command line options of ident
  2514. =============================
  2515.    Overview off all options which can be given to `rcs'
  2516.    `Synopsis': ident [options] [ file ... ]
  2517. * Menu:
  2518. * identOptq::        -q Quiet mode.
  2519. * identOptV::        -V Version
  2520. File: rcs,  Node: identOptq,  Next: identOptV,  Up: identOptions
  2521. Quiet mode
  2522. ----------
  2523.      Suppress warning given if there are no patterns in a file.
  2524. File: rcs,  Node: identOptV,  Prev: identOptq,  Up: identOptions
  2525. Version
  2526. -------
  2527.      Print ident's version number.
  2528. File: rcs,  Node: identKeywords,  Prev: identOptions,  Up: ident
  2529. Keywords
  2530. ========
  2531.    The maintained list of keywords of `co' you'll find in *Note
  2532. coKeyword::.
  2533. All times are given in Coordinated Universal  Time (UTC,  sometimes
  2534. called GMT) by default, but if the files were checked out with `co''s
  2535. `-z`zone'' (*Note coOptz::) option, times are  given with a numeric
  2536. time zone indication appended.
  2537. File: rcs,  Node: rcsclean,  Next: rcsdiff,  Prev: ident,  Up: Top
  2538. rcsclean - clean up working files
  2539. *********************************
  2540. * Menu:
  2541. * rcscleanIntro::       Introduction to `rcsclean'.
  2542. * rcscleanOptions::     command line options of `rcsclean'.
  2543. * rcscleanExamples::    Examples in using `rcsclean'.
  2544. * rcscleanFiles::       Files.
  2545. * rcscleanEnv::         The Environment which can change the
  2546.                         behaviour of much of the RCS commands.
  2547. * rcscleanDiag::        Diagnostic output of `rcsclean'.
  2548. * rcscleanBugs::        Bugs.
  2549. File: rcs,  Node: rcscleanIntro,  Next: rcscleanOptions,  Up: rcsclean
  2550. Description
  2551. ===========
  2552.    `rcsclean'  removes  files  that  are  not  being worked on.
  2553. `rcsclean -u' (*Note rcscleanOptu::) also unlocks and removes files
  2554. that are  being worked on but have not changed.
  2555.    For  each  `file' given, rcsclean compares the working file and a
  2556. revision in the corresponding RCS file.  If it finds a  difference,  it
  2557. does  nothing.   Otherwise,  it  first unlocks the revision if the
  2558. `-u' (*Note rcscleanOptu::  option is given,  and  then removes  the
  2559. working  file  unless  the  working  file is writable and the revision
  2560. is locked.  It logs its  actions by  outputting the corresponding `rcs
  2561. -u' (*Note rcsOptu::) and `rm -f' commands on the standard output.
  2562.    Files are paired as explained in *Note ciFiles::.  If  no  `file' is
  2563. given,  all  working  files  in  the current directory are cleaned.
  2564. Pathnames matching  an  RCS  suffix  denote  RCS files; all others
  2565. denote working files.
  2566.    The  number  of  the revision to which the working file is compared
  2567. may be attached to any of the options `-n', `-q', `-r', or `-u'.  If no
  2568. revision number is specified, then if the `-u' option is given and the
  2569. caller has  one  revision  locked, rcsclean  uses  that revision;
  2570. otherwise rcsclean uses the latest revision on the default branch,
  2571. normally the  root.
  2572.    `rcsclean' is  useful  for clean targets in makefiles.  *Note
  2573. rcsdiff::, which prints  out  the  differences,  and `ci' (*Note
  2574. ciIntro::),  which normally reverts to the previous revision if a file
  2575. was not changed.
  2576. File: rcs,  Node: rcscleanOptions,  Next: rcscleanExamples,  Prev: rcscleanIntro,  Up: rcsclean
  2577. Command line options of rcsclean
  2578. ================================
  2579.    Overview off all options which can be given to `rcsclean'
  2580.    `Synopsis': rcsclean [options] [ file ... ]
  2581. * Menu:
  2582. * rcscleanOptk::   -k Keyword substitution.
  2583. * rcscleanOptn::   -n Do not unlock or remove.
  2584. * rcscleanOptq::   -q Quiet mode.
  2585. * rcscleanOptr::   -r Revision for comparison.
  2586. * rcscleanOptT::   -T Modification time.
  2587. * rcscleanOptu::   -u unlock revisions.
  2588. * rcscleanOptV::   -V Version; Emulation RCS Version.
  2589. * rcscleanOptx::   -x Suffixes.
  2590. * rcscleanOptz::   -z Time zone.
  2591. File: rcs,  Node: rcscleanOptk,  Next: rcscleanOptn,  Up: rcscleanOptions
  2592. Keyword substitution
  2593. --------------------
  2594. `-k`subst''
  2595.      Use `subst' style keyword substitution when  retrieving the
  2596.      revision  for  comparison.  See *Note coKeyword:: for details.
  2597. File: rcs,  Node: rcscleanOptn,  Next: rcscleanOptq,  Prev: rcscleanOptk,  Up: rcscleanOptions
  2598. No removing
  2599. -----------
  2600. `-n`rev''
  2601.      Do not actually remove  any  files  or  unlock  any revisions.
  2602.      Using  this  option will tell you what `rcsclean' would do without
  2603.      actually doing it.
  2604. File: rcs,  Node: rcscleanOptq,  Next: rcscleanOptr,  Prev: rcscleanOptn,  Up: rcscleanOptions
  2605. Quiet mode
  2606. ----------
  2607. `-q`rev''
  2608.      Do not log the actions taken on standard output.
  2609. File: rcs,  Node: rcscleanOptr,  Next: rcscleanOptT,  Prev: rcscleanOptq,  Up: rcscleanOptions
  2610. Revision for comparison
  2611. -----------------------
  2612. `-r`rev''
  2613.      This option has no effect other than specifying the revision for
  2614.      comparison.
  2615. File: rcs,  Node: rcscleanOptT,  Next: rcscleanOptu,  Prev: rcscleanOptr,  Up: rcscleanOptions
  2616. Modification time
  2617. -----------------
  2618.      Preserve the modification time on the RCS file even if the RCS
  2619.      file changes because a lock is  removed.  This  option  can
  2620.      suppress extensive recompilation caused by a `make' dependency of
  2621.      some  other  copy of  the  working  file  on  the RCS file.  Use
  2622.      this option with care;  it  can  suppress  recompilation even
  2623.      when it is needed, i.e. when the lock removal would mean a change
  2624.      to keyword strings in the other working file.
  2625. File: rcs,  Node: rcscleanOptu,  Next: rcscleanOptV,  Prev: rcscleanOptT,  Up: rcscleanOptions
  2626. Unlock revision
  2627. ---------------
  2628. `-u`rev''
  2629.      Unlock  the revision if it is locked and no difference is found.
  2630. File: rcs,  Node: rcscleanOptV,  Next: rcscleanOptx,  Prev: rcscleanOptu,  Up: rcscleanOptions
  2631. Version and Emulation
  2632. ---------------------
  2633.      Print RCS's version number.
  2634. `-V`n''
  2635.      Emulate RCS version `n'.  *Note coOptV:: for details.
  2636. File: rcs,  Node: rcscleanOptx,  Next: rcscleanOptz,  Prev: rcscleanOptV,  Up: rcscleanOptions
  2637. Suffixes
  2638. --------
  2639. `-x`suffixes''
  2640.      Use `suffixes' to characterize RCS files.  See  *Note ciOptx:: for
  2641.      details.
  2642. File: rcs,  Node: rcscleanOptz,  Prev: rcscleanOptx,  Up: rcscleanOptions
  2643. Time zone
  2644. ---------
  2645. `-z`zone''
  2646.      `-z`zone'' Use `zone' as the time zone for keyword substitution;
  2647.      see *Note coOptz:: for details.
  2648. File: rcs,  Node: rcscleanExamples,  Next: rcscleanFiles,  Prev: rcscleanOptions,  Up: rcsclean
  2649. Examples
  2650. ========
  2651.      rcsclean  *.c  *.h
  2652.    removes all working files ending in .c or .h that were not changed
  2653. since their checkout.
  2654.      rcsclean
  2655.    removes  all  working  files in the current directory that were not
  2656. changed since their checkout.
  2657. File: rcs,  Node: rcscleanFiles,  Next: rcscleanEnv,  Prev: rcscleanExamples,  Up: rcsclean
  2658. Files
  2659. =====
  2660.    rcsclean accesses files much as `ci' (*Note ciFiles::)does.
  2661. File: rcs,  Node: rcscleanEnv,  Next: rcscleanDiag,  Prev: rcscleanFiles,  Up: rcsclean
  2662. Environment
  2663. ===========
  2664. `RCSINIT'
  2665.      options prepended to the argument list, separated by spaces.  See
  2666.      *Note ciEnv:: for details.
  2667. File: rcs,  Node: rcscleanDiag,  Next: rcscleanBugs,  Prev: rcscleanEnv,  Up: rcsclean
  2668. Diagnostics
  2669. ===========
  2670.    The exit status is zero if and only if all operations were
  2671. successful.   Missing  working  files  and  RCS  files are silently
  2672. ignored.
  2673. File: rcs,  Node: rcscleanBugs,  Prev: rcscleanDiag,  Up: rcsclean
  2674.    At  least  one  `file' must be given in older Unix versions that do
  2675. not provide the needed directory  scanning  operations.
  2676. File: rcs,  Node: rcsdiff,  Next: rcsmerge,  Prev: rcsclean,  Up: Top
  2677. rcsdiff - compare RCS revisions
  2678. *******************************
  2679. * Menu:
  2680. * rcsdiffIntro::        Introduction to `rcsdiff'.
  2681. * rcsdiffOptions::      command line options of `rcsdiff'.
  2682. * rcsdiffExamples::     Examples in using `rcsdiff'.
  2683. * rcsdiffEnv::          The Environment which can change the
  2684.                         behaviour of much of the RCS commands.
  2685. * rcsdiffDiag::         Diagnostic output of `rcsdiff'.
  2686. File: rcs,  Node: rcsdiffIntro,  Next: rcsdiffOptions,  Up: rcsdiff
  2687. Description
  2688. ===========
  2689.    rcsdiff  runs `diff' to compare two revisions of each RCS file given.
  2690.    Pathnames matching an RCS suffix  denote  RCS  files;  all others
  2691. denote   working  files.   Names  are  paired  as explained in *Note
  2692. ciFiles::.
  2693. File: rcs,  Node: rcsdiffOptions,  Next: rcsdiffExamples,  Prev: rcsdiffIntro,  Up: rcsdiff
  2694. Command line options of rcsdiff
  2695. ===============================
  2696.    Overview off all options which can be given to `rcsdiff'
  2697.    `Synopsis': rcsdiff [options] [`-r`rev1''] [`-r`rev2'']  [`diff
  2698. options'] [ file ... ]
  2699. * Menu:
  2700. * rcsdiffOptk::   -k Keyword substitution.
  2701. * rcsdiffOptq::   -q Quiet mode.
  2702. * rcsdiffOptr::   -r Revision for comparison.
  2703. * rcsdiffOptT::   -T Modification time.
  2704. * rcsdiffOptV::   -V Version; Emulation RCS Version.
  2705. * rcsdiffOptx::   -x Suffixes.
  2706. File: rcs,  Node: rcsdiffOptk,  Next: rcsdiffOptq,  Prev: rcsdiffOptions,  Up: rcsdiffOptions
  2707. Keyword substitution
  2708. --------------------
  2709. `-k`subst''
  2710.      `-k`subst'' affects keyword substitution when extracting
  2711.      revisions, as described in *Note coOptk::; for example, `-kk -r1.1
  2712.      -r1.2' ignores differences in keyword values when comparing
  2713.      revisions  `1.1'  and  `1.2'.  To avoid excess output from locker
  2714.      name substitution, `-kkvl' is assumed if
  2715.        1. at  most  one revision  option  is given,
  2716.        2. no `-k' option is given,
  2717.        3. `-kkv' is the default  keyword  substitution,  and
  2718.        4. the working file's mode would be produced by `co -l'.
  2719. File: rcs,  Node: rcsdiffOptq,  Next: rcsdiffOptr,  Prev: rcsdiffOptk,  Up: rcsdiffOptions
  2720. Quiet mode
  2721. ----------
  2722. `-q`rev''
  2723.      The option -q suppresses diagnostic output.
  2724. File: rcs,  Node: rcsdiffOptr,  Next: rcsdiffOptT,  Prev: rcsdiffOptq,  Up: rcsdiffOptions
  2725. Revision for comparison
  2726. -----------------------
  2727. `-r`rev1' -r`rev2''
  2728.      Zero, one, or two  revisions  may  be  specified  with  `-r'.  If
  2729.      both `rev1' and `rev2' are omitted,  rcsdiff  compares  the latest
  2730.      revision  on  the  default  branch (by default the trunk) with
  2731.      the  contents  of  the  corresponding  working file.   This  is
  2732.      useful  for determining what you changed since the last checkin.
  2733.      If `rev1' is given, but `rev2' is  omitted,  rcsdiff  compares
  2734.      revision  `rev1' of  the  RCS file with the contents of the
  2735.      corresponding working file.
  2736.      If both `rev1' and `rev2' are given,  rcsdiff  compares revisions
  2737.      `rev1' and `rev2' of the RCS file.
  2738.      Both  `rev1' and  `rev2' may be given numerically or symbolically.
  2739. File: rcs,  Node: rcsdiffOptT,  Next: rcsdiffOptV,  Prev: rcsdiffOptr,  Up: rcsdiffOptions
  2740. Modification time
  2741. -----------------
  2742.      For details *Note coOptT::.
  2743. File: rcs,  Node: rcsdiffOptV,  Next: rcsdiffOptx,  Prev: rcsdiffOptT,  Up: rcsdiffOptions
  2744. Version and Emulation
  2745. ---------------------
  2746.      Print RCS's version number.
  2747. `-V`n''
  2748.      Emulate RCS version `n'.  *Note coOptV:: for details.
  2749. File: rcs,  Node: rcsdiffOptx,  Prev: rcsdiffOptV,  Up: rcsdiffOptions
  2750. Suffixes
  2751. --------
  2752. `-x`suffixes''
  2753.      Use `suffixes' to characterize RCS files.  See  *Note ciOptx:: for
  2754.      details.
  2755. File: rcs,  Node: rcsdiffExamples,  Next: rcsdiffEnv,  Prev: rcsdiffOptions,  Up: rcsdiff
  2756. Examples
  2757. ========
  2758.      rcsdiff  *.c  *.h
  2759.    removes all working files ending in .c or .h that were not changed
  2760. since their checkout.
  2761.      rcsdiff
  2762.    removes  all  working  files in the current directory that were not
  2763. changed since their checkout.
  2764. File: rcs,  Node: rcsdiffEnv,  Next: rcsdiffDiag,  Prev: rcsdiffExamples,  Up: rcsdiff
  2765. Environment
  2766. ===========
  2767. `RCSINIT'
  2768.      options prepended to the argument list, separated by spaces.  See
  2769.      *Note ciEnv:: for details.
  2770. File: rcs,  Node: rcsdiffDiag,  Prev: rcsdiffEnv,  Up: rcsdiff
  2771. Diagnostics
  2772. ===========
  2773.    Exit status is 0 for no differences during any comparison, 1 for
  2774. some differences, 2 for trouble.
  2775. File: rcs,  Node: rcsmerge,  Next: rlog,  Prev: rcsdiff,  Up: Top
  2776. rcsmerge - merge RCS versions
  2777. *****************************
  2778. * Menu:
  2779. * rcsmergeIntro::    Introduction to `rcs'.
  2780. * rcsmergeOptions::  command line options of `rcs'.
  2781. * rcsmergeExamples:: Examples of `rcsmerge'.
  2782. * rcsmergeEnv::      The Environment which can change the
  2783.                      behaviour of much of the RCS commands.
  2784. * rcsmergeDiag::     Diagnostic output of `rcs'.
  2785. File: rcs,  Node: rcsmergeIntro,  Next: rcsmergeOptions,  Up: rcsmerge
  2786. Description
  2787. ===========
  2788.    rcsmerge incorporates the changes between two revisions of an RCS
  2789. file into the corresponding working file.
  2790.    Pathnames matching an RCS suffix  denote  RCS  files;  all others
  2791. denote   working  files.   Names  are  paired  as explained in *Note
  2792. ciFiles::.
  2793.    At least one revision must be specified with  one  of  the options
  2794. described  below,  usually `-r'.  At most two revisions may be
  2795. specified.  If only one revision  is  specified,  the latest revision
  2796. on the default branch (normally the highest branch on the trunk) is
  2797. assumed for the second revision.  Revisions may be specified
  2798. numerically or symbolically.
  2799.    rcsmerge prints a  warning  if  there  are  overlaps,  and delimits
  2800. the overlapping regions as explained in *Note merge::.  The command is
  2801. useful for  incorporating  changes  into  a checked-out revision.
  2802. File: rcs,  Node: rcsmergeOptions,  Next: rcsmergeExamples,  Prev: rcsmergeIntro,  Up: rcsmerge
  2803. Command line options of rcsmerge
  2804. ================================
  2805.    Overview off all options which can be given to `rcsmerge'
  2806.    `Synopsis': rcsmerge [options] file ...
  2807. * Menu:
  2808. * rcsmergeOptA::   -A Output conflicts the -A style.
  2809. * rcsmergeOptE::   -E specify Conflict style
  2810. * rcsmergeOptk::   -k Keyword substitution.
  2811. * rcsmergeOptp::   -p send to stdout.
  2812. * rcsmergeOptT::   -T Modification time.
  2813. * rcsmergeOptV::   -V Version; Emulation of RCS Version.
  2814. * rcsmergeOptx::   -x Suffixes.
  2815. * rcsmergeOptz::   -z Time zone.
  2816. File: rcs,  Node: rcsmergeOptA,  Next: rcsmergeOptE,  Prev: rcsmergeOptions,  Up: rcsmergeOptions
  2817. Output conflicts
  2818. ----------------
  2819.      Output conflicts using the `-A' style of `diff3', if supported by
  2820.      `diff3'.  This merges all changes  leading from  `file2' to
  2821.      `file3' into `file1', and generates the most verbose output.
  2822. File: rcs,  Node: rcsmergeOptE,  Next: rcsmergeOptk,  Prev: rcsmergeOptA,  Up: rcsmergeOptions
  2823. Less information
  2824. ----------------
  2825. `-E -e'
  2826.      These options specify conflict styles that generate less
  2827.      information   than  `-A'.   See  `diff3'  for details.  The
  2828.      default is  `-E'. With  `-e',  `rcsmerge' does not warn about
  2829.      conflicts.
  2830. File: rcs,  Node: rcsmergeOptk,  Next: rcsmergeOptp,  Prev: rcsmergeOptE,  Up: rcsmergeOptions
  2831. Keyword substitution
  2832. --------------------
  2833. `-k`subst''
  2834.      Use  `subst' style  keyword substitution.  See *Note coKeyword::
  2835.      for details.  For example, `-kk -r1.1 -r1.2'  ignores differences
  2836.      in  keyword  values  when  merging the changes from `1.1' to
  2837.      `1.2'.  It normally does not make sense  to  merge binary files as
  2838.      if they were text, so `rcsmerge' refuses to merge files if `-kb'
  2839.      expansion is used.
  2840. File: rcs,  Node: rcsmergeOptp,  Next: rcsmergeOptT,  Prev: rcsmergeOptk,  Up: rcsmergeOptions
  2841. Send to standard out
  2842. --------------------
  2843. `-p[`rev']'
  2844.      Send the result to standard output instead of over- writing the
  2845.      working file.
  2846. File: rcs,  Node: rcsmergeOptT,  Next: rcsmergeOptV,  Prev: rcsmergeOptp,  Up: rcsmergeOptions
  2847. Modification Time
  2848. -----------------
  2849.      This option has no effect; it is present  for  compatibility with
  2850.      other RCS commands.
  2851. File: rcs,  Node: rcsmergeOptV,  Next: rcsmergeOptx,  Prev: rcsmergeOptT,  Up: rcsmergeOptions
  2852. Version
  2853. -------
  2854.      Print RCS's version number.
  2855. `-V`n''
  2856.      Emulate RCS version `n'.  See *Note coOptV:: for details.
  2857. File: rcs,  Node: rcsmergeOptx,  Next: rcsmergeOptz,  Prev: rcsmergeOptV,  Up: rcsmergeOptions
  2858. Suffixes
  2859. --------
  2860. `-x`suffixes''
  2861.      Use `suffixes' to characterize RCS files. See *Note ciOptx::.
  2862. File: rcs,  Node: rcsmergeOptz,  Prev: rcsmergeOptx,  Up: rcsmergeOptions
  2863. Time Zone
  2864. ---------
  2865. `-z`zone''
  2866.      Use `zone' as the time zone for keyword substitution.  See *Note
  2867.      coOptz:: for details.
  2868. File: rcs,  Node: rcsmergeExamples,  Next: rcsmergeEnv,  Prev: rcsmergeOptions,  Up: rcsmerge
  2869. Examples
  2870. --------
  2871.    Suppose  you  have  released  revision `2.8' of `f.c'.  Assume
  2872. furthermore that after you complete an unreleased revision `3.4', you
  2873. receive updates to release `2.8' from someone else.  To combine the
  2874. updates to `2.8' and your changes between `2.8' and `3.4', put the
  2875. updates to `2.8' into file `f.c' and execute
  2876.      rcsmerge  -p  -r2.8  -r3.4  f.c  >f.merged.c
  2877.    Then  examine  `f.merged.c'.   Alternatively, if you want to save
  2878. the updates to `2.8' in the RCS file, check them in  as revision
  2879. `2.8.1.1' and execute `co -j':
  2880.      ci  -r2.8.1.1  f.c
  2881.      co  -r3.4  -j2.8:2.8.1.1  f.c
  2882.    As  another  example,  the  following  command  undoes the changes
  2883. between revision `2.4' and  `2.8'  in  your  currently checked out
  2884. revision in `f.c'.
  2885.      rcsmerge  -r2.8  -r2.4  f.c
  2886.    Note  the  order  of  the  arguments, and that `f.c' will be
  2887. overwritten.
  2888. File: rcs,  Node: rcsmergeEnv,  Next: rcsmergeDiag,  Prev: rcsmergeExamples,  Up: rcsmerge
  2889. Environment
  2890. ===========
  2891. `RCSINIT'
  2892.      options prepended to the argument list, separated by spaces.  See
  2893.      *Note ciEnv:: for details.
  2894. File: rcs,  Node: rcsmergeDiag,  Prev: rcsmergeEnv,  Up: rcsmerge
  2895. Diagnostics
  2896. ===========
  2897.    Exit  status  is 0 for no overlaps, 1 for some overlaps, 2 for
  2898. trouble.
  2899. File: rcs,  Node: rlog,  Next: merge,  Prev: rcsmerge,  Up: Top
  2900. rlog - print log messages
  2901. *************************
  2902. * Menu:
  2903. * rlogIntro::        Introduction to `rlog'.
  2904. * rlogOptions::      command line options of `rlog'.
  2905. * rlogExamples::     Examples.
  2906. * rlogEnv::          The Environment which can change the
  2907.                      behaviour of much of the RCS commands.
  2908. * rlogDiag::         Diagnostic output of `rlog'.
  2909. * rlogBugs::         Bugs.
  2910. File: rcs,  Node: rlogIntro,  Next: rlogOptions,  Up: rlog
  2911. Description
  2912. ===========
  2913.    `rlog' prints information about RCS files.
  2914.    Pathnames matching an RCS suffix  denote  RCS  files;  all others
  2915. denote   working  files.   Names  are  paired  as explained in *Note
  2916. ciFiles::.
  2917.    `rlog' prints the following information for each  RCS  file: RCS
  2918. pathname, working pathname, head (i.e., the number of the latest
  2919. revision on the trunk), default branch,  access list, locks, symbolic
  2920. names, suffix, total number of revisions, number of  revisions
  2921. selected  for  printing,  and descriptive  text.   This  is  followed
  2922. by entries for the selected revisions in reverse chronological order
  2923. for each branch.   For  each revision, rlog prints revision number,
  2924. author, date/time, state, number  of  lines  added/deleted (with
  2925. respect  to  the  previous revision), locker of the revision (if any),
  2926. and log message.  All  times  are  displayed in  Coordinated  Universal
  2927. Time (UTC) by default; this can be overridden with  `-z'.   Without
  2928. options, `rlog' prints  complete  information.  The options below
  2929. restrict this output.
  2930. File: rcs,  Node: rlogOptions,  Next: rlogExamples,  Prev: rlogIntro,  Up: rlog
  2931. Command line options of rlog
  2932. ============================
  2933.    Overview off all options which can be given to `rlog'
  2934.    `Synopsis': rlog [options] file ...
  2935. * Menu:
  2936. * rlogOptLu::      -L Ignore RCS files.
  2937. * rlogOptRu::      -R Only names of RCS files.
  2938. * rlogOpth::       -h Only path names.
  2939. * rlogOptt::       -t Path and discriptive text.
  2940. * rlogOptN::       -N Do not print symbolic names..
  2941. * rlogOptb::       -b Information about revisions on default branch.
  2942. * rlogOptd::       -d Info about revisions with ci-date.
  2943. * rlogOptl::       -l Print locked revisions only.
  2944. * rlogOptr::       -r Informations about specified revisions.
  2945. * rlogOpts::       -s Informations about revisions with state.
  2946. * rlogOptw::       -w Informations about revisions with user.
  2947. * rlogOptTu::      -T no effect.
  2948. * rlogOptV::       -V Version; Emulation of RCS version.
  2949. * rlogOptx::       -x Suffixes.
  2950. * rlogOptz::       -z Time zone.
  2951. File: rcs,  Node: rlogOptLu,  Next: rlogOptRu,  Up: rlogOptions
  2952. Ignore RCS files without locks
  2953. ------------------------------
  2954.      Ignore RCS files that have no locks set.  This is convenient in
  2955.      combination with `-h', `-l', and `-R'.
  2956. File: rcs,  Node: rlogOptRu,  Next: rlogOpth,  Prev: rlogOptLu,  Up: rlogOptions
  2957. Only names of RCS files
  2958. -----------------------
  2959.      Print  only  the name of the RCS file.  This is convenient for
  2960.      translating a working pathname into  an  RCS pathname.
  2961. File: rcs,  Node: rlogOpth,  Next: rlogOptt,  Prev: rlogOptRu,  Up: rlogOptions
  2962. Only pathname
  2963. -------------
  2964.      Print  only  the RCS pathname, working pathname, head, default
  2965.      branch, access list,  locks,  symbolic  names, and suffix.
  2966. File: rcs,  Node: rlogOptt,  Next: rlogOptN,  Prev: rlogOpth,  Up: rlogOptions
  2967. Descriptive text
  2968. ----------------
  2969.      Print the same as `-h', plus the descriptive text.
  2970. File: rcs,  Node: rlogOptN,  Next: rlogOptb,  Prev: rlogOptt,  Up: rlogOptions
  2971. No symbolic name
  2972. ----------------
  2973.      Do not print the symbolic names.
  2974. File: rcs,  Node: rlogOptb,  Next: rlogOptd,  Prev: rlogOptN,  Up: rlogOptions
  2975. Default branch
  2976. --------------
  2977.      Print  information  about the revisions on the default branch,
  2978.      normally the highest branch on the trunk.
  2979. File: rcs,  Node: rlogOptd,  Next: rlogOptl,  Prev: rlogOptb,  Up: rlogOptions
  2980. Checkin date/time
  2981. -----------------
  2982. `-d`dates''
  2983.      Print  information  about  revisions  with  a  checkin date/time
  2984.      in  the  ranges  given  by  the  semicolon-separated list of
  2985.      `dates'.  A range of the form `d1'<`d2' or `d2'>`d1' selects  the
  2986.      revisions  that  were deposited between `d1' and `d2' exclusive.
  2987.      A range of the  form <`d' or  `d'>  selects all revisions earlier
  2988.      than `d'. A range of the form `d'< or >`d' selects all revisions
  2989.      dated later than  `d'.   If  `<' or `>' is followed by `=' then
  2990.      the ranges are inclusive, not exclusive.  A range of the  form
  2991.      `d' selects  the single,  latest revision dated `d' or earlier.
  2992.      The date/time strings `d', `d1', and `d2' are in  the free format
  2993.      explained in *Note coOptd::. Quoting is normally necessary,
  2994.      especially for `<' and `>'. Note that the separator is a semicolon.
  2995. File: rcs,  Node: rlogOptl,  Next: rlogOptr,  Prev: rlogOptd,  Up: rlogOptions
  2996. Locked revisions
  2997. ----------------
  2998. `-l`lockers''
  2999.      Print  information  about  locked  revisions only.  In addition,
  3000.      if the comma-separated list `lockers' of login names is given,
  3001.      ignore all locks other than those held by the `lockers'.  For
  3002.      example,
  3003.           rlog -L -R -lwft RCS/*
  3004.      prints the name of RCS files locked by the user `wft'.
  3005. File: rcs,  Node: rlogOptr,  Next: rlogOpts,  Prev: rlogOptl,  Up: rlogOptions
  3006. Informations about revisions
  3007. ----------------------------
  3008. `-r`revisions''
  3009.      prints information about revisions given in the commaseparated
  3010.      list `revisions' of revisions and  ranges. A range ``rev1':`rev2''
  3011.      means  revisions `rev1' to `rev2' on the same branch, `:`rev''
  3012.      means revisions from  the  beginning of  the branch up to and
  3013.      including `rev' , and ``rev':'  means revisions starting with
  3014.      `rev' to the end of  the  branch containing `rev'.  An  argument
  3015.      that is a branch means all revisions on that branch.  A  range  of
  3016.      branches means  all revisions on the branches in that range.  A
  3017.      branch followed by a . means the  latest  revision in that
  3018.      branch. A  bare `-r' with no `revisions' means the latest revision
  3019.      on the default  branch,  normally  the trunk.
  3020. File: rcs,  Node: rlogOpts,  Next: rlogOptw,  Prev: rlogOptr,  Up: rlogOptions
  3021. Information about Rev. with given state
  3022. ---------------------------------------
  3023. `-s`states''
  3024.      prints   information   about   revisions  whose  state attributes
  3025.      match one of the states given in the commaseparated list `states'.
  3026. File: rcs,  Node: rlogOptw,  Next: rlogOptTu,  Prev: rlogOpts,  Up: rlogOptions
  3027. Revisons checked in by user
  3028. ---------------------------
  3029. `-w`logins''
  3030.      prints information about revisions checked in by users with login
  3031.      names appearing in the comma-separated list `logins'.   If
  3032.      `logins' is  omitted, the user's login is assumed.
  3033. File: rcs,  Node: rlogOptTu,  Next: rlogOptV,  Prev: rlogOptw,  Up: rlogOptions
  3034. Modification Time
  3035. -----------------
  3036.      This option has no effect; it is present for  compatibility with
  3037.      other RCS commands.
  3038. File: rcs,  Node: rlogOptV,  Next: rlogOptx,  Prev: rlogOptTu,  Up: rlogOptions
  3039. Version and Emulation
  3040. ---------------------
  3041.      Print RCS's version number.
  3042. `-V`n''
  3043.      Emulate RCS version `n' when generating logs.  See *Note coOptV::
  3044.      for more.
  3045. File: rcs,  Node: rlogOptx,  Next: rlogOptz,  Prev: rlogOptV,  Up: rlogOptions
  3046. Suffixes
  3047. --------
  3048. `-x`suffixes''
  3049.      Use `suffixes' to characterize RCS files.  See *Note ciOptx:: for
  3050.      details.
  3051. File: rcs,  Node: rlogOptz,  Prev: rlogOptx,  Up: rlogOptions
  3052. Time zone
  3053. ---------
  3054.    Rlog  prints  the  intersection  of the revisions selected with the
  3055. options `-d', `-l', `-s', and `-w', intersected with  the union of the
  3056. revisions selected by `-b' and `-r'.
  3057. `-z`zone''
  3058.      specifies the date output format, and specifies the default time
  3059.      zone for `date' in the  `-d`dates'' option.  The  `zone' should be
  3060.      empty, a numeric UTC offset, or the special string `LT' for local
  3061.      time.  The  default is  an  empty  `zone' , which uses the
  3062.      traditional RCS format of UTC without any time zone indication  and
  3063.      with slashes separating the parts of the date; oth- erwise, times
  3064.      are output in ISO  8601  format  with time  zone  indication.  For
  3065.      example, if local time is January 11, 1990,  8pm  Pacific
  3066.      Standard  Time, eight hours west of UTC, then the time is output as
  3067.      follows:
  3068.           option    time output
  3069.           -z        1990/01/12 04:00:00       (default)
  3070.           -zLT      1990-01-11 20:00:00-08
  3071.           -z+05:30  1990-01-12 09:30:00+05:30
  3072. File: rcs,  Node: rlogExamples,  Next: rlogEnv,  Prev: rlogOptions,  Up: rlog
  3073. Examples
  3074. --------
  3075.      rlog  -L  -R  RCS/*
  3076.      rlog  -L  -h  RCS/*
  3077.      rlog  -L  -l  RCS/*
  3078.      rlog  RCS/*
  3079.    The first command prints the names of all RCS files in the
  3080. subdirectory  RCS  that  have  locks.   The second command prints the
  3081. headers of those files, and  the  third  prints the headers plus the
  3082. log messages of the locked revisions.  The last command prints complete
  3083. information.
  3084. File: rcs,  Node: rlogEnv,  Next: rlogDiag,  Prev: rlogExamples,  Up: rlog
  3085. Environment
  3086. -----------
  3087. `RCSINIT'
  3088.      options prepended to the argument  list,  separated by spaces.
  3089.      See *Note ciEnv:: for details.
  3090. File: rcs,  Node: rlogDiag,  Next: rlogBugs,  Prev: rlogEnv,  Up: rlog
  3091. Diagnostics
  3092. ===========
  3093.    The exit status is zero if and only if all operations were
  3094. successful.
  3095. File: rcs,  Node: rlogBugs,  Prev: rlogDiag,  Up: rlog
  3096.    The separator for revision ranges in the `-r' option used to be  `-'
  3097. instead of `:', but this leads to confusion when symbolic names
  3098. contain `-'.  For backwards  compatibility `rlog -r'  still supports
  3099. the old `-' separator, but it warns about this obsolete use.
  3100. File: rcs,  Node: merge,  Next: AppendixA,  Prev: rlog,  Up: Top
  3101. merge - three-way file merge
  3102. ****************************
  3103. * Menu:
  3104. * mergeIntro::       Introduction to `merge'.
  3105. * mergeOptions::     command line options of `merge'.
  3106. * mergeDiag::        Diagnostic output of `merge'.
  3107. * mergeBugs::        Bugs.
  3108. File: rcs,  Node: mergeIntro,  Next: mergeOptions,  Up: merge
  3109. Description
  3110. ===========
  3111.    `merge'  incorporates  all  changes  that lead from `file2' to
  3112. `file3' into `file1'.  The result ordinarily goes into  `file1'.  merge
  3113. is useful for combining separate changes to an original.  Suppose
  3114. `file2' is the original, and both  `file1' and `file3' are
  3115. modifications  of  `file2' .  Then merge combines both changes.
  3116.    A conflict occurs if both `file1' and `file3' have changes  in a
  3117. common segment of lines.  If a conflict is found, merge normally
  3118. outputs a warning and brackets the conflict  with `<<<<<<<'  and
  3119. `>>>>>>>' lines.  A typical conflict will look like this:
  3120.      <<<<<<< file A
  3121.      lines in file A
  3122.      =======
  3123.      lines in file B
  3124.      >>>>>>> file B
  3125.    If there are conflicts, the user should  edit  the  result and
  3126. delete one of the alternatives.
  3127. File: rcs,  Node: mergeOptions,  Next: mergeDiag,  Prev: mergeIntro,  Up: merge
  3128. Command line options of merge
  3129. =============================
  3130.    Overview off all options which can be given to `merge'
  3131.    `Synopsis': merge [options] file1 file2 file3
  3132. * Menu:
  3133. * mergeOptA::      -A Style of diff3.
  3134. * mergeOptE::      -E Conflict style.
  3135. * mergeOptL::      -L Labels.
  3136. * mergeOptp::      -p Send to standard output.
  3137. * mergeOptq::      -q Quite mode.
  3138. * mergeOptV::      -V Version.
  3139. File: rcs,  Node: mergeOptA,  Next: mergeOptE,  Prev: mergeOptions,  Up: mergeOptions
  3140. Output conflicts
  3141. ----------------
  3142.      Output conflicts using the `-A' style of `diff3', if supported by
  3143.      diff3.  This merges all changes  leading from  `file2' to `file3'
  3144.      into `file1', and generates the most verbose output.
  3145. File: rcs,  Node: mergeOptE,  Next: mergeOptL,  Prev: mergeOptA,  Up: mergeOptions
  3146. Specify conflict styles
  3147. -----------------------
  3148. `-E -e'
  3149.      These options specify conflict styles that generate less
  3150.      information   than  `-A'.   See  `diff3'  for details.  The
  3151.      default is `-E'.  With `-e',  merge  does not warn about conflicts.
  3152. File: rcs,  Node: mergeOptL,  Next: mergeOptp,  Prev: mergeOptE,  Up: mergeOptions
  3153. Label
  3154. -----
  3155. `-L`label''
  3156.      This  option  may  be  given up to three times, and specifies
  3157.      labels to be used in place of the  corresponding file names in
  3158.      conflict reports.  That is, `merge -L x -L y -L z a b c'
  3159.      generates  output  that looks like it came from files `x', `y' and
  3160.      `z'instead of from files `a', `b' and `c'.
  3161. File: rcs,  Node: mergeOptp,  Next: mergeOptq,  Prev: mergeOptL,  Up: mergeOptions
  3162. Standard output
  3163. ---------------
  3164.      Send results to standard output  instead  of  overwriting `file1'.
  3165. File: rcs,  Node: mergeOptq,  Next: mergeOptV,  Prev: mergeOptp,  Up: mergeOptions
  3166. Quiet Mode
  3167. ----------
  3168.      Quiet;  do  not  warn about conflicts.
  3169. File: rcs,  Node: mergeOptV,  Prev: mergeOptq,  Up: mergeOptions
  3170. Version
  3171. -------
  3172.      Print's version number.
  3173. File: rcs,  Node: mergeDiag,  Next: mergeBugs,  Prev: mergeOptions,  Up: merge
  3174. Diagnostics
  3175. ===========
  3176.    Exit status is 0 for no conflicts, 1 for some conflicts, 2 for
  3177. trouble.
  3178. File: rcs,  Node: mergeBugs,  Prev: mergeDiag,  Up: merge
  3179.    It normally does not make sense to merge binary  files  as if they
  3180. were text, but merge tries to do it anyway.
  3181. File: rcs,  Node: AppendixA,  Next: AppendixB,  Prev: merge,  Up: Top
  3182. Format of RCS file
  3183. ******************
  3184. * Menu:
  3185. * rcsfileIntro::        Discription of the RCS file format.
  3186. * rcsfileExample::      Example of a revision tree.
  3187. File: rcs,  Node: rcsfileIntro,  Next: rcsfileExample,  Up: AppendixA
  3188. Description
  3189. ===========
  3190.    An RCS file's contents are described by the grammar below.  The text
  3191. is free format: space, backspace,  tab,  newline, vertical  tab,  form
  3192. feed,  and  carriage return (collectively, `white space')  have  no
  3193. significance  except  in strings.  However, white space cannot appear
  3194. within an id, num, or sym, and an RCS file must end with a newline.
  3195.    Strings are enclosed by @.  If a string contains a  @,  it must  be
  3196. doubled; otherwise, strings can contain arbitrary binary data.
  3197.    The meta syntax uses the following conventions: `|'  (bar) separates
  3198. alternatives;  `{'  and  `}'  enclose  optional phrases; `{' and `}*'
  3199. enclose phrases that can be repeated zero or more times; `{' and '}+'
  3200. enclose phrases that must appear at least once and can be repeated;
  3201. Terminal symbols are in boldface; nonterminal symbols are in `italic'.
  3202.      rcstext    ::=  admin {delta}* desc {deltatext}*
  3203.      admin      ::=  `head' {num};
  3204.                      { branch   {num}; }
  3205.                      `access' {id}*;
  3206.                      `symbols' {sym : num}*;
  3207.                      `locks' {id : num}*;  {`strict'  ;}
  3208.                      { `comment'  {string}; }
  3209.                      { `expand'   {string}; }
  3210.                      { newphrase }*
  3211.      delta      ::=  num
  3212.                      `date' num;
  3213.                      `author' id;
  3214.                      `state' {id};
  3215.                      `branches' {num}*;
  3216.                      `next' {num};
  3217.                      { newphrase }*
  3218.      desc       ::=  `desc' string
  3219.      deltatext  ::=  num
  3220.                      `log' string
  3221.                      { newphrase }*
  3222.                      `text' string
  3223.      num        ::=  {digit | .}+
  3224.      digit      ::=  0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
  3225.      id         ::=  {num} idchar {idchar | num }*
  3226.      sym        ::=  {digit}* idchar {idchar | digit }*
  3227.      idchar     ::=  any visible graphic character except `special'
  3228.      special    ::=  $ | , | . | : | ; | @
  3229.      string     ::=  @{any character, with @ doubled}*@
  3230.      newphrase  ::=  id word* ;
  3231.      word       ::=  id | num | string | :
  3232.    Identifiers  are  case  sensitive. Keywords are in lower case only.
  3233. The sets of keywords and identifiers can overlap. In most environments
  3234. RCS uses the ISO 8859/1 encoding: visible graphic characters  are
  3235. codes  041-176  and 240-377,  and white space characters are codes
  3236. 010-015 and 040.
  3237.    Dates, which appear after the date  keyword,  are  of  the form
  3238. `Y.mm.dd.hh.mm.ss',  where `Y' is the year, `mm' the month (01-12),
  3239. `dd' the day (01-31), `hh' the hour (00-23), `mm' the minute  (00-59),
  3240. and  `ss' the second (00-60). `Y' contains just the last two digits of
  3241. the year for years  from 1900 through  1999,  and  all  the  digits of
  3242. years thereafter. Dates use the Gregorian calendar; times use UTC.
  3243.    The `newphrase' productions in the grammar are reserved for future
  3244. extensions  to  the  format of RCS files.  No `newphrase' will begin
  3245. with any keyword already in use.
  3246.    The `delta' nodes form a tree.  All nodes whose numbers consist of a
  3247. single pair (e.g., 2.3, 2.1, 1.3, etc.)  are on the trunk, and are
  3248. linked through the next field in  order of  decreasing  numbers.  The
  3249. head field in the `admin' node points to the head of that sequence
  3250. (i.e.,  contains  the highest  pair).   The  branch node in the admin
  3251. node indicates the default branch (or revision) for most RCS operations.
  3252. If empty, the default branch is the highest branch on the trunk.
  3253.    All `delta' nodes whose numbers consist of 2`n' fields (`n'>=2)
  3254. (e.g.,  3.1.1.1,  2.1.2.2,  etc.) are linked as follows.  All nodes
  3255. whose first 2`n'-1 number fields are identical are linked  through the
  3256. next field in order of increasing numbers.  For each such sequence, the
  3257. `delta' node whose number is identical to the first 2`n'-2 number
  3258. fields of the deltas on that sequence is called the branchpoint.  The
  3259. branches field  of  a  node  contains  a list of the numbers of the
  3260. first nodes of all sequences for which  it  is  a  branchpoint.  This
  3261. list is ordered in increasing numbers.
  3262. File: rcs,  Node: rcsfileExample,  Prev: rcsfileIntro,  Up: AppendixA
  3263. Example Revision tree
  3264. =====================
  3265.    The  following  diagram  shows an example of an RCS file's
  3266. organization.
  3267.                                 Head
  3268.                                   |
  3269.                                   v                        / \
  3270.                               ---------                   /   \
  3271.         / \          / \      |       |      / \         /     \
  3272.        /   \        /   \     |  2.1  |     /   \       /       \
  3273.       /     \      /     \    |       |    /     \     /         \
  3274.      /1.2.1.3\    /1.3.1.1\   |       |   /1.2.2.2\   /1.2.2.1.1.1\
  3275.      ---------    ---------   ---------   ---------   -------------
  3276.          ^            ^           |           ^             ^
  3277.          |            |           v           |             |
  3278.         / \           |       ---------      / \            |
  3279.        /   \          |       \  1.3  /     /   \           |
  3280.       /     \         ---------\     /     /     \-----------
  3281.      /1.2.1.1\                  \   /     /1.2.2.1\
  3282.      ---------                   \ /      ---------
  3283.          ^                        |           ^
  3284.          |                        v           |
  3285.          |                    ---------       |
  3286.          |                    \  1.2  /       |
  3287.          ----------------------\     /---------
  3288.                                 \   /
  3289.                                  \ /
  3290.                                   |
  3291.                                   v
  3292.                               ---------
  3293.                               \  1.1  /
  3294.                                \     /
  3295.                                 \   /
  3296.                                  \ /
  3297. File: rcs,  Node: AppendixB,  Next: Index,  Prev: AppendixA,  Up: Top
  3298. Books and related manuals
  3299. *************************
  3300. * Menu:
  3301. * Feldman::   GNU - Make.
  3302. * Hunt::      GNU - diff.
  3303. * Rochkind::  SCCS.
  3304. * Tichy::     Design and implementation of RCS.
  3305. * Leblang::   Computer-Aided Software Engineering.
  3306. * Glasser::   The Evolution of a Source Code Control
  3307.               System.
  3308. * Brown::     The Clear/Caster System.
  3309. * Habermann:: A Software Development Control System.
  3310. * DEC::       Code Management System.
  3311. * Lampson::   Practical Use of a Polymorphic Applicative
  3312.               Language.
  3313. * Tichy1::    A Data Model for Programming Support
  3314.               Environments and its Application.
  3315. * Heckel::    A Technique for Isolating Differences
  3316.               Between Files.
  3317. * Tichy2::    The String-to-String Correction Problem
  3318.               with Block Moves.
  3319. File: rcs,  Node: Feldman,  Next: Hunt,  Up: AppendixB
  3320. Feldman,Stuart I.
  3321. =================
  3322.      Feldman, Stuart I.,
  3323.      "Make -- A Program for Maintaining Computer Programs",
  3324.      Software -- Practice & Experience,
  3325.      vol. 9, no. 3, pp. 255-265, March 1979.
  3326. File: rcs,  Node: Hunt,  Next: Rochkind,  Prev: Feldman,  Up: AppendixB
  3327. Hunt, James W. and McIlroy, M. D.
  3328. =================================
  3329.      Hunt, James W. and McIlroy, M. D.,
  3330.      "An Algorithm for Differential File Comparison",
  3331.      41, Computing Science Technical Report,
  3332.      Bell Laboratories, June 1976.
  3333. File: rcs,  Node: Rochkind,  Next: Tichy,  Prev: Hunt,  Up: AppendixB
  3334. Rochkind, Marc J.
  3335. =================
  3336.      Rochkind, Marc J.
  3337.      "The Source Code Control System",
  3338.      IEEE Transactions on Software Engineering, vol. SE-1,
  3339.      no. 4, pp. 364-370, Dec. 1975.
  3340. File: rcs,  Node: Tichy,  Next: Leblang,  Prev: Rochkind,  Up: AppendixB
  3341. Tichy, Walter F.
  3342. ================
  3343.      Tichy, Walter F.
  3344.      "Design, Implementation, and Evaluation of a Revision Control System"
  3345.      Proceedings of the 6th International Conference on Software Engineering,
  3346.      pp. 58-67, ACM, IEEE, IPS, NBS, September 1982.
  3347. File: rcs,  Node: Leblang,  Next: Glasser,  Prev: Tichy,  Up: AppendixB
  3348. Leblang, David B. and Chase, Robert P.
  3349. ======================================
  3350.      Leblang, David B. and Chase, Robert P.
  3351.      "Computer-Aided Software Engineering in a Distributed
  3352.      Workstation Environment",
  3353.      SIGPLAN Notices, vol. 19, no. 5, pp. 104-112, May 1984.
  3354.      Proceedings of the ACM SIGSOFT/SIGPLAN Software Engineering Symposium
  3355.      on Practical Software Development Environments.
  3356. File: rcs,  Node: Glasser,  Next: Brown,  Prev: Leblang,  Up: AppendixB
  3357. Glasser, Alan L.
  3358. ================
  3359.      Glasser, Alan L.
  3360.      "The Evolution of a Source Code Control System"
  3361.      Software Engineering Notes, vol. 3, no. 5, pp. 122-125, Nov. 1978.
  3362.      Proceedings of the Software Quality and Assurance Workshop.
  3363. File: rcs,  Node: Brown,  Next: Habermann,  Prev: Glasser,  Up: AppendixB
  3364. Brown, H.B.
  3365. ===========
  3366.      Brown, H.B.
  3367.      "The Clear/Caster System",
  3368.      Nato Conference on Software Engineering, Rome 1970
  3369. File: rcs,  Node: Habermann,  Next: DEC,  Prev: Brown,  Up: AppendixB
  3370. Habermann, A. Nico
  3371. ==================
  3372.      Habermann, A. Nico
  3373.      "A Software Development Control System",
  3374.      Technical Report, Carnegie-Mellon University,
  3375.      Department of Computer Science, Jan. 1979.
  3376. File: rcs,  Node: DEC,  Next: Lampson,  Prev: Habermann,  Up: AppendixB
  3377. Code Management System
  3378. ======================
  3379.      Digital Equipment Corporation
  3380.      "Code Management System",
  3381.      Document No. EA-23134-82, 1982
  3382. File: rcs,  Node: Lampson,  Next: Tichy1,  Prev: DEC,  Up: AppendixB
  3383. Lampson, Butler W. and Schmidt, Eric E.
  3384. =======================================
  3385.      Lampson, Butler W. and Schmidt, Eric E.
  3386.      "Practical Use of a Polymorphic Applicative Language",
  3387.      Proceedings of the 10th Symposium on Principles of
  3388.      Programming Languages,
  3389.      pp. 237-255, ACM, January 1983.
  3390. File: rcs,  Node: Tichy1,  Next: Heckel,  Prev: Lampson,  Up: AppendixB
  3391. Tichy, Walter F.
  3392. ================
  3393.      Tichy, Walter F.
  3394.      "A Data Model for Programming Support Environments and its Application",
  3395.      Automated Tools for Information System Design and Development, ed.
  3396.      Hans-Jochen Schneider and Anthony I. Wasserman,
  3397.      North-Holland Publishing Company, Amsterdam 1982.
  3398. File: rcs,  Node: Heckel,  Next: Tichy2,  Prev: Tichy1,  Up: AppendixB
  3399. Heckel, Paul
  3400. ============
  3401.      Heckel, Paul
  3402.      "A Technique for Isolating Differences Between Files",
  3403.      Communications of the ACM, vol. 21, no. 4, pp. 264-268, April
  3404.      1978.
  3405. File: rcs,  Node: Tichy2,  Prev: Heckel,  Up: AppendixB
  3406. Tichy, Walter F.
  3407. ================
  3408.      Tichy, Walter F.
  3409.      "The String-to-String Correction Problem with Block Moves",
  3410.      ACM Transactions on Computer Systems, vol. 2, no. 4, pp. 309-321,
  3411.      Nov. 1984.
  3412. File: rcs,  Node: Index,  Prev: AppendixB,  Up: Top
  3413. Index
  3414. *****
  3415. * Menu:
  3416. * -a:                                   rcsOpta.
  3417. * -A <1>:                               rcsOptAu.
  3418. * -A <1>:                               rcsmergeOptA.
  3419. * -A:                                   mergeOptA.
  3420. * -b <1>:                               rlogOptb.
  3421. * -b:                                   rcsOptb.
  3422. * -c:                                   rcsOptc.
  3423. * -d <1>:                               rlogOptd.
  3424. * -d <1>:                               ciOptd.
  3425. * -d:                                   coOptd.
  3426. * -E:                                   rcsmergeOptE.
  3427. * -e <1>:                               mergeOptE.
  3428. * -e:                                   rcsOpte.
  3429. * -E:                                   mergeOptE.
  3430. * -f <1>:                               coOptf.
  3431. * -f:                                   ciOptf.
  3432. * -h:                                   rlogOpth.
  3433. * -I <1>:                               ciOptIu.
  3434. * -I <1>:                               rcsOptIu.
  3435. * -I:                                   coOptI.
  3436. * -i <1>:                               rcsOpti.
  3437. * -i:                                   ciOpti.
  3438. * -j <1>:                               coOptj.
  3439. * -j:                                   ciOptj.
  3440. * -k <1>:                               ciOptk.
  3441. * -k <1>:                               rcsOptk.
  3442. * -k <1>:                               rcsdiffOptk.
  3443. * -k <1>:                               rcsmergeOptk.
  3444. * -k:                                   rcscleanOptk.
  3445. * -kb:                                  coOptk.
  3446. * -kk:                                  coOptk.
  3447. * -kkv:                                 coOptk.
  3448. * -kkvl:                                coOptk.
  3449. * -ko:                                  coOptk.
  3450. * -kv:                                  coOptk.
  3451. * -l <1>:                               ciOptl.
  3452. * -l:                                   rcsOptl.
  3453. * -L:                                   rlogOptLu.
  3454. * -l <1>:                               coOptl.
  3455. * -l:                                   rlogOptl.
  3456. * -L <1>:                               mergeOptL.
  3457. * -L:                                   rcsOptLu.
  3458. * -m:                                   rcsOptm.
  3459. * -M:                                   coOptM.
  3460. * -m:                                   ciOptm.
  3461. * -M <1>:                               ciOptMu.
  3462. * -M:                                   rcsOptMu.
  3463. * -n:                                   ciOptn.
  3464. * -N <1>:                               ciOptNu.
  3465. * -N:                                   rlogOptN.
  3466. * -n <1>:                               rcscleanOptn.
  3467. * -n:                                   rcsOptn.
  3468. * -N:                                   rcsOptNu.
  3469. * -o:                                   rcsOpto.
  3470. * -p <1>:                               rcsmergeOptp.
  3471. * -p <1>:                               coOptp.
  3472. * -p:                                   mergeOptp.
  3473. * -q <1>:                               rcscleanOptq.
  3474. * -q <1>:                               identOptq.
  3475. * -q <1>:                               coOptq.
  3476. * -q <1>:                               rcsdiffOptq.
  3477. * -q <1>:                               rcsOptq.
  3478. * -q <1>:                               ciOptq.
  3479. * -q:                                   mergeOptq.
  3480. * -r <1>:                               rcscleanOptr.
  3481. * -r:                                   rcsdiffOptr.
  3482. * -R:                                   rlogOptRu.
  3483. * -r <1>:                               coOptr.
  3484. * -r <1>:                               ciOptr.
  3485. * -r:                                   rlogOptr.
  3486. * -s <1>:                               coOpts.
  3487. * -s <1>:                               rcsOpts.
  3488. * -s <1>:                               rlogOpts.
  3489. * -s:                                   ciOpts.
  3490. * -T <1>:                               rcsmergeOptT.
  3491. * -T <1>:                               ciOptTu.
  3492. * -T <1>:                               rcsOptTu.
  3493. * -T:                                   rcscleanOptT.
  3494. * -t <1>:                               ciOptt.
  3495. * -t <1>:                               rcsOptt.
  3496. * -t:                                   rlogOptt.
  3497. * -T <1>:                               rlogOptTu.
  3498. * -T <1>:                               rcsdiffOptT.
  3499. * -T:                                   coOptT.
  3500. * -t-:                                  ciOptt.
  3501. * -u:                                   ciOptu.
  3502. * -U:                                   rcsOptUu.
  3503. * -u <1>:                               rcsOptu.
  3504. * -u <1>:                               coOptu.
  3505. * -u:                                   rcscleanOptu.
  3506. * -V <1>:                               rcsmergeOptV.
  3507. * -V <1>:                               rcsdiffOptV.
  3508. * -V <1>:                               coOptV.
  3509. * -V <1>:                               rcscleanOptV.
  3510. * -V <1>:                               rlogOptV.
  3511. * -V <1>:                               mergeOptV.
  3512. * -V <1>:                               identOptV.
  3513. * -V <1>:                               rcsOptV.
  3514. * -V:                                   ciOptV.
  3515. * -w <1>:                               ciOptw.
  3516. * -w <1>:                               rlogOptw.
  3517. * -w:                                   coOptw.
  3518. * -x <1>:                               ciOptx.
  3519. * -x <1>:                               rlogOptx.
  3520. * -x <1>:                               rcsdiffOptx.
  3521. * -x <1>:                               coOptx.
  3522. * -x <1>:                               rcsmergeOptx.
  3523. * -x <1>:                               rcsOptx.
  3524. * -x:                                   rcscleanOptx.
  3525. * -z <1>:                               rcsOptz.
  3526. * -z <1>:                               rlogOptz.
  3527. * -z <1>:                               rcsmergeOptz.
  3528. * -z <1>:                               ciOptz.
  3529. * -z <1>:                               rcscleanOptz.
  3530. * -z:                                   coOptz.
  3531. * About:                                About.
  3532. * Access:                               rcsOpta.
  3533. * Access Liste:                         rcsOptAu.
  3534. * ACM <1>:                              Lampson.
  3535. * ACM:                                  Heckel.
  3536. * Block moves:                          Tichy2.
  3537. * branch:                               rcsOptb.
  3538. * Bugs:                                 rlogBugs.
  3539. * change RCS:                           rcs.
  3540. * check in:                             CheckIn.
  3541. * Check out:                            coOptd.
  3542. * check out:                            CheckOut.
  3543. * Checked in by user:                   rlogOptw.
  3544. * Checkin date/time:                    rlogOptd.
  3545. * ci:                                   CheckIn.
  3546. * clean up:                             rcsclean.
  3547. * Clear/Caster <1>:                     Habermann.
  3548. * Clear/Caster:                         Brown.
  3549. * co:                                   CheckOut.
  3550. * Code Management System:               DEC.
  3551. * Command line options:                 rlogOptions.
  3552. * comment leader:                       rcsOptc.
  3553. * compare revisions:                    rcsdiff.
  3554. * comparison <1>:                       rcscleanOptr.
  3555. * comparison:                           rcsdiffOptr.
  3556. * Compatibility:                        rcsCompatibility.
  3557. * conflict:                             rcsmergeOptE.
  3558. * conflict styles:                      mergeOptE.
  3559. * Data Model:                           Tichy1.
  3560. * date <1>:                             coOptd.
  3561. * date:                                 ciOptd.
  3562. * DEC:                                  DEC.
  3563. * Default branch:                       rlogOptb.
  3564. * default form:                         coOptk.
  3565. * Delete revision:                      rcsOpto.
  3566. * description:                          ciOptt.
  3567. * Descriptive:                          rcsOptt.
  3568. * Descriptive text:                     rlogOptt.
  3569. * diagnostic:                           ciOptq.
  3570. * Diff <1>:                             Heckel.
  3571. * Diff:                                 Hunt.
  3572. * diff:                                 rcsmergeOptA.
  3573. * diff3 <1>:                            rcsmergeOptA.
  3574. * diff3 <1>:                            mergeOptA.
  3575. * diff3:                                mergeOptE.
  3576. * Differences between files:            Heckel.
  3577. * Emulate:                              coOptV.
  3578. * emulate RCS Version:                  ciOptV.
  3579. * Emulation:                            rlogOptV.
  3580. * Emulation of RCS <1>:                 rcsOptV.
  3581. * Emulation of RCS:                     rcsmergeOptV.
  3582. * Emulation of RCS Version <1>:         rcsdiffOptV.
  3583. * Emulation of RCS Version:             rcscleanOptV.
  3584. * Environment <1>:                      coEnv.
  3585. * Environment <1>:                      rcscleanEnv.
  3586. * Environment <1>:                      rlogEnv.
  3587. * Environment <1>:                      rcsmergeEnv.
  3588. * Environment <1>:                      rcsdiffEnv.
  3589. * Environment:                          rcsEnv.
  3590. * Environments:                         Tichy1.
  3591. * Erase Login names:                    rcsOpte.
  3592. * Examples <1>:                         rcsmergeExamples.
  3593. * Examples <1>:                         rcscleanExamples.
  3594. * Examples <1>:                         rcsdiffExamples.
  3595. * Examples:                             rlogExamples.
  3596. * Feldman Stuart I.:                    Feldman.
  3597. * file merge:                           merge.
  3598. * File Modes:                           coFileModes.
  3599. * Files <1>:                            coFiles.
  3600. * Files <1>:                            rcscleanFiles.
  3601. * Files:                                rcsFiles.
  3602. * force a deposit:                      ciOptf.
  3603. * Format:                               AppendixA.
  3604. * Format of RCS files.:                 AppendixA.
  3605. * GNU-Diff:                             Hunt.
  3606. * GNU-Make:                             Feldman.
  3607. * Hunt, James W. and McIlroy, M. D.:    Hunt.
  3608. * ident:                                ident.
  3609. * identify Keywords:                    ident.
  3610. * Ignore:                               rlogOptLu.
  3611. * Information:                          rlog.
  3612. * Information about Revisions:          rlogOptr.
  3613. * Information Rev. given state:         rlogOpts.
  3614. * initial checkin:                      ciOpti.
  3615. * Initialize:                           rcsOpti.
  3616. * Interactiv:                           rcsOptIu.
  3617. * Interactive:                          coOptI.
  3618. * interactive:                          ciOptIu.
  3619. * interactive mode:                     ciOptIu.
  3620. * Introduction:                         rcsIntroduction.
  3621. * join:                                 coOptj.
  3622. * just checkin:                         ciOptj.
  3623. * Keyword <1>:                          rcsOptk.
  3624. * Keyword <1>:                          rcsdiffOptk.
  3625. * Keyword <1>:                          coKeyword.
  3626. * Keyword <1>:                          rcsmergeOptk.
  3627. * Keyword:                              rcscleanOptk.
  3628. * Keyword Author:                       coKeyword.
  3629. * Keyword Date:                         coKeyword.
  3630. * Keyword Header:                       coKeyword.
  3631. * Keyword Id:                           coKeyword.
  3632. * Keyword Locker:                       coKeyword.
  3633. * Keyword Log:                          coKeyword.
  3634. * Keyword Name:                         coKeyword.
  3635. * Keyword RCSFile:                      coKeyword.
  3636. * Keyword Revision:                     coKeyword.
  3637. * Keyword Source:                       coKeyword.
  3638. * Keyword State:                        coKeyword.
  3639. * keyword values:                       ciOptk.
  3640. * Keywords <1>:                         identKeywords.
  3641. * Keywords:                             ident.
  3642. * lock <1>:                             coOptl.
  3643. * lock:                                 coOptu.
  3644. * lock a revision:                      ciOptl.
  3645. * Lock breaking:                        rcsOptMu.
  3646. * Lock revsion:                         rcsOptl.
  3647. * Locked revisions:                     rlogOptl.
  3648. * Log message:                          rcsOptm.
  3649. * log message:                          ciOptm.
  3650. * log messages:                         rlog.
  3651. * login <1>:                            ciOptw.
  3652. * login:                                coOptw.
  3653. * Login names:                          rcsOpta.
  3654. * Mail:                                 rcsOptMu.
  3655. * Make:                                 Feldman.
  3656. * merge:                                merge.
  3657. * merge revisions:                      rcsmerge.
  3658. * Modification <1>:                     coOptM.
  3659. * Modification <1>:                     coOptT.
  3660. * Modification <1>:                     rcscleanOptT.
  3661. * Modification:                         rcsdiffOptT.
  3662. * modification time <1>:                ciOptTu.
  3663. * modification time:                    ciOptMu.
  3664. * Modification time:                    rlogOptTu.
  3665. * Modification Time <1>:                rcsOptTu.
  3666. * Modification Time:                    rcsmergeOptT.
  3667. * name <1>:                             rcsOptn.
  3668. * name:                                 rcsOptNu.
  3669. * Names:                                rlogOptRu.
  3670. * no lock:                              rlogOptLu.
  3671. * no Symbolic name:                     rlogOptN.
  3672. * non-Strict Locking:                   rcsOptUu.
  3673. * Output:                               rcsmergeOptp.
  3674. * output:                               coOptp.
  3675. * Output conflicts:                     mergeOptA.
  3676. * override symbolic name:               ciOptNu.
  3677. * override Symbolic name:               rcsOptNu.
  3678. * overwriting:                          coOptf.
  3679. * pathname:                             rlogOpth.
  3680. * Polymorhpic Applicative Language:     Lampson.
  3681. * preserve:                             coOptT.
  3682. * print:                                coOptp.
  3683. * print RCS Version:                    ciOptV.
  3684. * Quiet <1>:                            rcsdiffOptq.
  3685. * Quiet:                                rcscleanOptq.
  3686. * quiet <1>:                            coOptq.
  3687. * quiet:                                ciOptq.
  3688. * Quiet mode:                           mergeOptq.
  3689. * Quiete mode <1>:                      identOptq.
  3690. * Quiete mode:                          rcsOptq.
  3691. * RCS:                                  Tichy.
  3692. * rcs:                                  rcs.
  3693. * RCS commands:                         rcsIntroduction.
  3694. * RCS Version <1>:                      rcscleanOptV.
  3695. * RCS Version:                          rcsdiffOptV.
  3696. * rcsclean:                             rcsclean.
  3697. * rcsdiff:                              rcsdiff.
  3698. * rcsfile:                              AppendixA.
  3699. * rcsmerge:                             rcsmerge.
  3700. * remove:                               rcscleanOptn.
  3701. * revision:                             ciOptr.
  3702. * Revision <1>:                         rcscleanOptr.
  3703. * Revision:                             rcsdiffOptr.
  3704. * revision:                             coOptr.
  3705. * Revision message:                     rcsOptm.
  3706. * rlog:                                 rlog.
  3707. * SCCS <1>:                             Glasser.
  3708. * SCCS:                                 Rochkind.
  3709. * send result to standard out.:         rcsmergeOptp.
  3710. * set branch:                           rcsOptb.
  3711. * SIGPLAN:                              Leblang.
  3712. * Software Quality:                     Glasser.
  3713. * Standard output:                      mergeOptp.
  3714. * State:                                coOpts.
  3715. * States:                               rcsOpts.
  3716. * states:                               ciOpts.
  3717. * Strict Locking:                       rcsOptLu.
  3718. * String-To-String Correction:          Tichy2.
  3719. * Substitution:                         coKeyword.
  3720. * Suffixes <1>:                         rcsdiffOptx.
  3721. * Suffixes <1>:                         rcsOptx.
  3722. * Suffixes <1>:                         rcsmergeOptx.
  3723. * Suffixes <1>:                         rlogOptx.
  3724. * Suffixes:                             coOptx.
  3725. * suffixes:                             ciOptx.
  3726. * Suffixes:                             rcscleanOptx.
  3727. * Support:                              Tichy1.
  3728. * Symbolic <1>:                         rcsOptNu.
  3729. * Symbolic:                             rcsOptn.
  3730. * symbolic name:                        ciOptn.
  3731. * Symposium:                            Leblang.
  3732. * tag <1>:                              ciOptn.
  3733. * tag <1>:                              rcsOptNu.
  3734. * tag:                                  rcsOptn.
  3735. * time:                                 coOptd.
  3736. * Time Zone:                            rcsOptz.
  3737. * Time zone <1>:                        rlogOptz.
  3738. * Time zone:                            rcscleanOptz.
  3739. * Time Zone:                            rcsmergeOptz.
  3740. * time zoone:                           ciOptz.
  3741. * time/date <1>:                        rcscleanOptT.
  3742. * time/date:                            rcsdiffOptT.
  3743. * Tools:                                Tichy1.
  3744. * TZ:                                   ciOptz.
  3745. * unlock:                               rcscleanOptn.
  3746. * unlock a revision:                    ciOptu.
  3747. * Unlock revision:                      rcscleanOptu.
  3748. * Unlock revsion:                       rcsOptu.
  3749. * Version <1>:                          rcsmergeOptV.
  3750. * Version <1>:                          identOptV.
  3751. * Version <1>:                          coOptV.
  3752. * Version <1>:                          rlogOptV.
  3753. * Version <1>:                          mergeOptV.
  3754. * Version:                              rcsOptV.
  3755. * working:                              coOptf.
  3756. * working files:                        rcsclean.
  3757. * Workstation:                          Leblang.
  3758. * zoone:                                ciOptz.
  3759. * Zoone:                                coOptz.
  3760. Tag Table:
  3761. Node: Top
  3762. Node: About
  3763. Node: AboutDesc
  3764. Node: Versions
  3765. Node: BugReport
  3766. 10959
  3767. Node: VersionControl
  3768. 11477
  3769. Node: Introduction
  3770. 13567
  3771. Node: StartRCS
  3772. 15841
  3773. Node: Identification
  3774. 20616
  3775. Node: RevisionTree
  3776. 23281
  3777. Node: Branches
  3778. 24405
  3779. Node: Deltas
  3780. 28501
  3781. Node: Controversial
  3782. 35453
  3783. Node: Configuration
  3784. 39738
  3785. Node: Functions
  3786. 40454
  3787. Node: MAKERCS
  3788. 44407
  3789. Node: Statistics
  3790. 48050
  3791. Node: Survey
  3792. 53822
  3793. Node: rcsIntroduction
  3794. 61131
  3795. Node: rcsintroDesc
  3796. 61474
  3797. Node: rcsintroFunc
  3798. 62243
  3799. Node: rcsintroStart
  3800. 64580
  3801. Node: rcsintroAutoIdent
  3802. 69423
  3803. Node: Synopsis
  3804. 70737
  3805. Node: CheckIn
  3806. 74650
  3807. Node: ciIntro
  3808. 75189
  3809. Node: ciOptions
  3810. 79303
  3811. Node: ciOptr
  3812. 80245
  3813. Node: ciOptl
  3814. 80818
  3815. Node: ciOptu
  3816. 81216
  3817. Node: ciOptf
  3818. 81674
  3819. Node: ciOptk
  3820. 81901
  3821. Node: ciOptq
  3822. 82769
  3823. Node: ciOpti
  3824. 83026
  3825. Node: ciOptj
  3826. 83276
  3827. Node: ciOptIu
  3828. 83495
  3829. Node: ciOptd
  3830. 83728
  3831. Node: ciOptMu
  3832. 84139
  3833. Node: ciOptm
  3834. 84560
  3835. Node: ciOptn
  3836. 85190
  3837. Node: ciOptNu
  3838. 85476
  3839. Node: ciOpts
  3840. 85692
  3841. Node: ciOptt
  3842. 85904
  3843. Node: ciOptTu
  3844. 86792
  3845. Node: ciOptw
  3846. 88386
  3847. Node: ciOptV
  3848. 88638
  3849. Node: ciOptx
  3850. 88850
  3851. Node: ciOptz
  3852. 89797
  3853. Node: ciFileNaming
  3854. 90818
  3855. Node: ciExamples
  3856. 92351
  3857. Node: ciFileModes
  3858. 93122
  3859. Node: ciFiles
  3860. 93465
  3861. Node: setuid use
  3862. 95859
  3863. Node: ciEnv
  3864. 98664
  3865. Node: ciDiag
  3866. 99297
  3867. Node: CheckOut
  3868. 99581
  3869. Node: coIntro
  3870. 100111
  3871. Node: coOptions
  3872. 101999
  3873. Node: coOptr
  3874. 102891
  3875. Node: coOptl
  3876. 103871
  3877. Node: coOptu
  3878. 104074
  3879. Node: coOptf
  3880. 104460
  3881. Node: coOptk
  3882. 104715
  3883. Node: coOptp
  3884. 107327
  3885. Node: coOptq
  3886. 107626
  3887. Node: coOptI
  3888. 107780
  3889. Node: coOptd
  3890. 108010
  3891. Node: coOptM
  3892. 109904
  3893. Node: coOpts
  3894. 110184
  3895. Node: coOptT
  3896. 110378
  3897. Node: coOptw
  3898. 110971
  3899. Node: coOptj
  3900. 111290
  3901. Node: coOptV
  3902. 112913
  3903. Node: coOptx
  3904. 114089
  3905. Node: coOptz
  3906. 114279
  3907. Node: coKeyword
  3908. 114407
  3909. Node: coFileModes
  3910. 117937
  3911. Node: coFiles
  3912. 118550
  3913. Node: coEnv
  3914. 118784
  3915. Node: coDiag
  3916. 118996
  3917. Node: coLimits
  3918. 119288
  3919. Node: rcs
  3920. 119421
  3921. Node: rcsIntro
  3922. 119964
  3923. Node: rcsOptions
  3924. 120672
  3925. Node: rcsOpti
  3926. 121886
  3927. Node: rcsOpta
  3928. 122274
  3929. Node: rcsOptAu
  3930. 122527
  3931. Node: rcsOpte
  3932. 122745
  3933. Node: rcsOptb
  3934. 123063
  3935. Node: rcsOptc
  3936. 123334
  3937. Node: rcsOptk
  3938. 124035
  3939. Node: rcsOptl
  3940. 124546
  3941. Node: rcsOptu
  3942. 124998
  3943. Node: rcsOptLu
  3944. 125666
  3945. Node: rcsOptUu
  3946. 125973
  3947. Node: rcsOptm
  3948. 126424
  3949. Node: rcsOptMu
  3950. 126616
  3951. Node: rcsOptn
  3952. 126983
  3953. Node: rcsOptNu
  3954. 127984
  3955. Node: rcsOpto
  3956. 128205
  3957. Node: rcsOptq
  3958. 128919
  3959. Node: rcsOptIu
  3960. 129071
  3961. Node: rcsOpts
  3962. 129254
  3963. Node: rcsOptt
  3964. 129822
  3965. Node: rcsOptTu
  3966. 130526
  3967. Node: rcsOptV
  3968. 131083
  3969. Node: rcsOptx
  3970. 131290
  3971. Node: rcsOptz
  3972. 131470
  3973. Node: rcsCompatibility
  3974. 131700
  3975. Node: rcsFiles
  3976. 132284
  3977. Node: rcsEnv
  3978. 132556
  3979. Node: rcsDiag
  3980. 132766
  3981. Node: rcsBugs
  3982. 133022
  3983. Node: ident
  3984. 133830
  3985. Node: identIntro
  3986. 134095
  3987. Node: identOptions
  3988. 135619
  3989. Node: identOptq
  3990. 135947
  3991. Node: identOptV
  3992. 136108
  3993. Node: identKeywords
  3994. 136234
  3995. Node: rcsclean
  3996. 136636
  3997. Node: rcscleanIntro
  3998. 137194
  3999. Node: rcscleanOptions
  4000. 138778
  4001. Node: rcscleanOptk
  4002. 139436
  4003. Node: rcscleanOptn
  4004. 139702
  4005. Node: rcscleanOptq
  4006. 140000
  4007. Node: rcscleanOptr
  4008. 140186
  4009. Node: rcscleanOptT
  4010. 140431
  4011. Node: rcscleanOptu
  4012. 141035
  4013. Node: rcscleanOptV
  4014. 141247
  4015. Node: rcscleanOptx
  4016. 141497
  4017. Node: rcscleanOptz
  4018. 141716
  4019. Node: rcscleanExamples
  4020. 141933
  4021. Node: rcscleanFiles
  4022. 142286
  4023. Node: rcscleanEnv
  4024. 142458
  4025. Node: rcscleanDiag
  4026. 142688
  4027. Node: rcscleanBugs
  4028. 142943
  4029. Node: rcsdiff
  4030. 143152
  4031. Node: rcsdiffIntro
  4032. 143644
  4033. Node: rcsdiffOptions
  4034. 143964
  4035. Node: rcsdiffOptk
  4036. 144532
  4037. Node: rcsdiffOptq
  4038. 145218
  4039. Node: rcsdiffOptr
  4040. 145395
  4041. Node: rcsdiffOptT
  4042. 146261
  4043. Node: rcsdiffOptV
  4044. 146431
  4045. Node: rcsdiffOptx
  4046. 146677
  4047. Node: rcsdiffExamples
  4048. 146872
  4049. Node: rcsdiffEnv
  4050. 147217
  4051. Node: rcsdiffDiag
  4052. 147446
  4053. Node: rcsmerge
  4054. 147639
  4055. Node: rcsmergeIntro
  4056. 148088
  4057. Node: rcsmergeOptions
  4058. 149020
  4059. Node: rcsmergeOptA
  4060. 149645
  4061. Node: rcsmergeOptE
  4062. 149989
  4063. Node: rcsmergeOptk
  4064. 150341
  4065. Node: rcsmergeOptp
  4066. 150868
  4067. Node: rcsmergeOptT
  4068. 151110
  4069. Node: rcsmergeOptV
  4070. 151347
  4071. Node: rcsmergeOptx
  4072. 151573
  4073. Node: rcsmergeOptz
  4074. 151773
  4075. Node: rcsmergeExamples
  4076. 151980
  4077. Node: rcsmergeEnv
  4078. 152959
  4079. Node: rcsmergeDiag
  4080. 153192
  4081. Node: rlog
  4082. 153362
  4083. Node: rlogIntro
  4084. 153817
  4085. Node: rlogOptions
  4086. 154939
  4087. Node: rlogOptLu
  4088. 155935
  4089. Node: rlogOptRu
  4090. 156184
  4091. Node: rlogOpth
  4092. 156451
  4093. Node: rlogOptt
  4094. 156701
  4095. Node: rlogOptN
  4096. 156880
  4097. Node: rlogOptb
  4098. 157041
  4099. Node: rlogOptd
  4100. 157275
  4101. Node: rlogOptl
  4102. 158240
  4103. Node: rlogOptr
  4104. 158686
  4105. Node: rlogOpts
  4106. 159584
  4107. Node: rlogOptw
  4108. 159904
  4109. Node: rlogOptTu
  4110. 160249
  4111. Node: rlogOptV
  4112. 160470
  4113. Node: rlogOptx
  4114. 160732
  4115. Node: rlogOptz
  4116. 160934
  4117. Node: rlogExamples
  4118. 162033
  4119. Node: rlogEnv
  4120. 162513
  4121. Node: rlogDiag
  4122. 162731
  4123. Node: rlogBugs
  4124. 162905
  4125. Node: merge
  4126. 163241
  4127. Node: mergeIntro
  4128. 163557
  4129. Node: mergeOptions
  4130. 164427
  4131. Node: mergeOptA
  4132. 164908
  4133. Node: mergeOptE
  4134. 165238
  4135. Node: mergeOptL
  4136. 165582
  4137. Node: mergeOptp
  4138. 166011
  4139. Node: mergeOptq
  4140. 166208
  4141. Node: mergeOptV
  4142. 166367
  4143. Node: mergeDiag
  4144. 166487
  4145. Node: mergeBugs
  4146. 166670
  4147. Node: AppendixA
  4148. 166857
  4149. Node: rcsfileIntro
  4150. 167091
  4151. Node: rcsfileExample
  4152. 171228
  4153. Node: AppendixB
  4154. 172952
  4155. Node: Feldman
  4156. 173811
  4157. Node: Hunt
  4158. 174078
  4159. Node: Rochkind
  4160. 174398
  4161. Node: Tichy
  4162. 174667
  4163. Node: Leblang
  4164. 175008
  4165. Node: Glasser
  4166. 175487
  4167. Node: Brown
  4168. 175811
  4169. Node: Habermann
  4170. 176020
  4171. Node: DEC
  4172. 176303
  4173. Node: Lampson
  4174. 176529
  4175. Node: Tichy1
  4176. 176910
  4177. Node: Heckel
  4178. 177302
  4179. Node: Tichy2
  4180. 177561
  4181. Node: Index
  4182. 177831
  4183. End Tag Table
  4184.