home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / info / cvs.info-2 < prev    next >
Encoding:
GNU Info File  |  1996-10-13  |  48.6 KB  |  1,257 lines
  1. This is Info file cvs.info, produced by Makeinfo-1.64 from the input
  2. file /ade-source/fsf/cvs/doc/cvs.texinfo.
  3.  
  4.    Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994
  5. Free Software Foundation, Inc.
  6.  
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.  
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided also
  13. that the section entitled "GNU General Public License" is included
  14. exactly as in the original, and provided that the entire resulting
  15. derived work is distributed under the terms of a permission notice
  16. identical to this one.
  17.  
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions, except that the section entitled "GNU General Public License"
  21. and this permission notice may be included in translations approved by
  22. the Free Software Foundation instead of in the original English.
  23.  
  24. 
  25. File: cvs.info,  Node: Setting up the files,  Next: Defining the module,  Up: Starting a new project
  26.  
  27. Setting up the files
  28. ====================
  29.  
  30.    The first step is to create the files inside the repository.  This
  31. can be done in a couple of different ways.
  32.  
  33. * Menu:
  34.  
  35. * From files::                  This method is useful with old projects
  36.                                 where files already exists.
  37. * From other version control systems::  Old projects where you want to
  38.                                         preserve history from another system.
  39. * From scratch::                Creating a directory tree from scratch.
  40.  
  41. 
  42. File: cvs.info,  Node: From files,  Next: From other version control systems,  Up: Setting up the files
  43.  
  44. Creating a directory tree from a number of files
  45. ------------------------------------------------
  46.  
  47.    When you begin using CVS, you will probably already have several
  48. projects that can be put under CVS control.  In these cases the easiest
  49. way is to use the `import' command.  An example is probably the easiest
  50. way to explain how to use it.  If the files you want to install in CVS
  51. reside in `WDIR', and you want them to appear in the repository as
  52. `$CVSROOT/yoyodyne/RDIR', you can do this:
  53.  
  54.      $ cd WDIR
  55.      $ cvs import -m "Imported sources" yoyodyne/RDIR yoyo start
  56.  
  57.    Unless you supply a log message with the `-m' flag, CVS starts an
  58. editor and prompts for a message.  The string `yoyo' is a "vendor tag",
  59. and `start' is a "release tag".  They may fill no purpose in this
  60. context, but since CVS requires them they must be present.  *Note
  61. Tracking sources::, for more information about them.
  62.  
  63.    You can now verify that it worked, and remove your original source
  64. directory.
  65.  
  66.      $ cd ..
  67.      $ mv DIR DIR.orig
  68.      $ cvs checkout yoyodyne/DIR       # Explanation below
  69.      $ ls -R yoyodyne
  70.      $ rm -r DIR.orig
  71.  
  72. Erasing the original sources is a good idea, to make sure that you do
  73. not accidentally edit them in DIR, bypassing CVS.  Of course, it would
  74. be wise to make sure that you have a backup of the sources before you
  75. remove them.
  76.  
  77.    The `checkout' command can either take a module name as argument (as
  78. it has done in all previous examples) or a path name relative to
  79. `$CVSROOT', as it did in the example above.
  80.  
  81.    It is a good idea to check that the permissions CVS sets on the
  82. directories inside `$CVSROOT' are reasonable, and that they belong to
  83. the proper groups.  *Note File permissions::.
  84.  
  85.    If some of the files you want to import are binary, you may want to
  86. use the wrappers features to specify which files are binary and which
  87. are not.  *Note Wrappers::.
  88.  
  89. 
  90. File: cvs.info,  Node: From other version control systems,  Next: From scratch,  Prev: From files,  Up: Setting up the files
  91.  
  92. Creating Files From Other Version Control Systems
  93. -------------------------------------------------
  94.  
  95.    If you have a project which you are maintaining with another version
  96. control system, such as RCS, you may wish to put the files from that
  97. project into CVS, and preserve the revision history of the files.
  98.  
  99. From RCS
  100.      If you have been using RCS, find the RCS files--usually a file
  101.      named `foo.c' will have its RCS file in `RCS/foo.c,v' (but it
  102.      could be other places; consult the RCS documentation for details).
  103.      Then create the appropriate directories in CVS if they do not
  104.      already exist.  Then copy the files into the appropriate
  105.      directories in the CVS repository (the name in the repository must
  106.      be the name of the source file with `,v' added; the files go
  107.      directly in the appopriate directory of the repository, not in an
  108.      `RCS' subdirectory).  This is one of the few times when it is a
  109.      good idea to access the CVS repository directly, rather than using
  110.      CVS commands.  Then you are ready to check out a new working
  111.      directory.
  112.  
  113.      The RCS file should not be locked when you move it into CVS; if it
  114.      is, CVS will have trouble letting you operate on it.
  115.  
  116. From another version control system
  117.      Many version control systems have the ability to export RCS files
  118.      in the standard format.  If yours does, export the RCS files and
  119.      then follow the above instructions.
  120.  
  121. From SCCS
  122.      There is a script in the `contrib' directory of the CVS source
  123.      distribution called `sccs2rcs' which converts SCCS files to RCS
  124.      files.  Note: you must run it on a machine which has both SCCS and
  125.      RCS installed, and like everything else in contrib it is
  126.      unsupported (your mileage may vary).
  127.  
  128. 
  129. File: cvs.info,  Node: From scratch,  Prev: From other version control systems,  Up: Setting up the files
  130.  
  131. Creating a directory tree from scratch
  132. --------------------------------------
  133.  
  134.    For a new project, the easiest thing to do is probably to create an
  135. empty directory structure, like this:
  136.  
  137.      $ mkdir tc
  138.      $ mkdir tc/man
  139.      $ mkdir tc/testing
  140.  
  141.    After that, you use the `import' command to create the corresponding
  142. (empty) directory structure inside the repository:
  143.  
  144.      $ cd tc
  145.      $ cvs import -m "Created directory structure" yoyodyne/DIR yoyo start
  146.  
  147.    Then, use `add' to add files (and new directories) as they appear.
  148.  
  149.    Check that the permissions CVS sets on the directories inside
  150. `$CVSROOT' are reasonable.
  151.  
  152. 
  153. File: cvs.info,  Node: Defining the module,  Prev: Setting up the files,  Up: Starting a new project
  154.  
  155. Defining the module
  156. ===================
  157.  
  158.    The next step is to define the module in the `modules' file.  This
  159. is not strictly necessary, but modules can be convenient in grouping
  160. together related files and directories.
  161.  
  162.    In simple cases these steps are sufficient to define a module.
  163.  
  164.   1. Get a working copy of the modules file.
  165.  
  166.           $ cvs checkout CVSROOT/modules
  167.           $ cd CVSROOT
  168.  
  169.   2. Edit the file and insert a line that defines the module.  *Note
  170.      Intro administrative files::, for an introduction.  *Note
  171.      modules::, for a full description of the modules file.  You can
  172.      use the following line to define the module `tc':
  173.  
  174.           tc   yoyodyne/tc
  175.  
  176.   3. Commit your changes to the modules file.
  177.  
  178.           $ cvs commit -m "Added the tc module." modules
  179.  
  180.   4. Release the modules module.
  181.  
  182.           $ cd ..
  183.           $ cvs release -d CVSROOT
  184.  
  185. 
  186. File: cvs.info,  Node: Multiple developers,  Next: Branches,  Prev: Starting a new project,  Up: Top
  187.  
  188. Multiple developers
  189. *******************
  190.  
  191.    When more than one person works on a software project things often
  192. get complicated.  Often, two people try to edit the same file
  193. simultaneously.  One solution, known as "file locking" or "reserved
  194. checkouts", is to allow only one person to edit each file at a time.
  195. This is the only solution with some version control systems, including
  196. RCS and SCCS.  CVS doesn't have a very nice implementation of reserved
  197. checkouts (yet) but there are ways to get it working (for example, see
  198. the `cvs admin -l' command in *Note admin options::).  It also may be
  199. possible to use the watches features described below, together with
  200. suitable procedures (not enforced by software), to avoid having two
  201. people edit at the same time.
  202.  
  203.    The default model with CVS is known as "unreserved checkouts".  In
  204. this model, developers can edit their own "working copy" of a file
  205. simultaneously.  The first person that commits his changes has no
  206. automatic way of knowing that another has started to edit it.  Others
  207. will get an error message when they try to commit the file.  They must
  208. then use CVS commands to bring their working copy up to date with the
  209. repository revision.  This process is almost automatic.
  210.  
  211.    CVS also supports mechanisms which facilitate various kinds of
  212. communcation, without actually enforcing rules like reserved checkouts
  213. do.
  214.  
  215.    The rest of this chapter describes how these various models work,
  216. and some of the issues involved in choosing between them.
  217.  
  218. * Menu:
  219.  
  220. * File status::                 A file can be in several states
  221. * Updating a file::             Bringing a file up-to-date
  222. * Conflicts example::           An informative example
  223. * Informing others::            To cooperate you must inform
  224. * Concurrency::                 Simultaneous repository access
  225. * Watches::                     Mechanisms to track who is editing files
  226. * Choosing a model::            Reserved or unreserved checkouts?
  227.  
  228. 
  229. File: cvs.info,  Node: File status,  Next: Updating a file,  Up: Multiple developers
  230.  
  231. File status
  232. ===========
  233.  
  234.    Based on what operations you have performed on a checked out file,
  235. and what operations others have performed to that file in the
  236. repository, one can classify a file in a number of states.  The states,
  237. as reported by the `status' command, are:
  238.  
  239. Up-to-date
  240.      The file is identical with the latest revision in the repository
  241.      for the branch in use.
  242.  
  243. Locally Modified
  244.      You have edited the file, and not yet committed your changes.
  245.  
  246. Locally Added
  247.      You have added the file with `add', and not yet committed your
  248.      changes.
  249.  
  250. Locally Removed
  251.      You have removed the file with `remove', and not yet committed
  252.      your changes.
  253.  
  254. Needs Checkout
  255.      Someone else has committed a newer revision to the repository.
  256.      The name is slightly misleading; you will ordinarily use `update'
  257.      rather than `checkout' to get that newer revision.
  258.  
  259. Needs Patch
  260.      Like Needs Checkout, but the CVS server will send a patch rather
  261.      than the entire file.  Sending a patch or sending an entire file
  262.      accomplishes the same thing.
  263.  
  264. Needs Merge
  265.      Someone else has committed a newer revision to the repository, and
  266.      you have also made modifications to the file.
  267.  
  268. Unresolved Conflict
  269.      This is like Locally Modified, except that a previous `update'
  270.      command gave a conflict.  You need to resolve the conflict as
  271.      described in *Note Conflicts example::.
  272.  
  273. Unknown
  274.      CVS doesn't know anything about this file.  For example, you have
  275.      created a new file and have not run `add'.
  276.  
  277.    To help clarify the file status, `status' also reports the `Working
  278. revision' which is the revision that the file in the working directory
  279. derives from, and the `Repository revision' which is the latest
  280. revision in the repository for the branch in use.
  281.  
  282.    For information on the options to `status', see *Note status::.  For
  283. information on its `Sticky tag' and `Sticky date' output, see *Note
  284. Sticky tags::.  For information on its `Sticky options' output, see the
  285. `-k' option in *Note update options::.
  286.  
  287. 
  288. File: cvs.info,  Node: Updating a file,  Next: Conflicts example,  Prev: File status,  Up: Multiple developers
  289.  
  290. Bringing a file up to date
  291. ==========================
  292.  
  293.    When you want to update or merge a file, use the `update' command.
  294. For files that are not up to date this is roughly equivalent to a
  295. `checkout' command: the newest revision of the file is extracted from
  296. the repository and put in your working copy of the module.
  297.  
  298.    Your modifications to a file are never lost when you use `update'.
  299. If no newer revision exists, running `update' has no effect.  If you
  300. have edited the file, and a newer revision is available, CVS will merge
  301. all changes into your working copy.
  302.  
  303.    For instance, imagine that you checked out revision 1.4 and started
  304. editing it.  In the meantime someone else committed revision 1.5, and
  305. shortly after that revision 1.6.  If you run `update' on the file now,
  306. CVS will incorporate all changes between revision 1.4 and 1.6 into your
  307. file.
  308.  
  309.    If any of the changes between 1.4 and 1.6 were made too close to any
  310. of the changes you have made, an "overlap" occurs.  In such cases a
  311. warning is printed, and the resulting file includes both versions of
  312. the lines that overlap, delimited by special markers.  *Note update::,
  313. for a complete description of the `update' command.
  314.  
  315. 
  316. File: cvs.info,  Node: Conflicts example,  Next: Informing others,  Prev: Updating a file,  Up: Multiple developers
  317.  
  318. Conflicts example
  319. =================
  320.  
  321.    Suppose revision 1.4 of `driver.c' contains this:
  322.  
  323.      #include <stdio.h>
  324.      
  325.      void main()
  326.      {
  327.          parse();
  328.          if (nerr == 0)
  329.              gencode();
  330.          else
  331.              fprintf(stderr, "No code generated.\n");
  332.          exit(nerr == 0 ? 0 : 1);
  333.      }
  334.  
  335. Revision 1.6 of `driver.c' contains this:
  336.  
  337.      #include <stdio.h>
  338.      
  339.      int main(int argc,
  340.               char **argv)
  341.      {
  342.          parse();
  343.          if (argc != 1)
  344.          {
  345.              fprintf(stderr, "tc: No args expected.\n");
  346.              exit(1);
  347.          }
  348.          if (nerr == 0)
  349.              gencode();
  350.          else
  351.              fprintf(stderr, "No code generated.\n");
  352.          exit(!!nerr);
  353.      }
  354.  
  355. Your working copy of `driver.c', based on revision 1.4, contains this
  356. before you run `cvs update':
  357.  
  358.      #include <stdlib.h>
  359.      #include <stdio.h>
  360.      
  361.      void main()
  362.      {
  363.          init_scanner();
  364.          parse();
  365.          if (nerr == 0)
  366.              gencode();
  367.          else
  368.              fprintf(stderr, "No code generated.\n");
  369.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  370.      }
  371.  
  372. You run `cvs update':
  373.  
  374.      $ cvs update driver.c
  375.      RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  376.      retrieving revision 1.4
  377.      retrieving revision 1.6
  378.      Merging differences between 1.4 and 1.6 into driver.c
  379.      rcsmerge warning: overlaps during merge
  380.      cvs update: conflicts found in driver.c
  381.      C driver.c
  382.  
  383. CVS tells you that there were some conflicts.  Your original working
  384. file is saved unmodified in `.#driver.c.1.4'.  The new version of
  385. `driver.c' contains this:
  386.  
  387.      #include <stdlib.h>
  388.      #include <stdio.h>
  389.      
  390.      int main(int argc,
  391.               char **argv)
  392.      {
  393.          init_scanner();
  394.          parse();
  395.          if (argc != 1)
  396.          {
  397.              fprintf(stderr, "tc: No args expected.\n");
  398.              exit(1);
  399.          }
  400.          if (nerr == 0)
  401.              gencode();
  402.          else
  403.              fprintf(stderr, "No code generated.\n");
  404.       <<<<<<< driver.c
  405.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  406.       =======
  407.          exit(!!nerr);
  408.       >>>>>>> 1.6
  409.      }
  410.  
  411. Note how all non-overlapping modifications are incorporated in your
  412. working copy, and that the overlapping section is clearly marked with
  413. `<<<<<<<', `=======' and `>>>>>>>'.
  414.  
  415.    You resolve the conflict by editing the file, removing the markers
  416. and the erroneous line.  Suppose you end up with this file:
  417.      #include <stdlib.h>
  418.      #include <stdio.h>
  419.      
  420.      int main(int argc,
  421.               char **argv)
  422.      {
  423.          init_scanner();
  424.          parse();
  425.          if (argc != 1)
  426.          {
  427.              fprintf(stderr, "tc: No args expected.\n");
  428.              exit(1);
  429.          }
  430.          if (nerr == 0)
  431.              gencode();
  432.          else
  433.              fprintf(stderr, "No code generated.\n");
  434.          exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
  435.      }
  436.  
  437. You can now go ahead and commit this as revision 1.7.
  438.  
  439.      $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
  440.      Checking in driver.c;
  441.      /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
  442.      new revision: 1.7; previous revision: 1.6
  443.      done
  444.  
  445.    For your protection, CVS will refuse to check in a file if a
  446. conflict occurred and you have not resolved the conflict.  Currently to
  447. resolve a conflict, you must change the timestamp on the file, and must
  448. also insure that the file contains no conflict markers.  If your file
  449. legitimately contains conflict markers (that is, occurrences of
  450. `>>>>>>> ' at the start of a line that don't mark a conflict), then CVS
  451. has trouble handling this and you need to start hacking on the
  452. `CVS/Entries' file or other such workarounds.
  453.  
  454.    If you use release 1.04 or later of pcl-cvs (a GNU Emacs front-end
  455. for CVS) you can use an Emacs package called emerge to help you resolve
  456. conflicts.  See the documentation for pcl-cvs.
  457.  
  458. 
  459. File: cvs.info,  Node: Informing others,  Next: Concurrency,  Prev: Conflicts example,  Up: Multiple developers
  460.  
  461. Informing others about commits
  462. ==============================
  463.  
  464.    It is often useful to inform others when you commit a new revision
  465. of a file.  The `-i' option of the `modules' file, or the `loginfo'
  466. file, can be used to automate this process.  *Note modules::.  *Note
  467. loginfo::.  You can use these features of CVS to, for instance,
  468. instruct CVS to mail a message to all developers, or post a message to
  469. a local newsgroup.
  470.  
  471. 
  472. File: cvs.info,  Node: Concurrency,  Next: Watches,  Prev: Informing others,  Up: Multiple developers
  473.  
  474. Several developers simultaneously attempting to run CVS
  475. =======================================================
  476.  
  477.    If several developers try to run CVS at the same time, one may get
  478. the following message:
  479.  
  480.      [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
  481.  
  482.    CVS will try again every 30 seconds, and either continue with the
  483. operation or print the message again, if it still needs to wait.  If a
  484. lock seems to stick around for an undue amount of time, find the person
  485. holding the lock and ask them about the cvs command they are running.
  486. If they aren't running a cvs command, look for and remove files
  487. starting with `#cvs.tfl', `#cvs.rfl', or `#cvs.wfl' from the repository.
  488.  
  489.    Note that these locks are to protect CVS's internal data structures
  490. and have no relationship to the word "lock" in the sense used by
  491. RCS--which refers to reserved checkouts (*note Multiple developers::.).
  492.  
  493.    Any number of people can be reading from a given repository at a
  494. time; only when someone is writing do the locks prevent other people
  495. from reading or writing.
  496.  
  497.    One might hope for the following property
  498.  
  499.      If someone commits some changes in one cvs command,
  500.      then an update by someone else will either get all the
  501.      changes, or none of them.
  502.  
  503.    but CVS does *not* have this property.  For example, given the files
  504.  
  505.      a/one.c
  506.      a/two.c
  507.      b/three.c
  508.      b/four.c
  509.  
  510.    if someone runs
  511.  
  512.      cvs ci a/two.c b/three.c
  513.  
  514.    and someone else runs `cvs update' at the same time, the person
  515. running `update' might get only the change to `b/three.c' and not the
  516. change to `a/two.c'.
  517.  
  518. 
  519. File: cvs.info,  Node: Watches,  Next: Choosing a model,  Prev: Concurrency,  Up: Multiple developers
  520.  
  521. Mechanisms to track who is editing files
  522. ========================================
  523.  
  524.    For many groups, use of CVS in its default mode is perfectly
  525. satisfactory.  Users may sometimes go to check in a modification only
  526. to find that another modification has intervened, but they deal with it
  527. and proceed with their check in.  Other groups prefer to be able to
  528. know who is editing what files, so that if two people try to edit the
  529. same file they can choose to talk about who is doing what when rather
  530. than be surprised at check in time.  The features in this section allow
  531. such coordination, while retaining the ability of two developers to
  532. edit the same file at the same time.
  533.  
  534.    For maximum benefit developers should use `cvs edit' (not `chmod')
  535. to make files read-write to edit them, and `cvs release' (not `rm') to
  536. discard a working directory which is no longer in use, but CVS is not
  537. able to enforce this behavior.
  538.  
  539. * Menu:
  540.  
  541. * Setting a watch::             Telling CVS to watch certain files
  542. * Getting Notified::            Telling CVS to notify you
  543. * Editing files::               How to edit a file which is being watched
  544. * Watch information::           Information about who is watching and editing
  545. * Watches Compatibility::       Watches interact poorly with CVS 1.6 or earlier
  546.  
  547. 
  548. File: cvs.info,  Node: Setting a watch,  Next: Getting Notified,  Up: Watches
  549.  
  550. Telling CVS to watch certain files
  551. ----------------------------------
  552.  
  553.    To enable the watch features, you first specify that certain files
  554. are to be watched.
  555.  
  556.  - Command: cvs watch on [`-l'] FILES ...
  557.      Specify that developers should run `cvs edit' before editing
  558.      FILES.  CVS will create working copies of FILES read-only, to
  559.      remind developers to run the `cvs edit' command before working on
  560.      them.
  561.  
  562.      If FILES includes the name of a directory, CVS arranges to watch
  563.      all files added to the corresponding repository directory, and
  564.      sets a default for files added in the future; this allows the user
  565.      to set notification policies on a per-directory basis.  The
  566.      contents of the directory are processed recursively, unless the
  567.      `-l' option is given.
  568.  
  569.      If FILES is omitted, it defaults to the current directory.
  570.  
  571.  
  572.  - Command: cvs watch off [`-l'] FILES ...
  573.      Do not provide notification about work on FILES.  CVS will create
  574.      working copies of FILES read-write.
  575.  
  576.      The FILES and `-l' arguments are processed as for `cvs watch on'.
  577.  
  578.  
  579. 
  580. File: cvs.info,  Node: Getting Notified,  Next: Editing files,  Prev: Setting a watch,  Up: Watches
  581.  
  582. Telling CVS to notify you
  583. -------------------------
  584.  
  585.    You can tell CVS that you want to receive notifications about
  586. various actions taken on a file.  You can do this without using `cvs
  587. watch on' for the file, but generally you will want to use `cvs watch
  588. on', so that developers use the `cvs edit' command.
  589.  
  590.  - Command: cvs watch add [`-a' ACTION] [`-l'] FILES ...
  591.      Add the current user to the list of people to receive notification
  592.      of work done on FILES.
  593.  
  594.      The `-a' option specifies what kinds of events CVS should notify
  595.      the user about.  ACTION is one of the following:
  596.  
  597.     `edit'
  598.           Another user has applied the `cvs edit' command (described
  599.           below) to a file.
  600.  
  601.     `unedit'
  602.           Another user has applied the `cvs unedit' command (described
  603.           below) or the `cvs release' command to a file, or has deleted
  604.           the file and allowed `cvs update' to recreate it.
  605.  
  606.     `commit'
  607.           Another user has committed changes to a file.
  608.  
  609.     `all'
  610.           All of the above.
  611.  
  612.     `none'
  613.           None of the above.  (This is useful with `cvs edit',
  614.           described below.)
  615.  
  616.      The `-a' option may appear more than once, or not at all.  If
  617.      omitted, the action defaults to `all'.
  618.  
  619.      The FILES and `-l' option are processed as for the `cvs watch'
  620.      commands.
  621.  
  622.  
  623.  - Command: cvs watch remove [`-a' ACTION] [`-l'] FILES ...
  624.      Remove a notification request established using `cvs watch add';
  625.      the arguments are the same.  If the `-a' option is present, only
  626.      watches for the specified actions are removed.
  627.  
  628.  
  629.    When the conditions exist for notification, CVS calls the `notify'
  630. administrative file.  Edit `notify' as one edits the other
  631. administrative files (*note Intro administrative files::.).  This file
  632. follows the usual conventions for administrative files (*note
  633. syntax::.), where each line is a regular expression followed by a
  634. command to execute.  The command should contain a single ocurrence of
  635. `%s' which will be replaced by the user to notify; the rest of the
  636. information regarding the notification will be supplied to the command
  637. on standard input.  The standard thing to put in the `notify' file is
  638. the single line:
  639.  
  640.      ALL mail %s -s \"CVS notification\"
  641.  
  642.    This causes users to be notified by electronic mail.
  643.  
  644.    Note that if you set this up in the straightforward way, users
  645. receive notifications on the server machine.  One could of course write
  646. a `notify' script which directed notifications elsewhere, but to make
  647. this easy, CVS allows you to associate a notification address for each
  648. user.  To do so create a file `users' in `CVSROOT' with a line for each
  649. user in the format USER:VALUE.  Then instead of passing the name of the
  650. user to be notified to `notify', CVS will pass the VALUE (normally an
  651. email address on some other machine).
  652.  
  653. 
  654. File: cvs.info,  Node: Editing files,  Next: Watch information,  Prev: Getting Notified,  Up: Watches
  655.  
  656. How to edit a file which is being watched
  657. -----------------------------------------
  658.  
  659.    Since a file which is being watched is checked out read-only, you
  660. cannot simply edit it.  To make it read-write, and inform others that
  661. you are planning to edit it, use the `cvs edit' command.  Some systems
  662. call this a "checkout", but CVS uses that term for obtaining a copy of
  663. the sources (*note Getting the source::.), an operation which those
  664. systems call a "get" or a "fetch".
  665.  
  666.  - Command: cvs edit [OPTIONS] FILES ...
  667.      Prepare to edit the working files FILES.  CVS makes the FILES
  668.      read-write, and notifies users who have requested `edit'
  669.      notification for any of FILES.
  670.  
  671.      The `cvs edit' command accepts the same OPTIONS as the `cvs watch
  672.      add' command, and establishes a temporary watch for the user on
  673.      FILES; CVS will remove the watch when FILES are `unedit'ed or
  674.      `commit'ted.  If the user does not wish to receive notifications,
  675.      she should specify `-a none'.
  676.  
  677.      The FILES and `-l' option are processed as for the `cvs watch'
  678.      commands.
  679.  
  680.  
  681.    Normally when you are done with a set of changes, you use the `cvs
  682. commit' command, which checks in your changes and returns the watched
  683. files to their usual read-only state.  But if you instead decide to
  684. abandon your changes, or not to make any changes, you can use the `cvs
  685. unedit' command.
  686.  
  687.  - Command: cvs unedit [`-l'] FILES ...
  688.      Abandon work on the working files FILES, and revert them to the
  689.      repository versions on which they are based.  CVS makes those
  690.      FILES read-only for which users have requested notification using
  691.      `cvs watch on'.  CVS notifies users who have requested `unedit'
  692.      notification for any of FILES.
  693.  
  694.      The FILES and `-l' option are processed as for the `cvs watch'
  695.      commands.
  696.  
  697.      If watches are not in use, the `unedit' command probably does not
  698.      work, and the way to revert to the repository version is to remove
  699.      the file and then use `cvs update' to get a new copy.  The meaning
  700.      is not precisely the same; removing and updating may also bring in
  701.      some changes which have been made in the repository since the last
  702.      time you updated.
  703.  
  704.    When using client/server CVS, you can use the `cvs edit' and `cvs
  705. unedit' commands even if CVS is unable to succesfully communicate with
  706. the server; the notifications will be sent upon the next successful CVS
  707. command.
  708.  
  709. 
  710. File: cvs.info,  Node: Watch information,  Next: Watches Compatibility,  Prev: Editing files,  Up: Watches
  711.  
  712. Information about who is watching and editing
  713. ---------------------------------------------
  714.  
  715.  - Command: cvs watchers [`-l'] FILES ...
  716.      List the users currently watching changes to FILES.  The report
  717.      includes the files being watched, and the mail address of each
  718.      watcher.
  719.  
  720.      The FILES and `-l' arguments are processed as for the `cvs watch'
  721.      commands.
  722.  
  723.  
  724.  - Command: cvs editors [`-l'] FILES ...
  725.      List the users currently working on FILES.  The report includes
  726.      the mail address of each user, the time when the user began
  727.      working with the file, and the host and path of the working
  728.      directory containing the file.
  729.  
  730.      The FILES and `-l' arguments are processed as for the `cvs watch'
  731.      commands.
  732.  
  733.  
  734. 
  735. File: cvs.info,  Node: Watches Compatibility,  Prev: Watch information,  Up: Watches
  736.  
  737. Using watches with old versions of CVS
  738. --------------------------------------
  739.  
  740.    If you use the watch features on a repository, it creates `CVS'
  741. directories in the repository and stores the information about watches
  742. in that directory.  If you attempt to use CVS 1.6 or earlier with the
  743. repository, you get an error message such as
  744.  
  745.      cvs update: cannot open CVS/Entries for reading: No such file or directory
  746.  
  747.    and your operation will likely be aborted.  To use the watch
  748. features, you must upgrade all copies of CVS which use that repository
  749. in local or server mode.  If you cannot upgrade, use the `watch off' and
  750. `watch remove' commands to remove all watches, and that will restore
  751. the repository to a state which CVS 1.6 can cope with.
  752.  
  753. 
  754. File: cvs.info,  Node: Choosing a model,  Prev: Watches,  Up: Multiple developers
  755.  
  756. Choosing between reserved or unreserved checkouts
  757. =================================================
  758.  
  759.    Reserved and unreserved checkouts each have pros and cons.  Let it
  760. be said that a lot of this is a matter of opinion or what works given
  761. different groups' working styles, but here is an attempt to briefly
  762. describe the issues.  There are many ways to organize a team of
  763. developers.  CVS does not try to enforce a certain organization.  It is
  764. a tool that can be used in several ways.
  765.  
  766.    Reserved checkouts can be very counter-productive.  If two persons
  767. want to edit different parts of a file, there may be no reason to
  768. prevent either of them from doing so.  Also, it is common for someone
  769. to take out a lock on a file, because they are planning to edit it, but
  770. then forget to release the lock.
  771.  
  772.    People, especially people who are familiar with reserved checkouts,
  773. often wonder how often conflicts occur if unreserved checkouts are
  774. used, and how difficult they are to resolve.  The experience with many
  775. groups is that they occur rarely and usually are relatively
  776. straightforward to resolve.
  777.  
  778.    The rarity of serious conflicts may be surprising, until one realizes
  779. that they occur only when two developers disagree on the proper design
  780. for a given section of code; such a disagreement suggests that the team
  781. has not been communicating properly in the first place.  In order to
  782. collaborate under *any* source management regimen, developers must
  783. agree on the general design of the system; given this agreement,
  784. overlapping changes are usually straightforward to merge.
  785.  
  786.    In some cases unreserved checkouts are clearly inappropriate.  If no
  787. merge tool exists for the kind of file you are managing (for example
  788. word processor files or files edited by Computer Aided Design
  789. programs), and it is not desirable to change to a program which uses a
  790. mergeable data format, then resolving conflicts is going to be
  791. unpleasant enough that you generally will be better off to simply avoid
  792. the conflicts instead, by using reserved checkouts.
  793.  
  794.    The watches features described above in *Note Watches:: can be
  795. considered to be an intermediate model between reserved checkouts and
  796. unreserved checkouts.  When you go to edit a file, it is possible to
  797. find out who else is editing it.  And rather than having the system
  798. simply forbid both people editing the file, it can tell you what the
  799. situation is and let you figure out whether it is a problem in that
  800. particular case or not.  Therefore, for some groups it can be
  801. considered the best of both the reserved checkout and unreserved
  802. checkout worlds.
  803.  
  804. 
  805. File: cvs.info,  Node: Branches,  Next: Merging,  Prev: Multiple developers,  Up: Top
  806.  
  807. Branches
  808. ********
  809.  
  810.    So far, all revisions shown in this manual have been on the "main
  811. trunk" of the revision tree, i.e., all revision numbers have been of
  812. the form X.Y.  One useful feature, especially when maintaining several
  813. releases of a software product at once, is the ability to make branches
  814. on the revision tree.  "Tags", symbolic names for revisions, will also
  815. be introduced in this chapter.
  816.  
  817. * Menu:
  818.  
  819. * Tags::                        Tags-Symbolic revisions
  820. * Branches motivation::         What branches are good for
  821. * Creating a branch::           Creating a branch
  822. * Sticky tags::                 Sticky tags
  823.  
  824. 
  825. File: cvs.info,  Node: Tags,  Next: Branches motivation,  Up: Branches
  826.  
  827. Tags-Symbolic revisions
  828. =======================
  829.  
  830.    The revision numbers live a life of their own.  They need not have
  831. anything at all to do with the release numbers of your software
  832. product.  Depending on how you use CVS the revision numbers might
  833. change several times between two releases.  As an example, some of the
  834. source files that make up RCS 5.6 have the following revision numbers:
  835.  
  836.      ci.c            5.21
  837.      co.c            5.9
  838.      ident.c         5.3
  839.      rcs.c           5.12
  840.      rcsbase.h       5.11
  841.      rcsdiff.c       5.10
  842.      rcsedit.c       5.11
  843.      rcsfcmp.c       5.9
  844.      rcsgen.c        5.10
  845.      rcslex.c        5.11
  846.      rcsmap.c        5.2
  847.      rcsutil.c       5.10
  848.  
  849.    You can use the `tag' command to give a symbolic name to a certain
  850. revision of a file.  You can use the `-v' flag to the `status' command
  851. to see all tags that a file has, and which revision numbers they
  852. represent.  Tag names can contain uppercase and lowercase letters,
  853. digits, `-', and `_'.  The two tag names `BASE' and `HEAD' are reserved
  854. for use by CVS.  It is expected that future names which are special to
  855. CVS will contain characters such as `%' or `=', rather than being named
  856. analogously to `BASE' and `HEAD', to avoid conflicts with actual tag
  857. names.
  858.  
  859.    The following example shows how you can add a tag to a file.  The
  860. commands must be issued inside your working copy of the module.  That
  861. is, you should issue the command in the directory where `backend.c'
  862. resides.
  863.  
  864.      $ cvs tag release-0-4 backend.c
  865.      T backend.c
  866.      $ cvs status -v backend.c
  867.      ===================================================================
  868.      File: backend.c         Status: Up-to-date
  869.      
  870.          Version:            1.4     Tue Dec  1 14:39:01 1992
  871.          RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
  872.          Sticky Tag:         (none)
  873.          Sticky Date:        (none)
  874.          Sticky Options:     (none)
  875.      
  876.          Existing Tags:
  877.              release-0-4                     (revision: 1.4)
  878.  
  879.    There is seldom reason to tag a file in isolation.  A more common
  880. use is to tag all the files that constitute a module with the same tag
  881. at strategic points in the development life-cycle, such as when a
  882. release is made.
  883.  
  884.      $ cvs tag release-1-0 .
  885.      cvs tag: Tagging .
  886.      T Makefile
  887.      T backend.c
  888.      T driver.c
  889.      T frontend.c
  890.      T parser.c
  891.  
  892.    (When you give CVS a directory as argument, it generally applies the
  893. operation to all the files in that directory, and (recursively), to any
  894. subdirectories that it may contain.  *Note Recursive behavior::.)
  895.  
  896.    The `checkout' command has a flag, `-r', that lets you check out a
  897. certain revision of a module.  This flag makes it easy to retrieve the
  898. sources that make up release 1.0 of the module `tc' at any time in the
  899. future:
  900.  
  901.      $ cvs checkout -r release-1-0 tc
  902.  
  903. This is useful, for instance, if someone claims that there is a bug in
  904. that release, but you cannot find the bug in the current working copy.
  905.  
  906.    You can also check out a module as it was at any given date.  *Note
  907. checkout options::.
  908.  
  909.    When you tag more than one file with the same tag you can think
  910. about the tag as "a curve drawn through a matrix of filename vs.
  911. revision number."  Say we have 5 files with the following revisions:
  912.  
  913.              file1   file2   file3   file4   file5
  914.      
  915.              1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
  916.              1.2*-   1.2     1.2    -1.2*-
  917.              1.3  \- 1.3*-   1.3   / 1.3
  918.              1.4          \  1.4  /  1.4
  919.                            \-1.5*-   1.5
  920.                              1.6
  921.  
  922.    At some time in the past, the `*' versions were tagged.  You can
  923. think of the tag as a handle attached to the curve drawn through the
  924. tagged revisions.  When you pull on the handle, you get all the tagged
  925. revisions.  Another way to look at it is that you "sight" through a set
  926. of revisions that is "flat" along the tagged revisions, like this:
  927.  
  928.              file1   file2   file3   file4   file5
  929.      
  930.                              1.1
  931.                              1.2
  932.                      1.1     1.3                       _
  933.              1.1     1.2     1.4     1.1              /
  934.              1.2*----1.3*----1.5*----1.2*----1.1     (--- <--- Look here
  935.              1.3             1.6     1.3              \_
  936.              1.4                     1.4
  937.                                      1.5
  938.  
  939. 
  940. File: cvs.info,  Node: Branches motivation,  Next: Creating a branch,  Prev: Tags,  Up: Branches
  941.  
  942. What branches are good for
  943. ==========================
  944.  
  945.    Suppose that release 1.0 of tc has been made.  You are continuing to
  946. develop tc, planning to create release 1.1 in a couple of months.
  947. After a while your customers start to complain about a fatal bug.  You
  948. check out release 1.0 (*note Tags::.) and find the bug (which turns out
  949. to have a trivial fix).  However, the current revision of the sources
  950. are in a state of flux and are not expected to be stable for at least
  951. another month.  There is no way to make a bugfix release based on the
  952. newest sources.
  953.  
  954.    The thing to do in a situation like this is to create a "branch" on
  955. the revision trees for all the files that make up release 1.0 of tc.
  956. You can then make modifications to the branch without disturbing the
  957. main trunk.  When the modifications are finished you can select to
  958. either incorporate them on the main trunk, or leave them on the branch.
  959.  
  960. 
  961. File: cvs.info,  Node: Creating a branch,  Next: Sticky tags,  Prev: Branches motivation,  Up: Branches
  962.  
  963. Creating a branch
  964. =================
  965.  
  966.    The `rtag' command can be used to create a branch.  The `rtag'
  967. command is much like `tag', but it does not require that you have a
  968. working copy of the module.  *Note rtag::.  (You can also use the `tag'
  969. command; *note tag::.).
  970.  
  971.      $ cvs rtag -b -r release-1-0 release-1-0-patches tc
  972.  
  973.    The `-b' flag makes `rtag' create a branch (rather than just a
  974. symbolic revision name).  `-r release-1-0' says that this branch should
  975. be rooted at the node (in the revision tree) that corresponds to the tag
  976. `release-1-0'.  Note that the numeric revision number that matches
  977. `release-1-0' will probably be different from file to file.  The name
  978. of the new branch is `release-1-0-patches', and the module affected is
  979. `tc'.
  980.  
  981.    To fix the problem in release 1.0, you need a working copy of the
  982. branch you just created.
  983.  
  984.      $ cvs checkout -r release-1-0-patches tc
  985.      $ cvs status -v driver.c backend.c
  986.      ===================================================================
  987.      File: driver.c          Status: Up-to-date
  988.      
  989.          Version:            1.7     Sat Dec  5 18:25:54 1992
  990.          RCS Version:        1.7     /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  991.          Sticky Tag:         release-1-0-patches (branch: 1.7.2)
  992.          Sticky Date:        (none)
  993.          Sticky Options:     (none)
  994.      
  995.          Existing Tags:
  996.              release-1-0-patches             (branch: 1.7.2)
  997.              release-1-0                     (revision: 1.7)
  998.      
  999.      ===================================================================
  1000.      File: backend.c         Status: Up-to-date
  1001.      
  1002.          Version:            1.4     Tue Dec  1 14:39:01 1992
  1003.          RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
  1004.          Sticky Tag:         release-1-0-patches (branch: 1.4.2)
  1005.          Sticky Date:        (none)
  1006.          Sticky Options:     (none)
  1007.      
  1008.          Existing Tags:
  1009.              release-1-0-patches             (branch: 1.4.2)
  1010.              release-1-0                     (revision: 1.4)
  1011.              release-0-4                     (revision: 1.4)
  1012.  
  1013.    As the output from the `status' command shows the branch number is
  1014. created by adding a digit at the tail of the revision number it is
  1015. based on.  (If `release-1-0' corresponds to revision 1.4, the branch's
  1016. revision number will be 1.4.2.  For obscure reasons CVS always gives
  1017. branches even numbers, starting at 2.  *Note Revision numbers::.).
  1018.  
  1019. 
  1020. File: cvs.info,  Node: Sticky tags,  Prev: Creating a branch,  Up: Branches
  1021.  
  1022. Sticky tags
  1023. ===========
  1024.  
  1025.    The `-r release-1-0-patches' flag that was given to `checkout' in
  1026. the previous example is "sticky", that is, it will apply to subsequent
  1027. commands in this directory.  If you commit any modifications, they are
  1028. committed on the branch.  You can later merge the modifications into
  1029. the main trunk.  *Note Merging::.
  1030.  
  1031.    You can use the `status' command to see what sticky tags or dates
  1032. are set:
  1033.  
  1034.      $ vi driver.c   # Fix the bugs
  1035.      $ cvs commit -m "Fixed initialization bug" driver.c
  1036.      Checking in driver.c;
  1037.      /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
  1038.      new revision: 1.7.2.1; previous revision: 1.7
  1039.      done
  1040.      $ cvs status -v driver.c
  1041.      ===================================================================
  1042.      File: driver.c          Status: Up-to-date
  1043.      
  1044.          Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
  1045.          RCS Version:        1.7.2.1 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
  1046.          Sticky Tag:         release-1-0-patches (branch: 1.7.2)
  1047.          Sticky Date:        (none)
  1048.          Sticky Options:     (none)
  1049.      
  1050.          Existing Tags:
  1051.              release-1-0-patches             (branch: 1.7.2)
  1052.              release-1-0                     (revision: 1.7)
  1053.  
  1054.    The sticky tags will remain on your working files until you delete
  1055. them with `cvs update -A'.  The `-A' option retrieves the version of
  1056. the file from the head of the trunk, and forgets any sticky tags,
  1057. dates, or options.
  1058.  
  1059.    Sticky tags are not just for branches.  For example, suppose that
  1060. you want to avoid updating your working directory, to isolate yourself
  1061. from possibly destabilizing changes other people are making.  You can,
  1062. of course, just refrain from running `cvs update'.  But if you want to
  1063. avoid updating only a portion of a larger tree, then sticky tags can
  1064. help.  If you check out a certain revision (such as 1.4) it will become
  1065. sticky.  Subsequent `cvs update' will not retrieve the latest revision
  1066. until you reset the tag with `cvs update -A'.  Likewise, use of the
  1067. `-D' option to `update' or `checkout' sets a "sticky date", which,
  1068. similarly, causes that date to be used for future retrievals.
  1069.  
  1070.    Many times you will want to retrieve an old version of a file
  1071. without setting a sticky tag.  The way to do that is with the `-p'
  1072. option to `checkout' or `update', which sends the contents of the file
  1073. to standard output.  For example, suppose you have a file named `file1'
  1074. which existed as revision 1.1, and you then removed it (thus adding a
  1075. dead revision 1.2).  Now suppose you want to add it again, with the same
  1076. contents it had previously.  Here is how to do it:
  1077.  
  1078.      $ cvs update -p -r 1.1 file1 >file1
  1079.      ===================================================================
  1080.      Checking out file1
  1081.      RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
  1082.      VERS: 1.1
  1083.      ***************
  1084.      $ cvs add file1
  1085.      cvs add: re-adding file file1 (in place of dead revision 1.2)
  1086.      cvs add: use 'cvs commit' to add this file permanently
  1087.      $ cvs commit -m test
  1088.      Checking in file1;
  1089.      /tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
  1090.      new revision: 1.3; previous revision: 1.2
  1091.      done
  1092.      $
  1093.  
  1094. 
  1095. File: cvs.info,  Node: Merging,  Next: Recursive behavior,  Prev: Branches,  Up: Top
  1096.  
  1097. Merging
  1098. *******
  1099.  
  1100.    You can include the changes made between any two revisions into your
  1101. working copy, by "merging".  You can then commit that revision, and
  1102. thus effectively copy the changes onto another branch.
  1103.  
  1104. * Menu:
  1105.  
  1106. * Merging a branch::            Merging an entire branch
  1107. * Merging more than once::      Merging from a branch several times
  1108. * Merging two revisions::       Merging differences between two revisions
  1109. * Merging adds and removals::   What if files are added or removed?
  1110.  
  1111. 
  1112. File: cvs.info,  Node: Merging a branch,  Next: Merging more than once,  Up: Merging
  1113.  
  1114. Merging an entire branch
  1115. ========================
  1116.  
  1117.    You can merge changes made on a branch into your working copy by
  1118. giving the `-j BRANCH' flag to the `update' command.  With one `-j
  1119. BRANCH' option it merges the changes made between the point where the
  1120. branch forked and newest revision on that branch (into your working
  1121. copy).
  1122.  
  1123.    The `-j' stands for "join".
  1124.  
  1125.    Consider this revision tree:
  1126.  
  1127.      +-----+    +-----+    +-----+    +-----+
  1128.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
  1129.      +-----+    +-----+    +-----+    +-----+
  1130.                      !
  1131.                      !
  1132.                      !   +---------+    +---------+
  1133.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  1134.                          +---------+    +---------+
  1135.  
  1136. The branch 1.2.2 has been given the tag (symbolic name) `R1fix'.  The
  1137. following example assumes that the module `mod' contains only one file,
  1138. `m.c'.
  1139.  
  1140.      $ cvs checkout mod               # Retrieve the latest revision, 1.4
  1141.      
  1142.      $ cvs update -j R1fix m.c        # Merge all changes made on the branch,
  1143.                                       # i.e. the changes between revision 1.2
  1144.                                       # and 1.2.2.2, into your working copy
  1145.                                       # of the file.
  1146.      
  1147.      $ cvs commit -m "Included R1fix" # Create revision 1.5.
  1148.  
  1149.    A conflict can result from a merge operation.  If that happens, you
  1150. should resolve it before committing the new revision.  *Note Conflicts
  1151. example::.
  1152.  
  1153.    The `checkout' command also supports the `-j BRANCH' flag.  The same
  1154. effect as above could be achieved with this:
  1155.  
  1156.      $ cvs checkout -j R1fix mod
  1157.      $ cvs commit -m "Included R1fix"
  1158.  
  1159. 
  1160. File: cvs.info,  Node: Merging more than once,  Next: Merging two revisions,  Prev: Merging a branch,  Up: Merging
  1161.  
  1162. Merging from a branch several times
  1163. ===================================
  1164.  
  1165.    Continuing our example, the revision tree now looks like this:
  1166.  
  1167.      +-----+    +-----+    +-----+    +-----+    +-----+
  1168.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
  1169.      +-----+    +-----+    +-----+    +-----+    +-----+
  1170.                      !                           *
  1171.                      !                          *
  1172.                      !   +---------+    +---------+
  1173.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
  1174.                          +---------+    +---------+
  1175.  
  1176.    where the starred line represents the merge from the `R1fix' branch
  1177. to the main trunk, as just discussed.
  1178.  
  1179.    Now suppose that development continues on the `R1fix' branch:
  1180.  
  1181.      +-----+    +-----+    +-----+    +-----+    +-----+
  1182.      ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
  1183.      +-----+    +-----+    +-----+    +-----+    +-----+
  1184.                      !                           *
  1185.                      !                          *
  1186.                      !   +---------+    +---------+    +---------+
  1187.      Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
  1188.                          +---------+    +---------+    +---------+
  1189.  
  1190.    and then you want to merge those new changes onto the main trunk.
  1191. If you just use the `cvs update -j R1fix m.c' command again, CVS will
  1192. attempt to merge again the changes which you have already merged, which
  1193. can have undesirable side effects.
  1194.  
  1195.    So instead you need to specify that you only want to merge the
  1196. changes on the branch which have not yet been merged into the trunk.
  1197. To do that you specify two `-j' options, and CVS merges the changes from
  1198. the first revision to the second revision.  For example, in this case
  1199. the simplest way would be
  1200.  
  1201.      cvs update -j 1.2.2.2 -j R1fix m.c    # Merge changes from 1.2.2.2 to the
  1202.                                            # head of the R1fix branch
  1203.  
  1204.    The problem with this is that you need to specify the 1.2.2.2
  1205. revision manually.  A slightly better approach might be to use the date
  1206. the last merge was done:
  1207.  
  1208.      cvs update -j R1fix:yesterday -j R1fix m.c
  1209.  
  1210.    Better yet, tag the R1fix branch after every merge into the trunk,
  1211. and then use that tag for subsequent merges:
  1212.  
  1213.      cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
  1214.  
  1215. 
  1216. File: cvs.info,  Node: Merging two revisions,  Next: Merging adds and removals,  Prev: Merging more than once,  Up: Merging
  1217.  
  1218. Merging differences between any two revisions
  1219. =============================================
  1220.  
  1221.    With two `-j REVISION' flags, the `update' (and `checkout') command
  1222. can merge the differences between any two revisions into your working
  1223. file.
  1224.  
  1225.      $ cvs update -j 1.5 -j 1.3 backend.c
  1226.  
  1227. will *remove* all changes made between revision 1.3 and 1.5.  Note the
  1228. order of the revisions!
  1229.  
  1230.    If you try to use this option when operating on multiple files,
  1231. remember that the numeric revisions will probably be very different
  1232. between the various files that make up a module.  You almost always use
  1233. symbolic tags rather than revision numbers when operating on multiple
  1234. files.
  1235.  
  1236. 
  1237. File: cvs.info,  Node: Merging adds and removals,  Prev: Merging two revisions,  Up: Merging
  1238.  
  1239. Merging can add or remove files
  1240. ===============================
  1241.  
  1242.    If the changes which you are merging involve removing or adding some
  1243. files, `update -j' will reflect such additions or removals.
  1244.  
  1245.    For example:
  1246.      cvs update -A
  1247.      touch a b c
  1248.      cvs add a b c ; cvs ci -m "added" a b c
  1249.      cvs tag -b branchtag
  1250.      cvs update -r branchtag
  1251.      touch d ; cvs add d
  1252.      rm a ; cvs rm a
  1253.      cvs ci -m "added d, removed a"
  1254.      cvs update -A
  1255.      cvs update -jbranchtag
  1256.  
  1257.