Knowledge base CVS — Concurrent Versions System

Manual

Creating a repository

  • Taken from Section 2.6 of CVS Manual
    • To create a repository, run the cvs init command. It will set up an empty repository in the cvs root ( <CVS root Directory> ) specified in the usual way.
      • cvs -d <CVS root Directory> init
    • NOTE:
      • cvs init is careful to never overwrite any existing files in the repository, so no harm is done if you run cvs init on an already set-up repository.
      • cvs init will enable history logging; if you don’t want that, remove the history file after running cvs init

Telling CVS where your repository is

    There are several ways to tell cvs where to find the repository. You can name the repository on the command line explicitly, with the -d (for "directory") option:
    cvs -d <CVS root Directory> checkout yoyodyne/tc
    Or you can set the $CVSROOT environment variable to an absolute path to the root of the repository, ‘          <CVS root Directory>          ’ in this example. To set $CVSROOT, csh and tcsh users should have this line in their ‘.cshrc’ or ‘.tcshrc’ files:
    setenv CVSROOT <CVS root Directory>
    sh and bash users should instead have these lines in their ‘.profile’ or ‘.bashrc’:
    CVSROOT= <CVS root Directory>
    export CVSROOT
    A repository specified with -d will override the $CVSROOT environment variable. Once you’ve checked a working copy out from the repository, it will remember where its repository is (the information is recorded in the ‘CVS/Root’ file in the working copy).
    The -d option and the ‘CVS/Root’ file both override the $CVSROOT environment variable. If -d option differs from ‘CVS/Root’, the former is used. Of course, for proper operation they should be two ways of referring to the same repository.

Creating a directory tree from a number of files

    When you begin using cvs, you will probably already have several projects that can be put under cvs control. In these cases the easiest way is to use the import command. An example is probably the easiest way to explain how to use it. If the files you want to install in cvs reside in ‘wdir‘, and you want them to appear in the repository as ‘$CVSROOT/yoyodyne/rdir‘, you can do this:
    $ cd wdir
    $ cvs import -m "Imported sources" yoyodyne/rdir yoyo start
    Unless you supply a log message with the ‘-m’ flag, cvs starts an editor and prompts for a message. The string ‘yoyo’ is a vendor tag, and ‘start’ is a release tag. They may fill no purpose in this context, but since cvs requires them they must be present.
    You can now verify that it worked, and remove your original source directory.
    $ cd ..
    $ cvs checkout yoyodyne/rdir # Explanation below
    $ diff -r wdir yoyodyne/rdir
    $ rm -r wdir
    Erasing the original sources is a good idea, to make sure that you do not accidentally edit them in wdir, bypassing cvs. Of course, it would be wise to make sure that you have a backup of the sources before you remove them.
    The checkout command can either take a module name as argument (as it has done in all previous examples) or a path name relative to $CVSROOT, as it did in the example above. It is a good idea to check that the permissions cvs sets on the directories inside $CVSROOT are reasonable, and that they belong to the proper groups.

    Ignoring files via cvsignore

      There are certain file names that frequently occur inside your working copy, but that you don’t want to put under cvs control. Examples are all the object files that you get while you compile your sources. Normally, when you run ‘cvs update’, it prints a line for each file it encounters that it doesn’t know about (see Section A.19.2 [update output], page 124).

      cvs has a list of files (or sh(1) file name patterns) that it should ignore while running update, import and release. This list is constructed in the following way.
      • The list is initialized to include certain file name patterns: names associated with cvs administration, or with other common source control systems; common names for patch files, object files, archive files, and editor backup files; and other names that are usually artifacts of assorted utilities. Currently, the default list of ignored file name patterns is:
            RCS SCCS CVS CVS.adm
            RCSLOG cvslog.*
            tags TAGS
            .make.state .nse_depinfo
            *~ #* .#* ,* _$* *$
            *.old *.bak *.BAK *.orig *.rej .del-*
            *.a *.olb *.o *.obj *.so *.exe
            *.Z *.elc *.ln
            core
      
      • The per-repository list in ‘$CVSROOT/CVSROOT/cvsignore’ is appended to the list, if that file exists.
      • The per-user list in ‘.cvsignore’ in your home directory is appended to the list, if it exists.
      • Any entries in the environment variable $CVSIGNORE is appended to the list.
      • Any ‘-I’ options given to cvs is appended.
      • As cvs traverses through your directories, the contents of any ‘.cvsignore’ will be appended to the list. The patterns found in ‘.cvsignore’ are only valid for the directory that contains them, not for any sub-directories.

      In any of the 5 places listed above, a single exclamation mark (‘!’) clears the ignore list. This can be used if you want to store any file which normally is ignored by cvs.

      Specifying ‘-I !’ to cvs import will import everything, which is generally what you want to do if you are importing files from a pristine distribution or any other source which is known to not contain any extraneous files. However, looking at the rules above you will see there is a fly in the ointment; if the distribution contains any ‘.cvsignore’ files, then the patterns from those files will be processed even if ‘-I !’ is specified. The only workaround is to remove the ‘.cvsignore’ files in order to do the import. Because this is awkward, in the future ‘-I !’ might be modified to override ‘.cvsignore’ files in each directory.

      Note that the syntax of the ignore files consists of a series of lines, each of which contains a space separated list of filenames. This offers no clean way to specify filenames which contain spaces, but you can use a workaround like ‘foo?bar’ to match a file named ‘foo bar’ (it also matches ‘fooxbar’ and the like). Also note that there is currently no way to specify comments.

