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