This is Info file cvs.info, produced by Makeinfo-1.63 from the input file ./cvs.texinfo. Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" and this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.  File: cvs.info, Node: Top, Next: Preface, Up: (dir) This info manual describes how to use and administer CVS version 1.8.1. * Menu: * Preface:: About this manual * What is CVS?:: What is CVS? * Basic concepts:: Basic concepts of revision management * A sample session:: A tour of basic CVS usage * Repository:: Where all your sources are stored * Starting a new project:: Starting a project with CVS * Multiple developers:: How CVS helps a group of developers * Branches:: Parallel development explained * Merging:: How to move changes between branches * Recursive behavior:: CVS descends directories * Adding files:: Adding files to a module * Removing files:: Removing files from a module * Tracking sources:: Tracking third-party sources * Moving files:: Moving and renaming files * Moving directories:: Moving and renaming directories * History browsing:: Viewing the history of files in various ways * Keyword substitution:: CVS can include the revision inside the file * Binary files:: CVS can handle binary files * Revision management:: Policy questions for revision management * Invoking CVS:: Reference manual for CVS commands * Administrative files:: Reference manual for the Administrative files * Environment variables:: All environment variables which affect CVS * Troubleshooting:: Some tips when nothing works * Copying:: GNU GENERAL PUBLIC LICENSE * Index:: Index  File: cvs.info, Node: Preface, Next: What is CVS?, Prev: Top, Up: Top About this manual ***************** Up to this point, one of the weakest parts of CVS has been the documentation. CVS is a complex program. Previous versions of the manual were written in the manual page format, which is not really well suited for such a complex program. When writing this manual, I had several goals in mind: * No knowledge of RCS should be necessary. * No previous knowledge of revision control software should be necessary. All terms, such as "revision numbers", "revision trees" and "merging" are explained as they are introduced. * The manual should concentrate on the things CVS users want to do, instead of what the CVS commands can do. The first part of this manual leads you through things you might want to do while doing development, and introduces the relevant CVS commands as they are needed. * Information should be easy to find. In the reference manual in the appendices almost all information about every CVS command is gathered together. There is also an extensive index, and a lot of cross references. This manual was contributed by Signum Support AB in Sweden. Signum is yet another in the growing list of companies that support free software. You are free to copy both this manual and the CVS program. *Note Copying::, for the details. Signum Support offers support contracts and binary distribution for many programs, such as CVS, GNU Emacs, the GNU C compiler and others. Write to us for more information. Signum Support AB Box 2044 S-580 02 Linkoping Sweden Email: info@signum.se Phone: +46 (0)13 - 21 46 00 Fax: +46 (0)13 - 21 47 00 Another company selling support for CVS is Cyclic Software, web: `http://www.cyclic.com/', email: `info@cyclic.com'. * Menu: * Checklist:: * Credits:: * BUGS::  File: cvs.info, Node: Checklist, Next: Credits, Up: Preface Checklist for the impatient reader ================================== CVS is a complex system. You will need to read the manual to be able to use all of its capabilities. There are dangers that can easily be avoided if you know about them, and this manual tries to warn you about them. This checklist is intended to help you avoid the dangers without reading the entire manual. If you intend to read the entire manual you can skip this table. Binary files CVS can handle binary files, but you must have RCS release 5.5 or later and a release of GNU diff that supports the `-a' flag (release 1.15 and later are OK). You must also configure both RCS and CVS to handle binary files when you install them. Keword substitution can be a source of trouble with binary files. *Note Keyword substitution::, for solutions. The `admin' command Uncareful use of the `admin' command can cause CVS to cease working. *Note admin::, before trying to use it.  File: cvs.info, Node: Credits, Next: BUGS, Prev: Checklist, Up: Preface Credits ======= Roland Pesch, Cygnus Support wrote the manual pages which were distributed with CVS 1.3. Appendix A and B contain much text that was extracted from them. He also read an early draft of this manual and contributed many ideas and corrections. The mailing-list `info-cvs' is sometimes informative. I have included information from postings made by the following persons: David G. Grubbs . Some text has been extracted from the man pages for RCS. The CVS FAQ (*note What is CVS?::.) by David G. Grubbs has been used as a check-list to make sure that this manual is as complete as possible. (This manual does however not include all of the material in the FAQ). The FAQ contains a lot of useful information. In addition, the following persons have helped by telling me about mistakes I've made: Roxanne Brunskill , Kathy Dyer , Karl Pingle , Thomas A Peterson , Inge Wallin , Dirk Koschuetzki and Michael Brown .  File: cvs.info, Node: BUGS, Prev: Credits, Up: Preface BUGS ==== This manual is known to have room for improvement. Here is a list of known deficiencies: * In the examples, the output from CVS is sometimes displayed, sometimes not. * The input that you are supposed to type in the examples should have a different font than the output from the computer. * This manual should be clearer about what file permissions you should set up in the repository, and about setuid/setgid. * Some of the chapters are not yet complete. They are noted by comments in the `cvs.texinfo' file. * This list is not complete. If you notice any error, omission, or something that is unclear, please send mail to bug-cvs@prep.ai.mit.edu. I hope that you will find this manual useful, despite the above-mentioned shortcomings. Linkoping, October 1993 Per Cederqvist  File: cvs.info, Node: What is CVS?, Next: Basic concepts, Prev: Preface, Up: Top What is CVS? ************ CVS is a version control system. Using it, you can record the history of your source files. For example, bugs sometimes creep in when software is modified, and you might not detect the bug until a long time after you make the modification. With CVS, you can easily retrieve old versions to see exactly which change caused the bug. This can sometimes be a big help. You could of course save every version of every file you have ever created. This would however waste an enormous amount of disk space. CVS stores all the versions of a file in a single file in a clever way that only stores the differences between versions. CVS also helps you if you are part of a group of people working on the same project. It is all too easy to overwrite each others' changes unless you are extremely careful. Some editors, like GNU Emacs, try to make sure that the same file is never modified by two people at the same time. Unfortunately, if someone is using another editor, that safeguard will not work. CVS solves this problem by insulating the different developers from each other. Every developer works in his own directory, and CVS merges the work when each developer is done. CVS started out as a bunch of shell scripts written by Dick Grune, posted to `comp.sources.unix' in the volume 6 release of December, 1986. While no actual code from these shell scripts is present in the current version of CVS much of the CVS conflict resolution algorithms come from them. In April, 1989, Brian Berliner designed and coded CVS. Jeff Polk later helped Brian with the design of the CVS module and vendor branch support. You can get CVS via anonymous ftp from a number of sites, for instance prep.ai.mit.edu in `pub/gnu'. There is a mailing list for CVS where bug reports can be sent, questions can be asked, an FAQ is posted, and discussion about future enhancements to CVS take place. To submit a message to the list, write to . To subscribe or unsubscribe, write to . Please be specific about your email address. CVS is not... ============= CVS can do a lot of things for you, but it does not try to be everything for everyone. CVS is not a build system. Though the structure of your repository and modules file interact with your build system (e.g. `Makefile's), they are essentially independent. CVS does not dictate how you build anything. It merely stores files for retrieval in a tree structure you devise. CVS does not dictate how to use disk space in the checked out working directories. If you write your `Makefile's or scripts in every directory so they have to know the relative positions of everything else, you wind up requiring the entire repository to be checked out. That's simply bad planning. If you modularize your work, and construct a build system that will share files (via links, mounts, `VPATH' in `Makefile's, etc.), you can arrange your disk usage however you like. But you have to remember that *any* such system is a lot of work to construct and maintain. CVS does not address the issues involved. You must use your brain and a collection of other tools to provide a build scheme to match your plans. Of course, you should place the tools created to support such a build system (scripts, `Makefile's, etc) under CVS. CVS is not a substitute for management. Your managers and project leaders are expected to talk to you frequently enough to make certain you are aware of schedules, merge points, branch names and release dates. If they don't, CVS can't help. CVS is an instrument for making sources dance to your tune. But you are the piper and the composer. No instrument plays itself or writes its own music. CVS is not a substitute for developer communication. When faced with conflicts within a single file, most developers manage to resolve them without too much effort. But a more general definition of "conflict" includes problems too difficult to solve without communication between developers. CVS cannot determine when simultaneous changes within a single file, or across a whole collection of files, will logically conflict with one another. Its concept of a "conflict" is purely textual, arising when two changes to the same base file are near enough to spook the merge (i.e. `diff3') command. CVS does not claim to help at all in figuring out non-textual or distributed conflicts in program logic. For example: Say you change the arguments to function `X' defined in file `A'. At the same time, someone edits file `B', adding new calls to function `X' using the old arguments. You are outside the realm of CVS's competence. Acquire the habit of reading specs and talking to your peers. CVS is not a configuration management system. CVS is a source control system. The phrase "configuration management" is a marketing term, not an industry-recognized set of functions. A true "configuration management system" would contain elements of the following: * Source control. * Dependency tracking. * Build systems (i.e. What to build and how to find things during a build. What is shared? What is local?) * Bug tracking. * Automated Testing procedures. * Release Engineering documentation and procedures. * Tape Construction. * Customer Installation. * A way for users to run different versions of the same software on the same host at the same time. CVS provides only the first. This section is taken from release 2.3 of the CVS FAQ.  File: cvs.info, Node: Basic concepts, Next: A sample session, Prev: What is CVS?, Up: Top Basic concepts ************** CVS stores all files in a centralized "repository": a directory (such as `/usr/local/cvsroot' or `user@remotehost:/usr/local/cvsroot') which is populated with a hierarchy of files and directories. (*note Remote repositories::. for information about keeping the repository on a remote machine.) Normally, you never access any of the files in the repository directly. Instead, you use CVS commands to get your own copy of the files, and then work on that copy. When you've finished a set of changes, you check (or "commit") them back into the repository. The files in the repository are organized in "modules". Each module is made up of one or more files, and can include files from several directories. A typical usage is to define one module per project. * Menu: * Revision numbers:: The meaning of a revision number * Versions revisions releases:: Terminology used in this manual  File: cvs.info, Node: Revision numbers, Next: Versions revisions releases, Up: Basic concepts Revision numbers ================ Each version of a file has a unique "revision number". Revision numbers look like `1.1', `1.2', `1.3.2.2' or even `1.3.2.2.4.5'. A revision number always has an even number of period-separated decimal integers. By default revision 1.1 is the first revision of a file. Each successive revision is given a new number by increasing the rightmost number by one. The following figure displays a few revisions, with newer revisions to the right. +-----+ +-----+ +-----+ +-----+ +-----+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! +-----+ +-----+ +-----+ +-----+ +-----+ CVS is not limited to linear development. The "revision tree" can be split into "branches", where each branch is a self-maintained line of development. Changes made on one branch can easily be moved back to the main trunk. Each branch has a "branch number", consisting of an odd number of period-separated decimal integers. The branch number is created by appending an integer to the revision number where the corresponding branch forked off. Having branch numbers allows more than one branch to be forked off from a certain revision. All revisions on a branch have revision numbers formed by appending an ordinal number to the branch number. The following figure illustrates branching with an example. +-------------+ Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! / +-------------+ / / +---------+ +---------+ +---------+ +---------+ Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 ! / +---------+ +---------+ +---------+ +---------+ / / +-----+ +-----+ +-----+ +-----+ +-----+ ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk +-----+ +-----+ +-----+ +-----+ +-----+ ! ! ! +---------+ +---------+ +---------+ Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! +---------+ +---------+ +---------+ The exact details of how the branch number is constructed is not something you normally need to be concerned about, but here is how it works: When CVS creates a branch number it picks the first unused even integer, starting with 2. So when you want to create a branch from revision 6.4 it will be numbered 6.4.2. All branch numbers ending in a zero (such as 6.4.0) are used internally by CVS (*note Magic branch numbers::.). The branch 1.1.1 has a special meaning. *Note Tracking sources::.  File: cvs.info, Node: Versions revisions releases, Prev: Revision numbers, Up: Basic concepts Versions, revisions and releases ================================ A file can have several versions, as described above. Likewise, a software product can have several versions. A software product is often given a version number such as `4.1.1'. Versions in the first sense are called "revisions" in this document, and versions in the second sense are called "releases". To avoid confusion, the word "version" is almost never used in this document.  File: cvs.info, Node: A sample session, Next: Repository, Prev: Basic concepts, Up: Top A sample session **************** This section describes a typical work-session using CVS. It assumes that a repository is set up (*note Repository::.). Suppose you are working on a simple compiler. The source consists of a handful of C files and a `Makefile'. The compiler is called `tc' (Trivial Compiler), and the repository is set up so that there is a module called `tc'. * Menu: * Getting the source:: Creating a workspace * Committing your changes:: Making your work available to others * Cleaning up:: Cleaning up * Viewing differences:: Viewing differences  File: cvs.info, Node: Getting the source, Next: Committing your changes, Up: A sample session Getting the source ================== The first thing you must do is to get your own working copy of the source for `tc'. For this, you use the `checkout' command: $ cvs checkout tc This will create a new directory called `tc' and populate it with the source files. $ cd tc $ ls tc CVS Makefile backend.c driver.c frontend.c parser.c The `CVS' directory is used internally by CVS. Normally, you should not modify or remove any of the files in it. You start your favorite editor, hack away at `backend.c', and a couple of hours later you have added an optimization pass to the compiler. A note to RCS and SCCS users: There is no need to lock the files that you want to edit. *Note Multiple developers:: for an explanation.  File: cvs.info, Node: Committing your changes, Next: Cleaning up, Prev: Getting the source, Up: A sample session Committing your changes ======================= When you have checked that the compiler is still compilable you decide to make a new version of `backend.c'. $ cvs commit backend.c CVS starts an editor, to allow you to enter a log message. You type in "Added an optimization pass.", save the temporary file, and exit the editor. The environment variable `$CVSEDITOR' determines which editor is started. If `$CVSEDITOR' is not set, then if the environment variable `$EDITOR' is set, it will be used. If both `$CVSEDITOR' and `$EDITOR' are not set then the editor defaults to `vi'. If you want to avoid the overhead of starting an editor you can specify the log message on the command line using the `-m' flag instead, like this: $ cvs commit -m "Added an optimization pass" backend.c  File: cvs.info, Node: Cleaning up, Next: Viewing differences, Prev: Committing your changes, Up: A sample session Cleaning up =========== Before you turn to other tasks you decide to remove your working copy of tc. One acceptable way to do that is of course $ cd .. $ rm -r tc but a better way is to use the `release' command (*note release::.): $ cd .. $ cvs release -d tc M driver.c ? tc You have [1] altered files in this repository. Are you sure you want to release (and delete) module `tc': n ** `release' aborted by user choice. The `release' command checks that all your modifications have been committed. If history logging is enabled it also makes a note in the history file. *Note history file::. When you use the `-d' flag with `release', it also removes your working copy. In the example above, the `release' command wrote a couple of lines of output. `? tc' means that the file `tc' is unknown to CVS. That is nothing to worry about: `tc' is the executable compiler, and it should not be stored in the repository. *Note cvsignore::, for information about how to make that warning go away. *Note release output::, for a complete explanation of all possible output from `release'. `M driver.c' is more serious. It means that the file `driver.c' has been modified since it was checked out. The `release' command always finishes by telling you how many modified files you have in your working copy of the sources, and then asks you for confirmation before deleting any files or making any note in the history file. You decide to play it safe and answer `n RET' when `release' asks for confirmation.  File: cvs.info, Node: Viewing differences, Prev: Cleaning up, Up: A sample session Viewing differences =================== You do not remember modifying `driver.c', so you want to see what has happened to that file. $ cd tc $ cvs diff driver.c This command runs `diff' to compare the version of `driver.c' that you checked out with your working copy. When you see the output you remember that you added a command line option that enabled the optimization pass. You check it in, and release the module. $ cvs commit -m "Added an optimization pass" driver.c Checking in driver.c; /usr/local/cvsroot/tc/driver.c,v <-- driver.c new revision: 1.2; previous revision: 1.1 done $ cd .. $ cvs release -d tc ? tc You have [0] altered files in this repository. Are you sure you want to release (and delete) module `tc': y  File: cvs.info, Node: Repository, Next: Starting a new project, Prev: A sample session, Up: Top The Repository ************** Figure 3 below shows a typical setup of a repository. Only directories are shown below. /usr | +--local | | | +--cvsroot | | | | | +--CVSROOT | (administrative files) | +--gnu | | | +--diff | | (source code to GNU diff) | | | +--rcs | | (source code to RCS) | | | +--cvs | (source code to CVS) | +--yoyodyne | +--tc | | | +--man | | | +--testing | +--(other Yoyodyne software) There are a couple of different 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 /usr/local/cvsroot checkout yoyodyne/tc Or you can set the `$CVSROOT' environment variable to an absolute path to the root of the repository, `/usr/local/cvsroot' in this example. To set `$CVSROOT', all `csh' and `tcsh' users should have this line in their `.cshrc' or `.tcshrc' files: setenv CVSROOT /usr/local/cvsroot `sh' and `bash' users should instead have these lines in their `.profile' or `.bashrc': CVSROOT=/usr/local/cvsroot 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; however, CVS will complain if the `-d' argument and the `CVS/Root' file disagree. There is nothing magical about the name `/usr/local/cvsroot'. You can choose to place the repository anywhere you like. *Note Remote repositories:: to learn how the repository can be on a different machine than your working copy of the sources. The repository is split in two parts. `$CVSROOT/CVSROOT' contains administrative files for CVS. The other directories contain the actual user-defined modules. * Menu: * User modules:: The structure of the repository * Intro administrative files:: Defining modules * Multiple repositories:: Multiple repositories * Creating a repository:: Creating a repository * Remote repositories:: Accessing repositories on remote machines  File: cvs.info, Node: User modules, Next: Intro administrative files, Up: Repository User modules ============ `$CVSROOT' | +--yoyodyne | | | +--tc | | | +--Makefile,v +--backend.c,v +--driver.c,v +--frontend.c,v +--parser.c,v +--man | | | +--tc.1,v | +--testing | +--testpgm.t,v +--test2.t,v The figure above shows the contents of the `tc' module inside the repository. As you can see all file names end in `,v'. The files are "history files". They contain, among other things, enough information to recreate any revision of the file, a log of all commit messages and the user-name of the person who committed the revision. CVS uses the facilities of RCS, a simpler version control system, to maintain these files. For a full description of the file format, see the `man' page `rcsfile(5)'. * Menu: * File permissions:: File permissions  File: cvs.info, Node: File permissions, Up: User modules File permissions ---------------- All `,v' files are created read-only, and you should not change the permission of those files. The directories inside the repository should be writable by the persons that have permission to modify the files in each directory. This normally means that you must create a UNIX group (see group(5)) consisting of the persons that are to edit the files in a project, and set up the repository so that it is that group that owns the directory. This means that you can only control access to files on a per-directory basis. CVS tries to set up reasonable file permissions for new directories that are added inside the tree, but you must fix the permissions manually when a new directory should have different permissions than its parent directory. Since CVS was not written to be run setuid, it is unsafe to try to run it setuid. You cannot use the setuid features of RCS together with CVS.  File: cvs.info, Node: Intro administrative files, Next: Multiple repositories, Prev: User modules, Up: Repository The administrative files ======================== The directory `$CVSROOT/CVSROOT' contains some "administrative files". *Note Administrative files::, for a complete description. You can use CVS without any of these files, but some commands work better when at least the `modules' file is properly set up. 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 for 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. *Note modules::, for a full explanation of all the available features. 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.  File: cvs.info, Node: Multiple repositories, Next: Creating a repository, Prev: Intro administrative files, Up: Repository Multiple repositories ===================== In some situations it is a good idea to have more than one repository, for instance if you have two development groups that work on separate projects without sharing any code. All you have to do to have several repositories is to specify the appropriate repository, using the `CVSROOT' environment variable, the `-d' option to CVS, or (once you have checked out a working directories) by simply allowing CVS to use the repository that was used to check out the working directory (*note Repository::.). Notwithstanding, it can be confusing to have two or more repositories. None of the examples in this manual show multiple repositories.  File: cvs.info, Node: Creating a repository, Next: Remote repositories, Prev: Multiple repositories, Up: Repository Creating a repository ===================== See the instructions in the `INSTALL' file in the CVS distribution.  File: cvs.info, Node: Remote repositories, Prev: Creating a repository, Up: Repository Remote repositories =================== Your working copy of the sources can be on a different machine than the repository. Generally, using a remote repository is just like using a local one, except that the format of the repository name is: user@hostname:/path/to/repository The details of exactly what needs to be set up depend on how you are connecting to the server. * Menu: * Connecting via rsh:: Using the `rsh' program to connect * Password authenticated:: Direct connections using passwords * Kerberos authenticated:: Direct connections with kerberos  File: cvs.info, Node: Connecting via rsh, Next: Password authenticated, Up: Remote repositories Connecting with rsh ------------------- CVS uses the `rsh' protocol to perform these operations, so the remote user host needs to have a `.rhosts' file which grants access to the local user. For example, suppose you are the user `mozart' on the local machine `anklet.grunge.com', and the server machine is `chainsaw.brickyard.com'. On chainsaw, put the following line into the file `.rhosts' in `bach''s home directory: anklet.grunge.com mozart Then test that `rsh' is working with rsh -l bach chainsaw.brickyard.com echo $PATH Next you have to make sure that `rsh' will be able to find the server. Make sure that the path which `rsh' printed in the above example includes the directory containing a program named `cvs' which is the server. You need to set the path in `.bashrc', `.cshrc', etc., not `.login' or `.profile'. Alternately, you can set the environment variable `CVS_SERVER' on the client machine to the filename of the server you want to use, for example `/usr/local/bin/cvs-1.6'. There is no need to edit `inetd.conf' or start a CVS server daemon. Continuing our example, supposing you want to access the module `foo' in the repository `/usr/local/cvsroot/', on machine `chainsaw.brickyard.com', you are ready to go: cvs -d bach@chainsaw.brickyard.com:/user/local/cvsroot checkout foo (The `bach@' can be omitted if the username is the same on both the local and remote hosts.)  File: cvs.info, Node: Password authenticated, Next: Kerberos authenticated, Prev: Connecting via rsh, Up: Remote repositories Direct connection with password authentication ---------------------------------------------- The CVS client can also connect to the server using a password protocol. This is particularly useful if using `rsh' is not feasible (for example, the server is behind a firewall), and Kerberos also is not available. To use this method, it is necessary to make some adjustments on both the server and client sides. * Menu: * Password authentication server:: Setting up the server * Password authentication client:: Using the client * Password authentication security:: What this method does and does not do  File: cvs.info, Node: Password authentication server, Next: Password authentication client, Up: Password authenticated Setting up the server for password authentication ................................................. On the server side, the file `/etc/inetd.conf' needs to be edited so `inetd' knows to run the command `cvs pserver' when it receives a connection on the right port. By default, the port number is 2401; it would be different if your client were compiled with `CVS_AUTH_PORT' defined to something else, though. If your `inetd' allows raw port numbers in `/etc/inetd.conf', then the following (all on a single line in `inetd.conf') should be sufficient: 2401 stream tcp nowait root /usr/local/bin/cvs cvs -b /usr/local/bin pserver The `-b' option specifies the directory which contains the RCS binaries on the server. If your `inetd' wants a symbolic service name instead of a raw port number, then put this in `/etc/services': cvspserver 2401/tcp and put `cvspserver' instead of `2401' in `inetd.conf'. Once the above is taken care of, restart your `inetd', or do whatever is necessary to force it to reread its initialization files. Because the client stores and transmits passwords in cleartext (almost--see *Note Password authentication security:: for details), a separate CVS password file may be used, so people don't compromise their regular passwords when they access the repository. This file is `$CVSROOT/CVSROOT/passwd' (*note Intro administrative files::.). Its format is similar to `/etc/passwd', except that it only has two fields, username and password. For example: bach:ULtgRLXo7NRxs cwang:1sOp854gDF3DY The password is encrypted according to the standard Unix `crypt()' function, so it is possible to paste in passwords directly from regular Unix `passwd' files. When authenticating a password, the server first checks for the user in the CVS `passwd' file. If it finds the user, it compares against that password. If it does not find the user, or if the CVS `passwd' file does not exist, then the server tries to match the password using the system's user-lookup routine. When using the CVS `passwd' file, the server runs under as the username specified in the the third argument in the entry, or as the first argument if there is no third argument (in this way CVS allows imaginary usernames provided the CVS `passwd' file indicates corresponding valid system usernames). In any case, CVS will have no privileges which the (valid) user would not have. Right now, the only way to put a password in the CVS `passwd' file is to paste it there from somewhere else. Someday, there may be a `cvs passwd' command.  File: cvs.info, Node: Password authentication client, Next: Password authentication security, Prev: Password authentication server, Up: Password authenticated Using the client with password authentication ............................................. Before connecting to the server, the client must "log in" with the command `cvs login'. Logging in verifies a password with the server, and also records the password for later transactions with the server. The `cvs login' command needs to know the username, server hostname, and full repository path, and it gets this information from the repository argument or the `CVSROOT' environment variable. `cvs login' is interactive -- it prompts for a password: cvs -d bach@chainsaw.brickyard.com:/usr/local/cvsroot login CVS password: The password is checked with the server; if it is correct, the `login' succeeds, else it fails, complaining that the password was incorrect. Once you have logged in, you can force CVS to connect directly to the server and authenticate with the stored password by prefixing the repository with `:pserver:': cvs -d :pserver:bach@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo The `:pserver:' is necessary because without it, CVS will assume it should use `rsh' to connect with the server (*note Connecting via rsh::.). (Once you have a working copy checked out and are running CVS commands from within it, there is no longer any need to specify the repository explicitly, because CVS records it in the working copy's `CVS' subdirectory.) Passwords are stored by default in the file `$HOME/.cvspass'. Its format is human-readable, but don't edit it unless you know what you are doing. The passwords are not stored in cleartext, but are trivially encoded to protect them from "innocent" compromise (i.e., inadvertently being seen by a system administrator who happens to look at that file). The `CVS_PASSFILE' environment variable overrides this default. If you use this variable, make sure you set it *before* `cvs login' is run. If you were to set it after running `cvs login', then later CVS commands would be unable to look up the password for transmission to the server. The `CVS_PASSWORD' environment variable overrides *all* stored passwords. If it is set, CVS will use it for all password-authenticated connections.  File: cvs.info, Node: Password authentication security, Prev: Password authentication client, Up: Password authenticated Security considerations with password authentication .................................................... The passwords are stored on the client side in a trivial encoding of the cleartext, and transmitted in the same encoding. The encoding is done only to prevent inadvertent password compromises (i.e., a system administrator accidentally looking at the file), and will not prevent even a naive attacker from gaining the password. The separate CVS password file (*note Password authentication server::.) allows people to use a different password for repository access than for login access. On the other hand, once a user has access to the repository, she can execute programs on the server system through a variety of means. Thus, repository access implies fairly broad system access as well. It might be possible to modify CVS to prevent that, but no one has done so as of this writing. Furthermore, there may be other ways in which having access to CVS allows people to gain more general access to the system; noone has done a careful audit. In summary, anyone who gets the password gets repository access, and some measure of general system access as well. The password is available to anyone who can sniff network packets or read a protected (i.e., user read-only) file. If you want real security, get Kerberos.  File: cvs.info, Node: Kerberos authenticated, Prev: Password authenticated, Up: Remote repositories Direct connection with kerberos ------------------------------- The main disadvantage of using rsh is that all the data needs to pass through additional programs, so it may be slower. So if you have kerberos installed you can connect via a direct TCP connection, authenticating with kerberos (note that the data transmitted is *not* encrypted). To do this, CVS needs to be compiled with kerberos support; when configuring CVS it tries to detect whether kerberos is present or you can use the `--with-krb4' flag to configure. You need to edit `inetd.conf' on the server machine to run `cvs kserver'. The client uses port 1999 by default; if you want to use another port specify it in the `CVS_CLIENT_PORT' environment variable on the client. Set `CVS_CLIENT_PORT' to `-1' to force an rsh connection. When you want to use CVS, get a ticket in the usual way (generally `kinit'); it must be a ticket which allows you to log into the server machine. Then you are ready to go: cvs -d chainsaw.brickyard.com:/user/local/cvsroot checkout foo If CVS fails to connect, it will fall back to trying rsh.  File: cvs.info, Node: Starting a new project, Next: Multiple developers, Prev: Repository, Up: Top Starting a project with CVS *************************** Since CVS 1.x is bad at renaming files and moving them between directories, the first thing you do when you start a new project should be to think through your file organization. It is not impossible--just awkward--to rename or move files. *Note Moving files::. What to do next depends on the situation at hand. * Menu: * Setting up the files:: Getting the files into the repository * Defining the module:: How to make a module of the files  File: cvs.info, Node: Setting up the files, Next: Defining the module, Up: Starting a new project Setting up the files ==================== The first step is to create the files inside the repository. This can be done in a couple of different ways. * Menu: * From files:: This method is useful with old projects where files already exists. * From other version control systems:: Old projects where you want to preserve history from another system. * From scratch:: Creating a module from scratch.  File: cvs.info, Node: From files, Next: From other version control systems, Up: Setting up the files Creating a module 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 `DIR', and you want them to appear in the repository as `$CVSROOT/yoyodyne/DIR', you can do this: $ cd DIR $ cvs import -m "Imported sources" yoyodyne/DIR 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. *Note Tracking sources::, for more information about them. You can now verify that it worked, and remove your original source directory. $ cd .. $ mv DIR DIR.orig $ cvs checkout yoyodyne/DIR # Explanation below $ ls -R yoyodyne $ rm -r DIR.orig Erasing the original sources is a good idea, to make sure that you do not accidentally edit them in DIR, 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. *Note File permissions::.  File: cvs.info, Node: From other version control systems, Next: From scratch, Prev: From files, Up: Setting up the files Creating Files From Other Version Control Systems ------------------------------------------------- If you have a project which you are maintaining with another version control system, such as RCS, you may wish to put the files from that project into CVS, and preserve the revision history of the files. From RCS If you have been using RCS, find the RCS files--usually a file named `foo.c' will have its RCS file in `RCS/foo.c,v' (but it could be other places; consult the RCS documentation for details). Then create the appropriate directories in CVS if they do not already exist. Then copy the files into the appropriate directories in the CVS repository (the name in the repository must be the name of the source file with `,v' added; the files go directly in the appopriate directory of the repository, not in an `RCS' subdirectory). This is one of the few times when it is a good idea to access the CVS repository directly, rather than using CVS commands. Then you are ready to check out a new working directory. From another version control system Many version control systems have the ability to export RCS files in the standard format. If yours does, export the RCS files and then follow the above instructions. From SCCS There is a script in the `contrib' directory of the CVS source distribution called `sccs2rcs' which converts SCCS files to RCS files. Note: you must run it on a machine which has both SCCS and RCS installed, and like everything else in contrib it is unsupported (your mileage may vary).  File: cvs.info, Node: From scratch, Prev: From other version control systems, Up: Setting up the files Creating a module from scratch ------------------------------ For a new project, the easiest thing to do is probably to create an empty directory structure, like this: $ mkdir tc $ mkdir tc/man $ mkdir tc/testing After that, you use the `import' command to create the corresponding (empty) directory structure inside the repository: $ cd tc $ cvs import -m "Created directory structure" yoyodyne/DIR yoyo start Then, use `add' to add files (and new directories) as they appear. Check that the permissions CVS sets on the directories inside `$CVSROOT' are reasonable.  File: cvs.info, Node: Defining the module, Prev: Setting up the files, Up: Starting a new project Defining the module =================== The next step is to define the module in the `modules' file. This is not strictly necessary, but modules can be convenient in grouping together related files and directories. In simple cases these steps are sufficient to define a module. 1. Get a working copy of the modules file. $ cvs checkout modules $ cd modules 2. Edit the file and insert a line that defines the module. *Note Intro administrative files::, for an introduction. *Note modules::, for a full description of the modules file. You can use the following line to define the module `tc': tc yoyodyne/tc 3. Commit your changes to the modules file. $ cvs commit -m "Added the tc module." modules 4. Release the modules module. $ cd .. $ cvs release -d modules  File: cvs.info, Node: Multiple developers, Next: Branches, Prev: Starting a new project, Up: Top Multiple developers ******************* When more than one person works on a software project things often get complicated. Often, two people try to edit the same file simultaneously. Some other version control systems (including RCS and SCCS) try to solve that particular problem by introducing "file locking", so that only one person can edit each file at a time. Unfortunately, file locking can be very counter-productive. If two persons want to edit different parts of a file, there may be no reason to prevent either of them from doing so. CVS does not use file locking. Instead, it allows many people to edit their own "working copy" of a file simultaneously. The first person that commits his changes has no automatic way of knowing that another has started to edit it. Others will get an error message when they try to commit the file. They must then use CVS commands to bring their working copy up to date with the repository revision. This process is almost automatic, and explained in this chapter. There are many ways to organize a team of developers. CVS does not try to enforce a certain organization. It is a tool that can be used in several ways. It is often useful to inform the group of commits you have done. CVS has several ways of automating that process. *Note Informing others::. *Note Revision management::, for more tips on how to use CVS. * Menu: * File status:: A file can be in several states * Updating a file:: Bringing a file up-to-date * Conflicts example:: An informative example * Informing others:: To cooperate you must inform * Concurrency:: Simultaneous repository access * Watches:: Mechanisms to track who is editing files