Modules

The administrative files

    The directory ‘$CVSROOT/CVSROOT’ contains some administrative files. [...] The most important of these files is the ‘modules’ file. It defines all modules in the repository. This is a sample ‘modules’ file.
    CVSROOT CVSROOT
    modules CVSROOT modules
    cvs gnu/cvs
    rcs gnu/rcs
    diff gnu/diff
    tc yoyodyne/tc
    
    The ‘modules’ file is line oriented. In its simplest form each line contains the name of the module, whitespace, and the directory where the module resides. The directory is a path relative to $CVSROOT. The last four lines in the example above are examples of such lines.
    The line that defines the module called ‘modules’ uses features that are not explained here. See [[http://ftp.gnu.org/non-gnu/cvs/source/feature/1.12.9/cederqvist-1.12.9.pdf][Section C.1 [modules], page 139]], for a full explanation of all the available features.

    NOTE: Editing administrative files

    You edit the administrative files in the same way that you would edit any other module. Use ‘cvs checkout CVSROOT’ to get a working copy, edit it, and commit your changes in the normal way.
    It is possible to commit an erroneous administrative file. You can often fix the error and check in a new revision, but sometimes a particularly bad error in the administrative file makes it impossible to commit new revisions. If and when this happens, you can correct the problem by temporarily copying a corrected administrative file directly into the $CVSROOT/CVSROOT repository directory, then committing the same correction via a checkout of the ‘CVSROOT’ module. It is important that the correction also be made via the checked out copy, or the next checkout and commit to the CVSROOT module will overwrite the correction that was copied directly into the repository, possibly breaking things in such a way as to prevent commits again.

The module file

  • Taken from [[http://ftp.gnu.org/non-gnu/cvs/source/feature/1.12.9/cederqvist-1.12.9.pdf][Section C.1 [modules], page 139]]
    The ‘modules’ file records your definitions of names for collections of source code. cvs will use these definitions if you use cvs to update the modules file (use normal commands like add, commit, etc).
    The ‘modules’ file may contain blank lines and comments (lines beginning with ‘#’) as well as module definitions. Long lines can be continued on the next line by specifying a backslash (‘\’) as the last character on the line.
    There are three basic types of modules: alias modules, regular modules, and ampersand modules. The difference between them is the way that they map files in the repository to files in the working directory. In all of the following examples, the top-level repository contains a directory called ‘first-dir’, which contains two files, ‘file1’ and ‘file2’, and a directory ‘sdir’. ‘first-dir/sdir’ contains a file ‘sfile’.

    Alias modules

      Alias modules are the simplest kind of module:
      mname -a aliases...
      
      This represents the simplest way of defining a module mname. The ‘-a’ flags the definition as a simple alias: cvs will treat any use of mname (as a command argument) as if the list of names aliases had been specified instead. aliases may contain either other module names or paths. When you use paths in aliases, checkout creates all intermediate directories in the working directory, just as if the path had been specified explicitly in the cvs arguments.
      For example, if the modules file contains:
      amodule -a first-dir
      
      then the following two commands are equivalent:
      $ cvs co amodule
      $ cvs co first-dir
      and they each would provide output such as:
      cvs checkout: Updating first-dir
      U first-dir/file1
      U first-dir/file2
      cvs checkout: Updating first-dir/sdir
      U first-dir/sdir/sfile
      

    Regular modules

      mname [ options ] dir [ files... ]
      
      In the simplest case, this form of module definition reduces to ‘mname dir’. This defines all the files in directory dir as module mname. dir is a relative path (from $CVSROOT) to a directory of source in the source repository. In this case, on checkout, a single directory called mname is created as a working directory; no intermediate directory levels are used by default, even if dir was a path involving several directory levels.
      For example, if a module is defined by:
      regmodule first-dir
      
      then regmodule will contain the files from first-dir:
      $ cvs co regmodule
      cvs checkout: Updating regmodule
      U regmodule/file1
      U regmodule/file2
      cvs checkout: Updating regmodule/sdir
      U regmodule/sdir/sfile
      
      By explicitly specifying files in the module definition after dir, you can select particular files from directory dir. Here is an example:
      regfiles first-dir/sdir sfile
      
      With this definition, getting the regfiles module will create a single working directory ‘regfiles’ containing the file listed, which comes from a directory deeper in the cvs source repository:
      $ cvs co regfiles
      U regfiles/sfile
      

    Ampersand modules

      A module definition can refer to other modules by including ‘&module’ in its definition.
      mname [ options ] &module...
      
      Then getting the module creates a subdirectory for each such module, in the directory containing the module. For example, if modules contains
      ampermod &first-dir
      
      then a checkout will create an ampermod directory which contains a directory called firstdir, which in turns contains all the directories and files which live there. For example, the command
      $ cvs co ampermod
      will create the following files:
      ampermod/first-dir/file1
      ampermod/first-dir/file2
      ampermod/first-dir/sdir/sfile
      
      There is one quirk/bug: the messages that cvs prints omit the ‘ampermod’, and thus do not correctly display the location to which it is checking out the files:
      $ cvs co ampermod
      cvs checkout: Updating first-dir
      U first-dir/file1
      U first-dir/file2
      cvs checkout: Updating first-dir/sdir
      U first-dir/sdir/sfile
      
      Do not rely on this buggy behavior; it may get fixed in a future release of cvs.

    Excluding directories

      An alias module may exclude particular directories from other modules by using an exclamation mark (‘!’) before the name of each directory to be excluded.
      For example, if the modules file contains:
      exmodule -a !first-dir/sdir first-dir
      
      then checking out the module ‘exmodule’ will check out everything in ‘first-dir’ except any files in the subdirectory ‘first-dir/sdir’.

Troubleshooting

For troubleshooting have a look at the Appendix F Troubleshooting of the manual.

-- PeterZumbruch - 16 Jun 2008

-- PeterZumbruch - 16 Jun 2008
Topic revision: r2 - 2008-06-16, PeterZumbruch
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding GSI Wiki? Send feedback
Imprint (in German)
Privacy Policy (in German)