home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cvs1929.zip / cvs / book / cvs.INF (.txt) < prev    next >
OS/2 Help File  |  1998-08-02  |  299KB  |  8,777 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. -Preface- ΓòÉΓòÉΓòÉ
  3.  
  4. Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994 Free 
  5. Software Foundation, Inc. 
  6.  
  7. Permission is granted to make and distribute verbatim copies of this manual 
  8. provided the copyright notice and this permission notice are preserved on all 
  9. copies. 
  10.  
  11. Permission is granted to copy and distribute modified versions of this manual 
  12. under the conditions for verbatim copying, provided also that the entire 
  13. resulting derived work is distributed under the terms of a permission notice 
  14. identical to this one. 
  15.  
  16. Permission is granted to copy and distribute translations of this manual into 
  17. another language, under the above conditions for modified versions, except that 
  18. this permission notice may be stated in a translation approved by the Free 
  19. Software Foundation. 
  20.  
  21.  
  22. ΓòÉΓòÉΓòÉ 2. Overview ΓòÉΓòÉΓòÉ
  23.  
  24.  This chapter is for people who have never used CVS, and perhaps have never 
  25.  used version control software before. 
  26.  
  27.  If you are already familiar with CVS and are just trying to learn a particular 
  28.  feature or remember a certain command, you can probably skip everything here. 
  29.  
  30.  What is CVS?                  What you can do with CVS 
  31.  What is CVS not?              Problems CVS doesn't try to solve 
  32.  A sample session              A tour of basic CVS usage 
  33.  
  34.  
  35. ΓòÉΓòÉΓòÉ 2.1. What is CVS? ΓòÉΓòÉΓòÉ
  36.  
  37.  CVS is a version control system.  Using it, you can record the history of your 
  38.  source files. 
  39.  
  40.  For example, bugs sometimes creep in when software is modified, and you might 
  41.  not detect the bug until a long time after you make the modification. With 
  42.  CVS, you can easily retrieve old versions to see exactly which change caused 
  43.  the bug.  This can sometimes be a big help. 
  44.  
  45.  You could of course save every version of every file you have ever created. 
  46.  This would however waste an enormous amount of disk space.  CVS stores all the 
  47.  versions of a file in a single file in a clever way that only stores the 
  48.  differences between versions. 
  49.  
  50.  CVS also helps you if you are part of a group of people working on the same 
  51.  project.  It is all too easy to overwrite each others' changes unless you are 
  52.  extremely careful. Some editors, like GNU Emacs, try to make sure that the 
  53.  same file is never modified by two people at the same time.  Unfortunately, if 
  54.  someone is using another editor, that safeguard will not work.  CVS solves 
  55.  this problem by insulating the different developers from each other.  Every 
  56.  developer works in his own directory, and CVS merges the work when each 
  57.  developer is done. 
  58.  
  59.  CVS started out as a bunch of shell scripts written by Dick Grune, posted to 
  60.  the newsgroup comp.sources.unix in the volume 6 release of December, 1986. 
  61.  While no actual code from these shell scripts is present in the current 
  62.  version of CVS much of the CVS conflict resolution algorithms come from them. 
  63.  
  64.  In April, 1989, Brian Berliner designed and coded CVS. Jeff Polk later helped 
  65.  Brian with the design of the CVS module and vendor branch support. 
  66.  
  67.  You can get CVS in a variety of ways, including free download from the 
  68.  internet.  For more information on downloading CVS and other CVS topics, see: 
  69.  
  70.                       http://www.cyclic.com/
  71.                       http://www.loria.fr/~molli/cvs-index.html
  72.  
  73.  There is a mailing list, known as info-cvs, devoted to CVS.  To subscribe or 
  74.  unsubscribe write to info-cvs-request@gnu.org. If you prefer a usenet group, 
  75.  the right group is comp.software.config-mgmt which is for CVS discussions 
  76.  (along with other configuration management systems).  In the future, it might 
  77.  be possible to create a comp.software.config-mgmt.cvs, but probably only if 
  78.  there is sufficient CVS traffic on comp.software.config-mgmt. You can also 
  79.  subscribe to the bug-cvs mailing list, described in more detail in BUGS.  To 
  80.  subscribe send mail to bug-cvs-request@gnu.org. 
  81.  
  82.  
  83. ΓòÉΓòÉΓòÉ 2.2. What is CVS not? ΓòÉΓòÉΓòÉ
  84.  
  85.  CVS can do a lot of things for you, but it does not try to be everything for 
  86.  everyone. 
  87.  
  88.  CVS is not a build system. 
  89.            Though the structure of your repository and modules file interact 
  90.            with your build system (e.g. 'Makefile's), they are essentially 
  91.            independent. 
  92.  
  93.            CVS does not dictate how you build anything.  It merely stores files 
  94.            for retrieval in a tree structure you devise. 
  95.  
  96.            CVS does not dictate how to use disk space in the checked out 
  97.            working directories.  If you write your 'Makefile's or scripts in 
  98.            every directory so they have to know the relative positions of 
  99.            everything else, you wind up requiring the entire repository to be 
  100.            checked out. 
  101.  
  102.            If you modularize your work, and construct a build system that will 
  103.            share files (via links, mounts, VPATH in 'Makefile's, etc.), you can 
  104.            arrange your disk usage however you like. 
  105.  
  106.            But you have to remember that any such system is a lot of work to 
  107.            construct and maintain.  CVS does not address the issues involved. 
  108.  
  109.            Of course, you should place the tools created to support such a 
  110.            build system (scripts, 'Makefile's, etc) under CVS. 
  111.  
  112.            Figuring out what files need to be rebuilt when something changes 
  113.            is, again, something to be handled outside the scope of CVS.  One 
  114.            traditional approach is to use make for building, and use some 
  115.            automated tool for generating the dependencies which make uses. 
  116.  
  117.            See Builds, for more information on doing builds in conjunction with 
  118.            CVS. 
  119.  
  120.  CVS is not a substitute for management. 
  121.            Your managers and project leaders are expected to talk to you 
  122.            frequently enough to make certain you are aware of schedules, merge 
  123.            points, branch names and release dates.  If they don't, CVS can't 
  124.            help. 
  125.  
  126.            CVS is an instrument for making sources dance to your tune.  But you 
  127.            are the piper and the composer.  No instrument plays itself or 
  128.            writes its own music. 
  129.  
  130.  CVS is not a substitute for developer communication. 
  131.            When faced with conflicts within a single file, most developers 
  132.            manage to resolve them without too much effort.  But a more general 
  133.            definition of ``conflict'' includes problems too difficult to solve 
  134.            without communication between developers. 
  135.  
  136.            CVS cannot determine when simultaneous changes within a single file, 
  137.            or across a whole collection of files, will logically conflict with 
  138.            one another.  Its concept of a conflict is purely textual, arising 
  139.            when two changes to the same base file are near enough to spook the 
  140.            merge (i.e. diff3) command. 
  141.  
  142.            CVS does not claim to help at all in figuring out non-textual or 
  143.            distributed conflicts in program logic. 
  144.  
  145.            For example: Say you change the arguments to function X defined in 
  146.            file 'A'.  At the same time, someone edits file 'B', adding new 
  147.            calls to function X using the old arguments.  You are outside the 
  148.            realm of CVS's competence. 
  149.  
  150.            Acquire the habit of reading specs and talking to your peers. 
  151.  
  152.  CVS does not have change control 
  153.            Change control refers to a number of things.  First of all it can 
  154.            mean bug-tracking, that is being able to keep a database of reported 
  155.            bugs and the status of each one (is it fixed?  in what release?  has 
  156.            the bug submitter agreed that it is fixed?).  For interfacing CVS to 
  157.            an external bug-tracking system, see the 'rcsinfo' and 'verifymsg' 
  158.            files (see Administrative files). 
  159.  
  160.            Another aspect of change control is keeping track of the fact that 
  161.            changes to several files were in fact changed together as one 
  162.            logical change.  If you check in several files in a single cvs 
  163.            commit operation, CVS then forgets that those files were checked in 
  164.            together, and the fact that they have the same log message is the 
  165.            only thing tying them together.  Keeping a GNU style 'ChangeLog' can 
  166.            help somewhat. Another aspect of change control, in some systems, is 
  167.            the ability to keep track of the status of each change.  Some 
  168.            changes have been written by a developer, others have been reviewed 
  169.            by a second developer, and so on.  Generally, the way to do this 
  170.            with CVS is to generate a diff (using cvs diff or diff) and email it 
  171.            to someone who can then apply it using the patch utility.  This is 
  172.            very flexible, but depends on mechanisms outside CVS to make sure 
  173.            nothing falls through the cracks. 
  174.  
  175.  CVS is not an automated testing program 
  176.            It should be possible to enforce mandatory use of a testsuite using 
  177.            the commitinfo file.  I haven't heard a lot about projects trying to 
  178.            do that or whether there are subtle gotchas, however. 
  179.  
  180.  CVS does not have a builtin process model 
  181.            Some systems provide ways to ensure that changes or releases go 
  182.            through various steps, with various approvals as needed.  Generally, 
  183.            one can accomplish this with CVS but it might be a little more work. 
  184.            In some cases you'll want to use the 'commitinfo', 'loginfo', 
  185.            'rcsinfo', or 'verifymsg' files, to require that certain steps be 
  186.            performed before cvs will allow a checkin.  Also consider whether 
  187.            features such as branches and tags can be used to perform tasks such 
  188.            as doing work in a development tree and then merging certain changes 
  189.            over to a stable tree only once they have been proven. 
  190.  
  191.  
  192. ΓòÉΓòÉΓòÉ 2.3. A sample session ΓòÉΓòÉΓòÉ
  193.  
  194.  As a way of introducing CVS, we'll go through a typical work-session using 
  195.  CVS.  The first thing to understand is that CVS stores all files in a 
  196.  centralized repository (see Repository); this section assumes that a 
  197.  repository is set up. Suppose you are working on a simple compiler.  The 
  198.  source consists of a handful of C files and a 'Makefile'. The compiler is 
  199.  called 'tc' (Trivial Compiler), and the repository is set up so that there is 
  200.  a module called 'tc'. 
  201.  
  202.  Getting the source            Creating a workspace 
  203.  Committing your changes       Making your work available to others 
  204.  Cleaning up                   Cleaning up 
  205.  Viewing differences           Viewing differences 
  206.  
  207.  
  208. ΓòÉΓòÉΓòÉ 2.3.1. Getting the source ΓòÉΓòÉΓòÉ
  209.  
  210.  The first thing you must do is to get your own working copy of the source for 
  211.  'tc'.  For this, you use the checkout command: 
  212.  
  213.                       $ cvs checkout tc
  214.  
  215.  This will create a new directory called 'tc' and populate it with the source 
  216.  files. 
  217.  
  218.                       $ cd tc
  219.                       $ ls
  220.                       CVS     Makefile   backend.c  driver.c   frontend.c  parser.c
  221.  
  222.  The 'CVS' directory is used internally by CVS.  Normally, you should not 
  223.  modify or remove any of the files in it. 
  224.  
  225.  You start your favorite editor, hack away at 'backend.c', and a couple of 
  226.  hours later you have added an optimization pass to the compiler. A note to RCS 
  227.  and SCCS users: There is no need to lock the files that you want to edit.  See 
  228.  Multiple developers, for an explanation. 
  229.  
  230.  
  231. ΓòÉΓòÉΓòÉ 2.3.2. Committing your changes ΓòÉΓòÉΓòÉ
  232.  
  233.  When you have checked that the compiler is still compilable you decide to make 
  234.  a new version of 'backend.c'.  This will store your new 'backend.c' in the 
  235.  repository and make it available to anyone else who is using that same 
  236.  repository. 
  237.  
  238.                       $ cvs commit backend.c
  239.  
  240.  CVS starts an editor, to allow you to enter a log message.  You type in 
  241.  ``Added an optimization pass.'', save the temporary file, and exit the editor. 
  242.  
  243.  The environment variable $CVSEDITOR determines which editor is started.  If 
  244.  $CVSEDITOR is not set, then if the environment variable $EDITOR is set, it 
  245.  will be used. If both $CVSEDITOR and $EDITOR are not set then there is a 
  246.  default which will vary with your operating system, for example vi for unix or 
  247.  notepad for Windows NT/95. 
  248.  
  249.  When CVS starts the editor, it includes a list of files which are modified. 
  250.  For the CVS client, this list is based on comparing the modification time of 
  251.  the file against the modification time that the file had when it was last 
  252.  gotten or updated.  Therefore, if a file's modification time has changed but 
  253.  its contents have not, it will show up as modified.  The simplest way to 
  254.  handle this is simply not to worry about it---if you proceed with the commit 
  255.  CVS will detect that the contents are not modified and treat it as an 
  256.  unmodified file.  The next update will clue CVS in to the fact that the file 
  257.  is unmodified, and it will reset its stored timestamp so that the file will 
  258.  not show up in future editor sessions. If you want to avoid starting an editor 
  259.  you can specify the log message on the command line using the '-m' flag 
  260.  instead, like this: 
  261.  
  262.                       $ cvs commit -m "Added an optimization pass" backend.c
  263.  
  264.  
  265. ΓòÉΓòÉΓòÉ 2.3.3. Cleaning up ΓòÉΓòÉΓòÉ
  266.  
  267.  Before you turn to other tasks you decide to remove your working copy of tc. 
  268.  One acceptable way to do that is of course 
  269.  
  270.                       $ cd ┬╖┬╖
  271.                       $ rm -r tc
  272.  
  273.  but a better way is to use the release command (see release): 
  274.  
  275.                       $ cd ┬╖┬╖
  276.                       $ cvs release -d tc
  277.                       M driver.c
  278.                       ? tc
  279.                       You have [1] altered files in this repository.
  280.                       Are you sure you want to release (and delete) module `tc': n
  281.                       ** `release' aborted by user choice.
  282.  
  283.  The release command checks that all your modifications have been committed. 
  284.  If history logging is enabled it also makes a note in the history file.  See 
  285.  history file. 
  286.  
  287.  When you use the '-d' flag with release, it also removes your working copy. 
  288.  
  289.  In the example above, the release command wrote a couple of lines of output. 
  290.  '? tc' means that the file 'tc' is unknown to CVS. That is nothing to worry 
  291.  about: 'tc' is the executable compiler, and it should not be stored in the 
  292.  repository.  See cvsignore, for information about how to make that warning go 
  293.  away. See release output, for a complete explanation of all possible output 
  294.  from release. 
  295.  
  296.  'M driver.c' is more serious.  It means that the file 'driver.c' has been 
  297.  modified since it was checked out. 
  298.  
  299.  The release command always finishes by telling you how many modified files you 
  300.  have in your working copy of the sources, and then asks you for confirmation 
  301.  before deleting any files or making any note in the history file. 
  302.  
  303.  You decide to play it safe and answer n RET when release asks for 
  304.  confirmation. 
  305.  
  306.  
  307. ΓòÉΓòÉΓòÉ 2.3.4. Viewing differences ΓòÉΓòÉΓòÉ
  308.  
  309.  You do not remember modifying 'driver.c', so you want to see what has happened 
  310.  to that file. 
  311.  
  312.                       $ cd tc
  313.                       $ cvs diff driver.c
  314.  
  315.  This command runs diff to compare the version of 'driver.c' that you checked 
  316.  out with your working copy.  When you see the output you remember that you 
  317.  added a command line option that enabled the optimization pass.  You check it 
  318.  in, and release the module. 
  319.  
  320.                       $ cvs commit -m "Added an optimization pass" driver.c
  321.                       Checking in driver.c;
  322.                       /usr/local/cvsroot/tc/driver.c,v  <--  driver.c
  323.                       new revision: 1.2; previous revision: 1.1
  324.                       done
  325.                       $ cd ┬╖┬╖
  326.                       $ cvs release -d tc
  327.                       ? tc
  328.                       You have [0] altered files in this repository.
  329.                       Are you sure you want to release (and delete) module `tc': y
  330.  
  331.  
  332. ΓòÉΓòÉΓòÉ 3. The Repository ΓòÉΓòÉΓòÉ
  333.  
  334.  The CVS repository stores a complete copy of all the files and directories 
  335.  which are under version control. 
  336.  
  337.  Normally, you never access any of the files in the repository directly. 
  338.  Instead, you use CVS commands to get your own copy of the files into a working 
  339.  directory, and then work on that copy.  When you've finished a set of changes, 
  340.  you check (or commit) them back into the repository.  The repository then 
  341.  contains the changes which you have made, as well as recording exactly what 
  342.  you changed, when you changed it, and other such information.  Note that the 
  343.  repository is not a subdirectory of the working directory, or vice versa; they 
  344.  should be in separate locations. CVS can access a repository by a variety of 
  345.  means.  It might be on the local computer, or it might be on a computer across 
  346.  the room or across the world. To distinguish various ways to access a 
  347.  repository, the repository name can start with an access method. For example, 
  348.  the access method :local: means to access a repository directory, so the 
  349.  repository :local:/usr/local/cvsroot means that the repository is in 
  350.  '/usr/local/cvsroot' on the computer running CVS.  For information on other 
  351.  access methods, see Remote repositories. 
  352.  
  353.  If the access method is omitted, then if the repository does not contain ':', 
  354.  then :local: is assumed.  If it does contain ':' then either :ext: or :server: 
  355.  is assumed.  For example, if you have a local repository in 
  356.  '/usr/local/cvsroot', you can use /usr/local/cvsroot instead of 
  357.  :local:/usr/local/cvsroot.  But if (under Windows NT, for example) your local 
  358.  repository is 'c:\src\cvsroot', then you must specify the access method, as in 
  359.  :local:c:\src\cvsroot. 
  360.  
  361.  The repository is split in two parts.  '$CVSROOT/CVSROOT' contains 
  362.  administrative files for CVS.  The other directories contain the actual 
  363.  user-defined modules. 
  364.  
  365.  Specifying a repository       Telling CVS where your repository is 
  366.  Repository storage            The structure of the repository 
  367.  Working directory storage     The structure of working directories 
  368.  Intro administrative files    Defining modules 
  369.  Multiple repositories         Multiple repositories 
  370.  Creating a repository         Creating a repository 
  371.  Backing up                    Backing up a repository 
  372.  Moving a repository           Moving a repository 
  373.  Remote repositories           Accessing repositories on remote machines 
  374.  Read-only access              Granting read-only access to the repository 
  375.  Server temporary directory    The server creates temporary directories 
  376.  
  377.  
  378. ΓòÉΓòÉΓòÉ 3.1. Telling CVS where your repository is ΓòÉΓòÉΓòÉ
  379.  
  380.  There are several ways to tell CVS where to find the repository.  You can name 
  381.  the repository on the command line explicitly, with the -d (for "directory") 
  382.  option: 
  383.  
  384.                       cvs -d /usr/local/cvsroot checkout yoyodyne/tc
  385.  
  386.      Or you can set the $CVSROOT environment variable to an absolute path to 
  387.  the root of the repository, '/usr/local/cvsroot' in this example. To set 
  388.  $CVSROOT, csh and tcsh users should have this line in their '.cshrc' or 
  389.  '.tcshrc' files: 
  390.  
  391.                       setenv CVSROOT /usr/local/cvsroot
  392.  
  393.  sh and bash users should instead have these lines in their '.profile' or 
  394.  '.bashrc': 
  395.  
  396.                       CVSROOT=/usr/local/cvsroot
  397.                       export CVSROOT
  398.  
  399.      A repository specified with -d will override the $CVSROOT environment 
  400.  variable. Once you've checked a working copy out from the repository, it will 
  401.  remember where its repository is (the information is recorded in the 
  402.  'CVS/Root' file in the working copy). 
  403.  
  404.  The -d option and the 'CVS/Root' file both override the $CVSROOT environment 
  405.  variable.  If -d option differs from 'CVS/Root', the former is used (and 
  406.  specifying -d will cause 'CVS/Root' to be updated).  Of course, for proper 
  407.  operation they should be two ways of referring to the same repository. 
  408.  
  409.  
  410. ΓòÉΓòÉΓòÉ 3.2. How data is stored in the repository ΓòÉΓòÉΓòÉ
  411.  
  412.  For most purposes it isn't important how CVS stores information in the 
  413.  repository.  In fact, the format has changed in the past, and is likely to 
  414.  change in the future.  Since in almost all cases one accesses the repository 
  415.  via CVS commands, such changes need not be disruptive. 
  416.  
  417.  However, in some cases it may be necessary to understand how CVS stores data 
  418.  in the repository, for example you might need to track down CVS locks (see 
  419.  Concurrency) or you might need to deal with the file permissions appropriate 
  420.  for the repository. 
  421.  
  422.  Repository files              What files are stored in the repository 
  423.  File permissions              File permissions 
  424.  Windows permissions           Issues specific to Windows 
  425.  Attic                         Some files are stored in the Attic 
  426.  CVS in repository             Additional information in CVS directory 
  427.  Locks                         CVS locks control concurrent accesses 
  428.  CVSROOT storage               A few things about CVSROOT are different 
  429.  
  430.  
  431. ΓòÉΓòÉΓòÉ 3.2.1. Where files are stored within the repository ΓòÉΓòÉΓòÉ
  432.  
  433.  The overall structure of the repository is a directory tree corresponding to 
  434.  the directories in the working directory.  For example, supposing the 
  435.  repository is in 
  436.  
  437.                       /usr/local/cvsroot
  438.  
  439.  here is a possible directory tree (showing only the directories): 
  440.  
  441.                       /usr
  442.                        |
  443.                        +--local
  444.                        |  |
  445.                        |  +--cvsroot
  446.                        |  |   |
  447.                        |  |   +--CVSROOT
  448.                            |    (administrative files)
  449.                            |
  450.                            +--gnu
  451.                            |  |
  452.                            |  +--diff
  453.                            |  |  (source code to GNU diff)
  454.                            |  |
  455.                            |  +--rcs
  456.                            |  |  (source code to RCS)
  457.                            |  |
  458.                            |  +--cvs
  459.                            |    (source code to CVS)
  460.                            |
  461.                            +--yoyodyne
  462.                              |
  463.                              +--tc
  464.                              |   |
  465.                              |   +--man
  466.                              |   |
  467.                              |   +--testing
  468.                              |
  469.                              +--(other Yoyodyne software)
  470.  
  471.  With the directories are history files for each file under version control. 
  472.  The name of the history file is the name of the corresponding file with ',v' 
  473.  appended to the end.  Here is what the repository for the 'yoyodyne/tc' 
  474.  directory might look like: 
  475.  
  476.                        $CVSROOT
  477.                         |
  478.                         +--yoyodyne
  479.                         |  |
  480.                         |  +--tc
  481.                         |  |  |
  482.                             +--Makefile,v
  483.                             +--backend.c,v
  484.                             +--driver.c,v
  485.                             +--frontend.c,v
  486.                             +--parser.c,v
  487.                             +--man
  488.                             |   |
  489.                             |   +--tc.1,v
  490.                             |
  491.                             +--testing
  492.                                |
  493.                                +--testpgm.t,v
  494.                                +--test2.t,v
  495.  
  496.  The history files contain, among other things, enough information to recreate 
  497.  any revision of the file, a log of all commit messages and the user-name of 
  498.  the person who committed the revision.  The history files are known as RCS 
  499.  files, because the first program to store files in that format was a version 
  500.  control system known as RCS.  For a full description of the file format, see 
  501.  the man page rcsfile(5), distributed with RCS, or the file 'doc/RCSFILES' in 
  502.  the CVS source distribution.  This file format has become very common---many 
  503.  systems other than CVS or RCS can at least import history files in this 
  504.  format. The RCS files used in CVS differ in a few ways from the standard 
  505.  format.  The biggest difference is magic branches; for more information see 
  506.  Magic branch numbers.  Also in CVS the valid tag names are a subset of what 
  507.  RCS accepts; for CVS's rules see Tags. 
  508.  
  509.  
  510. ΓòÉΓòÉΓòÉ 3.2.2. File permissions ΓòÉΓòÉΓòÉ
  511.  
  512.  All ',v' files are created read-only, and you should not change the permission 
  513.  of those files.  The directories inside the repository should be writable by 
  514.  the persons that have permission to modify the files in each directory.  This 
  515.  normally means that you must create a UNIX group (see group(5)) consisting of 
  516.  the persons that are to edit the files in a project, and set up the repository 
  517.  so that it is that group that owns the directory. This means that you can only 
  518.  control access to files on a per-directory basis. 
  519.  
  520.  Note that users must also have write access to check out files, because CVS 
  521.  needs to create lock files (see Concurrency). 
  522.  
  523.  Also note that users must have write access to the 'CVSROOT/val-tags' file. 
  524.  CVS uses it to keep track of what tags are valid tag names (it is sometimes 
  525.  updated when tags are used, as well as when they are created). 
  526.  
  527.  Each RCS file will be owned by the user who last checked it in.  This has 
  528.  little significance; what really matters is who owns the directories. 
  529.  
  530.  CVS tries to set up reasonable file permissions for new directories that are 
  531.  added inside the tree, but you must fix the permissions manually when a new 
  532.  directory should have different permissions than its parent directory.  If you 
  533.  set the CVSUMASK environment variable that will control the file permissions 
  534.  which CVS uses in creating directories and/or files in the repository. 
  535.  CVSUMASK does not affect the file permissions in the working directory; such 
  536.  files have the permissions which are typical for newly created files, except 
  537.  that sometimes CVS creates them read-only (see the sections on watches, 
  538.  Setting a watch; -r, Global options; or CVSREAD, Environment variables). Note 
  539.  that using the client/server CVS (see Remote repositories), there is no good 
  540.  way to set CVSUMASK; the setting on the client machine has no effect.  If you 
  541.  are connecting with rsh, you can set CVSUMASK in '.bashrc' or '.cshrc', as 
  542.  described in the documentation for your operating system.  This behavior might 
  543.  change in future versions of CVS; do not rely on the setting of CVSUMASK on 
  544.  the client having no effect. Using pserver, you will generally need stricter 
  545.  permissions on the CVSROOT directory and directories above it in the tree; see 
  546.  Password authentication security. 
  547.  
  548.  Some operating systems have features which allow a particular program to run 
  549.  with the ability to perform operations which the caller of the program could 
  550.  not. For example, the set user ID (setuid) or set group ID (setgid) features 
  551.  of unix or the installed image feature of VMS.  CVS was not written to use 
  552.  such features and therefore attempting to install CVS in this fashion will 
  553.  provide protection against only accidental lapses; anyone who is trying to 
  554.  circumvent the measure will be able to do so, and depending on how you have 
  555.  set it up may gain access to more than just CVS.  You may wish to instead 
  556.  consider pserver.  It shares some of the same attributes, in terms of possibly 
  557.  providing a false sense of security or opening security holes wider than the 
  558.  ones you are trying to fix, so read the documentation on pserver security 
  559.  carefully if you are considering this option (Password authentication 
  560.  security). 
  561.  
  562.  
  563. ΓòÉΓòÉΓòÉ 3.2.3. File Permission issues specific to Windows ΓòÉΓòÉΓòÉ
  564.  
  565.  Some file permission issues are specific to Windows operating systems (Windows 
  566.  95, Windows NT, and presumably future operating systems in this family. Some 
  567.  of the following might apply to OS/2 but I'm not sure). 
  568.  
  569.  If you are using local CVS and the repository is on a networked file system 
  570.  which is served by the Samba SMB server, some people have reported problems 
  571.  with permissions.  Enabling WRITE=YES in the samba configuration is said to 
  572.  fix/workaround it. Disclaimer: I haven't investigated enough to know the 
  573.  implications of enabling that option, nor do I know whether there is something 
  574.  which CVS could be doing differently in order to avoid the problem.  If you 
  575.  find something out, please let us know as described in BUGS. 
  576.  
  577.  
  578. ΓòÉΓòÉΓòÉ 3.2.4. The attic ΓòÉΓòÉΓòÉ
  579.  
  580.  You will notice that sometimes CVS stores an RCS file in the Attic.  For 
  581.  example, if the CVSROOT is '/usr/local/cvsroot' and we are talking about the 
  582.  file 'backend.c' in the directory 'yoyodyne/tc', then the file normally would 
  583.  be in 
  584.  
  585.                       /usr/local/cvsroot/yoyodyne/tc/backend.c,v
  586.  
  587.  but if it goes in the attic, it would be in 
  588.  
  589.                       /usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
  590.  
  591.  instead.  It should not matter from a user point of view whether a file is in 
  592.  the attic; CVS keeps track of this and looks in the attic when it needs to. 
  593.  But in case you want to know, the rule is that the RCS file is stored in the 
  594.  attic if and only if the head revision on the trunk has state dead.  A dead 
  595.  state means that file has been removed, or never added, for that revision. 
  596.  For example, if you add a file on a branch, it will have a trunk revision in 
  597.  dead state, and a branch revision in a non-dead state. 
  598.  
  599.  
  600. ΓòÉΓòÉΓòÉ 3.2.5. The CVS directory in the repository ΓòÉΓòÉΓòÉ
  601.  
  602.  The 'CVS' directory in each repository directory contains information such as 
  603.  file attributes (in a file called 'CVS/fileattr'; see fileattr.h in the CVS 
  604.  source distribution for more documentation).  In the future additional files 
  605.  may be added to this directory, so implementations should silently ignore 
  606.  additional files. 
  607.  
  608.  This behavior is implemented only by CVS 1.7 and later; for details see 
  609.  Watches Compatibility. 
  610.  
  611.  
  612. ΓòÉΓòÉΓòÉ 3.2.6. CVS locks in the repository ΓòÉΓòÉΓòÉ
  613.  
  614.  For an introduction to CVS locks focusing on user-visible behavior, see 
  615.  Concurrency.  The following section is aimed at people who are writing tools 
  616.  which want to access a CVS repository without interfering with other tools 
  617.  acessing the same repository.  If you find yourself confused by concepts 
  618.  described here, like read lock, write lock, and deadlock, you might consult 
  619.  the literature on operating systems or databases. 
  620.  
  621.  Any file in the repository with a name starting with '#cvs.rfl' is a read 
  622.  lock.  Any file in the repository with a name starting with '#cvs.wfl' is a 
  623.  write lock.  Old versions of CVS (before CVS 1.5) also created files with 
  624.  names starting with '#cvs.tfl', but they are not discussed here. The directory 
  625.  '#cvs.lock' serves as a master lock.  That is, one must obtain this lock first 
  626.  before creating any of the other locks. 
  627.  
  628.  To obtain a readlock, first create the '#cvs.lock' directory.  This operation 
  629.  must be atomic (which should be true for creating a directory under most 
  630.  operating systems).  If it fails because the directory already existed, wait 
  631.  for a while and try again.  After obtaining the '#cvs.lock' lock, create a 
  632.  file whose name is '#cvs.rfl' followed by information of your choice (for 
  633.  example, hostname and process identification number).  Then remove the 
  634.  '#cvs.lock' directory to release the master lock. Then proceed with reading 
  635.  the repository.  When you are done, remove the '#cvs.rfl' file to release the 
  636.  read lock. 
  637.  
  638.  To obtain a writelock, first create the '#cvs.lock' directory, as with a 
  639.  readlock.  Then check that there are no files whose names start with 
  640.  '#cvs.rfl'.  If there are, remove '#cvs.lock', wait for a while, and try 
  641.  again.  If there are no readers, then create a file whose name is '#cvs.wfl' 
  642.  followed by information of your choice (for example, hostname and process 
  643.  identification number).  Hang on to the '#cvs.lock' lock.  Proceed with 
  644.  writing the repository.  When you are done, first remove the '#cvs.wfl' file 
  645.  and then the '#cvs.lock' directory. Note that unlike the '#cvs.rfl' file, the 
  646.  '#cvs.wfl' file is just informational; it has no effect on the locking 
  647.  operation beyond what is provided by holding on to the '#cvs.lock' lock 
  648.  itself. 
  649.  
  650.  Note that each lock (writelock or readlock) only locks a single directory in 
  651.  the repository, including 'Attic' and 'CVS' but not including subdirectories 
  652.  which represent other directories under version control.  To lock an entire 
  653.  tree, you need to lock each directory (note that if you fail to obtain any 
  654.  lock you need, you must release the whole tree before waiting and trying 
  655.  again, to avoid deadlocks). 
  656.  
  657.  Note also that CVS expects writelocks to control access to individual 'foo,v' 
  658.  files.  RCS has a scheme where the ',foo,' file serves as a lock, but CVS does 
  659.  not implement it and so taking out a CVS writelock is recommended.  See the 
  660.  comments at rcs_internal_lockfile in the CVS source code for further 
  661.  discussion/rationale. 
  662.  
  663.  
  664. ΓòÉΓòÉΓòÉ 3.2.7. How files are stored in the CVSROOT directory ΓòÉΓòÉΓòÉ
  665.  
  666.  The '$CVSROOT/CVSROOT' directory contains the various administrative files. 
  667.  In some ways this directory is just like any other directory in the 
  668.  repository; it contains RCS files whose names end in ',v', and many of the CVS 
  669.  commands operate on it the same way.  However, there are a few differences. 
  670.  
  671.  For each administrative file, in addition to the RCS file, there is also a 
  672.  checked out copy of the file.  For example, there is an RCS file 'loginfo,v' 
  673.  and a file 'loginfo' which contains the latest revision contained in 
  674.  'loginfo,v'.  When you check in an administrative file, CVS should print 
  675.  
  676.                       cvs commit: Rebuilding administrative file database
  677.  
  678.  and update the checked out copy in '$CVSROOT/CVSROOT'.  If it does not, there 
  679.  is something wrong (see BUGS).  To add your own files to the files to be 
  680.  updated in this fashion, you can add them to the 'checkoutlist' administrative 
  681.  file. By default, the 'modules' file behaves as described above.  If the 
  682.  modules file is very large, storing it as a flat text file may make looking up 
  683.  modules slow (I'm not sure whether this is as much of a concern now as when 
  684.  CVS first evolved this feature; I haven't seen benchmarks).  Therefore, by 
  685.  making appropriate edits to the CVS source code one can store the modules file 
  686.  in a database which implements the ndbm interface, such as Berkeley db or 
  687.  GDBM.  If this option is in use, then the modules database will be stored in 
  688.  the files 'modules.db', 'modules.pag', and/or 'modules.dir'. For information 
  689.  on the meaning of the various administrative files, see Administrative files. 
  690.  
  691.  
  692. ΓòÉΓòÉΓòÉ 3.3. How data is stored in the working directory ΓòÉΓòÉΓòÉ
  693.  
  694.  While we are discussing CVS internals which may become visible from time to 
  695.  time, we might as well talk about what CVS puts in the 'CVS' directories in 
  696.  the working directories.  As with the repository, CVS handles this information 
  697.  and one can usually access it via CVS commands.  But in some cases it may be 
  698.  useful to look at it, and other programs, such as the jCVS graphical user 
  699.  interface or the VC package for emacs, may need to look at it. Such programs 
  700.  should follow the recommendations in this section if they hope to be able to 
  701.  work with other programs which use those files, including future versions of 
  702.  the programs just mentioned and the command-line CVS client. 
  703.  
  704.  The 'CVS' directory contains several files. Programs which are reading this 
  705.  directory should silently ignore files which are in the directory but which 
  706.  are not documented here, to allow for future expansion. 
  707.  
  708.  Root 
  709.            This file contains the current CVS root, as described in Specifying 
  710.            a repository. 
  711.  
  712.  Repository 
  713.            This file contains the directory within the repository which the 
  714.            current directory corresponds with.  It can be either an absolute 
  715.            pathname or a relative pathname; CVS has had the ability to read 
  716.            either format since at least version 1.3 or so.  The relative 
  717.            pathname is relative to the root, and is the more sensible approach, 
  718.            but the absolute pathname is quite common and implementations should 
  719.            accept either.  For example, after the command 
  720.  
  721.                       cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
  722.  
  723.  'Root' will contain 
  724.  
  725.                       :local:/usr/local/cvsroot
  726.  
  727.  and 'Repository' will contain either 
  728.  
  729.                       /usr/local/cvsroot/yoyodyne/tc
  730.  
  731.  or 
  732.  
  733.                       yoyodyne/tc
  734.  
  735.  Entries 
  736.            This file lists the files and directories in the working directory. 
  737.            It is a text file according to the conventions appropriate for the 
  738.            operating system in question. The first character of each line 
  739.            indicates what sort of line it is.  If the character is 
  740.            unrecognized, programs reading the file should silently skip that 
  741.            line, to allow for future expansion. 
  742.  
  743.            If the first character is '/', then the format is: 
  744.  
  745.                       /name/revision/timestamp[+conflict]/options/tagdate
  746.  
  747.  where '[' and ']' are not part of the entry, but instead indicate that the '+' 
  748.  and conflict marker are optional.  name is the name of the file within the 
  749.  directory.  revision is the revision that the file in the working derives 
  750.  from, or '0' for an added file, or '-' followed by a revision for a removed 
  751.  file.  timestamp is the timestamp of the file at the time that CVS created it; 
  752.  if the timestamp differs with the actual modification time of the file it 
  753.  means the file has been modified.  It is in Universal Time (UT), stored in the 
  754.  format used by the ISO C asctime() function (for example, 'Sun Apr  7 01:29:26 
  755.  1996').  One may write a string which is not in that format, for example, 
  756.  'Result of merge', to indicate that the file should always be considered to be 
  757.  modified.  This is not a special case; to see whether a file is modified a 
  758.  program should take the timestamp of the file and simply do a string compare 
  759.  with timestamp. conflict indicates that there was a conflict; if it is the 
  760.  same as the actual modification time of the file it means that the user has 
  761.  obviously not resolved the conflict.  options contains sticky options (for 
  762.  example '-kb' for a binary file).  tagdate contains 'T' followed by a tag 
  763.  name, or 'D' for a date, followed by a sticky tag or date.  Note that if 
  764.  timestamp contains a pair of timestamps separated by a space, rather than a 
  765.  single timestamp, you are dealing with a version of CVS earlier than CVS 1.5 
  766.  (not documented here). 
  767.  
  768.  If the first character of a line in 'Entries' is 'D', then it indicates a 
  769.  subdirectory.  'D' on a line all by itself indicates that the program which 
  770.  wrote the 'Entries' file does record subdirectories (therefore, if there is 
  771.  such a line and no other lines beginning with 'D', one knows there are no 
  772.  subdirectories).  Otherwise, the line looks like: 
  773.  
  774.                       D/name/filler1/filler2/filler3/filler4
  775.  
  776.  where name is the name of the subdirectory, and all the filler fields should 
  777.  be silently ignored, for future expansion.  Programs which modify Entries 
  778.  files should preserve these fields. 
  779.  
  780.  Entries.Log 
  781.            This file does not record any information beyond that in 'Entries', 
  782.            but it does provide a way to update the information without having 
  783.            to rewrite the entire 'Entries' file, including the ability to 
  784.            preserve the information even if the program writing 'Entries' and 
  785.            'Entries.Log' abruptly aborts. Programs which are reading the 
  786.            'Entries' file should also check for 'Entries.Log'.  If the latter 
  787.            exists, they should read 'Entries' and then apply the changes 
  788.            mentioned in 'Entries.Log'.  After applying the changes, the 
  789.            recommended practice is to rewrite 'Entries' and then delete 
  790.            'Entries.Log'. The format of a line in 'Entries.Log' is a single 
  791.            character command followed by a space followed by a line in the 
  792.            format specified for a line in 'Entries'.  The single character 
  793.            command is 'A' to indicate that the entry is being added, 'R' to 
  794.            indicate that the entry is being removed, or any other character to 
  795.            indicate that the entire line in 'Entries.Log' should be silently 
  796.            ignored (for future expansion).  If the second character of the line 
  797.            in 'Entries.Log' is not a space, then it was written by an older 
  798.            version of CVS (not documented here). 
  799.  
  800.  Entries.Backup 
  801.            This is a temporary file.  Recommended usage is to write a new 
  802.            entries file to 'Entries.Backup', and then to rename it (atomically, 
  803.            where possible) to 'Entries'. 
  804.  
  805.  Entries.Static 
  806.            The only relevant thing about this file is whether it exists or not. 
  807.            If it exists, then it means that only part of a directory was gotten 
  808.            and CVS will not create additional files in that directory.  To 
  809.            clear it, use the update command with the '-d' option, which will 
  810.            get the additional files and remove 'Entries.Static'. 
  811.  
  812.  Tag 
  813.            This file contains per-directory sticky tags or dates. The first 
  814.            character is 'T' for a branch tag, 'N' for a non-branch tag, or 'D' 
  815.            for a date, or another character to mean the file should be silently 
  816.            ignored, for future expansion.  This character is followed by the 
  817.            tag or date.  Note that per-directory sticky tags or dates are used 
  818.            for things like applying to files which are newly added; they might 
  819.            not be the same as the sticky tags or dates on individual files. 
  820.            For general information on sticky tags and dates, see Sticky tags. 
  821.  
  822.  Checkin.prog 
  823.  
  824.  Update.prog 
  825.            These files store the programs specified by the '-i' and '-u' 
  826.            options in the modules file, respectively. 
  827.  
  828.  Notify 
  829.            This file stores notifications (for example, for edit or unedit) 
  830.            which have not yet been sent to the server.  Its format is not yet 
  831.            documented here. 
  832.  
  833.  Notify.tmp 
  834.            This file is to 'Notify' as 'Entries.Backup' is to 'Entries'.  That 
  835.            is, to write 'Notify', first write the new contents to 'Notify.tmp' 
  836.            and then (atomically where possible), rename it to 'Notify'. 
  837.  
  838.  Base 
  839.            If watches are in use, then an edit command stores the original copy 
  840.            of the file in the 'Base' directory.  This allows the unedit command 
  841.            to operate even if it is unable to communicate with the server. 
  842.  
  843.  Baserev 
  844.            The file lists the revision for each of the files in the 'Base' 
  845.            directory.  The format is: 
  846.  
  847.                       Bname/rev/expansion
  848.  
  849.  where expansion should be ignored, to allow for future expansion. 
  850.  
  851.  Baserev.tmp 
  852.            This file is to 'Baserev' as 'Entries.Backup' is to 'Entries'.  That 
  853.            is, to write 'Baserev', first write the new contents to 
  854.            'Baserev.tmp' and then (atomically where possible), rename it to 
  855.            'Baserev'. 
  856.  
  857.  Template 
  858.            This file contains the template specified by the 'rcsinfo' file (see 
  859.            rcsinfo).  It is only used by the client; the non-client/server CVS 
  860.            consults 'rcsinfo' directly. 
  861.  
  862.  
  863. ΓòÉΓòÉΓòÉ 3.4. The administrative files ΓòÉΓòÉΓòÉ
  864.  
  865.  The directory '$CVSROOT/CVSROOT' contains some administrative files.  See 
  866.  Administrative files, for a complete description. You can use CVS without any 
  867.  of these files, but some commands work better when at least the 'modules' file 
  868.  is properly set up. 
  869.  
  870.  The most important of these files is the 'modules' file.  It defines all 
  871.  modules in the repository.  This is a sample 'modules' file. 
  872.  
  873.                       CVSROOT     CVSROOT
  874.                       modules     CVSROOT modules
  875.                       cvs       gnu/cvs
  876.                       rcs       gnu/rcs
  877.                       diff       gnu/diff
  878.                       tc        yoyodyne/tc
  879.  
  880.  The 'modules' file is line oriented.  In its simplest form each line contains 
  881.  the name of the module, whitespace, and the directory where the module 
  882.  resides.  The directory is a path relative to $CVSROOT.  The last four lines 
  883.  in the example above are examples of such lines. 
  884.  
  885.  The line that defines the module called 'modules' uses features that are not 
  886.  explained here. See modules, for a full explanation of all the available 
  887.  features. 
  888.  
  889.  
  890. ΓòÉΓòÉΓòÉ 3.4.1. Editing administrative files ΓòÉΓòÉΓòÉ
  891.  
  892.  You edit the administrative files in the same way that you would edit any 
  893.  other module.  Use 'cvs checkout CVSROOT' to get a working copy, edit it, and 
  894.  commit your changes in the normal way. 
  895.  
  896.  It is possible to commit an erroneous administrative file.  You can often fix 
  897.  the error and check in a new revision, but sometimes a particularly bad error 
  898.  in the administrative file makes it impossible to commit new revisions. 
  899.  
  900.  
  901. ΓòÉΓòÉΓòÉ 3.5. Multiple repositories ΓòÉΓòÉΓòÉ
  902.  
  903.  In some situations it is a good idea to have more than one repository, for 
  904.  instance if you have two development groups that work on separate projects 
  905.  without sharing any code.  All you have to do to have several repositories is 
  906.  to specify the appropriate repository, using the CVSROOT environment variable, 
  907.  the '-d' option to CVS, or (once you have checked out a working directory) by 
  908.  simply allowing CVS to use the repository that was used to check out the 
  909.  working directory (see Specifying a repository). 
  910.  
  911.  The big advantage of having multiple repositories is that they can reside on 
  912.  different servers.  The big disadvantage is that you cannot have a single CVS 
  913.  command recurse into directories which comes from different repositories. 
  914.  Generally speaking, if you are thinking of setting up several repositories on 
  915.  the same machine, you might want to consider using several directories within 
  916.  the same repository. None of the examples in this manual show multiple 
  917.  repositories. 
  918.  
  919.  
  920. ΓòÉΓòÉΓòÉ 3.6. Creating a repository ΓòÉΓòÉΓòÉ
  921.  
  922.  To set up a CVS repository, first choose the machine and disk on which you 
  923.  want to store the revision history of the source files.  CPU and memory 
  924.  requirements are modest, so most machines should be adequate.  For details see 
  925.  Server requirements. To estimate disk space requirements, if you are importing 
  926.  RCS files from another system, the size of those files is the approximate 
  927.  initial size of your repository, or if you are starting without any version 
  928.  history, a rule of thumb is to allow for the server approximately three times 
  929.  the size of the code to be under CVS for the repository (you will eventually 
  930.  outgrow this, but not for a while).  On the machines on which the developers 
  931.  will be working, you'll want disk space for approximately one working 
  932.  directory for each developer (either the entire tree or a portion of it, 
  933.  depending on what each developer uses). 
  934.  
  935.  The repository should be accessable (directly or via a networked file system) 
  936.  from all machines which want to use CVS in server or local mode; the client 
  937.  machines need not have any access to it other than via the CVS protocol.  It 
  938.  is not possible to use CVS to read from a repository which one only has read 
  939.  access to; CVS needs to be able to create lock files (see Concurrency). 
  940.  
  941.  To create a repository, run the cvs init command.  It will set up an empty 
  942.  repository in the CVS root specified in the usual way (see Repository).  For 
  943.  example, 
  944.  
  945.                       cvs -d /usr/local/cvsroot init
  946.  
  947.  cvs init is careful to never overwrite any existing files in the repository, 
  948.  so no harm is done if you run cvs init on an already set-up repository. 
  949.  
  950.  cvs init will enable history logging; if you don't want that, remove the 
  951.  history file after running cvs init.  See history file. 
  952.  
  953.  
  954. ΓòÉΓòÉΓòÉ 3.7. Backing up a repository ΓòÉΓòÉΓòÉ
  955.  
  956.  There is nothing particularly magical about the files in the repository; for 
  957.  the most part it is possible to back them up just like any other files. 
  958.  However, there are a few issues to consider. 
  959.  
  960.  The first is that to be paranoid, one should either not use CVS during the 
  961.  backup, or have the backup program lock CVS while doing the backup.  To not 
  962.  use CVS, you might forbid logins to machines which can access the repository, 
  963.  turn off your CVS server, or similar mechanisms.  The details would depend on 
  964.  your operating system and how you have CVS set up.  To lock CVS, you would 
  965.  create '#cvs.rfl' locks in each repository directory. See Concurrency, for 
  966.  more on CVS locks. Having said all this, if you just back up without any of 
  967.  these precautions, the results are unlikely to be particularly dire. 
  968.  Restoring from backup, the repository might be in an inconsistent state, but 
  969.  this would not be particularly hard to fix manually. 
  970.  
  971.  When you restore a repository from backup, assuming that changes in the 
  972.  repository were made after the time of the backup, working directories which 
  973.  were not affected by the failure may refer to revisions which no longer exist 
  974.  in the repository.  Trying to run CVS in such directories will typically 
  975.  produce an error message.  One way to get those changes back into the 
  976.  repository is as follows: 
  977.  
  978.      Get a new working directory. 
  979.  
  980.      Copy the files from the working directory from before the failure over to 
  981.       the new working directory (do not copy the contents of the 'CVS' 
  982.       directories, of course). 
  983.  
  984.      Working in the new working directory, use commands such as cvs update and 
  985.       cvs diff to figure out what has changed, and then when you are ready, 
  986.       commit the changes into the repository. 
  987.  
  988.  
  989. ΓòÉΓòÉΓòÉ 3.8. Moving a repository ΓòÉΓòÉΓòÉ
  990.  
  991.  Just as backing up the files in the repository is pretty much like backing up 
  992.  any other files, if you need to move a repository from one place to another it 
  993.  is also pretty much like just moving any other collection of files. 
  994.  
  995.  The main thing to consider is that working directories point to the 
  996.  repository.  The simplest way to deal with a moved repository is to just get a 
  997.  fresh working directory after the move.  Of course, you'll want to make sure 
  998.  that the old working directory had been checked in before the move, or you 
  999.  figured out some other way to make sure that you don't lose any changes.  If 
  1000.  you really do want to reuse the existing working directory, it should be 
  1001.  possible with manual surgery on the 'CVS/Repository' files.  You can see 
  1002.  Working directory storage, for information on the 'CVS/Repository' and 
  1003.  'CVS/Root' files, but unless you are sure you want to bother, it probably 
  1004.  isn't worth it. 
  1005.  
  1006.  
  1007. ΓòÉΓòÉΓòÉ 3.9. Remote repositories ΓòÉΓòÉΓòÉ
  1008.  
  1009.      Your working copy of the sources can be on a different machine than the 
  1010.  repository.  Using CVS in this manner is known as client/server operation. 
  1011.  You run CVS on a machine which can mount your working directory, known as the 
  1012.  client, and tell it to communicate to a machine which can mount the 
  1013.  repository, known as the server.  Generally, using a remote repository is just 
  1014.  like using a local one, except that the format of the repository name is: 
  1015.  
  1016.                       :method:user@hostname:/path/to/repository
  1017.  
  1018.  The details of exactly what needs to be set up depend on how you are 
  1019.  connecting to the server. 
  1020.  
  1021.  If method is not specified, and the repository name contains ':', then the 
  1022.  default is ext or server, depending on your platform; both are described in 
  1023.  Connecting via rsh. 
  1024.  
  1025.  Server requirements           Memory and other resources for servers 
  1026.  Connecting via rsh            Using the rsh program to connect 
  1027.  Password authenticated        Direct connections using passwords 
  1028.  GSSAPI authenticated          Direct connections using GSSAPI 
  1029.  Kerberos authenticated        Direct connections with kerberos 
  1030.  
  1031.  
  1032. ΓòÉΓòÉΓòÉ 3.9.1. Server requirements ΓòÉΓòÉΓòÉ
  1033.  
  1034.  The quick answer to what sort of machine is suitable as a server is that 
  1035.  requirements are modest---a server with 32M of memory or even less can handle 
  1036.  a fairly large source tree with a fair amount of activity. The real answer, of 
  1037.  course, is more complicated. Estimating the known areas of large memory 
  1038.  consumption should be sufficient to estimate memory requirements. There are 
  1039.  two such areas documented here; other memory consumption should be small by 
  1040.  comparison (if you find that is not the case, let us know, as described in 
  1041.  BUGS, so we can update this documentation). 
  1042.  
  1043.  The first area of big memory consumption is large checkouts, when using the 
  1044.  CVS server.  The server consists of two processes for each client that it is 
  1045.  serving.  Memory consumption on the child process should remain fairly small. 
  1046.  Memory consumption on the parent process, particularly if the network 
  1047.  connection to the client is slow, can be expected to grow to slightly more 
  1048.  than the size of the sources in a single directory, or two megabytes, 
  1049.  whichever is larger. Multiplying the size of each CVS server by the number of 
  1050.  servers which you expect to have active at one time should give an idea of 
  1051.  memory requirements for the server.  For the most part, the memory consumed by 
  1052.  the parent process probably can be swap space rather than physical memory. The 
  1053.  second area of large memory consumption is diff, when checking in large files. 
  1054.  This is required even for binary files.  The rule of thumb is to allow about 
  1055.  ten times the size of the largest file you will want to check in, although 
  1056.  five times may be adequate.  For example, if you want to check in a file which 
  1057.  is 10 megabytes, you should have 100 megabytes of memory on the machine doing 
  1058.  the checkin (the server machine for client/server, or the machine running CVS 
  1059.  for non-client/server).  This can be swap space rather than physical memory. 
  1060.  Because the memory is only required briefly, there is no particular need to 
  1061.  allow memory for more than one such checkin at a time. Resource consumption 
  1062.  for the client is even more modest---any machine with enough capacity to run 
  1063.  the operating system in question should have little trouble. For information 
  1064.  on disk space requirements, see Creating a repository. 
  1065.  
  1066.  
  1067. ΓòÉΓòÉΓòÉ 3.9.2. Connecting with rsh ΓòÉΓòÉΓòÉ
  1068.  
  1069.  CVS uses the 'rsh' protocol to perform these operations, so the remote user 
  1070.  host needs to have a '.rhosts' file which grants access to the local user. 
  1071.  
  1072.  For example, suppose you are the user 'mozart' on the local machine 
  1073.  'toe.grunge.com', and the server machine is 'chainsaw.yard.com'.  On chainsaw, 
  1074.  put the following line into the file '.rhosts' in 'bach''s home directory: 
  1075.  
  1076.                       toe.grunge.com  mozart
  1077.  
  1078.  Then test that rsh is working with 
  1079.  
  1080.                       rsh -l bach chainsaw.yard.com 'echo $PATH'
  1081.  
  1082.  Next you have to make sure that rsh will be able to find the server.  Make 
  1083.  sure that the path which rsh printed in the above example includes the 
  1084.  directory containing a program named cvs which is the server.  You need to set 
  1085.  the path in '.bashrc', '.cshrc', etc., not '.login' or '.profile'. 
  1086.  Alternately, you can set the environment variable CVS_SERVER on the client 
  1087.  machine to the filename of the server you want to use, for example 
  1088.  '/usr/local/bin/cvs-1.6'. There is no need to edit inetd.conf or start a CVS 
  1089.  server daemon. 
  1090.  
  1091.  There are two access methods that you use in CVSROOT for rsh.  :server: 
  1092.  specifies an internal rsh client, which is supported only by some CVS ports. 
  1093.  :ext: specifies an external rsh program.  By default this is rsh but you may 
  1094.  set the CVS_RSH environment variable to invoke another program which can 
  1095.  access the remote server (for example, remsh on HP-UX 9 because rsh is 
  1096.  something different).  It must be a program which can transmit data to and 
  1097.  from the server without modifying it; for example the Windows NT rsh is not 
  1098.  suitable since it by default translates between CRLF and LF.  The OS/2 CVS 
  1099.  port has a hack to pass '-b' to rsh to get around this, but since this could 
  1100.  potentially cause problems for programs other than the standard rsh, it may 
  1101.  change in the future.  If you set CVS_RSH to SSH or some other rsh 
  1102.  replacement, the instructions in the rest of this section concerning '.rhosts' 
  1103.  and so on are likely to be inapplicable; consult the documentation for your 
  1104.  rsh replacement. Continuing our example, supposing you want to access the 
  1105.  module 'foo' in the repository '/usr/local/cvsroot/', on machine 
  1106.  'chainsaw.yard.com', you are ready to go: 
  1107.  
  1108.                       cvs -d :ext:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo
  1109.  
  1110.  (The 'bach@' can be omitted if the username is the same on both the local and 
  1111.  remote hosts.) 
  1112.  
  1113.  
  1114. ΓòÉΓòÉΓòÉ 3.9.3. Direct connection with password authentication ΓòÉΓòÉΓòÉ
  1115.  
  1116.  The CVS client can also connect to the server using a password protocol.  This 
  1117.  is particularly useful if using rsh is not feasible (for example, the server 
  1118.  is behind a firewall), and Kerberos also is not available. 
  1119.  
  1120.      To use this method, it is necessary to make some adjustments on both the 
  1121.  server and client sides. 
  1122.  
  1123.  Password authentication serverSetting up the server 
  1124.  Password authentication clientUsing the client 
  1125.  Password authentication securityWhat this method does and does not do 
  1126.  
  1127.  
  1128. ΓòÉΓòÉΓòÉ 3.9.3.1. Setting up the server for password authentication ΓòÉΓòÉΓòÉ
  1129.  
  1130.  First of all, you probably want to tighten the permissions on the '$CVSROOT' 
  1131.  and '$CVSROOT/CVSROOT' directories.  See Password authentication security, for 
  1132.  more details. 
  1133.  
  1134.  On the server side, the file '/etc/inetd.conf' needs to be edited so inetd 
  1135.  knows to run the command cvs pserver when it receives a connection on the 
  1136.  right port.  By default, the port number is 2401; it would be different if 
  1137.  your client were compiled with CVS_AUTH_PORT defined to something else, 
  1138.  though. 
  1139.  
  1140.      If your inetd allows raw port numbers in '/etc/inetd.conf', then the 
  1141.  following (all on a single line in 'inetd.conf') should be sufficient: 
  1142.  
  1143.                       2401  stream  tcp  nowait  root  /usr/local/bin/cvs
  1144.                       cvs --allow-root=/usr/cvsroot pserver
  1145.  
  1146.  You could also use the '-T' option to specify a temporary directory. 
  1147.  
  1148.  The '--allow-root' option specifies the allowable CVSROOT directory.  Clients 
  1149.  which attempt to use a different CVSROOT directory will not be allowed to 
  1150.  connect.  If there is more than one CVSROOT directory which you want to allow, 
  1151.  repeat the option. 
  1152.  
  1153.      If your inetd wants a symbolic service name instead of a raw port number, 
  1154.  then put this in '/etc/services': 
  1155.  
  1156.                       cvspserver    2401/tcp
  1157.  
  1158.      and put cvspserver instead of 2401 in 'inetd.conf'. 
  1159.  
  1160.      Once the above is taken care of, restart your inetd, or do whatever is 
  1161.  necessary to force it to reread its initialization files. 
  1162.  
  1163.  Because the client stores and transmits passwords in cleartext (almost---see 
  1164.  Password authentication security, for details), a separate CVS password file 
  1165.  may be used, so people don't compromise their regular passwords when they 
  1166.  access the repository. This file is '$CVSROOT/CVSROOT/passwd' (see Intro 
  1167.  administrative files).  Its format is similar to '/etc/passwd', except that it 
  1168.  only has two or three fields, username, password, and optional username for 
  1169.  the server to use.  For example: 
  1170.  
  1171.                       bach:ULtgRLXo7NRxs
  1172.                       cwang:1sOp854gDF3DY
  1173.  
  1174.  The password is encrypted according to the standard Unix crypt() function, so 
  1175.  it is possible to paste in passwords directly from regular Unix 'passwd' 
  1176.  files. 
  1177.  
  1178.  When authenticating a password, the server first checks for the user in the 
  1179.  CVS 'passwd' file.  If it finds the user, it compares against that password. 
  1180.  If it does not find the user, or if the CVS 'passwd' file does not exist, then 
  1181.  the server tries to match the password using the system's user-lookup routine 
  1182.  (using the system's user-lookup routine can be disabled by setting 
  1183.  SystemAuth=no in the config file, see config).  When using the CVS 'passwd' 
  1184.  file, the server runs as the username specified in the third argument in the 
  1185.  entry, or as the first argument if there is no third argument (in this way CVS 
  1186.  allows imaginary usernames provided the CVS 'passwd' file indicates 
  1187.  corresponding valid system usernames).  In any case, CVS will have no 
  1188.  privileges which the (valid) user would not have. 
  1189.  
  1190.      It is possible to ``map'' cvs-specific usernames onto system usernames 
  1191.  (i.e., onto system login names) in the '$CVSROOT/CVSROOT/passwd' file by 
  1192.  appending a colon and the system username after the password.  For example: 
  1193.  
  1194.                       cvs:ULtgRLXo7NRxs:kfogel
  1195.                       generic:1sOp854gDF3DY:spwang
  1196.                       anyone:1sOp854gDF3DY:spwang
  1197.  
  1198.      Thus, someone remotely accessing the repository on 'chainsaw.yard.com' 
  1199.  with the following command: 
  1200.  
  1201.                       cvs -d :pserver:cvs@chainsaw.yard.com:/usr/local/cvsroot checkout foo
  1202.  
  1203.      would end up running the server under the system identity kfogel, assuming 
  1204.  successful authentication.  However, the remote user would not necessarily 
  1205.  need to know kfogel's system password, as the '$CVSROOT/CVSROOT/passwd' file 
  1206.  might contain a different password, used only for CVS.  And as the example 
  1207.  above indicates, it is permissible to map multiple cvs usernames onto a single 
  1208.  system username. 
  1209.  
  1210.      This feature is designed to allow people repository access without full 
  1211.  system access (in particular, see Read-only access); however, also see 
  1212.  Password authentication security.  Any sort of repository access very likely 
  1213.  implies a degree of general system access as well. 
  1214.  
  1215.  Right now, the only way to put a password in the CVS 'passwd' file is to paste 
  1216.  it there from somewhere else.  Someday, there may be a cvs passwd command. 
  1217.  
  1218.  
  1219. ΓòÉΓòÉΓòÉ 3.9.3.2. Using the client with password authentication ΓòÉΓòÉΓòÉ
  1220.  
  1221.  Before connecting to the server, the client must log in with the command cvs 
  1222.  login.  Logging in verifies a password with the server, and also records the 
  1223.  password for later transactions with the server. The cvs login command needs 
  1224.  to know the username, server hostname, and full repository path, and it gets 
  1225.  this information from the repository argument or the CVSROOT environment 
  1226.  variable. 
  1227.  
  1228.  cvs login is interactive --- it prompts for a password: 
  1229.  
  1230.                       cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot login
  1231.                       CVS password:
  1232.  
  1233.  The password is checked with the server; if it is correct, the login succeeds, 
  1234.  else it fails, complaining that the password was incorrect. 
  1235.  
  1236.  Once you have logged in, you can force CVS to connect directly to the server 
  1237.  and authenticate with the stored password: 
  1238.  
  1239.                       cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo
  1240.  
  1241.  The ':pserver:' is necessary because without it, CVS will assume it should use 
  1242.  rsh to connect with the server (see Connecting via rsh). (Once you have a 
  1243.  working copy checked out and are running CVS commands from within it, there is 
  1244.  no longer any need to specify the repository explicitly, because CVS records 
  1245.  it in the working copy's 'CVS' subdirectory.) 
  1246.  
  1247.  Passwords are stored by default in the file '$HOME/.cvspass'.  Its format is 
  1248.  human-readable, but don't edit it unless you know what you are doing. The 
  1249.  passwords are not stored in cleartext, but are trivially encoded to protect 
  1250.  them from "innocent" compromise (i.e., inadvertently being seen by a system 
  1251.  administrator who happens to look at that file). 
  1252.  
  1253.  The password for the currently choosen remote repository can be removed from 
  1254.  the CVS_PASSFILE by using the cvs logout command. 
  1255.  
  1256.  The CVS_PASSFILE environment variable overrides this default.  If you use this 
  1257.  variable, make sure you set it before cvs login is run.  If you were to set it 
  1258.  after running cvs login, then later CVS commands would be unable to look up 
  1259.  the password for transmission to the server. 
  1260.  
  1261.  
  1262. ΓòÉΓòÉΓòÉ 3.9.3.3. Security considerations with password authentication ΓòÉΓòÉΓòÉ
  1263.  
  1264.  The passwords are stored on the client side in a trivial encoding of the 
  1265.  cleartext, and transmitted in the same encoding.  The encoding is done only to 
  1266.  prevent inadvertent password compromises (i.e., a system administrator 
  1267.  accidentally looking at the file), and will not prevent even a naive attacker 
  1268.  from gaining the password. 
  1269.  
  1270.  The separate CVS password file (see Password authentication server) allows 
  1271.  people to use a different password for repository access than for login 
  1272.  access.  On the other hand, once a user has non-read-only access to the 
  1273.  repository, she can execute programs on the server system through a variety of 
  1274.  means.  Thus, repository access implies fairly broad system access as well. 
  1275.  It might be possible to modify CVS to prevent that, but no one has done so as 
  1276.  of this writing. Furthermore, there may be other ways in which having access 
  1277.  to CVS allows people to gain more general access to the system; no one has 
  1278.  done a careful audit. 
  1279.  
  1280.  Note that because the '$CVSROOT/CVSROOT' directory contains 'passwd' and other 
  1281.  files which are used to check security, you must control the permissions on 
  1282.  this directory as tightly as the permissions on '/etc'.  The same applies to 
  1283.  the '$CVSROOT' directory itself and any directory above it in the tree. 
  1284.  Anyone who has write access to such a directory will have the ability to 
  1285.  become any user on the system.  Note that these permissions are typically 
  1286.  tighter than you would use if you are not using pserver. In summary, anyone 
  1287.  who gets the password gets repository access, and some measure of general 
  1288.  system access as well.  The password is available to anyone who can sniff 
  1289.  network packets or read a protected (i.e., user read-only) file.  If you want 
  1290.  real security, get Kerberos. 
  1291.  
  1292.  
  1293. ΓòÉΓòÉΓòÉ 3.9.4. Direct connection with GSSAPI ΓòÉΓòÉΓòÉ
  1294.  
  1295.  GSSAPI is a generic interface to network security systems such as Kerberos 5. 
  1296.  If you have a working GSSAPI library, you can have CVS connect via a direct 
  1297.  TCP connection, authenticating with GSSAPI. 
  1298.  
  1299.  To do this, CVS needs to be compiled with GSSAPI support; when configuring CVS 
  1300.  it tries to detect whether GSSAPI libraries using kerberos version 5 are 
  1301.  present.  You can also use the '--with-gssapi' flag to configure. 
  1302.  
  1303.  The connection is authenticated using GSSAPI, but the message stream is not 
  1304.  authenticated by default. You must use the -a global option to request stream 
  1305.  authentication. 
  1306.  
  1307.  The data transmitted is not encrypted by default.  Encryption support must be 
  1308.  compiled into both the client and the server; use the '--enable-encrypt' 
  1309.  configure option to turn it on. You must then use the -x global option to 
  1310.  request encryption. 
  1311.  
  1312.  GSSAPI connections are handled on the server side by the same server which 
  1313.  handles the password authentication server; see Password authentication 
  1314.  server.  If you are using a GSSAPI mechanism such as Kerberos which provides 
  1315.  for strong authentication, you will probably want to disable the ability to 
  1316.  authenticate via cleartext passwords.  To do so, create an empty 
  1317.  'CVSROOT/passwd' password file, and set SystemAuth=no in the config file (see 
  1318.  config). 
  1319.  
  1320.  The GSSAPI server uses a principal name of cvs/hostname, where hostname is the 
  1321.  canonical name of the server host.  You will have to set this up as required 
  1322.  by your GSSAPI mechanism. 
  1323.  
  1324.  To connect using GSSAPI, use ':gserver:'.  For example, 
  1325.  
  1326.                       cvs -d :gserver:chainsaw.yard.com:/usr/local/cvsroot checkout foo
  1327.  
  1328.  
  1329. ΓòÉΓòÉΓòÉ 3.9.5. Direct connection with kerberos ΓòÉΓòÉΓòÉ
  1330.  
  1331.  The easiest way to use kerberos is to use the kerberos rsh, as described in 
  1332.  Connecting via rsh. The main disadvantage of using rsh is that all the data 
  1333.  needs to pass through additional programs, so it may be slower.  So if you 
  1334.  have kerberos installed you can connect via a direct TCP connection, 
  1335.  authenticating with kerberos. 
  1336.  
  1337.  This section concerns the kerberos network security system, version 4. 
  1338.  Kerberos version 5 is supported via the GSSAPI generic network security 
  1339.  interface, as described in the previous section. 
  1340.  
  1341.  To do this, CVS needs to be compiled with kerberos support; when configuring 
  1342.  CVS it tries to detect whether kerberos is present or you can use the 
  1343.  '--with-krb4' flag to configure. 
  1344.  
  1345.  The data transmitted is not encrypted by default.  Encryption support must be 
  1346.  compiled into both the client and server; use the '--enable-encryption' 
  1347.  configure option to turn it on.  You must then use the -x global option to 
  1348.  request encryption. 
  1349.  
  1350.  You need to edit inetd.conf on the server machine to run cvs kserver.  The 
  1351.  client uses port 1999 by default; if you want to use another port specify it 
  1352.  in the CVS_CLIENT_PORT environment variable on the client. 
  1353.  
  1354.  When you want to use CVS, get a ticket in the usual way (generally kinit); it 
  1355.  must be a ticket which allows you to log into the server machine.  Then you 
  1356.  are ready to go: 
  1357.  
  1358.                       cvs -d :kserver:chainsaw.yard.com:/usr/local/cvsroot checkout foo
  1359.  
  1360.  Previous versions of CVS would fall back to a connection via rsh; this version 
  1361.  will not do so. 
  1362.  
  1363.  
  1364. ΓòÉΓòÉΓòÉ 3.10. Read-only repository access ΓòÉΓòÉΓòÉ
  1365.  
  1366.      It is possible to grant read-only repository access to people using the 
  1367.  password-authenticated server (see Password authenticated).  (The other access 
  1368.  methods do not have explicit support for read-only users because those methods 
  1369.  all assume login access to the repository machine anyway, and therefore the 
  1370.  user can do whatever local file permissions allow her to do.) 
  1371.  
  1372.      A user who has read-only access can do only those CVS operations which do 
  1373.  not modify the repository, except for certain ``administrative'' files (such 
  1374.  as lock files and the history file).  It may be desirable to use this feature 
  1375.  in conjunction with user-aliasing (see Password authentication server). 
  1376.  
  1377.  Unlike with previous versions of CVS, read-only users should be able merely to 
  1378.  read the repository, and not to execute programs on the server or otherwise 
  1379.  gain unexpected levels of access.  Or to be more accurate, the known holes 
  1380.  have been plugged.  Because this feature is new and has not received a 
  1381.  comprehensive security audit, you should use whatever level of caution seems 
  1382.  warranted given your attitude concerning security. 
  1383.  
  1384.      There are two ways to specify read-only access for a user: by inclusion, 
  1385.  and by exclusion. 
  1386.  
  1387.      "Inclusion" means listing that user specifically in the 
  1388.  '$CVSROOT/CVSROOT/readers' file, which is simply a newline-separated list of 
  1389.  users.  Here is a sample 'readers' file: 
  1390.  
  1391.                       melissa
  1392.                       splotnik
  1393.                       jrandom
  1394.  
  1395.      (Don't forget the newline after the last user.) 
  1396.  
  1397.      "Exclusion" means explicitly listing everyone who has write access---if 
  1398.  the file 
  1399.  
  1400.                       $CVSROOT/CVSROOT/writers
  1401.  
  1402.  exists, then only those users listed in it have write access, and everyone 
  1403.  else has read-only access (of course, even the read-only users still need to 
  1404.  be listed in the CVS 'passwd' file).  The 'writers' file has the same format 
  1405.  as the 'readers' file. 
  1406.  
  1407.      Note: if your CVS 'passwd' file maps cvs users onto system users (see 
  1408.  Password authentication server), make sure you deny or grant read-only access 
  1409.  using the cvs usernames, not the system usernames.  That is, the 'readers' and 
  1410.  'writers' files contain cvs usernames, which may or may not be the same as 
  1411.  system usernames. 
  1412.  
  1413.      Here is a complete description of the server's behavior in deciding 
  1414.  whether to grant read-only or read-write access: 
  1415.  
  1416.      If 'readers' exists, and this user is listed in it, then she gets 
  1417.  read-only access.  Or if 'writers' exists, and this user is NOT listed in it, 
  1418.  then she also gets read-only access (this is true even if 'readers' exists but 
  1419.  she is not listed there).  Otherwise, she gets full read-write access. 
  1420.  
  1421.      Of course there is a conflict if the user is listed in both files.  This 
  1422.  is resolved in the more conservative way, it being better to protect the 
  1423.  repository too much than too little: such a user gets read-only access. 
  1424.  
  1425.  
  1426. ΓòÉΓòÉΓòÉ 3.11. Temporary directories for the server ΓòÉΓòÉΓòÉ
  1427.  
  1428.  While running, the CVS server creates temporary directories.  They are named 
  1429.  
  1430.                       cvs-servpid
  1431.  
  1432.  where pid is the process identification number of the server.  They are 
  1433.  located in the directory specified by the 'TMPDIR' environment variable (see 
  1434.  Environment variables), the '-T' global option (see Global options), or 
  1435.  failing that '/tmp'. 
  1436.  
  1437.  In most cases the server will remove the temporary directory when it is done, 
  1438.  whether it finishes normally or abnormally.  However, there are a few cases in 
  1439.  which the server does not or cannot remove the temporary directory, for 
  1440.  example: 
  1441.  
  1442.      If the server aborts due to an internal server error, it may preserve the 
  1443.       directory to aid in debugging 
  1444.  
  1445.      If the server is killed in a way that it has no way of cleaning up (most 
  1446.       notably, 'kill -KILL' on unix). 
  1447.  
  1448.      If the system shuts down without an orderly shutdown, which tells the 
  1449.       server to clean up. 
  1450.  
  1451.  In cases such as this, you will need to manually remove the 'cvs-servpid' 
  1452.  directories.  As long as there is no server running with process 
  1453.  identification number pid, it is safe to do so. 
  1454.  
  1455.  
  1456. ΓòÉΓòÉΓòÉ 4. Starting a project with CVS ΓòÉΓòÉΓòÉ
  1457.  
  1458.  Because renaming files and moving them between directories is somewhat 
  1459.  inconvenient, the first thing you do when you start a new project should be to 
  1460.  think through your file organization.  It is not impossible to rename or move 
  1461.  files, but it does increase the potential for confusion and CVS does have some 
  1462.  quirks particularly in the area of renaming directories.  See Moving files. 
  1463.  
  1464.  What to do next depends on the situation at hand. 
  1465.  
  1466.  Setting up the files          Getting the files into the repository 
  1467.  Defining the module           How to make a module of the files 
  1468.  
  1469.  
  1470. ΓòÉΓòÉΓòÉ 4.1. Setting up the files ΓòÉΓòÉΓòÉ
  1471.  
  1472.  The first step is to create the files inside the repository.  This can be done 
  1473.  in a couple of different ways. 
  1474.  
  1475.  From files                    This method is useful with old projects where 
  1476.                                files already exists. 
  1477.  From other version control systemsOld projects where you want to preserve 
  1478.                                history from another system. 
  1479.  From scratch                  Creating a directory tree from scratch. 
  1480.  
  1481.  
  1482. ΓòÉΓòÉΓòÉ 4.1.1. Creating a directory tree from a number of files ΓòÉΓòÉΓòÉ
  1483.  
  1484.  When you begin using CVS, you will probably already have several projects that 
  1485.  can be put under CVS control.  In these cases the easiest way is to use the 
  1486.  import command.  An example is probably the easiest way to explain how to use 
  1487.  it.  If the files you want to install in CVS reside in 'wdir', and you want 
  1488.  them to appear in the repository as '$CVSROOT/yoyodyne/rdir', you can do this: 
  1489.  
  1490.                       $ cd wdir
  1491.                       $ cvs import -m "Imported sources" yoyodyne/rdir yoyo start
  1492.  
  1493.  Unless you supply a log message with the '-m' flag, CVS starts an editor and 
  1494.  prompts for a message.  The string 'yoyo' is a vendor tag, and 'start' is a 
  1495.  release tag.  They may fill no purpose in this context, but since CVS requires 
  1496.  them they must be present.  See Tracking sources, for more information about 
  1497.  them. 
  1498.  
  1499.  You can now verify that it worked, and remove your original source directory. 
  1500.  
  1501.                       $ cd ┬╖┬╖
  1502.                       $ mv dir dir.orig
  1503.                       $ cvs checkout yoyodyne/dir    # Explanation below
  1504.                       $ diff -r dir.orig yoyodyne/dir
  1505.                       $ rm -r dir.orig
  1506.  
  1507.  Erasing the original sources is a good idea, to make sure that you do not 
  1508.  accidentally edit them in dir, bypassing CVS. Of course, it would be wise to 
  1509.  make sure that you have a backup of the sources before you remove them. 
  1510.  
  1511.  The checkout command can either take a module name as argument (as it has done 
  1512.  in all previous examples) or a path name relative to $CVSROOT, as it did in 
  1513.  the example above. 
  1514.  
  1515.  It is a good idea to check that the permissions CVS sets on the directories 
  1516.  inside '$CVSROOT' are reasonable, and that they belong to the proper groups. 
  1517.  See File permissions. 
  1518.  
  1519.  If some of the files you want to import are binary, you may want to use the 
  1520.  wrappers features to specify which files are binary and which are not.  See 
  1521.  Wrappers. 
  1522.  
  1523.  
  1524. ΓòÉΓòÉΓòÉ 4.1.2. Creating Files From Other Version Control Systems ΓòÉΓòÉΓòÉ
  1525.  
  1526.  If you have a project which you are maintaining with another version control 
  1527.  system, such as RCS, you may wish to put the files from that project into CVS, 
  1528.  and preserve the revision history of the files. 
  1529.  
  1530.  From RCS 
  1531.            If you have been using RCS, find the RCS files---usually a file 
  1532.            named 'foo.c' will have its RCS file in 'RCS/foo.c,v' (but it could 
  1533.            be other places; consult the RCS documentation for details).  Then 
  1534.            create the appropriate directories in CVS if they do not already 
  1535.            exist.  Then copy the files into the appropriate directories in the 
  1536.            CVS repository (the name in the repository must be the name of the 
  1537.            source file with ',v' added; the files go directly in the appopriate 
  1538.            directory of the repository, not in an 'RCS' subdirectory).  This is 
  1539.            one of the few times when it is a good idea to access the CVS 
  1540.            repository directly, rather than using CVS commands.  Then you are 
  1541.            ready to check out a new working directory. The RCS file should not 
  1542.            be locked when you move it into CVS; if it is, CVS will have trouble 
  1543.            letting you operate on it. 
  1544.  
  1545.  From another version control system 
  1546.            Many version control systems have the ability to export RCS files in 
  1547.            the standard format.  If yours does, export the RCS files and then 
  1548.            follow the above instructions. 
  1549.  
  1550.            Failing that, probably your best bet is to write a script that will 
  1551.            check out the files one revision at a time using the command line 
  1552.            interface to the other system, and then check the revisions into 
  1553.            CVS. The 'sccs2rcs' script mentioned below may be a useful example 
  1554.            to follow. 
  1555.  
  1556.  From SCCS 
  1557.            There is a script in the 'contrib' directory of the CVS source 
  1558.            distribution called 'sccs2rcs' which converts SCCS files to RCS 
  1559.            files. Note: you must run it on a machine which has both SCCS and 
  1560.            RCS installed, and like everything else in contrib it is unsupported 
  1561.            (your mileage may vary). 
  1562.  
  1563.  From PVCS 
  1564.            There is a script in the 'contrib' directory of the CVS source 
  1565.            distribution called 'pvcs_to_rcs' which converts PVCS archives to 
  1566.            RCS files. You must run it on a machine which has both PVCS and RCS 
  1567.            installed, and like everything else in contrib it is unsupported 
  1568.            (your mileage may vary).  See the comments in the script for 
  1569.            details. 
  1570.  
  1571.  
  1572. ΓòÉΓòÉΓòÉ 4.1.3. Creating a directory tree from scratch ΓòÉΓòÉΓòÉ
  1573.  
  1574.  For a new project, the easiest thing to do is probably to create an empty 
  1575.  directory structure, like this: 
  1576.  
  1577.                       $ mkdir tc
  1578.                       $ mkdir tc/man
  1579.                       $ mkdir tc/testing
  1580.  
  1581.  After that, you use the import command to create the corresponding (empty) 
  1582.  directory structure inside the repository: 
  1583.  
  1584.                       $ cd tc
  1585.                       $ cvs import -m "Created directory structure" yoyodyne/dir yoyo start
  1586.  
  1587.  Then, use add to add files (and new directories) as they appear. 
  1588.  
  1589.  Check that the permissions CVS sets on the directories inside '$CVSROOT' are 
  1590.  reasonable. 
  1591.  
  1592.  
  1593. ΓòÉΓòÉΓòÉ 4.2. Defining the module ΓòÉΓòÉΓòÉ
  1594.  
  1595.  The next step is to define the module in the 'modules' file.  This is not 
  1596.  strictly necessary, but modules can be convenient in grouping together related 
  1597.  files and directories. 
  1598.  
  1599.  In simple cases these steps are sufficient to define a module. 
  1600.  
  1601.    1. Get a working copy of the modules file. 
  1602.  
  1603.                       $ cvs checkout CVSROOT/modules
  1604.                       $ cd CVSROOT
  1605.  
  1606.    2. Edit the file and insert a line that defines the module.  See Intro 
  1607.       administrative files, for an introduction.  See modules, for a full 
  1608.       description of the modules file.  You can use the following line to 
  1609.       define the module 'tc': 
  1610.  
  1611.                       tc  yoyodyne/tc
  1612.  
  1613.    3. Commit your changes to the modules file. 
  1614.  
  1615.                       $ cvs commit -m "Added the tc module." modules
  1616.  
  1617.    4. Release the modules module. 
  1618.  
  1619.                       $ cd ┬╖┬╖
  1620.                       $ cvs release -d CVSROOT
  1621.  
  1622.  
  1623. ΓòÉΓòÉΓòÉ 5. Revisions ΓòÉΓòÉΓòÉ
  1624.  
  1625.  For many uses of CVS, one doesn't need to worry too much about revision 
  1626.  numbers; CVS assigns numbers such as 1.1, 1.2, and so on, and that is all one 
  1627.  needs to know.  However, some people prefer to have more knowledge and control 
  1628.  concerning how CVS assigns revision numbers. 
  1629.  
  1630.  If one wants to keep track of a set of revisions involving more than one file, 
  1631.  such as which revisions went into a particular release, one uses a tag, which 
  1632.  is a symbolic revision which can be assigned to a numeric revision in each 
  1633.  file. 
  1634.  
  1635.  Revision numbers              The meaning of a revision number 
  1636.  Versions revisions releases   Terminology used in this manual 
  1637.  Assigning revisions           Assigning revisions 
  1638.  Tags                          Tags--Symbolic revisions 
  1639.  Sticky tags                   Certain tags are persistent 
  1640.  
  1641.  
  1642. ΓòÉΓòÉΓòÉ 5.1. Revision numbers ΓòÉΓòÉΓòÉ
  1643.  
  1644.  Each version of a file has a unique revision number.  Revision numbers look 
  1645.  like '1.1', '1.2', '1.3.2.2' or even '1.3.2.2.4.5'. A revision number always 
  1646.  has an even number of period-separated decimal integers.  By default revision 
  1647.  1.1 is the first revision of a file.  Each successive revision is given a new 
  1648.  number by increasing the rightmost number by one.  The following figure 
  1649.  displays a few revisions, with newer revisions to the right. 
  1650.  
  1651.                           +-----+   +-----+   +-----+   +-----+   +-----+
  1652.                           ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
  1653.                           +-----+   +-----+   +-----+   +-----+   +-----+
  1654.  
  1655.  It is also possible to end up with numbers containing more than one period, 
  1656.  for example '1.3.2.2'.  Such revisions represent revisions on branches (see 
  1657.  Branching and merging); such revision numbers are explained in detail in 
  1658.  Branches and revisions. 
  1659.  
  1660.  
  1661. ΓòÉΓòÉΓòÉ 5.2. Versions, revisions and releases ΓòÉΓòÉΓòÉ
  1662.  
  1663.  A file can have several versions, as described above. Likewise, a software 
  1664.  product can have several versions. A software product is often given a version 
  1665.  number such as '4.1.1'. 
  1666.  
  1667.  Versions in the first sense are called revisions in this document, and 
  1668.  versions in the second sense are called releases.  To avoid confusion, the 
  1669.  word version is almost never used in this document. 
  1670.  
  1671.  
  1672. ΓòÉΓòÉΓòÉ 5.3. Assigning revisions ΓòÉΓòÉΓòÉ
  1673.  
  1674.  By default, CVS will assign numeric revisions by leaving the first number the 
  1675.  same and incrementing the second number.  For example, 1.1, 1.2, 1.3, etc. 
  1676.  
  1677.  When adding a new file, the second number will always be one and the first 
  1678.  number will equal the highest first number of any file in that directory.  For 
  1679.  example, the current directory contains files whose highest numbered revisions 
  1680.  are 1.7, 3.1, and 4.12, then an added file will be given the numeric revision 
  1681.  4.1. 
  1682.  
  1683.  Normally there is no reason to care about the revision numbers---it is easier 
  1684.  to treat them as internal numbers that CVS maintains, and tags provide a 
  1685.  better way to distinguish between things like release 1 versus release 2 of 
  1686.  your product (see Tags).  However, if you want to set the numeric revisions, 
  1687.  the '-r' option to cvs commit can do that.  The '-r' option implies the '-f' 
  1688.  option, in the sense that it causes the files to be committed even if they are 
  1689.  not modified. 
  1690.  
  1691.  For example, to bring all your files up to revision 3.0 (including those that 
  1692.  haven't changed), you might invoke: 
  1693.  
  1694.                       $ cvs commit -r 3.0
  1695.  
  1696.  Note that the number you specify with '-r' must be larger than any existing 
  1697.  revision number.  That is, if revision 3.0 exists, you cannot 'cvs commit -r 
  1698.  1.3'.  If you want to maintain several releases in parallel, you need to use a 
  1699.  branch (see Branching and merging). 
  1700.  
  1701.  
  1702. ΓòÉΓòÉΓòÉ 5.4. Tags--Symbolic revisions ΓòÉΓòÉΓòÉ
  1703.  
  1704.  The revision numbers live a life of their own.  They need not have anything at 
  1705.  all to do with the release numbers of your software product.  Depending on how 
  1706.  you use CVS the revision numbers might change several times between two 
  1707.  releases.  As an example, some of the source files that make up RCS 5.6 have 
  1708.  the following revision numbers: 
  1709.  
  1710.                       ci.c       5.21
  1711.                       co.c       5.9
  1712.                       ident.c     5.3
  1713.                       rcs.c      5.12
  1714.                       rcsbase.h    5.11
  1715.                       rcsdiff.c    5.10
  1716.                       rcsedit.c    5.11
  1717.                       rcsfcmp.c    5.9
  1718.                       rcsgen.c     5.10
  1719.                       rcslex.c     5.11
  1720.                       rcsmap.c     5.2
  1721.                       rcsutil.c    5.10
  1722.  
  1723.  You can use the tag command to give a symbolic name to a certain revision of a 
  1724.  file.  You can use the '-v' flag to the status command to see all tags that a 
  1725.  file has, and which revision numbers they represent.  Tag names must start 
  1726.  with an uppercase or lowercase letter and can contain uppercase and lowercase 
  1727.  letters, digits, '-', and '_'.  The two tag names BASE and HEAD are reserved 
  1728.  for use by CVS.  It is expected that future names which are special to CVS 
  1729.  will be specially named, for example by starting with '.', rather than being 
  1730.  named analogously to BASE and HEAD, to avoid conflicts with actual tag names. 
  1731.  You'll want to choose some convention for naming tags, based on information 
  1732.  such as the name of the program and the version number of the release.  For 
  1733.  example, one might take the name of the program, immediately followed by the 
  1734.  version number with '.' changed to '-', so that CVS 1.9 would be tagged with 
  1735.  the name cvs1-9.  If you choose a consistent convention, then you won't 
  1736.  constantly be guessing whether a tag is cvs-1-9 or cvs1_9 or what.  You might 
  1737.  even want to consider enforcing your convention in the taginfo file (see 
  1738.  user-defined logging). The following example shows how you can add a tag to a 
  1739.  file.  The commands must be issued inside your working copy of the module. 
  1740.  That is, you should issue the command in the directory where 'backend.c' 
  1741.  resides. 
  1742.  
  1743.                       $ cvs tag rel-0-4 backend.c
  1744.                       T backend.c
  1745.                       $ cvs status -v backend.c
  1746.                       ===================================================================
  1747.                       File: backend.c     Status: Up-to-date
  1748.                         Version:       1.4   Tue Dec  1 14:39:01 1992
  1749.                         RCS Version:     1.4   /u/cvsroot/yoyodyne/tc/backend.c,v
  1750.                         Sticky Tag:     (none)
  1751.                         Sticky Date:     (none)
  1752.                         Sticky Options:   (none)
  1753.                         Existing Tags:
  1754.                           rel-0-4           (revision: 1.4)
  1755.  
  1756.  There is seldom reason to tag a file in isolation.  A more common use is to 
  1757.  tag all the files that constitute a module with the same tag at strategic 
  1758.  points in the development life-cycle, such as when a release is made. 
  1759.  
  1760.                       $ cvs tag rel-1-0 .
  1761.                       cvs tag: Tagging .
  1762.                       T Makefile
  1763.                       T backend.c
  1764.                       T driver.c
  1765.                       T frontend.c
  1766.                       T parser.c
  1767.  
  1768.  (When you give CVS a directory as argument, it generally applies the operation 
  1769.  to all the files in that directory, and (recursively), to any subdirectories 
  1770.  that it may contain.  See Recursive behavior.) 
  1771.  
  1772.  The checkout command has a flag, '-r', that lets you check out a certain 
  1773.  revision of a module.  This flag makes it easy to retrieve the sources that 
  1774.  make up release 1.0 of the module 'tc' at any time in the future: 
  1775.  
  1776.                       $ cvs checkout -r rel-1-0 tc
  1777.  
  1778.  This is useful, for instance, if someone claims that there is a bug in that 
  1779.  release, but you cannot find the bug in the current working copy. 
  1780.  
  1781.  You can also check out a module as it was at any given date. See checkout 
  1782.  options. 
  1783.  
  1784.  When you tag more than one file with the same tag you can think about the tag 
  1785.  as "a curve drawn through a matrix of filename vs. revision number."  Say we 
  1786.  have 5 files with the following revisions: 
  1787.  
  1788.                           file1  file2  file3  file4  file5
  1789.                           1.1   1.1   1.1   1.1  /--1.1*    <-*-  TAG
  1790.                           1.2*-  1.2   1.2   -1.2*-
  1791.                           1.3  \- 1.3*-  1.3  / 1.3
  1792.                           1.4      \  1.4  /  1.4
  1793.                                  \-1.5*-  1.5
  1794.                                   1.6
  1795.  
  1796.  At some time in the past, the * versions were tagged. You can think of the tag 
  1797.  as a handle attached to the curve drawn through the tagged revisions.  When 
  1798.  you pull on the handle, you get all the tagged revisions.  Another way to look 
  1799.  at it is that you "sight" through a set of revisions that is "flat" along the 
  1800.  tagged revisions, like this: 
  1801.  
  1802.                           file1  file2  file3  file4  file5
  1803.                                   1.1
  1804.                                   1.2
  1805.                               1.1   1.3            _
  1806.                           1.1   1.2   1.4   1.1        /
  1807.                           1.2*----1.3*----1.5*----1.2*----1.1   (--- <--- Look here
  1808.                           1.3       1.6   1.3        \_
  1809.                           1.4           1.4
  1810.                                       1.5
  1811.  
  1812.  
  1813. ΓòÉΓòÉΓòÉ 5.5. Sticky tags ΓòÉΓòÉΓòÉ
  1814.  
  1815.  Sometimes a working copy's revision has extra data associated with it, for 
  1816.  example it might be on a branch (see Branching and merging), or restricted to 
  1817.  versions prior to a certain date by 'checkout -D' or 'update -D'.  Because 
  1818.  this data persists -- that is, it applies to subsequent commands in the 
  1819.  working copy -- we refer to it as sticky. 
  1820.  
  1821.  Most of the time, stickiness is an obscure aspect of CVS that you don't need 
  1822.  to think about.  However, even if you don't want to use the feature, you may 
  1823.  need to know something about sticky tags (for example, how to avoid them!). 
  1824.  
  1825.  You can use the status command to see if any sticky tags or dates are set: 
  1826.  
  1827.                       $ cvs status driver.c
  1828.                       ===================================================================
  1829.                       File: driver.c      Status: Up-to-date
  1830.                         Version:       1.7.2.1 Sat Dec  5 19:35:03 1992
  1831.                         RCS Version:     1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
  1832.                         Sticky Tag:     rel-1-0-patches (branch: 1.7.2)
  1833.                         Sticky Date:     (none)
  1834.                         Sticky Options:   (none)
  1835.  
  1836.  The sticky tags will remain on your working files until you delete them with 
  1837.  'cvs update -A'.  The '-A' option retrieves the version of the file from the 
  1838.  head of the trunk, and forgets any sticky tags, dates, or options. 
  1839.  
  1840.  The most common use of sticky tags is to identify which branch one is working 
  1841.  on, as described in Accessing branches.  However, non-branch sticky tags have 
  1842.  uses as well.  For example, suppose that you want to avoid updating your 
  1843.  working directory, to isolate yourself from possibly destabilizing changes 
  1844.  other people are making.  You can, of course, just refrain from running cvs 
  1845.  update.  But if you want to avoid updating only a portion of a larger tree, 
  1846.  then sticky tags can help. If you check out a certain revision (such as 1.4) 
  1847.  it will become sticky.  Subsequent cvs update commands will not retrieve the 
  1848.  latest revision until you reset the tag with cvs update -A.  Likewise, use of 
  1849.  the '-D' option to update or checkout sets a sticky date, which, similarly, 
  1850.  causes that date to be used for future retrievals. 
  1851.  
  1852.  Many times you will want to retrieve an old version of a file without setting 
  1853.  a sticky tag.  The way to do that is with the '-p' option to checkout or 
  1854.  update, which sends the contents of the file to standard output.  For example, 
  1855.  suppose you have a file named 'file1' which existed as revision 1.1, and you 
  1856.  then removed it (thus adding a dead revision 1.2). Now suppose you want to add 
  1857.  it again, with the same contents it had previously.  Here is how to do it: 
  1858.  
  1859.                       $ cvs update -p -r 1.1 file1 >file1
  1860.                       ===================================================================
  1861.                       Checking out file1
  1862.                       RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
  1863.                       VERS: 1.1
  1864.                       ***************
  1865.                       $ cvs add file1
  1866.                       cvs add: re-adding file file1 (in place of dead revision 1.2)
  1867.                       cvs add: use 'cvs commit' to add this file permanently
  1868.                       $ cvs commit -m test
  1869.                       Checking in file1;
  1870.                       /tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
  1871.                       new revision: 1.3; previous revision: 1.2
  1872.                       done
  1873.                       $
  1874.  
  1875.  
  1876. ΓòÉΓòÉΓòÉ 6. Branching and merging ΓòÉΓòÉΓòÉ
  1877.  
  1878.  CVS allows you to isolate changes onto a separate line of development, known 
  1879.  as a branch.  When you change files on a branch, those changes do not appear 
  1880.  on the main trunk or other branches. 
  1881.  
  1882.  Later you can move changes from one branch to another branch (or the main 
  1883.  trunk) by merging.  Merging involves first running cvs update -j, to merge the 
  1884.  changes into the working directory. You can then commit that revision, and 
  1885.  thus effectively copy the changes onto another branch. 
  1886.  
  1887.  Branches motivation           What branches are good for 
  1888.  Creating a branch             Creating a branch 
  1889.  Accessing branches            Checking out and updating branches 
  1890.  Branches and revisions        Branches are reflected in revision numbers 
  1891.  Magic branch numbers          Magic branch numbers 
  1892.  Merging a branch              Merging an entire branch 
  1893.  Merging more than once        Merging from a branch several times 
  1894.  Merging two revisions         Merging differences between two revisions 
  1895.  Merging adds and removals     What if files are added or removed? 
  1896.  
  1897.  
  1898. ΓòÉΓòÉΓòÉ 6.1. What branches are good for ΓòÉΓòÉΓòÉ
  1899.  
  1900.  Suppose that release 1.0 of tc has been made.  You are continuing to develop 
  1901.  tc, planning to create release 1.1 in a couple of months.  After a while your 
  1902.  customers start to complain about a fatal bug.  You check out release 1.0 (see 
  1903.  Tags) and find the bug (which turns out to have a trivial fix).  However, the 
  1904.  current revision of the sources are in a state of flux and are not expected to 
  1905.  be stable for at least another month.  There is no way to make a bugfix 
  1906.  release based on the newest sources. 
  1907.  
  1908.  The thing to do in a situation like this is to create a branch on the revision 
  1909.  trees for all the files that make up release 1.0 of tc.  You can then make 
  1910.  modifications to the branch without disturbing the main trunk.  When the 
  1911.  modifications are finished you can elect to either incorporate them on the 
  1912.  main trunk, or leave them on the branch. 
  1913.  
  1914.  
  1915. ΓòÉΓòÉΓòÉ 6.2. Creating a branch ΓòÉΓòÉΓòÉ
  1916.  
  1917.  You can create a branch with tag -b; for example, assuming you're in a working 
  1918.  copy: 
  1919.  
  1920.                       $ cvs tag -b rel-1-0-patches
  1921.  
  1922.  This splits off a branch based on the current revisions in the working copy, 
  1923.  assigning that branch the name 'rel-1-0-patches'. 
  1924.  
  1925.  It is important to understand that branches get created in the repository, not 
  1926.  in the working copy.  Creating a branch based on current revisions, as the 
  1927.  above example does, will not automatically switch the working copy to be on 
  1928.  the new branch.  For information on how to do that, see Accessing branches. 
  1929.  
  1930.  You can also create a branch without reference to any working copy, by using 
  1931.  rtag: 
  1932.  
  1933.                       $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
  1934.  
  1935.  '-r rel-1-0' says that this branch should be rooted at the revision that 
  1936.  corresponds to the tag 'rel-1-0'.  It need not be the most recent revision -- 
  1937.  it's often useful to split a branch off an old revision (for example, when 
  1938.  fixing a bug in a past release otherwise known to be stable). 
  1939.  
  1940.  As with 'tag', the '-b' flag tells rtag to create a branch (rather than just a 
  1941.  symbolic revision name).  Note that the numeric revision number that matches 
  1942.  'rel-1-0' will probably be different from file to file. 
  1943.  
  1944.  So, the full effect of the command is to create a new branch -- named 
  1945.  'rel-1-0-patches' -- in module 'tc', rooted in the revision tree at the point 
  1946.  tagged by 'rel-1-0'. 
  1947.  
  1948.  
  1949. ΓòÉΓòÉΓòÉ 6.3. Accessing branches ΓòÉΓòÉΓòÉ
  1950.  
  1951.  You can retrieve a branch in one of two ways: by checking it out fresh from 
  1952.  the repository, or by switching an existing working copy over to the branch. 
  1953.  
  1954.  To check out a branch from the repository, invoke 'checkout' with the '-r' 
  1955.  flag, followed by the tag name of the branch (see Creating a branch): 
  1956.  
  1957.                       $ cvs checkout -r rel-1-0-patches tc
  1958.  
  1959.  Or, if you already have a working copy, you can switch it to a given branch 
  1960.  with 'update -r': 
  1961.  
  1962.                       $ cvs update -r rel-1-0-patches tc
  1963.  
  1964.  or equivalently: 
  1965.  
  1966.                       $ cd tc
  1967.                       $ cvs update -r rel-1-0-patches
  1968.  
  1969.  It does not matter if the working copy was originally on the main trunk or on 
  1970.  some other branch -- the above command will switch it to the named branch. 
  1971.  And similarly to a regular 'update' command, 'update -r' merges any changes 
  1972.  you have made, notifying you of conflicts where they occur. 
  1973.  
  1974.  Once you have a working copy tied to a particular branch, it remains there 
  1975.  until you tell it otherwise. This means that changes checked in from the 
  1976.  working copy will add new revisions on that branch, while leaving the main 
  1977.  trunk and other branches unaffected. 
  1978.  
  1979.  To find out what branch a working copy is on, you can use the 'status' 
  1980.  command.  In its output, look for the field named 'Sticky tag' (see Sticky 
  1981.  tags) -- that's CVS's way of telling you the branch, if any, of the current 
  1982.  working files: 
  1983.  
  1984.                       $ cvs status -v driver.c backend.c
  1985.                       ===================================================================
  1986.                       File: driver.c      Status: Up-to-date
  1987.                         Version:       1.7   Sat Dec  5 18:25:54 1992
  1988.                         RCS Version:     1.7   /u/cvsroot/yoyodyne/tc/driver.c,v
  1989.                         Sticky Tag:     rel-1-0-patches (branch: 1.7.2)
  1990.                         Sticky Date:     (none)
  1991.                         Sticky Options:   (none)
  1992.                         Existing Tags:
  1993.                           rel-1-0-patches       (branch: 1.7.2)
  1994.                           rel-1-0           (revision: 1.7)
  1995.                       ===================================================================
  1996.                       File: backend.c     Status: Up-to-date
  1997.                         Version:       1.4   Tue Dec  1 14:39:01 1992
  1998.                         RCS Version:     1.4   /u/cvsroot/yoyodyne/tc/backend.c,v
  1999.                         Sticky Tag:     rel-1-0-patches (branch: 1.4.2)
  2000.                         Sticky Date:     (none)
  2001.                         Sticky Options:   (none)
  2002.                         Existing Tags:
  2003.                           rel-1-0-patches       (branch: 1.4.2)
  2004.                           rel-1-0           (revision: 1.4)
  2005.                           rel-0-4           (revision: 1.4)
  2006.  
  2007.  Don't be confused by the fact that the branch numbers for each file are 
  2008.  different ('1.7.2' and '1.4.2' respectively).  The branch tag is the same, 
  2009.  'rel-1-0-patches', and the files are indeed on the same branch.  The numbers 
  2010.  simply reflect the point in each file's revision history at which the branch 
  2011.  was made.  In the above example, one can deduce that 'driver.c' had been 
  2012.  through more changes than 'backend.c' before this branch was created. 
  2013.  
  2014.  See Branches and revisions for details about how branch numbers are 
  2015.  constructed. 
  2016.  
  2017.  
  2018. ΓòÉΓòÉΓòÉ 6.4. Branches and revisions ΓòÉΓòÉΓòÉ
  2019.  
  2020.  Ordinarily, a file's revision history is a linear series of increments (see 
  2021.  Revision numbers): 
  2022.  
  2023.                           +-----+   +-----+   +-----+   +-----+   +-----+
  2024.                           ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
  2025.                           +-----+   +-----+   +-----+   +-----+   +-----+
  2026.  
  2027.  However, CVS is not limited to linear development.  The revision tree can be 
  2028.  split into branches, where each branch is a self-maintained line of 
  2029.  development.  Changes made on one branch can easily be moved back to the main 
  2030.  trunk. 
  2031.  
  2032.  Each branch has a branch number, consisting of an odd number of 
  2033.  period-separated decimal integers.  The branch number is created by appending 
  2034.  an integer to the revision number where the corresponding branch forked off. 
  2035.  Having branch numbers allows more than one branch to be forked off from a 
  2036.  certain revision. 
  2037.  
  2038.  All revisions on a branch have revision numbers formed by appending an ordinal 
  2039.  number to the branch number. The following figure illustrates branching with 
  2040.  an example. 
  2041.  
  2042.                                          +-------------+
  2043.                             Branch 1.2.2.3.2 ->     ! 1.2.2.3.2.1 !
  2044.                                         / +-------------+
  2045.                                         /
  2046.                                        /
  2047.                                +---------+   +---------+   +---------+
  2048.                       Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
  2049.                               / +---------+   +---------+   +---------+
  2050.                              /
  2051.                              /
  2052.                       +-----+   +-----+   +-----+   +-----+   +-----+
  2053.                       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !  <- The main trunk
  2054.                       +-----+   +-----+   +-----+   +-----+   +-----+
  2055.                               !
  2056.                               !
  2057.                               !  +---------+   +---------+   +---------+
  2058.                       Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
  2059.                                 +---------+   +---------+   +---------+
  2060.  
  2061.  The exact details of how the branch number is constructed is not something you 
  2062.  normally need to be concerned about, but here is how it works: When CVS 
  2063.  creates a branch number it picks the first unused even integer, starting with 
  2064.  2.  So when you want to create a branch from revision 6.4 it will be numbered 
  2065.  6.4.2.  All branch numbers ending in a zero (such as 6.4.0) are used 
  2066.  internally by CVS (see Magic branch numbers).  The branch 1.1.1 has a special 
  2067.  meaning.  See Tracking sources. 
  2068.  
  2069.  
  2070. ΓòÉΓòÉΓòÉ 6.5. Magic branch numbers ΓòÉΓòÉΓòÉ
  2071.  
  2072.  This section describes a CVS feature called magic branches.  For most 
  2073.  purposes, you need not worry about magic branches; CVS handles them for you. 
  2074.  However, they are visible to you in certain circumstances, so it may be useful 
  2075.  to have some idea of how it works. 
  2076.  
  2077.  Externally, branch numbers consist of an odd number of dot-separated decimal 
  2078.  integers.  See Revision numbers.  That is not the whole truth, however.  For 
  2079.  efficiency reasons CVS sometimes inserts an extra 0 in the second rightmost 
  2080.  position (1.2.4 becomes 1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 
  2081.  on). 
  2082.  
  2083.  CVS does a pretty good job at hiding these so called magic branches, but in a 
  2084.  few places the hiding is incomplete: 
  2085.  
  2086.      The magic branch number appears in the output from cvs log. 
  2087.  
  2088.      You cannot specify a symbolic branch name to cvs admin. 
  2089.  
  2090.  You can use the admin command to reassign a symbolic name to a branch the way 
  2091.  RCS expects it to be.  If R4patches is assigned to the branch 1.4.2 (magic 
  2092.  branch number 1.4.0.2) in file 'numbers.c' you can do this: 
  2093.  
  2094.                       $ cvs admin -NR4patches:1.4.2 numbers.c
  2095.  
  2096.  It only works if at least one revision is already committed on the branch.  Be 
  2097.  very careful so that you do not assign the tag to the wrong number.  (There is 
  2098.  no way to see how the tag was assigned yesterday). 
  2099.  
  2100.  
  2101. ΓòÉΓòÉΓòÉ 6.6. Merging an entire branch ΓòÉΓòÉΓòÉ
  2102.  
  2103.  You can merge changes made on a branch into your working copy by giving the 
  2104.  '-j branch' flag to the update command.  With one '-j branch' option it merges 
  2105.  the changes made between the point where the branch forked and newest revision 
  2106.  on that branch (into your working copy). 
  2107.  
  2108.  The '-j' stands for ``join''. 
  2109.  
  2110.  Consider this revision tree: 
  2111.  
  2112.                       +-----+   +-----+   +-----+   +-----+
  2113.                       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !    <- The main trunk
  2114.                       +-----+   +-----+   +-----+   +-----+
  2115.                               !
  2116.                               !
  2117.                               !  +---------+   +---------+
  2118.                       Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  2119.                                 +---------+   +---------+
  2120.  
  2121.  The branch 1.2.2 has been given the tag (symbolic name) 'R1fix'.  The 
  2122.  following example assumes that the module 'mod' contains only one file, 'm.c'. 
  2123.  
  2124.                       $ cvs checkout mod        # Retrieve the latest revision, 1.4
  2125.                       $ cvs update -j R1fix m.c     # Merge all changes made on the branch,
  2126.                                        # i.e. the changes between revision 1.2
  2127.                                        # and 1.2.2.2, into your working copy
  2128.                                        # of the file.
  2129.                       $ cvs commit -m "Included R1fix" # Create revision 1.5.
  2130.  
  2131.  A conflict can result from a merge operation.  If that happens, you should 
  2132.  resolve it before committing the new revision.  See Conflicts example. 
  2133.  
  2134.  The checkout command also supports the '-j branch' flag.  The same effect as 
  2135.  above could be achieved with this: 
  2136.  
  2137.                       $ cvs checkout -j R1fix mod
  2138.                       $ cvs commit -m "Included R1fix"
  2139.  
  2140.  
  2141. ΓòÉΓòÉΓòÉ 6.7. Merging from a branch several times ΓòÉΓòÉΓòÉ
  2142.  
  2143.  Continuing our example, the revision tree now looks like this: 
  2144.  
  2145.                       +-----+   +-----+   +-----+   +-----+   +-----+
  2146.                       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !  <- The main trunk
  2147.                       +-----+   +-----+   +-----+   +-----+   +-----+
  2148.                               !              *
  2149.                               !              *
  2150.                               !  +---------+   +---------+
  2151.                       Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  2152.                                 +---------+   +---------+
  2153.  
  2154.  where the starred line represents the merge from the 'R1fix' branch to the 
  2155.  main trunk, as just discussed. 
  2156.  
  2157.  Now suppose that development continues on the 'R1fix' branch: 
  2158.  
  2159.                       +-----+   +-----+   +-----+   +-----+   +-----+
  2160.                       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !  <- The main trunk
  2161.                       +-----+   +-----+   +-----+   +-----+   +-----+
  2162.                               !              *
  2163.                               !              *
  2164.                               !  +---------+   +---------+   +---------+
  2165.                       Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
  2166.                                 +---------+   +---------+   +---------+
  2167.  
  2168.  and then you want to merge those new changes onto the main trunk.  If you just 
  2169.  use the cvs update -j R1fix m.c command again, CVS will attempt to merge again 
  2170.  the changes which you have already merged, which can have undesirable side 
  2171.  effects. 
  2172.  
  2173.  So instead you need to specify that you only want to merge the changes on the 
  2174.  branch which have not yet been merged into the trunk.  To do that you specify 
  2175.  two '-j' options, and CVS merges the changes from the first revision to the 
  2176.  second revision.  For example, in this case the simplest way would be 
  2177.  
  2178.                       cvs update -j 1.2.2.2 -j R1fix m.c   # Merge changes from 1.2.2.2 to the
  2179.                                          # head of the R1fix branch
  2180.  
  2181.  The problem with this is that you need to specify the 1.2.2.2 revision 
  2182.  manually.  A slightly better approach might be to use the date the last merge 
  2183.  was done: 
  2184.  
  2185.                       cvs update -j R1fix:yesterday -j R1fix m.c
  2186.  
  2187.  Better yet, tag the R1fix branch after every merge into the trunk, and then 
  2188.  use that tag for subsequent merges: 
  2189.  
  2190.                       cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
  2191.  
  2192.  
  2193. ΓòÉΓòÉΓòÉ 6.8. Merging differences between any two revisions ΓòÉΓòÉΓòÉ
  2194.  
  2195.  With two '-j revision' flags, the update (and checkout) command can merge the 
  2196.  differences between any two revisions into your working file. 
  2197.  
  2198.                       $ cvs update -j 1.5 -j 1.3 backend.c
  2199.  
  2200.  will remove all changes made between revision 1.3 and 1.5.  Note the order of 
  2201.  the revisions! 
  2202.  
  2203.  If you try to use this option when operating on multiple files, remember that 
  2204.  the numeric revisions will probably be very different between the various 
  2205.  files that make up a module.  You almost always use symbolic tags rather than 
  2206.  revision numbers when operating on multiple files. 
  2207.  
  2208.  
  2209. ΓòÉΓòÉΓòÉ 6.9. Merging can add or remove files ΓòÉΓòÉΓòÉ
  2210.  
  2211.  If the changes which you are merging involve removing or adding some files, 
  2212.  update -j will reflect such additions or removals. 
  2213.  
  2214.  For example: 
  2215.  
  2216.                       cvs update -A
  2217.                       touch a b c
  2218.                       cvs add a b c ; cvs ci -m "added" a b c
  2219.                       cvs tag -b branchtag
  2220.                       cvs update -r branchtag
  2221.                       touch d ; cvs add d
  2222.                       rm a ; cvs rm a
  2223.                       cvs ci -m "added d, removed a"
  2224.                       cvs update -A
  2225.                       cvs update -jbranchtag
  2226.  
  2227.  After these commands are executed and a 'cvs commit' is done, file 'a' will be 
  2228.  removed and file 'd' added in the main branch. 
  2229.  
  2230.  
  2231. ΓòÉΓòÉΓòÉ 7. Recursive behavior ΓòÉΓòÉΓòÉ
  2232.  
  2233.  Almost all of the subcommands of CVS work recursively when you specify a 
  2234.  directory as an argument.  For instance, consider this directory structure: 
  2235.  
  2236.                          $HOME
  2237.                           |
  2238.                           +--tc
  2239.                           |  |
  2240.                             +--CVS
  2241.                             |    (internal CVS files)
  2242.                             +--Makefile
  2243.                             +--backend.c
  2244.                             +--driver.c
  2245.                             +--frontend.c
  2246.                             +--parser.c
  2247.                             +--man
  2248.                             |   |
  2249.                             |   +--CVS
  2250.                             |   |  (internal CVS files)
  2251.                             |   +--tc.1
  2252.                             |
  2253.                             +--testing
  2254.                                |
  2255.                                +--CVS
  2256.                                |  (internal CVS files)
  2257.                                +--testpgm.t
  2258.                                +--test2.t
  2259.  
  2260.  If 'tc' is the current working directory, the following is true: 
  2261.  
  2262.      'cvs update testing' is equivalent to 
  2263.  
  2264.                       cvs update testing/testpgm.t testing/test2.t
  2265.  
  2266.      'cvs update testing man' updates all files in the subdirectories 
  2267.  
  2268.      'cvs update .' or just 'cvs update' updates all files in the tc module 
  2269.  
  2270.  If no arguments are given to update it will update all files in the current 
  2271.  working directory and all its subdirectories.  In other words, '.' is a 
  2272.  default argument to update.  This is also true for most of the CVS 
  2273.  subcommands, not only the update command. 
  2274.  
  2275.  The recursive behavior of the CVS subcommands can be turned off with the '-l' 
  2276.  option. Conversely, the '-R' option can be used to force recursion if '-l' is 
  2277.  specified in '~/.cvsrc' (see ~/.cvsrc). 
  2278.  
  2279.                       $ cvs update -l     # Don't update files in subdirectories
  2280.  
  2281.  
  2282. ΓòÉΓòÉΓòÉ 8. Adding, removing, and renaming files and directories ΓòÉΓòÉΓòÉ
  2283.  
  2284.  In the course of a project, one will often add new files.  Likewise with 
  2285.  removing or renaming, or with directories.  The general concept to keep in 
  2286.  mind in all these cases is that instead of making an irreversible change you 
  2287.  want CVS to record the fact that a change has taken place, just as with 
  2288.  modifying an existing file.  The exact mechanisms to do this in CVS vary 
  2289.  depending on the situation. 
  2290.  
  2291.  Adding files                  Adding files 
  2292.  Removing files                Removing files 
  2293.  Removing directories          Removing directories 
  2294.  Moving files                  Moving and renaming files 
  2295.  Moving directories            Moving and renaming directories 
  2296.  
  2297.  
  2298. ΓòÉΓòÉΓòÉ 8.1. Adding files to a directory ΓòÉΓòÉΓòÉ
  2299.  
  2300.  To add a new file to a directory, follow these steps. 
  2301.  
  2302.      You must have a working copy of the directory. See Getting the source. 
  2303.  
  2304.      Create the new file inside your working copy of the directory. 
  2305.  
  2306.      Use 'cvs add filename' to tell CVS that you want to version control the 
  2307.       file.  If the file contains binary data, specify '-kb' (see Binary 
  2308.       files). 
  2309.  
  2310.      Use 'cvs commit filename' to actually check in the file into the 
  2311.       repository.  Other developers cannot see the file until you perform this 
  2312.       step. 
  2313.  
  2314.  You can also use the add command to add a new directory. Unlike most other 
  2315.  commands, the add command is not recursive.  You cannot even type 'cvs add 
  2316.  foo/bar'!  Instead, you have to 
  2317.  
  2318.                       $ cd foo
  2319.                       $ cvs add bar
  2320.  
  2321.  cvs add  [-k kflag] [-m message] files ┬╖┬╖┬╖   (Command) 
  2322.  
  2323.            Schedule files to be added to the repository. The files or 
  2324.            directories specified with add must already exist in the current 
  2325.            directory.  To add a whole new directory hierarchy to the source 
  2326.            repository (for example, files received from a third-party vendor), 
  2327.            use the import command instead.  See import. 
  2328.  
  2329.            The added files are not placed in the source repository until you 
  2330.            use commit to make the change permanent.  Doing an add on a file 
  2331.            that was removed with the remove command will undo the effect of the 
  2332.            remove, unless a commit command intervened.  See Removing files, for 
  2333.            an example. 
  2334.  
  2335.            The '-k' option specifies the default way that this file will be 
  2336.            checked out; for more information see Substitution modes. 
  2337.  
  2338.            The '-m' option specifies a description for the file.  This 
  2339.            description appears in the history log (if it is enabled, see 
  2340.            history file).  It will also be saved in the version history inside 
  2341.            the repository when the file is committed.  The log command displays 
  2342.            this description.  The description can be changed using 'admin -t'. 
  2343.            See admin.  If you omit the '-m description' flag, an empty string 
  2344.            will be used.  You will not be prompted for a description. 
  2345.  
  2346.  For example, the following commands add the file 'backend.c' to the 
  2347.  repository: 
  2348.  
  2349.                       $ cvs add backend.c
  2350.                       $ cvs commit -m "Early version. Not yet compilable." backend.c
  2351.  
  2352.  When you add a file it is added only on the branch which you are working on 
  2353.  (see Branching and merging).  You can later merge the additions to another 
  2354.  branch if you want (see Merging adds and removals). 
  2355.  
  2356.  
  2357. ΓòÉΓòÉΓòÉ 8.2. Removing files ΓòÉΓòÉΓòÉ
  2358.  
  2359.  Modules change.  New files are added, and old files disappear.  Still, you 
  2360.  want to be able to retrieve an exact copy of old releases. 
  2361.  
  2362.  Here is what you can do to remove a file, but remain able to retrieve old 
  2363.  revisions: 
  2364.  
  2365.      Make sure that you have not made any uncommitted modifications to the 
  2366.       file.  See Viewing differences, for one way to do that.  You can also use 
  2367.       the status or update command.  If you remove the file without committing 
  2368.       your changes, you will of course not be able to retrieve the file as it 
  2369.       was immediately before you deleted it. 
  2370.  
  2371.      Remove the file from your working copy of the directory. You can for 
  2372.       instance use rm. 
  2373.  
  2374.      Use 'cvs remove filename' to tell CVS that you really want to delete the 
  2375.       file. 
  2376.  
  2377.      Use 'cvs commit filename' to actually perform the removal of the file 
  2378.       from the repository. 
  2379.  
  2380.  When you commit the removal of the file, CVS records the fact that the file no 
  2381.  longer exists.  It is possible for a file to exist on only some branches and 
  2382.  not on others, or to re-add another file with the same name later.  CVS will 
  2383.  correctly create or not create the file, based on the '-r' and '-D' options 
  2384.  specified to checkout or update. 
  2385.  
  2386.  cvs remove  [options] files ┬╖┬╖┬╖   (Command) 
  2387.  
  2388.            Schedule file(s) to be removed from the repository (files which have 
  2389.            not already been removed from the working directory are not 
  2390.            processed).  This command does not actually remove the file from the 
  2391.            repository until you commit the removal.  For a full list of 
  2392.            options, see Invoking CVS. 
  2393.  
  2394.  Here is an example of removing several files: 
  2395.  
  2396.                       $ cd test
  2397.                       $ rm *.c
  2398.                       $ cvs remove
  2399.                       cvs remove: Removing .
  2400.                       cvs remove: scheduling a.c for removal
  2401.                       cvs remove: scheduling b.c for removal
  2402.                       cvs remove: use 'cvs commit' to remove these files permanently
  2403.                       $ cvs ci -m "Removed unneeded files"
  2404.                       cvs commit: Examining .
  2405.                       cvs commit: Committing .
  2406.  
  2407.  As a convenience you can remove the file and cvs remove it in one step, by 
  2408.  specifying the '-f' option.  For example, the above example could also be done 
  2409.  like this: 
  2410.  
  2411.                       $ cd test
  2412.                       $ cvs remove -f *.c
  2413.                       cvs remove: scheduling a.c for removal
  2414.                       cvs remove: scheduling b.c for removal
  2415.                       cvs remove: use 'cvs commit' to remove these files permanently
  2416.                       $ cvs ci -m "Removed unneeded files"
  2417.                       cvs commit: Examining .
  2418.                       cvs commit: Committing .
  2419.  
  2420.  If you execute remove for a file, and then change your mind before you commit, 
  2421.  you can undo the remove with an add command. 
  2422.  
  2423.                       $ ls
  2424.                       CVS  ja.h  oj.c
  2425.                       $ rm oj.c
  2426.                       $ cvs remove oj.c
  2427.                       cvs remove: scheduling oj.c for removal
  2428.                       cvs remove: use 'cvs commit' to remove this file permanently
  2429.                       $ cvs add oj.c
  2430.                       U oj.c
  2431.                       cvs add: oj.c, version 1.1.1.1, resurrected
  2432.  
  2433.  If you realize your mistake before you run the remove command you can use 
  2434.  update to resurrect the file: 
  2435.  
  2436.                       $ rm oj.c
  2437.                       $ cvs update oj.c
  2438.                       cvs update: warning: oj.c was lost
  2439.                       U oj.c
  2440.  
  2441.  When you remove a file it is removed only on the branch which you are working 
  2442.  on (see Branching and merging).  You can later merge the removals to another 
  2443.  branch if you want (see Merging adds and removals). 
  2444.  
  2445.  
  2446. ΓòÉΓòÉΓòÉ 8.3. Removing directories ΓòÉΓòÉΓòÉ
  2447.  
  2448.  In concept removing directories is somewhat similar to removing files---you 
  2449.  want the directory to not exist in your current working directories, but you 
  2450.  also want to be able to retrieve old releases in which the directory existed. 
  2451.  
  2452.  The way that you remove a directory is to remove all the files in it.  You 
  2453.  don't remove the directory itself; there is no way to do that. Instead you 
  2454.  specify the '-P' option to cvs update, cvs checkout, or cvs export, which will 
  2455.  cause CVS to remove empty directories from working directories.  Probably the 
  2456.  best way to do this is to always specify '-P'; if you want an empty directory 
  2457.  then put a dummy file (for example '.keepme') in it to prevent '-P' from 
  2458.  removing it. 
  2459.  
  2460.  Note that '-P' is implied by the '-r' or '-D' options of checkout and export. 
  2461.  This way CVS will be able to correctly create the directory or not depending 
  2462.  on whether the particular version you are checking out contains any files in 
  2463.  that directory. 
  2464.  
  2465.  
  2466. ΓòÉΓòÉΓòÉ 8.4. Moving and renaming files ΓòÉΓòÉΓòÉ
  2467.  
  2468.  Moving files to a different directory or renaming them is not difficult, but 
  2469.  some of the ways in which this works may be non-obvious.  (Moving or renaming 
  2470.  a directory is even harder.  See Moving directories.). 
  2471.  
  2472.  The examples below assume that the file old is renamed to new. 
  2473.  
  2474.  Outside                       The normal way to Rename 
  2475.  Inside                        A tricky, alternative way 
  2476.  Rename by copying             Another tricky, alternative way 
  2477.  
  2478.  
  2479. ΓòÉΓòÉΓòÉ 8.4.1. The Normal way to Rename ΓòÉΓòÉΓòÉ
  2480.  
  2481.  The normal way to move a file is to copy old to new, and then issue the normal 
  2482.  CVS commands to remove old from the repository, and add new to it. 
  2483.  
  2484.                       $ mv old new
  2485.                       $ cvs remove old
  2486.                       $ cvs add new
  2487.                       $ cvs commit -m "Renamed old to new" old new
  2488.  
  2489.  This is the simplest way to move a file, it is not error-prone, and it 
  2490.  preserves the history of what was done.  Note that to access the history of 
  2491.  the file you must specify the old or the new name, depending on what portion 
  2492.  of the history you are accessing.  For example, cvs log old will give the log 
  2493.  up until the time of the rename. 
  2494.  
  2495.  When new is committed its revision numbers will start again, usually at 1.1, 
  2496.  so if that bothers you, use the '-r rev' option to commit.  For more 
  2497.  information see Assigning revisions. 
  2498.  
  2499.  
  2500. ΓòÉΓòÉΓòÉ 8.4.2. Moving the history file ΓòÉΓòÉΓòÉ
  2501.  
  2502.  This method is more dangerous, since it involves moving files inside the 
  2503.  repository.  Read this entire section before trying it out! 
  2504.  
  2505.                       $ cd $CVSROOT/module
  2506.                       $ mv old,v new,v
  2507.  
  2508.  Advantages: 
  2509.  
  2510.      The log of changes is maintained intact. 
  2511.  
  2512.      The revision numbers are not affected. 
  2513.  
  2514.  Disadvantages: 
  2515.  
  2516.      Old releases of the module cannot easily be fetched from the repository. 
  2517.       (The file will show up as new even in revisions from the time before it 
  2518.       was renamed). 
  2519.  
  2520.      There is no log information of when the file was renamed. 
  2521.  
  2522.      Nasty things might happen if someone accesses the history file while you 
  2523.       are moving it.  Make sure no one else runs any of the CVS commands while 
  2524.       you move it. 
  2525.  
  2526.  
  2527. ΓòÉΓòÉΓòÉ 8.4.3. Copying the history file ΓòÉΓòÉΓòÉ
  2528.  
  2529.  This way also involves direct modifications to the repository.  It is safe, 
  2530.  but not without drawbacks. 
  2531.  
  2532.                       # Copy the RCS file inside the repository
  2533.                       $ cd $CVSROOT/module
  2534.                       $ cp old,v new,v
  2535.                       # Remove the old file
  2536.                       $ cd ~/module
  2537.                       $ rm old
  2538.                       $ cvs remove old
  2539.                       $ cvs commit old
  2540.                       # Remove all tags from new
  2541.                       $ cvs update new
  2542.                       $ cvs log new       # Remember the non-branch tag names
  2543.                       $ cvs tag -d tag1 new
  2544.                       $ cvs tag -d tag2 new
  2545.                       ┬╖┬╖┬╖
  2546.  
  2547.  By removing the tags you will be able to check out old revisions of the 
  2548.  module. 
  2549.  Advantages: 
  2550.  
  2551.      Checking out old revisions works correctly, as long as you use '-rtag' 
  2552.       and not '-Ddate' to retrieve the revisions. 
  2553.  
  2554.      The log of changes is maintained intact. 
  2555.  
  2556.      The revision numbers are not affected. 
  2557.  
  2558.  Disadvantages: 
  2559.  
  2560.      You cannot easily see the history of the file across the rename. 
  2561.  
  2562.  
  2563. ΓòÉΓòÉΓòÉ 8.5. Moving and renaming directories ΓòÉΓòÉΓòÉ
  2564.  
  2565.  The normal way to rename or move a directory is to rename or move each file 
  2566.  within it as described in Outside.  Then check out with the '-P' option, as 
  2567.  described in Removing directories. 
  2568.  
  2569.  If you really want to hack the repository to rename or delete a directory in 
  2570.  the repository, you can do it like this: 
  2571.  
  2572.    1. Inform everyone who has a copy of the module that the directory will be 
  2573.       renamed.  They should commit all their changes, and remove their working 
  2574.       copies of the module, before you take the steps below. 
  2575.  
  2576.    2. Rename the directory inside the repository. 
  2577.  
  2578.                       $ cd $CVSROOT/module
  2579.                       $ mv old-dir new-dir
  2580.  
  2581.    3. Fix the CVS administrative files, if necessary (for instance if you 
  2582.       renamed an entire module). 
  2583.  
  2584.    4. Tell everyone that they can check out the module and continue working. 
  2585.  
  2586.  If someone had a working copy of the module the CVS commands will cease to 
  2587.  work for him, until he removes the directory that disappeared inside the 
  2588.  repository. 
  2589.  
  2590.  It is almost always better to move the files in the directory instead of 
  2591.  moving the directory.  If you move the directory you are unlikely to be able 
  2592.  to retrieve old releases correctly, since they probably depend on the name of 
  2593.  the directories. 
  2594.  
  2595.  
  2596. ΓòÉΓòÉΓòÉ 9. History browsing ΓòÉΓòÉΓòÉ
  2597.  
  2598.  Once you have used CVS to store a version control history---what files have 
  2599.  changed when, how, and by whom, there are a variety of mechanisms for looking 
  2600.  through the history. 
  2601.  
  2602.  log messages                  Log messages 
  2603.  history database              The history database 
  2604.  user-defined logging          User-defined logging 
  2605.  annotate                      What revision modified each line of a file? 
  2606.  
  2607.  
  2608. ΓòÉΓòÉΓòÉ 9.1. Log messages ΓòÉΓòÉΓòÉ
  2609.  
  2610.  Whenever you commit a file you specify a log message. 
  2611.  
  2612.  To look through the log messages which have been specified for every revision 
  2613.  which has been committed, use the cvs log command (see log). 
  2614.  
  2615.  
  2616. ΓòÉΓòÉΓòÉ 9.2. The history database ΓòÉΓòÉΓòÉ
  2617.  
  2618.  You can use the history file (see history file) to log various CVS actions. 
  2619.  To retrieve the information from the history file, use the cvs history command 
  2620.  (see history). 
  2621.  
  2622.  
  2623. ΓòÉΓòÉΓòÉ 9.3. User-defined logging ΓòÉΓòÉΓòÉ
  2624.  
  2625.  You can customize CVS to log various kinds of actions, in whatever manner you 
  2626.  choose.  These mechanisms operate by executing a script at various times.  The 
  2627.  script might append a message to a file listing the information and the 
  2628.  programmer who created it, or send mail to a group of developers, or, perhaps, 
  2629.  post a message to a particular newsgroup.  To log commits, use the 'loginfo' 
  2630.  file (see loginfo). To log commits, checkouts, exports, and tags, 
  2631.  respectively, you can also use the '-i', '-o', '-e', and '-t' options in the 
  2632.  modules file.  For a more flexible way of giving notifications to various 
  2633.  users, which requires less in the way of keeping centralized scripts up to 
  2634.  date, use the cvs watch add command (see Getting Notified); this command is 
  2635.  useful even if you are not using cvs watch on. 
  2636.  
  2637.  The 'taginfo' file defines programs to execute when someone executes a tag or 
  2638.  rtag command.  The 'taginfo' file has the standard form for administrative 
  2639.  files (see Administrative files), where each line is a regular expression 
  2640.  followed by a command to execute.  The arguments passed to the command are, in 
  2641.  order, the tagname, operation (add for tag, mov for tag -F, and del for tag 
  2642.  -d), repository, and any remaining are pairs of filename revision.  A non-zero 
  2643.  exit of the filter program will cause the tag to be aborted. 
  2644.  
  2645.  Here is an example of using taginfo to log tag and rtag commands.  In the 
  2646.  taginfo file put: 
  2647.  
  2648.                       ALL /usr/local/cvsroot/CVSROOT/loggit
  2649.  
  2650.  Where '/usr/local/cvsroot/CVSROOT/loggit' contains the following script: 
  2651.  
  2652.                       #!/bin/sh
  2653.                       echo "$@" >>/home/kingdon/cvsroot/CVSROOT/taglog
  2654.  
  2655.  
  2656. ΓòÉΓòÉΓòÉ 9.4. Annotate command ΓòÉΓòÉΓòÉ
  2657.  
  2658.  cvs annotate  [-flR] [-r rev|-D date] files ┬╖┬╖┬╖   (Command) 
  2659.  
  2660.            For each file in files, print the head revision of the trunk, 
  2661.            together with information on the last modification for each line. 
  2662.            For example: 
  2663.  
  2664.                                           $ cvs annotate ssfile
  2665.                                           Annotations for ssfile
  2666.                                           ***************
  2667.                                           1.1      (mary   27-Mar-96): ssfile line 1
  2668.                                           1.2      (joe    28-Mar-96): ssfile line 2
  2669.  
  2670.            The file 'ssfile' currently contains two lines. The ssfile line 1 
  2671.            line was checked in by mary on March 27.  Then, on March 28, joe 
  2672.            added a line ssfile line 2, without modifying the ssfile line 1 
  2673.            line.  This report doesn't tell you anything about lines which have 
  2674.            been deleted or replaced; you need to use cvs diff for that (see 
  2675.            diff). 
  2676.  
  2677.  The options to cvs annotate are listed in Invoking CVS, and can be used to 
  2678.  select the files and revisions to annotate.  The options are described in more 
  2679.  detail in Common options. 
  2680.  
  2681.  
  2682. ΓòÉΓòÉΓòÉ 10. Handling binary files ΓòÉΓòÉΓòÉ
  2683.  
  2684.  The most common use for CVS is to store text files.  With text files, CVS can 
  2685.  merge revisions, display the differences between revisions in a human-visible 
  2686.  fashion, and other such operations. However, if you are willing to give up a 
  2687.  few of these abilities, CVS can store binary files.  For example, one might 
  2688.  store a web site in CVS including both text files and binary images. 
  2689.  
  2690.  Binary why                    More details on issues with binary files 
  2691.  Binary howto                  How to store them 
  2692.  
  2693.  
  2694. ΓòÉΓòÉΓòÉ 10.1. The issues with binary files ΓòÉΓòÉΓòÉ
  2695.  
  2696.  While the need to manage binary files may seem obvious if the files that you 
  2697.  customarily work with are binary, putting them into version control does 
  2698.  present some additional issues. 
  2699.  
  2700.  One basic function of version control is to show the differences between two 
  2701.  revisions.  For example, if someone else checked in a new version of a file, 
  2702.  you may wish to look at what they changed and determine whether their changes 
  2703.  are good.  For text files, CVS provides this functionality via the cvs diff 
  2704.  command.  For binary files, it may be possible to extract the two revisions 
  2705.  and then compare them with a tool external to CVS (for example, word 
  2706.  processing software often has such a feature).  If there is no such tool, one 
  2707.  must track changes via other mechanisms, such as urging people to write good 
  2708.  log messages, and hoping that the changes they actually made were the changes 
  2709.  that they intended to make. 
  2710.  
  2711.  Another ability of a version control system is the ability to merge two 
  2712.  revisions.  For CVS this happens in two contexts.  The first is when users 
  2713.  make changes in separate working directories (see Multiple developers).  The 
  2714.  second is when one merges explicitly with the 'update -j' command (see 
  2715.  Branching and merging). 
  2716.  
  2717.  In the case of text files, CVS can merge changes made independently, and 
  2718.  signal a conflict if the changes conflict.  With binary files, the best that 
  2719.  CVS can do is present the two different copies of the file, and leave it to 
  2720.  the user to resolve the conflict.  The user may choose one copy or the other, 
  2721.  or may run an external merge tool which knows about that particular file 
  2722.  format, if one exists. Note that having the user merge relies primarily on the 
  2723.  user to not accidentally omit some changes, and thus is potentially error 
  2724.  prone. 
  2725.  
  2726.  If this process is thought to be undesirable, the best choice may be to avoid 
  2727.  merging.  To avoid the merges that result from separate working directories, 
  2728.  see the discussion of reserved checkouts (file locking) in Multiple 
  2729.  developers.  To avoid the merges resulting from branches, restrict use of 
  2730.  branches. 
  2731.  
  2732.  
  2733. ΓòÉΓòÉΓòÉ 10.2. How to store binary files ΓòÉΓòÉΓòÉ
  2734.  
  2735.  There are two issues with using CVS to store binary files.  The first is that 
  2736.  CVS by default converts line endings between the canonical form in which they 
  2737.  are stored in the repository (linefeed only), and the form appropriate to the 
  2738.  operating system in use on the client (for example, carriage return followed 
  2739.  by line feed for Windows NT). 
  2740.  
  2741.  The second is that a binary file might happen to contain data which looks like 
  2742.  a keyword (see Keyword substitution), so keyword expansion must be turned off. 
  2743.  
  2744.  The '-kb' option available with some CVS commands insures that neither line 
  2745.  ending conversion nor keyword expansion will be done. 
  2746.  
  2747.  Here is an example of how you can create a new file using the '-kb' flag: 
  2748.  
  2749.                       $ echo '${}Id$' > kotest
  2750.                       $ cvs add -kb -m"A test file" kotest
  2751.                       $ cvs ci -m"First checkin; contains a keyword" kotest
  2752.  
  2753.  If a file accidentally gets added without '-kb', one can use the cvs admin 
  2754.  command to recover. For example: 
  2755.  
  2756.                       $ echo '${}Id$' > kotest
  2757.                       $ cvs add -m"A test file" kotest
  2758.                       $ cvs ci -m"First checkin; contains a keyword" kotest
  2759.                       $ cvs admin -kb kotest
  2760.                       $ cvs update -A kotest
  2761.                       # For non-unix systems:
  2762.                       # Copy in a good copy of the file from outside CVS
  2763.                       $ cvs commit -m "make it binary" kotest
  2764.  
  2765.  When you check in the file 'kotest' the file is not preserved as a binary 
  2766.  file, because you did not check it in as a binary file.  The cvs admin -kb 
  2767.  command sets the default keyword substitution method for this file, but it 
  2768.  does not alter the working copy of the file that you have.  If you need to 
  2769.  cope with line endings (that is, you are using CVS on a non-unix system), then 
  2770.  you need to check in a new copy of the file, as shown by the cvs commit 
  2771.  command above. On unix, the cvs update -A command suffices. However, in using 
  2772.  cvs admin -k to change the keyword expansion, be aware that the keyword 
  2773.  expansion mode is not version controlled.  This means that, for example, that 
  2774.  if you have a text file in old releases, and a binary file with the same name 
  2775.  in new releases, CVS provides no way to check out the file in text or binary 
  2776.  mode depending on what version you are checking out.  There is no good 
  2777.  workaround for this problem. 
  2778.  
  2779.  You can also set a default for whether cvs add and cvs import treat a file as 
  2780.  binary based on its name; for example you could say that files who names end 
  2781.  in '.exe' are binary.  See Wrappers. There is currently no way to have CVS 
  2782.  detect whether a file is binary based on its contents.  The main difficulty 
  2783.  with designing such a feature is that it is not clear how to distinguish 
  2784.  between binary and non-binary files, and the rules to apply would vary 
  2785.  considerably with the operating system. 
  2786.  
  2787.  
  2788. ΓòÉΓòÉΓòÉ 11. Multiple developers ΓòÉΓòÉΓòÉ
  2789.  
  2790.  When more than one person works on a software project things often get 
  2791.  complicated.  Often, two people try to edit the same file simultaneously.  One 
  2792.  solution, known as file locking or reserved checkouts, is to allow only one 
  2793.  person to edit each file at a time. This is the only solution with some 
  2794.  version control systems, including RCS and SCCS.  Currently the usual way to 
  2795.  get reserved checkouts with CVS is the cvs admin -l command (see admin 
  2796.  options).  This is not as nicely integrated into CVS as the watch features, 
  2797.  described below, but it seems that most people with a need for reserved 
  2798.  checkouts find it adequate. It also may be possible to use the watches 
  2799.  features described below, together with suitable procedures (not enforced by 
  2800.  software), to avoid having two people edit at the same time. 
  2801.  
  2802.  The default model with CVS is known as unreserved checkouts.  In this model, 
  2803.  developers can edit their own working copy of a file simultaneously.  The 
  2804.  first person that commits his changes has no automatic way of knowing that 
  2805.  another has started to edit it.  Others will get an error message when they 
  2806.  try to commit the file.  They must then use CVS commands to bring their 
  2807.  working copy up to date with the repository revision.  This process is almost 
  2808.  automatic. 
  2809.  
  2810.  CVS also supports mechanisms which facilitate various kinds of communcation, 
  2811.  without actually enforcing rules like reserved checkouts do. 
  2812.  
  2813.  The rest of this chapter describes how these various models work, and some of 
  2814.  the issues involved in choosing between them. 
  2815.  
  2816.  File status                   A file can be in several states 
  2817.  Updating a file               Bringing a file up-to-date 
  2818.  Conflicts example             An informative example 
  2819.  Informing others              To cooperate you must inform 
  2820.  Concurrency                   Simultaneous repository access 
  2821.  Watches                       Mechanisms to track who is editing files 
  2822.  Choosing a model              Reserved or unreserved checkouts? 
  2823.  
  2824.  
  2825. ΓòÉΓòÉΓòÉ 11.1. File status ΓòÉΓòÉΓòÉ
  2826.  
  2827.  Based on what operations you have performed on a checked out file, and what 
  2828.  operations others have performed to that file in the repository, one can 
  2829.  classify a file in a number of states.  The states, as reported by the status 
  2830.  command, are: 
  2831.  
  2832.  Up-to-date 
  2833.            The file is identical with the latest revision in the repository for 
  2834.            the branch in use. 
  2835.  
  2836.  Locally Modified 
  2837.            You have edited the file, and not yet committed your changes. 
  2838.  
  2839.  Locally Added 
  2840.            You have added the file with add, and not yet committed your 
  2841.            changes. 
  2842.  
  2843.  Locally Removed 
  2844.            You have removed the file with remove, and not yet committed your 
  2845.            changes. 
  2846.  
  2847.  Needs Checkout 
  2848.            Someone else has committed a newer revision to the repository.  The 
  2849.            name is slightly misleading; you will ordinarily use update rather 
  2850.            than checkout to get that newer revision. 
  2851.  
  2852.  Needs Patch 
  2853.            Like Needs Checkout, but the CVS server will send a patch rather 
  2854.            than the entire file.  Sending a patch or sending an entire file 
  2855.            accomplishes the same thing. 
  2856.  
  2857.  Needs Merge 
  2858.            Someone else has committed a newer revision to the repository, and 
  2859.            you have also made modifications to the file. 
  2860.  
  2861.  File had conflicts on merge 
  2862.            This is like Locally Modified, except that a previous update command 
  2863.            gave a conflict.  If you have not already done so, you need to 
  2864.            resolve the conflict as described in Conflicts example. 
  2865.  
  2866.  Unknown 
  2867.            CVS doesn't know anything about this file.  For example, you have 
  2868.            created a new file and have not run add. 
  2869.  
  2870.  To help clarify the file status, status also reports the Working revision 
  2871.  which is the revision that the file in the working directory derives from, and 
  2872.  the Repository revision which is the latest revision in the repository for the 
  2873.  branch in use. The options to status are listed in Invoking CVS.  For 
  2874.  information on its Sticky tag and Sticky date output, see Sticky tags. For 
  2875.  information on its Sticky options output, see the '-k' option in update 
  2876.  options. 
  2877.  
  2878.  You can think of the status and update commands as somewhat complementary. 
  2879.  You use update to bring your files up to date, and you can use status to give 
  2880.  you some idea of what an update would do (of course, the state of the 
  2881.  repository might change before you actually run update).  In fact, if you want 
  2882.  a command to display file status in a more brief format than is displayed by 
  2883.  the status command, you can invoke 
  2884.  
  2885.                       $ cvs -n -q update
  2886.  
  2887.  The '-n' option means to not actually do the update, but merely to display 
  2888.  statuses; the '-q' option avoids printing the name of each directory.  For 
  2889.  more information on the update command, and these options, see Invoking CVS. 
  2890.  
  2891.  
  2892. ΓòÉΓòÉΓòÉ 11.2. Bringing a file up to date ΓòÉΓòÉΓòÉ
  2893.  
  2894.  When you want to update or merge a file, use the update command.  For files 
  2895.  that are not up to date this is roughly equivalent to a checkout command: the 
  2896.  newest revision of the file is extracted from the repository and put in your 
  2897.  working copy of the module. 
  2898.  
  2899.  Your modifications to a file are never lost when you use update.  If no newer 
  2900.  revision exists, running update has no effect.  If you have edited the file, 
  2901.  and a newer revision is available, CVS will merge all changes into your 
  2902.  working copy. 
  2903.  
  2904.  For instance, imagine that you checked out revision 1.4 and started editing 
  2905.  it.  In the meantime someone else committed revision 1.5, and shortly after 
  2906.  that revision 1.6.  If you run update on the file now, CVS will incorporate 
  2907.  all changes between revision 1.4 and 1.6 into your file. 
  2908.  
  2909.  If any of the changes between 1.4 and 1.6 were made too close to any of the 
  2910.  changes you have made, an overlap occurs.  In such cases a warning is printed, 
  2911.  and the resulting file includes both versions of the lines that overlap, 
  2912.  delimited by special markers. See update, for a complete description of the 
  2913.  update command. 
  2914.  
  2915.  
  2916. ΓòÉΓòÉΓòÉ 11.3. Conflicts example ΓòÉΓòÉΓòÉ
  2917.  
  2918.  Suppose revision 1.4 of 'driver.c' contains this: 
  2919.  
  2920.                       #include <stdio.h>
  2921.                       void main()
  2922.                       {
  2923.                         parse();
  2924.                         if (nerr == 0)
  2925.                           gencode();
  2926.                         else
  2927.                           fprintf(stderr, "No code generated.\n");
  2928.                         exit(nerr == 0 ? 0 : 1);
  2929.                       }
  2930.  
  2931.  Revision 1.6 of 'driver.c' contains this: 
  2932.  
  2933.                       #include <stdio.h>
  2934.                       int main(int argc,
  2935.                            char **argv)
  2936.                       {
  2937.                         parse();
  2938.                         if (argc != 1)
  2939.                         {
  2940.                           fprintf(stderr, "tc: No args expected.\n");
  2941.                           exit(1);
  2942.                         }
  2943.                         if (nerr == 0)
  2944.                           gencode();
  2945.                         else
  2946.                           fprintf(stderr, "No code generated.\n");
  2947.                         exit(!!nerr);
  2948.                       }
  2949.  
  2950.  Your working copy of 'driver.c', based on revision 1.4, contains this before 
  2951.  you run 'cvs update': 
  2952.  
  2953.                       #include <stdlib.h>
  2954.                       #include <stdio.h>
  2955.                       void main()
  2956.                       {
  2957.                         init_scanner();
  2958.                         parse();
  2959.                         if (nerr == 0)
  2960.                           gencode();
  2961.                         else
  2962.                           fprintf(stderr, "No code generated.\n");
  2963.                         exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  2964.                       }
  2965.  
  2966.  You run 'cvs update': 
  2967.  
  2968.                       $ cvs update driver.c
  2969.                       RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  2970.                       retrieving revision 1.4
  2971.                       retrieving revision 1.6
  2972.                       Merging differences between 1.4 and 1.6 into driver.c
  2973.                       rcsmerge warning: overlaps during merge
  2974.                       cvs update: conflicts found in driver.c
  2975.                       C driver.c
  2976.  
  2977.  CVS tells you that there were some conflicts. Your original working file is 
  2978.  saved unmodified in '.#driver.c.1.4'.  The new version of 'driver.c' contains 
  2979.  this: 
  2980.  
  2981.                       #include <stdlib.h>
  2982.                       #include <stdio.h>
  2983.                       int main(int argc,
  2984.                            char **argv)
  2985.                       {
  2986.                         init_scanner();
  2987.                         parse();
  2988.                         if (argc != 1)
  2989.                         {
  2990.                           fprintf(stderr, "tc: No args expected.\n");
  2991.                           exit(1);
  2992.                         }
  2993.                         if (nerr == 0)
  2994.                           gencode();
  2995.                         else
  2996.                           fprintf(stderr, "No code generated.\n");
  2997.                       {}<<<<<<< driver.c
  2998.                         exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  2999.                       {}=======
  3000.                         exit(!!nerr);
  3001.                       {}>>>>>>> 1.6
  3002.                       }
  3003.  
  3004.  Note how all non-overlapping modifications are incorporated in your working 
  3005.  copy, and that the overlapping section is clearly marked with '<<<<<<<', 
  3006.  '=======' and '>>>>>>>'. 
  3007.  
  3008.  You resolve the conflict by editing the file, removing the markers and the 
  3009.  erroneous line.  Suppose you end up with this file: 
  3010.  
  3011.                       #include <stdlib.h>
  3012.                       #include <stdio.h>
  3013.                       int main(int argc,
  3014.                            char **argv)
  3015.                       {
  3016.                         init_scanner();
  3017.                         parse();
  3018.                         if (argc != 1)
  3019.                         {
  3020.                           fprintf(stderr, "tc: No args expected.\n");
  3021.                           exit(1);
  3022.                         }
  3023.                         if (nerr == 0)
  3024.                           gencode();
  3025.                         else
  3026.                           fprintf(stderr, "No code generated.\n");
  3027.                         exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  3028.                       }
  3029.  
  3030.  You can now go ahead and commit this as revision 1.7. 
  3031.  
  3032.                       $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
  3033.                       Checking in driver.c;
  3034.                       /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
  3035.                       new revision: 1.7; previous revision: 1.6
  3036.                       done
  3037.  
  3038.  For your protection, CVS will refuse to check in a file if a conflict occurred 
  3039.  and you have not resolved the conflict.  Currently to resolve a conflict, you 
  3040.  must change the timestamp on the file.  In previous versions of CVS, you also 
  3041.  needed to insure that the file contains no conflict markers. Because your file 
  3042.  may legitimately contain conflict markers (that is, occurrences of '>>>>>>> ' 
  3043.  at the start of a line that don't mark a conflict), the current version of CVS 
  3044.  will print a warning and proceed to check in the file. If you use release 1.04 
  3045.  or later of pcl-cvs (a GNU Emacs front-end for CVS) you can use an Emacs 
  3046.  package called emerge to help you resolve conflicts. See the documentation for 
  3047.  pcl-cvs. 
  3048.  
  3049.  
  3050. ΓòÉΓòÉΓòÉ 11.4. Informing others about commits ΓòÉΓòÉΓòÉ
  3051.  
  3052.  It is often useful to inform others when you commit a new revision of a file. 
  3053.  The '-i' option of the 'modules' file, or the 'loginfo' file, can be used to 
  3054.  automate this process.  See modules. See loginfo.  You can use these features 
  3055.  of CVS to, for instance, instruct CVS to mail a message to all developers, or 
  3056.  post a message to a local newsgroup. 
  3057.  
  3058.  
  3059. ΓòÉΓòÉΓòÉ 11.5. Several developers simultaneously attempting to run CVS ΓòÉΓòÉΓòÉ
  3060.  
  3061.  If several developers try to run CVS at the same time, one may get the 
  3062.  following message: 
  3063.  
  3064.                       [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
  3065.  
  3066.  CVS will try again every 30 seconds, and either continue with the operation or 
  3067.  print the message again, if it still needs to wait.  If a lock seems to stick 
  3068.  around for an undue amount of time, find the person holding the lock and ask 
  3069.  them about the cvs command they are running.  If they aren't running a cvs 
  3070.  command, look in the repository directory mentioned in the message and remove 
  3071.  files which they own whose names start with '#cvs.rfl', '#cvs.wfl', or 
  3072.  '#cvs.lock'. 
  3073.  
  3074.  Note that these locks are to protect CVS's internal data structures and have 
  3075.  no relationship to the word lock in the sense used by RCS---which refers to 
  3076.  reserved checkouts (see Multiple developers). 
  3077.  
  3078.  Any number of people can be reading from a given repository at a time; only 
  3079.  when someone is writing do the locks prevent other people from reading or 
  3080.  writing. 
  3081.  
  3082.  One might hope for the following property 
  3083.  
  3084.                       If someone commits some changes in one cvs command,
  3085.                       then an update by someone else will either get all the
  3086.                       changes, or none of them.
  3087.  
  3088.  but CVS does not have this property.  For example, given the files 
  3089.  
  3090.                       a/one.c
  3091.                       a/two.c
  3092.                       b/three.c
  3093.                       b/four.c
  3094.  
  3095.  if someone runs 
  3096.  
  3097.                       cvs ci a/two.c b/three.c
  3098.  
  3099.  and someone else runs cvs update at the same time, the person running update 
  3100.  might get only the change to 'b/three.c' and not the change to 'a/two.c'. 
  3101.  
  3102.  
  3103. ΓòÉΓòÉΓòÉ 11.6. Mechanisms to track who is editing files ΓòÉΓòÉΓòÉ
  3104.  
  3105.  For many groups, use of CVS in its default mode is perfectly satisfactory. 
  3106.  Users may sometimes go to check in a modification only to find that another 
  3107.  modification has intervened, but they deal with it and proceed with their 
  3108.  check in.  Other groups prefer to be able to know who is editing what files, 
  3109.  so that if two people try to edit the same file they can choose to talk about 
  3110.  who is doing what when rather than be surprised at check in time.  The 
  3111.  features in this section allow such coordination, while retaining the ability 
  3112.  of two developers to edit the same file at the same time. 
  3113.  
  3114.  For maximum benefit developers should use cvs edit (not chmod) to make files 
  3115.  read-write to edit them, and cvs release (not rm) to discard a working 
  3116.  directory which is no longer in use, but CVS is not able to enforce this 
  3117.  behavior. 
  3118.  
  3119.  Setting a watch               Telling CVS to watch certain files 
  3120.  Getting Notified              Telling CVS to notify you 
  3121.  Editing files                 How to edit a file which is being watched 
  3122.  Watch information             Information about who is watching and editing 
  3123.  Watches Compatibility         Watches interact poorly with CVS 1.6 or earlier 
  3124.  
  3125.  
  3126. ΓòÉΓòÉΓòÉ 11.6.1. Telling CVS to watch certain files ΓòÉΓòÉΓòÉ
  3127.  
  3128.  To enable the watch features, you first specify that certain files are to be 
  3129.  watched. 
  3130.  
  3131.  cvs watch on  [-lR] files ┬╖┬╖┬╖   (Command) 
  3132.  
  3133.            Specify that developers should run cvs edit before editing files. 
  3134.            CVS will create working copies of files read-only, to remind 
  3135.            developers to run the cvs edit command before working on them. 
  3136.  
  3137.            If files includes the name of a directory, CVS arranges to watch all 
  3138.            files added to the corresponding repository directory, and sets a 
  3139.            default for files added in the future; this allows the user to set 
  3140.            notification policies on a per-directory basis.  The contents of the 
  3141.            directory are processed recursively, unless the -l option is given. 
  3142.            The -R option can be used to force recursion if the -l option is set 
  3143.            in '~/.cvsrc' (see ~/.cvsrc). 
  3144.  
  3145.            If files is omitted, it defaults to the current directory. 
  3146.  
  3147.  cvs watch off  [-lR] files ┬╖┬╖┬╖   (Command) 
  3148.  
  3149.            Do not provide notification about work on files.  CVS will create 
  3150.            working copies of files read-write. 
  3151.  
  3152.            The files and options are processed as for cvs watch on. 
  3153.  
  3154.  
  3155. ΓòÉΓòÉΓòÉ 11.6.2. Telling CVS to notify you ΓòÉΓòÉΓòÉ
  3156.  
  3157.  You can tell CVS that you want to receive notifications about various actions 
  3158.  taken on a file. You can do this without using cvs watch on for the file, but 
  3159.  generally you will want to use cvs watch on, so that developers use the cvs 
  3160.  edit command. 
  3161.  
  3162.  cvs watch add  [-a action] [-lR] files ┬╖┬╖┬╖   (Command) 
  3163.  
  3164.            Add the current user to the list of people to receive notification 
  3165.            of work done on files. 
  3166.  
  3167.            The -a option specifies what kinds of events CVS should notify the 
  3168.            user about.  action is one of the following: 
  3169.  
  3170.            edit 
  3171.                      Another user has applied the cvs edit command (described 
  3172.                      below) to a file. 
  3173.  
  3174.            unedit 
  3175.                      Another user has applied the cvs unedit command (described 
  3176.                      below) or the cvs release command to a file, or has 
  3177.                      deleted the file and allowed cvs update to recreate it. 
  3178.  
  3179.            commit 
  3180.                      Another user has committed changes to a file. 
  3181.  
  3182.            all 
  3183.                      All of the above. 
  3184.  
  3185.            none 
  3186.                      None of the above.  (This is useful with cvs edit, 
  3187.                      described below.) 
  3188.  
  3189.            The -a option may appear more than once, or not at all.  If omitted, 
  3190.            the action defaults to all. 
  3191.  
  3192.            The files and options are processed as for the cvs watch commands. 
  3193.  
  3194.  cvs watch remove  [-a action] [-lR] files ┬╖┬╖┬╖   (Command) 
  3195.  
  3196.            Remove a notification request established using cvs watch add; the 
  3197.            arguments are the same.  If the -a option is present, only watches 
  3198.            for the specified actions are removed. 
  3199.  
  3200.  When the conditions exist for notification, CVS calls the 'notify' 
  3201.  administrative file.  Edit 'notify' as one edits the other administrative 
  3202.  files (see Intro administrative files).  This file follows the usual 
  3203.  conventions for administrative files (see syntax), where each line is a 
  3204.  regular expression followed by a command to execute.  The command should 
  3205.  contain a single ocurrence of '%s' which will be replaced by the user to 
  3206.  notify; the rest of the information regarding the notification will be 
  3207.  supplied to the command on standard input.  The standard thing to put in the 
  3208.  notify file is the single line: 
  3209.  
  3210.                       ALL mail %s -s \"CVS notification\"
  3211.  
  3212.  This causes users to be notified by electronic mail. Note that if you set this 
  3213.  up in the straightforward way, users receive notifications on the server 
  3214.  machine. One could of course write a 'notify' script which directed 
  3215.  notifications elsewhere, but to make this easy, CVS allows you to associate a 
  3216.  notification address for each user.  To do so create a file 'users' in 
  3217.  'CVSROOT' with a line for each user in the format user:value.  Then instead of 
  3218.  passing the name of the user to be notified to 'notify', CVS will pass the 
  3219.  value (normally an email address on some other machine). 
  3220.  
  3221.  CVS does not notify you for your own changes. Currently this check is done 
  3222.  based on whether the user name of the person taking the action which triggers 
  3223.  notification matches the user name of the person getting notification.  In 
  3224.  fact, in general, the watches features only track one edit by each user.  It 
  3225.  probably would be more useful if watches tracked each working directory 
  3226.  separately, so this behavior might be worth changing. 
  3227.  
  3228.  
  3229. ΓòÉΓòÉΓòÉ 11.6.3. How to edit a file which is being watched ΓòÉΓòÉΓòÉ
  3230.  
  3231.  Since a file which is being watched is checked out read-only, you cannot 
  3232.  simply edit it.  To make it read-write, and inform others that you are 
  3233.  planning to edit it, use the cvs edit command.  Some systems call this a 
  3234.  checkout, but CVS uses that term for obtaining a copy of the sources (see 
  3235.  Getting the source), an operation which those systems call a get or a fetch. 
  3236.  
  3237.  cvs edit  [options] files ┬╖┬╖┬╖   (Command) 
  3238.  
  3239.            Prepare to edit the working files files.  CVS makes the files 
  3240.            read-write, and notifies users who have requested edit notification 
  3241.            for any of files. 
  3242.  
  3243.            The cvs edit command accepts the same options as the cvs watch add 
  3244.            command, and establishes a temporary watch for the user on files; 
  3245.            CVS will remove the watch when files are unedited or committed.  If 
  3246.            the user does not wish to receive notifications, she should specify 
  3247.            -a none. 
  3248.  
  3249.            The files and options are processed as for the cvs watch commands. 
  3250.  
  3251.            Caution: If the PreservePermissions option is enabled in the 
  3252.            repository (see config), CVS will not change the permissions on any 
  3253.            of the files.  The reason for this change is to ensure that using 
  3254.            'cvs edit' does not interfere with the ability to store file 
  3255.            permissions in the CVS repository. 
  3256.  
  3257.  Normally when you are done with a set of changes, you use the cvs commit 
  3258.  command, which checks in your changes and returns the watched files to their 
  3259.  usual read-only state.  But if you instead decide to abandon your changes, or 
  3260.  not to make any changes, you can use the cvs unedit command. 
  3261.  
  3262.  cvs unedit  [-lR] files ┬╖┬╖┬╖   (Command) 
  3263.  
  3264.            Abandon work on the working files files, and revert them to the 
  3265.            repository versions on which they are based.  CVS makes those files 
  3266.            read-only for which users have requested notification using cvs 
  3267.            watch on.  CVS notifies users who have requested unedit notification 
  3268.            for any of files. 
  3269.  
  3270.            The files and options are processed as for the cvs watch commands. 
  3271.  
  3272.            If watches are not in use, the unedit command probably does not 
  3273.            work, and the way to revert to the repository version is to remove 
  3274.            the file and then use cvs update to get a new copy.  The meaning is 
  3275.            not precisely the same; removing and updating may also bring in some 
  3276.            changes which have been made in the repository since the last time 
  3277.            you updated. 
  3278.  
  3279.  When using client/server CVS, you can use the cvs edit and cvs unedit commands 
  3280.  even if CVS is unable to succesfully communicate with the server; the 
  3281.  notifications will be sent upon the next successful CVS command. 
  3282.  
  3283.  
  3284. ΓòÉΓòÉΓòÉ 11.6.4. Information about who is watching and editing ΓòÉΓòÉΓòÉ
  3285.  
  3286.  cvs watchers  [-lR] files ┬╖┬╖┬╖   (Command) 
  3287.  
  3288.            List the users currently watching changes to files.  The report 
  3289.            includes the files being watched, and the mail address of each 
  3290.            watcher. 
  3291.  
  3292.            The files and options are processed as for the cvs watch commands. 
  3293.  
  3294.  cvs editors  [-lR] files ┬╖┬╖┬╖   (Command) 
  3295.  
  3296.            List the users currently working on files.  The report includes the 
  3297.            mail address of each user, the time when the user began working with 
  3298.            the file, and the host and path of the working directory containing 
  3299.            the file. 
  3300.  
  3301.            The files and options are processed as for the cvs watch commands. 
  3302.  
  3303.  
  3304. ΓòÉΓòÉΓòÉ 11.6.5. Using watches with old versions of CVS ΓòÉΓòÉΓòÉ
  3305.  
  3306.  If you use the watch features on a repository, it creates 'CVS' directories in 
  3307.  the repository and stores the information about watches in that directory. If 
  3308.  you attempt to use CVS 1.6 or earlier with the repository, you get an error 
  3309.  message such as the following (all on one line): 
  3310.  
  3311.                       cvs update: cannot open CVS/Entries for reading:
  3312.                       No such file or directory
  3313.  
  3314.  and your operation will likely be aborted.  To use the watch features, you 
  3315.  must upgrade all copies of CVS which use that repository in local or server 
  3316.  mode.  If you cannot upgrade, use the watch off and watch remove commands to 
  3317.  remove all watches, and that will restore the repository to a state which CVS 
  3318.  1.6 can cope with. 
  3319.  
  3320.  
  3321. ΓòÉΓòÉΓòÉ 11.7. Choosing between reserved or unreserved checkouts ΓòÉΓòÉΓòÉ
  3322.  
  3323.  Reserved and unreserved checkouts each have pros and cons.  Let it be said 
  3324.  that a lot of this is a matter of opinion or what works given different 
  3325.  groups' working styles, but here is a brief description of some of the issues. 
  3326.  There are many ways to organize a team of developers.  CVS does not try to 
  3327.  enforce a certain organization.  It is a tool that can be used in several 
  3328.  ways. 
  3329.  
  3330.  Reserved checkouts can be very counter-productive.  If two persons want to 
  3331.  edit different parts of a file, there may be no reason to prevent either of 
  3332.  them from doing so.  Also, it is common for someone to take out a lock on a 
  3333.  file, because they are planning to edit it, but then forget to release the 
  3334.  lock. 
  3335.  
  3336.  People, especially people who are familiar with reserved checkouts, often 
  3337.  wonder how often conflicts occur if unreserved checkouts are used, and how 
  3338.  difficult they are to resolve.  The experience with many groups is that they 
  3339.  occur rarely and usually are relatively straightforward to resolve. 
  3340.  
  3341.  The rarity of serious conflicts may be surprising, until one realizes that 
  3342.  they occur only when two developers disagree on the proper design for a given 
  3343.  section of code; such a disagreement suggests that the team has not been 
  3344.  communicating properly in the first place.  In order to collaborate under any 
  3345.  source management regimen, developers must agree on the general design of the 
  3346.  system; given this agreement, overlapping changes are usually straightforward 
  3347.  to merge. 
  3348.  
  3349.  In some cases unreserved checkouts are clearly inappropriate.  If no merge 
  3350.  tool exists for the kind of file you are managing (for example word processor 
  3351.  files or files edited by Computer Aided Design programs), and it is not 
  3352.  desirable to change to a program which uses a mergeable data format, then 
  3353.  resolving conflicts is going to be unpleasant enough that you generally will 
  3354.  be better off to simply avoid the conflicts instead, by using reserved 
  3355.  checkouts. 
  3356.  
  3357.  The watches features described above in Watches can be considered to be an 
  3358.  intermediate model between reserved checkouts and unreserved checkouts.  When 
  3359.  you go to edit a file, it is possible to find out who else is editing it.  And 
  3360.  rather than having the system simply forbid both people editing the file, it 
  3361.  can tell you what the situation is and let you figure out whether it is a 
  3362.  problem in that particular case or not. Therefore, for some groups it can be 
  3363.  considered the best of both the reserved checkout and unreserved checkout 
  3364.  worlds. 
  3365.  
  3366.  
  3367. ΓòÉΓòÉΓòÉ 12. Revision management ΓòÉΓòÉΓòÉ
  3368.  
  3369.  If you have read this far, you probably have a pretty good grasp on what CVS 
  3370.  can do for you.  This chapter talks a little about things that you still have 
  3371.  to decide. 
  3372.  
  3373.  If you are doing development on your own using CVS you could probably skip 
  3374.  this chapter.  The questions this chapter takes up become more important when 
  3375.  more than one person is working in a repository. 
  3376.  
  3377.  When to commit                Some discussion on the subject 
  3378.  
  3379.  
  3380. ΓòÉΓòÉΓòÉ 12.1. When to commit? ΓòÉΓòÉΓòÉ
  3381.  
  3382.  Your group should decide which policy to use regarding commits.  Several 
  3383.  policies are possible, and as your experience with CVS grows you will probably 
  3384.  find out what works for you. 
  3385.  
  3386.  If you commit files too quickly you might commit files that do not even 
  3387.  compile.  If your partner updates his working sources to include your buggy 
  3388.  file, he will be unable to compile the code.  On the other hand, other persons 
  3389.  will not be able to benefit from the improvements you make to the code if you 
  3390.  commit very seldom, and conflicts will probably be more common. 
  3391.  
  3392.  It is common to only commit files after making sure that they can be compiled. 
  3393.  Some sites require that the files pass a test suite.  Policies like this can 
  3394.  be enforced using the commitinfo file (see commitinfo), but you should think 
  3395.  twice before you enforce such a convention.  By making the development 
  3396.  environment too controlled it might become too regimented and thus 
  3397.  counter-productive to the real goal, which is to get software written. 
  3398.  
  3399.  
  3400. ΓòÉΓòÉΓòÉ 13. Keyword substitution ΓòÉΓòÉΓòÉ
  3401.  
  3402.  As long as you edit source files inside your working copy of a module you can 
  3403.  always find out the state of your files via 'cvs status' and 'cvs log'. But as 
  3404.  soon as you export the files from your development environment it becomes 
  3405.  harder to identify which revisions they are. 
  3406.  
  3407.  CVS can use a mechanism known as keyword substitution (or keyword expansion) 
  3408.  to help identifying the files.  Embedded strings of the form $keyword$ and 
  3409.  $keyword:┬╖┬╖┬╖$ in a file are replaced with strings of the form $keyword:value$ 
  3410.  whenever you obtain a new revision of the file. 
  3411.  
  3412.  Keyword list                  Keywords 
  3413.  Using keywords                Using keywords 
  3414.  Avoiding substitution         Avoiding substitution 
  3415.  Substitution modes            Substitution modes 
  3416.  Log keyword                   Problems with the $Log$ keyword. 
  3417.  
  3418.  
  3419. ΓòÉΓòÉΓòÉ 13.1. Keyword List ΓòÉΓòÉΓòÉ
  3420.  
  3421.  This is a list of the keywords: 
  3422.  
  3423.  $Author$ 
  3424.            The login name of the user who checked in the revision. 
  3425.  
  3426.  $Date$ 
  3427.            The date and time (UTC) the revision was checked in. 
  3428.  
  3429.  $Header$ 
  3430.            A standard header containing the full pathname of the RCS file, the 
  3431.            revision number, the date (UTC), the author, the state, and the 
  3432.            locker (if locked).  Files will normally never be locked when you 
  3433.            use CVS. 
  3434.  
  3435.  $Id$ 
  3436.            Same as $Header$}, except that the RCS filename is without a path. 
  3437.  
  3438.  $Name$ 
  3439.            Tag name used to check out this file. 
  3440.  
  3441.  $Locker$ 
  3442.            The login name of the user who locked the revision (empty if not 
  3443.            locked, and thus almost always useless when you are using CVS). 
  3444.  
  3445.  $Log$ 
  3446.            The log message supplied during commit, preceded by a header 
  3447.            containing the RCS filename, the revision number, the author, and 
  3448.            the date (UTC).  Existing log messages are not replaced.  Instead, 
  3449.            the new log message is inserted after $Log:┬╖┬╖┬╖$}. Each new line is 
  3450.            prefixed with the same string which precedes the $Log keyword.  For 
  3451.            example, if the file contains 
  3452.  
  3453.                        /* Here is what people have been up to:
  3454.                         *
  3455.                         * ${}Log: frob.c,v $
  3456.                         * Revision 1.1  1997/01/03 14:23:51  joe
  3457.                         * Add the superfrobnicate option
  3458.                         *
  3459.                         */
  3460.  
  3461.  then additional lines which are added when expanding the $Log keyword will be 
  3462.  preceded by '  * '. Unlike previous versions of CVS and RCS, the comment 
  3463.  leader from the RCS file is not used. The $Log keyword is useful for 
  3464.  accumulating a complete change log in a source file, but for several reasons 
  3465.  it can be problematic. See Log keyword. 
  3466.  
  3467.  $RCSfile$ 
  3468.            The name of the RCS file without a path. 
  3469.  
  3470.  $Revision$ 
  3471.            The revision number assigned to the revision. 
  3472.  
  3473.  $Source$ 
  3474.            The full pathname of the RCS file. 
  3475.  
  3476.  $State$ 
  3477.            The state assigned to the revision.  States can be assigned with cvs 
  3478.            admin -s---see admin options. 
  3479.  
  3480.  
  3481. ΓòÉΓòÉΓòÉ 13.2. Using keywords ΓòÉΓòÉΓòÉ
  3482.  
  3483.  To include a keyword string you simply include the relevant text string, such 
  3484.  as $Id$}, inside the file, and commit the file.  CVS will automatically expand 
  3485.  the string as part of the commit operation. 
  3486.  
  3487.  It is common to embed the $Id$} string in the source files so that it gets 
  3488.  passed through to generated files.  For example, if you are managing computer 
  3489.  program source code, you might include a variable which is initialized to 
  3490.  contain that string. Or some C compilers may provide a #pragma ident 
  3491.  directive.  Or a document management system might provide a way to pass a 
  3492.  string through to generated files. 
  3493.  
  3494.  The ident command (which is part of the RCS package) can be used to extract 
  3495.  keywords and their values from a file.  This can be handy for text files, but 
  3496.  it is even more useful for extracting keywords from binary files. 
  3497.  
  3498.                       $ ident samp.c
  3499.                       samp.c:
  3500.                          ${}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
  3501.                       $ gcc samp.c
  3502.                       $ ident a.out
  3503.                       a.out:
  3504.                          ${}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
  3505.  
  3506.  SCCS is another popular revision control system. It has a command, what, which 
  3507.  is very similar to ident and used for the same purpose.  Many sites without 
  3508.  RCS have SCCS.  Since what looks for the character sequence @(#) it is easy to 
  3509.  include keywords that are detected by either command.  Simply prefix the RCS 
  3510.  keyword with the magic SCCS phrase, like this: 
  3511.  
  3512.                       static char *id="@(#) ${}Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
  3513.  
  3514.  
  3515. ΓòÉΓòÉΓòÉ 13.3. Avoiding substitution ΓòÉΓòÉΓòÉ
  3516.  
  3517.  Keyword substitution has its disadvantages.  Sometimes you might want the 
  3518.  literal text string '$'Author$} to appear inside a file without CVS 
  3519.  interpreting it as a keyword and expanding it into something like '$'Author: 
  3520.  ceder $}. 
  3521.  
  3522.  There is unfortunately no way to selectively turn off keyword substitution. 
  3523.  You can use '-ko' (see Substitution modes) to turn off keyword substitution 
  3524.  entirely. 
  3525.  
  3526.  In many cases you can avoid using keywords in the source, even though they 
  3527.  appear in the final product.  For example, the source for this manual contains 
  3528.  '$@asis{}Author$' whenever the text '$'Author$} should appear.  In nroff and 
  3529.  troff you can embed the null-character \& inside the keyword for a similar 
  3530.  effect. 
  3531.  
  3532.  
  3533. ΓòÉΓòÉΓòÉ 13.4. Substitution modes ΓòÉΓòÉΓòÉ
  3534.  
  3535.  Each file has a stored default substitution mode, and each working directory 
  3536.  copy of a file also has a substitution mode.  The former is set by the '-k' 
  3537.  option to cvs add and cvs admin; the latter is set by the '-k' or '-A' options 
  3538.  to cvs checkout or cvs update.  cvs diff also has a '-k' option.  For some 
  3539.  examples, see Binary files. The modes available are: 
  3540.  
  3541.  '-kkv' 
  3542.            Generate keyword strings using the default form, e.g. $Revision: 5.7 
  3543.            $} for the Revision keyword. 
  3544.  
  3545.  '-kkvl' 
  3546.            Like '-kkv', except that a locker's name is always inserted if the 
  3547.            given revision is currently locked. This option is normally not 
  3548.            useful when CVS is used. 
  3549.  
  3550.  '-kk' 
  3551.            Generate only keyword names in keyword strings; omit their values. 
  3552.            For example, for the Revision keyword, generate the string 
  3553.            $Revision$} instead of $Revision: 5.7 $}.  This option is useful to 
  3554.            ignore differences due to keyword substitution when comparing 
  3555.            different revisions of a file. 
  3556.  
  3557.  '-ko' 
  3558.            Generate the old keyword string, present in the working file just 
  3559.            before it was checked in.  For example, for the Revision keyword, 
  3560.            generate the string $Revision: 1.1 $} instead of $Revision: 5.7 $} 
  3561.            if that is how the string appeared when the file was checked in. 
  3562.  
  3563.  '-kb' 
  3564.            Like '-ko', but also inhibit conversion of line endings between the 
  3565.            canonical form in which they are stored in the repository (linefeed 
  3566.            only), and the form appropriate to the operating system in use on 
  3567.            the client.  For systems, like unix, which use linefeed only to 
  3568.            terminate lines, this is the same as '-ko'.  For more information on 
  3569.            binary files, see Binary files. 
  3570.  
  3571.  '-kv' 
  3572.            Generate only keyword values for keyword strings.  For example, for 
  3573.            the Revision keyword, generate the string 5.7 instead of $Revision: 
  3574.            5.7 $}. This can help generate files in programming languages where 
  3575.            it is hard to strip keyword delimiters like $Revision: $} from a 
  3576.            string.  However, further keyword substitution cannot be performed 
  3577.            once the keyword names are removed, so this option should be used 
  3578.            with care. 
  3579.  
  3580.            One often would like to use '-kv' with cvs export---see export.  But 
  3581.            be aware that doesn't handle an export containing binary files 
  3582.            correctly. 
  3583.  
  3584.  
  3585. ΓòÉΓòÉΓòÉ 13.5. Problems with the $Log$ keyword. ΓòÉΓòÉΓòÉ
  3586.  
  3587.  The $Log$} keyword is somewhat controversial.  As long as you are working on 
  3588.  your development system the information is easily accessible even if you do 
  3589.  not use the $Log$} keyword---just do a cvs log.  Once you export the file the 
  3590.  history information might be useless anyhow. 
  3591.  
  3592.  A more serious concern is that CVS is not good at handling $Log$} entries when 
  3593.  a branch is merged onto the main trunk.  Conflicts often result from the 
  3594.  merging operation. People also tend to "fix" the log entries in the file 
  3595.  (correcting spelling mistakes and maybe even factual errors).  If that is done 
  3596.  the information from cvs log will not be consistent with the information 
  3597.  inside the file.  This may or may not be a problem in real life. 
  3598.  
  3599.  It has been suggested that the $Log$} keyword should be inserted last in the 
  3600.  file, and not in the files header, if it is to be used at all. That way the 
  3601.  long list of change messages will not interfere with everyday source file 
  3602.  browsing. 
  3603.  
  3604.  
  3605. ΓòÉΓòÉΓòÉ 14. Tracking third-party sources ΓòÉΓòÉΓòÉ
  3606.  
  3607.  If you modify a program to better fit your site, you probably want to include 
  3608.  your modifications when the next release of the program arrives.  CVS can help 
  3609.  you with this task. 
  3610.  
  3611.  In the terminology used in CVS, the supplier of the program is called a 
  3612.  vendor.  The unmodified distribution from the vendor is checked in on its own 
  3613.  branch, the vendor branch.  CVS reserves branch 1.1.1 for this use. 
  3614.  
  3615.  When you modify the source and commit it, your revision will end up on the 
  3616.  main trunk.  When a new release is made by the vendor, you commit it on the 
  3617.  vendor branch and copy the modifications onto the main trunk. 
  3618.  
  3619.  Use the import command to create and update the vendor branch.  When you 
  3620.  import a new file, the vendor branch is made the `head' revision, so anyone 
  3621.  that checks out a copy of the file gets that revision.  When a local 
  3622.  modification is committed it is placed on the main trunk, and made the `head' 
  3623.  revision. 
  3624.  
  3625.  First import                  Importing a module for the first time 
  3626.  Update imports                Updating a module with the import command 
  3627.  Reverting local changes       Reverting a module to the latest vendor release 
  3628.  Binary files in imports       Binary files require special handling 
  3629.  Keywords in imports           Keyword substitution might be undesirable 
  3630.  Multiple vendor branches      What if you get sources from several places? 
  3631.  
  3632.  
  3633. ΓòÉΓòÉΓòÉ 14.1. Importing a module for the first time ΓòÉΓòÉΓòÉ
  3634.  
  3635.  Use the import command to check in the sources for the first time.  When you 
  3636.  use the import command to track third-party sources, the vendor tag and 
  3637.  release tags are useful.  The vendor tag is a symbolic name for the branch 
  3638.  (which is always 1.1.1, unless you use the '-b branch' flag---See Multiple 
  3639.  vendor branches.).  The release tags are symbolic names for a particular 
  3640.  release, such as 'FSF_0_04'. 
  3641.  
  3642.  Note that import does not change the directory in which you invoke it.  In 
  3643.  particular, it does not set up that directory as a CVS working directory; if 
  3644.  you want to work with the sources import them first and then check them out 
  3645.  into a different directory (see Getting the source). 
  3646.  
  3647.  Suppose you have the sources to a program called wdiff in a directory 
  3648.  'wdiff-0.04', and are going to make private modifications that you want to be 
  3649.  able to use even when new releases are made in the future.  You start by 
  3650.  importing the source to your repository: 
  3651.  
  3652.                       $ cd wdiff-0.04
  3653.                       $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
  3654.  
  3655.  The vendor tag is named 'FSF_DIST' in the above example, and the only release 
  3656.  tag assigned is 'WDIFF_0_04'. 
  3657.  
  3658.  
  3659. ΓòÉΓòÉΓòÉ 14.2. Updating a module with the import command ΓòÉΓòÉΓòÉ
  3660.  
  3661.  When a new release of the source arrives, you import it into the repository 
  3662.  with the same import command that you used to set up the repository in the 
  3663.  first place.  The only difference is that you specify a different release tag 
  3664.  this time. 
  3665.  
  3666.                       $ tar xfz wdiff-0.05.tar.gz
  3667.                       $ cd wdiff-0.05
  3668.                       $ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
  3669.  
  3670.  For files that have not been modified locally, the newly created revision 
  3671.  becomes the head revision.  If you have made local changes, import will warn 
  3672.  you that you must merge the changes into the main trunk, and tell you to use 
  3673.  'checkout -j' to do so. 
  3674.  
  3675.                       $ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
  3676.  
  3677.  The above command will check out the latest revision of 'wdiff', merging the 
  3678.  changes made on the vendor branch 'FSF_DIST' since yesterday into the working 
  3679.  copy.  If any conflicts arise during the merge they should be resolved in the 
  3680.  normal way (see Conflicts example).  Then, the modified files may be 
  3681.  committed. 
  3682.  
  3683.  Using a date, as suggested above, assumes that you do not import more than one 
  3684.  release of a product per day. If you do, you can always use something like 
  3685.  this instead: 
  3686.  
  3687.                       $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
  3688.  
  3689.  In this case, the two above commands are equivalent. 
  3690.  
  3691.  
  3692. ΓòÉΓòÉΓòÉ 14.3. Reverting to the latest vendor release ΓòÉΓòÉΓòÉ
  3693.  
  3694.  You can also revert local changes completely and return to the latest vendor 
  3695.  release by changing the `head' revision back to the vendor branch on all 
  3696.  files.  For example, if you have a checked-out copy of the sources in 
  3697.  '~/work.d/wdiff', and you want to revert to the vendor's version for all the 
  3698.  files in that directory, you would type: 
  3699.  
  3700.                       $ cd ~/work.d/wdiff
  3701.                       $ cvs admin -bWDIFF .
  3702.  
  3703.  You must specify the '-bWDIFF' without any space after the '-b'.  See admin 
  3704.  options. 
  3705.  
  3706.  
  3707. ΓòÉΓòÉΓòÉ 14.4. How to handle binary files with cvs import ΓòÉΓòÉΓòÉ
  3708.  
  3709.  Use the '-k' wrapper option to tell import which files are binary.  See 
  3710.  Wrappers. 
  3711.  
  3712.  
  3713. ΓòÉΓòÉΓòÉ 14.5. How to handle keyword substitution with cvs import ΓòÉΓòÉΓòÉ
  3714.  
  3715.  The sources which you are importing may contain keywords (see Keyword 
  3716.  substitution).  For example, the vendor may use CVS or some other system which 
  3717.  uses similar keyword expansion syntax.  If you just import the files in the 
  3718.  default fashion, then the keyword expansions supplied by the vendor will be 
  3719.  replaced by keyword expansions supplied by your own copy of CVS.  It may be 
  3720.  more convenient to maintain the expansions supplied by the vendor, so that 
  3721.  this information can supply information about the sources that you imported 
  3722.  from the vendor. 
  3723.  
  3724.  To maintain the keyword expansions supplied by the vendor, supply the '-ko' 
  3725.  option to cvs import the first time you import the file. This will turn off 
  3726.  keyword expansion for that file entirely, so if you want to be more selective 
  3727.  you'll have to think about what you want and use the '-k' option to cvs update 
  3728.  or cvs admin as appropriate. 
  3729.  
  3730.  
  3731. ΓòÉΓòÉΓòÉ 14.6. Multiple vendor branches ΓòÉΓòÉΓòÉ
  3732.  
  3733.  All the examples so far assume that there is only one vendor from which you 
  3734.  are getting sources.  In some situations you might get sources from a variety 
  3735.  of places.  For example, suppose that you are dealing with a project where 
  3736.  many different people and teams are modifying the software.  There are a 
  3737.  variety of ways to handle this, but in some cases you have a bunch of source 
  3738.  trees lying around and what you want to do more than anything else is just to 
  3739.  all put them in CVS so that you at least have them in one place. 
  3740.  
  3741.  For handling situations in which there may be more than one vendor, you may 
  3742.  specify the '-b' option to cvs import.  It takes as an argument the vendor 
  3743.  branch to import to.  The default is '-b 1.1.1'. 
  3744.  
  3745.  For example, suppose that there are two teams, the red team and the blue team, 
  3746.  that are sending you sources. You want to import the red team's efforts to 
  3747.  branch 1.1.1 and use the vendor tag RED.  You want to import the blue team's 
  3748.  efforts to branch 1.1.3 and use the vendor tag BLUE.  So the commands you 
  3749.  might use are: 
  3750.  
  3751.                       $ cvs import dir RED RED_1-0
  3752.                       $ cvs import -b 1.1.3 dir BLUE BLUE_1-5
  3753.  
  3754.  Note that if your vendor tag does not match your '-b' option, CVS will not 
  3755.  detect this case!  For example, 
  3756.  
  3757.                       $ cvs import -b 1.1.3 dir RED RED_1-0
  3758.  
  3759.  Be careful; this kind of mismatch is sure to sow confusion or worse.  I can't 
  3760.  think of a useful purpose for the ability to specify a mismatch here, but if 
  3761.  you discover such a use, don't.  CVS is likely to make this an error in some 
  3762.  future release. 
  3763.  
  3764.  
  3765. ΓòÉΓòÉΓòÉ 15. How your build system interacts with CVS ΓòÉΓòÉΓòÉ
  3766.  
  3767.  As mentioned in the introduction, CVS does not contain software for building 
  3768.  your software from source code.  This section describes how various aspects of 
  3769.  your build system might interact with CVS. 
  3770.  
  3771.  One common question, especially from people who are accustomed to RCS, is how 
  3772.  to make their build get an up to date copy of the sources.  The answer to this 
  3773.  with CVS is two-fold.  First of all, since CVS itself can recurse through 
  3774.  directories, there is no need to modify your 'Makefile' (or whatever 
  3775.  configuration file your build tool uses) to make sure each file is up to date. 
  3776.  Instead, just use two commands, first cvs -q update and then make or whatever 
  3777.  the command is to invoke your build tool.  Secondly, you do not necessarily 
  3778.  want to get a copy of a change someone else made until you have finished your 
  3779.  own work.  One suggested approach is to first update your sources, then 
  3780.  implement, build and test the change you were thinking of, and then commit 
  3781.  your sources (updating first if necessary).  By periodically (in between 
  3782.  changes, using the approach just described) updating your entire tree, you 
  3783.  ensure that your sources are sufficiently up to date. 
  3784.  
  3785.  One common need is to record which versions of which source files went into a 
  3786.  particular build.  This kind of functionality is sometimes called bill of 
  3787.  materials or something similar.  The best way to do this with CVS is to use 
  3788.  the tag command to record which versions went into a given build (see Tags). 
  3789.  
  3790.  Using CVS in the most straightforward manner possible, each developer will 
  3791.  have a copy of the entire source tree which is used in a particular build.  If 
  3792.  the source tree is small, or if developers are geographically dispersed, this 
  3793.  is the preferred solution.  In fact one approach for larger projects is to 
  3794.  break a project down into smaller separately-compiled subsystems, and arrange 
  3795.  a way of releasing them internally so that each developer need check out only 
  3796.  those subsystems which are they are actively working on. 
  3797.  
  3798.  Another approach is to set up a structure which allows developers to have 
  3799.  their own copies of some files, and for other files to access source files 
  3800.  from a central location.  Many people have come up with some such a system 
  3801.  using features such as the symbolic link feature found in many operating 
  3802.  systems, or the VPATH feature found in many versions of make.  One build tool 
  3803.  which is designed to help with this kind of thing is Odin (see 
  3804.  ftp://ftp.cs.colorado.edu/pub/distribs/odin). 
  3805.  
  3806.  
  3807. ΓòÉΓòÉΓòÉ 16. Special Files ΓòÉΓòÉΓòÉ
  3808.  
  3809.  In normal circumstances, CVS works only with regular files.  Every file in a 
  3810.  project is assumed to be persistent; it must be possible to open, read and 
  3811.  close them; and so on.  CVS also ignores file permissions and ownerships, 
  3812.  leaving such issues to be resolved by the developer at installation time.  In 
  3813.  other words, it is not possible to "check in" a device into a repository; if 
  3814.  the device file cannot be opened, CVS will refuse to handle it.  Files also 
  3815.  lose their ownerships and permissions during repository transactions. 
  3816.  
  3817.  If the configuration variable PreservePermissions (see config) is set in the 
  3818.  repository, CVS will save the following file characteristics in the 
  3819.  repository: 
  3820.  
  3821.      user and group ownership 
  3822.  
  3823.      permissions 
  3824.  
  3825.      major and minor device numbers 
  3826.  
  3827.      symbolic links 
  3828.  
  3829.      hard link structure 
  3830.  
  3831.  Using the PreservePermissions option affects the behavior of CVS in several 
  3832.  ways.  First, some of the new operations supported by CVS are not accessible 
  3833.  to all users.  In particular, file ownership and special file characteristics 
  3834.  may only be changed by the superuser.  When the PreservePermissions 
  3835.  configuration variable is set, therefore, users will have to be `root' in 
  3836.  order to perform CVS operations. 
  3837.  
  3838.  When PreservePermissions is in use, some CVS operations (such as 'cvs status') 
  3839.  will not recognize a file's hard link structure, and so will emit spurious 
  3840.  warnings about mismatching hard links. The reason is that CVS's internal 
  3841.  structure does not make it easy for these operations to collect all the 
  3842.  necessary data about hard links, so they check for file conflicts with 
  3843.  inaccurate data. 
  3844.  
  3845.  A more subtle difference is that CVS considers a file to have changed only if 
  3846.  its contents have changed (specifically, if the modification time of the 
  3847.  working file does not match that of the repository's file). Therefore, if only 
  3848.  the permissions, ownership or hard linkage have changed, or if a device's 
  3849.  major or minor numbers have changed, CVS will not notice.  In order to commit 
  3850.  such a change to the repository, you must force the commit with 'cvs commit 
  3851.  -f'.  This also means that if a file's permissions have changed and the 
  3852.  repository file is newer than the working copy, performing 'cvs update' will 
  3853.  silently change the permissions on the working copy. 
  3854.  
  3855.  Changing hard links in a CVS repository is particularly delicate.  Suppose 
  3856.  that file 'foo' is linked to file 'old', but is later relinked to file 'new'. 
  3857.  You can wind up in the unusual situation where, although 'foo', 'old' and 
  3858.  'new' have all had their underlying link patterns changed, only 'foo' and 
  3859.  'new' have been modified, so 'old' is not considered a candidate for checking 
  3860.  in.  It can be very easy to produce inconsistent results this way.  Therefore, 
  3861.  we recommend that when it is important to save hard links in a repository, the 
  3862.  prudent course of action is to touch any file whose linkage or status has 
  3863.  changed since the last checkin.  Indeed, it may be wise to touch * before each 
  3864.  commit in a directory with complex hard link structures. 
  3865.  
  3866.  It is worth noting that only regular files may be merged, for reasons that 
  3867.  hopefully are obvious.  If 'cvs update' or 'cvs checkout -j' attempts to merge 
  3868.  a symbolic link with a regular file, or two device files for different kinds 
  3869.  of devices, CVS will report a conflict and refuse to perform the merge.  At 
  3870.  the same time, 'cvs diff' will not report any differences between these files, 
  3871.  since no meaningful textual comparisons can be made on files which contain no 
  3872.  text. 
  3873.  
  3874.  The PreservePermissions features do not work with client/server CVS.  Another 
  3875.  limitation is that hard links must be to other files within the same 
  3876.  directory; hard links across directories are not supported. 
  3877.  
  3878.  
  3879. ΓòÉΓòÉΓòÉ 17. Guide to CVS commands ΓòÉΓòÉΓòÉ
  3880.  
  3881.  This appendix describes the overall structure of CVS commands, and describes 
  3882.  some commands in detail (others are described elsewhere; for a quick reference 
  3883.  to CVS commands, see Invoking CVS). 
  3884.  
  3885.  Structure                     Overall structure of CVS commands 
  3886.  Exit status                   Indicating CVS's success or failure 
  3887.  ~/.cvsrc                      Default options with the ~/.csvrc file 
  3888.  Global options                Options you give to the left of cvs_command 
  3889.  Common options                Options you give to the right of cvs_command 
  3890.  admin                         Administration 
  3891.  checkout                      Checkout sources for editing 
  3892.  commit                        Check files into the repository 
  3893.  diff                          Show differences between revisions 
  3894.  export                        Export sources from CVS, similar to checkout 
  3895.  history                       Show status of files and users 
  3896.  import                        Import sources into CVS, using vendor branches 
  3897.  log                           Show log messages for files 
  3898.  rdiff                         'patch' format diffs between releases 
  3899.  release                       Indicate that a Module is no longer in use 
  3900.  rtag                          Add a tag to a module 
  3901.  tag                           Add a tag to checked out version 
  3902.  update                        Bring work tree in sync with repository 
  3903.  
  3904.  
  3905. ΓòÉΓòÉΓòÉ 17.1. Overall structure of CVS commands ΓòÉΓòÉΓòÉ
  3906.  
  3907.  The overall format of all CVS commands is: 
  3908.  
  3909.                       cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
  3910.  
  3911.  cvs 
  3912.            The name of the CVS program. 
  3913.  
  3914.  cvs_options 
  3915.            Some options that affect all sub-commands of CVS.  These are 
  3916.            described below. 
  3917.  
  3918.  cvs_command 
  3919.            One of several different sub-commands.  Some of the commands have 
  3920.            aliases that can be used instead; those aliases are noted in the 
  3921.            reference manual for that command.  There are only two situations 
  3922.            where you may omit 'cvs_command': 'cvs -H' elicits a list of 
  3923.            available commands, and 'cvs -v' displays version information on CVS 
  3924.            itself. 
  3925.  
  3926.  command_options 
  3927.            Options that are specific for the command. 
  3928.  
  3929.  command_args 
  3930.            Arguments to the commands. 
  3931.  
  3932.  There is unfortunately some confusion between cvs_options and command_options. 
  3933.  '-l', when given as a cvs_option, only affects some of the commands.  When it 
  3934.  is given as a command_option is has a different meaning, and is accepted by 
  3935.  more commands.  In other words, do not take the above categorization too 
  3936.  seriously.  Look at the documentation instead. 
  3937.  
  3938.  
  3939. ΓòÉΓòÉΓòÉ 17.2. CVS's exit status ΓòÉΓòÉΓòÉ
  3940.  
  3941.  CVS can indicate to the calling environment whether it succeeded or failed by 
  3942.  setting its exit status. The exact way of testing the exit status will vary 
  3943.  from one operating system to another.  For example in a unix shell script the 
  3944.  '$?' variable will be 0 if the last command returned a successful exit status, 
  3945.  or greater than 0 if the exit status indicated failure. 
  3946.  
  3947.  If CVS is successful, it returns a successful status; if there is an error, it 
  3948.  prints an error message and returns a failure status.  The one exception to 
  3949.  this is the cvs diff command.  It will return a successful status if it found 
  3950.  no differences, or a failure status if there were differences or if there was 
  3951.  an error.  Because this behavior provides no good way to detect errors, in the 
  3952.  future it is possible that cvs diff will be changed to behave like the other 
  3953.  CVS commands. 
  3954.  
  3955.  
  3956. ΓòÉΓòÉΓòÉ 17.3. Default options and the ~/.cvsrc file ΓòÉΓòÉΓòÉ
  3957.  
  3958.  There are some command_options that are used so often that you might have set 
  3959.  up an alias or some other means to make sure you always specify that option. 
  3960.  One example (the one that drove the implementation of the '.cvsrc' support, 
  3961.  actually) is that many people find the default output of the 'diff' command to 
  3962.  be very hard to read, and that either context diffs or unidiffs are much 
  3963.  easier to understand. 
  3964.  
  3965.  The '~/.cvsrc' file is a way that you can add default options to cvs_commands 
  3966.  within cvs, instead of relying on aliases or other shell scripts. 
  3967.  
  3968.  The format of the '~/.cvsrc' file is simple.  The file is searched for a line 
  3969.  that begins with the same name as the cvs_command being executed.  If a match 
  3970.  is found, then the remainder of the line is split up (at whitespace 
  3971.  characters) into separate options and added to the command arguments before 
  3972.  any options from the command line. 
  3973.  
  3974.  If a command has two names (e.g., checkout and co), the official name, not 
  3975.  necessarily the one used on the command line, will be used to match against 
  3976.  the file.  So if this is the contents of the user's '~/.cvsrc' file: 
  3977.  
  3978.                       log -N
  3979.                       diff -u
  3980.                       update -P
  3981.                       checkout -P
  3982.  
  3983.  the command 'cvs checkout foo' would have the '-P' option added to the 
  3984.  arguments, as well as 'cvs co foo'. 
  3985.  
  3986.  With the example file above, the output from 'cvs diff foobar' will be in 
  3987.  unidiff format.  'cvs diff -c foobar' will provide context diffs, as usual. 
  3988.  Getting "old" format diffs would be slightly more complicated, because diff 
  3989.  doesn't have an option to specify use of the "old" format, so you would need 
  3990.  'cvs -f diff foobar'. 
  3991.  
  3992.  In place of the command name you can use cvs to specify global options (see 
  3993.  Global options).  For example the following line in '.cvsrc' 
  3994.  
  3995.                       cvs -z6
  3996.  
  3997.  causes CVS to use compression level 6. 
  3998.  
  3999.  
  4000. ΓòÉΓòÉΓòÉ 17.4. Global options ΓòÉΓòÉΓòÉ
  4001.  
  4002.  The available 'cvs_options' (that are given to the left of 'cvs_command') are: 
  4003.  
  4004.  --allow-root=rootdir 
  4005.            Specify legal CVSROOT directory.  See Password authentication 
  4006.            server. 
  4007.  
  4008.  -a 
  4009.            Authenticate all communication between the client and the server. 
  4010.            Only has an effect on the CVS client. As of this writing, this is 
  4011.            only implemented when using a GSSAPI connection (see GSSAPI 
  4012.            authenticated). Authentication prevents certain sorts of attacks 
  4013.            involving hijacking the active TCP connection. Enabling 
  4014.            authentication does not enable encryption. 
  4015.  
  4016.  -b bindir 
  4017.            In CVS 1.9.18 and older, this specified that RCS programs are in the 
  4018.            bindir directory. Current versions of CVS do not run RCS programs; 
  4019.            for compatibility this option is accepted, but it does nothing. 
  4020.  
  4021.  -T tempdir 
  4022.            Use tempdir as the directory where temporary files are located. 
  4023.            Overrides the setting of the $TMPDIR environment variable and any 
  4024.            precompiled directory.  This parameter should be specified as an 
  4025.            absolute pathname. 
  4026.  
  4027.  -d cvs_root_directory 
  4028.            Use cvs_root_directory as the root directory pathname of the 
  4029.            repository.  Overrides the setting of the $CVSROOT environment 
  4030.            variable.  See Repository. 
  4031.  
  4032.  -e editor 
  4033.            Use editor to enter revision log information.  Overrides the setting 
  4034.            of the $CVSEDITOR and $EDITOR environment variables.  For more 
  4035.            information, see Committing your changes. 
  4036.  
  4037.  -f 
  4038.            Do not read the '~/.cvsrc' file.  This option is most often used 
  4039.            because of the non-orthogonality of the CVS option set.  For 
  4040.            example, the 'cvs log' option '-N' (turn off display of tag names) 
  4041.            does not have a corresponding option to turn the display on.  So if 
  4042.            you have '-N' in the '~/.cvsrc' entry for 'log', you may need to use 
  4043.            '-f' to show the tag names. 
  4044.  
  4045.  -H 
  4046.  
  4047.  --help 
  4048.            Display usage information about the specified 'cvs_command' (but do 
  4049.            not actually execute the command).  If you don't specify a command 
  4050.            name, 'cvs -H' displays overall help for CVS, including a list of 
  4051.            other help options. 
  4052.  
  4053.  -l 
  4054.            Do not log the 'cvs_command' in the command history (but execute it 
  4055.            anyway).  See history, for information on command history. 
  4056.  
  4057.  -n 
  4058.            Do not change any files.  Attempt to execute the 'cvs_command', but 
  4059.            only to issue reports; do not remove, update, or merge any existing 
  4060.            files, or create any new files. 
  4061.  
  4062.            Note that CVS will not necessarily produce exactly the same output 
  4063.            as without '-n'.  In some cases the output will be the same, but in 
  4064.            other cases CVS will skip some of the processing that would have 
  4065.            been required to produce the exact same output. 
  4066.  
  4067.  -Q 
  4068.            Cause the command to be really quiet; the command will only generate 
  4069.            output for serious problems. 
  4070.  
  4071.  -q 
  4072.            Cause the command to be somewhat quiet; informational messages, such 
  4073.            as reports of recursion through subdirectories, are suppressed. 
  4074.  
  4075.  -r 
  4076.            Make new working files read-only.  Same effect as if the $CVSREAD 
  4077.            environment variable is set (see Environment variables).  The 
  4078.            default is to make working files writable, unless watches are on 
  4079.            (see Watches). 
  4080.  
  4081.  -s variable=value 
  4082.            Set a user variable (see Variables). 
  4083.  
  4084.  -t 
  4085.            Trace program execution; display messages showing the steps of CVS 
  4086.            activity.  Particularly useful with '-n' to explore the potential 
  4087.            impact of an unfamiliar command. 
  4088.  
  4089.  -v 
  4090.  
  4091.  --version 
  4092.            Display version and copyright information for CVS. 
  4093.  
  4094.  -w 
  4095.            Make new working files read-write.  Overrides the setting of the 
  4096.            $CVSREAD environment variable. Files are created read-write by 
  4097.            default, unless $CVSREAD is set or '-r' is given. 
  4098.  
  4099.  -x 
  4100.            Encrypt all communication between the client and the server.  Only 
  4101.            has an effect on the CVS client.  As of this writing, this is only 
  4102.            implemented when using a GSSAPI connection (see GSSAPI 
  4103.            authenticated) or a Kerberos connection (see Kerberos 
  4104.            authenticated). Enabling encryption implies that message traffic is 
  4105.            also authenticated.  Encryption support is not available by default; 
  4106.            it must be enabled using a special configure option, 
  4107.            '--enable-encryption', when you build CVS. 
  4108.  
  4109.  -z gzip-level 
  4110.            Set the compression level.  Only has an effect on the CVS client. 
  4111.  
  4112.  
  4113. ΓòÉΓòÉΓòÉ 17.5. Common command options ΓòÉΓòÉΓòÉ
  4114.  
  4115.  This section describes the 'command_options' that are available across several 
  4116.  CVS commands.  These options are always given to the right of 'cvs_command'. 
  4117.  Not all commands support all of these options; each option is only supported 
  4118.  for commands where it makes sense. However, when a command has one of these 
  4119.  options you can almost always count on the same behavior of the option as in 
  4120.  other commands.  (Other command options, which are listed with the individual 
  4121.  commands, may have different behavior from one CVS command to the other). 
  4122.  
  4123.  Warning: the 'history' command is an exception; it supports many options that 
  4124.  conflict even with these standard options. 
  4125.  
  4126.  -D date_spec 
  4127.            Use the most recent revision no later than date_spec. date_spec is a 
  4128.            single argument, a date description specifying a date in the past. 
  4129.  
  4130.            The specification is sticky when you use it to make a private copy 
  4131.            of a source file; that is, when you get a working file using '-D', 
  4132.            CVS records the date you specified, so that further updates in the 
  4133.            same directory will use the same date (for more information on 
  4134.            sticky tags/dates, see Sticky tags). 
  4135.  
  4136.            '-D' is available with the checkout, diff, export, history, rdiff, 
  4137.            rtag, and update commands. (The history command uses this option in 
  4138.            a slightly different way; see history options). 
  4139.  
  4140.            A wide variety of date formats are supported by CVS.  The most 
  4141.            standard ones are ISO8601 (from the International Standards 
  4142.            Organization) and the Internet e-mail standard (specified in RFC822 
  4143.            as amended by RFC1123). 
  4144.  
  4145.            ISO8601 dates have many variants but a few examples are: 
  4146.  
  4147.                       1972-09-24
  4148.                       1972-09-24 20:05
  4149.  For more details about ISO8601 dates, see: 
  4150.  
  4151.                       http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html
  4152.  In addition to the dates allowed in Internet e-mail itself, CVS also allows 
  4153.  some of the fields to be omitted.  For example: 
  4154.  
  4155.                       24 Sep 1972 20:05
  4156.                       24 Sep
  4157.  
  4158.  The date is interpreted as being in the local timezone, unless a specific 
  4159.  timezone is specified. 
  4160.  
  4161.  These two date formats are preferred.  However, CVS currently accepts a wide 
  4162.  variety of other date formats.  They are intentionally not documented here in 
  4163.  any detail, and future versions of CVS might not accept all of them. One such 
  4164.  format is month/day/year.  This may confuse people who are accustomed to 
  4165.  having the month and day in the other order; '1/4/96' is January 4, not April 
  4166.  1. 
  4167.  
  4168.  Remember to quote the argument to the '-D' flag so that your shell doesn't 
  4169.  interpret spaces as argument separators.  A command using the '-D' flag can 
  4170.  look like this: 
  4171.  
  4172.                       $ cvs diff -D "1 hour ago" cvs.texinfo
  4173.  
  4174.  -f 
  4175.            When you specify a particular date or tag to CVS commands, they 
  4176.            normally ignore files that do not contain the tag (or did not exist 
  4177.            prior to the date) that you specified.  Use the '-f' option if you 
  4178.            want files retrieved even when there is no match for the tag or 
  4179.            date.  (The most recent revision of the file will be used). 
  4180.  
  4181.            '-f' is available with these commands: annotate, checkout, export, 
  4182.            rdiff, rtag, and update. 
  4183.  
  4184.            Warning:  The commit and remove commands also have a '-f' option, 
  4185.            but it has a different behavior for those commands.  See commit 
  4186.            options, and Removing files. 
  4187.  
  4188.  -k kflag 
  4189.            Alter the default processing of keywords. See Keyword substitution, 
  4190.            for the meaning of kflag.  Your kflag specification is sticky when 
  4191.            you use it to create a private copy of a source file; that is, when 
  4192.            you use this option with the checkout or update commands, CVS 
  4193.            associates your selected kflag with the file, and continues to use 
  4194.            it with future update commands on the same file until you specify 
  4195.            otherwise. 
  4196.  
  4197.            The '-k' option is available with the add, checkout, diff, import 
  4198.            and update commands. 
  4199.  
  4200.  -l 
  4201.            Local; run only in current working directory, rather than recursing 
  4202.            through subdirectories. 
  4203.  
  4204.            Warning: this is not the same as the overall 'cvs -l' option, which 
  4205.            you can specify to the left of a cvs command! 
  4206.  
  4207.            Available with the following commands: annotate, checkout, commit, 
  4208.            diff, edit, editors, export, log, rdiff, remove, rtag, status, tag, 
  4209.            unedit, update, watch, and watchers. 
  4210.  
  4211.  -m message 
  4212.            Use message as log information, instead of invoking an editor. 
  4213.  
  4214.            Available with the following commands: add, commit and import. 
  4215.  
  4216.  -n 
  4217.            Do not run any checkout/commit/tag program.  (A program can be 
  4218.            specified to run on each of these activities, in the modules 
  4219.            database (see modules); this option bypasses it). 
  4220.  
  4221.            Warning: this is not the same as the overall 'cvs -n' option, which 
  4222.            you can specify to the left of a cvs command! 
  4223.  
  4224.            Available with the checkout, commit, export, and rtag commands. 
  4225.  
  4226.  -P 
  4227.            Prune empty directories.  See Removing directories. 
  4228.  
  4229.  -p 
  4230.            Pipe the files retrieved from the repository to standard output, 
  4231.            rather than writing them in the current directory.  Available with 
  4232.            the checkout and update commands. 
  4233.  
  4234.  -R 
  4235.            Process directories recursively.  This is on by default. 
  4236.  
  4237.            Available with the following commands: annotate, checkout, commit, 
  4238.            diff, edit, editors, export, rdiff, remove, rtag, status, tag, 
  4239.            unedit, update, watch, and watchers. 
  4240.  
  4241.  -r tag 
  4242.            Use the revision specified by the tag argument instead of the 
  4243.            default head revision.  As well as arbitrary tags defined with the 
  4244.            tag or rtag command, two special tags are always available: 'HEAD' 
  4245.            refers to the most recent version available in the repository, and 
  4246.            'BASE' refers to the revision you last checked out into the current 
  4247.            working directory. 
  4248.  
  4249.            The tag specification is sticky when you use this with checkout or 
  4250.            update to make your own copy of a file: CVS remembers the tag and 
  4251.            continues to use it on future update commands, until you specify 
  4252.            otherwise (for more information on sticky tags/dates, see Sticky 
  4253.            tags).  The tag can be either a symbolic or numeric tag. See Tags. 
  4254.  
  4255.            Specifying the '-q' global option along with the '-r' command option 
  4256.            is often useful, to suppress the warning messages when the RCS file 
  4257.            does not contain the specified tag. 
  4258.  
  4259.            Warning: this is not the same as the overall 'cvs -r' option, which 
  4260.            you can specify to the left of a CVS command! 
  4261.  
  4262.            '-r' is available with the checkout, commit, diff, history, export, 
  4263.            rdiff, rtag, and update commands. 
  4264.  
  4265.  -W 
  4266.            Specify file names that should be filtered.  You can use this option 
  4267.            repeatedly.  The spec can be a file name pattern of the same type 
  4268.            that you can specify in the '.cvswrappers' file. Available with the 
  4269.            following commands: import, and update. 
  4270.  
  4271.  
  4272. ΓòÉΓòÉΓòÉ 17.6. admin---Administration ΓòÉΓòÉΓòÉ
  4273.  
  4274.      Requires: repository, working directory. 
  4275.  
  4276.      Changes: repository. 
  4277.  
  4278.      Synonym: rcs 
  4279.  
  4280.  This is the CVS interface to assorted administrative facilities.  Some of them 
  4281.  have questionable usefulness for CVS but exist for historical purposes.  Some 
  4282.  of the questionable options are likely to disappear in the future.  This 
  4283.  command does work recursively, so extreme care should be used. 
  4284.  
  4285.  On unix, if there is a group named cvsadmin, only members of that group can 
  4286.  run cvs admin. This group should exist on the server, or any system running 
  4287.  the non-client/server CVS.  To disallow cvs admin for all users, create a 
  4288.  group with no users in it.  On NT, the cvsadmin feature does not exist and all 
  4289.  users can run cvs admin. 
  4290.  
  4291.  admin options                 admin options 
  4292.  
  4293.  
  4294. ΓòÉΓòÉΓòÉ 17.6.1. admin options ΓòÉΓòÉΓòÉ
  4295.  
  4296.  Some of these options have questionable usefulness for CVS but exist for 
  4297.  historical purposes.  Some even make it impossible to use CVS until you undo 
  4298.  the effect! 
  4299.  
  4300.  -Aoldfile 
  4301.            Might not work together with CVS.  Append the access list of oldfile 
  4302.            to the access list of the RCS file. 
  4303.  
  4304.  -alogins 
  4305.            Might not work together with CVS.  Append the login names appearing 
  4306.            in the comma-separated list logins to the access list of the RCS 
  4307.            file. 
  4308.  
  4309.  -b[rev] 
  4310.            Set the default branch to rev.  In CVS, you normally do not 
  4311.            manipulate default branches; sticky tags (see Sticky tags) are a 
  4312.            better way to decide which branch you want to work on.  There is one 
  4313.            reason to run cvs admin -b: to revert to the vendor's version when 
  4314.            using vendor branches (see Reverting local changes). There can be no 
  4315.            space between '-b' and its argument. 
  4316.  
  4317.  -cstring 
  4318.            Sets the comment leader to string.  The comment leader is not used 
  4319.            by current versions of CVS or RCS 5.7.  Therefore, you can almost 
  4320.            surely not worry about it.  See Keyword substitution. 
  4321.  
  4322.  -e[logins] 
  4323.            Might not work together with CVS.  Erase the login names appearing 
  4324.            in the comma-separated list logins from the access list of the RCS 
  4325.            file.  If logins is omitted, erase the entire access list. 
  4326.  
  4327.  -I 
  4328.            Run interactively, even if the standard input is not a terminal. 
  4329.            This option does not work with the client/server CVS and is likely 
  4330.            to disappear in a future release of CVS. 
  4331.  
  4332.  -i 
  4333.            Useless with CVS.  This creates and initializes a new RCS file, 
  4334.            without depositing a revision.  With CVS, add files with the cvs add 
  4335.            command (see Adding files). 
  4336.  
  4337.  -ksubst 
  4338.            Set the default keyword substitution to subst.  See Keyword 
  4339.            substitution.  Giving an explicit '-k' option to cvs update, cvs 
  4340.            export, or cvs checkout overrides this default. 
  4341.  
  4342.  -l[rev] 
  4343.            Lock the revision with number rev.  If a branch is given, lock the 
  4344.            latest revision on that branch.  If rev is omitted, lock the latest 
  4345.            revision on the default branch.  There can be no space between '-l' 
  4346.            and its argument. 
  4347.  
  4348.            This can be used in conjunction with the 'rcslock.pl' script in the 
  4349.            'contrib' directory of the CVS source distribution to provide 
  4350.            reserved checkouts (where only one user can be editing a given file 
  4351.            at a time).  See the comments in that file for details (and see the 
  4352.            'README' file in that directory for disclaimers about the 
  4353.            unsupported nature of contrib).  According to comments in that file, 
  4354.            locking must set to strict (which is the default). 
  4355.  
  4356.  -L 
  4357.            Set locking to strict.  Strict locking means that the owner of an 
  4358.            RCS file is not exempt from locking for checkin.  For use with CVS, 
  4359.            strict locking must be set; see the discussion under the '-l' option 
  4360.            above. 
  4361.  
  4362.  -mrev:msg 
  4363.            Replace the log message of revision rev with msg. 
  4364.  
  4365.  -Nname[:[rev]] 
  4366.            Act like '-n', except override any previous assignment of name.  For 
  4367.            use with magic branches, see Magic branch numbers. 
  4368.  
  4369.  -nname[:[rev]] 
  4370.            Associate the symbolic name name with the branch or revision rev. 
  4371.            It is normally better to use 'cvs tag' or 'cvs rtag' instead. 
  4372.            Delete the symbolic name if both ':' and rev are omitted; otherwise, 
  4373.            print an error message if name is already associated with another 
  4374.            number. If rev is symbolic, it is expanded before association.  A 
  4375.            rev consisting of a branch number followed by a '.' stands for the 
  4376.            current latest revision in the branch.  A ':' with an empty rev 
  4377.            stands for the current latest revision on the default branch, 
  4378.            normally the trunk.  For example, 'cvs admin -nname:' associates 
  4379.            name with the current latest revision of all the RCS files; this 
  4380.            contrasts with 'cvs admin -nname:$' which associates name with the 
  4381.            revision numbers extracted from keyword strings in the corresponding 
  4382.            working files. 
  4383.  
  4384.  -orange 
  4385.            Deletes (outdates) the revisions given by range. 
  4386.  
  4387.            Note that this command can be quite dangerous unless you know 
  4388.            exactly what you are doing (for example see the warnings below about 
  4389.            how the rev1:rev2 syntax is confusing). 
  4390.  
  4391.            If you are short on disc this option might help you. But think twice 
  4392.            before using it---there is no way short of restoring the latest 
  4393.            backup to undo this command! If you delete different revisions than 
  4394.            you planned, either due to carelessness or (heaven forbid) a CVS 
  4395.            bug, there is no opportunity to correct the error before the 
  4396.            revisions are deleted.  It probably would be a good idea to 
  4397.            experiment on a copy of the repository first. 
  4398.  
  4399.            Specify range in one of the following ways: 
  4400.  
  4401.              rev1::rev2 
  4402.                          Collapse all revisions between rev1 and rev2, so that 
  4403.                          CVS only stores the differences associated with going 
  4404.                          from rev1 to rev2, not intermediate steps.  For 
  4405.                          example, after '-o 1.3::1.5' one can retrieve revision 
  4406.                          1.3, revision 1.5, or the differences to get from 1.3 
  4407.                          to 1.5, but not the revision 1.4, or the differences 
  4408.                          between 1.3 and 1.4.  Other examples: '-o 1.3::1.4' 
  4409.                          and '-o 1.3::1.3' have no effect, because there are no 
  4410.                          intermediate revisions to remove. 
  4411.  
  4412.              ::rev 
  4413.                          Collapse revisions between the beginning of the branch 
  4414.                          containing rev and rev itself.  The branchpoint and 
  4415.                          rev are left intact.  For example, '-o ::1.3.2.6' 
  4416.                          deletes revision 1.3.2.1, revision 1.3.2.5, and 
  4417.                          everything in between, but leaves 1.3 and 1.3.2.6 
  4418.                          intact. 
  4419.  
  4420.              rev:: 
  4421.                          Collapse revisions between rev and the end of the 
  4422.                          branch containing rev.  Revision rev is left intact 
  4423.                          but the head revision is deleted. 
  4424.  
  4425.              rev 
  4426.                          Delete the revision rev.  For example, '-o 1.3' is 
  4427.                          equivalent to '-o 1.2::1.4'. 
  4428.  
  4429.              rev1:rev2 
  4430.                          Delete the revisions from rev1 to rev2, inclusive, on 
  4431.                          the same branch.  One will not be able to retrieve 
  4432.                          rev1 or rev2 or any of the revisions in between.  For 
  4433.                          example, the command 'cvs admin -oR_1_01:R_1_02 .' is 
  4434.                          rarely useful. It means to delete revisions up to, and 
  4435.                          including, the tag R_1_02.  But beware!  If there are 
  4436.                          files that have not changed between R_1_02 and R_1_03 
  4437.                          the file will have the same numerical revision number 
  4438.                          assigned to the tags R_1_02 and R_1_03.  So not only 
  4439.                          will it be impossible to retrieve R_1_02; R_1_03 will 
  4440.                          also have to be restored from the tapes!  In most 
  4441.                          cases you want to specify rev1::rev2 instead. 
  4442.  
  4443.              :rev 
  4444.                          Delete revisions from the beginning of the branch 
  4445.                          containing rev up to and including rev. 
  4446.  
  4447.              rev: 
  4448.                          Delete revisions from revision rev, including rev 
  4449.                          itself, to the end of the branch containing rev. 
  4450.  
  4451.              None of the revisions to be deleted may have branches or locks. 
  4452.  
  4453.              If any of the revisions to be deleted have symbolic names, and one 
  4454.              specifies one of the '::' syntaxes, then CVS will give an error 
  4455.              and not delete any revisions.  If you really want to delete both 
  4456.              the symbolic names and the revisions, first delete the symbolic 
  4457.              names with cvs tag -d, then run cvs admin -o.  If one specifies 
  4458.              the non-'::' syntaxes, then CVS will delete the revisions but 
  4459.              leave the symbolic names pointing to nonexistent revisions.  This 
  4460.              behavior is preserved for compatibility with previous versions of 
  4461.              CVS, but because it isn't very useful, in the future it may change 
  4462.              to be like the '::' case. 
  4463.  
  4464.              Due to the way CVS handles branches rev cannot be specified 
  4465.              symbolically if it is a branch. See Magic branch numbers, for an 
  4466.              explanation. Make sure that no-one has checked out a copy of the 
  4467.              revision you outdate.  Strange things will happen if he starts to 
  4468.              edit it and tries to check it back in.  For this reason, this 
  4469.              option is not a good way to take back a bogus commit; commit a new 
  4470.              revision undoing the bogus change instead (see Merging two 
  4471.              revisions). 
  4472.  
  4473.  -q 
  4474.            Run quietly; do not print diagnostics. 
  4475.  
  4476.  -sstate[:rev] 
  4477.            Useful with CVS.  Set the state attribute of the revision rev to 
  4478.            state.  If rev is a branch number, assume the latest revision on 
  4479.            that branch.  If rev is omitted, assume the latest revision on the 
  4480.            default branch.  Any identifier is acceptable for state.  A useful 
  4481.            set of states is 'Exp' (for experimental), 'Stab' (for stable), and 
  4482.            'Rel' (for released).  By default, the state of a new revision is 
  4483.            set to 'Exp' when it is created.  The state is visible in the output 
  4484.            from cvs log (see log), and in the '$'Log$} and '$'State$} keywords 
  4485.            (see Keyword substitution).  Note that CVS uses the dead state for 
  4486.            its own purposes; to take a file to or from the dead state use 
  4487.            commands like cvs remove and cvs add, not cvs admin -s. 
  4488.  
  4489.  -t[file] 
  4490.            Useful with CVS.  Write descriptive text from the contents of the 
  4491.            named file into the RCS file, deleting the existing text.  The file 
  4492.            pathname may not begin with '-'.  The descriptive text can be seen 
  4493.            in the output from 'cvs log' (see log). There can be no space 
  4494.            between '-t' and its argument. 
  4495.  
  4496.            If file is omitted, obtain the text from standard input, terminated 
  4497.            by end-of-file or by a line containing '.' by itself. Prompt for the 
  4498.            text if interaction is possible; see '-I'.  Reading from standard 
  4499.            input does not work for client/server CVS and may change in a future 
  4500.            release of CVS. 
  4501.  
  4502.  -t-string 
  4503.            Similar to '-tfile'. Write descriptive text from the string into the 
  4504.            RCS file, deleting the existing text. There can be no space between 
  4505.            '-t' and its argument. 
  4506.  
  4507.  -U 
  4508.            Set locking to non-strict.  Non-strict locking means that the owner 
  4509.            of a file need not lock a revision for checkin.  For use with CVS, 
  4510.            strict locking must be set; see the discussion under the '-l' option 
  4511.            above. 
  4512.  
  4513.  -u[rev] 
  4514.            See the option '-l' above, for a discussion of using this option 
  4515.            with CVS.  Unlock the revision with number rev.  If a branch is 
  4516.            given, unlock the latest revision on that branch.  If rev is 
  4517.            omitted, remove the latest lock held by the caller. Normally, only 
  4518.            the locker of a revision may unlock it. Somebody else unlocking a 
  4519.            revision breaks the lock. This causes a mail message to be sent to 
  4520.            the original locker.  The message contains a commentary solicited 
  4521.            from the breaker.  The commentary is terminated by end-of-file or by 
  4522.            a line containing . by itself. There can be no space between '-u' 
  4523.            and its argument. 
  4524.  
  4525.  -Vn 
  4526.            In previous versions of CVS, this option meant to write an RCS file 
  4527.            which would be acceptable to RCS version n, but it is now obsolete 
  4528.            and specifying it will produce an error. 
  4529.  
  4530.  -xsuffixes 
  4531.            In previous versions of CVS, this was documented as a way of 
  4532.            specifying the names of the RCS files.  However, CVS has always 
  4533.            required that the RCS files used by CVS end in ',v', so this option 
  4534.            has never done anything useful. 
  4535.  
  4536.  
  4537. ΓòÉΓòÉΓòÉ 17.7. checkout---Check out sources for editing ΓòÉΓòÉΓòÉ
  4538.  
  4539.      Synopsis: checkout [options] modules┬╖┬╖┬╖ 
  4540.  
  4541.      Requires: repository. 
  4542.  
  4543.      Changes: working directory. 
  4544.  
  4545.      Synonyms: co, get 
  4546.  
  4547.  Create or update a working directory containing copies of the source files 
  4548.  specified by modules.  You must execute checkout before using most of the 
  4549.  other CVS commands, since most of them operate on your working directory. 
  4550.  
  4551.  The modules are either symbolic names for some collection of source 
  4552.  directories and files, or paths to directories or files in the repository. 
  4553.  The symbolic names are defined in the 'modules' file. See modules. Depending 
  4554.  on the modules you specify, checkout may recursively create directories and 
  4555.  populate them with the appropriate source files.  You can then edit these 
  4556.  source files at any time (regardless of whether other software developers are 
  4557.  editing their own copies of the sources); update them to include new changes 
  4558.  applied by others to the source repository; or commit your work as a permanent 
  4559.  change to the source repository. 
  4560.  
  4561.  Note that checkout is used to create directories.  The top-level directory 
  4562.  created is always added to the directory where checkout is invoked, and 
  4563.  usually has the same name as the specified module.  In the case of a module 
  4564.  alias, the created sub-directory may have a different name, but you can be 
  4565.  sure that it will be a sub-directory, and that checkout will show the relative 
  4566.  path leading to each file as it is extracted into your private work area 
  4567.  (unless you specify the '-Q' global option). 
  4568.  
  4569.  The files created by checkout are created read-write, unless the '-r' option 
  4570.  to CVS (see Global options) is specified, the CVSREAD environment variable is 
  4571.  specified (see Environment variables), or a watch is in effect for that file 
  4572.  (see Watches). 
  4573.  
  4574.  Note that running checkout on a directory that was already built by a prior 
  4575.  checkout is also permitted. This is similar to specifying the '-d' option to 
  4576.  the update command in the sense that new directories that have been created in 
  4577.  the repository will appear in your work area. However, checkout takes a module 
  4578.  name whereas update takes a directory name.  Also to use checkout this way it 
  4579.  must be run from the top level directory (where you originally ran checkout 
  4580.  from), so before you run checkout to update an existing directory, don't 
  4581.  forget to change your directory to the top level directory. 
  4582.  
  4583.  For the output produced by the checkout command see update output. 
  4584.  
  4585.  checkout options              checkout options 
  4586.  checkout examples             checkout examples 
  4587.  
  4588.  
  4589. ΓòÉΓòÉΓòÉ 17.7.1. checkout options ΓòÉΓòÉΓòÉ
  4590.  
  4591.  These standard options are supported by checkout (see Common options, for a 
  4592.  complete description of them): 
  4593.  
  4594.  -D date 
  4595.            Use the most recent revision no later than date. This option is 
  4596.            sticky, and implies '-P'.  See Sticky tags, for more information on 
  4597.            sticky tags/dates. 
  4598.  
  4599.  -f 
  4600.            Only useful with the '-D date' or '-r tag' flags.  If no matching 
  4601.            revision is found, retrieve the most recent revision (instead of 
  4602.            ignoring the file). 
  4603.  
  4604.  -k kflag 
  4605.            Process keywords according to kflag.  See Keyword substitution. This 
  4606.            option is sticky; future updates of this file in this working 
  4607.            directory will use the same kflag.  The status command can be viewed 
  4608.            to see the sticky options.  See Invoking CVS, for more information 
  4609.            on the status command. 
  4610.  
  4611.  -l 
  4612.            Local; run only in current working directory. 
  4613.  
  4614.  -n 
  4615.            Do not run any checkout program (as specified with the '-o' option 
  4616.            in the modules file; see modules). 
  4617.  
  4618.  -P 
  4619.            Prune empty directories.  See Moving directories. 
  4620.  
  4621.  -p 
  4622.            Pipe files to the standard output. 
  4623.  
  4624.  -R 
  4625.            Checkout directories recursively.  This option is on by default. 
  4626.  
  4627.  -r tag 
  4628.            Use revision tag.  This option is sticky, and implies '-P'. See 
  4629.            Sticky tags, for more information on sticky tags/dates. 
  4630.  
  4631.  In addition to those, you can use these special command options with checkout: 
  4632.  
  4633.  -A 
  4634.            Reset any sticky tags, dates, or '-k' options. See Sticky tags, for 
  4635.            more information on sticky tags/dates. 
  4636.  
  4637.  -c 
  4638.            Copy the module file, sorted, to the standard output, instead of 
  4639.            creating or modifying any files or directories in your working 
  4640.            directory. 
  4641.  
  4642.  -d dir 
  4643.            Create a directory called dir for the working files, instead of 
  4644.            using the module name.  In general, using this flag is equivalent to 
  4645.            using 'mkdir dir; cd dir' followed by the checkout command without 
  4646.            the '-d' flag. 
  4647.  
  4648.            There is an important exception, however.  It is very convenient 
  4649.            when checking out a single item to have the output appear in a 
  4650.            directory that doesn't contain empty intermediate directories.  In 
  4651.            this case only, CVS tries to ``shorten'' pathnames to avoid those 
  4652.            empty directories. 
  4653.  
  4654.            For example, given a module 'foo' that contains the file 'bar.c', 
  4655.            the command 'cvs co -d dir foo' will create directory 'dir' and 
  4656.            place 'bar.c' inside.  Similarly, given a module 'bar' which has 
  4657.            subdirectory 'baz' wherein there is a file 'quux.c', the command 
  4658.            'cvs -d dir co bar/baz' will create directory 'dir' and place 
  4659.            'quux.c' inside. 
  4660.  
  4661.            Using the '-N' flag will defeat this behavior. Given the same module 
  4662.            definitions above, 'cvs co -N -d dir foo' will create directories 
  4663.            'dir/foo' and place 'bar.c' inside, while 'cvs co -N -d dir bar/baz' 
  4664.            will create directories 'dir/bar/baz' and place 'quux.c' inside. 
  4665.  
  4666.  -j tag 
  4667.            With two '-j' options, merge changes from the revision specified 
  4668.            with the first '-j' option to the revision specified with the second 
  4669.            'j' option, into the working directory. 
  4670.  
  4671.            With one '-j' option, merge changes from the ancestor revision to 
  4672.            the revision specified with the '-j' option, into the working 
  4673.            directory.  The ancestor revision is the common ancestor of the 
  4674.            revision which the working directory is based on, and the revision 
  4675.            specified in the '-j' option. 
  4676.  
  4677.            In addition, each -j option can contain an optional date 
  4678.            specification which, when used with branches, can limit the chosen 
  4679.            revision to one within a specific date.  An optional date is 
  4680.            specified by adding a colon (:) to the tag: 
  4681.            '-jSymbolic_Tag:Date_Specifier'. 
  4682.  
  4683.            See Branching and merging. 
  4684.  
  4685.  -N 
  4686.            Only useful together with '-d dir'.  With this option, CVS will not 
  4687.            ``shorten'' module paths in your working directory when you check 
  4688.            out a single module.  See the '-d' flag for examples and a 
  4689.            discussion. 
  4690.  
  4691.  -s 
  4692.            Like '-c', but include the status of all modules, and sort it by the 
  4693.            status string.  See modules, for info about the '-s' option that is 
  4694.            used inside the modules file to set the module status. 
  4695.  
  4696.  
  4697. ΓòÉΓòÉΓòÉ 17.7.2. checkout examples ΓòÉΓòÉΓòÉ
  4698.  
  4699.  Get a copy of the module 'tc': 
  4700.  
  4701.                       $ cvs checkout tc
  4702.  
  4703.  Get a copy of the module 'tc' as it looked one day ago: 
  4704.  
  4705.                       $ cvs checkout -D yesterday tc
  4706.  
  4707.  
  4708. ΓòÉΓòÉΓòÉ 17.8. commit---Check files into the repository ΓòÉΓòÉΓòÉ
  4709.  
  4710.      Synopsis: commit [-lnRf] [-m 'log_message' | -F file] [-r revision] 
  4711.       [files┬╖┬╖┬╖] 
  4712.  
  4713.      Requires: working directory, repository. 
  4714.  
  4715.      Changes: repository. 
  4716.  
  4717.      Synonym: ci 
  4718.  
  4719.  Use commit when you want to incorporate changes from your working source files 
  4720.  into the source repository. 
  4721.  
  4722.  If you don't specify particular files to commit, all of the files in your 
  4723.  working current directory are examined.  commit is careful to change in the 
  4724.  repository only those files that you have really changed.  By default (or if 
  4725.  you explicitly specify the '-R' option), files in subdirectories are also 
  4726.  examined and committed if they have changed; you can use the '-l' option to 
  4727.  limit commit to the current directory only. 
  4728.  
  4729.  commit verifies that the selected files are up to date with the current 
  4730.  revisions in the source repository; it will notify you, and exit without 
  4731.  committing, if any of the specified files must be made current first with 
  4732.  update (see update). commit does not call the update command for you, but 
  4733.  rather leaves that for you to do when the time is right. 
  4734.  
  4735.  When all is well, an editor is invoked to allow you to enter a log message 
  4736.  that will be written to one or more logging programs (see modules, and see 
  4737.  loginfo) and placed in the RCS file inside the repository.  This log message 
  4738.  can be retrieved with the log command; see log.  You can specify the log 
  4739.  message on the command line with the '-m message' option, and thus avoid the 
  4740.  editor invocation, or use the '-F file' option to specify that the argument 
  4741.  file contains the log message. 
  4742.  
  4743.  commit options                commit options 
  4744.  commit examples               commit examples 
  4745.  
  4746.  
  4747. ΓòÉΓòÉΓòÉ 17.8.1. commit options ΓòÉΓòÉΓòÉ
  4748.  
  4749.  These standard options are supported by commit (see Common options, for a 
  4750.  complete description of them): 
  4751.  
  4752.  -l 
  4753.            Local; run only in current working directory. 
  4754.  
  4755.  -n 
  4756.            Do not run any module program. 
  4757.  
  4758.  -R 
  4759.            Commit directories recursively.  This is on by default. 
  4760.  
  4761.  -r revision 
  4762.            Commit to revision.  revision must be either a branch, or a revision 
  4763.            on the main trunk that is higher than any existing revision number 
  4764.            (see Assigning revisions).  You cannot commit to a specific revision 
  4765.            on a branch. 
  4766.  
  4767.  commit also supports these options: 
  4768.  
  4769.  -F file 
  4770.            Read the log message from file, instead of invoking an editor. 
  4771.  
  4772.  -f 
  4773.            Note that this is not the standard behavior of the '-f' option as 
  4774.            defined in Common options. 
  4775.  
  4776.            Force CVS to commit a new revision even if you haven't made any 
  4777.            changes to the file.  If the current revision of file is 1.7, then 
  4778.            the following two commands are equivalent: 
  4779.  
  4780.                       $ cvs commit -f file
  4781.                       $ cvs commit -r 1.8 file
  4782.  
  4783.  The '-f' option disables recursion (i.e., it implies '-l').  To force CVS to 
  4784.  commit a new revision for all files in all subdirectories, you must use '-f 
  4785.  -R'. 
  4786.  
  4787.  -m message 
  4788.            Use message as the log message, instead of invoking an editor. 
  4789.  
  4790.  
  4791. ΓòÉΓòÉΓòÉ 17.8.2. commit examples ΓòÉΓòÉΓòÉ
  4792.  
  4793.  
  4794. ΓòÉΓòÉΓòÉ 17.8.2.1. Committing to a branch ΓòÉΓòÉΓòÉ
  4795.  
  4796.  You can commit to a branch revision (one that has an even number of dots) with 
  4797.  the '-r' option.  To create a branch revision, use the '-b' option of the rtag 
  4798.  or tag commands (see tag or see rtag).  Then, either checkout or update can be 
  4799.  used to base your sources on the newly created branch.  From that point on, 
  4800.  all commit changes made within these working sources will be automatically 
  4801.  added to a branch revision, thereby not disturbing main-line development in 
  4802.  any way.  For example, if you had to create a patch to the 1.2 version of the 
  4803.  product, even though the 2.0 version is already under development, you might 
  4804.  do: 
  4805.  
  4806.                       $ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
  4807.                       $ cvs checkout -r FCS1_2_Patch product_module
  4808.                       $ cd product_module
  4809.                       [[ hack away ]]
  4810.                       $ cvs commit
  4811.  
  4812.  This works automatically since the '-r' option is sticky. 
  4813.  
  4814.  
  4815. ΓòÉΓòÉΓòÉ 17.8.2.2. Creating the branch after editing ΓòÉΓòÉΓòÉ
  4816.  
  4817.  Say you have been working on some extremely experimental software, based on 
  4818.  whatever revision you happened to checkout last week.  If others in your group 
  4819.  would like to work on this software with you, but without disturbing main-line 
  4820.  development, you could commit your change to a new branch.  Others can then 
  4821.  checkout your experimental stuff and utilize the full benefit of CVS conflict 
  4822.  resolution.  The scenario might look like: 
  4823.  
  4824.                       [[ hacked sources are present ]]
  4825.                       $ cvs tag -b EXPR1
  4826.                       $ cvs update -r EXPR1
  4827.                       $ cvs commit
  4828.  
  4829.  The update command will make the '-r EXPR1' option sticky on all files.  Note 
  4830.  that your changes to the files will never be removed by the update command. 
  4831.  The commit will automatically commit to the correct branch, because the '-r' 
  4832.  is sticky.  You could also do like this: 
  4833.  
  4834.                       [[ hacked sources are present ]]
  4835.                       $ cvs tag -b EXPR1
  4836.                       $ cvs commit -r EXPR1
  4837.  
  4838.  but then, only those files that were changed by you will have the '-r EXPR1' 
  4839.  sticky flag.  If you hack away, and commit without specifying the '-r EXPR1' 
  4840.  flag, some files may accidentally end up on the main trunk. 
  4841.  
  4842.  To work with you on the experimental change, others would simply do 
  4843.  
  4844.                       $ cvs checkout -r EXPR1 whatever_module
  4845.  
  4846.  
  4847. ΓòÉΓòÉΓòÉ 17.9. diff---Show differences between revisions ΓòÉΓòÉΓòÉ
  4848.  
  4849.      Synopsis: diff [-lR] [format_options] [[-r rev1 | -D date1] [-r rev2 | 
  4850.       -D date2]] [files┬╖┬╖┬╖] 
  4851.  
  4852.      Requires: working directory, repository. 
  4853.  
  4854.      Changes: nothing. 
  4855.  
  4856.  The diff command is used to compare different revisions of files.  The default 
  4857.  action is to compare your working files with the revisions they were based on, 
  4858.  and report any differences that are found. 
  4859.  
  4860.  If any file names are given, only those files are compared.  If any 
  4861.  directories are given, all files under them will be compared. 
  4862.  
  4863.  The exit status for diff is different than for other CVS commands; for details 
  4864.  Exit status. 
  4865.  
  4866.  diff options                  diff options 
  4867.  diff examples                 diff examples 
  4868.  
  4869.  
  4870. ΓòÉΓòÉΓòÉ 17.9.1. diff options ΓòÉΓòÉΓòÉ
  4871.  
  4872.  These standard options are supported by diff (see Common options, for a 
  4873.  complete description of them): 
  4874.  
  4875.  -D date 
  4876.            Use the most recent revision no later than date. See '-r' for how 
  4877.            this affects the comparison. 
  4878.  
  4879.  -k kflag 
  4880.            Process keywords according to kflag.  See Keyword substitution. 
  4881.  
  4882.  -l 
  4883.            Local; run only in current working directory. 
  4884.  
  4885.  -R 
  4886.            Examine directories recursively.  This option is on by default. 
  4887.  
  4888.  -r tag 
  4889.            Compare with revision tag.  Zero, one or two '-r' options can be 
  4890.            present.  With no '-r' option, the working file will be compared 
  4891.            with the revision it was based on.  With one '-r', that revision 
  4892.            will be compared to your current working file. With two '-r' options 
  4893.            those two revisions will be compared (and your working file will not 
  4894.            affect the outcome in any way). One or both '-r' options can be 
  4895.            replaced by a '-D date' option, described above. 
  4896.  
  4897.  The following options specify the format of the output.  They have the same 
  4898.  meaning as in GNU diff. 
  4899.  
  4900.                       -0 -1 -2 -3 -4 -5 -6 -7 -8 -9
  4901.                       --binary
  4902.                       --brief
  4903.                       --changed-group-format=arg
  4904.                       -c
  4905.                        -C nlines
  4906.                        --context[=lines]
  4907.                       -e --ed
  4908.                       -t --expand-tabs
  4909.                       -f --forward-ed
  4910.                       --horizon-lines=arg
  4911.                       --ifdef=arg
  4912.                       -w --ignore-all-space
  4913.                       -B --ignore-blank-lines
  4914.                       -i --ignore-case
  4915.                       -I regexp
  4916.                         --ignore-matching-lines=regexp
  4917.                       -h
  4918.                       -b --ignore-space-change
  4919.                       -T --initial-tab
  4920.                       -L label
  4921.                        --label=label
  4922.                       --left-column
  4923.                       -d --minimal
  4924.                       -N --new-file
  4925.                       --new-line-format=arg
  4926.                       --old-line-format=arg
  4927.                       --paginate
  4928.                       -n --rcs
  4929.                       -s --report-identical-files
  4930.                       -p
  4931.                       --show-c-function
  4932.                       -y --side-by-side
  4933.                       -F regexp
  4934.                       --show-function-line=regexp
  4935.                       -H --speed-large-files
  4936.                       --suppress-common-lines
  4937.                       -a --text
  4938.                       --unchanged-group-format=arg
  4939.                       -u
  4940.                        -U nlines
  4941.                        --unified[=lines]
  4942.                       -V arg
  4943.                       -W columns
  4944.                        --width=columns
  4945.  
  4946.  
  4947. ΓòÉΓòÉΓòÉ 17.9.2. diff examples ΓòÉΓòÉΓòÉ
  4948.  
  4949.  The following line produces a Unidiff ('-u' flag) between revision 1.14 and 
  4950.  1.19 of 'backend.c'.  Due to the '-kk' flag no keywords are substituted, so 
  4951.  differences that only depend on keyword substitution are ignored. 
  4952.  
  4953.                       $ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
  4954.  
  4955.  Suppose the experimental branch EXPR1 was based on a set of files tagged 
  4956.  RELEASE_1_0.  To see what has happened on that branch, the following can be 
  4957.  used: 
  4958.  
  4959.                       $ cvs diff -r RELEASE_1_0 -r EXPR1
  4960.  
  4961.  A command like this can be used to produce a context diff between two 
  4962.  releases: 
  4963.  
  4964.                       $ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
  4965.  
  4966.  If you are maintaining ChangeLogs, a command like the following just before 
  4967.  you commit your changes may help you write the ChangeLog entry.  All local 
  4968.  modifications that have not yet been committed will be printed. 
  4969.  
  4970.                       $ cvs diff -u | less
  4971.  
  4972.  
  4973. ΓòÉΓòÉΓòÉ 17.10. export---Export sources from CVS, similar to checkout ΓòÉΓòÉΓòÉ
  4974.  
  4975.      Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module┬╖┬╖┬╖ 
  4976.  
  4977.      Requires: repository. 
  4978.  
  4979.      Changes: current directory. 
  4980.  
  4981.  This command is a variant of checkout; use it when you want a copy of the 
  4982.  source for module without the CVS administrative directories.  For example, 
  4983.  you might use export to prepare source for shipment off-site.  This command 
  4984.  requires that you specify a date or tag (with '-D' or '-r'), so that you can 
  4985.  count on reproducing the source you ship to others. 
  4986.  
  4987.  One often would like to use '-kv' with cvs export.  This causes any keywords 
  4988.  to be expanded such that an import done at some other site will not lose the 
  4989.  keyword revision information.  But be aware that doesn't handle an export 
  4990.  containing binary files correctly.  Also be aware that after having used 
  4991.  '-kv', one can no longer use the ident command (which is part of the RCS 
  4992.  suite---see ident(1)) which looks for keyword strings.  If you want to be able 
  4993.  to use ident you must not use '-kv'. 
  4994.  
  4995.  export options                export options 
  4996.  
  4997.  
  4998. ΓòÉΓòÉΓòÉ 17.10.1. export options ΓòÉΓòÉΓòÉ
  4999.  
  5000.  These standard options are supported by export (see Common options, for a 
  5001.  complete description of them): 
  5002.  
  5003.  -D date 
  5004.            Use the most recent revision no later than date. 
  5005.  
  5006.  -f 
  5007.            If no matching revision is found, retrieve the most recent revision 
  5008.            (instead of ignoring the file). 
  5009.  
  5010.  -l 
  5011.            Local; run only in current working directory. 
  5012.  
  5013.  -n 
  5014.            Do not run any checkout program. 
  5015.  
  5016.  -R 
  5017.            Export directories recursively.  This is on by default. 
  5018.  
  5019.  -r tag 
  5020.            Use revision tag. 
  5021.  
  5022.  In addition, these options (that are common to checkout and export) are also 
  5023.  supported: 
  5024.  
  5025.  -d dir 
  5026.            Create a directory called dir for the working files, instead of 
  5027.            using the module name. See checkout options, for complete details on 
  5028.            how CVS handles this flag. 
  5029.  
  5030.  -k subst 
  5031.            Set keyword expansion mode (see Substitution modes). 
  5032.  
  5033.  -N 
  5034.            Only useful together with '-d dir'. See checkout options, for 
  5035.            complete details on how CVS handles this flag. 
  5036.  
  5037.  
  5038. ΓòÉΓòÉΓòÉ 17.11. history---Show status of files and users ΓòÉΓòÉΓòÉ
  5039.  
  5040.      Synopsis:   history [-report] [-flags] [-options args] [files┬╖┬╖┬╖] 
  5041.  
  5042.      Requires: the file '$CVSROOT/CVSROOT/history' 
  5043.  
  5044.      Changes: nothing. 
  5045.  
  5046.  CVS can keep a history file that tracks each use of the checkout, commit, 
  5047.  rtag, update, and release commands.  You can use history to display this 
  5048.  information in various formats. 
  5049.  
  5050.  Logging must be enabled by creating the file '$CVSROOT/CVSROOT/history'. 
  5051.  
  5052.  Warning: history uses '-f', '-l', '-n', and '-p' in ways that conflict with 
  5053.  the normal use inside CVS (see Common options). 
  5054.  
  5055.  history options               history options 
  5056.  
  5057.  
  5058. ΓòÉΓòÉΓòÉ 17.11.1. history options ΓòÉΓòÉΓòÉ
  5059.  
  5060.  Several options (shown above as '-report')  control  what kind of report is 
  5061.  generated: 
  5062.  
  5063.  -c 
  5064.            Report on each time commit was used (i.e., each time the repository 
  5065.            was modified). 
  5066.  
  5067.  -e 
  5068.            Everything (all record types).  Equivalent to specifying '-x' with 
  5069.            all record types.  Of course, '-e' will also include record types 
  5070.            which are added in a future version of CVS; if you are writing a 
  5071.            script which can only handle certain record types, you'll want to 
  5072.            specify '-x'. 
  5073.  
  5074.  -m module 
  5075.            Report on a particular module.  (You can meaningfully use '-m' more 
  5076.            than once on the command line.) 
  5077.  
  5078.  -o 
  5079.            Report on checked-out modules. 
  5080.  
  5081.  -T 
  5082.            Report on all tags. 
  5083.  
  5084.  -x type 
  5085.            Extract a particular set of record types type from the CVS history. 
  5086.            The types are indicated by single letters, which you may specify in 
  5087.            combination. 
  5088.  
  5089.            Certain commands have a single record type: 
  5090.  
  5091.              F 
  5092.                          release 
  5093.  
  5094.              O 
  5095.                          checkout 
  5096.  
  5097.              E 
  5098.                          export 
  5099.  
  5100.              T 
  5101.                          rtag 
  5102.  
  5103.  
  5104.              One of four record types may result from an update: 
  5105.  
  5106.              C 
  5107.                          A merge was necessary but collisions were detected 
  5108.                          (requiring manual merging). 
  5109.  
  5110.              G 
  5111.                          A merge was necessary and it succeeded. 
  5112.  
  5113.              U 
  5114.                          A working file was copied from the repository. 
  5115.  
  5116.              W 
  5117.                          The working copy of a file was deleted during update 
  5118.                          (because it was gone from the repository). 
  5119.  
  5120.  
  5121.              One of three record types results from commit: 
  5122.  
  5123.              A 
  5124.                          A file was added for the first time. 
  5125.  
  5126.              M 
  5127.                          A file was modified. 
  5128.  
  5129.              R 
  5130.                          A file was removed. 
  5131.  
  5132.  
  5133.  The options shown as '-flags' constrain or expand the report without requiring 
  5134.  option arguments: 
  5135.  
  5136.  -a 
  5137.            Show data for all users (the default is to show data only for the 
  5138.            user executing history). 
  5139.  
  5140.  -l 
  5141.            Show last modification only. 
  5142.  
  5143.  -w 
  5144.            Show only the records for modifications done from the same working 
  5145.            directory where history is executing. 
  5146.  
  5147.  The options shown as '-options args' constrain the report based on an 
  5148.  argument: 
  5149.  
  5150.  -b str 
  5151.            Show data back to a record containing  the  string str  in  either 
  5152.            the module name, the file name, or the repository path. 
  5153.  
  5154.  -D date 
  5155.            Show data since date.  This is slightly different from the normal 
  5156.            use of '-D date', which selects the newest revision older than date. 
  5157.  
  5158.  -p repository 
  5159.            Show data for a particular source repository  (you can specify 
  5160.            several '-p' options on the same command line). 
  5161.  
  5162.  -r rev 
  5163.            Show records referring to revisions since the revision or tag named 
  5164.            rev appears in individual RCS files.  Each RCS file is searched for 
  5165.            the revision or tag. 
  5166.  
  5167.  -t tag 
  5168.            Show records since tag tag was last added to the history file.  This 
  5169.            differs from the '-r' flag above in that it reads only the history 
  5170.            file, not the RCS files, and is much faster. 
  5171.  
  5172.  -u name 
  5173.            Show records for user name. 
  5174.  
  5175.  
  5176. ΓòÉΓòÉΓòÉ 17.12. import---Import sources into CVS, using vendor branches ΓòÉΓòÉΓòÉ
  5177.  
  5178.      Synopsis: import [-options] repository vendortag releasetag┬╖┬╖┬╖ 
  5179.  
  5180.      Requires: Repository, source distribution directory. 
  5181.  
  5182.      Changes: repository. 
  5183.  
  5184.  Use import to incorporate an entire source distribution from an outside source 
  5185.  (e.g., a source vendor) into your source repository directory.  You can use 
  5186.  this command both for initial creation of a repository, and for wholesale 
  5187.  updates to the module from the outside source.  See Tracking sources, for a 
  5188.  discussion on this subject. 
  5189.  
  5190.  The repository argument gives a directory name (or a path to a directory) 
  5191.  under the CVS root directory for repositories; if the directory did not exist, 
  5192.  import creates it. 
  5193.  
  5194.  When you use import for updates to source that has been modified in your 
  5195.  source repository (since a prior import), it will notify you of any files that 
  5196.  conflict in the two branches of development; use 'checkout -j' to reconcile 
  5197.  the differences, as import instructs you to do. 
  5198.  
  5199.  If CVS decides a file should be ignored (see cvsignore), it does not import it 
  5200.  and prints 'I ' followed by the filename (see import output, for a complete 
  5201.  description of the output). 
  5202.  
  5203.  If the file '$CVSROOT/CVSROOT/cvswrappers' exists, any file whose names match 
  5204.  the specifications in that file will be treated as packages and the 
  5205.  appropriate filtering will be performed on the file/directory before being 
  5206.  imported.  See Wrappers. 
  5207.  
  5208.  The outside source is saved in a first-level branch, by default 1.1.1. 
  5209.  Updates are leaves of this branch; for example, files from the first imported 
  5210.  collection of source will be revision 1.1.1.1, then files from the first 
  5211.  imported update will be revision 1.1.1.2, and so on. 
  5212.  
  5213.  At least three arguments are required. repository is needed to identify the 
  5214.  collection of source.  vendortag is a tag for the entire branch (e.g., for 
  5215.  1.1.1).  You must also specify at least one releasetag to identify the files 
  5216.  at the leaves created each time you execute import. 
  5217.  
  5218.  Note that import does not change the directory in which you invoke it.  In 
  5219.  particular, it does not set up that directory as a CVS working directory; if 
  5220.  you want to work with the sources import them first and then check them out 
  5221.  into a different directory (see Getting the source). 
  5222.  
  5223.  import options                import options 
  5224.  import output                 import output 
  5225.  import examples               import examples 
  5226.  
  5227.  
  5228. ΓòÉΓòÉΓòÉ 17.12.1. import options ΓòÉΓòÉΓòÉ
  5229.  
  5230.  This standard option is supported by import (see Common options, for a 
  5231.  complete description): 
  5232.  
  5233.  -m message 
  5234.            Use message as log information, instead of invoking an editor. 
  5235.  
  5236.  There are the following additional special options. 
  5237.  
  5238.  -b branch 
  5239.            See Multiple vendor branches. 
  5240.  
  5241.  -k subst 
  5242.            Indicate the keyword expansion mode desired.  This setting will 
  5243.            apply to all files created during the import, but not to any files 
  5244.            that previously existed in the repository.  See Substitution modes, 
  5245.            for a list of valid '-k' settings. 
  5246.  
  5247.  -I name 
  5248.            Specify file names that should be ignored during import.  You can 
  5249.            use this option repeatedly.  To avoid ignoring any files at all 
  5250.            (even those ignored by default), specify `-I !'. 
  5251.  
  5252.            name can be a file name pattern of the same type that you can 
  5253.            specify in the '.cvsignore' file. See cvsignore. 
  5254.  
  5255.  -W spec 
  5256.            Specify file names that should be filtered during import.  You can 
  5257.            use this option repeatedly. 
  5258.  
  5259.            spec can be a file name pattern of the same type that you can 
  5260.            specify in the '.cvswrappers' file. See Wrappers. 
  5261.  
  5262.  
  5263. ΓòÉΓòÉΓòÉ 17.12.2. import output ΓòÉΓòÉΓòÉ
  5264.  
  5265.  import keeps you informed of its progress by printing a line for each file, 
  5266.  preceded by one character indicating the status of the file: 
  5267.  
  5268.  U file 
  5269.            The file already exists in the repository and has not been locally 
  5270.            modified; a new revision has been created (if necessary). 
  5271.  
  5272.  N file 
  5273.            The file is a new file which has been added to the repository. 
  5274.  
  5275.  C file 
  5276.            The file already exists in the repository but has been locally 
  5277.            modified; you will have to merge the changes. 
  5278.  
  5279.  I file 
  5280.            The file is being ignored (see cvsignore). 
  5281.  
  5282.  L file 
  5283.            The file is a symbolic link; cvs import ignores symbolic links. 
  5284.            People periodically suggest that this behavior should be changed, 
  5285.            but if there is a consensus on what it should be changed to, it 
  5286.            doesn't seem to be apparent. (Various options in the 'modules' file 
  5287.            can be used to recreate symbolic links on checkout, update, etc.; 
  5288.            see modules.) 
  5289.  
  5290.  
  5291. ΓòÉΓòÉΓòÉ 17.12.3. import examples ΓòÉΓòÉΓòÉ
  5292.  
  5293.  See Tracking sources, and From files. 
  5294.  
  5295.  
  5296. ΓòÉΓòÉΓòÉ 17.13. log---Print out log information for files ΓòÉΓòÉΓòÉ
  5297.  
  5298.      Synopsis: log [options] [files┬╖┬╖┬╖] 
  5299.  
  5300.      Requires: repository, working directory. 
  5301.  
  5302.      Changes: nothing. 
  5303.  
  5304.  Display log information for files.  log used to call the RCS utility rlog. 
  5305.  Although this is no longer true in the current sources, this history 
  5306.  determines the format of the output and the options, which are not quite in 
  5307.  the style of the other CVS commands. 
  5308.  
  5309.  The output includes the location of the RCS file, the head revision (the 
  5310.  latest revision on the trunk), all symbolic names (tags) and some other 
  5311.  things.  For each revision, the revision number, the author, the number of 
  5312.  lines added/deleted and the log message are printed.  All times are displayed 
  5313.  in Coordinated Universal Time (UTC).  (Other parts of CVS print times in the 
  5314.  local timezone). Warning: log uses '-R' in a way that conflicts with the 
  5315.  normal use inside CVS (see Common options). 
  5316.  
  5317.  log options                   log options 
  5318.  log examples                  log examples 
  5319.  
  5320.  
  5321. ΓòÉΓòÉΓòÉ 17.13.1. log options ΓòÉΓòÉΓòÉ
  5322.  
  5323.  By default, log prints all information that is available.  All other options 
  5324.  restrict the output. 
  5325.  
  5326.  -b 
  5327.            Print information about the revisions on the default branch, 
  5328.            normally the highest branch on the trunk. 
  5329.  
  5330.  -d dates 
  5331.            Print information about revisions with a checkin date/time in the 
  5332.            range given by the semicolon-separated list of dates.  The date 
  5333.            formats accepted are those accepted by the '-D' option to many other 
  5334.            CVS commands (see Common options). Dates can be combined into ranges 
  5335.            as follows: 
  5336.  
  5337.              d1<d2 
  5338.  
  5339.              d2>d1 
  5340.                          Select the revisions that were deposited between d1 
  5341.                          and d2. 
  5342.  
  5343.              <d 
  5344.  
  5345.              d> 
  5346.                          Select all revisions dated d or earlier. 
  5347.  
  5348.              d< 
  5349.  
  5350.              >d 
  5351.                          Select all revisions dated d or later. 
  5352.  
  5353.              d 
  5354.                          Select the single, latest revision dated d or earlier. 
  5355.  
  5356.              The '>' or '<' characters may be followed by '=' to indicate an 
  5357.              inclusive range rather than an exclusive one. 
  5358.  
  5359.              Note that the separator is a semicolon (;). 
  5360.  
  5361.  -h 
  5362.            Print only the name of the RCS file, name of the file in the working 
  5363.            directory, head, default branch, access list, locks, symbolic names, 
  5364.            and suffix. 
  5365.  
  5366.  -l 
  5367.            Local; run only in current working directory.  (Default is to run 
  5368.            recursively). 
  5369.  
  5370.  -N 
  5371.            Do not print the list of tags for this file.  This option can be 
  5372.            very useful when your site uses a lot of tags, so rather than 
  5373.            "more"'ing over 3 pages of tag information, the log information is 
  5374.            presented without tags at all. 
  5375.  
  5376.  -R 
  5377.            Print only the name of the RCS file. 
  5378.  
  5379.  -rrevisions 
  5380.            Print information about revisions given in the comma-separated list 
  5381.            revisions of revisions and ranges.  The following table explains the 
  5382.            available range formats: 
  5383.  
  5384.              rev1:rev2 
  5385.                          Revisions rev1 to rev2 (which must be on the same 
  5386.                          branch). 
  5387.  
  5388.              :rev 
  5389.                          Revisions from the beginning of the branch up to and 
  5390.                          including rev. 
  5391.  
  5392.              rev: 
  5393.                          Revisions starting with rev to the end of the branch 
  5394.                          containing rev. 
  5395.  
  5396.              branch 
  5397.                          An argument that is a branch means all revisions on 
  5398.                          that branch. 
  5399.  
  5400.              branch1:branch2 
  5401.                          A range of branches means all revisions on the 
  5402.                          branches in that range. 
  5403.  
  5404.              branch. 
  5405.                          The latest revision in branch. 
  5406.  
  5407.              A bare '-r' with no revisions means the latest revision on the 
  5408.              default branch, normally the trunk. There can be no space between 
  5409.              the '-r' option and its argument. 
  5410.  
  5411.  -s states 
  5412.            Print information about revisions whose state attributes match one 
  5413.            of the states given in the comma-separated list states. 
  5414.  
  5415.  -t 
  5416.            Print the same as '-h', plus the descriptive text. 
  5417.  
  5418.  -wlogins 
  5419.            Print information about revisions checked in by users with login 
  5420.            names appearing in the comma-separated list logins.  If logins is 
  5421.            omitted, the user's login is assumed.  There can be no space between 
  5422.            the '-w' option and its argument. 
  5423.  
  5424.  log prints the intersection of the revisions selected with the options '-d', 
  5425.  '-s', and '-w', intersected with the union of the revisions selected by '-b' 
  5426.  and '-r'. 
  5427.  
  5428.  
  5429. ΓòÉΓòÉΓòÉ 17.13.2. log examples ΓòÉΓòÉΓòÉ
  5430.  
  5431.  Contributed examples are gratefully accepted. 
  5432.  
  5433.  
  5434. ΓòÉΓòÉΓòÉ 17.14. rdiff---'patch' format diffs between releases ΓòÉΓòÉΓòÉ
  5435.  
  5436.      rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules┬╖┬╖┬╖ 
  5437.  
  5438.      Requires: repository. 
  5439.  
  5440.      Changes: nothing. 
  5441.  
  5442.      Synonym: patch 
  5443.  
  5444.  Builds a Larry Wall format patch(1) file between two releases, that can be fed 
  5445.  directly into the patch program to bring an old release up-to-date with the 
  5446.  new release.  (This is one of the few CVS commands that operates directly from 
  5447.  the repository, and doesn't require a prior checkout.) The diff output is sent 
  5448.  to the standard output device. 
  5449.  
  5450.  You can specify (using the standard '-r' and '-D' options) any combination of 
  5451.  one or two revisions or dates.  If only one revision or date is specified, the 
  5452.  patch file reflects differences between that revision or date and the current 
  5453.  head revisions in the RCS file. 
  5454.  
  5455.  Note that if the software release affected is contained in more than one 
  5456.  directory, then it may be necessary to specify the '-p' option to the patch 
  5457.  command when patching the old sources, so that patch is able to find the files 
  5458.  that are located in other directories. 
  5459.  
  5460.  rdiff options                 rdiff options 
  5461.  rdiff examples                rdiff examples 
  5462.  
  5463.  
  5464. ΓòÉΓòÉΓòÉ 17.14.1. rdiff options ΓòÉΓòÉΓòÉ
  5465.  
  5466.  These standard options are supported by rdiff (see Common options, for a 
  5467.  complete description of them): 
  5468.  
  5469.  -D date 
  5470.            Use the most recent revision no later than date. 
  5471.  
  5472.  -f 
  5473.            If no matching revision is found, retrieve the most recent revision 
  5474.            (instead of ignoring the file). 
  5475.  
  5476.  -l 
  5477.            Local; don't descend subdirectories. 
  5478.  
  5479.  -R 
  5480.            Examine directories recursively.  This option is on by default. 
  5481.  
  5482.  -r tag 
  5483.            Use revision tag. 
  5484.  
  5485.  In addition to the above, these options are available: 
  5486.  
  5487.  -c 
  5488.            Use the context diff format.  This is the default format. 
  5489.  
  5490.  -s 
  5491.            Create a summary change report instead of a patch.  The summary 
  5492.            includes information about files that were changed or added between 
  5493.            the releases.  It is sent to the standard output device.  This is 
  5494.            useful for finding out, for example, which files have changed 
  5495.            between two dates or revisions. 
  5496.  
  5497.  -t 
  5498.            A diff of the top two revisions is sent to the standard output 
  5499.            device.  This is most useful for seeing what the last change to a 
  5500.            file was. 
  5501.  
  5502.  -u 
  5503.            Use the unidiff format for the context diffs. This option is not 
  5504.            available if your diff does not support the unidiff format. 
  5505.            Remember that old versions of the patch program can't handle the 
  5506.            unidiff format, so if you plan to post this patch to the net you 
  5507.            should probably not use '-u'. 
  5508.  
  5509.  -V vn 
  5510.            Expand keywords according to the rules current in RCS version vn 
  5511.            (the expansion format changed with RCS version 5).  Note that this 
  5512.            option is no longer accepted.  CVS will always expand keywords the 
  5513.            way that RCS version 5 does. 
  5514.  
  5515.  
  5516. ΓòÉΓòÉΓòÉ 17.14.2. rdiff examples ΓòÉΓòÉΓòÉ
  5517.  
  5518.  Suppose you receive mail from foo@bar.com asking for an update from release 
  5519.  1.2 to 1.4 of the tc compiler.  You have no such patches on hand, but with CVS 
  5520.  that can easily be fixed with a command such as this: 
  5521.  
  5522.                       $ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
  5523.                       $$ Mail -s 'The patches you asked for' foo@bar.com
  5524.  
  5525.  Suppose you have made release 1.3, and forked a branch called 'R_1_3fix' for 
  5526.  bugfixes.  'R_1_3_1' corresponds to release 1.3.1, which was made some time 
  5527.  ago.  Now, you want to see how much development has been done on the branch. 
  5528.  This command can be used: 
  5529.  
  5530.                       $ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
  5531.                       cvs rdiff: Diffing module-name
  5532.                       File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
  5533.                       File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
  5534.                       File bar.h,v changed from revision 1.29.2.1 to 1.2
  5535.  
  5536.  
  5537. ΓòÉΓòÉΓòÉ 17.15. release---Indicate that a Module is no longer in use ΓòÉΓòÉΓòÉ
  5538.  
  5539.      release [-d] directories┬╖┬╖┬╖ 
  5540.  
  5541.      Requires: Working directory. 
  5542.  
  5543.      Changes: Working directory, history log. 
  5544.  
  5545.  This command is meant to safely cancel the effect of 'cvs checkout'.  Since 
  5546.  CVS doesn't lock files, it isn't strictly necessary to use this command.  You 
  5547.  can always simply delete your working directory, if you like; but you risk 
  5548.  losing changes you may have forgotten, and you leave no trace in the CVS 
  5549.  history file (see history file) that you've abandoned your checkout. 
  5550.  
  5551.  Use 'cvs release' to avoid these problems.  This command checks that no 
  5552.  uncommitted changes are present; that you are executing it from immediately 
  5553.  above a CVS working directory; and that the repository recorded for your files 
  5554.  is the same as the repository defined in the module database. 
  5555.  
  5556.  If all these conditions are true, 'cvs release' leaves a record of its 
  5557.  execution (attesting to your intentionally abandoning your checkout) in the 
  5558.  CVS history log. 
  5559.  
  5560.  release options               release options 
  5561.  release output                release output 
  5562.  release examples              release examples 
  5563.  
  5564.  
  5565. ΓòÉΓòÉΓòÉ 17.15.1. release options ΓòÉΓòÉΓòÉ
  5566.  
  5567.  The release command supports one command option: 
  5568.  
  5569.  -d 
  5570.            Delete your working copy of the file if the release succeeds.  If 
  5571.            this flag is not given your files will remain in your working 
  5572.            directory. 
  5573.  
  5574.            Warning:  The release command deletes all directories and files 
  5575.            recursively.  This has the very serious side-effect that any 
  5576.            directory that you have created inside your checked-out sources, and 
  5577.            not added to the repository (using the add command; see Adding 
  5578.            files) will be silently deleted---even if it is non-empty! 
  5579.  
  5580.  
  5581. ΓòÉΓòÉΓòÉ 17.15.2. release output ΓòÉΓòÉΓòÉ
  5582.  
  5583.  Before release releases your sources it will print a one-line message for any 
  5584.  file that is not up-to-date. 
  5585.  
  5586.  Warning:  Any new directories that you have created, but not added to the CVS 
  5587.  directory hierarchy with the add command (see Adding files) will be silently 
  5588.  ignored (and deleted, if '-d' is specified), even if they contain files. 
  5589.  
  5590.  U file 
  5591.  
  5592.  P file 
  5593.            There exists a newer revision of this file in the repository, and 
  5594.            you have not modified your local copy of the file ('U' and 'P' mean 
  5595.            the same thing). 
  5596.  
  5597.  A file 
  5598.            The file has been added to your private copy of the sources, but has 
  5599.            not yet been committed to the repository.  If you delete your copy 
  5600.            of the sources this file will be lost. 
  5601.  
  5602.  R file 
  5603.            The file has been removed from your private copy of the sources, but 
  5604.            has not yet been removed from the repository, since you have not yet 
  5605.            committed the removal.  See commit. 
  5606.  
  5607.  M file 
  5608.            The file is modified in your working directory.  There might also be 
  5609.            a newer revision inside the repository. 
  5610.  
  5611.  ? file 
  5612.            file is in your working directory, but does not correspond to 
  5613.            anything in the source repository, and is not in the list of files 
  5614.            for CVS to ignore (see the description of the '-I' option, and see 
  5615.            cvsignore).  If you remove your working sources, this file will be 
  5616.            lost. 
  5617.  
  5618.  
  5619. ΓòÉΓòÉΓòÉ 17.15.3. release examples ΓòÉΓòÉΓòÉ
  5620.  
  5621.  Release the module, and delete your local working copy of the files. 
  5622.  
  5623.                       $ cd ┬╖┬╖     # You must stand immediately above the
  5624.                               # sources when you issue 'cvs release'.
  5625.                       $ cvs release -d tc
  5626.                       You have [0] altered files in this repository.
  5627.                       Are you sure you want to release (and delete) module `tc': y
  5628.                       $
  5629.  
  5630.  
  5631. ΓòÉΓòÉΓòÉ 17.16. rtag---Add a symbolic tag to a module ΓòÉΓòÉΓòÉ
  5632.  
  5633.      rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules┬╖┬╖┬╖ 
  5634.  
  5635.      Requires: repository. 
  5636.  
  5637.      Changes: repository. 
  5638.  
  5639.      Synonym: rfreeze 
  5640.  
  5641.  You can use this command to assign symbolic tags to particular, explicitly 
  5642.  specified source revisions in the repository.  rtag works directly on the 
  5643.  repository contents (and requires no prior checkout). Use tag instead (see 
  5644.  tag), to base the selection of revisions on the contents of your working 
  5645.  directory. 
  5646.  
  5647.  If you attempt to use a tag name that already exists, CVS will complain and 
  5648.  not overwrite that tag.  Use the '-F' option to force the new tag value. 
  5649.  
  5650.  rtag options                  rtag options 
  5651.  
  5652.  
  5653. ΓòÉΓòÉΓòÉ 17.16.1. rtag options ΓòÉΓòÉΓòÉ
  5654.  
  5655.  These standard options are supported by rtag (see Common options, for a 
  5656.  complete description of them): 
  5657.  
  5658.  -D date 
  5659.            Tag the most recent revision no later than date. 
  5660.  
  5661.  -f 
  5662.            Only useful with the '-D date' or '-r tag' flags.  If no matching 
  5663.            revision is found, use the most recent revision (instead of ignoring 
  5664.            the file). 
  5665.  
  5666.  -F 
  5667.            Overwrite an existing tag of the same name on a different revision. 
  5668.  
  5669.  -l 
  5670.            Local; run only in current working directory. 
  5671.  
  5672.  -n 
  5673.            Do not run any tag program that was specified with the '-t' flag 
  5674.            inside the 'modules' file. (see modules). 
  5675.  
  5676.  -R 
  5677.            Tag directories recursively.  This is on by default. 
  5678.  
  5679.  -r tag 
  5680.            Only tag those files that contain tag.  This can be used to rename a 
  5681.            tag: tag only the files identified by the old tag, then delete the 
  5682.            old tag, leaving the new tag on exactly the same files as the old 
  5683.            tag. 
  5684.  
  5685.  In addition to the above common options, these options are available: 
  5686.  
  5687.  -a 
  5688.            Use the '-a' option to have rtag look in the 'Attic' (see Attic) for 
  5689.            removed files that contain the specified tag.  The tag is removed 
  5690.            from these files, which makes it convenient to re-use a symbolic tag 
  5691.            as development continues (and files get removed from the up-coming 
  5692.            distribution). 
  5693.  
  5694.  -b 
  5695.            Make the tag a branch tag.  See Branching and merging. 
  5696.  
  5697.  -d 
  5698.            Delete the tag instead of creating it. 
  5699.  
  5700.            In general, tags (often the symbolic names of software 
  5701.            distributions) should not be removed, but the '-d' option is 
  5702.            available as a means to remove completely obsolete symbolic names if 
  5703.            necessary (as might be the case for an Alpha release, or if you 
  5704.            mistagged a module). 
  5705.  
  5706.  
  5707. ΓòÉΓòÉΓòÉ 17.17. tag---Add a symbolic tag to checked out versions of files ΓòÉΓòÉΓòÉ
  5708.  
  5709.      tag [-lR] [-b] [-c] [-d] symbolic_tag [files┬╖┬╖┬╖] 
  5710.  
  5711.      Requires: working directory, repository. 
  5712.  
  5713.      Changes: repository. 
  5714.  
  5715.      Synonym: freeze 
  5716.  
  5717.  Use this command to assign symbolic tags to the nearest repository versions to 
  5718.  your working sources.  The tags are applied immediately to the repository, as 
  5719.  with rtag, but the versions are supplied implicitly by the CVS records of your 
  5720.  working files' history rather than applied explicitly. 
  5721.  
  5722.  One use for tags is to record a snapshot of the current sources when the 
  5723.  software freeze date of a project arrives.  As bugs are fixed after the freeze 
  5724.  date, only those changed sources that are to be part of the release need be 
  5725.  re-tagged. 
  5726.  
  5727.  The symbolic tags are meant to permanently record which revisions of which 
  5728.  files were used in creating a software distribution.  The checkout and update 
  5729.  commands allow you to extract an exact copy of a tagged release at any time in 
  5730.  the future, regardless of whether files have been changed, added, or removed 
  5731.  since the release was tagged. 
  5732.  
  5733.  This command can also be used to delete a symbolic tag, or to create a branch. 
  5734.  See the options section below. 
  5735.  
  5736.  If you attempt to use a tag name that already exists, CVS will complain and 
  5737.  not overwrite that tag.  Use the '-F' option to force the new tag value. 
  5738.  
  5739.  tag options                   tag options 
  5740.  
  5741.  
  5742. ΓòÉΓòÉΓòÉ 17.17.1. tag options ΓòÉΓòÉΓòÉ
  5743.  
  5744.  These standard options are supported by tag (see Common options, for a 
  5745.  complete description of them): 
  5746.  
  5747.  -F 
  5748.            Overwrite an existing tag of the same name on a different revision. 
  5749.  
  5750.  -l 
  5751.            Local; run only in current working directory. 
  5752.  
  5753.  -R 
  5754.            Tag directories recursively.  This is on by default. 
  5755.  
  5756.  Two special options are available: 
  5757.  
  5758.  -b 
  5759.            Make the tag a branch tag (see Branching and merging), allowing 
  5760.            concurrent, isolated development.  This is most useful for creating 
  5761.            a patch to a previously released software distribution. 
  5762.  
  5763.  -c 
  5764.            Check that all files which are to be tagged are unmodified.  This 
  5765.            can be used to make sure that you can reconstruct the current file 
  5766.            contents. 
  5767.  
  5768.  -d 
  5769.            Delete a tag. 
  5770.  
  5771.            If you use 'cvs tag -d symbolic_tag', the symbolic tag you specify 
  5772.            is deleted instead of being added. Warning: Be very certain of your 
  5773.            ground before you delete a tag; doing this permanently discards some 
  5774.            historical information, which may later turn out to be valuable. 
  5775.  
  5776.  
  5777. ΓòÉΓòÉΓòÉ 17.18. update---Bring work tree in sync with repository ΓòÉΓòÉΓòÉ
  5778.  
  5779.      update [-AdflPpR] [-d] [-r tag|-D date] files┬╖┬╖┬╖ 
  5780.  
  5781.      Requires: repository, working directory. 
  5782.  
  5783.      Changes: working directory. 
  5784.  
  5785.  After you've run checkout to create your private copy of source from the 
  5786.  common repository, other developers will continue changing the central source. 
  5787.  From time to time, when it is convenient in your development process, you can 
  5788.  use the update command from within your working directory to reconcile your 
  5789.  work with any revisions applied to the source repository since your last 
  5790.  checkout or update. 
  5791.  
  5792.  update options                update options 
  5793.  update output                 update output 
  5794.  
  5795.  
  5796. ΓòÉΓòÉΓòÉ 17.18.1. update options ΓòÉΓòÉΓòÉ
  5797.  
  5798.  These standard options are available with update (see Common options, for a 
  5799.  complete description of them): 
  5800.  
  5801.  -D date 
  5802.            Use the most recent revision no later than date. This option is 
  5803.            sticky, and implies '-P'. See Sticky tags, for more information on 
  5804.            sticky tags/dates. 
  5805.  
  5806.  -f 
  5807.            Only useful with the '-D date' or '-r tag' flags.  If no matching 
  5808.            revision is found, retrieve the most recent revision (instead of 
  5809.            ignoring the file). 
  5810.  
  5811.  -k kflag 
  5812.            Process keywords according to kflag.  See Keyword substitution. This 
  5813.            option is sticky; future updates of this file in this working 
  5814.            directory will use the same kflag.  The status command can be viewed 
  5815.            to see the sticky options.  See Invoking CVS, for more information 
  5816.            on the status command. 
  5817.  
  5818.  -l 
  5819.            Local; run only in current working directory.  See Recursive 
  5820.            behavior. 
  5821.  
  5822.  -P 
  5823.            Prune empty directories.  See Moving directories. 
  5824.  
  5825.  -p 
  5826.            Pipe files to the standard output. 
  5827.  
  5828.  -R 
  5829.            Update directories recursively (default).  See Recursive behavior. 
  5830.  
  5831.  -r rev 
  5832.            Retrieve revision/tag rev.  This option is sticky, and implies '-P'. 
  5833.            See Sticky tags, for more information on sticky tags/dates. 
  5834.  
  5835.  These special options are also available with update. 
  5836.  
  5837.  -A 
  5838.            Reset any sticky tags, dates, or '-k' options. See Sticky tags, for 
  5839.            more information on sticky tags/dates. 
  5840.  
  5841.  -d 
  5842.            Create any directories that exist in the repository if they're 
  5843.            missing from the working directory.  Normally, update acts only on 
  5844.            directories and files that were already enrolled in your working 
  5845.            directory. 
  5846.  
  5847.            This is useful for updating directories that were created in the 
  5848.            repository since the initial checkout; but it has an unfortunate 
  5849.            side effect.  If you deliberately avoided certain directories in the 
  5850.            repository when you created your working directory (either through 
  5851.            use of a module name or by listing explicitly the files and 
  5852.            directories you wanted on the command line), then updating with '-d' 
  5853.            will create those directories, which may not be what you want. 
  5854.  
  5855.  -I name 
  5856.            Ignore files whose names match name (in your working directory) 
  5857.            during the update.  You can specify '-I' more than once on the 
  5858.            command line to specify several files to ignore.  Use '-I !' to 
  5859.            avoid ignoring any files at all.  See cvsignore, for other ways to 
  5860.            make CVS ignore some files. 
  5861.  
  5862.  -Wspec 
  5863.            Specify file names that should be filtered during update.  You can 
  5864.            use this option repeatedly. 
  5865.  
  5866.            spec can be a file name pattern of the same type that you can 
  5867.            specify in the '.cvswrappers' file. See Wrappers. 
  5868.  
  5869.  -jrevision 
  5870.            With two '-j' options, merge changes from the revision specified 
  5871.            with the first '-j' option to the revision specified with the second 
  5872.            'j' option, into the working directory. 
  5873.  
  5874.            With one '-j' option, merge changes from the ancestor revision to 
  5875.            the revision specified with the '-j' option, into the working 
  5876.            directory.  The ancestor revision is the common ancestor of the 
  5877.            revision which the working directory is based on, and the revision 
  5878.            specified in the '-j' option. 
  5879.  
  5880.            In addition, each '-j' option can contain an optional date 
  5881.            specification which, when used with branches, can limit the chosen 
  5882.            revision to one within a specific date.  An optional date is 
  5883.            specified by adding a colon (:) to the tag: 
  5884.            '-jSymbolic_Tag:Date_Specifier'. 
  5885.  
  5886.            See Branching and merging. 
  5887.  
  5888.  
  5889. ΓòÉΓòÉΓòÉ 17.18.2. update output ΓòÉΓòÉΓòÉ
  5890.  
  5891.  update and checkout keep you informed of their progress by printing a line for 
  5892.  each file, preceded by one character indicating the status of the file: 
  5893.  
  5894.  U file 
  5895.            The file was brought up to date with respect to the repository. 
  5896.            This is done for any file that exists in the repository but not in 
  5897.            your source, and for files that you haven't changed but are not the 
  5898.            most recent versions available in the repository. 
  5899.  
  5900.  P file 
  5901.            Like 'U', but the CVS server sends a patch instead of an entire 
  5902.            file.  These two things accomplish the same thing. 
  5903.  
  5904.  A file 
  5905.            The file has been added to your private copy of the sources, and 
  5906.            will be added to the source repository when you run commit on the 
  5907.            file.  This is a reminder to you that the file needs to be 
  5908.            committed. 
  5909.  
  5910.  R file 
  5911.            The file has been removed from your private copy of the sources, and 
  5912.            will be removed from the source repository when you run commit on 
  5913.            the file.  This is a reminder to you that the file needs to be 
  5914.            committed. 
  5915.  
  5916.  M file 
  5917.            The file is modified in  your  working  directory. 
  5918.  
  5919.            'M' can indicate one of two states for a file you're working on: 
  5920.            either there were no modifications to the same file in the 
  5921.            repository, so that your file remains as you last saw it; or there 
  5922.            were modifications in the repository as well as in your copy, but 
  5923.            they were merged successfully, without conflict, in your working 
  5924.            directory. 
  5925.  
  5926.            CVS will print some messages if it merges your work, and a backup 
  5927.            copy of your working file (as it looked before you ran update) will 
  5928.            be made.  The exact name of that file is printed while update runs. 
  5929.  
  5930.  C file 
  5931.            A conflict was detected while trying to merge your changes to file 
  5932.            with changes from the source repository.  file (the copy in your 
  5933.            working directory) is now the result of attempting to merge the two 
  5934.            revisions; an unmodified copy of your file is also in your working 
  5935.            directory, with the name '.#file.revision' where revision is the 
  5936.            revision that your modified file started from.  Resolve the conflict 
  5937.            as described in Conflicts example. (Note that some systems 
  5938.            automatically purge files that begin with '.#' if they have not been 
  5939.            accessed for a few days.  If you intend to keep a copy of your 
  5940.            original file, it is a very good idea to rename it.)  Under VMS, the 
  5941.            file name starts with '__' rather than '.#'. 
  5942.  
  5943.  ? file 
  5944.            file is in your working directory, but does not correspond to 
  5945.            anything in the source repository, and is not in the list of files 
  5946.            for CVS to ignore (see the description of the '-I' option, and see 
  5947.            cvsignore). 
  5948.  
  5949.  
  5950. ΓòÉΓòÉΓòÉ 18. Quick reference to CVS commands ΓòÉΓòÉΓòÉ
  5951.  
  5952.  This appendix describes how to invoke CVS, with references to where each 
  5953.  command or feature is described in detail.  For other references run the cvs 
  5954.  --help command, or see Index. 
  5955.  
  5956.  A CVS command looks like: 
  5957.  
  5958.                       cvs [ global_options ] command [ command_options ] [ command_args ]
  5959.  
  5960.  Global options: 
  5961.  
  5962.  --allow-root=rootdir 
  5963.            Specify legal CVSROOT directory (server only) (not in CVS 1.9 and 
  5964.            older).  See Password authentication server. 
  5965.  
  5966.  -a 
  5967.            Authenticate all communication (client only) (not in CVS 1.9 and 
  5968.            older).  See Global options. 
  5969.  
  5970.  -b 
  5971.            Specify RCS location (CVS 1.9 and older).  See Global options. 
  5972.  
  5973.  -d root 
  5974.            Specify the CVSROOT.  See Repository. 
  5975.  
  5976.  -e editor 
  5977.            Edit messages with editor.  See Committing your changes. 
  5978.  
  5979.  -f 
  5980.            Do not read the '~/.cvsrc' file.  See Global options. 
  5981.  
  5982.  -H 
  5983.  
  5984.  --help 
  5985.            Print a help message.  See Global options. 
  5986.  
  5987.  -l 
  5988.            Do not log in CVSROOT/history file.  See Global options. 
  5989.  
  5990.  -n 
  5991.            Do not change any files.  See Global options. 
  5992.  
  5993.  -Q 
  5994.            Be really quiet.  See Global options. 
  5995.  
  5996.  -q 
  5997.            Be somewhat quiet.  See Global options. 
  5998.  
  5999.  -r 
  6000.            Make new working files read-only.  See Global options. 
  6001.  
  6002.  -s variable=value 
  6003.            Set a user variable.  See Variables. 
  6004.  
  6005.  -T tempdir 
  6006.            Put temporary files in tempdir.  See Global options. 
  6007.  
  6008.  -t 
  6009.            Trace CVS execution.  See Global options. 
  6010.  
  6011.  -v 
  6012.  
  6013.  --version 
  6014.            Display version and copyright information for CVS. 
  6015.  
  6016.  -w 
  6017.            Make new working files read-write.  See Global options. 
  6018.  
  6019.  -x 
  6020.            Encrypt all communication (client only).  See Global options. 
  6021.  
  6022.  -z gzip-level 
  6023.            Set the compression level (client only). 
  6024.  
  6025.  Keyword expansion modes (see Substitution modes): 
  6026.  
  6027.                       -kkv  ${}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
  6028.                       -kkvl ${}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
  6029.                       -kk  ${}Id$
  6030.                       -kv  file1,v 1.1 1993/12/09 03:21:13 joe Exp
  6031.                       -ko  no expansion
  6032.                       -kb  no expansion, file is binary
  6033.  
  6034.  Keywords (see Keyword list): 
  6035.  
  6036.                       ${}Author: joe $
  6037.                       ${}Date: 1993/12/09 03:21:13 $
  6038.                       ${}Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
  6039.                       ${}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
  6040.                       ${}Locker: harry $
  6041.                       ${}Name: snapshot_1_14 $
  6042.                       ${}RCSfile: file1,v $
  6043.                       ${}Revision: 1.1 $
  6044.                       ${}Source: /home/files/file1,v $
  6045.                       ${}State: Exp $
  6046.                       ${}Log: file1,v $
  6047.                       Revision 1.1  1993/12/09 03:30:17  joe
  6048.                       Initial revision
  6049.  
  6050.  Commands, command options, and command arguments: 
  6051.  
  6052.  add [options] [files┬╖┬╖┬╖] 
  6053.            Add a new file/directory.  See Adding files. 
  6054.  
  6055.              -k kflag 
  6056.                          Set keyword expansion. 
  6057.  
  6058.              -m msg 
  6059.                          Set file description. 
  6060.  
  6061.  admin [options] [files┬╖┬╖┬╖] 
  6062.            Administration of history files in the repository.  See admin. 
  6063.  
  6064.              -b[rev] 
  6065.                          Set default branch.  See Reverting local changes. 
  6066.  
  6067.              -cstring 
  6068.                          Set comment leader. 
  6069.  
  6070.              -ksubst 
  6071.                          Set keyword substitution.  See Keyword substitution. 
  6072.  
  6073.              -l[rev] 
  6074.                          Lock revision rev, or latest revision. 
  6075.  
  6076.              -mrev:msg 
  6077.                          Replace the log message of revision rev with msg. 
  6078.  
  6079.              -orange 
  6080.                          Delete revisions from the repository.  See admin 
  6081.                          options. 
  6082.  
  6083.              -q 
  6084.                          Run quietly; do not print diagnostics. 
  6085.  
  6086.              -sstate[:rev] 
  6087.                          Set the state. 
  6088.  
  6089.              -t 
  6090.                          Set file description from standard input. 
  6091.  
  6092.              -tfile 
  6093.                          Set file description from file. 
  6094.  
  6095.              -t-string 
  6096.                          Set file description to string. 
  6097.  
  6098.              -u[rev] 
  6099.                          Unlock revision rev, or latest revision. 
  6100.  
  6101.  annotate [options] [files┬╖┬╖┬╖] 
  6102.            Show last revision where each line was modified.  See annotate. 
  6103.  
  6104.              -D date 
  6105.                          Annotate the most recent revision no later than date. 
  6106.                          See Common options. 
  6107.  
  6108.              -f 
  6109.                          Use head revision if tag/date not found.  See Common 
  6110.                          options. 
  6111.  
  6112.              -l 
  6113.                          Local; run only in current working directory.  See 
  6114.                          Recursive behavior. 
  6115.  
  6116.              -R 
  6117.                          Operate recursively (default).  See Recursive 
  6118.                          behavior. 
  6119.  
  6120.              -r tag 
  6121.                          Annotate revision tag.  See Common options. 
  6122.  
  6123.  checkout [options] modules┬╖┬╖┬╖ 
  6124.            Get a copy of the sources.  See checkout. 
  6125.  
  6126.              -A 
  6127.                          Reset any sticky tags/date/options.  See Sticky tags 
  6128.                          and Keyword substitution. 
  6129.  
  6130.              -c 
  6131.                          Output the module database.  See checkout options. 
  6132.  
  6133.              -D date 
  6134.                          Check out revisions as of date (is sticky).  See 
  6135.                          Common options. 
  6136.  
  6137.              -d dir 
  6138.                          Check out into dir.  See checkout options. 
  6139.  
  6140.              -f 
  6141.                          Use head revision if tag/date not found.  See Common 
  6142.                          options. 
  6143.  
  6144.              -j rev 
  6145.                          Merge in changes.  See checkout options. 
  6146.  
  6147.              -k kflag 
  6148.                          Use kflag keyword expansion.  See Substitution modes. 
  6149.  
  6150.              -l 
  6151.                          Local; run only in current working directory.  See 
  6152.                          Recursive behavior. 
  6153.  
  6154.              -N 
  6155.                          Don't ``shorten'' module paths if -d specified.  See 
  6156.                          checkout options. 
  6157.  
  6158.              -n 
  6159.                          Do not run module program (if any).  See checkout 
  6160.                          options. 
  6161.  
  6162.              -P 
  6163.                          Prune empty directories.  See Moving directories. 
  6164.  
  6165.              -p 
  6166.                          Check out files to standard output (avoids 
  6167.                          stickiness).  See checkout options. 
  6168.  
  6169.              -R 
  6170.                          Operate recursively (default).  See Recursive 
  6171.                          behavior. 
  6172.  
  6173.              -r tag 
  6174.                          Checkout revision tag (is sticky).  See Common 
  6175.                          options. 
  6176.  
  6177.              -s 
  6178.                          Like -c, but include module status.  See checkout 
  6179.                          options. 
  6180.  
  6181.  commit [options] [files┬╖┬╖┬╖] 
  6182.            Check changes into the repository.  See commit. 
  6183.  
  6184.              -F file 
  6185.                          Read log message from file.  See commit options. 
  6186.  
  6187.              -f 
  6188.                          Force the file to be committed; disables recursion. 
  6189.                          See commit options. 
  6190.  
  6191.              -l 
  6192.                          Local; run only in current working directory.  See 
  6193.                          Recursive behavior. 
  6194.  
  6195.              -m msg 
  6196.                          Use msg as log message.  See commit options. 
  6197.  
  6198.              -n 
  6199.                          Do not run module program (if any).  See commit 
  6200.                          options. 
  6201.  
  6202.              -R 
  6203.                          Operate recursively (default).  See Recursive 
  6204.                          behavior. 
  6205.  
  6206.              -r rev 
  6207.                          Commit to rev.  See commit options. 
  6208.  
  6209.  diff [options] [files┬╖┬╖┬╖] 
  6210.            Show differences between revisions.  See diff. In addition to the 
  6211.            options shown below, accepts a wide variety of options to control 
  6212.            output style, for example '-c' for context diffs. 
  6213.  
  6214.              -D date1 
  6215.                          Diff revision for date against working file.  See diff 
  6216.                          options. 
  6217.  
  6218.              -D date2 
  6219.                          Diff rev1/date1 against date2.  See diff options. 
  6220.  
  6221.              -l 
  6222.                          Local; run only in current working directory.  See 
  6223.                          Recursive behavior. 
  6224.  
  6225.              -N 
  6226.                          Include diffs for added and removed files.  See diff 
  6227.                          options. 
  6228.  
  6229.              -R 
  6230.                          Operate recursively (default).  See Recursive 
  6231.                          behavior. 
  6232.  
  6233.              -r rev1 
  6234.                          Diff revision for rev1 against working file.  See diff 
  6235.                          options. 
  6236.  
  6237.              -r rev2 
  6238.                          Diff rev1/date1 against rev2.  See diff options. 
  6239.  
  6240.  edit [options] [files┬╖┬╖┬╖] 
  6241.            Get ready to edit a watched file.  See Editing files. 
  6242.  
  6243.              -a actions 
  6244.                          Specify actions for temporary watch, where actions is 
  6245.                          edit, unedit, commit, all, or none.  See Editing 
  6246.                          files. 
  6247.  
  6248.              -l 
  6249.                          Local; run only in current working directory.  See 
  6250.                          Recursive behavior. 
  6251.  
  6252.              -R 
  6253.                          Operate recursively (default).  See Recursive 
  6254.                          behavior. 
  6255.  
  6256.  editors [options] [files┬╖┬╖┬╖] 
  6257.            See who is editing a watched file.  See Watch information. 
  6258.  
  6259.              -l 
  6260.                          Local; run only in current working directory.  See 
  6261.                          Recursive behavior. 
  6262.  
  6263.              -R 
  6264.                          Operate recursively (default).  See Recursive 
  6265.                          behavior. 
  6266.  
  6267.  export [options] modules┬╖┬╖┬╖ 
  6268.            Export files from CVS.  See export. 
  6269.  
  6270.              -D date 
  6271.                          Check out revisions as of date.  See Common options. 
  6272.  
  6273.              -d dir 
  6274.                          Check out into dir.  See export options. 
  6275.  
  6276.              -f 
  6277.                          Use head revision if tag/date not found.  See Common 
  6278.                          options. 
  6279.  
  6280.              -k kflag 
  6281.                          Use kflag keyword expansion.  See Substitution modes. 
  6282.  
  6283.              -l 
  6284.                          Local; run only in current working directory.  See 
  6285.                          Recursive behavior. 
  6286.  
  6287.              -N 
  6288.                          Don't ``shorten'' module paths if -d specified.  See 
  6289.                          export options. 
  6290.  
  6291.              -n 
  6292.                          Do not run module program (if any).  See export 
  6293.                          options. 
  6294.  
  6295.              -P 
  6296.                          Prune empty directories.  See Moving directories. 
  6297.  
  6298.              -R 
  6299.                          Operate recursively (default).  See Recursive 
  6300.                          behavior. 
  6301.  
  6302.              -r tag 
  6303.                          Checkout revision tag (is sticky).  See Common 
  6304.                          options. 
  6305.  
  6306.  history [options] [files┬╖┬╖┬╖] 
  6307.            Show repository access history.  See history. 
  6308.  
  6309.              -a 
  6310.                          All users (default is self).  See history options. 
  6311.  
  6312.              -b str 
  6313.                          Back to record with str in module/file/repos field. 
  6314.                          See history options. 
  6315.  
  6316.              -c 
  6317.                          Report on committed (modified) files.  See history 
  6318.                          options. 
  6319.  
  6320.              -D date 
  6321.                          Since date.  See history options. 
  6322.  
  6323.              -e 
  6324.                          Report on all record types.  See history options. 
  6325.  
  6326.              -l 
  6327.                          Last modified (committed or modified report).  See 
  6328.                          history options. 
  6329.  
  6330.              -m module 
  6331.                          Report on module (repeatable).  See history options. 
  6332.  
  6333.              -n module 
  6334.                          In module.  See history options. 
  6335.  
  6336.              -o 
  6337.                          Report on checked out modules.  See history options. 
  6338.  
  6339.              -r rev 
  6340.                          Since revision rev.  See history options. 
  6341.  
  6342.              -T 
  6343.                          Produce report on all TAGs.  See history options. 
  6344.  
  6345.              -t tag 
  6346.                          Since tag record placed in history file (by anyone). 
  6347.                          See history options. 
  6348.  
  6349.              -u user 
  6350.                          For user user (repeatable).  See history options. 
  6351.  
  6352.              -w 
  6353.                          Working directory must match.  See history options. 
  6354.  
  6355.              -x types 
  6356.                          Report on types, one or more of TOEFWUCGMAR.  See 
  6357.                          history options. 
  6358.  
  6359.              -z zone 
  6360.                          Output for time zone zone.  See history options. 
  6361.  
  6362.  import [options] repository vendor-tag release-tags┬╖┬╖┬╖ 
  6363.            Import files into CVS, using vendor branches.  See import. 
  6364.  
  6365.              -b bra 
  6366.                          Import to vendor branch bra.  See Multiple vendor 
  6367.                          branches. 
  6368.  
  6369.              -d 
  6370.                          Use the file's modification time as the time of 
  6371.                          import.  See import options. 
  6372.  
  6373.              -k kflag 
  6374.                          Set default keyword substitution mode.  See import 
  6375.                          options. 
  6376.  
  6377.              -m msg 
  6378.                          Use msg for log message.  See import options. 
  6379.  
  6380.              -I ign 
  6381.                          More files to ignore (! to reset).  See import 
  6382.                          options. 
  6383.  
  6384.              -W spec 
  6385.                          More wrappers.  See import options. 
  6386.  
  6387.  init 
  6388.            Create a CVS repository if it doesn't exist.  See Creating a 
  6389.            repository. 
  6390.  
  6391.  log [options] [files┬╖┬╖┬╖] 
  6392.            Print out history information for files.  See log. 
  6393.  
  6394.              -b 
  6395.                          Only list revisions on the default branch.  See log 
  6396.                          options. 
  6397.  
  6398.              -d dates 
  6399.                          Specify dates (d1<d2 for range, d for latest before). 
  6400.                          See log options. 
  6401.  
  6402.              -h 
  6403.                          Only print header.  See log options. 
  6404.  
  6405.              -l 
  6406.                          Local; run only in current working directory.  See 
  6407.                          Recursive behavior. 
  6408.  
  6409.              -N 
  6410.                          Do not list tags.  See log options. 
  6411.  
  6412.              -R 
  6413.                          Only print name of RCS file.  See log options. 
  6414.  
  6415.              -rrevs 
  6416.                          Only list revisions revs.  See log options. 
  6417.  
  6418.              -s states 
  6419.                          Only list revisions with specified states.  See log 
  6420.                          options. 
  6421.  
  6422.              -t 
  6423.                          Only print header and descriptive text.  See log 
  6424.                          options. 
  6425.  
  6426.              -wlogins 
  6427.                          Only list revisions checked in by specified logins. 
  6428.                          See log options. 
  6429.  
  6430.  login 
  6431.            Prompt for password for authenticating server.  See Password 
  6432.            authentication client. 
  6433.  
  6434.  logout 
  6435.            Remove stored password for authenticating server.  See Password 
  6436.            authentication client. 
  6437.  
  6438.  rdiff [options] modules┬╖┬╖┬╖ 
  6439.            Show differences between releases.  See rdiff. 
  6440.  
  6441.              -c 
  6442.                          Context diff output format (default).  See rdiff 
  6443.                          options. 
  6444.  
  6445.              -D date 
  6446.                          Select revisions based on date.  See Common options. 
  6447.  
  6448.              -f 
  6449.                          Use head revision if tag/date not found.  See Common 
  6450.                          options. 
  6451.  
  6452.              -l 
  6453.                          Local; run only in current working directory.  See 
  6454.                          Recursive behavior. 
  6455.  
  6456.              -R 
  6457.                          Operate recursively (default).  See Recursive 
  6458.                          behavior. 
  6459.  
  6460.              -r rev 
  6461.                          Select revisions based on rev.  See Common options. 
  6462.  
  6463.              -s 
  6464.                          Short patch - one liner per file.  See rdiff options. 
  6465.  
  6466.              -t 
  6467.                          Top two diffs - last change made to the file.  See 
  6468.                          diff options. 
  6469.  
  6470.              -u 
  6471.                          Unidiff output format.  See rdiff options. 
  6472.  
  6473.              -V vers 
  6474.                          Use RCS Version vers for keyword expansion (obsolete). 
  6475.                          See rdiff options. 
  6476.  
  6477.  release [options] directory 
  6478.            Indicate that a directory is no longer in use.  See release. 
  6479.  
  6480.              -d 
  6481.                          Delete the given directory.  See release options. 
  6482.  
  6483.  remove [options] [files┬╖┬╖┬╖] 
  6484.            Remove an entry from the repository.  See Removing files. 
  6485.  
  6486.              -f 
  6487.                          Delete the file before removing it.  See Removing 
  6488.                          files. 
  6489.  
  6490.              -l 
  6491.                          Local; run only in current working directory.  See 
  6492.                          Recursive behavior. 
  6493.  
  6494.              -R 
  6495.                          Operate recursively (default).  See Recursive 
  6496.                          behavior. 
  6497.  
  6498.  rtag [options] tag modules┬╖┬╖┬╖ 
  6499.            Add a symbolic tag to a module.  See rtag. 
  6500.  
  6501.              -a 
  6502.                          Clear tag from removed files that would not otherwise 
  6503.                          be tagged.  See rtag options. 
  6504.  
  6505.              -b 
  6506.                          Create a branch named tag.  See rtag options. 
  6507.  
  6508.              -D date 
  6509.                          Tag revisions as of date.  See rtag options. 
  6510.  
  6511.              -d 
  6512.                          Delete the given tag.  See rtag options. 
  6513.  
  6514.              -F 
  6515.                          Move tag if it already exists.  See rtag options. 
  6516.  
  6517.              -f 
  6518.                          Force a head revision match if tag/date not found. See 
  6519.                          rtag options. 
  6520.  
  6521.              -l 
  6522.                          Local; run only in current working directory.  See 
  6523.                          Recursive behavior. 
  6524.  
  6525.              -n 
  6526.                          No execution of tag program.  See rtag options. 
  6527.  
  6528.              -R 
  6529.                          Operate recursively (default).  See Recursive 
  6530.                          behavior. 
  6531.  
  6532.              -r tag 
  6533.                          Tag existing tag tag.  See rtag options. 
  6534.  
  6535.  status [options] files┬╖┬╖┬╖ 
  6536.            Display status information in a working directory.  See File status. 
  6537.  
  6538.              -l 
  6539.                          Local; run only in current working directory.  See 
  6540.                          Recursive behavior. 
  6541.  
  6542.              -R 
  6543.                          Operate recursively (default).  See Recursive 
  6544.                          behavior. 
  6545.  
  6546.              -v 
  6547.                          Include tag information for file.  See Tags. 
  6548.  
  6549.  tag [options] tag [files┬╖┬╖┬╖] 
  6550.            Add a symbolic tag to checked out version of files. See tag. 
  6551.  
  6552.              -b 
  6553.                          Create a branch named tag.  See tag options. 
  6554.  
  6555.              -D date 
  6556.                          Tag revisions as of date.  See tag options. 
  6557.  
  6558.              -d 
  6559.                          Delete the given tag.  See tag options. 
  6560.  
  6561.              -F 
  6562.                          Move tag if it already exists.  See tag options. 
  6563.  
  6564.              -f 
  6565.                          Force a head revision match if tag/date not found. See 
  6566.                          tag options. 
  6567.  
  6568.              -l 
  6569.                          Local; run only in current working directory.  See 
  6570.                          Recursive behavior. 
  6571.  
  6572.              -n 
  6573.                          No execution of tag program.  See tag options. 
  6574.  
  6575.              -R 
  6576.                          Operate recursively (default).  See Recursive 
  6577.                          behavior. 
  6578.  
  6579.              -r tag 
  6580.                          Tag existing tag tag.  See tag options. 
  6581.  
  6582.  unedit [options] [files┬╖┬╖┬╖] 
  6583.            Undo an edit command.  See Editing files. 
  6584.  
  6585.              -a actions 
  6586.                          Specify actions for temporary watch, where actions is 
  6587.                          edit, unedit, commit, all, or none.  See Editing 
  6588.                          files. 
  6589.  
  6590.              -l 
  6591.                          Local; run only in current working directory.  See 
  6592.                          Recursive behavior. 
  6593.  
  6594.              -R 
  6595.                          Operate recursively (default).  See Recursive 
  6596.                          behavior. 
  6597.  
  6598.  update [options] [files┬╖┬╖┬╖] 
  6599.            Bring work tree in sync with repository.  See update. 
  6600.  
  6601.              -A 
  6602.                          Reset any sticky tags/date/options.  See Sticky tags 
  6603.                          and Keyword substitution. 
  6604.  
  6605.              -D date 
  6606.                          Check out revisions as of date (is sticky).  See 
  6607.                          Common options. 
  6608.  
  6609.              -d 
  6610.                          Create directories.  See update options. 
  6611.  
  6612.              -f 
  6613.                          Use head revision if tag/date not found.  See Common 
  6614.                          options. 
  6615.  
  6616.              -I ign 
  6617.                          More files to ignore (! to reset).  See import 
  6618.                          options. 
  6619.  
  6620.              -j rev 
  6621.                          Merge in changes.  See update options. 
  6622.  
  6623.              -k kflag 
  6624.                          Use kflag keyword expansion.  See Substitution modes. 
  6625.  
  6626.              -l 
  6627.                          Local; run only in current working directory.  See 
  6628.                          Recursive behavior. 
  6629.  
  6630.              -P 
  6631.                          Prune empty directories.  See Moving directories. 
  6632.  
  6633.              -p 
  6634.                          Check out files to standard output (avoids 
  6635.                          stickiness).  See update options. 
  6636.  
  6637.              -R 
  6638.                          Operate recursively (default).  See Recursive 
  6639.                          behavior. 
  6640.  
  6641.              -r tag 
  6642.                          Checkout revision tag (is sticky).  See Common 
  6643.                          options. 
  6644.  
  6645.              -W spec 
  6646.                          More wrappers.  See import options. 
  6647.  
  6648.  watch [on|off|add|remove] [options] [files┬╖┬╖┬╖] 
  6649.            on/off: turn on/off read-only checkouts of files.  See Setting a 
  6650.            watch. 
  6651.  
  6652.            add/remove: add or remove notification on actions.  See Getting 
  6653.            Notified. 
  6654.  
  6655.              -a actions 
  6656.                          Specify actions for temporary watch, where actions is 
  6657.                          edit, unedit, commit, all, or none.  See Editing 
  6658.                          files. 
  6659.  
  6660.              -l 
  6661.                          Local; run only in current working directory.  See 
  6662.                          Recursive behavior. 
  6663.  
  6664.              -R 
  6665.                          Operate recursively (default).  See Recursive 
  6666.                          behavior. 
  6667.  
  6668.  watchers [options] [files┬╖┬╖┬╖] 
  6669.            See who is watching a file.  See Watch information. 
  6670.  
  6671.              -l 
  6672.                          Local; run only in current working directory.  See 
  6673.                          Recursive behavior. 
  6674.  
  6675.              -R 
  6676.                          Operate recursively (default).  See Recursive 
  6677.                          behavior. 
  6678.  
  6679.  
  6680. ΓòÉΓòÉΓòÉ 19. Reference manual for Administrative files ΓòÉΓòÉΓòÉ
  6681.  
  6682.  Inside the repository, in the directory '$CVSROOT/CVSROOT', there are a number 
  6683.  of supportive files for CVS.  You can use CVS in a limited fashion without any 
  6684.  of them, but if they are set up properly they can help make life easier.  For 
  6685.  a discussion of how to edit them, see Intro administrative files. 
  6686.  
  6687.  The most important of these files is the 'modules' file, which defines the 
  6688.  modules inside the repository. 
  6689.  
  6690.  modules                       Defining modules 
  6691.  Wrappers                      Treat directories as files 
  6692.  commit files                  The commit support files 
  6693.  commitinfo                    Pre-commit checking 
  6694.  verifymsg                     How are log messages evaluated? 
  6695.  editinfo                      Specifying how log messages are created 
  6696.                                (obsolete) 
  6697.  loginfo                       Where should log messages be sent? 
  6698.  rcsinfo                       Templates for the log messages 
  6699.  cvsignore                     Ignoring files via cvsignore 
  6700.  history file                  History information 
  6701.  Variables                     Various variables are expanded 
  6702.  config                        Miscellaneous CVS configuration 
  6703.  
  6704.  
  6705. ΓòÉΓòÉΓòÉ 19.1. The modules file ΓòÉΓòÉΓòÉ
  6706.  
  6707.  The 'modules' file records your definitions of names for collections of source 
  6708.  code.  CVS will use these definitions if you use CVS to update the modules 
  6709.  file (use normal commands like add, commit, etc). 
  6710.  
  6711.  The 'modules' file may contain blank lines and comments (lines beginning with 
  6712.  '#') as well as module definitions.  Long lines can be continued on the next 
  6713.  line by specifying a backslash ('\') as the last character on the line. 
  6714.  
  6715.  There are three basic types of modules: alias modules, regular modules, and 
  6716.  ampersand modules.  The difference between them is the way that they map files 
  6717.  in the repository to files in the working directory.  In all of the following 
  6718.  examples, the top-level repository contains a directory called 'first-dir', 
  6719.  which contains two files, 'file1' and 'file2', and a directory 'sdir'. 
  6720.  'first-dir/sdir' contains a file 'sfile'. 
  6721.  
  6722.  Alias modules                 The simplest kind of module 
  6723.  Regular modules               Regular modules 
  6724.  Ampersand modules             Ampersand modules 
  6725.  Excluding directories         Excluding directories from a module 
  6726.  Module options                Regular and ampersand modules can take options 
  6727.  
  6728.  
  6729. ΓòÉΓòÉΓòÉ 19.1.1. Alias modules ΓòÉΓòÉΓòÉ
  6730.  
  6731.  Alias modules are the simplest kind of module: 
  6732.  
  6733.  mname -a aliases┬╖┬╖┬╖ 
  6734.            This represents the simplest way of defining a module mname.  The 
  6735.            '-a' flags the definition as a simple alias: CVS will treat any use 
  6736.            of mname (as a command argument) as if the list of names aliases had 
  6737.            been specified instead. aliases may contain either other module 
  6738.            names or paths.  When you use paths in aliases, checkout creates all 
  6739.            intermediate directories in the working directory, just as if the 
  6740.            path had been specified explicitly in the CVS arguments. 
  6741.  
  6742.  For example, if the modules file contains: 
  6743.  
  6744.                       amodule -a first-dir
  6745.  
  6746.  then the following two commands are equivalent: 
  6747.  
  6748.                       $ cvs co amodule
  6749.                       $ cvs co first-dir
  6750.  
  6751.  and they each would provide output such as: 
  6752.  
  6753.                       cvs checkout: Updating first-dir
  6754.                       U first-dir/file1
  6755.                       U first-dir/file2
  6756.                       cvs checkout: Updating first-dir/sdir
  6757.                       U first-dir/sdir/sfile
  6758.  
  6759.  
  6760. ΓòÉΓòÉΓòÉ 19.1.2. Regular modules ΓòÉΓòÉΓòÉ
  6761.  
  6762.  mname [ options ] dir [ files┬╖┬╖┬╖ ] 
  6763.            In the simplest case, this form of module definition reduces to 
  6764.            'mname dir'.  This defines all the files in directory dir as module 
  6765.            mname. dir is a relative path (from $CVSROOT) to a directory of 
  6766.            source in the source repository.  In this case, on checkout, a 
  6767.            single directory called mname is created as a working directory; no 
  6768.            intermediate directory levels are used by default, even if dir was a 
  6769.            path involving several directory levels. 
  6770.  
  6771.  For example, if a module is defined by: 
  6772.  
  6773.                       regmodule first-dir
  6774.  
  6775.  then regmodule will contain the files from first-dir: 
  6776.  
  6777.                       $ cvs co regmodule
  6778.                       cvs checkout: Updating regmodule
  6779.                       U regmodule/file1
  6780.                       U regmodule/file2
  6781.                       cvs checkout: Updating regmodule/sdir
  6782.                       U regmodule/sdir/sfile
  6783.                       $
  6784.  
  6785.  By explicitly specifying files in the module definition after dir, you can 
  6786.  select particular files from directory dir.  Here is an example: 
  6787.  
  6788.                       regfiles first-dir/sdir sfile
  6789.  
  6790.  With this definition, getting the regfiles module will create a single working 
  6791.  directory 'regfiles' containing the file listed, which comes from a directory 
  6792.  deeper in the CVS source repository: 
  6793.  
  6794.                       $ cvs co regfiles
  6795.                       U regfiles/sfile
  6796.                       $
  6797.  
  6798.  
  6799. ΓòÉΓòÉΓòÉ 19.1.3. Ampersand modules ΓòÉΓòÉΓòÉ
  6800.  
  6801.  A module definition can refer to other modules by including '&module' in its 
  6802.  definition. 
  6803.  
  6804.                       mname [ options ] &module┬╖┬╖┬╖
  6805.  
  6806.  Then getting the module creates a subdirectory for each such module, in the 
  6807.  directory containing the module.  For example, if modules contains 
  6808.  
  6809.                       ampermod &first-dir
  6810.  
  6811.  then a checkout will create an ampermod directory which contains a directory 
  6812.  called first-dir, which in turns contains all the directories and files which 
  6813.  live there.  For example, the command 
  6814.  
  6815.                       $ cvs co ampermod
  6816.  
  6817.  will create the following files: 
  6818.  
  6819.                       ampermod/first-dir/file1
  6820.                       ampermod/first-dir/file2
  6821.                       ampermod/first-dir/sdir/sfile
  6822.  
  6823.  There is one quirk/bug: the messages that CVS prints omit the 'ampermod', and 
  6824.  thus do not correctly display the location to which it is checking out the 
  6825.  files: 
  6826.  
  6827.                       $ cvs co ampermod
  6828.                       cvs checkout: Updating first-dir
  6829.                       U first-dir/file1
  6830.                       U first-dir/file2
  6831.                       cvs checkout: Updating first-dir/sdir
  6832.                       U first-dir/sdir/sfile
  6833.                       $
  6834.  
  6835.  Do not rely on this buggy behavior; it may get fixed in a future release of 
  6836.  CVS. 
  6837.  
  6838.  
  6839. ΓòÉΓòÉΓòÉ 19.1.4. Excluding directories ΓòÉΓòÉΓòÉ
  6840.  
  6841.  An alias module may exclude particular directories from other modules by using 
  6842.  an exclamation mark ('!') before the name of each directory to be excluded. 
  6843.  
  6844.  For example, if the modules file contains: 
  6845.  
  6846.                       exmodule -a !first-dir/sdir first-dir
  6847.  
  6848.  then checking out the module 'exmodule' will check out everything in 
  6849.  'first-dir' except any files in the subdirectory 'first-dir/sdir'. 
  6850.  
  6851.  
  6852. ΓòÉΓòÉΓòÉ 19.1.5. Module options ΓòÉΓòÉΓòÉ
  6853.  
  6854.  Either regular modules or ampersand modules can contain options, which supply 
  6855.  additional information concerning the module. 
  6856.  
  6857.  -d name 
  6858.            Name the working directory something other than the module name. 
  6859.  
  6860.  -e prog 
  6861.            Specify a program prog to run whenever files in a module are 
  6862.            exported.  prog runs with a single argument, the module name. 
  6863.  
  6864.  -i prog 
  6865.            Specify a program prog to run whenever files in a module are 
  6866.            committed.  prog runs with a single argument, the full pathname of 
  6867.            the affected directory in a source repository.  The 'commitinfo', 
  6868.            'loginfo', and 'verifymsg' files provide other ways to call a 
  6869.            program on commit. 
  6870.  
  6871.  -o prog 
  6872.            Specify a program prog to run whenever files in a module are checked 
  6873.            out.  prog runs with a single argument, the module name. 
  6874.  
  6875.  -s status 
  6876.            Assign a status to the module.  When the module file is printed with 
  6877.            'cvs checkout -s' the modules are sorted according to primarily 
  6878.            module status, and secondarily according to the module name.  This 
  6879.            option has no other meaning.  You can use this option for several 
  6880.            things besides status: for instance, list the person that is 
  6881.            responsible for this module. 
  6882.  
  6883.  -t prog 
  6884.            Specify a program prog to run whenever files in a module are tagged 
  6885.            with rtag.  prog runs with two arguments: the module name and the 
  6886.            symbolic tag specified to rtag.  It is not run when tag is executed. 
  6887.            Generally you will find that taginfo is a better solution (see 
  6888.            user-defined logging). 
  6889.  
  6890.  -u prog 
  6891.            Specify a program prog to run whenever 'cvs update' is executed from 
  6892.            the top-level directory of the checked-out module.  prog runs with a 
  6893.            single argument, the full path to the source repository for this 
  6894.            module. 
  6895.  
  6896.  
  6897. ΓòÉΓòÉΓòÉ 19.2. The cvswrappers file ΓòÉΓòÉΓòÉ
  6898.  
  6899.  Wrappers allow you to set a hook which transforms files on their way in and 
  6900.  out of CVS. 
  6901.  
  6902.  The file 'cvswrappers' defines the script that will be run on a file when its 
  6903.  name matches a regular expresion. There are two scripts that can be run on a 
  6904.  file or directory. One script is executed on the file/directory before being 
  6905.  checked into the repository (this is denoted with the -t flag) and the other 
  6906.  when the file is checked out of the repository (this is denoted with the -f 
  6907.  flag).  The '-t'/'-f' feature does not work with client/server CVS. The 
  6908.  'cvswrappers' also has a '-m' option to specify the merge methodology that 
  6909.  should be used when a non-binary file is updated.  MERGE means the usual CVS 
  6910.  behavior: try to merge the files.  COPY means that cvs update will refuse to 
  6911.  merge files, as it also does for files specified as binary with '-kb' (but if 
  6912.  the file is specified as binary, there is no need to specify '-m 'COPY''). CVS 
  6913.  will provide the user with the two versions of the files, and require the user 
  6914.  using mechanisms outside CVS, to insert any necessary changes.  WARNING: do 
  6915.  not use COPY with CVS 1.9 or earlier--such versions of CVS will copy one 
  6916.  version of your file over the other, wiping out the previous contents. The 
  6917.  '-m' wrapper option only affects behavior when merging is done on update; it 
  6918.  does not affect how files are stored.  See Binary files, for more on binary 
  6919.  files. 
  6920.  
  6921.  The basic format of the file 'cvswrappers' is: 
  6922.  
  6923.                       wildcard   [option value][option value]┬╖┬╖┬╖
  6924.                       where option is one of
  6925.                       -f      from cvs filter     value: path to filter
  6926.                       -t      to cvs filter      value: path to filter
  6927.                       -m      update methodology    value: MERGE or COPY
  6928.                       -k      keyword expansion    value: expansion mode
  6929.                       and value is a single-quote delimited value.
  6930.  
  6931.                       *.nib   -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
  6932.                       *.c    -t 'indent %s %s'
  6933.  
  6934.  The above example of a 'cvswrappers' file states that all files/directories 
  6935.  that end with a .nib should be filtered with the 'wrap' program before 
  6936.  checking the file into the repository. The file should be filtered though the 
  6937.  'unwrap' program when the file is checked out of the repository. The 
  6938.  'cvswrappers' file also states that a COPY methodology should be used when 
  6939.  updating the files in the repository (that is, no merging should be 
  6940.  performed). 
  6941.  
  6942.  The last example line says that all files that end with .c should be filtered 
  6943.  with 'indent' before being checked into the repository. Unlike the previous 
  6944.  example, no filtering of the .c file is done when it is checked out of the 
  6945.  repository. 
  6946.  The -t filter is called with two arguments, the first is the name of the 
  6947.  file/directory to filter and the second is the pathname to where the resulting 
  6948.  filtered file should be placed. 
  6949.  The -f filter is called with one argument, which is the name of the file to 
  6950.  filter from. The end result of this filter will be a file in the users 
  6951.  directory that they can work on as they normally would. 
  6952.  
  6953.  Note that the '-t'/'-f' features do not conveniently handle one portion of 
  6954.  CVS's operation: determining when files are modified.  CVS will still want a 
  6955.  file (or directory) to exist, and it will use its modification time to 
  6956.  determine whether a file is modified.  If CVS erroneously thinks a file is 
  6957.  unmodified (for example, a directory is unchanged but one of the files within 
  6958.  it is changed), you can force it to check in the file anyway by specifying the 
  6959.  '-f' option to cvs commit (see commit options). For another example, the 
  6960.  following command imports a directory, treating files whose name ends in 
  6961.  '.exe' as binary: 
  6962.  
  6963.                       cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
  6964.  
  6965.  
  6966. ΓòÉΓòÉΓòÉ 19.3. The commit support files ΓòÉΓòÉΓòÉ
  6967.  
  6968.  The '-i' flag in the 'modules' file can be used to run a certain program 
  6969.  whenever files are committed (see modules).  The files described in this 
  6970.  section provide other, more flexible, ways to run programs whenever something 
  6971.  is committed. 
  6972.  
  6973.  There are three kind of programs that can be run on commit.  They are 
  6974.  specified in files in the repository, as described below.  The following table 
  6975.  summarizes the file names and the purpose of the corresponding programs. 
  6976.  
  6977.  commitinfo 
  6978.            The program is responsible for checking that the commit is allowed. 
  6979.            If it exits with a non-zero exit status the commit will be aborted. 
  6980.  
  6981.  verifymsg 
  6982.            The specified program is used to evaluate the log message, and 
  6983.            possibly verify that it contains all required fields.  This is most 
  6984.            useful in combination with the 'rcsinfo' file, which can hold a log 
  6985.            message template (see rcsinfo). 
  6986.  
  6987.  editinfo 
  6988.            The specified program is used to edit the log message, and possibly 
  6989.            verify that it contains all required fields.  This is most useful in 
  6990.            combination with the 'rcsinfo' file, which can hold a log message 
  6991.            template (see rcsinfo).  (obsolete) 
  6992.  
  6993.  loginfo 
  6994.            The specified program is called when the commit is complete.  It 
  6995.            receives the log message and some additional information and can 
  6996.            store the log message in a file, or mail it to appropriate persons, 
  6997.            or maybe post it to a local newsgroup, or┬╖┬╖┬╖  Your imagination is 
  6998.            the limit! 
  6999.  
  7000.  syntax                        The common syntax 
  7001.  
  7002.  
  7003. ΓòÉΓòÉΓòÉ 19.3.1. The common syntax ΓòÉΓòÉΓòÉ
  7004.  
  7005.  The administrative files such as 'commitinfo', 'loginfo', 'rcsinfo', 
  7006.  'verifymsg', etc., all have a common format.  The purpose of the files are 
  7007.  described later on.  The common syntax is described here. 
  7008.  
  7009.  Each line contains the following: 
  7010.  
  7011.      A regular expression.  This is a basic regular expression in the syntax 
  7012.       used by GNU emacs. 
  7013.  
  7014.      A whitespace separator---one or more spaces and/or tabs. 
  7015.  
  7016.      A file name or command-line template. 
  7017.  
  7018.  Blank lines are ignored.  Lines that start with the character '#' are treated 
  7019.  as comments.  Long lines unfortunately can not be broken in two parts in any 
  7020.  way. 
  7021.  
  7022.  The first regular expression that matches the current directory name in the 
  7023.  repository is used.  The rest of the line is used as a file name or 
  7024.  command-line as appropriate. 
  7025.  
  7026.  
  7027. ΓòÉΓòÉΓòÉ 19.4. Commitinfo ΓòÉΓòÉΓòÉ
  7028.  
  7029.  The 'commitinfo' file defines programs to execute whenever 'cvs commit' is 
  7030.  about to execute.  These programs are used for pre-commit checking to verify 
  7031.  that the modified, added and removed files are really ready to be committed. 
  7032.  This could be used, for instance, to verify that the changed files conform to 
  7033.  to your site's standards for coding practice. 
  7034.  
  7035.  As mentioned earlier, each line in the 'commitinfo' file consists of a regular 
  7036.  expression and a command-line template.  The template can include a program 
  7037.  name and any number of arguments you wish to supply to it.  The full path to 
  7038.  the current source repository is appended to the template, followed by the 
  7039.  file names of any files involved in the commit (added, removed, and modified 
  7040.  files). 
  7041.  
  7042.  The first line with a regular expression matching the relative path to the 
  7043.  module will be used.  If the command returns a non-zero exit status the commit 
  7044.  will be aborted. 
  7045.  
  7046.  If the repository name does not match any of the regular expressions in this 
  7047.  file, the 'DEFAULT' line is used, if it is specified. 
  7048.  
  7049.  All occurances of the name 'ALL' appearing as a regular expression are used in 
  7050.  addition to the first matching regular expression or the name 'DEFAULT'. 
  7051.  
  7052.  Note: when CVS is accessing a remote repository, 'commitinfo' will be run on 
  7053.  the remote (i.e., server) side, not the client side (see Remote repositories). 
  7054.  
  7055.  
  7056. ΓòÉΓòÉΓòÉ 19.5. Verifying log messages ΓòÉΓòÉΓòÉ
  7057.  
  7058.  Once you have entered a log message, you can evaluate that message to check 
  7059.  for specific content, such as a bug ID.  Use the 'verifymsg' file to specify a 
  7060.  program that is used to verify the log message. This program could be a simple 
  7061.  script that checks that the entered message contains the required fields. 
  7062.  
  7063.  The 'verifymsg' file is often most useful together with the 'rcsinfo' file, 
  7064.  which can be used to specify a log message template. 
  7065.  
  7066.  Each line in the 'verifymsg' file consists of a regular expression and a 
  7067.  command-line template.  The template must include a program name, and can 
  7068.  include any number of arguments.  The full path to the current log message 
  7069.  template file is appended to the template. 
  7070.  
  7071.  One thing that should be noted is that the 'ALL' keyword is not supported.  If 
  7072.  more than one matching line is found, the first one is used.  This can be 
  7073.  useful for specifying a default verification script in a module, and then 
  7074.  overriding it in a subdirectory. 
  7075.  
  7076.  If the repository name does not match any of the regular expressions in this 
  7077.  file, the 'DEFAULT' line is used, if it is specified. 
  7078.  
  7079.  If the verification script exits with a non-zero exit status, the commit is 
  7080.  aborted. 
  7081.  
  7082.  Note that the verification script cannot change the log message; it can merely 
  7083.  accept it or reject it. The following is a little silly example of a 
  7084.  'verifymsg' file, together with the corresponding 'rcsinfo' file, the log 
  7085.  message template and an verification  script.  We begin with the log message 
  7086.  template. We want to always record a bug-id number on the first line of the 
  7087.  log message.  The rest of log message is free text.  The following template is 
  7088.  found in the file '/usr/cvssupport/tc.template'. 
  7089.  
  7090.                       BugId:
  7091.  
  7092.  The script '/usr/cvssupport/bugid.verify' is used to evaluate the log message. 
  7093.  
  7094.                       #!/bin/sh
  7095.                       #
  7096.                       #    bugid.verify filename
  7097.                       #
  7098.                       #  Verify that the log message contains a valid bugid
  7099.                       #  on the first line.
  7100.                       #
  7101.                       if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
  7102.                         exit 0
  7103.                       else
  7104.                         echo "No BugId found."
  7105.                         exit 1
  7106.                       fi
  7107.  
  7108.  The 'verifymsg' file contains this line: 
  7109.  
  7110.                       ^tc   /usr/cvssupport/bugid.edit
  7111.  
  7112.  The 'rcsinfo' file contains this line: 
  7113.  
  7114.                       ^tc   /usr/cvssupport/tc.template
  7115.  
  7116.  
  7117. ΓòÉΓòÉΓòÉ 19.6. Editinfo ΓòÉΓòÉΓòÉ
  7118.  
  7119.  NOTE: The 'editinfo' feature has been rendered obsolete.  To set a default 
  7120.  editor for log messages use the EDITOR environment variable (see Environment 
  7121.  variables) or the '-e' global option (see Global options).  See verifymsg, for 
  7122.  information on the use of the 'verifymsg' feature for evaluating log messages. 
  7123.  
  7124.  If you want to make sure that all log messages look the same way, you can use 
  7125.  the 'editinfo' file to specify a program that is used to edit the log message. 
  7126.  This program could be a custom-made editor that always enforces a certain 
  7127.  style of the log message, or maybe a simple shell script that calls an editor, 
  7128.  and checks that the entered message contains the required fields. 
  7129.  
  7130.  If no matching line is found in the 'editinfo' file, the editor specified in 
  7131.  the environment variable $CVSEDITOR is used instead.  If that variable is not 
  7132.  set, then the environment variable $EDITOR is used instead.  If that variable 
  7133.  is not set a default will be used.  See Committing your changes. 
  7134.  
  7135.  The 'editinfo' file is often most useful together with the 'rcsinfo' file, 
  7136.  which can be used to specify a log message template. 
  7137.  
  7138.  Each line in the 'editinfo' file consists of a regular expression and a 
  7139.  command-line template.  The template must include a program name, and can 
  7140.  include any number of arguments.  The full path to the current log message 
  7141.  template file is appended to the template. 
  7142.  
  7143.  One thing that should be noted is that the 'ALL' keyword is not supported.  If 
  7144.  more than one matching line is found, the first one is used.  This can be 
  7145.  useful for specifying a default edit script in a module, and then overriding 
  7146.  it in a subdirectory. 
  7147.  
  7148.  If the repository name does not match any of the regular expressions in this 
  7149.  file, the 'DEFAULT' line is used, if it is specified. 
  7150.  
  7151.  If the edit script exits with a non-zero exit status, the commit is aborted. 
  7152.  
  7153.  Note: when CVS is accessing a remote repository, or when the '-m' or '-F' 
  7154.  options to cvs commit are used, 'editinfo' will not be consulted. There is no 
  7155.  good workaround for this; use 'verifymsg' instead. 
  7156.  
  7157.  editinfo example              Editinfo example 
  7158.  
  7159.  
  7160. ΓòÉΓòÉΓòÉ 19.6.1. Editinfo example ΓòÉΓòÉΓòÉ
  7161.  
  7162.  The following is a little silly example of a 'editinfo' file, together with 
  7163.  the corresponding 'rcsinfo' file, the log message template and an editor 
  7164.  script.  We begin with the log message template. We want to always record a 
  7165.  bug-id number on the first line of the log message.  The rest of log message 
  7166.  is free text.  The following template is found in the file 
  7167.  '/usr/cvssupport/tc.template'. 
  7168.  
  7169.                       BugId:
  7170.  
  7171.  The script '/usr/cvssupport/bugid.edit' is used to edit the log message. 
  7172.  
  7173.                       #!/bin/sh
  7174.                       #
  7175.                       #    bugid.edit filename
  7176.                       #
  7177.                       #  Call $EDITOR on FILENAME, and verify that the
  7178.                       #  resulting file contains a valid bugid on the first
  7179.                       #  line.
  7180.                       if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
  7181.                       if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
  7182.                       $CVSEDITOR $1
  7183.                       until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
  7184.                       do  echo -n  "No BugId found.  Edit again? ([y]/n)"
  7185.                         read ans
  7186.                         case ${ans} in
  7187.                           n*) exit 1;;
  7188.                         esac
  7189.                         $CVSEDITOR $1
  7190.                       done
  7191.  
  7192.  The 'editinfo' file contains this line: 
  7193.  
  7194.                       ^tc   /usr/cvssupport/bugid.edit
  7195.  
  7196.  The 'rcsinfo' file contains this line: 
  7197.  
  7198.                       ^tc   /usr/cvssupport/tc.template
  7199.  
  7200.  
  7201. ΓòÉΓòÉΓòÉ 19.7. Loginfo ΓòÉΓòÉΓòÉ
  7202.  
  7203.  The 'loginfo' file is used to control where 'cvs commit' log information is 
  7204.  sent.  The first entry on a line is a regular expression which is tested 
  7205.  against the directory that the change is being made to, relative to the 
  7206.  $CVSROOT.  If a match is found, then the remainder of the line is a filter 
  7207.  program that should expect log information on its standard input. 
  7208.  
  7209.  If the repository name does not match any of the regular expressions in this 
  7210.  file, the 'DEFAULT' line is used, if it is specified. 
  7211.  
  7212.  All occurances of the name 'ALL' appearing as a regular expression are used in 
  7213.  addition to the first matching regular expression or 'DEFAULT'. 
  7214.  
  7215.  The first matching regular expression is used. 
  7216.  
  7217.  See commit files, for a description of the syntax of the 'loginfo' file. 
  7218.  
  7219.  The user may specify a format string as part of the filter.  The string is 
  7220.  composed of a '%' followed by a space, or followed by a single format 
  7221.  character, or followed by a set of format characters surrounded by '{' and '}' 
  7222.  as separators.  The format characters are: 
  7223.  
  7224.  s 
  7225.            file name 
  7226.  
  7227.  V 
  7228.            old version number (pre-checkin) 
  7229.  
  7230.  v 
  7231.            new version number (post-checkin) 
  7232.  
  7233.  All other characters that appear in a format string expand to an empty field 
  7234.  (commas separating fields are still provided). 
  7235.  
  7236.  For example, some valid format strings are '%', '%s', '%{s}', and '%{sVv}'. 
  7237.  
  7238.  The output will be a string of tokens separated by spaces.  For backwards 
  7239.  compatibility, the first token will be the repository name.  The rest of the 
  7240.  tokens will be comma-delimited lists of the information requested in the 
  7241.  format string.  For example, if '/u/src/master' is the repository, '%{sVv}' is 
  7242.  the format string, and three files (ChangeLog, Makefile, foo.c) were modified, 
  7243.  the output might be: 
  7244.  
  7245.                       /u/src/master ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13
  7246.  
  7247.  As another example, '%{}' means that only the name of the repository will be 
  7248.  generated. 
  7249.  
  7250.  Note: when CVS is accessing a remote repository, 'loginfo' will be run on the 
  7251.  remote (i.e., server) side, not the client side (see Remote repositories). 
  7252.  
  7253.  loginfo example               Loginfo example 
  7254.  Keeping a checked out copy    Updating a tree on every checkin 
  7255.  
  7256.  
  7257. ΓòÉΓòÉΓòÉ 19.7.1. Loginfo example ΓòÉΓòÉΓòÉ
  7258.  
  7259.  The following 'loginfo' file, together with the tiny shell-script below, 
  7260.  appends all log messages to the file '$CVSROOT/CVSROOT/commitlog', and any 
  7261.  commits to the administrative files (inside the 'CVSROOT' directory) are also 
  7262.  logged in '/usr/adm/cvsroot-log'. Commits to the 'prog1' directory are mailed 
  7263.  to ceder. 
  7264.  
  7265.                       ALL       /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
  7266.                       ^CVSROOT     /usr/local/bin/cvs-log /usr/adm/cvsroot-log
  7267.                       ^prog1      Mail -s %s ceder
  7268.  
  7269.  The shell-script '/usr/local/bin/cvs-log' looks like this: 
  7270.  
  7271.                       #!/bin/sh
  7272.                       (echo "------------------------------------------------------";
  7273.                        echo -n $2"  ";
  7274.                        date;
  7275.                        echo;
  7276.                        cat) >> $1
  7277.  
  7278.  
  7279. ΓòÉΓòÉΓòÉ 19.7.2. Keeping a checked out copy ΓòÉΓòÉΓòÉ
  7280.  
  7281.  It is often useful to maintain a directory tree which contains files which 
  7282.  correspond to the latest version in the repository.  For example, other 
  7283.  developers might want to refer to the latest sources without having to check 
  7284.  them out, or you might be maintaining a web site with CVS and want every 
  7285.  checkin to cause the files used by the web server to be updated. The way to do 
  7286.  this is by having loginfo invoke cvs update.  Doing so in the naive way will 
  7287.  cause a problem with locks, so the cvs update must be run in the background. 
  7288.  Here is an example for unix (this should all be on one line): 
  7289.  
  7290.                       ^cyclic-pages        (date; cat; (sleep 2; cd /u/www/local-docs;
  7291.                        cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
  7292.  
  7293.  This will cause checkins to repository directories starting with cyclic-pages 
  7294.  to update the checked out tree in '/u/www/local-docs'. 
  7295.  
  7296.  
  7297. ΓòÉΓòÉΓòÉ 19.8. Rcsinfo ΓòÉΓòÉΓòÉ
  7298.  
  7299.  The 'rcsinfo' file can be used to specify a form to edit when filling out the 
  7300.  commit log.  The 'rcsinfo' file has a syntax similar to the 'verifymsg', 
  7301.  'commitinfo' and 'loginfo' files.  See syntax.  Unlike the other files the 
  7302.  second part is not a command-line template.  Instead, the part after the 
  7303.  regular expression should be a full pathname to a file containing the log 
  7304.  message template. 
  7305.  
  7306.  If the repository name does not match any of the regular expressions in this 
  7307.  file, the 'DEFAULT' line is used, if it is specified. 
  7308.  
  7309.  All occurances of the name 'ALL' appearing as a regular expression are used in 
  7310.  addition to the first matching regular expression or 'DEFAULT'. 
  7311.  
  7312.  The log message template will be used as a default log message.  If you 
  7313.  specify a log message with 'cvs commit -m message' or 'cvs commit -f file' 
  7314.  that log message will override the template. 
  7315.  
  7316.  See verifymsg, for an example 'rcsinfo' file. 
  7317.  
  7318.  When CVS is accessing a remote repository, the contents of 'rcsinfo' at the 
  7319.  time a directory is first checked out will specify a template which does not 
  7320.  then change.  If you edit 'rcsinfo' or its templates, you may need to check 
  7321.  out a new working directory. 
  7322.  
  7323.  
  7324. ΓòÉΓòÉΓòÉ 19.9. Ignoring files via cvsignore ΓòÉΓòÉΓòÉ
  7325.  
  7326.  There are certain file names that frequently occur inside your working copy, 
  7327.  but that you don't want to put under CVS control.  Examples are all the object 
  7328.  files that you get while you compile your sources. Normally, when you run 'cvs 
  7329.  update', it prints a line for each file it encounters that it doesn't know 
  7330.  about (see update output). 
  7331.  
  7332.  CVS has a list of files (or sh(1) file name patterns) that it should ignore 
  7333.  while running update, import and release. This list is constructed in the 
  7334.  following way. 
  7335.  
  7336.      The list is initialized to include certain file name patterns: names 
  7337.       associated with CVS administration, or with other common source control 
  7338.       systems; common names for patch files, object files, archive files, and 
  7339.       editor backup files; and other names that are usually artifacts of 
  7340.       assorted utilities. Currently, the default list of ignored file name 
  7341.       patterns is: 
  7342.  
  7343.                         RCS   SCCS   CVS   CVS.adm
  7344.                         RCSLOG  cvslog.*
  7345.                         tags   TAGS
  7346.                         .make.state   .nse_depinfo
  7347.                         *~    #*    .#*   ,*    _$*   *$
  7348.                         *.old  *.bak  *.BAK  *.orig  *.rej  .del-*
  7349.                         *.a   *.olb  *.o   *.obj  *.so   *.exe
  7350.                         *.Z   *.elc  *.ln
  7351.                         core
  7352.  
  7353.      The per-repository list in '$CVSROOT/CVSROOT/cvsignore' is appended to 
  7354.       the list, if that file exists. 
  7355.  
  7356.      The per-user list in '.cvsignore' in your home directory is appended to 
  7357.       the list, if it exists. 
  7358.  
  7359.      Any entries in the environment variable $CVSIGNORE is appended to the 
  7360.       list. 
  7361.  
  7362.      Any '-I' options given to CVS is appended. 
  7363.  
  7364.      As CVS traverses through your directories, the contents of any 
  7365.       '.cvsignore' will be appended to the list. The patterns found in 
  7366.       '.cvsignore' are only valid for the directory that contains them, not for 
  7367.       any sub-directories. 
  7368.  
  7369.  In any of the 5 places listed above, a single exclamation mark ('!') clears 
  7370.  the ignore list. This can be used if you want to store any file which normally 
  7371.  is ignored by CVS. 
  7372.  
  7373.  Specifying '-I !' to cvs import will import everything, which is generally 
  7374.  what you want to do if you are importing files from a pristine distribution or 
  7375.  any other source which is known to not contain any extraneous files.  However, 
  7376.  looking at the rules above you will see there is a fly in the ointment; if the 
  7377.  distribution contains any '.cvsignore' files, then the patterns from those 
  7378.  files will be processed even if '-I !' is specified.  The only workaround is 
  7379.  to remove the '.cvsignore' files in order to do the import.  Because this is 
  7380.  awkward, in the future '-I !' might be modified to override '.cvsignore' files 
  7381.  in each directory. 
  7382.  
  7383.  Note that the syntax of the ignore files consists of a series of lines, each 
  7384.  of which contains a space separated list of filenames.  This offers no clean 
  7385.  way to specify filenames which contain spaces, but you can use a workaround 
  7386.  like 'foo?bar' to match a file named 'foo bar' (it also matches 'fooxbar' and 
  7387.  the like).  Also note that there is currently no way to specify comments. 
  7388.  
  7389.  
  7390. ΓòÉΓòÉΓòÉ 19.10. The history file ΓòÉΓòÉΓòÉ
  7391.  
  7392.  The file '$CVSROOT/CVSROOT/history' is used to log information for the history 
  7393.  command (see history).  This file must be created to turn on logging.  This is 
  7394.  done automatically if the cvs init command is used to set up the repository 
  7395.  (see Creating a repository). 
  7396.  
  7397.  The file format of the 'history' file is documented only in comments in the 
  7398.  CVS source code, but generally programs should use the cvs history command to 
  7399.  access it anyway, in case the format changes with future releases of CVS. 
  7400.  
  7401.  
  7402. ΓòÉΓòÉΓòÉ 19.11. Expansions in administrative files ΓòÉΓòÉΓòÉ
  7403.  
  7404.  Sometimes in writing an administrative file, you might want the file to be 
  7405.  able to know various things based on environment CVS is running in.  There are 
  7406.  several mechanisms to do that. 
  7407.  
  7408.  To find the home directory of the user running CVS (from the HOME environment 
  7409.  variable), use '~' followed by '/' or the end of the line. Likewise for the 
  7410.  home directory of user, use '~user'.  These variables are expanded on the 
  7411.  server machine, and don't get any reasonable expansion if pserver (see 
  7412.  Password authenticated) is in use; therefore user variables (see below) may be 
  7413.  a better choice to customize behavior based on the user running CVS. One may 
  7414.  want to know about various pieces of information internal to CVS.  A CVS 
  7415.  internal variable has the syntax ${variable}, where variable starts with a 
  7416.  letter and consists of alphanumberic characters and '_'.  If the character 
  7417.  following variable is a non-alphanumeric character other than '_', the '{' and 
  7418.  '}' can be omitted.  The CVS internal variables are: 
  7419.  
  7420.  CVSROOT 
  7421.            This is the value of the CVS root in use. See Repository, for a 
  7422.            description of the various ways to specify this. 
  7423.  
  7424.  RCSBIN 
  7425.            In CVS 1.9.18 and older, this specified the directory where CVS was 
  7426.            looking for RCS programs.  Because CVS no longer runs RCS programs, 
  7427.            specifying this internal variable is now an error. 
  7428.  
  7429.  CVSEDITOR 
  7430.  
  7431.  VISUAL 
  7432.  
  7433.  EDITOR 
  7434.            These all expand to the same value, which is the editor that CVS is 
  7435.            using.  See Global options, for how to specify this. 
  7436.  
  7437.  USER 
  7438.            Username of the user running CVS (on the CVS server machine). 
  7439.  
  7440.  If you want to pass a value to the administrative files which the user who is 
  7441.  running CVS can specify, use a user variable.  To expand a user variable, the 
  7442.  administrative file contains ${=variable}.  To set a user variable, specify 
  7443.  the global option '-s' to CVS, with argument variable=value.  It may be 
  7444.  particularly useful to specify this option via '.cvsrc' (see ~/.cvsrc). 
  7445.  
  7446.  For example, if you want the administrative file to refer to a test directory 
  7447.  you might create a user variable TESTDIR.  Then if CVS is invoked as 
  7448.  
  7449.                       cvs -s TESTDIR=/work/local/tests
  7450.  
  7451.  and the administrative file contains sh ${=TESTDIR}/runtests, then that string 
  7452.  is expanded to sh /work/local/tests/runtests. 
  7453.  
  7454.  All other strings containing '$' are reserved; there is no way to quote a '$' 
  7455.  character so that '$' represents itself. 
  7456.  
  7457.  
  7458. ΓòÉΓòÉΓòÉ 19.12. The CVSROOT/config configuration file ΓòÉΓòÉΓòÉ
  7459.  
  7460.  The administrative file 'config' contains various miscellaneous settings which 
  7461.  affect the behavior of CVS.  The syntax is slightly different from the other 
  7462.  administrative files.  Variables are not expanded.  Lines which start with '#' 
  7463.  are considered comments. Other lines consist of a keyword, '=', and a value. 
  7464.  Note that this syntax is very strict. Extraneous spaces or tabs are not 
  7465.  permitted. Currently defined keywords are: 
  7466.  
  7467.  RCSBIN=bindir 
  7468.            For CVS 1.9.12 through 1.9.18, this setting told CVS to look for RCS 
  7469.            programs in the bindir directory.  Current versions of CVS do not 
  7470.            run RCS programs; for compatibility this setting is accepted, but it 
  7471.            does nothing. 
  7472.  
  7473.  SystemAuth=value 
  7474.            If value is 'yes', then pserver should check for users in the 
  7475.            system's user database if not found in 'CVSROOT/passwd'.  If it is 
  7476.            'no', then all pserver users must exist in 'CVSROOT/passwd'. The 
  7477.            default is 'yes'.  For more on pserver, see Password authenticated. 
  7478.  
  7479.  PreservePermissions=value 
  7480.            Enable support for saving special device files, symbolic links, file 
  7481.            permissions and ownerships in the repository.  The default value is 
  7482.            'no'. See Special Files for the full implications of using this 
  7483.            keyword. 
  7484.  
  7485.  TopLevelAdmin=value 
  7486.            Modify the 'checkout' command to create a 'CVS' directory at the top 
  7487.            level of the new working directory, in addition to 'CVS' directories 
  7488.            created within checked-out directories. The default value is 'no'. 
  7489.  
  7490.            This option is useful if you find yourself performing many commands 
  7491.            at the top level of your working directory, rather than in one of 
  7492.            the checked out subdirectories.  The 'CVS' directory created there 
  7493.            will mean you don't have to specify 'CVSROOT' for each command.  It 
  7494.            also provides a place for the 'CVS/Template' file (see Working 
  7495.            directory storage). 
  7496.  
  7497.  
  7498. ΓòÉΓòÉΓòÉ 20. All environment variables which affect CVS ΓòÉΓòÉΓòÉ
  7499.  
  7500.  This is a complete list of all environment variables that affect CVS. 
  7501.  
  7502.  $CVSIGNORE 
  7503.            A whitespace-separated list of file name patterns that CVS should 
  7504.            ignore. See cvsignore. 
  7505.  
  7506.  $CVSWRAPPERS 
  7507.            A whitespace-separated list of file name patterns that CVS should 
  7508.            treat as wrappers. See Wrappers. 
  7509.  
  7510.  $CVSREAD 
  7511.            If this is set, checkout and update will try hard to make the files 
  7512.            in your working directory read-only.  When this is not set, the 
  7513.            default behavior is to permit modification of your working files. 
  7514.  
  7515.  $CVSUMASK 
  7516.            Controls permissions of files in the repository.  See File 
  7517.            permissions. 
  7518.  
  7519.  $CVSROOT 
  7520.            Should contain the full pathname to the root of the CVS source 
  7521.            repository (where the RCS files are kept).  This information must be 
  7522.            available to CVS for most commands to execute; if $CVSROOT is not 
  7523.            set, or if you wish to override it for one invocation, you can 
  7524.            supply it on the command line: 'cvs -d cvsroot cvs_command┬╖┬╖┬╖' Once 
  7525.            you have checked out a working directory, CVS stores the appropriate 
  7526.            root (in the file 'CVS/Root'), so normally you only need to worry 
  7527.            about this when initially checking out a working directory. 
  7528.  
  7529.  $EDITOR 
  7530.  
  7531.  $CVSEDITOR 
  7532.            Specifies the program to use for recording log messages during 
  7533.            commit.  $CVSEDITOR overrides $EDITOR.  See Committing your changes. 
  7534.  
  7535.  $PATH 
  7536.            If $RCSBIN is not set, and no path is compiled into CVS, it will use 
  7537.            $PATH to try to find all programs it uses. 
  7538.  
  7539.  $HOME 
  7540.  
  7541.  $HOMEPATH 
  7542.  
  7543.  $HOMEDRIVE 
  7544.            Used to locate the directory where the '.cvsrc' file, and other such 
  7545.            files, are searched.  On Unix, CVS just checks for HOME.  On Windows 
  7546.            NT, the system will set HOMEDRIVE, for example to 'd:' and HOMEPATH, 
  7547.            for example to '\joe'.  On Windows 95, you'll probably need to set 
  7548.            HOMEDRIVE and HOMEPATH yourself. 
  7549.  
  7550.  $CVS_RSH 
  7551.            Specifies the external program which CVS connects with, when :ext: 
  7552.            access method is specified. see Connecting via rsh. 
  7553.  
  7554.  $CVS_SERVER 
  7555.            Used in client-server mode when accessing a remote repository using 
  7556.            RSH.  It specifies the name of the program to start on the server 
  7557.            side when accessing a remote repository using RSH.  The default 
  7558.            value is cvs.  see Connecting via rsh 
  7559.  
  7560.  $CVS_PASSFILE 
  7561.            Used in client-server mode when accessing the cvs login server. 
  7562.            Default value is '$HOME/.cvspass'. see Password authentication 
  7563.            client 
  7564.  
  7565.  $CVS_CLIENT_PORT 
  7566.            Used in client-server mode when accessing the server via Kerberos. 
  7567.            see Kerberos authenticated 
  7568.  
  7569.  $CVS_RCMD_PORT 
  7570.            Used in client-server mode.  If set, specifies the port number to be 
  7571.            used when accessing the RCMD demon on the server side. (Currently 
  7572.            not used for Unix clients). 
  7573.  
  7574.  $CVS_CLIENT_LOG 
  7575.            Used for debugging only in client-server mode.  If set, everything 
  7576.            send to the server is logged into '$CVS_CLIENT_LOG.in' and 
  7577.            everything send from the server is logged into 
  7578.            '$CVS_CLIENT_LOG.out'. 
  7579.  
  7580.  $CVS_SERVER_SLEEP 
  7581.            Used only for debugging the server side in client-server mode.  If 
  7582.            set, delays the start of the server child process the specified 
  7583.            amount of seconds so that you can attach to it with a debugger. 
  7584.  
  7585.  $CVS_IGNORE_REMOTE_ROOT 
  7586.            (What is the purpose of this variable?) 
  7587.  
  7588.  $COMSPEC 
  7589.            Used under OS/2 only.  It specifies the name of the command 
  7590.            interpreter and defaults to CMD.EXE. 
  7591.  
  7592.  $TMPDIR 
  7593.  
  7594.  $TMP 
  7595.  
  7596.  $TEMP 
  7597.            Directory in which temporary files are located. The CVS server uses 
  7598.            TMPDIR.  See Global options, for a description of how to specify 
  7599.            this. Some parts of CVS will always use '/tmp' (via the tmpnam 
  7600.            function provided by the system). 
  7601.  
  7602.            On Windows NT, TMP is used (via the _tempnam function provided by 
  7603.            the system). 
  7604.  
  7605.            The patch program which is used by the CVS client uses TMPDIR, and 
  7606.            if it is not set, uses '/tmp' (at least with GNU patch 2.1).  Note 
  7607.            that if your server and client are both running CVS 1.9.10 or later, 
  7608.            CVS will not invoke an external patch program. 
  7609.  
  7610.  
  7611. ΓòÉΓòÉΓòÉ 21. Compatibility between CVS Versions ΓòÉΓòÉΓòÉ
  7612.  
  7613.  The repository format is compatible going back to CVS 1.3.  But see Watches 
  7614.  Compatibility, if you have copies of CVS 1.6 or older and you want to use the 
  7615.  optional developer communication features. The working directory format is 
  7616.  compatible going back to CVS 1.5.  It did change between CVS 1.3 and CVS 1.5. 
  7617.  If you run CVS 1.5 or newer on a working directory checked out with CVS 1.3, 
  7618.  CVS will convert it, but to go back to CVS 1.3 you need to check out a new 
  7619.  working directory with CVS 1.3. 
  7620.  
  7621.  The remote protocol is interoperable going back to CVS 1.5, but no further 
  7622.  (1.5 was the first official release with the remote protocol, but some older 
  7623.  versions might still be floating around).  In many cases you need to upgrade 
  7624.  both the client and the server to take advantage of new features and bugfixes, 
  7625.  however. 
  7626.  
  7627.  
  7628. ΓòÉΓòÉΓòÉ 22. Troubleshooting ΓòÉΓòÉΓòÉ
  7629.  
  7630.  If you are having trouble with CVS, this appendix may help.  If there is a 
  7631.  particular error message which you are seeing, then you can look up the 
  7632.  message alphabetically.  If not, you can look through the section on other 
  7633.  problems to see if your problem is mentioned there. 
  7634.  
  7635.  Error messages                Partial list of CVS errors 
  7636.  Connection                    Trouble making a connection to a CVS server 
  7637.  Other problems                Problems not readily listed by error message 
  7638.  
  7639.  
  7640. ΓòÉΓòÉΓòÉ 22.1. Partial list of error messages ΓòÉΓòÉΓòÉ
  7641.  
  7642.  Here is a partial list of error messages that you may see from CVS.  It is not 
  7643.  a complete list---CVS is capable of printing many, many error messages, often 
  7644.  with parts of them supplied by the operating system, but the intention is to 
  7645.  list the common and/or potentially confusing error messages. 
  7646.  
  7647.  The messages are alphabetical, but introductory text such as 'cvs update: ' is 
  7648.  not considered in ordering them. 
  7649.  
  7650.  In some cases the list includes messages printed by old versions of CVS 
  7651.  (partly because users may not be sure which version of CVS they are using at 
  7652.  any particular moment). 
  7653.  
  7654.  cvs command: authorization failed: server host rejected access 
  7655.            This is a generic response when trying to connect to a pserver 
  7656.            server which chooses not to provide a specific reason for denying 
  7657.            authorization.  Check that the username and password specified are 
  7658.            correct and that the CVSROOT specified is allowed by --allow-root in 
  7659.            inetd.conf.  See Password authenticated. 
  7660.  
  7661.  file:line: Assertion 'text' failed 
  7662.            The exact format of this message may vary depending on your system. 
  7663.            It indicates a bug in CVS, which can be handled as described in 
  7664.            BUGS. 
  7665.  
  7666.  cvs command: conflict: removed file was modified by second party 
  7667.            This message indicates that you removed a file, and someone else 
  7668.            modified it.  To resolve the conflict, first run 'cvs add file'.  If 
  7669.            desired, look at the other party's modification to decide whether 
  7670.            you still want to remove it.  If you don't want to remove it, stop 
  7671.            here.  If you do want to remove it, proceed with 'cvs remove file' 
  7672.            and commit your removal. 
  7673.  
  7674.  cannot change permissions on temporary directory 
  7675.  
  7676.                       Operation not permitted
  7677.  This message has been happening in a non-reproducible, occasional way when we 
  7678.  run the client/server testsuite, both on Red Hat Linux 3.0.3 and 4.1.  We 
  7679.  haven't been able to figure out what causes it, nor is it known whether it is 
  7680.  specific to linux (or even to this particular machine!).  If the problem does 
  7681.  occur on other unices, 'Operation not permitted' would be likely to read 'Not 
  7682.  owner' or whatever the system in question uses for the unix EPERM error.  If 
  7683.  you have any information to add, please let us know as described in BUGS.  If 
  7684.  you experience this error while using CVS, retrying the operation which 
  7685.  produced it should work fine. 
  7686.  
  7687.  cannot open CVS/Entries for reading: No such file or directory 
  7688.            This generally indicates a CVS internal error, and can be handled as 
  7689.            with other CVS bugs (see BUGS).  Usually there is a workaround---the 
  7690.            exact nature of which would depend on the situation but which 
  7691.            hopefully could be figured out. 
  7692.  
  7693.  cvs [init aborted]: cannot open CVS/Root: No such file or directory 
  7694.            This message is harmless.  Provided it is not accompanied by other 
  7695.            errors, the operation has completed successfully.  This message 
  7696.            should not occur with current versions of CVS, but it is documented 
  7697.            here for the benefit of CVS 1.9 and older. 
  7698.  
  7699.  cvs [checkout aborted]: cannot rename file file to CVS/,,file: Invalid 
  7700.  argument 
  7701.            This message has been reported as intermittently happening with CVS 
  7702.            1.9 on Solaris 2.5.  The cause is unknown; if you know more about 
  7703.            what causes it, let us know as described in BUGS. 
  7704.  
  7705.  cvs [command aborted]: cannot start server via rcmd 
  7706.            This, unfortunately, is a rather nonspecific error message which CVS 
  7707.            1.9 will print if you are running the CVS client and it is having 
  7708.            trouble connecting to the server.  Current versions of CVS should 
  7709.            print a much more specific error message.  If you get this message 
  7710.            when you didn't mean to run the client at all, you probably forgot 
  7711.            to specify :local:, as described in Repository. 
  7712.  
  7713.  ci: file,v: bad diff output line: Binary files - and /tmp/T2a22651 differ 
  7714.            CVS 1.9 and older will print this message when trying to check in a 
  7715.            binary file if RCS is not correctly installed.  Re-read the 
  7716.            instructions that came with your RCS distribution and the INSTALL 
  7717.            file in the CVS distribution.  Alternately, upgrade to a current 
  7718.            version of CVS, which checks in files itself rather than via RCS. 
  7719.  
  7720.  cvs checkout: could not check out file 
  7721.            With CVS 1.9, this can mean that the co program (part of RCS) 
  7722.            returned a failure.  It should be preceded by another error message, 
  7723.            however it has been observed without another error message and the 
  7724.            cause is not well-understood.  With the current version of CVS, 
  7725.            which does not run co, if this message occurs without another error 
  7726.            message, it is definitely a CVS bug (see BUGS). 
  7727.  
  7728.  cvs [login aborted]: could not find out home directory 
  7729.            This means that you need to set the environment variables that CVS 
  7730.            uses to locate your home directory. See the discussion of HOME, 
  7731.            HOMEDRIVE, and HOMEPATH in Environment variables. 
  7732.  
  7733.  cvs update: could not merge revision rev of file: No such file or directory 
  7734.            CVS 1.9 and older will print this message if there was a problem 
  7735.            finding the rcsmerge program.  Make sure that it is in your PATH, or 
  7736.            upgrade to a current version of CVS, which does not require an 
  7737.            external rcsmerge program. 
  7738.  
  7739.  cvs [update aborted]: could not patch file: No such file or directory 
  7740.            This means that there was a problem finding the patch program.  Make 
  7741.            sure that it is in your PATH.  Note that despite appearances the 
  7742.            message is not referring to whether it can find file. If both the 
  7743.            client and the server are running a current version of CVS, then 
  7744.            there is no need for an external patch program and you should not 
  7745.            see this message.  But if either client or server is running CVS 
  7746.            1.9, then you need patch. 
  7747.  
  7748.  cvs update: could not patch file; will refetch 
  7749.            This means that for whatever reason the client was unable to apply a 
  7750.            patch that the server sent.  The message is nothing to be concerned 
  7751.            about, because inability to apply the patch only slows things down 
  7752.            and has no effect on what CVS does. 
  7753.  
  7754.  dying gasps from server unexpected 
  7755.            There is a known bug in the server for CVS 1.9.18 and older which 
  7756.            can cause this.  For me, this was reproducible if I used the '-t' 
  7757.            global option.  It was fixed by Andy Piper's 14 Nov 1997 change to 
  7758.            src/filesubr.c, if anyone is curious. If you see the message, you 
  7759.            probably can just retry the operation which failed, or if you have 
  7760.            discovered information concerning its cause, please let us know as 
  7761.            described in BUGS. 
  7762.  
  7763.  end of file from server (consult above messages if any) 
  7764.            The most common cause for this message is if you are using an 
  7765.            external rsh program and it exited with an error.  In this case the 
  7766.            rsh program should have printed a message, which will appear before 
  7767.            the above message.  For more information on setting up a CVS client 
  7768.            and server, see Remote repositories. 
  7769.  
  7770.  cvs commit: Executing 'mkmodules' 
  7771.            This means that your repository is set up for a version of CVS prior 
  7772.            to CVS 1.8.  When using CVS 1.8 or later, the above message will be 
  7773.            preceded by 
  7774.  
  7775.                       cvs commit: Rebuilding administrative file database
  7776.  
  7777.  If you see both messages, the database is being rebuilt twice, which is 
  7778.  unnecessary but harmless.  If you wish to avoid the duplication, and you have 
  7779.  no versions of CVS 1.7 or earlier in use, remove -i mkmodules every place it 
  7780.  appears in your modules file.  For more information on the modules file, see 
  7781.  modules. 
  7782.  
  7783.  missing author 
  7784.            Typically this can happen if you created an RCS file with your 
  7785.            username set to empty.  CVS will, bogusly, create an illegal RCS 
  7786.            file with no value for the author field.  The solution is to make 
  7787.            sure your username is set to a non-empty value and re-create the RCS 
  7788.            file. 
  7789.  
  7790.  *PANIC* administration files missing 
  7791.            This typically means that there is a directory named CVS but it does 
  7792.            not contain the administrative files which CVS puts in a CVS 
  7793.            directory.  If the problem is that you created a CVS directory via 
  7794.            some mechanism other than CVS, then the answer is simple, use a name 
  7795.            other than CVS.  If not, it indicates a CVS bug (see BUGS). 
  7796.  
  7797.  rcs error: Unknown option: -x,v/ 
  7798.            This message will be followed by a usage message for RCS.  It means 
  7799.            that you have an old version of RCS (probably supplied with your 
  7800.            operating system).  CVS only works with RCS version 5 and later. 
  7801.  
  7802.  cvs [server aborted]: received broken pipe signal 
  7803.            This message seems to be caused by a hard-to-track-down bug in CVS 
  7804.            or the systems it runs on (we don't know---we haven't tracked it 
  7805.            down yet!).  It seems to happen only after a CVS command has 
  7806.            completed, and you should be able to just ignore the message. 
  7807.            However, if you have discovered information concerning its cause, 
  7808.            please let us know as described in BUGS. 
  7809.  
  7810.  Too many arguments! 
  7811.            This message is typically printed by the 'log.pl' script which is in 
  7812.            the 'contrib' directory in the CVS source distribution.  In some 
  7813.            versions of CVS, 'log.pl' has been part of the default CVS 
  7814.            installation.  The 'log.pl' script gets called from the 'loginfo' 
  7815.            administrative file. Check that the arguments passed in 'loginfo' 
  7816.            match what your version of 'log.pl' expects.  In particular, the 
  7817.            'log.pl' from CVS 1.3 and older expects the logfile as an argument 
  7818.            whereas the 'log.pl' from CVS 1.5 and newer expects the logfile to 
  7819.            be specified with a '-f' option.  Of course, if you don't need 
  7820.            'log.pl' you can just comment it out of 'loginfo'. 
  7821.  
  7822.  cvs commit: Up-to-date check failed for `file' 
  7823.            This means that someone else has committed a change to that file 
  7824.            since the last time that you did a cvs update.  So before proceeding 
  7825.            with your cvs commit you need to cvs update.  CVS will merge the 
  7826.            changes that you made and the changes that the other person made. 
  7827.            If it does not detect any conflicts it will report 'M cacErrCodes.h' 
  7828.            and you are ready to cvs commit.  If it detects conflicts it will 
  7829.            print a message saying so, will report 'C cacErrCodes.h', and you 
  7830.            need to manually resolve the conflict.  For more details on this 
  7831.            process see Conflicts example. 
  7832.  
  7833.  Usage:    diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 
  7834.  
  7835.                       Only one of [exEX3] allowed
  7836.  This indicates a problem with the installation of diff3 and rcsmerge. 
  7837.  Specifically rcsmerge was compiled to look for GNU diff3, but it is finding 
  7838.  unix diff3 instead.  The exact text of the message will vary depending on the 
  7839.  system.  The simplest solution is to upgrade to a current version of CVS, 
  7840.  which does not rely on external rcsmerge or diff3 programs. 
  7841.  
  7842.  warning: unrecognized response `text' from cvs server 
  7843.            If text contains a valid response (such as 'ok') followed by an 
  7844.            extra carriage return character (on many systems this will cause the 
  7845.            second part of the message to overwrite the first part), then it 
  7846.            probably means that you are using the ':ext:' access method with a 
  7847.            version of rsh, such as most non-unix rsh versions, which does not 
  7848.            by default provide a transparent data stream.  In such cases you 
  7849.            probably want to try ':server:' instead of ':ext:'.  If text is 
  7850.            something else, this may signify a problem with your CVS server. 
  7851.            Double-check your installation against the instructions for setting 
  7852.            up the CVS server. 
  7853.  
  7854.  cvs commit: warning: editor session failed 
  7855.            This means that the editor which CVS is using exits with a nonzero 
  7856.            exit status.  Some versions of vi will do this even when there was 
  7857.            not a problem editing the file.  If so, point the CVSEDITOR 
  7858.            environment variable to a small script such as: 
  7859.  
  7860.                       #!/bin/sh
  7861.                       vi $*
  7862.                       exit 0
  7863.  
  7864.  
  7865. ΓòÉΓòÉΓòÉ 22.2. Trouble making a connection to a CVS server ΓòÉΓòÉΓòÉ
  7866.  
  7867.  This section concerns what to do if you are having trouble making a connection 
  7868.  to a CVS server.  If you are running the CVS command line client running on 
  7869.  Windows, first upgrade the client to CVS 1.9.12 or later.  The error reporting 
  7870.  in earlier versions provided much less information about what the problem was. 
  7871.  If the client is non-Windows, CVS 1.9 should be fine. 
  7872.  
  7873.  If the error messages are not sufficient to track down the problem, the next 
  7874.  steps depend largely on which access method you are using. 
  7875.  
  7876.  :ext: 
  7877.            Try running the rsh program from the command line.  For example: 
  7878.            "rsh servername cvs -v" should print CVS version information.  If 
  7879.            this doesn't work, you need to fix it before you can worry about CVS 
  7880.            problems. 
  7881.  
  7882.  :server: 
  7883.            You don't need a command line rsh program to use this access method, 
  7884.            but if you have an rsh program around, it may be useful as a 
  7885.            debugging tool.  Follow the directions given for :ext:. 
  7886.  
  7887.  :pserver: 
  7888.            One good debugging tool is to "telnet servername 2401".  After 
  7889.            connecting, send any text (for example "foo" followed by return). 
  7890.            If CVS is working correctly, it will respond with 
  7891.  
  7892.                       cvs [pserver aborted]: bad auth protocol start: foo
  7893.  
  7894.  If this fails to work, then make sure inetd is working right.  Change the 
  7895.  invocation in inetd.conf to run the echo program instead of cvs.  For example: 
  7896.  
  7897.                       2401  stream  tcp  nowait  root /bin/echo echo hello
  7898.  
  7899.  After making that change and instructing inetd to re-read its configuration 
  7900.  file, "telnet servername 2401" should show you the text hello and then the 
  7901.  server should close the connection.  If this doesn't work, you need to fix it 
  7902.  before you can worry about CVS problems. 
  7903.  
  7904.  On AIX systems, the system will often have its own program trying to use port 
  7905.  2401.  This is AIX's problem in the sense that port 2401 is registered for use 
  7906.  with CVS.  I hear that there is an AIX patch available to address this 
  7907.  problem. 
  7908.  
  7909.  
  7910. ΓòÉΓòÉΓòÉ 22.3. Other common problems ΓòÉΓòÉΓòÉ
  7911.  
  7912.  Here is a list of problems which do not fit into the above categories.  They 
  7913.  are in no particular order. 
  7914.  
  7915.      If you are running CVS 1.9.18 or older, and cvs update finds a conflict 
  7916.       and tries to merge, as described in Conflicts example, but doesn't tell 
  7917.       you there were conflicts, then you may have an old version of RCS.  The 
  7918.       easiest solution probably is to upgrade to a current version of CVS, 
  7919.       which does not rely on external RCS programs. 
  7920.  
  7921.  
  7922. ΓòÉΓòÉΓòÉ 23. Credits ΓòÉΓòÉΓòÉ
  7923.  
  7924.  Roland Pesch, then of Cygnus Support <roland@wrs.com> wrote the manual pages 
  7925.  which were distributed with CVS 1.3.  Much of their text was copied into this 
  7926.  manual.  He also read an early draft of this manual and contributed many ideas 
  7927.  and corrections. 
  7928.  
  7929.  The mailing-list info-cvs is sometimes informative. I have included 
  7930.  information from postings made by the following persons: David G. Grubbs 
  7931.  <dgg@think.com>. 
  7932.  
  7933.  Some text has been extracted from the man pages for RCS. 
  7934.  
  7935.  The CVS FAQ by David G. Grubbs has provided useful material.  The FAQ is no 
  7936.  longer maintained, however, and this manual is about the closest thing there 
  7937.  is to a successor (with respect to documenting how to use CVS, at least). 
  7938.  
  7939.  In addition, the following persons have helped by telling me about mistakes 
  7940.  I've made: 
  7941.  
  7942.                       Roxanne Brunskill <rbrunski@datap.ca>,
  7943.                       Kathy Dyer <dyer@phoenix.ocf.llnl.gov>,
  7944.                       Karl Pingle <pingle@acuson.com>,
  7945.                       Thomas A Peterson <tap@src.honeywell.com>,
  7946.                       Inge Wallin <ingwa@signum.se>,
  7947.                       Dirk Koschuetzki <koschuet@fmi.uni-passau.de>
  7948.                       and Michael Brown <brown@wi.extrel.com>.
  7949.  
  7950.  The list of contributors here is not comprehensive; for a more complete list 
  7951.  of who has contributed to this manual see the file 'doc/ChangeLog' in the CVS 
  7952.  source distribution. 
  7953.  
  7954.  
  7955. ΓòÉΓòÉΓòÉ 24. Dealing with bugs in CVS or this manual ΓòÉΓòÉΓòÉ
  7956.  
  7957.  Neither CVS nor this manual is perfect, and they probably never will be.  If 
  7958.  you are having trouble using CVS, or think you have found a bug, there are a 
  7959.  number of things you can do about it.  Note that if the manual is unclear, 
  7960.  that can be considered a bug in the manual, so these problems are often worth 
  7961.  doing something about as well as problems with CVS itself. 
  7962.  
  7963.      If you want someone to help you and fix bugs that you report, there are 
  7964.       companies which will do that for a fee.  Two such companies are: 
  7965.  
  7966.                       Signum Support AB
  7967.                       Box 2044
  7968.                       S-580 02  Linkoping
  7969.                       Sweden
  7970.                       Email: info@signum.se
  7971.                       Phone: +46 (0)13 - 21 46 00
  7972.                       Fax:  +46 (0)13 - 21 47 00
  7973.                       http://www.signum.se/
  7974.                       Cyclic Software
  7975.                       United States of America
  7976.                       http://www.cyclic.com/
  7977.                       info@cyclic.com
  7978.  
  7979.      If you got CVS through a distributor, such as an operating system vendor 
  7980.       or a vendor of freeware CD-ROMs, you may wish to see whether the 
  7981.       distributor provides support.  Often, they will provide no support or 
  7982.       minimal support, but this may vary from distributor to distributor. 
  7983.  
  7984.      If you have the skills and time to do so, you may wish to fix the bug 
  7985.       yourself.  If you wish to submit your fix for inclusion in future 
  7986.       releases of CVS, see the file HACKING in the CVS source distribution.  It 
  7987.       contains much more information on the process of submitting fixes. 
  7988.  
  7989.      There may be resources on the net which can help.  Two good places to 
  7990.       start are: 
  7991.  
  7992.                       http://www.cyclic.com
  7993.                       http://www.loria.fr/~molli/cvs-index.html
  7994.  
  7995.  If you are so inspired, increasing the information available on the net is 
  7996.  likely to be appreciated.  For example, before the standard CVS distribution 
  7997.  worked on Windows 95, there was a web page with some explanation and patches 
  7998.  for running CVS on Windows 95, and various people helped out by mentioning 
  7999.  this page on mailing lists or newsgroups when the subject came up. 
  8000.  
  8001.      It is also possible to report bugs to bug-cvs. Note that someone may or 
  8002.       may not want to do anything with your bug report---if you need a solution 
  8003.       consider one of the options mentioned above.  People probably do want to 
  8004.       hear about bugs which are particularly severe in consequences and/or easy 
  8005.       to fix, however.  You can also increase your odds by being as clear as 
  8006.       possible about the exact nature of the bug and any other relevant 
  8007.       information.  The way to report bugs is to send email to bug-cvs@gnu.org. 
  8008.       Note that submissions to bug-cvs may be distributed under the terms of 
  8009.       the GNU Public License, so if you don't like this, don't submit them. 
  8010.       There is usually no justification for sending mail directly to one of the 
  8011.       CVS maintainers rather than to bug-cvs; those maintainers who want to 
  8012.       hear about such bug reports read bug-cvs.  Also note that sending a bug 
  8013.       report to other mailing lists or newsgroups is not a substitute for 
  8014.       sending it to bug-cvs.  It is fine to discuss CVS bugs on whatever forum 
  8015.       you prefer, but there are not necessarily any maintainers reading bug 
  8016.       reports sent anywhere except bug-cvs. 
  8017.  
  8018.  People often ask if there is a list of known bugs or whether a particular bug 
  8019.  is a known one.  The file BUGS in the CVS source distribution is one list of 
  8020.  known bugs, but it doesn't necessarily try to be comprehensive.  Perhaps there 
  8021.  will never be a comprehensive, detailed list of known bugs. 
  8022.  
  8023.  
  8024. ΓòÉΓòÉΓòÉ 25. Index ΓòÉΓòÉΓòÉ
  8025.  
  8026.  !, in modules file                                Excluding directories 
  8027.  #cvs.lock, removing                               Several developers 
  8028.                                                    simultaneously attempting to 
  8029.                                                    run CVS 
  8030.  #cvs.lock, technical details                      CVS locks in the repository 
  8031.  #cvs.rfl, and backups                             Backing up a repository 
  8032.  #cvs.rfl, removing                                Several developers 
  8033.                                                    simultaneously attempting to 
  8034.                                                    run CVS 
  8035.  #cvs.rfl, technical details                       CVS locks in the repository 
  8036.  #cvs.tfl                                          CVS locks in the repository 
  8037.  #cvs.wfl, removing                                Several developers 
  8038.                                                    simultaneously attempting to 
  8039.                                                    run CVS 
  8040.  #cvs.wfl, technical details                       CVS locks in the repository 
  8041.  &, in modules file                                Ampersand modules 
  8042.  :ext:, setting up                                 Connecting with rsh 
  8043.  :ext:, troubleshooting                            Trouble making a connection 
  8044.                                                    to a CVS server 
  8045.  :gserver:, setting up                             Direct connection with 
  8046.                                                    GSSAPI 
  8047.  :kserver:, setting up                             Direct connection with 
  8048.                                                    kerberos 
  8049.  :local:, setting up                               The Repository 
  8050.  :pserver:, setting up                             Using the client with 
  8051.                                                    password authentication 
  8052.  :pserver:, troubleshooting                        Trouble making a connection 
  8053.                                                    to a CVS server 
  8054.  :server:, setting up                              Connecting with rsh 
  8055.  :server:, troubleshooting                         Trouble making a connection 
  8056.                                                    to a CVS server 
  8057.  ┬╖# files                                          update output 
  8058.  ┬╖bashrc, setting CVSROOT in                       Telling CVS where your 
  8059.                                                    repository is 
  8060.  ┬╖cshrc, setting CVSROOT in                        Telling CVS where your 
  8061.                                                    repository is 
  8062.  ┬╖profile, setting CVSROOT in                      Telling CVS where your 
  8063.                                                    repository is 
  8064.  ┬╖tcshrc, setting CVSROOT in                       Telling CVS where your 
  8065.                                                    repository is 
  8066.  -a, in modules file                               Alias modules 
  8067.  -d, in modules file                               Module options 
  8068.  -e, in modules file                               Module options 
  8069.  -i, in modules file                               Module options 
  8070.  -j (merging branches)                             Merging an entire branch 
  8071.  -k (keyword substitution)                         Substitution modes 
  8072.  -o, in modules file                               Module options 
  8073.  -s, in modules file                               Module options 
  8074.  -t, in modules file                               Module options 
  8075.  -u, in modules file                               Module options 
  8076.  .cvsrc file                                       Default options and the 
  8077.                                                    ~/.cvsrc file 
  8078.  /usr/local/cvsroot, as example repository         The Repository 
  8079.  <<<<<<<                                           Conflicts example 
  8080.  =======                                           Conflicts example 
  8081.  >>>>>>>                                           Conflicts example 
  8082.  abandoning work                                   How to edit a file which is 
  8083.                                                    being watched 
  8084.  Access a branch                                   Accessing branches 
  8085.  add (subcommand)                                  Adding files to a directory 
  8086.  Adding a tag                                      Tags--Symbolic revisions 
  8087.  Adding files                                      Adding files to a directory 
  8088.  Admin (subcommand)                                admin---Administration 
  8089.  Administrative files (intro)                      The administrative files 
  8090.  Administrative files (reference)                  Reference manual for 
  8091.                                                    Administrative files 
  8092.  Administrative files, editing them                Editing administrative files 
  8093.  Alias modules                                     Alias modules 
  8094.  ALL in commitinfo                                 Commitinfo 
  8095.  Ampersand modules                                 Ampersand modules 
  8096.  annotate (subcommand)                             Annotate command 
  8097.  Atomic transactions, lack of                      Several developers 
  8098.                                                    simultaneously attempting to 
  8099.                                                    run CVS 
  8100.  attic                                             The attic 
  8101.  authenticated client, using                       Using the client with 
  8102.                                                    password authentication 
  8103.  authenticating server, setting up                 Setting up the server for 
  8104.                                                    password authentication 
  8105.  authentication, stream                            Global options 
  8106.  Author keyword                                    Keyword List 
  8107.  Automatically ignored files                       Ignoring files via cvsignore 
  8108.  Avoiding editor invocation                        Common command options 
  8109.  Backing up, repository                            Backing up a repository 
  8110.  Base directory, in CVS directory                  How data is stored in the 
  8111.                                                    working directory 
  8112.  BASE, as reserved tag name                        Tags--Symbolic revisions 
  8113.  BASE, special tag                                 Common command options 
  8114.  Baserev file, in CVS directory                    How data is stored in the 
  8115.                                                    working directory 
  8116.  Baserev.tmp file, in CVS directory                How data is stored in the 
  8117.                                                    working directory 
  8118.  bill of materials                                 How your build system 
  8119.                                                    interacts with CVS 
  8120.  Binary files                                      Handling binary files 
  8121.  Branch merge example                              Merging an entire branch 
  8122.  Branch number                                     Revision numbers 
  8123.                                                    Branches and revisions 
  8124.  Branch, accessing                                 Accessing branches 
  8125.  Branch, check out                                 Accessing branches 
  8126.  Branch, creating a                                Creating a branch 
  8127.  Branch, identifying                               Accessing branches 
  8128.  Branch, retrieving                                Accessing branches 
  8129.  Branch, vendor-                                   Tracking third-party sources 
  8130.  Branches motivation                               What branches are good for 
  8131.  Branches, copying changes between                 Branching and merging 
  8132.  Branches, sticky                                  Accessing branches 
  8133.  Branching                                         Branching and merging 
  8134.  Bringing a file up to date                        Bringing a file up to date 
  8135.  Bugs in this manual or CVS                        Dealing with bugs in CVS or 
  8136.                                                    this manual 
  8137.  Bugs, reporting                                   Dealing with bugs in CVS or 
  8138.                                                    this manual 
  8139.  builds                                            How your build system 
  8140.                                                    interacts with CVS 
  8141.  Changes, copying between branches                 Branching and merging 
  8142.  Changing a log message                            admin options 
  8143.  Check out a branch                                Accessing branches 
  8144.  checked out copy, keeping                         Keeping a checked out copy 
  8145.  Checkin program                                   Module options 
  8146.  Checkin.prog file, in CVS directory               How data is stored in the 
  8147.                                                    working directory 
  8148.  Checking commits                                  Commitinfo 
  8149.  Checking out source                               Getting the source 
  8150.  Checkout (subcommand)                             checkout---Check out sources 
  8151.                                                    for editing 
  8152.  Checkout program                                  Module options 
  8153.  checkout, as term for getting ready to edit       How to edit a file which is 
  8154.                                                    being watched 
  8155.  Checkout, example                                 Getting the source 
  8156.  checkoutlist                                      How files are stored in the 
  8157.                                                    CVSROOT directory 
  8158.  choosing, reserved or unreserved checkouts        Choosing between reserved or 
  8159.                                                    unreserved checkouts 
  8160.  Cleaning up                                       Cleaning up 
  8161.  Client/Server Operation                           Remote repositories 
  8162.  Co (subcommand)                                   checkout---Check out sources 
  8163.                                                    for editing 
  8164.  Command reference                                 Quick reference to CVS 
  8165.                                                    commands 
  8166.  Command structure                                 Overall structure of CVS 
  8167.                                                    commands 
  8168.  comment leader                                    admin options 
  8169.  Commit (subcommand)                               commit---Check files into 
  8170.                                                    the repository 
  8171.  Commit files                                      The commit support files 
  8172.  Commit, when to                                   When to commit? 
  8173.  Commitinfo                                        Commitinfo 
  8174.  Committing changes                                Committing your changes 
  8175.  Common options                                    Common command options 
  8176.  Common syntax of info files                       The common syntax 
  8177.  compatibility, between CVS versions               Compatibility between CVS 
  8178.                                                    Versions 
  8179.  COMSPEC, environment variable                     All environment variables 
  8180.                                                    which affect CVS 
  8181.  config, in CVSROOT                                The CVSROOT/config 
  8182.                                                    configuration file 
  8183.  Conflict markers                                  Conflicts example 
  8184.  Conflict resolution                               Conflicts example 
  8185.  Conflicts (merge example)                         Conflicts example 
  8186.  Contributors (CVS program)                        What is CVS? 
  8187.  Contributors (manual)                             Credits 
  8188.  copying a repository                              Moving a repository 
  8189.  Copying changes                                   Branching and merging 
  8190.  Correcting a log message                          admin options 
  8191.  Creating a branch                                 Creating a branch 
  8192.  Creating a project                                Starting a project with CVS 
  8193.  Creating a repository                             Creating a repository 
  8194.  Credits (CVS program)                             What is CVS? 
  8195.  Credits (manual)                                  Credits 
  8196.  CVS 1.6, and watches                              Using watches with old 
  8197.                                                    versions of CVS 
  8198.  CVS command structure                             Overall structure of CVS 
  8199.                                                    commands 
  8200.  CVS directory, in repository                      The CVS directory in the 
  8201.                                                    repository 
  8202.  CVS directory, in working directory               How data is stored in the 
  8203.                                                    working directory 
  8204.  CVS passwd file                                   Setting up the server for 
  8205.                                                    password authentication 
  8206.  CVS, history of                                   What is CVS? 
  8207.  CVS, introduction to                              What is CVS? 
  8208.  CVS, versions of                                  Compatibility between CVS 
  8209.                                                    Versions 
  8210.  CVS/Base directory                                How data is stored in the 
  8211.                                                    working directory 
  8212.  CVS/Baserev file                                  How data is stored in the 
  8213.                                                    working directory 
  8214.  CVS/Baserev.tmp file                              How data is stored in the 
  8215.                                                    working directory 
  8216.  CVS/Checkin.prog file                             How data is stored in the 
  8217.                                                    working directory 
  8218.  CVS/Entries file                                  How data is stored in the 
  8219.                                                    working directory 
  8220.  CVS/Entries.Backup file                           How data is stored in the 
  8221.                                                    working directory 
  8222.  CVS/Entries.Log file                              How data is stored in the 
  8223.                                                    working directory 
  8224.  CVS/Entries.Static file                           How data is stored in the 
  8225.                                                    working directory 
  8226.  CVS/Notify file                                   How data is stored in the 
  8227.                                                    working directory 
  8228.  CVS/Notify.tmp file                               How data is stored in the 
  8229.                                                    working directory 
  8230.  CVS/Repository file                               How data is stored in the 
  8231.                                                    working directory 
  8232.  CVS/Root file                                     Telling CVS where your 
  8233.                                                    repository is 
  8234.  CVS/Tag file                                      How data is stored in the 
  8235.                                                    working directory 
  8236.  CVS/Template file                                 How data is stored in the 
  8237.                                                    working directory 
  8238.  CVS/Update.prog file                              How data is stored in the 
  8239.                                                    working directory 
  8240.  CVSEDITOR, environment variable                   Committing your changes 
  8241.  cvsignore (admin file), global                    Ignoring files via cvsignore 
  8242.  CVSIGNORE, environment variable                   All environment variables 
  8243.                                                    which affect CVS 
  8244.  CVSREAD, environment variable                     All environment variables 
  8245.                                                    which affect CVS 
  8246.  CVSREAD, overriding                               Global options 
  8247.  cvsroot                                           The Repository 
  8248.  CVSROOT (file)                                    Reference manual for 
  8249.                                                    Administrative files 
  8250.  CVSROOT, environment variable                     Telling CVS where your 
  8251.                                                    repository is 
  8252.  CVSROOT, module name                              The administrative files 
  8253.  CVSROOT, multiple repositories                    Multiple repositories 
  8254.  CVSROOT, overriding                               Global options 
  8255.  CVSROOT, storage of files                         How files are stored in the 
  8256.                                                    CVSROOT directory 
  8257.  CVSROOT/config                                    The CVSROOT/config 
  8258.                                                    configuration file 
  8259.  CVSUMASK, environment variable                    File permissions 
  8260.  cvswrappers (admin file)                          The cvswrappers file 
  8261.  CVSWRAPPERS, environment variable                 The cvswrappers file 
  8262.                                                    All environment variables 
  8263.                                                    which affect CVS 
  8264.  CVS_CLIENT_LOG, environment variable              All environment variables 
  8265.                                                    which affect CVS 
  8266.  CVS_CLIENT_PORT                                   Direct connection with 
  8267.                                                    kerberos 
  8268.  CVS_IGNORE_REMOTE_ROOT, environment variable      All environment variables 
  8269.                                                    which affect CVS 
  8270.  CVS_PASSFILE, environment variable                Using the client with 
  8271.                                                    password authentication 
  8272.  CVS_RCMD_PORT, environment variable               All environment variables 
  8273.                                                    which affect CVS 
  8274.  CVS_RSH, environment variable                     All environment variables 
  8275.                                                    which affect CVS 
  8276.  CVS_SERVER, environment variable                  Connecting with rsh 
  8277.  CVS_SERVER_SLEEP, environment variable            All environment variables 
  8278.                                                    which affect CVS 
  8279.  Cyclic Software                                   Dealing with bugs in CVS or 
  8280.                                                    this manual 
  8281.  Date keyword                                      Keyword List 
  8282.  Dates                                             Common command options 
  8283.  dead state                                        The attic 
  8284.  Decimal revision number                           Revision numbers 
  8285.  DEFAULT in commitinfo                             Commitinfo 
  8286.  DEFAULT in editinfo                               Editinfo 
  8287.  DEFAULT in verifymsg                              Verifying log messages 
  8288.  Defining a module                                 Defining the module 
  8289.  Defining modules (intro)                          The administrative files 
  8290.  Defining modules (reference manual)               The modules file 
  8291.  Deleting files                                    Removing files 
  8292.  Deleting revisions                                admin options 
  8293.  Deleting sticky tags                              Sticky tags 
  8294.  Descending directories                            Recursive behavior 
  8295.  device nodes                                      Special Files 
  8296.  Diff                                              Viewing differences 
  8297.  Diff (subcommand)                                 diff---Show differences 
  8298.                                                    between revisions 
  8299.  Differences, merging                              Merging differences between 
  8300.                                                    any two revisions 
  8301.  Directories, moving                               Moving and renaming 
  8302.                                                    directories 
  8303.  directories, removing                             Removing directories 
  8304.  Directory, descending                             Recursive behavior 
  8305.  Disjoint repositories                             Multiple repositories 
  8306.  Distributing log messages                         Loginfo 
  8307.  driver.c (merge example)                          Conflicts example 
  8308.  edit (subcommand)                                 How to edit a file which is 
  8309.                                                    being watched 
  8310.  editinfo (admin file)                             Editinfo 
  8311.  Editing administrative files                      Editing administrative files 
  8312.  Editing the modules file                          Defining the module 
  8313.  Editor, avoiding invocation of                    Common command options 
  8314.  EDITOR, environment variable                      Committing your changes 
  8315.  EDITOR, overriding                                Global options 
  8316.  Editor, specifying per module                     Editinfo 
  8317.  editors (subcommand)                              Information about who is 
  8318.                                                    watching and editing 
  8319.  emerge                                            Conflicts example 
  8320.  encryption                                        Global options 
  8321.  Entries file, in CVS directory                    How data is stored in the 
  8322.                                                    working directory 
  8323.  Entries.Backup file, in CVS directory             How data is stored in the 
  8324.                                                    working directory 
  8325.  Entries.Log file, in CVS directory                How data is stored in the 
  8326.                                                    working directory 
  8327.  Entries.Static file, in CVS directory             How data is stored in the 
  8328.                                                    working directory 
  8329.  Environment variables                             All environment variables 
  8330.                                                    which affect CVS 
  8331.  Errors, reporting                                 Dealing with bugs in CVS or 
  8332.                                                    this manual 
  8333.  Example of a work-session                         A sample session 
  8334.  Example of merge                                  Conflicts example 
  8335.  Example, branch merge                             Merging an entire branch 
  8336.  excluding directories, in modules file            Excluding directories 
  8337.  exit status, of commitinfo                        Commitinfo 
  8338.  exit status, of CVS                               CVS's exit status 
  8339.  exit status, of editor                            Partial list of error 
  8340.                                                    messages 
  8341.  exit status, of taginfo                           User-defined logging 
  8342.  exit status, of verifymsg                         Verifying log messages 
  8343.  Export (subcommand)                               export---Export sources from 
  8344.                                                    CVS, similar to checkout 
  8345.  Export program                                    Module options 
  8346.  Fetching source                                   Getting the source 
  8347.  File had conflicts on merge                       File status 
  8348.  File locking                                      Multiple developers 
  8349.  File permissions, general                         File permissions 
  8350.  File permissions, Windows-specific                File Permission issues 
  8351.                                                    specific to Windows 
  8352.  File status                                       File status 
  8353.  Files, moving                                     Moving and renaming files 
  8354.  Files, reference manual                           Reference manual for 
  8355.                                                    Administrative files 
  8356.  Fixing a log message                              admin options 
  8357.  Forcing a tag match                               Common command options 
  8358.  Form for log message                              Rcsinfo 
  8359.  Format of CVS commands                            Overall structure of CVS 
  8360.                                                    commands 
  8361.  Getting started                                   A sample session 
  8362.  Getting the source                                Getting the source 
  8363.  Global cvsignore                                  Ignoring files via cvsignore 
  8364.  Global options                                    Global options 
  8365.  Group                                             File permissions 
  8366.  GSSAPI                                            Direct connection with 
  8367.                                                    GSSAPI 
  8368.  hard links                                        Special Files 
  8369.  HEAD, as reserved tag name                        Tags--Symbolic revisions 
  8370.  HEAD, special tag                                 Common command options 
  8371.  Header keyword                                    Keyword List 
  8372.  History (subcommand)                              history---Show status of 
  8373.                                                    files and users 
  8374.  History browsing                                  History browsing 
  8375.  History file                                      The history file 
  8376.  History files                                     Where files are stored 
  8377.                                                    within the repository 
  8378.  History of CVS                                    What is CVS? 
  8379.  HOME, environment variable                        All environment variables 
  8380.                                                    which affect CVS 
  8381.  HOMEDRIVE, environment variable                   All environment variables 
  8382.                                                    which affect CVS 
  8383.  HOMEPATH, environment variable                    All environment variables 
  8384.                                                    which affect CVS 
  8385.  Id keyword                                        Keyword List 
  8386.  Ident (shell command)                             Using keywords 
  8387.  Identifying a branch                              Accessing branches 
  8388.  Identifying files                                 Keyword substitution 
  8389.  Ignored files                                     Ignoring files via cvsignore 
  8390.  Ignoring files                                    Ignoring files via cvsignore 
  8391.  Import (subcommand)                               import---Import sources into 
  8392.                                                    CVS, using vendor branches 
  8393.  Importing files                                   Creating a directory tree 
  8394.                                                    from a number of files 
  8395.  Importing files, from other version control systems Creating Files From Other 
  8396.                                                    Version Control Systems 
  8397.  Importing modules                                 Importing a module for the 
  8398.                                                    first time 
  8399.  Index                                             Index 
  8400.  Info files (syntax)                               The common syntax 
  8401.  Informing others                                  Informing others about 
  8402.                                                    commits 
  8403.  init (subcommand)                                 Creating a repository 
  8404.  installed images (VMS)                            File permissions 
  8405.  Introduction to CVS                               What is CVS? 
  8406.  Invoking CVS                                      Quick reference to CVS 
  8407.                                                    commands 
  8408.  Isolation                                         History browsing 
  8409.  Join                                              Merging an entire branch 
  8410.  keeping a checked out copy                        Keeping a checked out copy 
  8411.  kerberos                                          Direct connection with 
  8412.                                                    kerberos 
  8413.  Keyword expansion                                 Keyword substitution 
  8414.  Keyword List                                      Keyword List 
  8415.  Keyword substitution                              Keyword substitution 
  8416.  Kflag                                             Substitution modes 
  8417.  kinit                                             Direct connection with 
  8418.                                                    kerberos 
  8419.  Known bugs in this manual or CVS                  Dealing with bugs in CVS or 
  8420.                                                    this manual 
  8421.  Layout of repository                              The Repository 
  8422.  Left-hand options                                 Global options 
  8423.  Linear development                                Revision numbers 
  8424.  link, symbolic, importing                         import output 
  8425.  List, mailing list                                What is CVS? 
  8426.  Locally Added                                     File status 
  8427.  Locally Modified                                  File status 
  8428.  Locally Removed                                   File status 
  8429.  Locker keyword                                    Keyword List 
  8430.  Locking files                                     Multiple developers 
  8431.  locks, cvs, and backups                           Backing up a repository 
  8432.  locks, cvs, introduction                          Several developers 
  8433.                                                    simultaneously attempting to 
  8434.                                                    run CVS 
  8435.  locks, cvs, technical details                     CVS locks in the repository 
  8436.  Log (subcommand)                                  log---Print out log 
  8437.                                                    information for files 
  8438.  Log information, saving                           The history file 
  8439.  Log keyword                                       Keyword List 
  8440.  Log message entry                                 Committing your changes 
  8441.  Log message template                              Rcsinfo 
  8442.  Log message, correcting                           admin options 
  8443.  log message, verifying                            Verifying log messages 
  8444.  Log messages                                      Loginfo 
  8445.  Log messages, editing                             Editinfo 
  8446.  Login (subcommand)                                Using the client with 
  8447.                                                    password authentication 
  8448.  loginfo (admin file)                              Loginfo 
  8449.  Logout (subcommand)                               Using the client with 
  8450.                                                    password authentication 
  8451.  Mail, automatic mail on commit                    Informing others about 
  8452.                                                    commits 
  8453.  Mailing list                                      What is CVS? 
  8454.  Mailing log messages                              Loginfo 
  8455.  Main trunk and branches                           Branching and merging 
  8456.  make                                              How your build system 
  8457.                                                    interacts with CVS 
  8458.  Many repositories                                 Multiple repositories 
  8459.  Markers, conflict                                 Conflicts example 
  8460.  Merge, an example                                 Conflicts example 
  8461.  Merge, branch example                             Merging an entire branch 
  8462.  Merging                                           Branching and merging 
  8463.  Merging a branch                                  Merging an entire branch 
  8464.  Merging a file                                    Bringing a file up to date 
  8465.  Merging two revisions                             Merging differences between 
  8466.                                                    any two revisions 
  8467.  mkmodules                                         Partial list of error 
  8468.                                                    messages 
  8469.  Modifications, copying between branches           Branching and merging 
  8470.  Module status                                     Module options 
  8471.  Module, defining                                  Defining the module 
  8472.  Modules (admin file)                              The modules file 
  8473.  Modules file                                      The administrative files 
  8474.  Modules file, changing                            Defining the module 
  8475.  modules.db                                        How files are stored in the 
  8476.                                                    CVSROOT directory 
  8477.  modules.dir                                       How files are stored in the 
  8478.                                                    CVSROOT directory 
  8479.  modules.pag                                       How files are stored in the 
  8480.                                                    CVSROOT directory 
  8481.  Motivation for branches                           What branches are good for 
  8482.  moving a repository                               Moving a repository 
  8483.  Moving directories                                Moving and renaming 
  8484.                                                    directories 
  8485.  Moving files                                      Moving and renaming files 
  8486.  moving tags                                       tag options 
  8487.  Multiple developers                               Multiple developers 
  8488.  Multiple repositories                             Multiple repositories 
  8489.  Name keyword                                      Keyword List 
  8490.  Name, symbolic (tag)                              Tags--Symbolic revisions 
  8491.  Needs Checkout                                    File status 
  8492.  Needs Merge                                       File status 
  8493.  Needs Patch                                       File status 
  8494.  Newsgroups                                        What is CVS? 
  8495.  notify (admin file)                               Telling CVS to notify you 
  8496.  Notify file, in CVS directory                     How data is stored in the 
  8497.                                                    working directory 
  8498.  Notify.tmp file, in CVS directory                 How data is stored in the 
  8499.                                                    working directory 
  8500.  Number, branch                                    Revision numbers 
  8501.                                                    Branches and revisions 
  8502.  Number, revision-                                 Revision numbers 
  8503.  option defaults                                   Default options and the 
  8504.                                                    ~/.cvsrc file 
  8505.  Options, global                                   Global options 
  8506.  options, in modules file                          Module options 
  8507.  Outdating revisions                               admin options 
  8508.  Overlap                                           Bringing a file up to date 
  8509.  Overriding CVSREAD                                Global options 
  8510.  Overriding CVSROOT                                Global options 
  8511.  Overriding EDITOR                                 Global options 
  8512.  Overriding RCSBIN                                 Global options 
  8513.  Overriding TMPDIR                                 Global options 
  8514.  Overview                                          Overview 
  8515.  ownership, saving in CVS                          Special Files 
  8516.  Parallel repositories                             Multiple repositories 
  8517.  passwd (admin file)                               Setting up the server for 
  8518.                                                    password authentication 
  8519.  password client, using                            Using the client with 
  8520.                                                    password authentication 
  8521.  password server, setting up                       Setting up the server for 
  8522.                                                    password authentication 
  8523.  PATH, environment variable                        All environment variables 
  8524.                                                    which affect CVS 
  8525.  Per-directory sticky tags/dates                   How data is stored in the 
  8526.                                                    working directory 
  8527.  Per-module editor                                 Editinfo 
  8528.  permissions, general                              File permissions 
  8529.  permissions, saving in CVS                        Special Files 
  8530.  permissions, Windows-specific                     File Permission issues 
  8531.                                                    specific to Windows 
  8532.  Policy                                            When to commit? 
  8533.  Precommit checking                                Commitinfo 
  8534.  PreservePermissions, in CVSROOT/config            The CVSROOT/config 
  8535.                                                    configuration file 
  8536.  Pserver (subcommand)                              Setting up the server for 
  8537.                                                    password authentication 
  8538.  PVCS, importing files from                        Creating Files From Other 
  8539.                                                    Version Control Systems 
  8540.  RCS history files                                 Where files are stored 
  8541.                                                    within the repository 
  8542.  RCS revision numbers                              Tags--Symbolic revisions 
  8543.  RCS, importing files from                         Creating Files From Other 
  8544.                                                    Version Control Systems 
  8545.  RCS-style locking                                 Multiple developers 
  8546.  RCSBIN, in CVSROOT/config                         The CVSROOT/config 
  8547.                                                    configuration file 
  8548.  RCSBIN, overriding                                Global options 
  8549.  RCSfile keyword                                   Keyword List 
  8550.  rcsinfo (admin file)                              Rcsinfo 
  8551.  Rdiff (subcommand)                                rdiff---'patch' format diffs 
  8552.                                                    between releases 
  8553.  read-only files, and -r                           Global options 
  8554.  read-only files, and CVSREAD                      All environment variables 
  8555.                                                    which affect CVS 
  8556.  read-only files, and watches                      Telling CVS to watch certain 
  8557.                                                    files 
  8558.  read-only files, in repository                    File permissions 
  8559.  Read-only mode                                    Global options 
  8560.  read-only repository access                       Read-only repository access 
  8561.  readers (admin file)                              Read-only repository access 
  8562.  Recursive (directory descending)                  Recursive behavior 
  8563.  Reference manual (files)                          Reference manual for 
  8564.                                                    Administrative files 
  8565.  Reference manual for variables                    All environment variables 
  8566.                                                    which affect CVS 
  8567.  Reference, commands                               Quick reference to CVS 
  8568.                                                    commands 
  8569.  regular expression syntax                         The common syntax 
  8570.  Regular modules                                   Regular modules 
  8571.  Release (subcommand)                              release---Indicate that a 
  8572.                                                    Module is no longer in use 
  8573.  Releases, revisions and versions                  Versions, revisions and 
  8574.                                                    releases 
  8575.  Releasing your working copy                       Cleaning up 
  8576.  Remote repositories                               Remote repositories 
  8577.  Remove (subcommand)                               Removing files 
  8578.  Removing a change                                 Merging differences between 
  8579.                                                    any two revisions 
  8580.  removing directories                              Removing directories 
  8581.  Removing files                                    Removing files 
  8582.  Removing your working copy                        Cleaning up 
  8583.  Renaming directories                              Moving and renaming 
  8584.                                                    directories 
  8585.  Renaming files                                    Moving and renaming files 
  8586.  renaming tags                                     tag options 
  8587.  Replacing a log message                           admin options 
  8588.  Reporting bugs                                    Dealing with bugs in CVS or 
  8589.                                                    this manual 
  8590.  Repositories, multiple                            Multiple repositories 
  8591.  Repositories, remote                              Remote repositories 
  8592.  Repository (intro)                                The Repository 
  8593.  Repository file, in CVS directory                 How data is stored in the 
  8594.                                                    working directory 
  8595.  Repository, backing up                            Backing up a repository 
  8596.  Repository, example                               The Repository 
  8597.  Repository, how data is stored                    How data is stored in the 
  8598.                                                    repository 
  8599.  repository, moving                                Moving a repository 
  8600.  Repository, setting up                            Creating a repository 
  8601.  reserved checkouts                                Multiple developers 
  8602.  Resetting sticky tags                             Sticky tags 
  8603.  Resolving a conflict                              Conflicts example 
  8604.  Restoring old version of removed file             Sticky tags 
  8605.  Resurrecting old version of dead file             Sticky tags 
  8606.  Retrieve a branch                                 Accessing branches 
  8607.  Retrieving an old revision using tags             Tags--Symbolic revisions 
  8608.  reverting to repository version                   How to edit a file which is 
  8609.                                                    being watched 
  8610.  Revision keyword                                  Keyword List 
  8611.  Revision management                               Revision management 
  8612.  Revision numbers                                  Revision numbers 
  8613.  Revision numbers (branches)                       Branches and revisions 
  8614.  Revision tree                                     Revision numbers 
  8615.  Revision tree, making branches                    Branching and merging 
  8616.  Revisions, merging differences between            Merging differences between 
  8617.                                                    any two revisions 
  8618.  Revisions, versions and releases                  Versions, revisions and 
  8619.                                                    releases 
  8620.  Right-hand options                                Common command options 
  8621.  Root file, in CVS directory                       Telling CVS where your 
  8622.                                                    repository is 
  8623.  rsh                                               Connecting with rsh 
  8624.  Rtag (subcommand)                                 rtag---Add a symbolic tag to 
  8625.                                                    a module 
  8626.  rtag, creating a branch using                     Creating a branch 
  8627.  Saving space                                      admin options 
  8628.  SCCS, importing files from                        Creating Files From Other 
  8629.                                                    Version Control Systems 
  8630.  Security, file permissions in repository          File permissions 
  8631.  security, GSSAPI                                  Direct connection with 
  8632.                                                    GSSAPI 
  8633.  security, kerberos                                Direct connection with 
  8634.                                                    kerberos 
  8635.  security, of pserver                              Security considerations with 
  8636.                                                    password authentication 
  8637.  security, setuid                                  File permissions 
  8638.  server, CVS                                       Remote repositories 
  8639.  server, temporary directories                     Temporary directories for 
  8640.                                                    the server 
  8641.  setgid                                            File permissions 
  8642.  Setting up a repository                           Creating a repository 
  8643.  setuid                                            File permissions 
  8644.  Signum Support                                    Dealing with bugs in CVS or 
  8645.                                                    this manual 
  8646.  Source keyword                                    Keyword List 
  8647.  Source, getting CVS source                        What is CVS? 
  8648.  Source, getting from CVS                          Getting the source 
  8649.  special files                                     Special Files 
  8650.  Specifying dates                                  Common command options 
  8651.  Spreading information                             Informing others about 
  8652.                                                    commits 
  8653.  Starting a project with CVS                       Starting a project with CVS 
  8654.  State keyword                                     Keyword List 
  8655.  Status of a file                                  File status 
  8656.  Status of a module                                Module options 
  8657.  sticky date                                       Sticky tags 
  8658.  Sticky tags                                       Sticky tags 
  8659.  Sticky tags, resetting                            Sticky tags 
  8660.  Sticky tags/dates, per-directory                  How data is stored in the 
  8661.                                                    working directory 
  8662.  Storing log messages                              Loginfo 
  8663.  stream authentication                             Global options 
  8664.  Structure                                         Overall structure of CVS 
  8665.                                                    commands 
  8666.  Subdirectories                                    Recursive behavior 
  8667.  Support, getting CVS support                      Dealing with bugs in CVS or 
  8668.                                                    this manual 
  8669.  symbolic link, importing                          import output 
  8670.  symbolic links                                    Special Files 
  8671.  Symbolic name (tag)                               Tags--Symbolic revisions 
  8672.  Syntax of info files                              The common syntax 
  8673.  SystemAuth, in CVSROOT/config                     The CVSROOT/config 
  8674.                                                    configuration file 
  8675.  Tag (subcommand)                                  tag---Add a symbolic tag to 
  8676.                                                    checked out versions of 
  8677.                                                    files 
  8678.  Tag file, in CVS directory                        How data is stored in the 
  8679.                                                    working directory 
  8680.  Tag program                                       Module options 
  8681.  tag, command, introduction                        Tags--Symbolic revisions 
  8682.  tag, creating a branch using                      Creating a branch 
  8683.  tag, example                                      Tags--Symbolic revisions 
  8684.  Tag, retrieving old revisions                     Tags--Symbolic revisions 
  8685.  Tag, symbolic name                                Tags--Symbolic revisions 
  8686.  taginfo                                           User-defined logging 
  8687.  Tags                                              Tags--Symbolic revisions 
  8688.  tags, renaming                                    tag options 
  8689.  Tags, sticky                                      Sticky tags 
  8690.  tc, Trivial Compiler (example)                    A sample session 
  8691.  Team of developers                                Multiple developers 
  8692.  TEMP, environment variable                        All environment variables 
  8693.                                                    which affect CVS 
  8694.  Template file, in CVS directory                   How data is stored in the 
  8695.                                                    working directory 
  8696.  Template for log message                          Rcsinfo 
  8697.  temporary directories, and server                 Temporary directories for 
  8698.                                                    the server 
  8699.  temporary files, location of                      All environment variables 
  8700.                                                    which affect CVS 
  8701.  Third-party sources                               Tracking third-party sources 
  8702.  Time                                              Common command options 
  8703.  timezone, in input                                Common command options 
  8704.  timezone, in output                               log---Print out log 
  8705.                                                    information for files 
  8706.  TMP, environment variable                         All environment variables 
  8707.                                                    which affect CVS 
  8708.  TMPDIR, environment variable                      All environment variables 
  8709.                                                    which affect CVS 
  8710.  TMPDIR, overriding                                Global options 
  8711.  TopLevelAdmin, in CVSROOT/config                  The CVSROOT/config 
  8712.                                                    configuration file 
  8713.  Trace                                             Global options 
  8714.  Traceability                                      History browsing 
  8715.  Tracking sources                                  Tracking third-party sources 
  8716.  Transactions, atomic, lack of                     Several developers 
  8717.                                                    simultaneously attempting to 
  8718.                                                    run CVS 
  8719.  Trivial Compiler (example)                        A sample session 
  8720.  Typical repository                                The Repository 
  8721.  umask, for repository files                       File permissions 
  8722.  Undoing a change                                  Merging differences between 
  8723.                                                    any two revisions 
  8724.  unedit (subcommand)                               How to edit a file which is 
  8725.                                                    being watched 
  8726.  Unknown                                           File status 
  8727.  unreserved checkouts                              Multiple developers 
  8728.  Up-to-date                                        File status 
  8729.  Update (subcommand)                               update---Bring work tree in 
  8730.                                                    sync with repository 
  8731.  Update program                                    Module options 
  8732.  update, introduction                              Bringing a file up to date 
  8733.  update, to display file status                    File status 
  8734.  Update.prog file, in CVS directory                How data is stored in the 
  8735.                                                    working directory 
  8736.  Updating a file                                   Bringing a file up to date 
  8737.  user aliases                                      Setting up the server for 
  8738.                                                    password authentication 
  8739.  users (admin file)                                Telling CVS to notify you 
  8740.  Vendor                                            Tracking third-party sources 
  8741.  Vendor branch                                     Tracking third-party sources 
  8742.  verifymsg (admin file)                            Verifying log messages 
  8743.  versions, of CVS                                  Compatibility between CVS 
  8744.                                                    Versions 
  8745.  Versions, revisions and releases                  Versions, revisions and 
  8746.                                                    releases 
  8747.  Viewing differences                               Viewing differences 
  8748.  watch add (subcommand)                            Telling CVS to notify you 
  8749.  watch off (subcommand)                            Telling CVS to watch certain 
  8750.                                                    files 
  8751.  watch on (subcommand)                             Telling CVS to watch certain 
  8752.                                                    files 
  8753.  watch remove (subcommand)                         Telling CVS to notify you 
  8754.  watchers (subcommand)                             Information about who is 
  8755.                                                    watching and editing 
  8756.  Watches                                           Mechanisms to track who is 
  8757.                                                    editing files 
  8758.  Wdiff (import example)                            Importing a module for the 
  8759.                                                    first time 
  8760.  web pages, maintaining with CVS                   Keeping a checked out copy 
  8761.  What (shell command)                              Using keywords 
  8762.  What branches are good for                        What branches are good for 
  8763.  What is CVS not?                                  What is CVS not? 
  8764.  What is CVS?                                      What is CVS? 
  8765.  When to commit                                    When to commit? 
  8766.  Windows, and permissions                          File Permission issues 
  8767.                                                    specific to Windows 
  8768.  Work-session, example of                          A sample session 
  8769.  Working copy                                      Multiple developers 
  8770.  Working copy, removing                            Cleaning up 
  8771.  Wrappers                                          The cvswrappers file 
  8772.  writers (admin file)                              Read-only repository access 
  8773.  zone, time, in input                              Common command options 
  8774.  zone, time, in output                             log---Print out log 
  8775.                                                    information for files 
  8776.  __ files (VMS)                                    update output 
  8777.