home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / xwplascr.zip / XWPL0208.ZIP / cvs.txt < prev    next >
Text File  |  2002-03-06  |  13KB  |  305 lines
  1. Netlabs CVS README
  2. (W) Ulrich Möller, November 12, 1999
  3. Last updated March 6, 2002 by Ulrich Möller
  4.  
  5.  
  6. 0. CONTENTS OF THIS FILE
  7. ========================
  8.  
  9.     1. INTRODUCTION TO CVS
  10.     2. WHICH CVS VERSION TO USE
  11.     3. SETUP
  12.     4. CVS CONCEPTS
  13.     5. CHECKING OUT THE CODE
  14.  
  15.  
  16. 0. ABOUT THIS DOCUMENT
  17. ======================
  18.  
  19.     This is for people who would like to access the XWorkplace
  20.     source code. If you have never written a C program before,
  21.     you will probably not be interested in this document.
  22.  
  23.  
  24. 1. INTRODUCTION TO CVS
  25. ======================
  26.  
  27.     CVS stands for "Concurrent Versioning System". It is a tool
  28.     which allows several developers to work on the same source code
  29.     at the same time.
  30.  
  31.     For those of you that have never dealt with anything like this...
  32.     just imagine a word processor document on a shared network
  33.     directory that several people work on at the same time. There
  34.     has to be some coordination of all the changes going on and
  35.     checks whether the changes conflict with each other.
  36.  
  37.     CVS does exactly that, except that it can handle large directory
  38.     trees with many files of any type -- text or binary.
  39.  
  40.     The concept of a client/server CVS setup is that the server
  41.     maintains a "repository" with the entire source code, including
  42.     all changes that were ever made. Each developer then creates a
  43.     local copy of the sources on his hard disk. So each developer
  44.     can safely work on the local sources until he thinks that
  45.     everyone else should get the changes (once they're halfway
  46.     stable), and can then put the changes on the server, and all
  47.     other developers can then update their local copy.
  48.  
  49.     While your local copy will always be at a certain code/revision
  50.     level (and only updated from the server if you request this),
  51.     the server maintains all changes that were ever made. You can,
  52.     for example, even retrieve the sources in the state were in in
  53.     the middle of 1999, if you want.
  54.  
  55.     Maybe the nicest thing about CVS is that with text files, it can
  56.     merge code changes. CVS has GNU "diff" built in so even if two
  57.     people work on the same source file, CVS in most cases can
  58.     automatically keep the changes in sync. See "Terminology" below.
  59.  
  60.     Netlabs has set up a CVS server on which all the Netlabs projects
  61.     reside. This document should give you all the information about
  62.     how to access that repository.
  63.  
  64.  
  65. 2. WHICH CVS VERSION TO USE
  66. ===========================
  67.  
  68.     CVS is a Unix program that was ported to OS/2. At the time of
  69.     writing, there are three CVS versions on Hobbes. I strongly
  70.     recommend to use 1.10.6, which is the most bug-free of them all.
  71.     While 1.10 might still work OK, 1.10.7 causes tons of problems.
  72.     Do not use it.
  73.  
  74.  
  75. 3. SETUP
  76. ========
  77.  
  78.     You can use the Netlabs Open Source Archive Client (NOSAC)
  79.     instead of running CVS from the command line. However, I have
  80.     found the command line much more practical, so I am going to
  81.     explain the basics here. Please refer to the CVS documentation
  82.     for details.
  83.  
  84.     As with most Unix programs, CVS expects you to have a "home"
  85.     directory. If you don't have one, create an empty directory
  86.     somewhere and set the HOME environment variable to that directory.
  87.  
  88.     In any case, I strongly recommend to create a file in $(HOME)
  89.     called ".cvsrc" and add put a single line
  90.  
  91.         cvs -z9
  92.  
  93.     in there to enable maximum compression during transfers. This
  94.     greatly speeds up things if you have a slow internet connection.
  95.     Otherwise CVS will do all network transfers with uncompressed
  96.     data, which can be terribly slow.
  97.  
  98.     Secondly, the most practical way to use CVS is to have a common
  99.     parent directory for all code repositories (i.e. projects). So
  100.     create one (for example, "F:\cvs"), which will become the parent
  101.     directory for all CVS projects (e.g. "F:\cvs\xworkplace",
  102.     "F:\cvs\warpin", "F:\cvs\xwphelpers"). If you later check out
  103.     repositories from sources other than Netlabs (e.g. from
  104.     SourceForge), they can go into this root as well.
  105.  
  106.     Finally, CVS needs you to have a user name and a password. If you
  107.     don't have one yet, use "guest" and "readonly", which will give
  108.     you read-only access to all Netlabs projects. (Other servers will
  109.     have different conventions here.)
  110.  
  111.     Set the current project environment. This is done via another
  112.     environment variable, so for XWorkplace, set:
  113.  
  114.         CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/xworkplace
  115.  
  116.     For WarpIN, use:
  117.  
  118.         CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/warpin
  119.  
  120.     For the "XWorkplace helpers", which are needed by both XWorkplace
  121.     and WarpIN, use:
  122.  
  123.         CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/xwphelpers
  124.  
  125.     and so on. Currently, Netlabs holds over a dozen projects which
  126.     can all be retrieved that way.
  127.  
  128.     NOTE: The CVSROOT path was changed in February 2002 for all Netlabs
  129.     projects. From your old CVSROOT variables, simply remove the "e:"
  130.     before "/netlabs.cvs". You will need to run "cvs login" again to
  131.     have CVS pick up the change (see below).
  132.  
  133.     Create a local subdirectory in your CVS root directory with the
  134.     same name (e.g. ("F:\cvs\xworkplace"). Change to that directory.
  135.  
  136.     Set USER=guest in your environment. Fire up your internet connection.
  137.     To log onto a project, use the "cvs login" command. Enter "readonly"
  138.     when you are prompted for the password. (Note that you will need to
  139.     enter "cvs login" separately for each repository. CVS will then store
  140.     the data in $(HOME)\.cvspass so you only need to do this once per project.)
  141.  
  142.     You are now ready to download ("check out") a project. See section
  143.     5 below.
  144.  
  145.  
  146. 4. CVS TERMINOLOGY
  147. ==================
  148.  
  149.     The following terms should be known when working with CVS (or
  150.     even reading the documentation):
  151.  
  152.     -- "Repository" is the unit CVS uses for managing projects.
  153.        For example, "xworkplace", "warpin", and "xwphelpers" are
  154.        three repositories on the Netlabs CVS server. Repositories
  155.        are mirrored locally in a subdirectory of your CVS root
  156.        directory, if you followed the above setup.
  157.  
  158.        Repositories are usually equivalent to projects. However,
  159.        repositories are just a directory on the server and can be
  160.        created in any way. For example, we created the "xwphelpers"
  161.        repository for code that is shared between XWorkplace and
  162.        WarpIN.
  163.  
  164.     -- "Checkout": "Checking out" code means that you retrieve (or
  165.        update) a local copy of files in a repository. You can check
  166.        out an entire repository or single files from it.
  167.  
  168.        To check out code, use the "cvs checkout" command. Details
  169.        follow in the next section.
  170.  
  171.     -- "Commit": If you have write access to the CVS server (which
  172.        requires that you have been given a user name and password
  173.        by the Netlabs admin, Adrian Gschwend), you can change the
  174.        repository by "committing" your local copy back onto the
  175.        server. Once the code has been committed, all other developers
  176.        can check it out again and will have the updates.
  177.  
  178.        To commit code to the server, use the "cvs commit" command.
  179.        See the CVS reference for details. Again, this requires that
  180.        you have been granted write access by the server administrator.
  181.  
  182.        Usually, with most projects, only a limited number of people
  183.        have write access to the server, for obvious reasons. But
  184.        this is a "project policy" issue and not a CVS restriction.
  185.  
  186.     -- "Merge": This can happen if you have checked out your local
  187.        copy of a repository already and do another "checkout" later.
  188.  
  189.        If CVS then finds that a file has been changed on the server
  190.        and your local copy needs to be updated, it "merges" all
  191.        changes into the local copy. That is, it does not simply
  192.        overwrite the local copy with the new version on the server,
  193.        but will compare (diff) the two files and patch the local
  194.        copy! As a result, you will not lose changes you made to
  195.        your local copy when you check out updates.
  196.  
  197.        CVS has GNU "diff" built in for this, so this is pretty
  198.        powerful.
  199.  
  200.        This happens automatically if you do "cvs checkout" after
  201.        your initial checkout. Note that you can also use
  202.        "cvs update"; the difference is that "update" will not
  203.        retrieve new files, but only update existing local files.
  204.        See the CVS reference for details.
  205.  
  206.     -- "Conflicts": This happens if CVS cannot successfully merge
  207.        changes into your local copy. Most frequently, this occurs
  208.        when two developers have modified the same lines in the
  209.        same source file. Of course, CVS cannot resolve these
  210.        conflicts by itself, so it will put two versions into the
  211.        file marked with special characters. (With C files, this
  212.        will cause compilation to fail, which is intentional so
  213.        that you have to manually resolve the conflict.)
  214.  
  215.        See the CVS reference for details.
  216.  
  217.  
  218. 5. CHECKING OUT THE CODE
  219. ========================
  220.  
  221.     Change to the XWorkplace root directory (e.g. "F:\cvs\xworkplace")
  222.     set the XWorkplace environment as described above (HOME, USER,
  223.     CVSROOT), and log on if you haven't logged on yet.
  224.  
  225.     The command for getting source from the server is "cvs checkout".
  226.     With checkout, you need to specify the module to check out. For
  227.     the purpose of this explanation, we will consider a "module" a
  228.     directory name. Note that CVS normally operates on directories
  229.     recursively! So if you use
  230.  
  231.         cvs checkout .
  232.  
  233.     (mind the dot) from the XWorkplace root directory, this will
  234.     retrieve the entire code tree and create new local files if
  235.     they don't exist yet. This can take a while for bigger projects.
  236.     Again, use maximum compression (see section 3).
  237.  
  238.     "cvs checkout" allows you to specify file masks as well. For
  239.     example, if you type
  240.  
  241.         cvs checkout src/shared/*.c
  242.  
  243.     only those files are checked out. Mind the forward slashes.
  244.  
  245.     By contrast, "cvs update" only updates local files which have
  246.     been changed on the server. It does not create new files.
  247.     Since I frequently create new files on the server, using
  248.     "checkout" will probably be the better general choice.
  249.  
  250.     Note that to compile XWorkplace, you will also need the
  251.     "XWorkplace Helpers" code, which is in a separate repository
  252.     called "xwphelpers". So create a new empty project directory
  253.     (e.g. "F:\cvs\xwphelpers"), change CVSROOT to point to the
  254.     "xwphelpers" repository, change to the new directory, and
  255.     do a "cvs checkout ." again.
  256.  
  257.     You will see that CVS puts out lots of information about the
  258.     files that were worked on. A typical CVS output from "update"
  259.     or "checkout" looks like this:
  260.  
  261.         ? doc/progref.ipf
  262.         M makefile
  263.         M include/build.h
  264.         M include/filesys/program.h
  265.         M src/classes/xcenter.c
  266.  
  267.     I strongly recommend redirecting standard output when using
  268.     "cvs update" or "checkout" so you know what CVS has done,
  269.     since these lines scroll of the screen very quickly. You
  270.     can simply use "cvs checkout . > checkout.log". An even
  271.     better choice is "tee", another GNU program, which prints
  272.     the output to the screen and logs it in a file at the same
  273.     time.
  274.  
  275.     In each such line, the first letter tells you what CVS has
  276.     done to the file:
  277.  
  278.         ?: CVS does not know the file. It is in your local tree,
  279.            but not in the repository.
  280.            This happens if you have added files to your local copy
  281.            yourself.
  282.  
  283.         U: This is the most frequent one. It means that CVS has
  284.            "U"pdated a local file with a new copy from the server
  285.            and occurs during "checkout" or "update".
  286.  
  287.         P: Similar to "U", except that the server has only sent
  288.            a "P"atch instead of the entire file. The result isn't
  289.            any different from "U"; the file has been updated.
  290.  
  291.         M: This means that your local file was "M"odified before the
  292.            update. You get this no matter if the file was updated
  293.            (i.e. changes were merged successfully) or not.
  294.  
  295.         C: This happens if merge failed and a "C"onflict occured.
  296.            You need to manually edit all files which have been
  297.            marked with "C"; if they are C source files, they will
  298.            no longer compile.
  299.  
  300.         R: A local file has been removed because it is no longer
  301.            in the repository (i.e. has been removed by someone
  302.            with write access).
  303.  
  304.  
  305.