Preface to the Beta version of the CVS FAQ: This document took more work than I expected. MEGO (My Eyes Glazed Over) probably allowed more errors to creep in than I had hoped. I expect feedback and additions from you readers out there. Over time, I'll probably rewrite and *shorten* most entries. If you have limited time, look first for sections delimited by "[[" & "]]" markers. They will say something like: [[I need an explanation of the mxyzptlk function here.]] Warning: This is a Beta release. Everything up to the '####' will be removed when I believe the original questions have been answered, if only cursorily. Then we'll fall into the normal FAQ routine of fixing text, responding to new releases of CVS, adding entries as people ask questions and incrementing the Revision number along with each update. Notes: The change markers indicate changes in content. I didn't note spelling corrections and grammar fixups. I changed the quoting from ``word'', which caused some complaint, to "word". If you "diff" the Beta version with the Alpha version, you'll see many more changes than are reported in the change markers. Though I mention a fair number of ways that CVS 1.3 fails to match expectations, I haven't been exhaustive. The coming patch release should fix many of the simple problems I left out. I'd rather spend the time making the permanent parts more readable than in adding all sorts of text on bugs in 1.3 that I'll have to remove later. ########################################################################## Archive-name: cvs-faq <<== When I post it to news.answers $Revision: 1.5 $ <<== Include this in your comments $Date: 1993/04/13 16:36:43 $ =========================================================================== == Frequently Asked Questions about CVS (The Concurrent Versions System) == =========================================================================== This document attempts to answer questions posed by users of CVS. CVS installers, administrators and maintainers looking for info on system setup should read the section entitled "Installing CVS". Disclaimer: Though every attempt has been made to ensure the veracity of the following material, no responsibility is assumed for any use, or for any consequences resulting from any use, of the information contained herein. No guarantee of suitability for any purpose is offered or implied. Nothing in this document may be assumed to represent the employers of its contributors. I also might have slipped in a whopper or two to see if you are paying attention. ;-) In other words, don't bet the house on anything you read here unless you have checked it out yourself. Send questions and answers (along with additions to, subtractions from, and divisions of existing questions -- no multiplications, square roots, or transcendental functions, my cabinet is full of them) to the author, who wrote all unattributed text: (Does it always feel strange to refer to oneself in the third person?) David G. Grubbs You may redistribute this as long as you don't take statements out of context. Keep it together along with the revision number. Formatting note: Column 1 will contain a: '-' for a Question that has changed since the last time. '=' for an Answer that has changed since the last time. '#' for an entry with changes to both Question and Answer. '+' for a newly added Question and Answer. Changes will be noted when the $\Revision: changes. ============================================ == Section 0 ==== Introduction ==== ============================================ The questions in this document come from many sources in many forms. Some are simple, some verbose. A few are difficult, but all of them have been asked of the author at one time or another. Some questions are really three or more different problems rolled into one plaintive cry for help. Others reveal one of the bugs or weaknesses of CVS. CVS addresses some difficult problems to which there are no perfect solutions. CVS also changes over time as new features are required. Therefore, the questions are about a complicated moving target. Though in most cases I've tried to provide the simplest answer I can think of, some of the *questions* are difficult to follow. If you aren't using CVS regularly, don't expect to understand everything. A Frequently Asked Questions document is not a substitute for the man page or any other documentation. It is an attempt to answer questions. You should also keep in mind that FAQs are not really intended to be read in their entirety like a text book. You should use "grep" or your editor's search capability to hunt for keywords and read the sections you need. Questions are divided into five numbered Sections. Sections are divided into lettered sub-sections. The questions are numbered sequentially within each sub-section, though they are in no particular order. 1. What is CVS? A. What is CVS? What's it for? Why CVS? B. Where do I find it? Where can I find Help? C. How does CVS differ from other systems? D. What do you mean by . . .? (Definitions) 2. User Tasks A. Getting Started B. Common User Tasks C. Less Common User Tasks D. General Questions 3. Commands A. through P. One section for each CVS command. 4. Advanced Topics A. Installing CVS B. Setting up and Managing the Repository C. Branching D. Tricks of the Trade E. Weirdness F. Other Systems 5. Past & Future A. Contributors. B. Bugs and Patches C. Development 6. Table of Contents Final note: Except for the "Past & Future" section, all answers in this document refer to the latest released version of CVS. ============================================ == Section 1 ==== What is CVS? ==== ============================================ ---------------- -- Section 1A -- What is CVS? What's it for? Why CVS? ---------------- **** Questions: 1A.1 What does CVS stand for? Can you describe it in one sentence? 1A.2 What is CVS for? What does it do for me? 1A.3 How does CVS work? 1A.4 What is CVS useful for? =1A.5 What is CVS *not* useful for? 1A.6 Why isn't it called OSCO (Online Source COntrol)? **** Answers: 1A.1 What does CVS stand for? Can you describe it in one sentence? "CVS" is an acronym for the "Concurrent Versions System". CVS is a "Source Control" or "Revision Control" tool designed to keep track of changes to files made by groups of developers working on the same files, allowing them to stay in sync with each other as each individual chooses. 1A.2 What is CVS for? What does it do for me? CVS is used to keep track of collections of files in a shared directory, called "The Repository". Each collection of files can be given a "module" name, which is used to "checkout" that collection. After checkout, files can be modified (using your favorite editor), "committed" back into the Repository and compared against earlier revisions. Collections of files can be "tagged" with a symbolic name for later retrieval. You can add new files, remove files you no longer want, ask for information about sets of files in three different ways, produce patch "diffs" from a base revision and merge the committed changes of other developers into your working files. 1A.3 How does CVS work? CVS stores its files in a directory hierarchy, called the Repository, which is separate from the user's working directory. Files in the Repository are stored in a format dictated by the RCS commands CVS uses to do much of its real work. RCS files are standard byte-stream files with an internal format described by keywords stored in the files themselves. To begin work, you execute the "checkout" command, handing it a module or directory you want to work on. CVS copies each file in the specified module or directory out of the Repository and into a sub-directory created in your current directory. You then modify files in the new sub-directory, building them into output files and testing the results. When you want to make your changes available to other developers, you "commit" them back into the Repository. Other developers can check out the same files at the same time. To merge the committed work of others into your working files you use the "update" command. When your merged files build and test correctly, you may commit the merged result. This method is referred to as "copy-modify-merge", which does not require locks on the source files. At any time, usually at some milestone, you can "tag" the committed files, producing a symbolic name that can be handed to a future "checkout" command. A special form of "tag" can produce a branch in development, as usually happens at "release" time. When you no longer plan to modify or refer to your local copy of the files, they can be removed. 1A.4 What is CVS useful for? CVS is intended to be useful for three major activities: 1. Multiple developers The major advantage of using CVS over the older and simpler tools like RCS or SCCS is that it allows multiple developers to work on the same sources at the same time. The shared Repository provides a rendezvous point for committed sources that allows developers a fair amount of flexibility in how often to publish (via the "commit" command) changes or include work committed by others (via the "update" command). 2. Vendor releases If you are making changes to a product distributed by someone else, the CVS feature, called the Vendor Branch, allows you to combine local modifications with vendor releases. I have found this most useful when dealing with sources from three major classes of source vendor: a. Large companies who send you tapes full of the latest release (e.g. Unix OS vendors, database companies). b. Public Domain software which *always* requires work. c. Pseudo-Public sources which require medium amounts of work. (e.g. GNU, X, etc.) 3. Branches There are three kinds of "branches in development" that CVS can support: a. While working in a checked-out directory, you can consider yourself to be on a private "branch". No one but you can work on your files and you have complete control over when you include work committed by others. You can't commit or tag intermediate versions of your work, however. b. When groups of developers want to share changes only within the group, you can create a branch to work on where only those who have checked-out that particular branch see the changes on that branch. c. At release time, a branch to hold patch-releases can be made. Though the internal format of this is the same as in the above, the purpose is different. Though at this writing, the branch support is a bit primitive, CVS was designed to allow you to create branches, work on them for while and merge them back into the main stream of development. Arbitrary sharing and merging between branches is not currently supported. =1A.5 What is CVS *not* useful for? CVS is not a build system. Though the structure of your Repository and modules file interact with your build system (e.g. Makefiles), they are essentially independent. CVS does not dictate how you build anything. It stores files for retrieval. CVS does not dictate how to use disk space in the checked out working directories. If you write your Makefiles 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 Makefiles, 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. 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 a tool for making sources dance to your tune. But you are the piper and the composer. No tool recovers from lack of planning. 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 each other. Its concept of a "conflict" is purely textual, arising when two changes made by different people are near enough to spook the "diff" command. CVS does not claim to help in this matter at all. For example: If you add new arguments to a function defined in file A at the same time that someone else adds new calls to the function using only the old arguments in file B, you are outside the realm of CVS's competence. You must talk to your peers. CVS is not a configuration management system. It 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. 1A.6 Why isn't it called OSCO (Online Source COntrol)? I don't know. ---------------- -- Section 1B -- Where do I find CVS? Where can I find Help? ---------------- **** Questions: 1B.1 How do I get more information about CVS? 1B.2 Is there an archive of CVS material? =1B.3 How do I get a copy of the latest version of CVS? =1B.4 Is there any other documentation? How about tutorials? 1B.5 Is there a mailing list devoted to CVS? How do I get on it? 1B.6 What prayers are appropriate for each of the major denominations **** Answers: 1B.1 How do I get more information about CVS? 1. The first thing you should do is read the man page. 2. Type "cvs -H" for general help or "cvs -H command" for command-specific help. 3. Read the original CVS paper (in the source tree, under "doc"). It describes the purpose of CVS, but some of the emphasis (especially on multiple vendors providing the same sources) is out of date. 4. Look in the "doc" directory in the FTP archive described below. 5. Join the info-cvs mailing list, described below. 6. Read the man pages for RCS. 1B.2 Is there an archive of CVS material? An anonymous FTP area has been set up. It contains many of the CVS files you might want, including documentation, patches and the latest release. ftp think.com >>>> User: "anonymous"; Passwd: Your Internet address cd /pub/cvs Get the README, Index & FAQ files and read them. Warnings 1. This archive is new. It will not have all the files in it until we have time to put them there. 2. This archive has no history. Though it is unlikely to disappear immediately, you should not depend on something as new as this until it is has had time to become accepted. =1B.3 How do I get a copy of the latest version of CVS? The latest released version of CVS and all the programs it depends on should be available through anonymous FTP on any FSF archive. The main FSF archive is at "prep.ai.mit.edu". There is another archive at UUNET and other large Internet sites. Program(s) Latest revision ----------- ----------------------- CVS 1.3 (Patch release coming soon.) RCS 5.6.0.1 GNU diff 2.2 The GNU version of diff is suggested by both the RCS and CVS configuration instructions because it works better than the standard version. If you plan to use dbm in the modules file, you might also want to pick up the GNU dbm library. It is a good idea not to accept the versions of CVS, RCS or diff you find lying on your system, unless you have checked out their provenance. Using inconsistent collections of tools can cause you more trouble than you probably want. The latest release, plus official and unofficial patches will be stored in the CVS FTP area mentioned above. =1B.4 Is there any other documentation? How about tutorials? Take a look at the "doc" sub-directory in the FTP archive. You should find a growing collection of additional CVS documentation there. Other sources: 1. Per Cederqvist's Texinfo manual. The latest version of the Texinfo manual written by Per Cederqvist is included in the "doc" area mentioned above. 2. Gray Watson's cvs_tutorial. There should be a version of this document in the "doc" area. 3. Apparently there is at least one project at O'Reilly (on RCS/SCCS) that will include some info about CVS. [[Anything else?]] 1B.5 Is there a mailing list devoted to CVS? How do I get on it? To get on the mailing list, send an Email message to: info-cvs-request@prep.ai.mit.edu (Don't forget the "-request" or you'll send a message to the whole list, some of whom are capable of remote execution.) Mail to the list itself should be sent to: info-cvs@prep.ai.mit.edu An archive of the mailing list back to . . . [[Unknown as yet.]] is available in the FTP archive. 1B.6 What prayers are appropriate for each of the major denominations (e.g. 20's, 50's, 100's) when issuing complex CVS commands? Only what the traffic will allow, in small, unmarked bills delivered to me, Ralph Icebag, in a plain brown wrapper, by a brown-shoed square, in the dead of night. (Apologies to Firesign Theater.) ---------------- -- Section 1C -- How does CVS differ from other systems? ---------------- [[Any other systems that should be mentioned?]] **** Questions: 1C.1 How does CVS differ from RCS? =1C.2 How does CVS differ from SCCS? 1C.3 How does CVS differ from ClearCase? 1C.4 How does CVS differ from TeamWare? 1C.5 How does CVS differ from SunPro? 1C.6 How does CVS differ from Aegis? +1C.7 How does CVS differ from Shapetools? **** Answers: 1C.1 How does CVS differ from RCS? CVS uses RCS to do much of its work and absolutely all the work of changing the underlying RCS files in the Repository. RCS comprises a set of programs designed to keep track of changes to individual files. Of course, it also allows you to refer to whole sets of files on the command line, but groups are manipulated by iterating over those files. There is no pretense of combined interaction between the files. CVS's main intent is to provide a set of grouping functions that allow you to treat a collection of RCS files as a single object. Of course, CVS also has to do a lot of iteration, but it tries its best to hide that it is doing so. In addition, CVS has some truly group-oriented facets, such as the modules file and the CVS administrative files that refer to a whole directory or module. One group aspect that can be a bit confusing is that a CVS branch is not the same as an RCS branch. To support a CVS branch, CVS uses "tags" (what RCS calls "symbols") and some local state, in addition to RCS branches. Other features offered by CVS that are not supported directly by RCS are 1. Automatic determination of the state of a file, (e.g. modified, up-to-date with the Repository, already tagged with the same string, etc.) which helps in limiting the amount of displayed text you have to wade through to figure out what changed and what to do next. 2. A copy-modify-merge scheme that avoids locking the files and allows simultaneous development on a single file. 3. Relatively easy merging of releases from external Vendors. =1C.2 How does CVS differ from SCCS? SCCS is much closer to RCS than to CVS, so some of the previous entry applies. You might want to take a look at Walter Tichy's papers on RCS, which are referred to in the RCS man pages. [[More info here?]] 1C.3 How does CVS differ from ClearCase? [[Need some info here.]] 1C.4 How does CVS differ from TeamWare? [[Need some info here.]] 1C.5 How does CVS differ from SunPro? [[Need some info here.]] 1C.6 How does CVS differ from Aegis? Aegis appears to be a policy-setting tool that allows you to use other sub-programs (make, RCS, etc.) to implement pieces of the imposed policy. The initial document seems to say that most Unix tools are inadequate for use under Aegis. It is not really similar to CVS and requires a different mindset. [[Need more info here.]] +1C.7 How does CVS differ from shapetools? Shapetools includes a build mechanism (called Shape, not surprisingly) that is aware of the version mechanism, and some dependency tracking. It is based on a file system extension called Attributed File System, which allows arbitrary-sized "attributes" to be associated with a file. Files are versioned in a manner similar to RCS. Configurations are managed through the Shapefile, an extension of the Makefile syntax and functionality. Shape includes version selection rules to allow sophisticated selection of component versions in a build. Shapetools' concurrency control is pessimistic, in contrast to that of CVS. Also, there's very limited support for branching and merging. It has a built-in policy for transitioning a system from initial development to production. Contributed by Don Dwiggins ---------------- -- Section 1D -- What do you mean by . . .? (Definitions) ---------------- **** Questions: 1D.1 What is "The Repository"? 1D.2 What is an RCS file? 1D.3 What is a working file? +1D.4 What is a working directory (or working area)? 1D.5 What is "checking out"? 1D.6 What is a revision? 1D.7 What is a "Tag"? #1D.8 What are "HEAD" and "BASE"? 1D.9 What is a Branch? 1D.10 What is "the trunk"? 1D.11 What is a module? **** Answers: 1D.1 What is "The Repository"? The Repository is a directory tree containing the CVSROOT directory (which contains the CVS global admin files) and a collection of RCS files. It is kept in a shared area, separate from the working areas of all developers. 1D.2 What is an RCS file? A file, usually ending in ",v", containing the source text and the revision history for all committed revisions of a source file. It is stored separately from the working files, in a directory hierarchy, called the Repository. RCS is the "Revision Control System" that CVS uses to manage individual files. 1D.3 What is a working file? A disk file containing a checked-out copy of a source file that earlier had been placed under CVS. If the working file has been edited, the changes since the last committed revision are invisible to others using CVS. +1D.4 What is a working directory (or working area)? The "checkout" command creates a tree of working directories, filling them with working files. A working directory always contains a sub-directory named ./CVS containing information about working files and the location of the directory within the Repository that was used to create the working directory. A working directory is the place where you work and the place from which you "commit" files. 1D.5 What is "checking out"? "Checking out" is the act of using the "checkout" command to copy a particular revision from a set of RCS files into your working area. See the "checkout" command in Section 3C. 1D.6 What is a revision? A "revision" is a version of a file that was "committed" (or "checked in", in RCS terms) some time in the past. CVS (and RCS) can retrieve any file that was committed by specifying its revision number or its "tag" (or symbolic name, in RCS terms). In CVS, a "tag" is more useful than a revision number. It usually marks a milestone in development represented by different revision numbers in different files, all available as one "tagged" collection. 1D.7 What is a "Tag"? A "Tag" is a symbolic name, a synonym or alias for a particular revision number in a file. The CVS "tag" command places the same "Tag" on all files in a working directory, allowing you to retrieve those files by name in the future. #1D.8 What are "HEAD" and "BASE"? BASE and HEAD are built-in tags that don't show up in the "log" or "status" listings. They are interpreted directly by CVS. "HEAD" refers to the latest revision on the current branch in the Repository. The current branch is either the main line of development, or a branch in development created by placing a branch tag on a set of files and checking out that branch. "BASE" refers to the revision on the current branch you last checked out, updated, or committed. If you have not modified your working file, "BASE" is the committed revision matching it. Normally BASE and HEAD refer to the same revision. They can be different for two reasons: 1. Someone else changed HEAD by committing a new revision of your file to the Repository. You can pull BASE up to equal HEAD by executing "update". 2. You moved BASE backward by executing "checkout" or "update" with the "-r {rev/tag}" option. It sets a sticky tag and moves to an earlier revision. You can clear the sticky tag and pull BASE up to equal HEAD by executing "update -A". 1D.9 What is a Branch? Any mechanism that allows one or more developers to modify a physically separate copy of a file without affecting anyone other than those working on the branch. See section 4C, on Branching. 1D.10 What is "the trunk"? Another name for the Main Branch in an RCS file. The Main Branch is related, but not the same as, the Main line of development. 1D.11 What is a module? A module is a name you hand to the "checkout" command to retrieve one or more files to work on. It was originally intended to be a simple, unique name in the "modules" file attached to a directory or a subset of files within a directory. Since you can also "checkout" relative pathnames within the Repository, I tend to think of a "module" as any of the following: 1. A name for a directory buried within the Repository that allows you to ignore the nested sub-directories above it. 2. A name for a subset of the files within such a directory. 3. A relative pathname to a directory within the Repository which, when checked out, creates an image of the Repository structure from the pathname downward. 4. A relative pathname to a single file as in #3. 5. A module name followed by a single '/' followed by a file or directory name. This is a way to checkout only part of a module. 6. An alias consisting of a list of any of the above, including other aliases. It has been pointed out to me that the modules file is simply another way to "name" files. The hierarchical directory structure provides another. You should use whatever turns out to be simplest. ========================================== == Section 2 ==== User Tasks ==== ========================================== ---------------- -- Section 2A -- Getting Started ---------------- **** Questions: 2A.1 What is the first thing I have to know? 2A.2 Where do I work? =2A.3 What does CVS use from my environment? 2A.4 OK, I've been told that CVS is set up, my module is named "ralph" and I have to start editing. What do I type? 2A.5 I have been using RCS for a while. Can I convert to CVS without losing my revision history? How about converting from SCCS? **** Answers: 2A.1 What is the first thing I have to know? Your organization has assigned one or more persons to understand, baby-sit and administer both the CVS programs and the data Repository. I call these persons Repository Administrators. They will have set up a Repository and "imported" files into it. If you don't believe anyone has this responsibility, or you are just testing CVS, then *you* are the Repository Administrator. If you are a normal user of CVS ask your Repository Administrator what module you should check out. Then you can work. If you *are* the Repository Administrator, you will want to read the "Installing CVS" section in "Advanced Topics". You should read everything you can get your hands on, including this document, and expect to feel stupid for a few days/weeks. Source control issues can be difficult. CVS is not bug-free and no tool in the universe avoids the need for intelligent organization. In other words, there are all sorts of related issues you will probably have to learn. Don't expect to dive in and stuff 300 Megabytes of sources into it or you will probably spend a few sleepless nights. 2A.2 Where do I work? Wherever you have disk space. That's one of the advantages of CVS: you use the "checkout" command to copy files from the Repository to your working directory, which can be anywhere you have the space. Your local group might have conventions for where to work. Ask your peers. =2A.3 What does CVS use from my environment? You must set two environment variables. Some shells share these variables with local shell variables using a different syntax. You'll have to learn how your shell handles them. Variable Value (or action) --------- --------------------- CVSROOT Absolute pathname of the head of your Repository. PATH Normally set to a list of ':'-separated directory pathnames searched to find executables. You must make sure "cvs" is in one of the directories. Optional variables: (These are used if set, but ignored otherwise.) Variable Value (or action) --------- --------------------- CVSEDITOR The name of your favorite fast-start editor program. You'll be kicked into your editor to supply revision comments if you don't specify them via -m "Log message" on the command line. [[Note: This is not in 1.3 -- It should appear in the next release.]] EDITOR Used if CVSEDITOR doesn't exist. If EDITOR doesn't exist, CVS uses a configured constant, usually, "vi". CVSREAD Sets files to read-only on "checkout". RCSBIN Changes where CVS finds the RCS commands. CVSIGNORE Adds to the ignore list. See section 2D. Other variables used by CVS that are normally set upon login: Variable Value (or action) --------- --------------------- LOGNAME Used to find the real user name if running as root. USER Used to find the real user name if no LOGNAME. HOME Used to determine home directory in "history". 2A.4 OK, I've been told that CVS is set up, my module is named "ralph" and I have to start editing. What do I type? cvs checkout ralph cd ralph And hack away. 2A.5 I have been using RCS for a while. Can I convert to CVS without losing my revision history? How about converting from SCCS? If you are asking such questions, you are not a mere user of CVS, but one of its Administrators! You should take a look at Section 4A, "Installing CVS" and section 4B, "Setting up and Managing the Repository". ---------------- -- Section 2B -- Common User Tasks ---------------- What I consider a "common user task" generally involves combinations of the following commands: add, checkout, commit, diff, log, status, tag, update Conventions in this section: 1. Before each CVS command, you are assumed to have typed a "cd" command to go to a writable working directory. 2. All further "cd" commands specified in the examples are assumed to start in the above working directory. 3. Unless a point is being made about multiple instances, all modules are named , all tags are named (branch tags are named ) and all files are named . Note: The checkout command will take a relative path name in place of a module name. If you use a relative pathname in place of , you should use the same relative path every place you see in that example. **** Questions: 2B.1 What is the absolute minimum I have to do to make a simple change to a single file? 2B.2 If I edit multiple files, must I type "commit" for each one? 2B.3 How do I get rid of the directory that "checkout" created? 2B.4 How do I find out what has changed? 2B.5 I just created a new file. How do I add it to the Repository? 2B.6 How do I merge changes made by others into my working directory? 2B.7 How do I label a set of revisions so I retrieve them later? 2B.8 How do I checkout an old release of a module, directory or file? 2B.9 What do I have to remember to do periodically? **** Answers: 2B.1 What is the absolute minimum I have to do to make a simple change to a single file? Tell your Repository Administrator to create a module for you that covers the directory or files you care about. S/he tells you the module or relative pathname is . cvs checkout cd emacs # Isn't Emacs a synonym for editor? cvs commit 2B.2 If I edit multiple files, must I type "commit" for each one? No. The "commit" command, like all CVS commands, will work on the whole directory by default. Just type: "cvs commit". 2B.3 How do I get rid of the directory that "checkout" created? Change your directory to be the same as when you typed your "checkout" command and type: cvs release -d The current version of CVS does not detect foreign directories (i.e. ones that weren't created by CVS) in your working directory and will destroy them. If you don't care about keeping "history", and you don't care to plan ahead to a possibly working "release" command, you can just remove it. That's "rm -rf " under Unix. 2B.4 How do I find out what has changed? This is a vaguely worded question. But it was asked by a number of different people and it opens up a lot of different topics. To find out what you've changed since your last commit, type: cvs diff To find out what other people have added (to your branch) since you last checked out or updated, type: cvs diff -r BASE -r HEAD To find out more about changes, you can use the "log" command. You can also use "history" to trace a wide variety of events. 2B.5 I just created a new file. How do I add it to the Repository? cvs add cvs commit 2B.6 How do I merge changes made by others into my working directory? If you are asking about other branches, see the section on "Branching". You will have to use the "update -j" command. Retrieving changes made by others to the *same* branch you are working on, is the main purpose of the "update" command. The "update" command tries to merge work committed to the Repository since you last ran "checkout" or "update" into your working directory. There are five possible outcomes for each file: 1. If neither you nor others have made changes, "update" will print nothing. 2. If you have made no changes to a file, but others have, you will see: U You might want to examine the changes (using the CVS "diff" command) to see if they mesh with your own in related files. 3. If you have made changes, but others have not, you will see: M Nothing happened except you were told that you have a modified file in your directory. 4. If both you and others have made changes to a file, but in different sections of the file, you will see: RCS file: /Repository/module/ retrieving revision 1.X retrieving revision 1.Y Merging differences between 1.X and 1.Y into M If you run "diff" before and after this step, you should see the same output. This is one of the few times the otherwise nonsensical phrase "same difference" means something. 5. If both you and others have made changes to the same section of a file, you will see: RCS file: /Repository/module/ retrieving revision 1.X retrieving revision 1.Y Merging differences between 1.X and 1.Y into rcsmerge warning: overlaps during merge cvs update: conflicts found in C This is a "conflict". The file will have strange looking text inserted into it to mark the overlapping text. You must examine the overlaps with care and resolve the problem without removing all previous work. 2B.7 How do I label a set of revisions so I retrieve them later? To "tag" the BASE revisions (the ones you last checked out or updated) you "cd" to the head of the working directory you want to tag and type: cvs tag It walks through your working directory tagging the BASE revisions. To "tag" the latest revision on the Main branch in the Repository, you can use the following from anywhere: (No "cd" is required -- it works directly on the Repository.) cvs rtag 2B.8 How do I checkout an old release of a module, directory or file? Module names and directories are simply ways to name sets of files. Once the list of file names is determined, there are 6 ways to specify which revision of a particular file to check out: 1. By tag or symbolic name, via the '-r ' option. 2. By date, via the '-D ' option. 3. By branch tag (a type of tag with a magic format), via the '-r ' option. 4. By date within a branch, via the '-r :' option. (This one may not yet be implemented.) 5. By an explicit branch revision number, which refers to the latest revision on the branch. This isn't really an "old" revision, from the branch's perspective, but from the user's perspective the branch might have been abandoned in the past. 6. An explicit revision number. Though this works, it is almost useless for more than one file. You type: cvs checkout cd 2B.9 What do I have to remember to do periodically? You should certainly run "cvs -n update" often to keep track of what you and others have changed. It won't change anything, it will just give you a report. Unless you are purposely delaying the inclusion of other developers' work, you should run "update" once in a while and resolve the conflicts. It is not good to get too far out of sync. It is assumed that your system administrators have arranged for editor backup and Unix temp files (#* and .#*) to be deleted after a few weeks. But you might want to look around for anything else that is ignored or hidden. Try "cvs -n update -I !" to see all the ignored files. If you are the Repository Administrator, see section 4B.17. ---------------- -- Section 2C -- Less Common User Tasks ---------------- What I consider a "less common user task" generally involves one or more of the following commands: history, import, export, rdiff, release, remove, rtag **** Questions: 2C.1 Can I create sub-directories in my working directory? 2C.2 How do I add new sub-directories to the Repository? 2C.3 How do I remove a file I don't need? 2C.4 How do I rename a file? 2C.5 How do I make sure that all the files and directories in my working directory are really in the Repository? 2C.6 How do I create a branch? 2C.7 How do I modify the modules file? How about the other files in the CVSROOT administrative area? **** Answers: 2C.1 Can I create sub-directories in my working directory? Yes, but the "update" command will traverse them, wasting a lot of time. You can't currently ignore directories but if a directory has no ./CVS administrative directory, nothing will happen to it during an "update". On the other hand "release -d" will delete it without warning. 2C.2 How do I add new sub-directories to the Repository? The "add" command will work on directories. You type: mkdir cvs add It will respond: Add directory /Repository/ to the Repository (y/n) [n] ? If you type a "y", you will create both a directory in the Repository and a ./CVS administrative directory within the local working directory. 2C.3 How do I remove a file I don't need? (See the questions in section 4B on removing files from the Repository.) You type: rm cvs remove CVS registers the file for removal. To complete the removal, you must type: cvs commit CVS moves the file to the Attic associated with your working directory. Each directory in the Repository stores its deleted files in an Attic sub-directory. A normal "checkout" doesn't look in the Attic, but if you specify a tag, a date or a revision, the "checkout" (or "update") command will retrieve files from the Attic with that tag, date or revision. 2C.4 How do I rename a file? CVS does not offer a way to rename a file in a way that CVS can track later. See questions in Section 4B for details. 2C.5 How do I make sure that all the files and directories in my working directory are really in the Repository? Normally, you only need to be notified of files you forgot to "add". A simple "update", or "update -n" (which won't modify your working directory) will show non-added files with a "?" in front of them. To recover, "add" and "commit" them. To verify that all your directories are in the Repository, you have to go look. Though CVS traverses all directories, it produces no output for directories not backed up by a Repository directory. By default many patterns of files are ignored. If you create a file named "core" or a file ending in ".o", it is usually ignored. If you really want to see all the files that aren't in the Repository, you can use a special "ignore" pattern to say "ignore no files". Try executing: (You may have to quote or backwhack the "!" in your shell.) cvs -n update -I ! The above command will display not only the normal "M"odified, "U"pdate and "C"onflict indicators on files within the Repository, but it will also display each file not in the Repository preceded by a "?" character. The '-n' option will not allow "update" to alter your working directory. 2C.6 How do I create a branch? See Section 4C, on Branching. 2C.7 How do I modify the modules file? How about the other files in the CVSROOT administrative area? A module named "modules" has been provided in the default modules file, so you can type: cvs checkout modules cd modules Another module named CVSROOT has been provided in the default modules file, covering all the administrative files. Type: cvs checkout CVSROOT cd CVSROOT Then you can edit your files, followed by: cvs commit ---------------- -- Section 2D -- General Questions ---------------- **** Questions: 2D.1 How do I see what CVS is trying to do? 2D.2 If I work with multiple modules, should I check them all out and commit them occasionally? Is it OK to leave modules checked out? 2D.3 What is a "sticky" tag? What makes it sticky? How do I loosen it? 2D.4 How do I get a old revision without updating the "sticky tag"? =2D.5 What operations disregard sticky tags? 2D.6 Is there a way to avoid reverting my Emacs buffer after committing a file? Is there a "cvs-mode" for Emacs? 2D.7 How does conflict resolution work? What *really* happens if two of us change the same file? 2D.8 How can I tell who has a module checked out? 2D.9 Where did the .#.1.2 files in my working directory come from? 2D.10 What is this "ignore" stuff? 2D.11 Why does .cvsignore not ignore directories? 2D.12 Is it safe to interrupt CVS using Control-C? 2D.13 How do I turn off the "admin" command? 2D.14 How do I turn off the ability to disable history via "cvs -l"? 2D.15 How do I keep certain people from accessing certain directories? **** Answers: 2D.1 How do I see what CVS is trying to do? The '-t' option on the main "cvs" command will show you every external command (mostly RCS commands and file deletions) it executes. When combined with the '-n' option, which prevents the execution, you can see what it will do before you let it fly. The '-t' option will *not* show you every internal action, only the calls to external programs. Some systems offer a "trace" command that will show you all the system calls as they happen. This is a *very* low-level interface, but it can be useful. The most complete answer is to run it under a debugger. 2D.2 If I work with multiple modules, should I check them all out and commit them occasionally? Is it OK to leave modules checked out? The simple answers are "Yes." There is no reason to remove working directories, other than to save disk space. As long as you have committed the files you choose to make public, your working directory is just like any other directory. CVS doesn't care whether you leave modules checked out or not. The advantage of leaving them checked out is that you can quickly visit them to make and commit changes. 2D.3 What is a "sticky" tag? What makes it sticky? How do I loosen it? When you execute "update -r ", CVS remembers the . It has become "sticky" in the sense that until you change it or remove it, the tag is remembered and used in references to the file as if you had typed '-r ' on the command line. It is most useful for a , which is a sticky tag indicating what branch you are working on. A revision number or date can become sticky when they are used to ask for a file by revision number ("update -r ") or by date ("update -D "). A sticky tag, revision or date remains until you specify another tag, revision or date the same way. The "update -A" command moves back to the Main branch, which has the side-effect of clearing all sticky items on the updated files. The "checkout" command sticky tags, revisions and dates the same way as "update" does. Also, the '-k' option records a "sticky" keyword option that is used in further "updates until "update -A" is specified. 2D.4 How do I get a old revision without updating the "sticky tag"? Use the '-p' option. The command "update -p -r " will send the selected revision to your terminal (actually, to "stdout"), affecting nothing else. If you want to save the result, you aim "stdout" at a file using your shell's redirection capability. In most shells this works: cvs update -p -r TAG filename > diskfile =2D.5 What operations disregard sticky tags? The functions that routinely disregard sticky tags are: 1. Those that work directly on the Repository or its administrative files: admin rtag log status remove history 2. Those that take TAGS or revisions as arguments and ignore everything else: (They also never *set* a sticky tag.) rdiff import export 3. The "release" command, which doesn't really look at *anything*. It calls "update -n" to figure out what's up. 4. The "tag" command, which works on the revision lying in the working directory however it got there. That the revision lying there might happen to have a sticky tag attached to it is not the "tag" command's concern. The main function that *does* read and write sticky tags is the "update" command. You can avoid referring to or changing the sticky tag by using the '-p' option, which sends files to your terminal, touching nothing else. The "checkout" command sets sticky tags when checking out a new module and it acts like "update" when checking out a module into an existing directory. The "diff" and "commit" commands use the sticky tags, unless overridden on the command line. They do not set sticky tags. Note that you can only "commit" to a file checked out with a sticky tag, if the tag identifies a branch. There are really two types of sticky tags, one attached to individual files (in the CVS/Entries file) and one attached to each directory (in the CVS/Tag file). They can differ. The "add" command doesn't pay attention to anything -- it just registers the desire to add a new file. When a newly added file is `committed", CVS *should* use the "directory tag" to determine what branch to commit it to. Unfortunately, it doesn't work correctly. See 4C.8. 2D.6 Is there a way to avoid reverting my Emacs buffer after committing a file? Is there a "cvs-mode" for Emacs? There is a set of files called "pcl-cvs" in the "contrib" directory. It is large and somewhat complicated, but it appears to allow you to use CVS from within Emacs. [[Is there anything like a "cvs-mode.el" file with a few cvs access routines?]] 2D.7 How does conflict resolution work? What *really* happens if two of us change the same file? While editing, there is no conflict -- you are working on separate virtual branches of development. When one of you decides to commit the file, the other may not commit the same file until "update" has merged the two together. Say you both check out rev 1.2 of . Your coworker commits revision 1.3. When you try to commit your file, CVS says: cvs commit: Up-date-check failed for `' You must merge your coworker's changes into your working file by typing: cvs update which will produce the output described in question 2B.6. After you resolve any overlaps caused by the merging process, you may then commit the file. Yes, the first one who commits can cause the other some work. Yes, between the time you run "update" and "commit", someone else may have committed a later revision of . You will have to run "update" again to merge the new work before committing. Most organizations don't have this problem. If you do, you might consider splitting the file. 2D.8 How can I tell who has a module checked out? If you "checkout" module names (not relative pathnames) and you use the release command, the "history" command will show you who has what checked out. It is advisory only; it can be circumvented by using the '-l' option on the main "cvs" command. 2D.9 Where did the .#.1.2 files in my working directory come from? They are created during an "update" when CVS merges committed revisions into your modified working file. They serve the same purpose as any "backup" file: saving your bacon often enough to be worth retaining. They are invaluable in recovering when things go wrong. Say Developers A(you) and B check out rev 1.1 of file You both make changes, different changes. B commits first, so the Repository's ,v file contains revisions 1.1 and 1.2. At this point, there are 5 (yes, five) versions of the file of interest to you: 1. Revision 1.1 (What you originally checked out.) 2. Revision 1.2 (What you need from developer B.) 3. Your old working file. (Before the update.) 4. Your new working file. (After the merge caused by "cvs update".) 5. Revision 1.3 (Which you will commit shortly.) In the case where your working file was not modified, #1 and #3 will be the same, as will #2 and #4. In this degenerate case, there is no need to create #5. The following assumes that your working file was modified. If the merge executed by the "update" caused no overlaps, #4 and #5 will be the same. But you might then make changes before committing, so the difference between #4 and #5 might be more than just the correction of overlaps. In general, though, you don't need #4 after a commit. But #3 (which is the one saved as ".#.1.2") holds all of your work, independent of B's work. It could represent a major effort that you couldn't afford to lose. If you don't save it somewhere, the merge makes #3 *disappear* under a potential rat's nest of conflicts caused by overlapping changes. I have been saved a few times, and others I support have been saved hundreds of times, by the ability to "diff ", which can be done in the example above by the Unix shell command: "cvs -p -r 1.2 | diff - .#.1.2". The assumption is that the ".#" files will be useful far beyond the "commit" point, but not forever. You are expected to run the "normal" Unix cleanup script from "cron", which removes "#*" and ".#*" files older than a some period chosen by your sysadmin, usually ranging from 7 to 30 days. A question was raised about the need for #3 after #5 has been committed, under the assumption that you won't commit files until everything is exactly as you like them. This assumes perfect humans, which violates one of the Cardinal rules of Software Engineering: Never assume any form of discipline on the part of the users of software. If the restrictions are not bound into the software, then you, the toolsmith, have to arrange a recovery path. In other words, I've seen every possible variety of screwup you can imagine in #5. There is no way to make assumptions about what "should" happen. I've seen #5 filled with zeros because of NFS failures, I've seen emacs core dumps that leave #5 in an unreasonable state, I've seen a foolish developer uppercase the whole file (with his "undo" size set low so he couldn't undo it) and decide that it would be less work to play with the uppercased file than to blow it away and start over. I've even seen committed files with conflict markers still in them. There are all sorts of scenarios where having #3 is incredibly useful. You can move it back into place and try again. 2D.10 What is this "ignore" stuff? The "update" and "import" commands use collections of Unix wildcards and they skip over files matching any of those patterns. You may add to the built-in ignore list by adding wildcards to the following places: (They are read in this order.) 1. In a file named "cvsignore" in $CVSROOT/CVSROOT. A Repository Administrator uses this to add site-specific files and patterns to the built-in ignore list. 2. In a file named ".cvsignore" in your home directory. For user-specific files. For example, if you use "__" as your default junk file prefix, you can put "__*" in your .cvsignore file. People who play around in the X tree might want to put "Makefile" in their ignore list, since they are all generated and usually don't end up in the Repository. 3. In the CVSIGNORE environment variable. For session-specific files. 4. Via the '-I' option on "import" or "update" commands. For this-command-only files. 5. In a file named ".cvsignore" within each directory. The contents of a ".cvsignore" file in each directory is temporarily added to the ignore list. This way you can ignore files that are peculiar to that directory, such as executables and other files without known suffix patterns. In any of the 5 places listed above, a single '!' character nulls out the ignore list. A Repository administrator can use this to override, rather than enhance, the built-in ignore list. A user can choose to override the system-wide ignore list. For example, if you place "! *.o *.a" in your .cvsignore file, only *.o *.a files, plus any files a local-directory .cvsignore file, are ignored. 2D.11 Why does .cvsignore not ignore directories? Ignore lists are intended to be per-directory wildcards matching various patterns. They are matched against file names, not directory names or relative paths ('/' is an invalid character in an ignore list). I suppose it could be extended, but as it stands, it only works on files. This might change in the future. 2D.12 Is it safe to interrupt CVS using Control-C? It depends on what you mean by "safe". ("Ah," said Arthur, "this is obviously some strange usage of the word *safe* that I wasn't previously aware of." -- Hitchhiker's Guide to the Galaxy) You won't hurt the underlying RCS files and if you are executing a command that only *reads* data, you will have no cleanup to do. But you may have to hit Control-C repeatedly to stop it. CVS uses the Unix "system" routine which blocks signals in the CVS parent process. A single Control-C during "system" will only halt the child process, usually some form of RCS command. If you don't hit another Control-C while the CVS process has control, it is likely to continue onto the next task assuming that the earlier one did its job. It is not enough to hit two Control-C's. You might simply kill two child processes and not interrupt CVS at all. Depending on the speed of your processor, your terminal and your fingers, you might have to hit dozens of Control-C's to stop the damn thing. Executing a CVS command, such as "commit" or "tag" that writes to the files is a different matter. Since CVS is not a full-fledged database, with what database people call "commit points", merely stopping the process will not place you back in the starting blocks. CVS has no concept of an "atomic" transaction or of "backtracking", which means that a command can be half-executed. First, you will usually leave lock files that you have to go clean up in the Repository. Example1: If you interrupt a multi-file "commit" in the middle of an RCS checkin, RCS will leave the file either fully checked-in or in its original state. But CVS might have been half-way through the list of files to commit. The directory or module will be inconsistent. To recover, you must remove the lock files, then decide whether you want to back out or finish the job. To back out, you'll have to apply the "admin -o" command, very carefully, to remove the newly committed revisions. This is usually a bad idea, but is occasionally necessary. To finish, you can simply retype the same commit command. CVS will figure out what files are still modified and commit them. It helps that RCS doesn't leave a file in an intermediate state. Example2: If you interrupt a multi-file "tag" command, you have a problem similar, but not equivalent, to interrupting a "commit". The RCS file will still be consistent, but unlike "commit", which only *adds* to the RCS file, "tag" can *move* a tag and it doesn't keep a history of what revision a tag used to be attached to. Normally, you have little choice but to rerun the command and allow it to tag everything consistently. You might be able to recover by applying a raw "rcs -n" to the Repository, or by using the "cvs admin" equivalent. Halting a new "checkout" should cause no harm. If you don't want it, "release" (or rm -rf) it. If you do want it, rerun the command. Halting "update" half-way will give you some strange collection of files and revisions. You'll have to examine the output from the command and take a look at each file that was modified. Good Luck. 2D.13 How do I turn off the "admin" command? In the current revision, you'd have to edit the source code. 2D.14 How do I turn off the ability to disable history via "cvs -l"? In the current revision, you'd have to edit the source code. 2D.15 How do I keep certain people from accessing certain directories? If you don't try to run CVS set[ug]id, you can use Unix groups and protection modes to limit access to the Repository. If you only want to limit "commit" commands, you can write a program to put in the "commitinfo" file. In the "contrib" directory, there is a script called "cvs_acls.pl" that implements a form of access control. ======================================== == Section 3 ==== Commands ==== ======================================== This section contains questions that are easily recognized to be about a single command, usually of the form: "Why does the 'xyz' command do this?" I won't provide patches here that are longer than a few lines. Patches are referred to in this section are available in the FTP archive described toward the beginning of this document. ---------------- -- Section 3A -- "add", "ad", "new" ---------------- **** Questions: 3A.1 What is "add" for? =3A.2 How do I add a new file to the branch I'm working on? #3A.3 Why did my newly added file end up in the Attic? =3A.4 How do I put a new file on the Main Branch and branch off from there onto my default branch? **** Answers: 3A.1 What is "add" for? To add a new directory to the Repository or to register the desire to add a new file to the Repository. The directory is created immediately, after verification, while the file is recorded in the local CVS administrative directory. To really add the file to the Repository, you must then "commit" it. =3A.2 How do I add a new file to the branch I'm working on? See section 4C.8 #3A.3 Why did my newly added file end up in the Attic? Your new file is placed in the Attic if it is added onto a side branch without ever showing up on the trunk. If the file were in the main Repository area, it would show up when the Main branch is checked out. You didn't commit it onto the Main branch -- only onto the side branch. =3A.4 How do I put a new file on the Main Branch and branch off from there onto my default branch? See section 4C.8 ---------------- -- Section 3B -- "admin", "adm", "rcs" ---------------- **** Questions: 3B.1 What is "admin" for? 3B.2 Wow! Isn't that dangerous? 3B.3 What would I normally use "admin" for? 3B.4 What should I avoid when using "admin"? 3B.5 The -i flag in the modules file can restrict commits. How do I turn off the "admin" command? **** Answers: 3B.1 What is "admin" for? To provide direct access to the underlying "rcs" command, which is not documented in this FAQ 3B.2 Wow! Isn't that dangerous? Yes. Though you can't hurt the internal structure of an RCS file using its own "rcs" command, you *can* change the underlying RCS files using "admin" in ways that CVS can't handle. If you feel the need to use "admin", create some test files with the RCS "ci" command and experiment on them with "rcs" before blasting any CVS files. 3B.3 What would I normally use "admin" for? Normally, you wouldn't use admin at all. In unusual circumstances, experts can use it to set up or restore the internal RCS state that CVS requires. You can also use the '-o' (for "outdate") option to remove revisions you don't care about. 3B.4 What should I avoid when using "admin"? Never use "admin" to alter branches (using the '-b' option), which CVS takes very seriously. If you change the default branch, CVS will not work as expected. If you create new branches without using the "tag -b" command, you may not be able to treat them as CVS branches. When trying to outdate old revisions, make sure you don't have "Tags" you still need attached to the revisions you are about to remove. Also, don't outdate any branch points, even the ones that are not physical branches in the RCS files but are only represented by magic CVS branch tags. If you don't understand the above, you should not use the admin command at all. [[I know there's more, but I've drawn a blank.]] 3B.5 The -i flag in the modules file can restrict commits. How do I turn off the "admin" command? At this writing, to disable the "admin" command, you will have to change the program source code, recompile and reinstall. ---------------- -- Section 3C -- "checkout", "co", "get" ---------------- **** Questions: 3C.1 What is "checkout" for? 3C.2 What is the "module" that "checkout" takes on the command line? 3C.3 Isn't a CVS "checkout" just a bunch of RCS checkouts? 3C.4 What's the difference between "update" and "checkout"? 3C.5 Why can't I check out a file from within my working directory? 3C.6 How do I avoid dealing with those long relative pathnames? 3C.7 Can I move a checked-out directory? Does CVS remember where it was 3C.8 How can I avoid losing the ability to lock files on checkout? **** Answers: 3C.1 What is "checkout" for? To acquire a copy of a module (or set of files) to work on. All work on files controlled by CVS starts with a "checkout". 3C.2 What is the "module" that "checkout" takes on the command line? It is a name for a directory or a collection of files in the Repository. It provides a compact name space and the ability to run before and after daemons based on definitions in the modules file. See question 1D.10. 3C.3 Isn't a CVS "checkout" just a bunch of RCS checkouts? Like many parts of CVS, a similar RCS concept is used to support CVS functions. But a CVS checkout is *not* the same as an RCS checkout. Differences include: 1. CVS does not lock the files. Others may access them at the same time. 2. CVS works best when you provide a name for a collection of files (a module or a directory) rather than an explicit list of files. 3. CVS remembers what revisions you checked out and what branch you are on, simplifying later commands. 3C.4 What's the difference between "update" and "checkout"? The "checkout" and "update" differ in the following ways: 1. The "checkout" command always creates a directory, moves into it, then becomes equivalent to "update -d". 2. The "update" does not create directories unless you add the '-d' option. 3. "Update" is intended to be executed within a working directory created by "checkout". It doesn't take a "module" or "directory" argument, but figures out what Repository files to look at by reading the CVS administrative directory in your working directory. 4. The two commands generate completely different types of records in the "history" file. The two commands are equivalent in nearly all other respects. 3C.5 Why can't I check out a file from within my working directory? You normally check out a module or directory, not a file. And you normally do it only once at the beginning of a project. After the initial "checkout", you can use the "update' command to retrieve any file you want within the checked-out directory. There is no need for further "checkout" commands. If you want to retrieve another module or directory to work on, you must provide names for both where to find it in the Repository and where to put it on disk. The "modules" file and your current directory supply two pieces of naming information. While inside a checked-out working directory, the CVS administrative information provides most of the rest. You should be careful not to confuse CVS with RCS and use "checkout" in the RCS sense. An RCS "checkout" is closer to an "update" in the CVS environment than a "checkout". 3C.6 How do I avoid dealing with those long relative pathnames? This question has also been phrased: How do I avoid all those layers of directories on checkout? or Why do I have to go to the top of my working directory and checkout some long pathname to get a file or two? This type of question occurs only among groups of people who decided not to use "modules", for one reason or another, and only hand "checkout" relative pathnames within the Repository. When you hand the "checkout" command a relative pathname, rather than a module name, all directories in the path are created, maintaining the same directory hierarchy as in the Repository. The same kind of environment results if you specify a "module" that is really an alias pointing to relative pathnames rather than module names. If you use "module" names, "checkout" creates a single directory by the name of the module in your current directory. This "module" directory becomes your working directory. The "module" concept combines the ability to "name" a collection of files with the ability to structure the Repository so that consistent sets of files are checked out together. It is the responsibility of the Repository Administrators to set up a modules file that describes the software within the Repository. I consider it unfortunate that CVS sprouted the ability to check out relative pathnames rather than a more extensive and flexible support for "modules." 3C.7 Can I move a checked-out directory? Does CVS remember where it was checked out? Yes and Yes. The "./CVS/Repository" file in each working directory contains a pathname pointing to the matching directory within the Repository. The pathname is either absolute or a pathname relative to $CVSROOT, depending on how you configured CVS. When you move a checked-out directory, the CVS administrative files will move along with it. As long as you don't move the Repository itself, or alter your $CVSROOT variable, the moved directory will continue to be usable. CVS remembers where you checked out the directory in the "history" file, which can be edited, or even ignored if you don't use the "working directory" information displayed by the "history" command. 3C.8 How can I avoid losing the ability to lock files on checkout? How can you "lose" something that wasn't there in the first place? Or are you attached to some old model of how to work with files that you learned from using raw RCS commands? Think about why you want that ability. RCS locking is there to keep people from breaking individual files. CVS does the same task a different way. If you are only looking for the consistency aspect, then you should just forget about locking. For normal development, there is no need for CVS to lock anything. If you want to restrict access to parts of the Repository, see the question in section 4B on "Limiting Access". ---------------- -- Section 3D -- "commit", "ci", "com" ---------------- **** Questions: 3D.1 What is "commit" for? 3D.2 If I edit ten files, do I have to type "commit" ten times? 3D.3 Explain: cvs commit: Up-to-date check failed for `' 3D.4 What happens if two people try to "commit" conflicting changes? 3D.5 I committed something and I don't like it. How do I remove it? 3D.6 Explain: cvs commit: sticky tag `V3' for file `' is not a branch 3D.7 Why does "commit -r BRANCH_TAG" put new files in the attic? **** Answers: 3D.1 What is "commit" for? To store new revisions in the Repository, making them visible to other users. 3D.2 If I edit ten files, do I have to type "commit" ten times? No. The "commit" command, like all CVS commands, will work on the whole directory by default. Just type: "cvs commit". It commits only files that "update" would show as "M"odified. 3D.3 Explain: cvs commit: Up-to-date check failed for `' You may not "commit" a file if your BASE revision (i.e. the revision you last checked out or retrieved via "update") doesn't match the HEAD revision (i.e the latest revision on your branch, usually the Main Branch). In other words, someone committed a revision since you last ran "update". You must now run "update" to merge the other person's changes into your working directory before "commit" will work. You are thus protected (somewhat) from a common form of race condition in source control systems, where a second checkin of minor changes from the same base file obliterates the changes made in the first. Normally, the "update" command's auto-merge should be followed by another round of building and testing before the "commit". 3D.4 What happens if two people try to "commit" conflicting changes? Conflicts can occur only when two developers check out the same revision of the same file and make changes. The first developer to commit the file has no chance of seeing the conflict, only the second one runs into it, usually when faced with the "Up-to-date" error explained in the previous message. There are two types of conflicts: 1. When two developers make changes to the same section of code, the auto-merge caused by "update" will print a 'C' on your terminal and leave "overlap" markers in the file. You are expected to examine and clean them up before committing the file. (That may be obvious to *some* of you, but . . .) 2. A more difficult problem arises when two developers change different sections of code, but make calls to, or somehow depend on, the old version of each other's code. The auto-merge does the "right" thing, if you view the file as a series of text lines. But as a program, the two developers have created a problem for themselves. This is no different from making cross-referential changes in *separate* files. CVS can't help you. In a perfect world, you would each refer to the specification and resolve it independently. In the real world you have to talk/argue, read code, test and debug until the combined changes work again. Welcome to simultaneous development. 3D.5 I committed something and I don't like it. How do I remove it? Though you *can* use the "admin -o" command to delete revisions, unless the file you committed is so embarrassing that the need to eradicate it overrides the need for being careful, you should just grab an old version of the file ("update -p" might help here) and commit it on top of the offending revision. 3D.6 Explain: cvs commit: sticky tag `V3' for file `' is not a branch The message implies two things: 1. You created your working directory by typing "checkout -r V3", or you recently typed "update -r V3". 2. The tag named V3 is not a branch tag. CVS remembers any '-r ' arguments handed to the "checkout" or "update" commands. This is the "sticky" part. The TAG/revision is recorded as the CVS working branch, which is the branch to which "commit" will add a new revision. Branch tags are created when you use the -b switch on the "tag" or "rtag" commands. They are magic tags that don't create a physical branch, but merely register the desire to do so. The first commit to a magic branch creates a physical branch in the RCS files. You can commit onto the end of the Main Trunk, if you have no sticky tag at all, or onto the end of a branch, if you have a sticky branch tag. But you can't commit a file that has a sticky tag not pointing to a branch. CVS assumes a TAG/revision that does not refer to a branch is attached to the middle of a series of revisions. You can't squeeze a new revision between two others. Scenario1: If you don't want a branch and were just looking at an old revision, then you can move back to the Main Branch by typing: cvs update -A {optional files - default is whole directory} Scenario2: If you really wanted to be on a branch and made an earlier mistake by tagging your branch point with a non-branch tag, you can recover by adding a new branch tag to the old non-branch tag: cvs rtag -b -r OLDTAG NEWTAG (It was not a big mistake. Branch-point tags can be useful. But the newtag must have a different name.) If you don't know the name or don't use "modules", you can also use "tag" this way: cvs update -r OLDTAG cvs tag -b NEWTAG . Then, to put your working directory onto the branch, you type: cvs update -r NEWTAG You can't delete OLDTAG before adding NEWTAG, and I would not advise deleting the OLDTAG at all, because it is useful in referring to the branch point. If you must, you can delete the non-branch tag by: cvs rtag -d OLDTAG or cvs tag -d OLDTAG . Scenario3: If you made the same mistake as in Scenario2, but really want "OLDTAG' to be the name of your branch, you can execute a slightly different series of commands to rename it and move your working directory onto the branch: cvs rtag -r OLDTAG BRANCH_POINT_TAG cvs rtag -d OLDTAG cvs rtag -b -r BRANCH_POINT_TAG OLDTAG Then, if you really must, you can delete the BRANCH_POINT_TAG: cvs rtag -d BRANCH_POINT_TAG Note: The unwieldy mixture of "tag" and "rtag" is mostly because you can't specify a revision (-r TAG) to the "tag" command. 3D.7 Why does "commit -r BRANCH_TAG" put new files in the attic? This was a design choice. If the file doesn't already exist on the Main branch, committing it directly to the BRANCH will stuff it into the Attic. Such files are skipped over when checking out the Main Branch because the file isn't on that branch. If it didn't go into the Attic, you would be simultaneously committing the new file to the Main branch at the same time as committing it to the Branch you are working on. This is an undesirable side-effect. The Attic is a way to keep track of files that are no longer on the Main Branch, or ones that were *never* on the Main Branch. The file can be retrieved by using the '-r BRANCH_TAG' option on a "checkout" or "update" command. See Section 4C, on Branching, for many more details. ---------------- -- Section 3E -- "diff", "di", "dif" ---------------- **** Questions: 3E.1 What is "diff" for? 3E.2 Why did "diff" show nothing when there are committed revisions beyond what I have in my directory? 3E.3 How do I display what changed in the Repository since I checked out or last updated? 3E.4 How do I display the difference between my working file and what I checked in last Thursday? 3E.5 Why can't I pass the +unified (or --unified) option to "diff"? **** Answers: 3E.1 What is "diff" for? To display the difference between your working file and a committed revision: cvs diff -r or between two committed revisions: cvs diff -r -r Without explicit file names, it "diffs" the whole directory. Without explicit revision numbers, it "diffs" your working file against the BASE revision, which is the one you checked out or last updated. 3E.2 Why did "diff" show nothing when there are committed revisions beyond what I have in my directory? By default, "diff" displays the difference between your working file and what you last updated (i.e. the BASE revision). If you haven't made any changes since then, there is no difference. To display the difference between your working file and the latest revision committed to your current branch, type: cvs diff -r HEAD 3E.3 How do I display what changed in the Repository since I checked out or last updated? All "diff" commands are the same, once you know how to specify the revisions you want to compare. A special tag named "BASE" always refers to the revision you checked out or last updated. Another special tag named "HEAD" always refers to the latest revision on your working branch. To compare BASE and HEAD, you type: cvs diff -r BASE -r HEAD 3E.4 How do I display the difference between my working file and what I checked in last Thursday? cvs diff -D "last Thursday" where "last Thursday" is a date string. Many formats are understood. See the man page under '-D date_spec' for details. 3E.5 Why can't I pass the +unified (or --unified) option to "diff"? There are a few reasons: 1. CVS passes through only arguments it knows about, because a few arguments are captured and interpreted. 2. CVS only parses single character '-X' arguments, not the FSF long options. (They recently changed their long-option command prefix from '+' to '--' to conform to POSIX.) 3. If you didn't configure RCS and CVS to use the GNU version of diff, long options wouldn't work even if future versions of CVS grow the ability to pass them through. Most of the long options have equivalent single character options, which do work. The '--unified' option is '-u' in GNU diff since revision 1.15. ---------------- -- Section 3F -- "export", "exp", "ex" ---------------- **** Questions: 3F.1 What is "export" for? 3F.2 Why does it remove the RCS keywords so I can't use the "ident" command on the source files? 3F.3 Can I override the -kv flag CVS passes to RCS? 3F.4 Why the hell not? 3F.5 Why does export -D check out every file in the Attic? **** Answers: 3F.1 What is "export" for? "export" checks out a copy of a module in a form intended for export outside the CVS environment. The "export" command produces the same structure and source files as the "checkout" command, but it doesn't create "CVS" sub-directories and it removes all the RCS keywords from the files. 3F.2 Why does it remove the RCS keywords so I can't use the "ident" command on the source files? I don't know. 3F.3 Can I override the -kv flag CVS passes to RCS? No. 3F.4 Why the hell not? I don't know. [[I need something here.]] 3F.5 Why does export -D check out every file in the Attic? See the explanation of the same problem with "update -D" contained in section 5B. ---------------- -- Section 3G -- "history", "hi", "his" ---------------- **** Questions: 3G.1 What is "history" for? 3G.2 Of what use is it? 3G.3 What is this, Big Brother? 3G.4 I deleted my working directory and "history" still says I have it checked out. How do I fix it? 3G.5 So I *can* edit the History file? 3G.6 Why does the history file grow so quickly? 3G.7 What is the difference between "cvs history -r TAG/rev" and "cvs history -t TAG"? 3G.8 Why does "cvs history -c -t TAG" fail to print anything? 3G.9 "cvs history -a -o" only printed one line for each checked-out module. Shouldn't it print all the directories where the modules are checked out? 3G.10 I can't figure out history, can you give me concrete examples? **** Answers: 3G.1 What is "history" for? To provide information difficult or impossible to extract out of the RCS files, such as a "tag" history or a summary of module activity. 3G.2 Of what use is it? I have found it useful in a number of ways, including: 1. Providing a list of files changed since - A tagged release. - Yesterday. - Someone changed the DEFAULT kernel config file. 2. Providing a list of special events: - Files added or removed since one of the above events. - Merge failures since one of the above events. (Where did the conflicts occur?) - Has anyone (and who) updated to the revision of this file I committed last week, or are they still working blind? 3. Telling me how often a file/directory/module has been changed. 4. Dumping a summary of work done on a particular module, including who last worked on it and what changed. 5. Displaying the checked-out modules and where they are being worked on. 6. To tell me what users "joe" and "malcolm" have done this week. 3G.3 What is this, Big Brother? War is Peace. Freedom is Slavery. Ignorance is Strength. Normally manager types and those with the power to play Big Brother don't care about this information. The Software Engineer responsible for integration usually wants to know who is working on what and what changed. Use your imagination. 3G.4 I deleted my working directory and "history" still says I have it checked out. How do I fix it? In later versions of CVS, you can use the '-f' option which forcibly adds a "release" record to the history file. If your version of "release" doesn't have the '-f' option, you have to edit the $CVSROOT/CVSROOT/history file. You can remove the last "O" line in the history file referring to the module in question or add an "F" record. 3G.5 So I *can* edit the History file? Yes, but if you are using history at all, you should take a little care not to lose information. I normally use Emacs on the file, since it can detect that a file has changed out from under it. You could also copy and zero out the history file, edit the copy and append any new records to the edited copy before replacing it. 3G.6 Why does the history file grow so quickly? It stores "U" records, which come in handy sometimes when you are tracking whether people have updated each other's code before testing. There should (and probably will sometime) be a way to choose what kinds of events go into the history file. The contributed "cln_hist.pl" script will remove all the "U" records, plus matching pairs of "O" and "F" records during your normal clean up of the history file. 3G.7 What is the difference between "cvs history -r TAG/rev" and "cvs history -t TAG"? The '-t' option looks for a Tag record stored by "rtag" in the history file and limits the search to dates after the last TAG of the given name was added. The '-r' option was intended to search all files looking for the TAG in the RCS files. It takes forever and needs to be rewritten. 3G.8 Why does "cvs history -c -t TAG" fail to print anything? You have been using "tag" instead of "rtag". The "tag" command currently doesn't store a history record. This is another remnant of the earlier firm believe by CVS in "modules". 3G.9 "cvs history -a -o" only printed one line for each checked-out module. Shouldn't it print all the directories where the modules are checked out? Not as designed. Command Question it is supposed to answer. ---------------- ---------------------------------------------- cvs history -o What modules do I have checked out? cvs history -a -o cvs history -o -w What working directories have I created and what modules are in them? cvs history -a -o -w (The -o option, checked out modules, is the default history report.) 3G.10 I can't figure out history, can you give me concrete examples? Default is just for yourself. Add one or more '-u user' options or -a (for all users) to get records other than for yourself. * Checked out modules: cvs hi * Added files since creation: cvs hi -x A * Modified files since creation: cvs hi -c * Modified files since last Friday: cvs hi -c -D 'last Friday' * Modified files since TAG was added: cvs hi -c -t TAG * Modified files since TAG on files: cvs hi -c -r TAG * Last modifier of file/Repository X? cvs hi -c -l -[fp] X * Modified files since string "str": cvs hi -c -b string * Tag history: cvs hi -T * History of file/Repository/module X: cvs hi -[fpn] X * Module report on "module": cvs hi -m module ---------------- -- Section 3H -- "import", "im", "imp" ---------------- **** Questions: 3H.1 What is "import" for? 3H.2 How am I supposed to use "import"? 3H.3 Why does import put files on a branch? Why can't you put it on the Main Trunk and let me work on a branch? 3H.4 Is there any way to import binary files? 3H.5 Why does CVS "import" corrupt some binary files? 3H.6 How do I keep "import" from expanding all the $\Revision$ strings to be 1.1.1.1? 3H.7 I imported some files for the Yarg compiler that looks for files with a suffix of ".yarg". When I check them out, they will no longer compile because they have this junk in them. Why? 3H.8 How do I make "import" save the timestamps on the original files? 3H.9 Why didn't "import" ignore the directories I told it to? 3H.10 Why can't I "import" 3 releases on different branches? 3H.11 What do I do if the Vendor adds or deletes files between releases? 3H.12 What about if the Vendor changes the names of files or directories, or rearranges the whole structure between releases? 3H.13 I thought "import" was for Vendor releases, why would I use it for code of my own? Do I have to use import? 3H.14 How do I import a large Vendor release? **** Answers: 3H.1 What is "import" for? To place a copy of a tree of files into the CVS Repository. Each file is placed on the Vendor branch. 3H.2 How am I supposed to use "import"? Create source a directory containing only the files you want to import. Make sure you clean up any cruft left over from previous builds or editing. You want to make sure that the directory contains only what you want to call "source" from which everything else is built. "cd" into your source directory and type: cvs import -m "Message" Repository Vendor-Tag Release-Tag where Message is the checkin string to be stored in the RCS files. Repository is a relative path starting at $CVSROOT. Vendor-Tag is a string you use to identify the Vendor who sent you the files you are importing. Subsequent releases *must* use the same Vendor-Tag, which you can find later by using "cvs log". Release-Tag is a string that identifies the particular release of this software by the vendor. For example, if the FSF, CVS, Make and I are alive in the year 2015, I'll import version 89.53 of GNU make this way: cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53 3H.3 Why does import put files on a branch? Why can't you put it on the Main Trunk and let me work on a branch? The CVS "Main Branch" and the RCS Main Trunk are not the same. See section 4C, on Branching. 3H.4 Is there any way to import binary files? See question 4D.1 on Binary files. 3H.5 Why does CVS "import" corrupt some binary files? Import doesn't do it. The RCS "co" command does it when it is by a CVS "checkout" or "update". The RCS "co" command looks for certain sequences of characters, such as $\Id$, and expands them into revision, file and date information. If RCS keyword strings show up in a binary file, they will be altered unless you use the '-ko' option on the RCS files to tell RCS to keep the original keyword values and not to expand new ones. cvs admin -ko See question 4D.1 on Binary files. 3H.6 How do I keep "import" from expanding all the $\Revision$ strings to be 1.1.1.1? If you want to leave old RCS keywords as they are, you can use the '-ko' trick described above. In the future, "import" might sprout a '-ko' option of its own, so you don't have to execute two commands. 3H.7 I imported some files for the Yarg compiler that looks for files with a suffix of ".yarg". When I check them out, they will no longer compile because they have this junk in them. Why? YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> YARG> $\Log: # Revision 1.3 1998/03/03 00:16:16 bubba # What is 2+2 anyway? # # Revision 1.2 1998/03/03 00:15:15 bubba # Added scorekeeping. YARG> YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS know about your suffix or your comment prefix. So you have three choices: 1. Head into the Repository and tell all the files about your prefix by typing: rcs -c"YARG> " <*,v> 2. Check out the Yarg-less module, and type: cvs admin -c"YARG> " Then delete the broken files and type "update". 3. Go into the import.c file in the CVS sources and add the .yarg suffix, along with the "YARG> " comment prefix to the "comtable" array. If you ever plan to add new files with $\Log in them, you should also go into the RCS sources and make the same change in the table contained in the "rcsfnms.c" file. 3H.8 How do I make "import" save the timestamps on the original files? In the released CVS 1.3, there is no way. In the coming patch release, there will supposedly be a '-d' option to save the dates of the files rather than the current date. See question 4D.8 for more details. 3H.9 Why didn't "import" ignore the directories I told it to? See Question 2D.11. 3H.10 Why can't I "import" 3 releases on different branches? I'll bet you typed something like this: cd /src/blasto.v2 cvs import -b 1.1.2 VENDOR2 Version2 cd /src/blasto.v3 cvs import -b 1.1.3 VENDOR3 Version3 cd /src/blasto.v4 cvs import -b 1.1.4 VENDOR4 Version4 This is wrong, or at least it won't help you much. You have created three separate Vendor branches, which is probably not what you wanted. Earlier versions of CVS, as described in Brian Berliner's Usenix paper, tried to support multiple Vendor branches on the theory that you might receive source for the *same* program from multiple vendors. It turns out that this is very rare, whereas the need to branch in *your* development, for releases and for project branches, is much greater. So the model now is to use a single vendor branch to contain a series of releases from the same vendor. Your work moves along on the Main Trunk, or on a CVS branch to support a real "branch in development". To set this up, you should type this instead of the above: cd /src/blasto.v2 cvs import VENDOR Version2 cd /src/blasto.v3 cvs import VENDOR Version3 cd /src/blasto.v4 cvs import VENDOR Version4 3H.11 What do I do if the Vendor adds or deletes files between releases? Added files show up with no extra effort. To handle "removed" files, you should always compare the tree structure of the new release against the one you have in your Repository. If the Vendor has removed files since the previous release, go into a working directory containing your current version of the sources and "cvs remove" (followed by "cvs commit" to make it really take effect) each file that is no longer in the latest release. Using this scheme will allow you to "checkout" any version of the vendor's code, with the correct revisions and files, by using "checkout -r Version[234]". 3H.12 What about if the Vendor changes the names of files or directories, or rearranges the whole structure between releases? Currently CVS can't handle this cleanly. It requires "renaming" a bunch of files or directories. See question 4B.9 on "renaming" for more details. What I generally do is to close the Repository for a while and make changes in both the Repository and in a copy of the vendor release until the structure matches, then run the import. If you ever have to check out and build an old version, you may have to use the new, or completely different Makefiles. 3H.13 I thought "import" was for Vendor releases, why would I use it for code of my own? Do I have to use import? For code you produce yourself, "import" is a convenience for fast insertion. It is not necessary. You can just as easily checkin all the files using the RCS "ci" command and move the resulting *,v files into the Repository. See section 4B, on Setting up and Managing the Repository. 3H.14 How do I import a large Vendor release? When the sum of the changes made by the Vendor and the changes made by local developers is small, "import" is not a big problem. But when you are managing a large Repository, any care taken up front will save you time later. Read this, but before running "import", see the questions in Section 4C dealing with branch merges and Vendor branch merges. 1. The first step is to make sure the structure of the new files matches the structure of the current Repository. Run "find . -print | sort" on both trees and "diff" the output. 2. Alter the "source" tree until the "diff" (of the list of filenames, not of the whole trees) shows that the structures are equivalent. 3. If they deleted any files, you can handle them cleanly with "cvs remove". 4. If they renamed any files, you have to make a permanent and unrecoverable change to the Repository if you want to retain the combined change log. If you just want to leave the old file for "cvs checkout -r OLDTAG" to find, then do a "cvs remove" on the old file and allow import to stuff the new one in. See question 4B.9 on renaming files. 5. When you have dealt with "cvs remove", run the import: cd cvs import -m "Message" Where is a directory pathname relative to the head of your Repository (i.e. $CVSROOT). The directory must be at the same relative level as the relative path you give. (I realize this is not obvious. You should experiment first.) is the Tag you assigned to the Vendor. It must be the same for every import to the Vendor branch. is an arbitrary Tag for this particular release. It has to be unique and it is good to use something mnemonic. 6. *SAVE* the output from the import command. 7. There will be seven categories of files to deal with. (Actually there are nine, but you have already dealt with "removed" and "renamed" files.) a. Ignored file. CVS prints: I filename You'll need to examine it to see if it *should* have been ignored. Alternatively, you can examine every file in the "find" at the beginning and use the "import -I !" option to avoid ignoring anything. b. Symbolic link. CVS prints: L linkname Links are "ignored", but you'll probably want to create a "checkout helper" function to regenerate them. c. New file. CVS prints: N filename CVS creates a new file in the Repository. You don't have to do anything to the file, but you might have to change Makefiles to refer to it. d. A file unchanged by the Vendor since its last release. CVS prints: U filename CVS will notice this and simply add the new ReleaseTag to the latest rev on the Vendor branch. No work will be needed by you, whether you have changed the file or not. No one will notice anything. e. A file changed by the Vendor, but not by you. CVS prints: U filename CVS should add the file onto the vendor branch and attach the Release Tag to it. When you next run "update" in any working directory you'll get the new revision. f. A file changed by both the Vendor and by you. CVS prints: C filename These are the trouble files. For each of these files (or in groups -- I usually do one directory at a time), you must execute: cvs update -j -j It will print either 'M' (if no overlaps) or 'C', if overlaps. If a 'C' shows up, you'll need to edit the file by hand. Then, for every file, you'll need to run "cvs commit". See Section 4C dealing with branch merges. ---------------- -- Section 3I -- "log", "lo", "rlog" ---------------- **** Questions: 3I.1 What is "log" for? 3I.2 How do I extract the log entries between two revisions? 3I.3 How do I extract the log entries on a whole branch? 3I.4 How do I generate ChangeLogs from RCS logs? 3I.5 Why does "log" tell me a file was checked in 5 hours later than I know it was? **** Answers: 3I.1 What is "log" for? To provide an interface to the RCS "rlog" command, which prints out information, including the revision history, about a file. 3I.2 How do I extract the log entries between two revisions? If both and are on the same branch, you can get what you are looking for with: cvs log -r: If either or contain '-' characters, it will complain and fail due to RCS's continued support of '-' as an alternate range character. and can be tag/symbol names, but they have to be on the same branch, whether they are numeric or symbolic. 3I.3 How do I extract the log entries on a whole branch? cvs log -r where must be a branch revision (one with an even number of dots) or a *non-branch" tag on a branch revision. 3I.4 How do I generate ChangeLogs from RCS logs? There is a script called rcs2log that might appear in the CVS FTP archive. [[or where?]] 3I.5 Why does "log" tell me a file was checked in 5 hours later than I know it was? RCS file dates are stored in GMT. To allow the same files to be accessed in different timezones (through some remote file system) and agree on dates, some standard form must be used. The only other choice besides GMT is to put the timezone information in all the date stamps, which changes the format incompatibly. ---------------- -- Section 3J -- "patch", "pa", "rdiff" ---------------- **** Questions: 3J.1 What is "patch" for? 3J.2 Why does patch include files from the Attic when I use '-D'? +3J.3 How do I make "patch" produce a patch for one or two files? It seems to work only with modules. **** Answers: 3J.1 What is "patch" for? To produce a "diff" between tagged releases to be handed to the "patch" command at other sites. This is the standard way that source patches are distributed on the network. 3J.2 Why does "patch" include files from the Attic when I use '-D'? See the explanation of the same problem with "update -D" contained in section 5B. +3J.3 How do I make "patch" produce a patch for one or two files? It seems to work only with modules. Patch is intended for producing patches of whole modules between releases. For a few files, you should use the "diff" command with the '-c' context option: cvs diff -c -r -r filenames The patch command will be able to merge such a "diff" into your source files. If the version of "diff" you are using supports the '-u' option to produce the more compact "Unidiff" format, the latest revisions of the patch command understand that too. ---------------- -- Section 3K -- "release", "re", "rel" ---------------- **** Questions: 3K.1 What is "release" for? =3K.2 Why does release -d delete directories within my directory that weren't ever in the CVS Repository? 3K.3 Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs release path/name/subdir" without an "unknown module name"? 3K.4 Why can't I "release" portions of a checked out directory? I should be able to "release" any file or sub-directory within my working directory. -3K.5 I removed the tree that I was about to start working on. How do I tell cvs that I want to release it if I don't have it anymore? =3K.6 Why doesn't "release -d module" reverse a "checkout module"? =3K.7 Why can't I release a module renamed with "cvs checkout -d"? **** Answers: 3K.1 What is "release" for? To register that a module is no longer in use. It is intended to reverse the effects of a "checkout" by adding a record to the history file to balance the checkout record and by optionally allowing you to delete the checked-out directory associated with the module name. =3K.2 Why does release -d delete directories within my directory that weren't ever in the CVS Repository? A simplistic implementation. (I can say this -- I wrote it.) The "release" function was written under the assumptions that the "module name" is a first class, unavoidable interface to the Repository, allowing no way to retrieve anything other than by module name and a module is a self-contained entity with no foreign directories allowed. Though it is easier to program that way, many users of CVS believe the modules support to be too primitive to allow such a limitation. Since "release" was written, other parts of CVS broke those assumptions. And it hasn't been upgraded. Yet. 3K.3 Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs release path/name/subdir" without an "unknown module name"? Again, "release" is too primitive. It believes, truly *believes* in modules, not relative paths. I can't *believe* how many times I've been asked this. It was a hack of the moment with a particular use in mind. I had no idea it was going to cause so much trouble. I'll *fix* it already. :-) 3K.4 Why can't I "release" portions of a checked out directory? I should be able to "release" any file or sub-directory within my working directory. Again, "release" believes in modules. Breaking it into bits wasn't part of the plan. In the future, "release" might become sophisticated enough to handle both the reversal of a "checkout" and the deletion of random portions of the working directory, but it isn't that way now. -3K.5 I removed the tree that I was about to start working on. How do I tell cvs that I want to release it if I don't have it anymore? See question 3G.4. =3K.6 Why doesn't "release -d module" reverse a "checkout module"? It does, if you are using "module" in a way that "release" expects: a non-alias string in the left column of the "modules" database. If "module" is really an alias, or if you are using a relative path in the place of "module", or if you renamed the directory with the -d option in the modules file or on the "checkout" command line, then the current version of "release" won't work. Future versions of "release" will probably fix most of these. =3K.7 Why can't I release a module renamed with "cvs checkout -d"? The current version of "release" doesn't know how to track the renaming option ('-d') of the "checkout" command. It will probably be fixed in the future. ---------------- -- Section 3L -- "remove", "rm", "delete" ---------------- **** Questions: 3L.1 What is "remove" for? 3L.2 Why doesn't "remove" work on directories? 3L.3 I don't like removing files. Is there another way to ignore them? 3L.4 I just removed a file. How do I resurrect it? 3L.5 Why doesn't "remove" delete the file? Instead, it prints: cvs remove: no files removed; use `rm' to remove the file first **** Answers: 3L.1 What is "remove" for? To remove a file from the working branch. It removes a file from the main branch by placing it in an "Attic" directory. 3L.2 Why doesn't "remove" work on directories? Oversight. It should be able to delete an empty directory, but you still don't have a way to remember when it was there an when it disappeared to allow the -D option to work. You'll have to remove the working directory and the matching directory in the Repository. 3L.3 I don't like removing files. Is there another way to ignore them? There's no reason to be hasty in using the "remove" command. If there is a way to ignore files in your build procedures, I'd just do that. Later, when you decide that the files are really ancient, you can execute a "remove" command to clean up. The CVS "ignore" concept can't ignore files already in CVS. 3L.4 I just removed a file. How do I resurrect it? If you executed "remove", but haven't typed "commit" (you can tell this by the 'R' notation that "update" prints next to the file), you can execute "add" to reverse the "remove". If you followed the "remove" with a "commit", you'll have to move it back out of the Attic by hand: I use something like this: set repos = `cat CVS/Repository` mv $repos/Attic/filename,v $repos/filename,v (If you use relative paths in your Repository files, that first line becomes: set repos = $CVSROOT/`cat CVS/Repository`) While a file is in the Attic, you can't "add" another file by the same name. To add such a file you either have to move it by hand as in the above, or delete it from the Attic. The main reason for the Attic is to retain files with tags in them. If you execute: "update -r OLDTAG", files with OLDTAG attached to some revision will be taken from the normal Repository area and from the Attic. That's why you can't "add" a file with the same name. "remove" only moves a file off a branch, it doesn't obliterate it. 3L.5 Why doesn't "remove" delete the file? Instead, it prints: cvs remove: no files removed; use `rm' to remove the file first Design choice. Unix software written within last decade, usually require an extra verification step, such as answering a question or adding a flag on the command line. CVS currently requires that you delete the file first. [[I'd go for a new '-f' switch that deletes an existing file.]] ---------------- -- Section 3M -- "rtag", "rt", "rfreeze" ---------------- (See the "tag" section below for questions in common with "rtag".) **** Questions: 3M.1 What is "rtag" for? 3M.2 Why would you use "rtag"? It assumes a static Repository. **** Answers: 3M.1 What is "rtag" for? To add a symbolic label (a "tag") to the last committed revisions of a module directly in the Repository. 3M.2 Why would you use "rtag"? It assumes a static Repository. Though the "tag" command is more useful in marking the revisions you have in a particular working directory, "rtag" is much handier for whole-Repository actions, which occur at major release boundaries. ---------------- -- Section 3N -- "status", "st", "stat" ---------------- **** Questions: 3N.1 What is "status" for? 3N.2 Why does "status" limit the File: at the top to 17 characters? **** Answers: 3N.1 What is "status" for? To display the status of files, including what revision and branch you are working on. 3N.2 Why does "status" limit the File: at the top to 17 characters? Designed that way to line up with other data. You can look at the RCS version line, which is not limited in length. ---------------- -- Section 3O -- "tag", "ta", "freeze" ---------------- **** Questions: 3O.1 What is "tag" for? 3O.2 What is the difference between "tag" and "rtag"? 3O.3 Why does "tag -b" not put a tag on the Branch Point revision? How do I refer to the Branch Point? 3O.4 So we've labeled a bunch of files. What do you use a Tag for? 3O.5 How do I get "tag" and "rtag" to send mail the way "commit" does? 3O.6 Why can't "tag" handle the -r option that "rtag" takes? 3O.7 I ran "tag" in my working directory. When it is checked it out with -r , why don't they get a copy of my current work? 3O.8 Why doesn't "cvs tag" write a history record? **** Answers: 3O.1 What is "tag" for? To add a symbolic label (a "tag") to the RCS files last checked out (or updated) in a working directory. 3O.2 What is the difference between "tag" and "rtag"? The end result of both commands is that a tag, or symbolic name, is attached to a particular revision of a collection of files. The differences lie in: 1. How they name the collection of files to work on: "rtag" refers to a collection of files by "module" name, defined in the modules file. "tag" refers to files and directories in the working directory (assumed to be the current directory). Once named, both commands recursively follow directory hierarchies. 2. And what revision it chooses to tag. "rtag" places the tag on the latest committed revision of the branch specified by the '-r' option, by default, the Main Branch. "tag" places the tag on the BASE (i.e. last checked out or updated) revisions of all the files found in the working directory. 3O.3 Why does "tag -b" not put a tag on the Branch Point revision? How do I refer to the Branch Point? Design decision. If everything works perfectly, the "update -j" command will do the merge you need and you don't need to check up on it by playing with the branch point revision. The '-b' option attaches a magic branch tag to the selected revision. References to the branch tag are equivalent to references to the latest revision on the branch. There is no way to refer to the branch point without adding a non-branch tag. In fact, if you don't add the non-branch tag at the same time as (or before) the branch tag, you won't be able to do it in the future. Your best bet is to attach a non-branch tag first, then retag the non-branch tag with a second magic branch tag: cvs tag BRANCH_POINT_1 cvs rtag -b -r BRANCH_POINT_1 BRANCH_1 3O.4 So we've labeled a bunch of files. What do you use a Tag for? You use it to "checkout" the labeled collection of files as a single object, referring to it by name. Anywhere a revision number can be used a Tag can be used. In fact tags are more useful because they draw a line through a collection of files, marking a development milestone. The way to think about a Tag is as a curve drawn through a matrix of filename vs. revision number. Consider this: Say we have 5 files (in some arbitrary modules, some are in 2 or three different modules by name, some are in 2 or 3 by virtue of the tree structure) with the following revisions: file1 file2 file3 file4 file5 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 1.2*- 1.2 1.2 -1.2*- 1.3 \- 1.3*- 1.3 / 1.3 1.4 \ 1.4 / 1.4 \-1.5*- 1.5 1.6 At some time in the past, the '*' versions were tagged. Think of the TAG as a handle attached to the curve drawn through the tagged revisions. When you pull on the handle, you get all the tagged revisions. Another way to look at it is that you draw a straight line through the set of revisions you care about and shuffle the other revisions accordingly. Like this: file1 file2 file3 file4 file5 1.1 1.2 1.1 1.3 _ 1.1 1.2 1.4 1.1 / 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here 1.3 1.6 1.3 \_ 1.4 1.4 1.5 I find that using these visual aids, it is much easier to understand what a TAG is and what it is useful for. 3O.5 How do I get "tag" and "rtag" to send mail the way "commit" does? The "commit" command is supported by two files ("commitinfo" and "loginfo") not used by other commands. To do logging the same way for "tag" and "rtag" would require another file like loginfo -- it currently doesn't exist. The "rtag" command requires a "module" entry, which can specify a "tag" program using the '-t programname' option on the module line. There is no equivalent support for "tag". 3O.6 Why can't "tag" handle the -r option that "rtag" takes? Oversight. The answer is probably "Fixed in a Future Release." 3O.7 I ran "tag" in my working directory. When it is checked it out with -r , why don't they get a copy of my current work? The only reason this would fail, other than misspelling, is that you didn't "commit" your work before "tagging" it. Only committed revisions may be tagged. Modified files are not marked for later tagging. 3O.8 Why doesn't "cvs tag" write a history record? In cvs 1.2, "tag" worked on the Repository like "rtag" does now. The current "tag" functionality was added between 1.2 and 1.3 as an option (something like "tag -l" for "local"). The "rtag" command would be used to place major "release" tags onto modules. The "tag" functionality was developed to *move* the more significant tag when slight changes to individual files sneaked in after the release tag as stamped onto the Repository. The significant event, was the "rtag", which was recorded in the "history" file for the "history -t" option to work. It turns out that "tag" is more useful than "rtag", so the model has changed. Future revisions of CVS will probably store both kinds of tags in the history file. ---------------- -- Section 3P -- "update", "up", "upd" ---------------- **** Questions: 3P.1 What is "update" for? 3P.2 What do 'U', 'M' and 'C' mean when I type "update"? 3P.3 What's the difference between "update" and "checkout"? 3P.4 Why don't I get new files when I execute "update"? 3P.5 Why does "update -j" say "M" both for files I have modified and they haven't and for files that we both modified, when the Merge showed no errors. Aren't they different? 3P.6 After a merge ("update -j"), why doesn't it remember the conflicts and not allow you to commit the result until the conflict is resolved? 3P.7 Is there a feature to tell me what I have changed, added and removed without changing anything? 3P.8 Why does "cvs update" not flag directories that are not in the Repository as it does with new files? 3P.9 Why are all my files deleted when I run "update"? **** Answers: 3P.1 What is "update" for? The "update" command is by far the most important command and is probably also the most used command. It has five purposes: (And many options.) 1. To show the status of files in your working directory. Though a plain "update" shows the status, it does so after possibly altering your working directory. To see the status of all files without changing anything, type: cvs -n update {optional list of files} 2. To merge changes made to the branch you are working on. Each working directory is attached to a branch, usually the Main branch. To merge changes made by other people to your working branch by other people into your working files, type: cvs update {optional list of files} 3. To merge changes made to another branch into the branch you are working on. If you want to take a whole branch from the branch point, which is assumed to be on the Main Branch, to the end of the branch, you type: cvs update -j BRANCH_TAG {optional list of files} If you want to grab the changes made between two tags or revisions, you type: cvs update -j TAG1 -j TAG2 {optional list of files} (If you are working with a single file, the TAGs could also be revisions numbers. Unless you take really unusual care to match revision numbers across different files (a waste of time given the way TAGS work), using revision numbers in places of the TAGs for multiple files would be meaningless.) 4. To move your working directory to another branch. To move to a tagged branch, type: cvs update -r BRANCH_TAG {optional list of files} To move to the Main Branch, type: cvs update -A {optional list of files} 5. To retrieve old revisions of files. This option is similar to 4 above but you are not restricted to BRANCH_TAGS. You may specify any revision or Tag with '-r' and get the specified revision or the tagged revision: cvs update -r TAG/Revision {optional list of files} Or you may specify any date with '-D': cvs update -D '3 days ago' {optional list of files} The '-p' option sends the revisions to your terminal rather than setting the "sticky" tag and changing the files. 3P.2 What do 'U', 'M' and 'C' mean when I type "update"? The "update" command normally merges changes from the Repository that others have made to your working branch. It will resolve conflicts semi-automatically. Question 4C.6 describes what the letters mean for merging in from another branch. The output is almost the same for a normal update, if you consider the Repository as the branch and your working directory as the "trunk". The "cvs -n update" command will print lines beginning with 'U' for files you have not modified that have changed in the Repository. 'M' for files you have modified that have not changed in the Repository. 'C' for files you have modified that have been changed in the Repository too. The "cvs update" command will print lines beginning with 'U' after replacing your unmodified file with a later revision from the Repository. 'M' for two different reasons: 1. for files you have modified that have not changed in the Repository (as in the previous 'M' description) 2. after the merge (without conflicts) into your working directory of changes made in the Repository since your last "checkout" or "update". 'C' after the merge (with conflicts) into your working directory of changes made in the Repository since your last "checkout" or "update". You will need to remove the conflicts by editing the file. Conflicts are surrounded by <<<<< and >>>>> markers. 3P.3 What's the difference between "update" and "checkout"? See question 3C.4 above. 3P.4 Why don't I get new files when I execute "update"? There are five main reasons for nothing to happen during an "update": 1. Nothing changed on your branch. If no one has committed anything to the branch you are working on (normally the Main branch) since the last time you executed "checkout" or "update", nothing will happen. It's like shouting "xyzzy" or "plugh" in the wrong room. 2. You have a "sticky" non-branch tag or date. At some time in the past you checked out or updated your directory with the '-r TAG' or '-D date' option. Until you do it again with a different tag or date, or go back to the Main Branch with "update -A", you will never again see any updates. 3. The ./CVS/Entries.static file exists and you are expecting a new file. If your ./CVS administrative directory contains an Entries.Static file, no files will be checked out that aren't already in the Entries file. 4. You forget to use the '-d' option and are looking for new directories. If you execute "update" without the '-d' option, it will not create new directories that have been added to the Repository. 5. You typed "update" instead of "cvs update". And now your disk caches are furiously being flushed by multiple update daemons, destroying performance and proving to management that you need more CPU power. :-) 3P.5 Why does "update -j" say "M" both for files I have modified and they haven't and for files that we both modified, when the Merge showed no errors. Aren't they different? Design choice. Yes, they are different internally, but the actions you are expected to take are the same -- you type "cvs diff" and what you see should be what you changed by hand. Another case of "same difference" having real meaning. 3P.6 After a merge ("update -j"), why doesn't it remember the conflicts and not allow you to commit the result until the conflict is resolved? A complicated problem. When do you decide that the conflict has been resolved? You could look at the modification time of the file as a hint, or even search the file for the conflict markers. Maybe in a future release. 3P.7 Is there a feature to tell me what I have changed, added and removed without changing anything? The command "cvs -n update" will do exactly that. 3P.8 Why does "cvs update" not flag directories that are not in the Repository as it does with new files? Design choice. Because directories are handled specially. You can aim "cvs update" and any random directory and it will traverse the whole tree beneath it, looking for CVS administrative directories. When it finds one, it will run "normal" update. Printing a '?' for each directory would get really ugly in a big tree of files, only some of which is under CVS. 3P.9 Why are all my files deleted when I run "update"? You probably executed "update -r TAG" some time ago, then removed that tag from the Repository files. "update -r TAG" will delete a file that doesn't contain the TAG. A way to fix this is to "cd" into your working directory and type: cvs update -A If you don't want the latest revisions on the Main (or Vendor) Branch, then decide what TAG (normal or branch) you want and type: cvs update -r THE_TAG_YOU_WANT Another way to make files disappear is to execute "update -D " where is before the date stamped onto the first revision in the RCS file. =============================================== == Section 4 ==== Advanced Topics ==== =============================================== ---------------- -- Section 4A -- Installing CVS ---------------- **** Questions: 4A.1 What do I have to know before I install CVS? 4A.2 How do I configure the CVS programs? 4A.3 Besides CVS, what do I have to install? =4A.4 How do I get around the bugs I've heard of GNU diff version 2.2? **** Answers: 4A.1 What do I have to do before I install CVS? 1. You need to find a place to put the Repository. CVS does not support a distributed Repository. You can have multiple Repositories, but each one must be mounted (not copied or "rdist"ed) from a single place onto all machines where it will be used. Initially, a Repository takes about same amount of disk space as the sources you want to put into it, plus a bit of overhead for the RCS files. 2. You need a directory in everyone's $PATH variable where you can install all the executables. /usr/local/bin is a common place. 3. You need some helper tools besides CVS such as "RCS" and a good set of "diff" and "diff3" programs. Suggestion: grab the GNU version of diff. 4. Make sure you have versions of all the programs mentioned in the "cvs/src/config.h" file. 5. Though you can probably muddle along without it, you should appoint one or more "Repository Administrators" who will be responsible for maintaining the Repository structure, data files and the "modules" interface. Someone at your site should probably be on the info-cvs mailing list. 4A.2 How do I configure the CVS programs? 1. You should certainly start by reading the README file, the INSTALL files and possibly the Makefiles and "cvsinit" program. 2. Edit the "config.h" file in the "src" directory. Read it carefully. You will need to specify a number of site-specific pieces of information including the names of a number of functions. Hint1: You really want to set the DIFF macro to use your version of the GNU diff program with the '-a' option. Ours is set to "gdiff -a". Hint2: You probably want to use RCS 5.5 or greater and set the "HAVE_RCS5" macro. 3. Run ./configure. 4. Type "make". 4A.3 Besides CVS, what do I have to install? 1. The "cvs" executable and "mkmodules" from the CVS sources. (The man page is useful too.) 2. Versions of all the programs mentioned in the config.h file, most of which are available in standard Unix. 3. Unless you plan to do a lot of recoding, you must install RCS. 4. The Repository control files, created by "cvsinit", which you should read. 5. Any helper programs mentioned in the modules file. =4A.4 How do I get around the bugs I've heard of GNU diff version 2.2? See question 4D.11 ---------------- -- Section 4B -- Setting up and Managing the Repository ---------------- **** Questions: =4B.1 What do I do first? How do I create a Repository? 4B.2 What are those files in $CVSROOT/CVSROOT? 4B.3 Is there any other state in the Repository besides in the $CVSROOT/CVSROOT directory? 4B.4 How do I put sources into the Repository? 4B.5 What file protection modes do I use on the Repository? 4B.6 How do I structure my Repository? 4B.7 How do I manage the modules file? 4B.8 Why would anyone use "modules"? They are too restrictive. I want to be able to select just the files I want to edit. =4B.9 How do I rename a file or directory? What are the consequences? 4B.10 What are "Attic" directories? 4B.11 Is it OK to remove anything from the Repository to save space? 4B.12 Can I convert to CVS from RCS without losing my revision history? =4B.13 Can I move RCS files with branches in them into the Repository? 4B.14 Can I use raw RCS commands on the Repository? 4B.15 How do I convert from SCCS to RCS? 4B.16 How do I limit access to the Repository? =4B.17 What are the Repository Administrator's responsibilities? +4B.18 How do I move the whole Repository? **** Answers: =4B.1 What do I do first? How do I create a Repository? First, install everything. (See section 4A.) Then create a Repository by running "cvsinit", which works only from within the head of the CVS source directory. (It needs files from the distribution to work.) (If you want a very primitive Repository and don't want to save history, refer to modules, or use any of the "info" files for logging, pre-commit checks, or editing templates, you can dispense with "cvsinit" entirely.) The cvsinit program will create a short modules file containing the module named "CVSROOT". Execute: cvs checkout CVSROOT and read the information stored in the files that are checked out. You will certainly want to add modules of your own. Edit the "modules" file and add lines to describe the items you want to "checkout" by module name. Here's a short list that could be used for storing a small number of GNU and PD sources: local local gnu local/gnu emacs local/gnu/emacs cvs local/gnu/cvs public local/public pdprog1 local/public/pdprog1 pdprog2 local/public/pdprog2 test test junk test/junk When you are done editing, "commit" the modules file. If you configured CVS to use "dbm", you might have to edit and commit the modules file twice, in order to change the pathname of the mkmodules program in the modules file. Try using the "import" command to insert the "junk" module and play around until you are comfortable. 4B.2 What are those files in $CVSROOT/CVSROOT? There are seven Repository control (or "database") files of interest in the CVSROOT directory: 1. commitinfo contains two columns. The first is a regular expression to compare against a relative pathname within the Repository before a "commit". The second contains a command line to execute if the first column matches the committed file. A pathname of DEFAULT is matched if nothing else matches. A pathname of ALL always matches and is run separately. The program is called with the directory name and a list of files within that directory as arguments. 2. rcsinfo contains the same first column as commitinfo, but the second column is a template file for specifying the log entry you are required to enter for each commit. DEFAULT and ALL work the same as in commitinfo. 3. editinfo contains the same two columns as commitinfo, but the program in the second column is intended to do some consistency checking on the commit log. DEFAULT works as in commitinfo. 4. loginfo contains the same two columns as commitinfo, but the program is expected to read a log message from its standard input and append it to log or send it to mailing lists. DEFAULT and ALL work the same as in commitinfo. 5. cvsignore contains "ignore" patterns that are added to the built-in list. See Section 2D.10 6. history contains a stream of text records, one for each event that the "history" command is interested in. Though the contents of the history file can be read, it is intended to be read and displayed by the "history" command. 7. modules The "modules" database. See sections 1D.10, 2C.7, 4B.7 and 4B.8 for more details. 4B.3 Is there any other state in the Repository besides in the $CVSROOT/CVSROOT directory? Only in the RCS files. The Repository holds exactly two things: the tree of RCS files (each usually ending in ",v") and the CVSROOT directory described above. 4B.4 How do I put sources into the Repository? There are three main ways to put files in the Repository: 1. The "import" command described in Section 3H. This method is the fastest way to put trees of new code into the Repository and the *only* way to handle source releases from a 3rd party software vendor. 2. The "add" command followed by a "commit". This is how you add new files to the Repository, one at a time. 3. You can move older RCS files directly into the Repository. It would probably be a good idea to create directories to hold them. 4B.5 What file protection modes do I use on the Repository? If you run a completely open environment (which usually means that you don't have, or don't want to waste, the time to deal with it): - Set all directories to mode 777. - Have everyone set their umasks to 0. (BTW, I am not suggesting this, merely reporting it.) If you are a normal Unix shop and want to use groups effectively: - Set all the directories in the Repository to mode 775. (If you are using a system that handles both System V and BSD filesystems, you might have to set the modes to 2775.) - Change all the groups on the directories to match the groups you want to write to various directories. - Make sure every user is in the appropriate groups. - Have everyone set their umask to 002. If you don't want non-group members to even read the files, do the above, but change: - Repository directory modes to 770. (or 2770) - Umasks to 007. 4B.6 How do I structure my Repository? The Repository holds your software. It can be all related or it can be a bunch of separately managed directories. How you break a whole system down into its component parts, while defining interfaces between them, is one aspect of "Software Engineering", a discipline that requires the study of dozens of strange and wonderful areas of the computer and management worlds. CVS provides a way to keep track of changes to individual files, a way to "tag" collections of files, and a way to "name" collections of files and directories. That's all. Everything else is in the way you apply it. In other words, you structure your Repository to match your needs, usually tied in with the other tools you use to build, install and distribute your work. Common needs include the ability to: - mount (or automount) multiple sub-directories from different places in your organization. - check out an appropriately sized piece. - check out multiple sections in a fixed relation to each other. - check out large sections to match the assumptions built into your build system. (Makefiles?) In my opinion, you should start small and keep everything in one tree, separating each major sub-systems in separate directories. Later, when you know what you are doing, you can make it more sophisticated. 4B.7 How do I manage the modules file? Once you have defined the structure of the Repository, the modules file is easy. You set up module names and aliases to match what you need to check out by name. If you like relative directories, it is possible, but not advised, to work completely without a modules file. See sections 1D.10 and 2C.7. 4B.8 Why would anyone use "modules"? They are too restrictive. I want to be able to select just the files I want to edit. Any form of structure is restrictive. If you believe that total chaos is a viable working paradigm, or if you believe you can keep track of the interrelations between all portions of your Repository in your head, then you can do what you please. If you believe that systems of files require management and structure, then the "modules" idea is very useful. It is a way to impose a naming scheme on a tree of files, a naming scheme that can be simpler than a large list of relative pathnames. The "modules" file represents a published interface to the Repository set up by your Repository Administrator. If s/he did a creditable job, the modules offered will be internally consistent and will smoothly interact with the rest of your environment. =4B.9 How do I rename a file or directory? What are the consequences? Currently CVS can't rename anything cleanly. A "renaming database" has been proposed that would keep track of name changes so that "update -r OLDTAG" would continue to work across the renaming. But as it stands, you have to pick one of the following poor options: 1. Move the files and directories in the Repository to the new names. - You save the revision history under a different file name. - You save a little space. - If you ever execute "update -r OLDTAG", you get the files with the new names and the Makefiles won't work. If you are clever you might be able to rework your Makefiles to be able to handle either the new or old names. Then you can move the OLDTAG to point to the new Makefile. (Yes, this changes the "released" file if OLDTAG indicates a release. But it is an option.) - Important Note: If you rename a directory, you must rename the corresponding directory in every checked-out working directory. At the same time, you must edit the pathname stored in the ./CVS/Repository file within each of the moved directories. The easiest way to move a lot of directories around is to tell everyone to remove their working directories and check them out again from scratch. 2. Copy (i.e. duplicate) the files and directories in the Repository to the new names. - You save the revision history in two places -- misleading. - I you ever "update -r OLDTAG", you get the right files, including working Makefiles. - "checkout" or "update -d" will give you an extra directory, but you can delete it and plain "update" won't bring it back. 3. For each file, execute "remove", rename the file and execute "add". (There is no way to do this with directories.) - This appears to be the best option, but you lose the connection of your working file to its past revision history. 4. Copy the working files and either use "import" or "add" & "commit" to put the files into the Repository by the new names. - This is essentially the same as #2, but you save the revision history in one place, but not in the files you will be working on. Without a "rename" command that keeps track of the history of renaming, I would probably do #1, and add a comment in the Makefile that says "If you are working before the tag "OLDTAG" was placed on the files, execute this: ln -s dir1 dir2". 4B.10 What are "Attic" directories? When you use the "remove" command on a file, CVS doesn't delete the file, it only registers your desire to delete it. When you "commit" a removed file, CVS moves the Repository's matching RCS file into a sub-directory within the Repository called "Attic". Attic files are examined when the '-r' or '-D' option is used on "checkout" or "update". If the specified revision, tag or date matches one on a file in the Attic, that file is checked out with the others. 4B.11 Is it OK to remove anything from the Repository? In general, removing anything from the Repository is a bad idea. The information in a deleted object is lost forever. There are many ways to skip over files, directories and revisions without deleting them. Here are some of the consequences of removing the following things stored in the Repository: 1. CVSROOT files (Repository control files) The Repository will work without any of them, but you should understand what you are losing by deleting them. See Section 4B.2 for more info. 2. Revisions The only way to remove revisions is to use the "admin -o" command (or the equivalent RCS command "rcs -o"). They are lost forever. Any tags formerly attached to deleted revisions are now pointing into Outer Space. 3. Files You should not remove a file unless you truly never want to see it again. If you want to be able to check out an old revision of this file, use "cvs remove" instead. 4. Tags Tags take up little space and you can't recover from deleting them. If you depend on tags for releases you will lose vital information. 5. Directories There is no Attic for directories, so the only way to remove them is to use "rm -r". They are gone forever. If you delete (or move) a directory, all checked-out versions of that directory will cause CVS to halt. You'll have to visit each checked-out directory and remove the matching working directory by hand. 6. Attic files The "remove" command sends files to the Attic. To really delete them, you have to go into the Attic and use "rm". If a file in the Attic has a TAG on it that you might ever want to check out again, you probably don't want to delete it. 7. Can I get rid of the "#cvs.[wr]fl.pid" files in the Repository? These are lock files. If you are getting "lock" errors and the dates on the lock files indicate that they are old, you can delete them. Deleting lock files still in use by a CVS process might produce unusual errors. 4B.12 Can I convert to CVS from RCS without losing my revision history? Yes, you can simply move (or copy) your RCS files into a directory within the Repository, check out that directory and start working. =4B.13 Can I move RCS files with branches in them into the Repository? Yes, but they may not work if you have used branches in a way that conflicts with CVS's assumptions: 1. You can't use .0. branches. (They are reserved for "Magic" branch tags.) 2. If you use branch 1.1.1, you can't use the Vendor branch. 3. To use other branches under CVS, you'll have to create branch tags for each branch you'll ever want to refer to. [[I haven't tested this. I suspect that branch numbers and normal branch tags will work. Do we have to go in and hand-craft magic tags?]] 4B.14 Can I use raw RCS commands on the Repository? You can use raw rcs commands directly on the Repository if you take a little care. The Repository itself contains no "CVS state" (as opposed to revision histories) outside the CVSROOT module. But using raw RCS commands to change branches, tags or other things that CVS depends on may render the files unusable. 4B.15 How do I convert from SCCS to RCS? You'll have to run something like "sccs2rcs" (in the CVS contrib directory) on every file. Then you can move the resulting RCS files into the Repository as described above. 4B.16 How do I limit access to the Repository? 1. You can use Unix groups and modes. 2. You can try the "setgid" trick described in question 4D.16. 3. You can catch every commit using the "commitinfo" file. 4. You can try to use the RCS access control lists, though I don't think CVS will handle them cleanly. 5. You can edit the source code to CVS. =4B.17 What are the Repository Administrator's responsibilities? 1. Examining the Repository once in a while to clean up: - Junk files left by people looking around. - Non-RCS files outside of CVSROOT. - Lock files left around after crashes. - Wrong protection modes, groups and ownerships. 2. Maintaining the modules file. 3. Maintaining the other Repository control files: commitinfo, loginfo, rcsinfo and editinfo files. 4. Storing site-specific ignore patterns in the "cvsignore" file. 5. Pruning the history file every once in a while. (Try the "cln_hist.pl" script in the "contrib" directory.) 6. Staying aware of developments on info-cvs and in the FTP archive. 7. Run "ps ax" once in a while and kill off any "update" programs not running as "root". It is too easy to leave the "cvs" off the front of the "cvs update" command. + 4B.18 How do I move the whole Repository? The repository itself contains pathnames only within the files in the CVSROOT directory. If helper functions in the modules file or logging programs executed out of the loginfo file point into the Repository, you'll have to change the pathnames to point to the new Repository location. The main change you'll have to make is to all the ./CVS/Repository files in the checked-out working directories. You have four choices: 1. If you can avoid changing $CVSROOT by using a symbolic link or mount point you don't have to do anything else. If you must change $CVSROOT, you must also tell everyone to change the CVSROOT environment variable in all running shells and in their "." files where it is set. Then pick one of the other three options that follow: 2. If all ./CVS/Repository files in all working directories contain relative pathnames, you don't have to do anything else. 3. Have everyone "release" or delete their working directories (after comitting, or just saving, their work) and check them all out again from the new Repository after the move. 4. Use a PERL or shell script to run through all the CVS/Repository files and edit the values in the files. ---------------- -- Section 4C -- Branching ---------------- **** Questions: 4C.1 What is a branch? =4C.2 Why (or when) would I want to create a branch? =4C.3 How do I create and checkout a branch? 4C.4 Once created, how do I manage a branch? 4C.5 Are there any extra issues in managing multiple branches? 4C.6 How do I merge a branch back into the trunk? 4C.7 How do I merge changes from the trunk into my branch or between branches? =4C.8 How do I add a new file to a branch? 4C.9 How do I know what branch I'm on? 4C.10 Do I really have to know the name of the branch I'm working on? 4C.11 How do I refer to the revision where I branched so I can see what changed since the Branch Point on another branch? 4C.12 Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 4C.13 Is it possible to set the "default CVS branch" for everyone? 4C.14 How do I perform a large merge? 4C.15 Is a Vendor merge any different from a branch merge? **** Answers: 4C.1 What is a branch? Unfortunately, the word "branch" is overloaded. It is used in too many different ways in three categories. It might help to understand some of the issues by going through them. 1. How Humans use the word "branch": Most development starts with everyone working on the same software, making changes and heading toward a single goal. This is called something like "Main Line Development". Note that though many people do main line development on CVS's "Main Branch", that is a choice, not a requirement. After a release or when one or more developers want to go off and work on some project for a while, the Software Engineers assigned to deal with large software issues generate a "Branch in Development" to support the release or project. (Keep in mind that a programmer is no more a Software Engineer than a carpenter is Civil Engineer.) Essentially, the word "branch" implies a way to allow simultaneous development on the same files by multiple people. The above terms are human-oriented. They refer to actions that people would like to take. They do *not* imply any particular implementation or set of procedures. Branches in development can be supported in many different ways. 2. How CVS uses the word "branch": CVS uses the word "branch" in a number of ways. The two most important are: - The vendor branch holds releases from (normally) an outside software vendor. It is implemented using a specific RCS branch (i.e. 1.1.1). - The "Main Branch", which normally holds your "Main Line Development", but is defined as the collection of revisions you get when you "checkout" something fresh, or when you use the '-A' option to "update". Important Note: The CVS "Main Branch" is *not* the same as the RCS concept with the same name. If you are using Vendor Branches, files you have never changed are on three branches at the same time: - The RCS 1.1.1 branch. - The CVS Vendor branch. - The CVS "Main Branch". The concepts overlap, but they are not equivalent. In referring to CVS, "branch" can be used in four other ways: - A CVS working directory satisfies the definition of "branch" for a single developer -- you are on a "virtual branch" that does not appear in any of the RCS files or the CVS control files. - The CVS "default branch" is the collection of files in your working directory. It is *not* the same as the RCS "default branch". Normally the CVS default branch is the same as the CVS Main branch. If you use the '-r' option to the "checkout" command, you will record a "sticky" tag that changes your "default branch " to the one you checked out. - A magic branch is a branch that hasn't happened yet. It is implemented by a special tag you can check out that is not attached to a real RCS branch. When you commit a file to a magic branch, the branch becomes real (i.e. a physical RCS branch). - And, of course, CVS uses "branch" to indicate a human-oriented "branch in development". 3. How RCS uses the word "branch": - The RCS "Main Branch" (Synonym: "The Trunk") contains a series of two-part revision numbers separated by a single "." (e.g. 1.2). It is treated specially and is the initial default branch. (The default default?) - The RCS "Default" branch starts out attached to the RCS "Main Branch". For RCS purposes, it can be changed to point to any branch. Within CVS, you *must*not* alter the RCS default branch. It is used to support the CVS idea of a "Main Branch" and it must either point to the RCS Main Branch or the Vendor Branch (1.1.1) if you haven't made any changes to the file. =4C.2 Why (or when) would I want to create a branch? Remember that you can think of your working directory as a "branch for one". You can consider yourself to be on a branch all the time because you can work without interfering with others until your project (big or small) is done. The four major situations when should create a branch are when: 1. You expect to take a long enough time or make a large enough set of changes that the merging process will be difficult. 2. You want to be able to "commit" and "tag" your work repeatedly without affecting others. If you ever think you need Source Control for yourself, create a branch. 3. You need to share code among a group of developers, but not the whole development organization working on the files. Rather than trying to share a working directory, you move onto a branch and share through "committing" your work to the branch. Developers not on the branch won't see your work unless they switch to your branch or explicitly merge your branch into theirs. 4. You need to make minor changes to a released system. Normally a "release" is labeled by a branch tag, allowing later work on the released files. If the release is labeled by a non-branch tag, it is easy to add a branch tag to a previously tagged module with the "rtag" command. If the release is not tagged, you made a mistake. Recovery requires identifying all revisions involved in the release and adding a tag to them. =4C.3 How do I create and checkout a branch? In short, you 1. "checkout" or "update" a working directory to contain the files you want to branch from. 2. Add a branch tag. 3. Move onto the branch by retrieving the tagged files. The branch tag is an unusual creature. It labels a branch in a way that allows you to "checkout" the branch, to "commit" files to the end of the branch and to refer to the end of the branch. It does not label the base of the branch (the branch point). Though not required, it might be a good idea, as mentioned in 4C.11, to add a non-branch tag before adding the branch tag. The non-branch tag referes to the branch point. (Future revisions of CVS might do this for you, tying the names together somehow. For now, you have to pick two names for the tags. I use a "BP_" prefix, for "branch point".) To add a non-branch tag, marking the branch point, execute: cvs tag BP_ . which places the BP_ on your last updated or committed revisions in your working directory. To add the branch tag, execute: cvs tag -b . which places the on the same working files. Then move your working directory to the new branch: cvs update -r If you know the branch tag is already attached to the files, you can checkout a branch directly with the following: cvs checkout -r Notes: - The '-r' option tells CVS to mark your directory (by storing in the CVS/Tag file) and the checked-out files (by storing on each file in the CVS/Entries file). - The is considered "sticky", which causes most CVS commands to use the as if it had been typed on the command line following a '-r' option. 4C.4 Once created, how do I manage a branch? The most important thing you should know about managing a branch is that the creation of a branch is not a lightweight act. When you create branches, you must also create a set of procedures to keep track of them. Specifically, you must: - Remember that the branch exists. (This is non-trivial if you create a lot of them.) - Plan when to merge it back into the main line of development. - Schedule the order that multiple branch merges are to be done. - If you ever intend to merge branches into each other, instead of limiting merges of branch work back into the "main line", you must keep careful track of which parts of which branches have merged into which other branches. The simplest way to deal with branches is to limit their number, "collapse" them back into the main line as quickly as is reasonable and forget them. If a group wants to continue working, tell them to create another branch off the fully merged main line. Remember that CVS is just a tool. Over time, it'll probably handle branching better, requiring less careful attendance. But no matter how good it becomes, the whole idea of "branching" is a complicated management problem. Don't take it lightly. 4C.5 Are there any extra issues in managing multiple branches? If you plan to split from the "main line" and merge back after a time, the only problem will be scheduling the order of branch merges. As each branch is merged, the main line must be rebuilt and tested. Merging multiple branches (i.e. "lines of development") before building and testing creates more problems than you are ready for. If you plan to collapse some branches into others, then move the combined branches back into the main line, you have to be careful with the revisions and tags you hand to your "update -j" command, but it shouldn't be much trouble. If you plan to allow every branch to incrementally take the work done on other branches, you are creating an almost insurmountable bookkeeping problem. Every developer will say "Hey, I can handle taking just this little bit," but for the system as a whole it is disaster. Try it once and see. If you are forced into this situation, you will need to keep track of the beginning and end points of every merge ever done. Good Luck. 4C.6 How do I merge a branch back into the trunk? If you don't have a working directory, you can checkout and merge in one command: cvs checkout -j cd If you already have a working directory: cd cvs update <<== Optional, to bring it up to date. cvs update -j CVS will print lines beginning with 'U' for files that you hadn't changed, but the branch did. 'M' for files that you changed and the branch didn't *and* for files that you both changed that were merged without overlaps. (this overload is unfortunate.) 'C' for files that you both changed in a way that conflicts with each other. You need to go edit all the 'C' files and clean up the conflicts. Then you must commit them. 4C.7 How do I merge changes from the trunk into my branch or between branches? The idea is similar to the above, but since CVS doesn't treat the main branch like other branches, you'll have to be more precise. Check out or "update" the files you want to merge into. Identify the two tags on the branch you want to merge from. (Revisions don't work too well because the same revision doesn't mean the same thing in different files.) Then type: cvs update -j -j You can use a to refer to the latest revision on the branch, but there is no built-in way to refer to the branch point. An alternative to merging is to identify a single revision you want, grab it by using "update -p" and commit it. If you do merges later, you'll get overlaps, but you get your file. In the future, (but not yet) merging from the main branch will look something like this: cvs update -j MAIN cvs commit -m "Log message" =4C.8 How do I add a new file to a branch? The obvious technique is broken in CVS 1.3. This is the way it is supposed to work: In a directory checked out (or updated) with the option -r , to add to the branch named you type: cvs add cvs commit Until the next release shows up, you must explicitly specify the branch_tag: cvs add cvs commit -r One not-so-obvious problem with this is that the file ends up in the Attic. It wasn't added to the Main Branch, so it doesn't show up in the main part of the Repository, only the Attic. You can add it to the Main Branch and branch off from there onto the side-branch this way: 1. Move the working file back to the main branch: cvs update -A 2. Add the file "normally": cvs add cvs commit 3. Branch-tag the file using the same as you did on all the other files in your directory: cvs tag -b 4. And move the file back onto the branch: cvs update -r 4C.9 How do I know what branch I'm on? Your working branch (or default branch) is attached to a directory by a "sticky" tag in the CVS/Tag file. The same tag is usually attached to each file by placing it in the CVS/Entries file. Normally, your branch can be displayed by typing: cat CVS/Tag But individual files can be on different branches and the "sticky" information is not just a Tag, so be careful. To make sure you are consistently on a particular branch, type: cvs update -r 4C.10 Do I really have to know the name of the branch I'm working on? If a developer can't be relied on to know what branch of development to work on, then either the developer's manager isn't planning branches properly or the developer has serious problems. I have found that one of the hardest concepts to get across to developers (and some managers) is that "a branch in development" (as opposed to the use of RCS branches to support some other scheme) is a heavyweight act. Every time you create a real branch in development, you must spawn a set of managerial procedures and a schedule by which you plan to merge each branch into each other branch. Unless you plan to keep it simple and collapse (by merging and forgetting) branches quickly, they are not to be created lightly. In other words, if there aren't group meetings in which the branch to be worked on is a major topic of discussion, then the group is not managing branches properly. We created a couple major branches a few months ago and even the customer service people refer to the "XYZ branch" as a shorthand for "continuing development on the XYZ project". 4C.11 How do I refer to the revision where I branched so I can see what changed since the Branch Point on another branch? Given the current Branch-tag format, there is no direct way to refer to the branch point, which is more useful in many ways than referring to the branch, which always refers to the latest revision on the branch. When CVS adds a branch tag, it attaches an RCS symbol to a non-existent revision number containing the revision number of the branch point as a prefix. (See Section 3O, on the "tag" command.) RCS can't refer to it and many of the CVS commands can't refer to it. To be certain of your ability to refer to a branch point, you must create your own tag at the same time as the Branch tag. 4C.12 Why didn't the command "cvs admin -bBRANCH1 *" create a branch? Because your command creates an RCS branch, not a CVS branch. See the above discussion on branches. RCS branches are used to support CVS branches, but they are not the same. You can't act as if you have direct control over the RCS files. The "admin" command was placed there as a convenience to allow you to run raw "rcs" commands on the Repository, taking advantage of CVS's ability to find the files in the Repository. But you have to remember that you are using RCS commands on a CVS Repository, which is not generally safe unless you know exactly what CVS depends on. For one thing, CVS insists on control of the default branch. It is set either to the Main branch or the Vendor branch depending on whether you have changed the Vendor's code. If you change the default branch, you are monkeying with the internals and will get unexpected results. To set your "default CVS branch" to BRANCH1, you must use "checkout" or "update" with the '-r BRANCH1' option. Then you have changed CVS's idea of your "default branch", which has little to do with RCS's default branch. 4C.13 Is it possible to set the "default CVS branch" for everyone? No. It doesn't work that way. When using CVS, all administrative information (such as what branch you checked out) is stored in CVS sub-directories, local to the user. There is no global state, other than the description and logging files in $CVSROOT/CVSROOT. You tell "checkout" or "update", via the '-r ' option, what branch you want to check out. The default is CVS's "Main Branch". I don't see a problem in *designing* a new way to indicate what branch you get by default, instead of the main one, but that's not how it currently works. 4C.14 How do I perform a large merge? Large merges require a bit more planning to be able to track what has happened in the inevitable cases where something goes wrong. No tool can make a "merge" make perfect sense. Though you can handle the details in many different ways, the two ends of the spectrum of merge techniques are: gonzo and paranoid. The gonzo method assumes that you know everything about your sources so that recovery from failures is "just a matter of typing." You created the branch this way: cvs checkout cd cvs tag -b cvs update -r >>>> Edit away. cvs commit <<== Onto branch Now that you need to merge your back into the Main Line, you know you can make it work, or at least detect all the failures, so you dive in and hack away: (For simplicity, we will assume you are collapsing (i.e. merging and forgetting) a side-branch into the Main branch from your single working directory.) cvs update -A cvs update -j >>>> Edit the "C" files and remove the overlaps. >>>> Edit some more to make it all compile and work. cvs commit Looks simple. For more details on the output from the "update -j" command, see section 4C above. (Note: You could also checkout a whole new working directory and perform the merge at the same time by replacing the two update commands with "cvs checkout -j ". The paranoid way is more difficult, but it can catch all sorts of problems. You created the branch this way: cvs checkout cd cvs tag cvs tag -b cvs update -r >>>> Edit away. cvs commit <<== Onto branch The extra tag command places a non-magic tag on the Branch Point, an act that makes it easier to do "diffs" later. Now we decide to perform the merge: cvs tag cvs update -A *1* cvs diff -r -r >>>> *1* holds all the changes on the branch. *2* cvs diff -r -r HEAD >>>> *2* holds all the changes on the trunk since branching. cvs tag cvs update -j >>>> Edit the "C" files and remove the overlaps. *3* cvs diff >>>> Verify that *3* matches *1*, except for line numbers and overlaps. cvs commit cvs tag >>>> Edit some more to make it all compile and work. cvs commit cvs tag The reason *3* and *1* match so closely is that they are the differences between two sets of starting points and ending points after the same data was inserted. If they are significantly different, you will want to figure out why. NOTE: You will have to tell everyone to stay the hell out of the Repository while you do this. If they commit something while you are in the middle of a merge, your job will be much more difficult. If they "update" at the wrong time, their work will be randomized until you finish. It's better to call a halt. 4C.15 Is a Vendor merge any different from a branch merge? No. In most ways, a Vendor branch is exactly the same as any other branch. In a Vendor merge, the data is append to the branch by the "import" command, rather than by hand-editing, but the merge process is the same. See the "import" command in section 3H. ---------------- -- Section 4D -- Tricks of the Trade ---------------- This section covers topics ranging from simple ideas that occur to every CVS user to time-saving procedures I consider difficult to understand. Some are therefore dangerous. Avoid anything you don't fully understand. **** Questions: 4D.1 How can you even check in binary files, let alone allow CVS to do its auto-merge trick on them? =4D.2 Can I edit the RCS (i.e. *,v) files in the Repository? 4D.3 Can I edit the CVS/{Entries,Repository,Tag} files? 4D.4 Someone ran "admin -o" and removed revisions to which tags/symbols were attached. How do I fix them? 4D.5 How do I move a magic branch tag? 4D.6 Can I use RCS locally to record my changes without making them globally visible by committing them? 4D.7 How can I allow shared access to the Repository by CVS and RCS at the same time? 4D.8 I "updated" a file my friend "bubba" committed yesterday. Why doesn't the file now have a modified date of yesterday? 4D.9 While I'm in the middle of a large "commit", how do I run other commands, like "diff" without getting lock errors? 4D.10 Why does the merge occasionally resurrect lines of code? 4D.11 Why does the merge fail when my "rcsmerge" program is configured to use GNU diff versions 2.1 and 2.2? 4D.12 What the hell is Entries.Static? 4D.13 Why did I get the wrong Repository in the loginfo message? 4D.14 Can I have multiple source repositories, one for each project? 4D.15 How do I run CVS setuid so I can only allow access through the CVS program itself? 4D.16 How about using groups and setgid() then? 4D.17 How do I use the "commitinfo" file? 4D.18 How do I use the "loginfo" files? **** Answers: 4D.1 How can you even check in binary files, let alone allow CVS to do its auto-merge trick on them? If you configure RCS and CVS to use the GNU version of diff with the '-a' option, CVS and RCS will handle binary files. See section 4A for configuration info. You also need to apply the '-ko' flag to the files to avoid expanding RCS keywords, which can be done via: cvs admin -ko filename (You should be able to do it by handing "import" the -ko option, but that isn't yet in the official release.) The only real problem occurs when "cvs update" attempts to merge binary revisions committed elsewhere into a modified working file. Since you very rarely have modified binary files in your working directory, this shouldn't be much of a problem. If you get hit with an auto-merge, you can always replace the merged (and therefore worthless) binary with the .#. that was saved and commit it. =4D.2 Can I edit the RCS (i.e. *,v) files in the Repository? Yes, but be very careful. The RCS files are not free-form files, they have a structure that is easily broken by hand-editing. The only time I would suggest doing this is to recover from emergency failures that are difficult to deal with using CVS or the "admin" command. Though no one actively encourages the editing of RCS files, many people have succumbed to the urge to do so when pressed for time. The reasons given, usually with evident contrition, include: - Editing mistakes out of the log entries. - Adding text to log entries. - Renaming or moving symbolic names. - Unlocking a file by changing the "locker" from someone else to yourself - Making global changes to past history. Example: Eradicating former employees names from old documents and Author entries. (And someone thought the "history" command was evidence of Big Brother! I had never realized how much help CVS/RCS could have provided to The Ministry of Truth.) 4D.3 Can I edit the CVS/{Entries,Repository,Tag} files? Yes, but with CVS 1.3 and later, there is almost no reason to edit any of the CVS administrative files. If you move pieces of your Repository around it can be faster to edit all the CVS/Repository files rather than checking out a large tree. But that is nearly the only reason to do so. 4D.4 Someone ran "admin -o" and removed revisions to which tags/symbols were attached. How do I fix them? It depends on what you mean by "fix". You can *remove* a tag, even if it is attached to a non-existent filename, by typing: cvs admin -N If you want to retain the tags, but make sure they point to valid revisions, you may be out of luck unless you can get a copy from a backup tape. The revision is deleted and gone. To attach the tag to something reasonable will require you to examine each revision and *pick* one, then type: cvs admin -N: 4D.5 How do I move a magic branch tag? If the tag refers to a physical branch within an RCS file, renaming a tag will make the existing branch in the file seem to disappear. This is not a good idea. If the magic branch has never had a revision committed to it, you can move the branch by rerunning the "tag" or "rtag" command that created it, aiming the tag at a different revision. 4D.6 Can I use RCS locally to record my changes without making them globally visible by committing them? You can, but it will probably confuse CVS to have *,v files in your working directory. And you will lose all your log entries when you finally commit it. Your best bet is to create your own CVS branch and work there. You can commit as many revisions as you want, then merge it back into the main line when you are finished. 4D.7 How can I allow shared access to the Repository by CVS and RCS at the same time? The first step is to try not to. If some people are using CVS, there is no reason for everyone not to. It is not hard to learn the basics and CVS makes certain operations *easier* than a series of RCS commands. Personal preference in what software tools can be applied to a shared Repository has to take second place to system integration needs. If you disagree, try writing some Lisp code for inclusion in your Unix kernel and see what kind of reception you get. If you really must allow routine RCS access to the CVS Repository, you can link an RCS sub-directory into a piece of the Repository: ln -s /Repository/some/directory/I/want RCS and RCS will work just fine. Those who are using RCS will have to keep the following in mind: 1. If a file was originally added to the Repository by "import" and has not been changed using CVS, the *RCS* default branch will remain attached to the Vendor branch, causing revisions checked-in by "ci" to wind up on the Vendor branch, instead of the main branch. Only CVS moves the RCS default branch on first commit. The way around this is to checkin (using "ci") all the files first and move them into the Repository. That way they won't have Vendor branches. Then RCS will work OK. 2. It is possible to use raw "rcs" and "ci" to make the files unusable by CVS. The same is true of the CVS "admin" command. 3. Normal RCS practice locks a file on checkout with "co -l". In such an environment, RCS users should plan to keep survival gear and food for at least 30 days near their desks. When faced with bizarre and unexpected protection errors, howling mobs of slavering CVS users will run the RCS users out of town with pitchforks and machetes. 4. Though files checked in by RCS users will correctly cause "up-to-date" failures during CVS "commits" and they will be auto-merged into CVS working directories during "update", the opposite won't happen. RCS users will get no warning and will not be required to merge older work into their code. They can easily checkin an old file on top of a new revision added by CVS, discarding work. See the howling mob scenario described above. RCS is great. I have used it for years. But I wouldn't mix it this way. You are asking for real trouble, both technical hassles to clean up and political hassles in a two-camp society. 4D.8 I "updated" a file my friend "bubba" committed yesterday. Why doesn't the file now have a modified date of yesterday? CVS restores dates from the RCS files only on first "checkout". After that, it is more important to maintain a timestamp relative to the other files in the working directory. Example: I commit a source file at 5PM. You commit the same file at 6PM. At 7PM, I compile my file. Then I execute "update". If it set the date to the one in the RCS file, the file would be given a date of 6PM and my Makefile wouldn't rebuild anything that depended on it. Bad news. When you first get a file, there is no reason to expect any particular date on the file within the work area. But later, it is more important to be consistent with the dates on the local files. 4D.9 While I'm in the middle of a large "commit", how do I run other commands, like "diff" without getting lock errors? Using CVS, you can't. CVS locks are 1-writer *or* 1-reader, when a case could be made for locks to be 1-writer *and* N-readers. You can delete the locks and confuse CVS slightly, or use raw RCS functions to read them. Instead of "cvs log ", I use something like this: rlog `cat CVS/Repository`/,v 4D.10 Why does the merge occasionally resurrect lines of code? The diff3 program provided by GNU diff version 1.15 has a bug that occasionally causes text to come back from the dead. If you plan to upgrade to the latest GNU diff program, see the next question. 4D.11 Why does the merge fail when my "rcsmerge" program is configured to use GNU diff versions 2.1 and 2.2? A change in the overlap format was introduced in GNU diff3 between versions 2.0 and 2.1. To get back the old rcsmerge behavior, you have four choices: 1. Go back to using GNU diff 1.15 or 2.0. If you insist on using GNU diff 2.1 or later, you'll have to pick one of the other three choices in this list. 2. Grab RCS version 5.6.0.1 from an FSF archive, set the DIFF3_A flag as it tells you to in the Makefile, build and install it. 3. Patch the RCS 5.6 source. Change line 84 in "merger.c" from: DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L", label[0], "-L", "", "-L", label[1], 4. Wait both for RCS version 5.7 to be released and for a new version of CVS that can deal with it. 4D.12 What the hell is Entries.Static? Each ./CVS administrative directory contains an Entries file, listing the files under CVS in the directory above it. If a new file is added to the Repository, an "update" command copies it out of the Repository and adds it to the Entries file. If your ./CVS directory has an Entries.Static file in it, CVS checks it before bringing new files out of the Repository. If a new file is *not* in Entries.Static, it is not checked out. The Entries.Static file is created by checking out something that doesn't include all files in a directory. Without an Entries.Static file, the first "update" would bring more files out of the Repository. Examples: - A multi-module checkout renamed with the "checkout -d" option. - Checking out a module specified with directory and filenames. The Entries.Static file is removed by an "update" with the '-A', '-r' or '-D' option. 4D.13 Why did I get the wrong Repository in the loginfo message? "commit" and all other CVS commands will heed the CVS/Repository file (and the '-d CVSrootdir' override), but the log function doesn't take arguments -- it just looks at $CVSROOT. 4D.14 Can I have multiple source repositories, one for each project? Yes, you can have as many Repositories as you like. You will have to change the $CVSROOT environment variable if you want to change projects. You can't just set it in your "." files at login time and forget it as you can when you use a single Repository. If you configure CVS to place absolute pathnames in your CVS/Repository files, $CVSROOT will only be used to check files out the first time (and in the "info" programs executed before and after "commits"). If you configure CVS to use relative pathnames in your CVS/Repository files, you must always be careful to set your $CVSROOT properly or you will get unexpected results. One monster of an unexpected result can happen when you have two modules or directories by the same name at the same relative path inside the Repository, in two different Repositories. You can update a directory with completely unrelated files. 4D.15 How do I run CVS setuid so I can only allow access through the CVS program itself? Setuid to root is not a great idea. Any program that modifies files and is used by a widely distributed group of users is not a good candidate for a setuid program. (The worst suggestion I've ever heard was to make *Emacs* setuid to root.) Root access on Unix is too powerful. Also, it might not work in some (secure?) environments. Running it setuid to some user other than root might work, if you add this line to main.c near the beginning: setuid(geteuid()); Otherwise it uses *your* access rights, rather than the effective uid's. Also, you have to invent a fake user whose name will show up in various places. But many sites, especially those who might want a setuid CVS for "security", want personal accountability -- no generic accounts. I don't know whether accountability outweighs file security. And finally, unless you take action to limit the "admin" command, you are leaving yourself unprotected anyway. 4D.16 How about using groups and setgid() then? Here is a way to run CVS setgid in some environments: 0. Stick this near the front of the main() in main.c: setgid(getegid()); This will allow "access" to work on systems where it only works on the real gid. 1. Create a group named "cvsg", for example. Name it as you wish. 2. Put *no* users in the "cvsg" group. You can put Repository administrators in this group, if you really want to. 3. Set the cvs executable to setgid (not setuid): cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs 4. Make sure every file in the Repository is in group "cvsg": chown -R root.cvsg $CVSROOT 5. Change all directories to mode 770. This allows all access to the files by the "cvsg" group (which has no members!) and no access at all to anyone else. find $CVSROOT -type d -exec chmod 2770 {} \; This should allow only the cvs program (or other setgid to group cvsg) programs to write into the area, but no one else. Yes the user winds up owning the file, but s/he can't find it again later since he can't traverse the tree. (If you use 775 on directories, the user who last wrote the file can still write to it.) If you want to allow read access, check out an entire tree somewhere. You have to do this anyway to build it. Notes: If you are using a stupid file system that can't inherit file groups from the parent directory (even with the mode 2000 bit set), you might have to modify CVS (or RCS) to reset the group every time you create a new file. I have not tested this. The setgid() method shares the "admin" problem with the setuid() method. 4D.17 How do I use the "commitinfo" file? Go read Section 4B.2 first. The "commitinfo" file allows you to execute "sanity check" functions before allowing a commit. If the function exits with a non-zero status, the commit is denied. To fill out a "commitinfo" file, ask yourself (and those sharing your Repository) these questions: - Is there anything you want to check or change before someone is allowed to commit a file? If not, forget commitinfo. - Do you want to execute the same exact thing before committing to every file in the Repository? (This is useful if you want to program the restrictions yourself.) If so, set up a single line in the commitinfo: DEFAULT /absolute/path/to/program CVS executes the program once for each directory that "commit" traverses, passing as arguments the directory and the files to be committed within that directory. Write your program accordingly. - Do you want to do something different for each set of directories? If so, you'll have to decide what to do for all directories and enter lines like this: regexp1 /absolute/path/to/program-for-regexp1 regexp2 /absolute/path/to/program-for-regexp2 DEFAULT /absolute/path/to/program-for-all-else Since the first match wins, you will have to order them properly. - Is there anything you want to happen before *all* commits, in addition to other pattern matches? If so, include a line like this: ALL /absolute/path/to/program It is executed independently of all the above. 4D.18 How do I use the "loginfo" files? See Section 4B.2 and the "commitinfo" question above. The "loginfo" file has the same format as the "commitinfo" file, but its function is different. Where the "commitinfo" information is used before a commit, the "loginfo" file is used after a commit. All the commands in the "loginfo" file should read data from standard input, then either append it to a file or send a message to a mailing list. If you want to make it simple, you can put shell (the shell used by "popen") commands lines directly in the "loginfo" (or "commitinfo") file. These seem to work: ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) > /path/name/to/log/file ---------------- -- Section 4E -- Weirdness ---------------- **** Questions: -4E.1 Explain: "ci error: unexpected EOF in diff output" -4E.2 Explain: "RCS file /Repository/module/file.c,v is in use" 4E.3 I don't want a Vendor branch. Why can't I work on the main trunk? =4E.4 Merges can't work. I don't trust them. If you won't change it to something I can understand, I won't use CVS. +4E.5 Explain: "co error, line 2: Missing access list" **** Answers: -4E.1 Explain: "ci error: unexpected EOF in diff output" RCS versions earlier than 5.5 print the above error when a file does not end in a newline character. It can be caused by: - Editing with Emacs and not using "require-final-newline". - Committing a binary file. - Filesystem failures (NFS!) that put nulls in your file. The solution is to upgrade to RCS 5.5 or later. -4E.2 Explain: "RCS file /Repository/module/file.c,v is in use" This is an RCS error that occurs when its internal lock file has been left around by an RCS command interrupted by some sort of system crash or disk failure. Go into the Repository and look for zero-length files with names similar to the "file.c,v" file, usually starting with ",", "_" or "#". Delete them. 4E.3 I don't want a Vendor branch. Why can't I work on the main trunk? The Vendor branch is the way "import" deals with a Vendor release. If you do it any other way, you are wasting your time. CVS was designed to work this way. If you are not working with 3rd party (i.e. Vendor) sources, you can skip the "import" and either move pre-existing RCS files into the Repository, or apply the RCS "ci" command to your source files by hand and *then* move them into the Repository. =4E.4 Merges can't work. I don't trust them. If you won't change it to something I can understand, I won't use CVS. Some developers have the feeling that three-way merging doesn't work. They don't trust the way the "update" command automatically merges committed changes from the Repository into the working file. Experience has shown that most merges are utterly painless and most of the rest are easily resolved. The few conflicts that cause headaches are nearly all due to poor communication between developers, a problem no source control system can obliterate. Some developers were troubled in the past by flaky Unix software. I can't say that everything is perfect, but the tools CVS depends on (RCS and diff, mainly) are fairly solid nowadays. They work. Since it does seem to work for most of us, the algorithm is unlikely to change soon. Why not test it on a couple trouble spots and if it works for you, use if for a while? Then you can make an informed decision. +4E.5 Explain: "co error, line 2: Missing access list" This is an error message from RCS Version 3 when it tries to read a file created by a later version of RCS. You should upgrade to the latest version of RCS, which is Version 5.6.0.1 as I write this. ---------------- -- Section 4F -- Other Systems ---------------- **** Questions: 4F.1 I use a NeXT. Is there anything I need to know? 4F.2 I use a OS/2. Is there anything I need to know? 4F.3 I use SCO Unix. Is there anything I need to know? 4F.4 I use AIX. Is there anything I need to know? +4F.5 I use IRIX. Is there anything I need to know? +4F.6 I use an HP system. Is there anything I need to know? **** Answers: Out of the box, CVS works on most varieties of Unix. Some near-Unix systems have a few problems and non-Unix systems have a *lot* of problems. 4F.1 I use a NeXT. Is there anything I need to know? [[Anything else?]] Under NeXTSTEP 2.2, the tmpnam() function always returns the same filename, which breaks "cvs patch". Apparently the "mktemp()" function works OK, but you'll have to hack it up to build something that acts like "tmpnam()". NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than files in previous revisions. It removes files it doesn't recognize, making it impossible to place such a directory under CVS -- the CVS admin directory will be removed. 4F.2 I use OS/2. Is there anything I need to know? [[Well?]] 4F.3 I use SCO Unix. Is there anything I need to know? [[Well?]] 4F.4 I use AIX. Is there anything I need to know? [[Well?]] +4F.5 I use IRIX. Is there anything I need to know? It is possible that you may need to add -lsun to the link line to retrieve the passwd data through NIS. [[Else?]] +4F.6 I use an HP system. Is there anything I need to know? There was a report that HP distributes RCS version 3 (a very old release) with one of its systems. CVS can be made to work with RCS version 3 if you don't have any RCS files created by later versions of RCS and if you configure CVS not to define "HAVE_RCS5". A better solution is to find the latest version of RCS and install it somewhere. ============================================= == Section 5 ==== Past & Future ==== ============================================= ---------------- -- Section 5A -- Contributors ---------------- **** Questions: #5A.1 Who wrote CVS? #5A.2 You didn't write all of this FAQ, did you? **** Answers: #5A.1 Who wrote CVS? Brian Berliner converted a collection of scripts written by Dick Grune into a C program. He continues to maintain CVS. Jeff Polk wrote much of the new code added between revisions 1.2 and 1.3. Many others were involved at some level. Take a look at the README and the ChangeLog files in the CVS sources for more details. #5A.2 You didn't write all of this FAQ, did you? In the original hunt for questions to answer, I polled hundreds of people and I rephrased all sorts of things I found on the net. Because there are so many askers and so many questions I will list only the people who contribute answers or helped significantly with the content and structure of the document. I didn't use anyone else's verbatim answers, unless their name is included in the answer itself. On the other hand, I did use ideas and information provided by many. The people whose answers have added to this document or who have added to my understanding: Brian Berliner , CVS maintainer. Paul Eggert , RCS maintainer. Gray Watson Per Cederqvist Pete Clark all of whom have all sent me copies of their tutorials and local CVS documentation. A myriad Thinking Machines people who posed hundreds of questions. Additional contributors, who have sent me ideas, text, corrections and support include: Tom Cunningham Don Dwiggins Dave Wolfe Chris Moore Donald Amby Please send me corrections. If I forgot you, remind me and I'll add your name. ---------------- -- Section 5B -- Bugs and Patches ---------------- This section addresses some known bugs and patches for them. Large patches will be stored in the FTP area. See the Development section later for stuff being worked on. **** Questions: 5B.1 Why can't CVS handle deletion of directories? 5B.2 Why can't CVS handle the moving of sources from one place in the directory hierarchy to another? 5B.3 Why does "checkout" recurse indefinitely if an alias contains its own name? 5B.4 When I typed "cvs update -D ", why did it check out all sorts of ancient files from the Attic? Shouldn't it just create the set of files and revisions that existed at that date? 5B.5 When I typed "cvs update -D " in my branch, why did it screw up all my files? 5B.6 When I ran "checkout" into a existing directory I got "No such file or directory" errors. Why? +5B.7 Why does "update" send all output to the terminal after 26 files have been updated? **** Answers: 5B.1 Why can't CVS handle deletion of directories? An oversight, probably. [[Fixed?]] 5B.2 Why can't CVS handle the moving of sources from one place in the directory hierarchy to another? A general "renaming database" to keep track of changes in the pathnames of files and directories has been proposed. It is a difficult problem. 5B.3 Why does "checkout" recurse indefinitely if an alias contains its own name? A bug. [[Fixed?]] 5B.4 When I typed "cvs update -D ", why did it check out all sorts of ancient files from the Attic? Shouldn't it just create the set of files and revisions that existed at that date? This seems to be a bug, but is really the lack of any obvious place to store the date when a file is "removed". There are four ranges of dates that CVS has to deal with when trying to determine what revision was available on : 1. Dates before the earliest revision in the file. 2. Dates between the earliest and latest revisions in the file. 3. Dates between the latest revision in the file and the date when the file was moved to the Attic by "commit". 4. Dates after moving the file to the Attic. Since the date when a file is moved to the Attic is not stored anywhere, CVS can't tell the difference between #3 and #4. To avoid not producing a file that should be in case #3, it produces extraneous files in case #4. For the above reason, if you have removed files in the Attic, it is better to use '-r TAG', or even '-r HEAD' than to use a date spec. 5B.5 When I typed "cvs update -D " in my branch, why did it screw up all my files? Currently, the internal routine ("version_ts") that looks up info about a file, overrides both the tag and date if *either* the tag or date is specified on the command line. If only the date is specified, it should not override a branch tag, but it does. 5B.6 When I ran "checkout" into a existing directory I got "No such file or directory" errors. Why? Though the man page says that "checkout" turns into an "update -d" in directories that already exist, it is referring to directories that already exist *and* were created by CVS. When you try to run "checkout" on top of an existing directory structure, some of which wasn't created by CVS, it will handle directories and non-CVS files within directories already under CVS, but it will show the above error on non-CVS files within non-CVS directories. +5B.7 Why does "update" send all output to the terminal after 26 files have been updated? CVS uses the "tmpnam()" function to generate temporary file names. The ANSI standard for the "tmpnam()" function says: "The tmpnam function generates a different string each time it is called, up to TMP_MAX times. If it is called more than TMP_MAX times, the behavior is implementation defined." Later it says that the value of "TMP_MAX shall be at least 25." On some platforms, the above specification is taken literally by turning "at least 25" into "exactly 26" and by doing something foolish (i.e. "implementation defined") after that. Some systems return the same name repeatedly, which causes one form of trouble. Others return NULL or garbage, which causes a different form of trouble. The broken systems appear to be cycling a single character through the alphabet. SunOS cycles 3 characters through the alphabet, so it won't cause trouble until 26 cubed or 17576 calls to "tmpnam()". Since CVS doesn't depend on the exact format of the tmp files, the workaround is to provide a "tmpnam()" that doesn't have a limit on the number of calls to it. [[This section needs more, but should probably wait until the patch release comes out. Then we can document them for real and provide pointers to patches in the FTP area.]] ---------------- -- Section 5C -- Development ---------------- I hope to record three types of information here: 1. Plans (with the developer's name attached) for fixing larger bugs. (Smaller bugs should just show up, with a patch or a reference to a patch stored in the FTP archive, in the "Bugs" section above.) 2. Plans for new development, with the developer's name attached. (If the developer is particularly gonzo, it might also show a completion date.) 3. Requests for ideas and code to fix unresolved issues. **** Questions: 5C.1 Where do I send bug reports? 5C.2 Where do I send fixes and patches? 5C.3 Where do I send ideas for future development? 5C.4 What plans are there for fixing bugs? 5C.5 What plans are there for new features? 5C.6 I have some time and I'd like to help. What can I do for you? **** Answers: 5C.1 Where do I send bug reports? [[Send them to this list?]] 5C.2 Where do I send fixes and patches? [[This list again?]] I expect to collect them and store patches in the FTP archive. 5C.3 Where do I send ideas for future development? [[Brian?]] 5C.4 What plans are there for fixing bugs? David G. Grubbs plans/hopes to: - Fix the release command to be more sophisticated about foreign directories, renaming and to allow the release of anything in the working directory. - Fix the history command to track changes made in the underlying layers since I originally wrote it, including making "tag" work with history. [[Brian?]] [[Others?]] 5C.5 What plans are there for new features? David G. Grubbs plans/hopes to: - Implement the design described in the Branching spec distributed to this list in January, 93. It attempts to address the problem of merging between arbitrary branches and to fully support the idea of "branching". - Add a feature to "cvs add" (Maybe a '-a' switch.) to add a file by the same name as one in the Attic, by dragging it back out of the Attic. (This connects to the branching code, since a way has to be added to drag a file out of the Attic that is merged onto the Main branch from being only on a side-branch.) - If no one else wants to deal with it, I would like to enhance the whole "modules" concept to cover more of the naming problem and to allow more complicated access control. (Optional, of course.) - Create a set of configuration files (in addition to or to supersede the cvsignore files) to allow the setting of a wide variety of site-specific options. Brian Berliner plans/hopes to: - [[Rename database?]] [[Brian? Any plans?]] [[remote CVS: rcvs?]] [[Others?]] 5C.6 I have some time and I'd like to help. What can I do for you? You can review this document, correct errors and fill in any of the sections marked as incomplete (i.e. surrounded by [[]]). You can add to the contrib area, which contains useful ways to use some of the programmable CVS facilities (loginfo, commitinfo) or ways of connecting to work environments (pcl-cvs). You can fix bugs, review the man page or . . . [[Brian?]] [[Is there some way we can register someone as working on something or should we just stay in the "implement it and send it to me" mode?]] ================================================= == Section 6 ==== Table of Contents ==== ================================================= =========================================================================== == Frequently Asked Questions about CVS (The Concurrent Versions System) == =========================================================================== ============================================ == Section 0 ==== Introduction ==== ============================================ Questions are divided into five numbered Sections. Sections are divided into lettered sub-sections. The questions are numbered sequentially within each sub-section, though they are in no particular order. 1. What is CVS? A. What is CVS? What's it for? Why CVS? B. Where do I find it? Where can I find Help? C. How does CVS differ from other systems? D. What do you mean by . . .? (Definitions) 2. User Tasks A. Getting Started B. Common User Tasks C. Less Common User Tasks D. General Questions 3. Commands A. through P. One section for each CVS command. 4. Advanced Topics A. Installing CVS B. Setting up and Managing the Repository C. Branching D. Tricks of the Trade E. Weirdness F. Other Systems 5. Past & Future A. Contributors. B. Bugs and Patches C. Development 6. Table of Contents ============================================ == Section 1 ==== What is CVS? ==== ============================================ ---------------- -- Section 1A -- What is CVS? What's it for? Why CVS? ---------------- 1A.1 What does CVS stand for? Can you describe it in one sentence? 1A.2 What is CVS for? What does it do for me? 1A.3 How does CVS work? 1A.4 What is CVS useful for? =1A.5 What is CVS *not* useful for? 1A.6 Why isn't it called OSCO (Online Source COntrol)? ---------------- -- Section 1B -- Where do I find CVS? Where can I find Help? ---------------- 1B.1 How do I get more information about CVS? 1B.2 Is there an archive of CVS material? =1B.3 How do I get a copy of the latest version of CVS? =1B.4 Is there any other documentation? How about tutorials? 1B.5 Is there a mailing list devoted to CVS? How do I get on it? 1B.6 What prayers are appropriate for each of the major denominations ---------------- -- Section 1C -- How does CVS differ from other systems? ---------------- 1C.1 How does CVS differ from RCS? =1C.2 How does CVS differ from SCCS? 1C.3 How does CVS differ from ClearCase? 1C.4 How does CVS differ from TeamWare? 1C.5 How does CVS differ from SunPro? 1C.6 How does CVS differ from Aegis? +1C.7 How does CVS differ from Shapetools? ---------------- -- Section 1D -- What do you mean by . . .? (Definitions) ---------------- 1D.1 What is "The Repository"? 1D.2 What is an RCS file? 1D.3 What is a working file? +1D.4 What is a working directory (or working area)? 1D.5 What is "checking out"? 1D.6 What is a revision? 1D.7 What is a "Tag"? #1D.8 What are "HEAD" and "BASE"? 1D.9 What is a Branch? 1D.10 What is "the trunk"? 1D.11 What is a module? ========================================== == Section 2 ==== User Tasks ==== ========================================== ---------------- -- Section 2A -- Getting Started ---------------- 2A.1 What is the first thing I have to know? 2A.2 Where do I work? =2A.3 What does CVS use from my environment? 2A.4 OK, I've been told that CVS is set up, my module is named "ralph" and I have to start editing. What do I type? 2A.5 I have been using RCS for a while. Can I convert to CVS without losing my revision history? How about converting from SCCS? ---------------- -- Section 2B -- Common User Tasks ---------------- 2B.1 What is the absolute minimum I have to do to make a simple change to a single file? 2B.2 If I edit multiple files, must I type "commit" for each one? 2B.3 How do I get rid of the directory that "checkout" created? 2B.4 How do I find out what has changed? 2B.5 I just created a new file. How do I add it to the Repository? 2B.6 How do I merge changes made by others into my working directory? 2B.7 How do I label a set of revisions so I retrieve them later? 2B.8 How do I checkout an old release of a module, directory or file? 2B.9 What do I have to remember to do periodically? ---------------- -- Section 2C -- Less Common User Tasks ---------------- 2C.1 Can I create sub-directories in my working directory? 2C.2 How do I add new sub-directories to the Repository? 2C.3 How do I remove a file I don't need? 2C.4 How do I rename a file? 2C.5 How do I make sure that all the files and directories in my working directory are really in the Repository? 2C.6 How do I create a branch? 2C.7 How do I modify the modules file? How about the other files in the CVSROOT administrative area? ---------------- -- Section 2D -- General Questions ---------------- 2D.1 How do I see what CVS is trying to do? 2D.2 If I work with multiple modules, should I check them all out and commit them occasionally? Is it OK to leave modules checked out? 2D.3 What is a "sticky" tag? What makes it sticky? How do I loosen it? 2D.4 How do I get a old revision without updating the "sticky tag"? =2D.5 What operations disregard sticky tags? 2D.6 Is there a way to avoid reverting my Emacs buffer after committing a file? Is there a "cvs-mode" for Emacs? 2D.7 How does conflict resolution work? What *really* happens if two of us change the same file? 2D.8 How can I tell who has a module checked out? 2D.9 Where did the .#.1.2 files in my working directory come from? 2D.10 What is this "ignore" stuff? 2D.11 Why does .cvsignore not ignore directories? 2D.12 Is it safe to interrupt CVS using Control-C? 2D.13 How do I turn off the "admin" command? 2D.14 How do I turn off the ability to disable history via "cvs -l"? 2D.15 How do I keep certain people from accessing certain directories? ======================================== == Section 3 ==== Commands ==== ======================================== ---------------- -- Section 3A -- "add", "ad", "new" ---------------- 3A.1 What is "add" for? =3A.2 How do I add a new file to the branch I'm working on? #3A.3 Why did my newly added file end up in the Attic? =3A.4 How do I put a new file on the Main Branch and branch off from there onto my default branch? ---------------- -- Section 3B -- "admin", "adm", "rcs" ---------------- 3B.1 What is "admin" for? 3B.2 Wow! Isn't that dangerous? 3B.3 What would I normally use "admin" for? 3B.4 What should I avoid when using "admin"? 3B.5 The -i flag in the modules file can restrict commits. How do I turn off the "admin" command? ---------------- -- Section 3C -- "checkout", "co", "get" ---------------- 3C.1 What is "checkout" for? 3C.2 What is the "module" that "checkout" takes on the command line? 3C.3 Isn't a CVS "checkout" just a bunch of RCS checkouts? 3C.4 What's the difference between "update" and "checkout"? 3C.5 Why can't I check out a file from within my working directory? 3C.6 How do I avoid dealing with those long relative pathnames? 3C.7 Can I move a checked-out directory? Does CVS remember where it was 3C.8 How can I avoid losing the ability to lock files on checkout? ---------------- -- Section 3D -- "commit", "ci", "com" ---------------- 3D.1 What is "commit" for? 3D.2 If I edit ten files, do I have to type "commit" ten times? 3D.3 Explain: cvs commit: Up-to-date check failed for `' 3D.4 What happens if two people try to "commit" conflicting changes? 3D.5 I committed something and I don't like it. How do I remove it? 3D.6 Explain: cvs commit: sticky tag `V3' for file `' is not a branch 3D.7 Why does "commit -r BRANCH_TAG" put new files in the attic? ---------------- -- Section 3E -- "diff", "di", "dif" ---------------- 3E.1 What is "diff" for? 3E.2 Why did "diff" show nothing when there are committed revisions beyond what I have in my directory? 3E.3 How do I display what changed in the Repository since I checked out or last updated? 3E.4 How do I display the difference between my working file and what I checked in last Thursday? 3E.5 Why can't I pass the +unified (or --unified) option to "diff"? ---------------- -- Section 3F -- "export", "exp", "ex" ---------------- 3F.1 What is "export" for? 3F.2 Why does it remove the RCS keywords so I can't use the "ident" command on the source files? 3F.3 Can I override the -kv flag CVS passes to RCS? 3F.4 Why the hell not? 3F.5 Why does export -D check out every file in the Attic? ---------------- -- Section 3G -- "history", "hi", "his" ---------------- 3G.1 What is "history" for? 3G.2 Of what use is it? 3G.3 What is this, Big Brother? 3G.4 I deleted my working directory and "history" still says I have it checked out. How do I fix it? 3G.5 So I *can* edit the History file? 3G.6 Why does the history file grow so quickly? 3G.7 What is the difference between "cvs history -r TAG/rev" and "cvs history -t TAG"? 3G.8 Why does "cvs history -c -t TAG" fail to print anything? 3G.9 "cvs history -a -o" only printed one line for each checked-out module. Shouldn't it print all the directories where the modules are checked out? 3G.10 I can't figure out history, can you give me concrete examples? ---------------- -- Section 3H -- "import", "im", "imp" ---------------- 3H.1 What is "import" for? 3H.2 How am I supposed to use "import"? 3H.3 Why does import put files on a branch? Why can't you put it on the Main Trunk and let me work on a branch? 3H.4 Is there any way to import binary files? 3H.5 Why does CVS "import" corrupt some binary files? 3H.6 How do I keep "import" from expanding all the $\Revision$ strings to be 1.1.1.1? 3H.7 I imported some files for the Yarg compiler that looks for files with a suffix of ".yarg". When I check them out, they will no longer compile because they have this junk in them. Why? 3H.8 How do I make "import" save the timestamps on the original files? 3H.9 Why didn't "import" ignore the directories I told it to? 3H.10 Why can't I "import" 3 releases on different branches? 3H.11 What do I do if the Vendor adds or deletes files between releases? 3H.12 What about if the Vendor changes the names of files or directories, or rearranges the whole structure between releases? 3H.13 I thought "import" was for Vendor releases, why would I use it for code of my own? Do I have to use import? 3H.14 How do I import a large Vendor release? ---------------- -- Section 3I -- "log", "lo", "rlog" ---------------- 3I.1 What is "log" for? 3I.2 How do I extract the log entries between two revisions? 3I.3 How do I extract the log entries on a whole branch? 3I.4 How do I generate ChangeLogs from RCS logs? 3I.5 Why does "log" tell me a file was checked in 5 hours later than I know it was? ---------------- -- Section 3J -- "patch", "pa", "rdiff" ---------------- 3J.1 What is "patch" for? 3J.2 Why does patch include files from the Attic when I use '-D'? +3J.3 How do I make "patch" produce a patch for one or two files? It seems to work only with modules. ---------------- -- Section 3K -- "release", "re", "rel" ---------------- 3K.1 What is "release" for? =3K.2 Why does release -d delete directories within my directory that weren't ever in the CVS Repository? 3K.3 Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs release path/name/subdir" without an "unknown module name"? 3K.4 Why can't I "release" portions of a checked out directory? I should be able to "release" any file or sub-directory within my working directory. -3K.5 I removed the tree that I was about to start working on. How do I tell cvs that I want to release it if I don't have it anymore? =3K.6 Why doesn't "release -d module" reverse a "checkout module"? =3K.7 Why can't I release a module renamed with "cvs checkout -d"? ---------------- -- Section 3L -- "remove", "rm", "delete" ---------------- 3L.1 What is "remove" for? 3L.2 Why doesn't "remove" work on directories? 3L.3 I don't like removing files. Is there another way to ignore them? 3L.4 I just removed a file. How do I resurrect it? 3L.5 Why doesn't "remove" delete the file? Instead, it prints: cvs remove: no files removed; use `rm' to remove the file first ---------------- -- Section 3M -- "rtag", "rt", "rfreeze" ---------------- 3M.1 What is "rtag" for? 3M.2 Why would you use "rtag"? It assumes a static Repository. ---------------- -- Section 3N -- "status", "st", "stat" ---------------- 3N.1 What is "status" for? 3N.2 Why does "status" limit the File: at the top to 17 characters? ---------------- -- Section 3O -- "tag", "ta", "freeze" ---------------- 3O.1 What is "tag" for? 3O.2 What is the difference between "tag" and "rtag"? 3O.3 Why does "tag -b" not put a tag on the Branch Point revision? How do I refer to the Branch Point? 3O.4 So we've labeled a bunch of files. What do you use a Tag for? 3O.5 How do I get "tag" and "rtag" to send mail the way "commit" does? 3O.6 Why can't "tag" handle the -r option that "rtag" takes? 3O.7 I ran "tag" in my working directory. When it is checked it out with -r , why don't they get a copy of my current work? 3O.8 Why doesn't "cvs tag" write a history record? ---------------- -- Section 3P -- "update", "up", "upd" ---------------- 3P.1 What is "update" for? 3P.2 What do 'U', 'M' and 'C' mean when I type "update"? 3P.3 What's the difference between "update" and "checkout"? 3P.4 Why don't I get new files when I execute "update"? 3P.5 Why does "update -j" say "M" both for files I have modified and they haven't and for files that we both modified, when the Merge showed no errors. Aren't they different? 3P.6 After a merge ("update -j"), why doesn't it remember the conflicts and not allow you to commit the result until the conflict is resolved? 3P.7 Is there a feature to tell me what I have changed, added and removed without changing anything? 3P.8 Why does "cvs update" not flag directories that are not in the Repository as it does with new files? 3P.9 Why are all my files deleted when I run "update"? =============================================== == Section 4 ==== Advanced Topics ==== =============================================== ---------------- -- Section 4A -- Installing CVS ---------------- 4A.1 What do I have to know before I install CVS? 4A.2 How do I configure the CVS programs? 4A.3 Besides CVS, what do I have to install? =4A.4 How do I get around the bugs I've heard of GNU diff version 2.2? ---------------- -- Section 4B -- Setting up and Managing the Repository ---------------- =4B.1 What do I do first? How do I create a Repository? 4B.2 What are those files in $CVSROOT/CVSROOT? 4B.3 Is there any other state in the Repository besides in the $CVSROOT/CVSROOT directory? 4B.4 How do I put sources into the Repository? 4B.5 What file protection modes do I use on the Repository? 4B.6 How do I structure my Repository? 4B.7 How do I manage the modules file? 4B.8 Why would anyone use "modules"? They are too restrictive. I want to be able to select just the files I want to edit. =4B.9 How do I rename a file or directory? What are the consequences? 4B.10 What are "Attic" directories? 4B.11 Is it OK to remove anything from the Repository to save space? 4B.12 Can I convert to CVS from RCS without losing my revision history? =4B.13 Can I move RCS files with branches in them into the Repository? 4B.14 Can I use raw RCS commands on the Repository? 4B.15 How do I convert from SCCS to RCS? 4B.16 How do I limit access to the Repository? =4B.17 What are the Repository Administrator's responsibilities? +4B.18 How do I move the whole Repository? ---------------- -- Section 4C -- Branching ---------------- 4C.1 What is a branch? =4C.2 Why (or when) would I want to create a branch? =4C.3 How do I create and checkout a branch? 4C.4 Once created, how do I manage a branch? 4C.5 Are there any extra issues in managing multiple branches? 4C.6 How do I merge a branch back into the trunk? 4C.7 How do I merge changes from the trunk into my branch or between branches? =4C.8 How do I add a new file to a branch? 4C.9 How do I know what branch I'm on? 4C.10 Do I really have to know the name of the branch I'm working on? 4C.11 How do I refer to the revision where I branched so I can see what changed since the Branch Point on another branch? 4C.12 Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 4C.13 Is it possible to set the "default CVS branch" for everyone? 4C.14 How do I perform a large merge? 4C.15 Is a Vendor merge any different from a branch merge? ---------------- -- Section 4D -- Tricks of the Trade ---------------- 4D.1 How can you even check in binary files, let alone allow CVS to do its auto-merge trick on them? =4D.2 Can I edit the RCS (i.e. *,v) files in the Repository? 4D.3 Can I edit the CVS/{Entries,Repository,Tag} files? 4D.4 Someone ran "admin -o" and removed revisions to which tags/symbols were attached. How do I fix them? 4D.5 How do I move a magic branch tag? 4D.6 Can I use RCS locally to record my changes without making them globally visible by committing them? 4D.7 How can I allow shared access to the Repository by CVS and RCS at the same time? 4D.8 I "updated" a file my friend "bubba" committed yesterday. Why doesn't the file now have a modified date of yesterday? 4D.9 While I'm in the middle of a large "commit", how do I run other commands, like "diff" without getting lock errors? 4D.10 Why does the merge occasionally resurrect lines of code? 4D.11 Why does the merge fail when my "rcsmerge" program is configured to use GNU diff versions 2.1 and 2.2? 4D.12 What the hell is Entries.Static? 4D.13 Why did I get the wrong Repository in the loginfo message? 4D.14 Can I have multiple source repositories, one for each project? 4D.15 How do I run CVS setuid so I can only allow access through the CVS program itself? 4D.16 How about using groups and setgid() then? 4D.17 How do I use the "commitinfo" file? 4D.18 How do I use the "loginfo" files? ---------------- -- Section 4E -- Weirdness ---------------- -4E.1 Explain: "ci error: unexpected EOF in diff output" -4E.2 Explain: "RCS file /Repository/module/file.c,v is in use" 4E.3 I don't want a Vendor branch. Why can't I work on the main trunk? =4E.4 Merges can't work. I don't trust them. If you won't change it to something I can understand, I won't use CVS. +4E.5 Explain: "co error, line 2: Missing access list" ---------------- -- Section 4F -- Other Systems ---------------- 4F.1 I use a NeXT. Is there anything I need to know? 4F.2 I use a OS/2. Is there anything I need to know? 4F.3 I use SCO Unix. Is there anything I need to know? 4F.4 I use AIX. Is there anything I need to know? +4F.5 I use IRIX. Is there anything I need to know? +4F.6 I use an HP system. Is there anything I need to know? ============================================= == Section 5 ==== Past & Future ==== ============================================= ---------------- -- Section 5A -- Contributors ---------------- #5A.1 Who wrote CVS? #5A.2 You didn't write all of this FAQ, did you? ---------------- -- Section 5B -- Bugs and Patches ---------------- 5B.1 Why can't CVS handle deletion of directories? 5B.2 Why can't CVS handle the moving of sources from one place in the directory hierarchy to another? 5B.3 Why does "checkout" recurse indefinitely if an alias contains its own name? 5B.4 When I typed "cvs update -D ", why did it check out all sorts of ancient files from the Attic? Shouldn't it just create the set of files and revisions that existed at that date? 5B.5 When I typed "cvs update -D " in my branch, why did it screw up all my files? 5B.6 When I ran "checkout" into a existing directory I got "No such file or directory" errors. Why? +5B.7 Why does "update" send all output to the terminal after 26 files have been updated? ---------------- -- Section 5C -- Development ---------------- 5C.1 Where do I send bug reports? 5C.2 Where do I send fixes and patches? 5C.3 Where do I send ideas for future development? 5C.4 What plans are there for fixing bugs? 5C.5 What plans are there for new features? 5C.6 I have some time and I'd like to help. What can I do for you? ================================================= == Section 6 ==== Table of Contents ==== ================================================= % End of Table of Contents % End of CVS FAQ document