home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / cvs.info-5 < prev    next >
Encoding:
GNU Info File  |  1996-10-13  |  48.0 KB  |  1,290 lines
  1. This is Info file cvs.info, produced by Makeinfo-1.64 from the input
  2. file /ade-source/fsf/cvs/doc/cvs.texinfo.
  3.  
  4.    Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994
  5. Free Software Foundation, Inc.
  6.  
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.  
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided also
  13. that the section entitled "GNU General Public License" is included
  14. exactly as in the original, and provided that the entire resulting
  15. derived work is distributed under the terms of a permission notice
  16. identical to this one.
  17.  
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions, except that the section entitled "GNU General Public License"
  21. and this permission notice may be included in translations approved by
  22. the Free Software Foundation instead of in the original English.
  23.  
  24. 
  25. File: cvs.info,  Node: rdiff,  Next: release,  Prev: log,  Up: Invoking CVS
  26.  
  27. rdiff--'patch' format diffs between releases
  28. ============================================
  29.  
  30.    * rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules...
  31.  
  32.    * Requires: repository.
  33.  
  34.    * Changes: nothing.
  35.  
  36.    * Synonym: patch
  37.  
  38.    Builds a Larry Wall format patch(1) file between two releases, that
  39. can be fed directly into the patch program to bring an old release
  40. up-to-date with the new release.  (This is one of the few CVS commands
  41. that operates directly from the repository, and doesn't require a prior
  42. checkout.) The diff output is sent to the standard output device.
  43.  
  44.    You can specify (using the standard `-r' and `-D' options) any
  45. combination of one or two revisions or dates.  If only one revision or
  46. date is specified, the patch file reflects differences between that
  47. revision or date and the current head revisions in the RCS file.
  48.  
  49.    Note that if the software release affected is contained in more than
  50. one directory, then it may be necessary to specify the `-p' option to
  51. the patch command when patching the old sources, so that patch is able
  52. to find the files that are located in other directories.
  53.  
  54. * Menu:
  55.  
  56. * rdiff options::               rdiff options
  57. * rdiff examples::              rdiff examples
  58.  
  59. 
  60. File: cvs.info,  Node: rdiff options,  Next: rdiff examples,  Up: rdiff
  61.  
  62. rdiff options
  63. -------------
  64.  
  65.    These standard options are supported by `rdiff' (*note Common
  66. options::., for a complete description of them):
  67.  
  68. `-D DATE'
  69.      Use the most recent revision no later than DATE.
  70.  
  71. `-f'
  72.      If no matching revision is found, retrieve the most recent
  73.      revision (instead of ignoring the file).
  74.  
  75. `-l'
  76.      Local; don't descend subdirectories.
  77.  
  78. `-r TAG'
  79.      Use revision TAG.
  80.  
  81.    In addition to the above, these options are available:
  82.  
  83. `-c'
  84.      Use the context diff format.  This is the default format.
  85.  
  86. `-s'
  87.      Create a summary change report instead of a patch.  The summary
  88.      includes information about files that were changed or added
  89.      between the releases.  It is sent to the standard output device.
  90.      This is useful for finding out, for example, which files have
  91.      changed between two dates or revisions.
  92.  
  93. `-t'
  94.      A diff of the top two revisions is sent to the standard output
  95.      device.  This is most useful for seeing what the last change to a
  96.      file was.
  97.  
  98. `-u'
  99.      Use the unidiff format for the context diffs.  This option is not
  100.      available if your diff does not support the unidiff format.
  101.      Remember that old versions of the `patch' program can't handle the
  102.      unidiff format, so if you plan to post this patch to the net you
  103.      should probably not use `-u'.
  104.  
  105. `-V VN'
  106.      Expand RCS keywords according to the rules current in RCS version
  107.      VN (the expansion format changed with RCS version 5).
  108.  
  109. 
  110. File: cvs.info,  Node: rdiff examples,  Prev: rdiff options,  Up: rdiff
  111.  
  112. rdiff examples
  113. --------------
  114.  
  115.    Suppose you receive mail from foo@bar.com asking for an update from
  116. release 1.2 to 1.4 of the tc compiler.  You have no such patches on
  117. hand, but with CVS that can easily be fixed with a command such as this:
  118.  
  119.      $ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
  120.      $$ Mail -s 'The patches you asked for' foo@bar.com
  121.  
  122.    Suppose you have made release 1.3, and forked a branch called
  123. `R_1_3fix' for bugfixes.  `R_1_3_1' corresponds to release 1.3.1, which
  124. was made some time ago.  Now, you want to see how much development has
  125. been done on the branch.  This command can be used:
  126.  
  127.      $ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
  128.      cvs rdiff: Diffing module-name
  129.      File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
  130.      File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
  131.      File bar.h,v changed from revision 1.29.2.1 to 1.2
  132.  
  133. 
  134. File: cvs.info,  Node: release,  Next: rtag,  Prev: rdiff,  Up: Invoking CVS
  135.  
  136. release--Indicate that a Module is no longer in use
  137. ===================================================
  138.  
  139.    * release [-d] directories...
  140.  
  141.    * Requires: Working directory.
  142.  
  143.    * Changes: Working directory, history log.
  144.  
  145.    This command is meant to safely cancel the effect of `cvs checkout'.
  146. Since CVS doesn't lock files, it isn't strictly necessary to use this
  147. command.  You can always simply delete your working directory, if you
  148. like; but you risk losing changes you may have forgotten, and you leave
  149. no trace in the CVS history file (*note history file::.) that you've
  150. abandoned your checkout.
  151.  
  152.    Use `cvs release' to avoid these problems.  This command checks that
  153. no uncommitted changes are present; that you are executing it from
  154. immediately above a CVS working directory; and that the repository
  155. recorded for your files is the same as the repository defined in the
  156. module database.
  157.  
  158.    If all these conditions are true, `cvs release' leaves a record of
  159. its execution (attesting to your intentionally abandoning your
  160. checkout) in the CVS history log.
  161.  
  162. * Menu:
  163.  
  164. * release options::             release options
  165. * release output::              release output
  166. * release examples::            release examples
  167.  
  168. 
  169. File: cvs.info,  Node: release options,  Next: release output,  Up: release
  170.  
  171. release options
  172. ---------------
  173.  
  174.    The `release' command supports one command option:
  175.  
  176. `-d'
  177.      Delete your working copy of the file if the release succeeds.  If
  178.      this flag is not given your files will remain in your working
  179.      directory.
  180.  
  181.      *Warning:*  The `release' command deletes all directories and
  182.      files recursively.  This has the very serious side-effect that any
  183.      directory that you have created inside your checked-out sources,
  184.      and not added to the repository (using the `add' command; *note
  185.      Adding files::.) will be silently deleted--even if it is non-empty!
  186.  
  187. 
  188. File: cvs.info,  Node: release output,  Next: release examples,  Prev: release options,  Up: release
  189.  
  190. release output
  191. --------------
  192.  
  193.    Before `release' releases your sources it will print a one-line
  194. message for any file that is not up-to-date.
  195.  
  196.    *Warning:*  Any new directories that you have created, but not added
  197. to the CVS directory hierarchy with the `add' command (*note Adding
  198. files::.) will be silently ignored (and deleted, if `-d' is specified),
  199. even if they contain files.
  200.  
  201. `U FILE'
  202.      There exists a newer revision of this file in the repository, and
  203.      you have not modified your local copy of the file.
  204.  
  205. `A FILE'
  206.      The file has been added to your private copy of the sources, but
  207.      has not yet been committed to the repository.  If you delete your
  208.      copy of the sources this file will be lost.
  209.  
  210. `R FILE'
  211.      The file has been removed from your private copy of the sources,
  212.      but has not yet been removed from the repository, since you have
  213.      not yet committed the removal.  *Note commit::.
  214.  
  215. `M FILE'
  216.      The file is modified in your working directory.  There might also
  217.      be a newer revision inside the repository.
  218.  
  219. `? FILE'
  220.      FILE is in your working directory, but does not correspond to
  221.      anything in the source repository, and is not in the list of files
  222.      for CVS to ignore (see the description of the `-I' option, and
  223.      *note cvsignore::.).  If you remove your working sources, this
  224.      file will be lost.
  225.  
  226.      Note that no warning message like this is printed for spurious
  227.      directories that CVS encounters.  The directory, and all its
  228.      contents, are silently ignored.
  229.  
  230. 
  231. File: cvs.info,  Node: release examples,  Prev: release output,  Up: release
  232.  
  233. release examples
  234. ----------------
  235.  
  236.    Release the module, and delete your local working copy of the files.
  237.  
  238.      $ cd ..         # You must stand immediately above the
  239.                      # sources when you issue `cvs release'.
  240.      $ cvs release -d tc
  241.      You have [0] altered files in this repository.
  242.      Are you sure you want to release (and delete) module `tc': y
  243.      $
  244.  
  245. 
  246. File: cvs.info,  Node: rtag,  Next: status,  Prev: release,  Up: Invoking CVS
  247.  
  248. rtag--Add a symbolic tag to a module
  249. ====================================
  250.  
  251.    * rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules...
  252.  
  253.    * Requires: repository.
  254.  
  255.    * Changes: repository.
  256.  
  257.    * Synonym: rfreeze
  258.  
  259.    You can use this command to assign symbolic tags to particular,
  260. explicitly specified source revisions in the repository.  `rtag' works
  261. directly on the repository contents (and requires no prior checkout).
  262. Use `tag' instead (*note tag::.), to base the selection of revisions on
  263. the contents of your working directory.
  264.  
  265.    If you attempt to use a tag name that already exists, CVS will
  266. complain and not overwrite that tag.  Use the `-F' option to force the
  267. new tag value.
  268.  
  269. * Menu:
  270.  
  271. * rtag options::                rtag options
  272.  
  273. 
  274. File: cvs.info,  Node: rtag options,  Up: rtag
  275.  
  276. rtag options
  277. ------------
  278.  
  279.    These standard options are supported by `rtag' (*note Common
  280. options::., for a complete description of them):
  281.  
  282. `-D DATE'
  283.      Tag the most recent revision no later than DATE.
  284.  
  285. `-f'
  286.      Only useful with the `-D DATE' or `-r TAG' flags.  If no matching
  287.      revision is found, use the most recent revision (instead of
  288.      ignoring the file).
  289.  
  290. `-F'
  291.      Overwrite an existing tag of the same name on a different
  292.      revision.  This option is new in CVS 1.4.  The old behavior is
  293.      matched by `cvs tag -F'.
  294.  
  295. `-l'
  296.      Local; run only in current working directory.
  297.  
  298. `-n'
  299.      Do not run any tag program that was specified with the `-t' flag
  300.      inside the `modules' file.  (*note modules::.).
  301.  
  302. `-R'
  303.      Commit directories recursively.  This is on by default.
  304.  
  305. `-r TAG'
  306.      Only tag those files that contain TAG.  This can be used to rename
  307.      a tag: tag only the files identified by the old tag, then delete
  308.      the old tag, leaving the new tag on exactly the same files as the
  309.      old tag.
  310.  
  311.    In addition to the above common options, these options are available:
  312.  
  313. `-a'
  314.      Use the `-a' option to have `rtag' look in the `Attic' (*note
  315.      Removing files::.) for removed files that contain the specified
  316.      tag.  The tag is removed from these files, which makes it
  317.      convenient to re-use a symbolic tag as development continues (and
  318.      files get removed from the up-coming distribution).
  319.  
  320. `-b'
  321.      Make the tag a branch tag.  *Note Branches::.
  322.  
  323. `-d'
  324.      Delete the tag instead of creating it.
  325.  
  326.      In general, tags (often the symbolic names of software
  327.      distributions) should not be removed, but the `-d' option is
  328.      available as a means to remove completely obsolete symbolic names
  329.      if necessary (as might be the case for an Alpha release, or if you
  330.      mistagged a module).
  331.  
  332. 
  333. File: cvs.info,  Node: status,  Next: tag,  Prev: rtag,  Up: Invoking CVS
  334.  
  335. status--Display status information on checked out files
  336. =======================================================
  337.  
  338.    * status [-lR] [-v] [files...]
  339.  
  340.    * Requires: working directory, repository.
  341.  
  342.    * Changes: nothing.
  343.  
  344.    Display a brief report on the current status of files with respect
  345. to the source repository.  For information on the basic output see
  346. *Note File status::.  For information on the `Sticky tag' and `Sticky
  347. date' output, see *Note Sticky tags::.  For information on the `Sticky
  348. options' output, see the `-k' option in *Note update options::.
  349.  
  350.    You can also use this command to determine the potential impact of a
  351. `cvs update' on your working source directory--but remember that things
  352. might change in the repository before you run `update'.
  353.  
  354. * Menu:
  355.  
  356. * status options::              status options
  357.  
  358. 
  359. File: cvs.info,  Node: status options,  Up: status
  360.  
  361. status options
  362. --------------
  363.  
  364.    These standard options are supported by `status' (*note Common
  365. options::., for a complete description of them):
  366.  
  367. `-l'
  368.      Local; run only in current working directory.
  369.  
  370. `-R'
  371.      Commit directories recursively.  This is on by default.
  372.  
  373.    There is one additional option:
  374.  
  375. `-v'
  376.      Verbose.  In addition to the information normally displayed, print
  377.      all symbolic tags, together with the numerical value of the
  378.      revision or branch they refer to.  For more information, see *Note
  379.      Tags::
  380.  
  381. 
  382. File: cvs.info,  Node: tag,  Next: update,  Prev: status,  Up: Invoking CVS
  383.  
  384. tag--Add a symbolic tag to checked out versions of files
  385. ========================================================
  386.  
  387.    * tag [-lR] [-b] [-c] [-d] symbolic_tag [files...]
  388.  
  389.    * Requires: working directory, repository.
  390.  
  391.    * Changes: repository.
  392.  
  393.    * Synonym: freeze
  394.  
  395.    Use this command to assign symbolic tags to the nearest repository
  396. versions to your working sources.  The tags are applied immediately to
  397. the repository, as with `rtag', but the versions are supplied
  398. implicitly by the CVS records of your working files' history rather than
  399. applied explicitly.
  400.  
  401.    One use for tags is to record a snapshot of the current sources when
  402. the software freeze date of a project arrives.  As bugs are fixed after
  403. the freeze date, only those changed sources that are to be part of the
  404. release need be re-tagged.
  405.  
  406.    The symbolic tags are meant to permanently record which revisions of
  407. which files were used in creating a software distribution.  The
  408. `checkout' and `update' commands allow you to extract an exact copy of
  409. a tagged release at any time in the future, regardless of whether files
  410. have been changed, added, or removed since the release was tagged.
  411.  
  412.    This command can also be used to delete a symbolic tag, or to create
  413. a branch.  See the options section below.
  414.  
  415.    If you attempt to use a tag name that already exists, CVS will
  416. complain and not overwrite that tag.  Use the `-F' option to force the
  417. new tag value.
  418.  
  419. * Menu:
  420.  
  421. * tag options::                 tag options
  422.  
  423. 
  424. File: cvs.info,  Node: tag options,  Up: tag
  425.  
  426. tag options
  427. -----------
  428.  
  429.    These standard options are supported by `tag' (*note Common
  430. options::., for a complete description of them):
  431.  
  432. `-F'
  433.      Overwrite an existing tag of the same name on a different
  434.      revision.  This option is new in CVS 1.4.  The old behavior is
  435.      matched by `cvs tag -F'.
  436.  
  437. `-l'
  438.      Local; run only in current working directory.
  439.  
  440. `-R'
  441.      Commit directories recursively.  This is on by default.
  442.  
  443.    Two special options are available:
  444.  
  445. `-b'
  446.      The -b option makes the tag a branch tag (*note Branches::.),
  447.      allowing concurrent, isolated development.  This is most useful
  448.      for creating a patch to a previously released software
  449.      distribution.
  450.  
  451. `-c'
  452.      The -c option checks that all files which are to be tagged are
  453.      unmodified.  This can be used to make sure that you can
  454.      reconstruct the current file contents.
  455.  
  456. `-d'
  457.      Delete a tag.
  458.  
  459.      If you use `cvs tag -d symbolic_tag', the symbolic tag you specify
  460.      is deleted instead of being added.  Warning: Be very certain of
  461.      your ground before you delete a tag; doing this permanently
  462.      discards some historical information, which may later turn out to
  463.      be valuable.
  464.  
  465. 
  466. File: cvs.info,  Node: update,  Prev: tag,  Up: Invoking CVS
  467.  
  468. update--Bring work tree in sync with repository
  469. ===============================================
  470.  
  471.    * update [-AdflPpR] [-d] [-r tag|-D date] files...
  472.  
  473.    * Requires: repository, working directory.
  474.  
  475.    * Changes: working directory.
  476.  
  477.    After you've run checkout to create your private copy of source from
  478. the common repository, other developers will continue changing the
  479. central source.  From time to time, when it is convenient in your
  480. development process, you can use the `update' command from within your
  481. working directory to reconcile your work with any revisions applied to
  482. the source repository since your last checkout or update.
  483.  
  484. * Menu:
  485.  
  486. * update options::              update options
  487. * update output::               update output
  488. * update examples::             update examples
  489.  
  490. 
  491. File: cvs.info,  Node: update options,  Next: update output,  Up: update
  492.  
  493. update options
  494. --------------
  495.  
  496.    These standard options are available with `update' (*note Common
  497. options::., for a complete description of them):
  498.  
  499. `-D date'
  500.      Use the most recent revision no later than DATE.  This option is
  501.      sticky, and implies `-P'.  See *Note Sticky tags::, for more
  502.      information on sticky tags/dates.
  503.  
  504. `-f'
  505.      Only useful with the `-D DATE' or `-r TAG' flags.  If no matching
  506.      revision is found, retrieve the most recent revision (instead of
  507.      ignoring the file).
  508.  
  509. `-k KFLAG'
  510.      Process RCS keywords according to KFLAG.  See co(1).  This option
  511.      is sticky; future updates of this file in this working directory
  512.      will use the same KFLAG.  The `status' command can be viewed to
  513.      see the sticky options.  *Note status::.
  514.  
  515. `-l'
  516.      Local; run only in current working directory.  *Note Recursive
  517.      behavior::.
  518.  
  519. `-P'
  520.      Prune empty directories.
  521.  
  522. `-p'
  523.      Pipe files to the standard output.
  524.  
  525. `-R'
  526.      Operate recursively.  This is on by default.  *Note Recursive
  527.      behavior::.
  528.  
  529. `-r tag'
  530.      Retrieve revision TAG.  This option is sticky, and implies `-P'.
  531.      See *Note Sticky tags::, for more information on sticky tags/dates.
  532.  
  533.    These special options are also available with `update'.
  534.  
  535. `-A'
  536.      Reset any sticky tags, dates, or `-k' options.  See *Note Sticky
  537.      tags::, for more information on sticky tags/dates.
  538.  
  539. `-d'
  540.      Create any directories that exist in the repository if they're
  541.      missing from the working directory.  Normally, `update' acts only
  542.      on directories and files that were already enrolled in your
  543.      working directory.
  544.  
  545.      This is useful for updating directories that were created in the
  546.      repository since the initial checkout; but it has an unfortunate
  547.      side effect.  If you deliberately avoided certain directories in
  548.      the repository when you created your working directory (either
  549.      through use of a module name or by listing explicitly the files
  550.      and directories you wanted on the command line), then updating
  551.      with `-d' will create those directories, which may not be what you
  552.      want.
  553.  
  554. `-I NAME'
  555.      Ignore files whose names match NAME (in your working directory)
  556.      during the update.  You can specify `-I' more than once on the
  557.      command line to specify several files to ignore.  Use `-I !' to
  558.      avoid ignoring any files at all.  *Note cvsignore::, for other
  559.      ways to make CVS ignore some files.
  560.  
  561. `-WSPEC'
  562.      Specify file names that should be filtered during update.  You can
  563.      use this option repeatedly.
  564.  
  565.      SPEC can be a file name pattern of the same type that you can
  566.      specify in the `.cvswrappers' file. *Note Wrappers::.
  567.  
  568. `-jREVISION'
  569.      With two `-j' options, merge changes from the revision specified
  570.      with the first `-j' option to the revision specified with the
  571.      second `j' option, into the working directory.
  572.  
  573.      With one `-j' option, merge changes from the ancestor revision to
  574.      the revision specified with the `-j' option, into the working
  575.      directory.  The ancestor revision is the common ancestor of the
  576.      revision which the working directory is based on, and the revision
  577.      specified in the `-j' option.
  578.  
  579.      In addition, each -j option can contain an optional date
  580.      specification which, when used with branches, can limit the chosen
  581.      revision to one within a specific date.  An optional date is
  582.      specified by adding a colon (:) to the tag:
  583.      `-jSYMBOLIC_TAG:DATE_SPECIFIER'.
  584.  
  585.      *Note Merging::.
  586.  
  587. 
  588. File: cvs.info,  Node: update output,  Next: update examples,  Prev: update options,  Up: update
  589.  
  590. update output
  591. -------------
  592.  
  593.    `update' and `checkout' keep you informed of its progress by
  594. printing a line for each file, preceded by one character indicating the
  595. status of the file:
  596.  
  597. `U FILE'
  598.      The file was brought up to date with respect to the repository.
  599.      This is done for any file that exists in the repository but not in
  600.      your source, and for files that you haven't changed but are not
  601.      the most recent versions available in the repository.
  602.  
  603. `A FILE'
  604.      The file has been added to your private copy of the sources, and
  605.      will be added to the source repository when you run `commit' on
  606.      the file.  This is a reminder to you that the file needs to be
  607.      committed.
  608.  
  609. `R FILE'
  610.      The file has been removed from your private copy of the sources,
  611.      and will be removed from the source repository when you run
  612.      `commit' on the file.  This is a reminder to you that the file
  613.      needs to be committed.
  614.  
  615. `M FILE'
  616.      The file is modified in  your  working  directory.
  617.  
  618.      `M' can indicate one of two states for a file you're working on:
  619.      either there were no modifications to the same file in the
  620.      repository, so that your file remains as you last saw it; or there
  621.      were modifications in the repository as well as in your copy, but
  622.      they were merged successfully, without conflict, in your working
  623.      directory.
  624.  
  625.      CVS will print some messages if it merges your work, and a backup
  626.      copy of your working file (as it looked before you ran `update')
  627.      will be made.  The exact name of that file is printed while
  628.      `update' runs.
  629.  
  630. `C FILE'
  631.      A conflict was detected while trying to merge your changes to FILE
  632.      with changes from the source repository.  FILE (the copy in your
  633.      working directory) is now the output of the rcsmerge(1) command on
  634.      the two revisions; an unmodified copy of your file is also in your
  635.      working directory, with the name `.#FILE.REVISION' where REVISION
  636.      is the RCS revision that your modified file started from.  Resolve
  637.      the conflict as described in *Note Conflicts example:: (Note that
  638.      some systems automatically purge files that begin with `.#' if
  639.      they have not been accessed for a few days.  If you intend to keep
  640.      a copy of your original file, it is a very good idea to rename
  641.      it.)  Under VMS, the file name starts with `__' rather than `.#'.
  642.  
  643. `? FILE'
  644.      FILE is in your working directory, but does not correspond to
  645.      anything in the source repository, and is not in the list of files
  646.      for CVS to ignore (see the description of the `-I' option, and
  647.      *note cvsignore::.).
  648.  
  649.      Note that no warning message like this is printed for spurious
  650.      directories that CVS encounters.  The directory, and all its
  651.      contents, are silently ignored.
  652.  
  653. 
  654. File: cvs.info,  Node: update examples,  Prev: update output,  Up: update
  655.  
  656. update examples
  657. ---------------
  658.  
  659.    The following line will display all files which are not up-to-date
  660. without actually change anything in your working directory.  It can be
  661. used to check what has been going on with the project.
  662.  
  663.      $ cvs -n -q update
  664.  
  665. 
  666. File: cvs.info,  Node: Administrative files,  Next: Environment variables,  Prev: Invoking CVS,  Up: Top
  667.  
  668. Reference manual for the Administrative files
  669. *********************************************
  670.  
  671.    Inside the repository, in the directory `$CVSROOT/CVSROOT', there
  672. are a number of supportive files for CVS.  You can use CVS in a limited
  673. fashion without any of them, but if they are set up properly they can
  674. help make life easier.  For a discussion of how to edit them, *Note
  675. Intro administrative files::.
  676.  
  677.    The most important of these files is the `modules' file, which
  678. defines the modules inside the repository.
  679.  
  680. * Menu:
  681.  
  682. * modules::                     Defining modules
  683. * Wrappers::                    Treat directories as files
  684. * commit files::                The commit support files
  685. * commitinfo::                  Pre-commit checking
  686. * editinfo::                    Specifying how log messages are created
  687. * loginfo::                     Where should log messages be sent?
  688. * rcsinfo::                     Templates for the log messages
  689. * cvsignore::                   Ignoring files via cvsignore
  690. * history file::                History information
  691. * Variables::                   Various variables are expanded
  692.  
  693. 
  694. File: cvs.info,  Node: modules,  Next: Wrappers,  Up: Administrative files
  695.  
  696. The modules file
  697. ================
  698.  
  699.    The `modules' file records your definitions of names for collections
  700. of source code.  CVS will use these definitions if you use CVS to
  701. update the modules file (use normal commands like `add', `commit', etc).
  702.  
  703.    The `modules' file may contain blank lines and comments (lines
  704. beginning with `#') as well as module definitions.  Long lines can be
  705. continued on the next line by specifying a backslash (`\') as the last
  706. character on the line.
  707.  
  708.    A module definition is a single line of the `modules' file, in
  709. either of two formats.  In both cases, MNAME represents the symbolic
  710. module name, and the remainder of the line is its definition.
  711.  
  712. `MNAME -a ALIASES...'
  713.      This represents the simplest way of defining a module MNAME.  The
  714.      `-a' flags the definition as a simple alias: CVS will treat any
  715.      use of MNAME (as a command argument) as if the list of names
  716.      ALIASES had been specified instead.  ALIASES may contain either
  717.      other module names or paths.  When you use paths in aliases,
  718.      `checkout' creates all intermediate directories in the working
  719.      directory, just as if the path had been specified explicitly in
  720.      the CVS arguments.
  721.  
  722. `MNAME [ options ] DIR [ FILES... ] [ &MODULE... ]'
  723.      In the simplest case, this form of module definition reduces to
  724.      `MNAME DIR'.  This defines all the files in directory DIR as
  725.      module mname.  DIR is a relative path (from `$CVSROOT') to a
  726.      directory of source in the source repository.  In this case, on
  727.      checkout, a single directory called MNAME is created as a working
  728.      directory; no intermediate directory levels are used by default,
  729.      even if DIR was a path involving several directory levels.
  730.  
  731.      By explicitly specifying files in the module definition after DIR,
  732.      you can select particular files from directory DIR.  The sample
  733.      definition for `modules' is an example of a module defined with a
  734.      single file from a particular directory.  Here is another example:
  735.  
  736.           m4test  unsupported/gnu/m4 foreach.m4 forloop.m4
  737.  
  738.      With this definition, executing `cvs checkout m4test' will create
  739.      a single working directory `m4test' containing the two files
  740.      listed, which both come from a common directory several levels deep
  741.      in the CVS source repository.
  742.  
  743.      A module definition can refer to other modules by including
  744.      `&MODULE' in its definition.  `checkout' creates a subdirectory
  745.      for each such module, in your working directory.
  746.  
  747.     `-d NAME'
  748.           Name the working directory something other than the module
  749.           name.
  750.  
  751.     `-e PROG'
  752.           Specify a program PROG to run whenever files in a module are
  753.           exported.  PROG runs with a single argument, the module name.
  754.  
  755.     `-i PROG'
  756.           Specify a program PROG to run whenever files in a module are
  757.           committed.  PROG runs with a single argument, the full
  758.           pathname of the affected directory in a source repository.
  759.           The `commitinfo', `loginfo', and `editinfo' files provide
  760.           other ways to call a program on commit.
  761.  
  762.     `-o PROG'
  763.           Specify a program PROG to run whenever files in a module are
  764.           checked out.  PROG runs with a single argument, the module
  765.           name.
  766.  
  767.     `-s STATUS'
  768.           Assign a status to the module.  When the module file is
  769.           printed with `cvs checkout -s' the modules are sorted
  770.           according to primarily module status, and secondarily
  771.           according to the module name.  This option has no other
  772.           meaning.  You can use this option for several things besides
  773.           status: for instance, list the person that is responsible for
  774.           this module.
  775.  
  776.     `-t PROG'
  777.           Specify a program PROG to run whenever files in a module are
  778.           tagged with `rtag'.  PROG runs with two arguments: the module
  779.           name and the symbolic tag specified to `rtag'.  There is no
  780.           way to specify a program to run when `tag' is executed.
  781.  
  782.     `-u PROG'
  783.           Specify a program PROG to run whenever `cvs update' is
  784.           executed from the top-level directory of the checked-out
  785.           module.  PROG runs with a single argument, the full path to
  786.           the source repository for this module.
  787.  
  788. 
  789. File: cvs.info,  Node: Wrappers,  Next: commit files,  Prev: modules,  Up: Administrative files
  790.  
  791. The cvswrappers file
  792. ====================
  793.  
  794.    Wrappers allow you to set a hook which transforms files on their way
  795. in and out of CVS.  Most or all of the wrappers features do not work
  796. with client/server CVS.
  797.  
  798.    The file `cvswrappers' defines the script that will be run on a file
  799. when its name matches a regular expresion. There are two scripts that
  800. can be run on a file or directory. One script is executed on the
  801. file/directory before being checked into the repository (this is denoted
  802. with the `-t' flag) and the other when the file is checked out of the
  803. repository (this is denoted with the `-f' flag)
  804.  
  805.    The `cvswrappers' also has a `-m' option to specify the merge
  806. methodology that should be used when the file is updated.  `MERGE'
  807. means the usual CVS behavior: try to merge the files (this generally
  808. will not work for binary files).  `COPY' means that `cvs update' will
  809. merely copy one version over the other, and require the user using
  810. mechanisms outside CVS, to insert any necessary changes.  The `-m'
  811. wrapper option only affects behavior when merging is done on update; it
  812. does not affect how files are stored.  See *Note Binary files::, for
  813. more on binary files.
  814.  
  815.    The basic format of the file `cvswrappers' is:
  816.  
  817.      wildcard     [option value][option value]...
  818.      
  819.      where option is one of
  820.      -f           from cvs filter         value: path to filter
  821.      -t           to cvs filter           value: path to filter
  822.      -m           update methodology      value: MERGE or COPY
  823.      -k           keyword expansion       value: expansion mode
  824.      
  825.      and value is a single-quote delimited value.
  826.  
  827.      *.nib    -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
  828.      *.c      -t 'indent %s %s'
  829.  
  830. The above example of a `cvswrappers' file states that all
  831. files/directories that end with a `.nib' should be filtered with the
  832. `wrap' program before checking the file into the repository. The file
  833. should be filtered though the `unwrap' program when the file is checked
  834. out of the repository. The `cvswrappers' file also states that a `COPY'
  835. methodology should be used when updating the files in the repository
  836. (that is no merging should be performed).
  837.  
  838.    The last example line says that all files that end with a `*.c'
  839. should be filtered with `indent' before being checked into the
  840. repository. Unlike the previous example no filtering of the `*.c' file
  841. is done when it is checked out of the repository.
  842.  
  843. The `-t' filter is called with two arguments, the first is the name of
  844. the file/directory to filter and the second is the pathname to where
  845. the resulting filtered file should be placed.
  846.  
  847. The `-f' filter is called with one argument, which is the name of the
  848. file to filter from. The end result of this filter will be a file in
  849. the users directory that they can work on as they normally would.
  850.  
  851.    For another example, the following command imports a directory,
  852. treating files whose name ends in `.exe' as binary:
  853.  
  854.      cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
  855.  
  856. 
  857. File: cvs.info,  Node: commit files,  Next: commitinfo,  Prev: Wrappers,  Up: Administrative files
  858.  
  859. The commit support files
  860. ========================
  861.  
  862.    The `-i' flag in the `modules' file can be used to run a certain
  863. program whenever files are committed (*note modules::.).  The files
  864. described in this section provide other, more flexible, ways to run
  865. programs whenever something is committed.
  866.  
  867.    There are three kind of programs that can be run on commit.  They
  868. are specified in files in the repository, as described below.  The
  869. following table summarizes the file names and the purpose of the
  870. corresponding programs.
  871.  
  872. `commitinfo'
  873.      The program is responsible for checking that the commit is
  874.      allowed.  If it exits with a non-zero exit status the commit will
  875.      be aborted.
  876.  
  877. `editinfo'
  878.      The specified program is used to edit the log message, and
  879.      possibly verify that it contains all required fields.  This is
  880.      most useful in combination with the `rcsinfo' file, which can hold
  881.      a log message template (*note rcsinfo::.).
  882.  
  883. `loginfo'
  884.      The specified program is called when the commit is complete.  It
  885.      receives the log message and some additional information and can
  886.      store the log message in a file, or mail it to appropriate
  887.      persons, or maybe post it to a local newsgroup, or...  Your
  888.      imagination is the limit!
  889.  
  890. * Menu:
  891.  
  892. * syntax::                      The common syntax
  893.  
  894. 
  895. File: cvs.info,  Node: syntax,  Up: commit files
  896.  
  897. The common syntax
  898. -----------------
  899.  
  900.    The four files `commitinfo', `loginfo', `rcsinfo' and `editinfo' all
  901. have a common format.  The purpose of the files are described later on.
  902. The common syntax is described here.
  903.  
  904.    Each line contains the following:
  905.    * A regular expression
  906.  
  907.    * A whitespace separator--one or more spaces and/or tabs.
  908.  
  909.    * A file name or command-line template.
  910.  
  911. Blank lines are ignored.  Lines that start with the character `#' are
  912. treated as comments.  Long lines unfortunately can *not* be broken in
  913. two parts in any way.
  914.  
  915.    The first regular expression that matches the current directory name
  916. in the repository is used.  The rest of the line is used as a file name
  917. or command-line as appropriate.
  918.  
  919. 
  920. File: cvs.info,  Node: commitinfo,  Next: editinfo,  Prev: commit files,  Up: Administrative files
  921.  
  922. Commitinfo
  923. ==========
  924.  
  925.    The `commitinfo' file defines programs to execute whenever `cvs
  926. commit' is about to execute.  These programs are used for pre-commit
  927. checking to verify that the modified, added and removed files are really
  928. ready to be committed.  This could be used, for instance, to verify
  929. that the changed files conform to to your site's standards for coding
  930. practice.
  931.  
  932.    As mentioned earlier, each line in the `commitinfo' file consists of
  933. a regular expression and a command-line template.  The template can
  934. include a program name and any number of arguments you wish to supply
  935. to it.  The full path to the current source repository is appended to
  936. the template, followed by the file names of any files involved in the
  937. commit (added, removed, and modified files).
  938.  
  939.    The first line with a regular expression matching the relative path
  940. to the module will be used.  If the command returns a non-zero exit
  941. status the commit will be aborted.
  942.  
  943.    If the repository name does not match any of the regular expressions
  944. in this file, the `DEFAULT' line is used, if it is specified.
  945.  
  946.    All occurances of the name `ALL' appearing as a regular expression
  947. are used in addition to the first matching regular expression or the
  948. name `DEFAULT'.
  949.  
  950.    Note: when CVS is accessing a remote repository, `commitinfo' will
  951. be run on the *remote* (i.e., server) side, not the client side (*note
  952. Remote repositories::.).
  953.  
  954. 
  955. File: cvs.info,  Node: editinfo,  Next: loginfo,  Prev: commitinfo,  Up: Administrative files
  956.  
  957. Editinfo
  958. ========
  959.  
  960.    If you want to make sure that all log messages look the same way,
  961. you can use the `editinfo' file to specify a program that is used to
  962. edit the log message.  This program could be a custom-made editor that
  963. always enforces a certain style of the log message, or maybe a simple
  964. shell script that calls an editor, and checks that the entered message
  965. contains the required fields.
  966.  
  967.    If no matching line is found in the `editinfo' file, the editor
  968. specified in the environment variable `$CVSEDITOR' is used instead.  If
  969. that variable is not set, then the environment variable `$EDITOR' is
  970. used instead.  If that variable is not set a precompiled default,
  971. normally `vi', will be used.
  972.  
  973.    The `editinfo' file is often most useful together with the `rcsinfo'
  974. file, which can be used to specify a log message template.
  975.  
  976.    Each line in the `editinfo' file consists of a regular expression
  977. and a command-line template.  The template must include a program name,
  978. and can include any number of arguments.  The full path to the current
  979. log message template file is appended to the template.
  980.  
  981.    One thing that should be noted is that the `ALL' keyword is not
  982. supported.  If more than one matching line is found, the first one is
  983. used.  This can be useful for specifying a default edit script in a
  984. module, and then overriding it in a subdirectory.
  985.  
  986.    If the repository name does not match any of the regular expressions
  987. in this file, the `DEFAULT' line is used, if it is specified.
  988.  
  989.    If the edit script exits with a non-zero exit status, the commit is
  990. aborted.
  991.  
  992.    Note: when CVS is accessing a remote repository, or when the `-m' or
  993. `-F' options to `cvs commit' are used, `editinfo' will not be consulted.
  994. There is no good workaround for this.
  995.  
  996. * Menu:
  997.  
  998. * editinfo example::            Editinfo example
  999.  
  1000. 
  1001. File: cvs.info,  Node: editinfo example,  Up: editinfo
  1002.  
  1003. Editinfo example
  1004. ----------------
  1005.  
  1006.    The following is a little silly example of a `editinfo' file,
  1007. together with the corresponding `rcsinfo' file, the log message
  1008. template and an editor script.  We begin with the log message template.
  1009. We want to always record a bug-id number on the first line of the log
  1010. message.  The rest of log message is free text.  The following template
  1011. is found in the file `/usr/cvssupport/tc.template'.
  1012.  
  1013.      BugId:
  1014.  
  1015.    The script `/usr/cvssupport/bugid.edit' is used to edit the log
  1016. message.
  1017.  
  1018.      #!/bin/sh
  1019.      #
  1020.      #       bugid.edit filename
  1021.      #
  1022.      #  Call $EDITOR on FILENAME, and verify that the
  1023.      #  resulting file contains a valid bugid on the first
  1024.      #  line.
  1025.      if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
  1026.      if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
  1027.      $CVSEDITOR $1
  1028.      until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
  1029.      do  echo -n  "No BugId found.  Edit again? ([y]/n)"
  1030.          read ans
  1031.          case ${ans} in
  1032.              n*) exit 1;;
  1033.          esac
  1034.          $CVSEDITOR $1
  1035.      done
  1036.  
  1037.    The `editinfo' file contains this line:
  1038.  
  1039.      ^tc     /usr/cvssupport/bugid.edit
  1040.  
  1041.    The `rcsinfo' file contains this line:
  1042.  
  1043.      ^tc     /usr/cvssupport/tc.template
  1044.  
  1045. 
  1046. File: cvs.info,  Node: loginfo,  Next: rcsinfo,  Prev: editinfo,  Up: Administrative files
  1047.  
  1048. Loginfo
  1049. =======
  1050.  
  1051.    The `loginfo' file is used to control where `cvs commit' log
  1052. information is sent.  The first entry on a line is a regular expression
  1053. which is tested against the directory that the change is being made to,
  1054. relative to the `$CVSROOT'.  If a match is found, then the remainder of
  1055. the line is a filter program that should expect log information on its
  1056. standard input.
  1057.  
  1058.    The filter program may use one and only one % modifier (a la
  1059. printf).  If `%s' is specified in the filter program, a brief title is
  1060. included (enclosed in single quotes) showing the modified file names.
  1061.  
  1062.    If the repository name does not match any of the regular expressions
  1063. in this file, the `DEFAULT' line is used, if it is specified.
  1064.  
  1065.    All occurances of the name `ALL' appearing as a regular expression
  1066. are used in addition to the first matching regular expression or
  1067. `DEFAULT'.
  1068.  
  1069.    The first matching regular expression is used.
  1070.  
  1071.    *Note commit files::, for a description of the syntax of the
  1072. `loginfo' file.
  1073.  
  1074.    Note: when CVS is accessing a remote repository, `loginfo' will be
  1075. run on the *remote* (i.e., server) side, not the client side (*note
  1076. Remote repositories::.).
  1077.  
  1078. * Menu:
  1079.  
  1080. * loginfo example::             Loginfo example
  1081. * Keeping a checked out copy::  Updating a tree on every checkin
  1082.  
  1083. 
  1084. File: cvs.info,  Node: loginfo example,  Next: Keeping a checked out copy,  Up: loginfo
  1085.  
  1086. Loginfo example
  1087. ---------------
  1088.  
  1089.    The following `loginfo' file, together with the tiny shell-script
  1090. below, appends all log messages to the file
  1091. `$CVSROOT/CVSROOT/commitlog', and any commits to the administrative
  1092. files (inside the `CVSROOT' directory) are also logged in
  1093. `/usr/adm/cvsroot-log'.
  1094.  
  1095.      ALL             /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog
  1096.      ^CVSROOT        /usr/local/bin/cvs-log /usr/adm/cvsroot-log
  1097.  
  1098.    The shell-script `/usr/local/bin/cvs-log' looks like this:
  1099.  
  1100.      #!/bin/sh
  1101.      (echo "-----------------------------------------------------------------";
  1102.       echo -n $USER"  ";
  1103.       date;
  1104.       echo;
  1105.       sed '1s+'${CVSROOT}'++') >> $1
  1106.  
  1107. 
  1108. File: cvs.info,  Node: Keeping a checked out copy,  Prev: loginfo example,  Up: loginfo
  1109.  
  1110. Keeping a checked out copy
  1111. --------------------------
  1112.  
  1113.    It is often useful to maintain a directory tree which contains files
  1114. which correspond to the latest version in the repository.  For example,
  1115. other developers might want to refer to the latest sources without
  1116. having to check them out, or you might be maintaining a web site with
  1117. CVS and want every checkin to cause the files used by the web server to
  1118. be updated.
  1119.  
  1120.    The way to do this is by having loginfo invoke `cvs update'.  Doing
  1121. so in the naive way will cause a problem with locks, so the `cvs update'
  1122. must be run in the background.  Here is an example (this should all be
  1123. on one line):
  1124.  
  1125.      ^cyclic-pages        (date; cat; (sleep 2; cd /u/www/local-docs;
  1126.       cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
  1127.  
  1128.    This will cause checkins to repository directories starting with
  1129. `cyclic-pages' to update the checked out tree in `/u/www/local-docs'.
  1130.  
  1131. 
  1132. File: cvs.info,  Node: rcsinfo,  Next: cvsignore,  Prev: loginfo,  Up: Administrative files
  1133.  
  1134. Rcsinfo
  1135. =======
  1136.  
  1137.    The `rcsinfo' file can be used to specify a form to edit when
  1138. filling out the commit log.  The `rcsinfo' file has a syntax similar to
  1139. the `editinfo', `commitinfo' and `loginfo' files.  *Note syntax::.
  1140. Unlike the other files the second part is *not* a command-line
  1141. template.  Instead, the part after the regular expression should be a
  1142. full pathname to a file containing the log message template.
  1143.  
  1144.    If the repository name does not match any of the regular expressions
  1145. in this file, the `DEFAULT' line is used, if it is specified.
  1146.  
  1147.    All occurances of the name `ALL' appearing as a regular expression
  1148. are used in addition to the first matching regular expression or
  1149. `DEFAULT'.
  1150.  
  1151.    The log message template will be used as a default log message.  If
  1152. you specify a log message with `cvs commit -m MESSAGE' or `cvs commit -f
  1153. FILE' that log message will override the template.
  1154.  
  1155.    *Note editinfo example::, for an example `rcsinfo' file.
  1156.  
  1157.    When CVS is accessing a remote repository, the contents of `rcsinfo'
  1158. at the time a directory is first checked out will specify a template
  1159. which does not then change.  If you edit `rcsinfo' or its templates,
  1160. you may need to check out a new working directory.
  1161.  
  1162. 
  1163. File: cvs.info,  Node: cvsignore,  Next: history file,  Prev: rcsinfo,  Up: Administrative files
  1164.  
  1165. Ignoring files via cvsignore
  1166. ============================
  1167.  
  1168.    There are certain file names that frequently occur inside your
  1169. working copy, but that you don't want to put under CVS control.
  1170. Examples are all the object files that you get while you compile your
  1171. sources.  Normally, when you run `cvs update', it prints a line for
  1172. each file it encounters that it doesn't know about (*note update
  1173. output::.).
  1174.  
  1175.    CVS has a list of files (or sh(1) file name patterns) that it should
  1176. ignore while running `update', `import' and `release'.  This list is
  1177. constructed in the following way.
  1178.  
  1179.    * The list is initialized to include certain file name patterns:
  1180.      names associated with CVS administration, or with other common
  1181.      source control systems; common names for patch files, object files,
  1182.      archive files, and editor backup files; and other names that are
  1183.      usually artifacts of assorted utilities.  Currently, the default
  1184.      list of ignored file name patterns is:
  1185.  
  1186.               RCS     SCCS    CVS     CVS.adm
  1187.               RCSLOG  cvslog.*
  1188.               tags    TAGS
  1189.               .make.state     .nse_depinfo
  1190.               *~      #*      .#*     ,*      _$*     *$
  1191.               *.old   *.bak   *.BAK   *.orig  *.rej   .del-*
  1192.               *.a     *.olb   *.o     *.obj   *.so    *.exe
  1193.               *.Z     *.elc   *.ln
  1194.               core
  1195.  
  1196.    * The per-repository list in `$CVSROOT/CVSROOT/cvsignore' is
  1197.      appended to the list, if that file exists.
  1198.  
  1199.    * The per-user list in `.cvsignore' in your home directory is
  1200.      appended to the list, if it exists.
  1201.  
  1202.    * Any entries in the environment variable `$CVSIGNORE' is appended
  1203.      to the list.
  1204.  
  1205.    * Any `-I' options given to CVS is appended.
  1206.  
  1207.    * As CVS traverses through your directories, the contents of any
  1208.      `.cvsignore' will be appended to the list.  The patterns found in
  1209.      `.cvsignore' are only valid for the directory that contains them,
  1210.      not for any sub-directories.
  1211.  
  1212.    In any of the 5 places listed above, a single exclamation mark (`!')
  1213. clears the ignore list.  This can be used if you want to store any file
  1214. which normally is ignored by CVS.
  1215.  
  1216. 
  1217. File: cvs.info,  Node: history file,  Next: Variables,  Prev: cvsignore,  Up: Administrative files
  1218.  
  1219. The history file
  1220. ================
  1221.  
  1222.    The file `$CVSROOT/CVSROOT/history' is used to log information for
  1223. the `history' command (*note history::.).  This file must be created to
  1224. turn on logging.  This is done automatically if the `cvs init' command
  1225. is used to set up the repository (*note Creating a repository::.).
  1226.  
  1227.    The file format of the `history' file is documented only in comments
  1228. in the CVS source code, but generally programs should use the `cvs
  1229. history' command to access it anyway, in case the format changes with
  1230. future releases of CVS.
  1231.  
  1232. 
  1233. File: cvs.info,  Node: Variables,  Prev: history file,  Up: Administrative files
  1234.  
  1235. Expansions in administrative files
  1236. ==================================
  1237.  
  1238.    Sometimes in writing an administrative file, you might want the file
  1239. to be able to know various things based on environment CVS is running
  1240. in.  There are several mechanisms to do that.
  1241.  
  1242.    To find the home directory of the user running CVS (from the `HOME'
  1243. environment variable), use `~' followed by `/' or the end of the line.
  1244. Likewise for the home directory of USER, use `~USER'.  These variables
  1245. are expanded on the server machine, and don't get any resonable
  1246. expansion if pserver (*note Password authenticated::.) is in used;
  1247. therefore user variables (see below) may be a better choice to
  1248. customize behavior based on the user running CVS.
  1249.  
  1250.    One may want to know about various pieces of information internal to
  1251. CVS.  A CVS internal variable has the syntax `${VARIABLE}', where
  1252. VARIABLE starts with a letter and consists of alphanumberic characters
  1253. and `_'.  If the character following VARIABLE is a non-alphanumeric
  1254. character other than `_', the `{' and `}' can be omitted.  The CVS
  1255. internal variables are:
  1256.  
  1257. `CVSROOT'
  1258.      This is the value of the CVS root in use.  *Note Repository::, for
  1259.      a description of the various ways to specify this.
  1260.  
  1261. `RCSBIN'
  1262.      This is the value CVS is using for where to find RCS binaries.
  1263.      *Note Global options::, for a description of how to specify this.
  1264.  
  1265. `CVSEDITOR'
  1266. `VISUAL'
  1267. `EDITOR'
  1268.      These all expand to the same value, which is the editor that CVS
  1269.      is using.  *Note Global options::, for how to specify this.
  1270.  
  1271. `USER'
  1272.      Username of the user running CVS (on the CVS server machine).
  1273.  
  1274.    If you want to pass a value to the administrative files which the
  1275. user that is running CVS can specify, use a user variable.  To expand a
  1276. user variable, the administrative file contains `${=VARIABLE}'.  To set
  1277. a user variable, specify the global option `-s' to CVS, with argument
  1278. `VARIABLE=VALUE'.  It may be particularly useful to specify this option
  1279. via `.cvsrc' (*note ~/.cvsrc::.).
  1280.  
  1281.    For example, if you want the administrative file to refer to a test
  1282. directory you might create a user variable `TESTDIR'.  Then if CVS is
  1283. invoked as `cvs -s TESTDIR=/work/local/tests', and the administrative
  1284. file contains `sh ${=TESTDIR}/runtests', then that string is expanded
  1285. to `sh /work/local/tests/runtests'.
  1286.  
  1287.    All other strings containing `$' are reserved; there is no way to
  1288. quote a `$' character so that `$' represents itself.
  1289.  
  1290.