From 97dcd3ee2c52c29f7f4f4ad1a792395166114f77 Mon Sep 17 00:00:00 2001 From: nate Date: Fri, 31 Mar 1995 07:45:34 +0000 Subject: Original sources from CVS-1.4A2 munged to fit our directory structure. --- gnu/usr.bin/cvs/FAQ | 7826 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 7826 insertions(+) create mode 100644 gnu/usr.bin/cvs/FAQ (limited to 'gnu/usr.bin/cvs/FAQ') diff --git a/gnu/usr.bin/cvs/FAQ b/gnu/usr.bin/cvs/FAQ new file mode 100644 index 0000000..38f8e15 --- /dev/null +++ b/gnu/usr.bin/cvs/FAQ @@ -0,0 +1,7826 @@ + +Archive-name: cvs-faq +$Revision: 1.1 $ <<== Include this in your comments +$Date: 1994/10/07 06:17:45 $ + +=========================================================================== +== 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 + + + To help readers of previous versions of this document, I will annotate + each question with a change marker + + Change markers: Column 1 will contain a: + + '-' for a Question that has changed. + '=' for an Answer that has changed. + '#' for an entry with changes to both Question and Answer. + '+' for a newly added Question and Answer. + + + The markers indicate significant changes in content between major + revision numbers. Trivial changes, such as question reordering or + spelling and grammar corrections are not marked. If I need to delete + a question, I'll move it to a "Deleted" section for a few revisions. + Deletions will arise when new versions of CVS are released. In the + long run, any question that can be answered by "get the latest + release" will be deleted. + + The minor revision number will change frequently. If a minor revision + change is large enough, I'll add a change marker. At major revision + changes the markers will be cleared and set again, based on the latest + minor revision of the previous major revision. + + + + Editorial comments are delimited by pairs of "[[" & "]]". They + contain either references to the (usually unfinished) nature of the + FAQ entry itself or version-specific comments to be removed (or + altered) when new revisions of CVS are released. + + You may redistribute this as long as you don't take statements out + of context. Keep it together along with the revision number. + + +============================================ +== 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 similar software? + 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. Related Software + G. 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: 1.3. + + +============================================ +== 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 may 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 programs, X, etc.) + + + 3. Branches + + Aside from the "Vendor Branch", there are three kinds of + "branches in development" that CVS can support: + + a. Your working directory can be treated as a private branch. + + b. A Development branch can be shared by one or more developers. + + c. At release time, a branch is usually created for bug fixes. + + (See 1D.9 and Section 4C for more info on branches.) + + Although, at this writing, CVS's 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 + line 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 merely stores + files for retrieval in a tree structure you devise. + + CVS does not dictate how to use disk space in the checked + out working directories. If you write your 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. + + Of course, you should place the tools created to support such + a build system (scripts, Makefiles, etc) under CVS. + + + CVS is not a substitute for management. + + Your managers and project leaders are expected to talk to + you frequently enough to make certain you are aware of + schedules, merge points, branch names and release dates. If + they don't, CVS can't help. + + CVS is an instrument for making sources dance to your tune. + But you are the piper and the composer. No instrument plays + itself or writes its own music. + + + CVS is not a substitute for developer communication. + + When faced with conflicts within a single file, most + developers manage to resolve them without too much effort. + But a more general definition of "conflict" includes problems + too difficult to solve without communication between + developers. + + CVS cannot determine when simultaneous changes within a single + file, or across a whole collection of files, will logically + conflict with one another. Its concept of a "conflict" is + purely textual, arising when two changes to the same base file + are near enough to spook the merge (i.e. "diff3") command. + + CVS does not claim to help at all in figuring out non-textual + or distributed conflicts in program logic. + + For example: Say you change the arguments to function X + defined in file A. At the same time, someone edits file B, + adding new calls to function X using the old arguments. You + are outside the realm of CVS's competence. + + Acquire the habit of reading specs and talking to your peers. + + + CVS is not a configuration management system. + + CVS is a source control system. The phrase "configuration + management" is a marketing term, not an industry-recognized + set of functions. + + A true "configuration management system" would contain + elements of the following: + + * Source control. + * Dependency tracking. + * Build systems (i.e. What to build and how to find + things during a build. What is shared? What is local?) + * Bug tracking. + * Automated Testing procedures. + * Release Engineering documentation and procedures. + * Tape Construction. + * Customer Installation. + * A way for users to run different versions of the same + software on the same host at the same time. + + CVS provides only the first. + + +=1A.6 Why isn't it called OSCO (Online Source COntrol)? + + Better discount? CVS is shorter? (The international audience + requires an explanation: Both CVS and OSCO are the names of large + chains of Pharmacies (drug stores) in the U.S.) + + + +---------------- +-- 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 + (e.g. 20's, 50's, 100's) when issuing complex CVS commands? ++1B.7 How do I get files out of the archive if I don't have FTP? + + + **** 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 and some of its workings. Note + that some of the emphasis (especially on multiple vendors + providing the same sources) is out of date. + + 4. Read the man pages for RCS. + + 5. Read the source code. + + 6. Look in the "doc" directory in the FTP archive described + below. + + 7. Read the gnu.cvs.info newsgroup. + + 8. If you don't get the newsgroup, you can join the info-cvs + mailing list, described below. + + + 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: + cd /pub/cvs + get README + get Index + + The README has more (and more up-to-date) information. The Index + contains a terse list of what is in the archive. + + ++1B.3 How do I get files out of the archive if I don't have FTP? + + Use one of the FTP<->Email servers. These are the ones + I've been told about: + + + 1. To use DEC's ftpmail service, type + + echo 'send help' | mail ftpmail@decwrl.dec.com + + which will send you a message telling you how to use Email to + retrieve files from FTP archives. + + + 2. If you are on BITNET, use Princeton's BITFTP server. Type + + echo 'send help' | mail bitftp@pucc.princeton.edu + + (It is likely that only BITNET addresses can use this one.) + + + 3. Other possibilities I've heard of from the net: + (Try the one closest to you.) + + ftpmail@sunsite.unc.edu + ftpmail@cs.arizona.edu + ftpmail@cs.uow.edu.au + ftpmail@doc.ic.ac.uk + + + 1B.4 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 + RCS 5.6.0.1 + GNU diff 2.3 + + 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 FTP archive mentioned above should contain the latest official + release of CVS, some official and unofficial patches and possibly + complete patched versions of CVS in use somewhere. + + + 1B.5 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 is 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.6 Is there a mailing list or Usenet newsgroup devoted to CVS? + How do I find them? + + An Internet mailing list named "info-cvs" grew out of the private + mailing list used by the CVS 1.3 alpha testers in early 1992. An + associated Usenet newsgroup named "gnu.cvs.info" was created in + August, 1993. + + The newsgroup and the mailing list are bidirectionally gatewayed, + meaning that you only need access to one of them. Anything sent + to the mailing list will be automatically posted to "gnu.cvs.info" + and anything posted to the newsgroup will be automatically mailed + to "info-cvs". + + First try the newsgroup, since it is generally easier to read (and + manage) than a mailing list. Ask your system administrator + whether you get the "gnu" hierarchy. If so, select a newsreader + and dive in. + + If you don't get any form of Usenet News (or don't get the "gnu" + hierarchy), you can add yourself to the mailing list by sending 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 whole list should be sent to: + + info-cvs@prep.ai.mit.edu + + An archive of the mailing list and the newsgroup might appear + someday in the CVS FTP archive. + + + 1B.7 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 similar software? +---------------- + +This section attempts to list programs purporting to cover some of the +same territory as CVS. [[These are very sparsely documented here. If you +know something about one of these tools, how about trying to flesh out an +entry or two?]] + + + **** 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? ++1C.8 How does CVS differ from TeamNet? ++1C.9 How does CVS differ from ProFrame? ++1C.10 How does CVS differ from CaseWare/CM? ++1C.11 How does CVS differ from Sublime? + + + **** 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. Serialization of commits. CVS requires you to merge all + changes committed (via "update") since you checked out + your working copy of the file. Although it is still + possible to commit a file filled with old data, it is less + likely than when using raw RCS. + + 4. 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? + + ClearCase is a client-server CASE tool for version management, + configuration management, and process management. ClearCase + is an evolution of the popular DSEE tools, formerly available + on HP/Apollo platforms. ClearCase includes an X/Motif GUI, + command-line interface, and C programmer API, and is currently + available on Sun, HP, and SGI platforms. + + ClearCase uses a special Unix filesystem type, called "mfs" + for "multi-version file system". Conceptually, mfs adds + another dimension to the regular Unix filesystem. The new + axis is used to store the different versions of files. Each + user makes a "view" into the file database by creating a + special mfs mountpoint on their machine. Each view has a set + of flexible selection rules that specify the particular + version of each file to make visible in that view. You can + think of a "view" as a workarea in CVS, except that the files + don't really exist on your local disk until you modify them. + This type of filesystem is sometimes called "copy-on-write" + and conserves disk space for files that are read-only. + Another advantage is that a view is "tranparent" in the sense + that all of the files in a "view" appear to be regular Unix + files to other tools and Unix system calls. An extended + naming convention allows access to particular versions of a + file directly: "test.cc@@/main/bugfix/3" identifies the third + version of test.c on the bugfix branch. + + ClearCase supports both the copy-modify-merge model of CVS and + the checkin/checkout development model with file locking. + Directories are versionable objects as well as files. A + graphical n-way merge tool is provided. Like CVS, ClearCase + supports branches, symbolic tags, and delta compression. + ASCII as well as binary files are supported, and converters + from RCS, SCCS, DSEE formats are also included. + + A make-compatible build facility is provided that can identify + common object code and share it among developers. A build + auditing feature automatically records file dependencies by + tracking every file that is opened when producing a derived + object, thus making explicit Makefiles unnecessary. Pre- and + post-event triggers are available for most ClearCase + operations to invoke user programs or shell scripts. + User-defined attributes can be assigned to any version or + object. Hyperlinks between versioned objects can record their + relationship. + + For more information, contact: + + Atria Software, Inc. + 24 Prime Park Way + Natick, MA 01760 + info@atria.com + + (508) 650-1193 (phone) + (508) 650-1196 (fax) + + Contributed by Steve Turner + [extracted from the ClearCase 1.1.1 documentation] + + +=1C.4 How does CVS differ from TeamWare? + + TeamWare is a configuration management tool from Sun + Microsystems. + + For more information, contact: + + SunExpress, Inc. + P.O. Box 4426 + Bridgeton, MO 63044-9863 + (800)873-7869 + + + 1C.5 How does CVS differ from SunPro? + + SunPro is advertised as the successor to "SCCS". + + [[Need more 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 + + ++1C.8 How does CVS differ from TeamNet? + + TeamNet is a configuration management tool from TeamOne. + + For more information, contact: + + TeamOne + 710 Lakeway Drive, Ste 100 + Sunnyvale, CA 94086 + (800) 442-6650 + + Contributed by Steve Turner + + ++1C.9 How does CVS differ from ProFrame? + + ProFrame is a new system integration framework from IBM. + ProFrame is compliant with the CFI (CAD Framework Initiative) + industry standards, including the Scheme extension language. + + ProFrame consists of three major components: (1) the Process + Manager that automates your local design methodology (2) the + Design Data Manager handles configuration management, and (3) + Inter-tool Communication to provide a communication path among + tools running on heterogeneous servers. + + The Design Data Manager(2) is probably the appropriate + component to compare to CVS. The Design Data Manager provides + version control with checkin/checkout capability, + configuration management, and data dependency tracking. A + graphical data selection interface is provided. Using this + interface, you may create and manipulate objects and hierarchy + structures, view the revision history for an object, and view + and assign attributes to a design object. + + The ProFrame server currently runs only on RS600, but clients + may be a wide variety of Unix platforms. Contact IBM for the + latest platform information. + + For more information, contact: + + IBM + EDA Marketing and Sales + P.O. Box 950, M/S P121 + Poughkeepsie, NY 12602 + (800) 332-0066 + + + Contributed by Steve Turner + [extracted from the ProFrame 1.1.0 datasheet] + + ++1C.10 How does CVS differ from CaseWare/CM? + + CaseWare/CM is a software configuration management product + from CaseWare, Inc. CaseWare/CM may be customized to support + a wide variety of methodologies, including various phases of + the software lifecycle, and different access rights for users. + + A GUI is provided to view version histories and + configurations. A merge tools is also included. CaseWare + supports type-specific lifecycles, which allows different types + of files to move through different lifecycles. Also provided + is a build facility to support automatic dependency analysis, + parallel, distributed, and remote builds, and variant + releases. + + CaseWare/CM has been integrated with other CASE tools, + including FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP + SoftBench, and Software Through Pictures. CaseWare also + offers CaseWare/PT, a problem tracking system to integrate + change requests with configuration management. + + Multiple vendors and operating systems are supported. + + For more information, contact: + + CaseWare, Inc. + 108 Pacifica, 2nd Floor + Irvine, CA 92718-3332 + (714) 453-2200 (phone) + (714) 453-2276 (fax) + + Contributed by Steve Turner + [extracted from the CaseWare/CM data sheet] + + ++1C.11 How does CVS differ from Sublime? + + Produced by AT&T. + + [[Need more info here.]] + + +---------------- +-- Section 1D -- What do you mean by . . .? (Definitions) +---------------- + + **** Questions: + +#1D.1 What are "The Repository", "$CVSROOT" and "CVSROOT"? + 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? ++1D.12 What does "merge" mean? + + + **** Answers: + + +#1D.1 What are "The Repository", "$CVSROOT" and "CVSROOT"? + + The Repository is a directory tree containing the CVS + administrative files and all the RCS files that constitute + "imported" or "committed" work. The Repository is kept in a + shared area, separate from the working areas of all developers. + + Users of CVS must set their "CVSROOT" environment variable to the + absolute pathname of the head of the Repository. Most command + line interpreters replace an instance of "$CVSROOT" with the value + of the "CVSROOT" environment variable. By analogy, in this + document "$CVSROOT" is used as shorthand for "the absolute + pathname of the directory at the head of the Repository". + + One of the things found in $CVSROOT is a directory named CVSROOT. + It contains all the "state", the administrative files, that CVS + needs during execution. The "modules", "history", "commitinfo", + "loginfo" and other files can be found there. + + + 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 other users of 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. + + Sometimes the word "revision" is used as shorthand for "the file + you get if you retrieve (via "checkout" or "update") the given + revision from the Repository." + + + 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. + + Most of the time BASE and HEAD refer to the same revision. They + become 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 option "-r " or "-D ". CVS records a + sticky tag and moves your files to the specified 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. + + There are four kinds of branches CVS deals with: + + 1. The Vendor Branch. + + A single vendor branch is supported. The "import" command + takes a sequence of releases from a source code vendor (called + a "vendor" even if no money is involved), placing them on a + special "Vendor" branch. The Vendor branch is considered part + of the "Main line" of development, though it must be merged + into locally modified files on the RCS Main branch before the + "import" is complete. + + See Section 3H ("import"). + + 2. Your Working directory. + + A checked-out working directory, can be treated like a private + branch. No one but you can touch your files. You have + complete control over when you include work committed by + others. However, you can't commit or tag intermediate versions + of your work. + + 3. A Development branch. + + A group of developers can share changes among the group, + without affecting the Main line of development, by creating a + branch. Only those who have checked-out the branch see the + changes committed to that branch. This kind of branch is + usually temporary, collapsing (i.e. merge and forget) into the + Main line when the project requiring the branch is completed. + + You can also create a private branch of this type, allowing an + individual to commit (and tag) intermediate revisions without + changing the Main line. It should be managed exactly like a + Development Branch -- collapsed into the Main line and + forgotten when the work is done. + + 4. A Release branch. + + At release time, a branch should be created marking what was + released. Later, small changes (sometimes called "patches") + can be made to the release without including everything else on + the Main line of development. You avoid forcing the customer + to accept new, possibly untested, features added since the + release. This is also the way to correct bugs found during + testing in an environment where other developers have continued + to commit to the Main line while you are testing and packaging + the release. + + Although the internal format of this type of branch (branch tag + and RCS branches) is the same as in a development branch, the + purpose and the way it is managed are different. The major + difference is that the branch is Permanent. Once you let a + release out the door to customers, or to the next stage of + whatever process you are using, you should retain forever the + branch marking the release. + + Since the branch is permanent, you cannot incorporate the + branch fixes into the Main line by "collapsing" (merging and + forgetting) the release branch. For large changes to many + files on the release branch, you will have to perform a branch + merge using "update -j -j ". (See 4C.7) + + The most common way to merge small changes back into Main line + development is to make the change in both places + simultaneously. This is faster than trying to perform a + selective merge. + + See 1D.12 (merges) and Section 4C, on Branching for more info. + + +=1D.10 What is "the trunk"? + + Another name for the RCS Main Branch. The RCS Main Branch is + related, but not equivalent, to both the CVS Main branch and what + developers consider to be the Main line of development. + See 3H.3 and Section 4C on Branching. + + +=1D.11 What is a module? + + In essence, 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. + + The module idea is now a somewhat slippery concept that can be + defined in two different ways: + + A. A module is an argument to "checkout". There are three types: + + 1. An entry in the modules file. A "module" name as described + in 'B.' below. + + 2. A relative path to a directory or file in the Repository. + + 3. A mixed-mode string of "modulename/relative-path". + Everything up to the first slash ('/') is looked up as a + module. The relative path is appended to the directory + associated with the module name and the resulting path is + checked out as in #2 above. + + + B. A module is a unique (within the file) character string in the + first column of the modules file. There are five types: + + 1. A name for a directory within the Repository that + allows you to ignore the parent directories above it. + + Example: + + emacs gnu/emacs + + + 2. A name for a subset of the files within such a directory. + + Example: + + ls unix/bin Makefile ls.c + + + The 2nd through Nth strings in the above must be *files*. + No directories, no relative pathnames. To checkout more + than one directory by a single name, use an alias as + described in #5 below. + + + 3. A relative pathname to a directory within the Repository + which, when checked out, creates an image of part of the + Repository structure in your current directory. + + Example: + + gnu/emacs -o /emacs.helper gnu/emacs + + The files checked out are exactly the same as the files you + would get if the path weren't even in the modules file. The + only reason to put this kind of relative pathname into the + modules file is to hook one of the helper functions onto it. + + + 4. A relative pathname to a single file within the Repository + which, when checked out, creates something you probably + don't want: It creates a directory by the name of the file + and puts the file in it. + + Example: + + gnu/emacs/Makefile -o /emacs.helper gnu/emacs Makefile + + The file checked out is the same as what you would get if + you handed the relative pathname to the "checkout" command. + But it puts it in a strange place. The only reason to do + this is to hook a helper function onto a specific file name. + + + 5. An alias consisting of a list of any of the above, including + other aliases. + + Example: + + my_work -a emacs gnu/bison unix/bin/ls.c + + + Another way to look at it is 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 for your development group. + + + As an example, say you want to keep track of three programs, and + want to be allowed to check out any combination of one, two or all + three at a time. Here are most of the combinations I can think + of. Experiment and choose what you want -- you won't need every + possibility. + + + # All directories in "world", even ones added later. + world world + + # All three programs by name. They checkout into local dir. + prog123 -a prog1 prog2 prog3 + + # All three programs by name. They checkout into "world" subdir. + wprog123 -a wprog1 wprog2 wprog3 + + # Individual progs checkout into dirs named "prog1", etc. + prog1 world/prog1 + prog2 world/prog2 + prog3 world/prog3 + + # Individual progs checkout into dirs named "world/prog1", etc. + wprog1 -a world/prog1 + wprog2 -a world/prog2 + wprog3 -a world/prog3 + + # Pairs that checkout into local dir. + prog12 -a prog1 prog2 + prog13 -a prog1 prog3 + prog23 -a prog2 prog3 + + # Pairs that checkout into world subdir. + # Instead of using the wprog aliases, we could use "world/prog9" + wprog12 -a wprog1 wprog2 + wprog13 -a wprog1 wprog3 + wprog23 -a wprog2 wprog3 + + ++1D.12 What does "merge" mean? + + A merge is a way of combining changes made in two independent + copies of the same "base" file. There are always three files + involved in a merge: the original, or "base", file and two + copies of that base file modified in different ways. + + Humans aren't very good at handling three things at once, so the + terminology dealing with merges can become strained. One way to + think about it is that all merges are performed by inserting the + difference between a base revision and a later revision (committed + by someone else) into your working file. Both the "later" + revision and your working file are presumed to have started life + as a copy of the "base" revision. + + In CVS, there are three main types of "merge": + + 1. The "update" command automatically merges revisions committed + by others into your working file. In this case, the three + files involved in the merge are: + + Base: The revision you originally checked out. + Later: A revision committed onto the current branch + after you checked out the Base revision. + Working: Your working file. The one lying in the working + directory containing changes you have made. + + 2. The "update -j " command merges a whole branch into + your working file, which is presumed to be on the Main line of + development. + + See 4C.6 + + 3. The "update -j -j " merges the difference between + two specific revisions on some other branch (though the two + revisions are usually on the same branch) into your working + directory. + + See 4C.7 + + + + +========================================== +== 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 + everything you can get your hands on, including this FAQ. Source + control issues can be difficult, especially when you get to + branches and release planning. Expect to feel stupid for a few + days/weeks. + + 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 + without any preparation, stuff your 300 Megabytes of sources into + CVS and expect to start working. If you don't prepare first, 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. + If your CVS installation set the RCSBIN directory + to null (""), then the RCS commands also must be + somewhere in your PATH. + + + Optional variables: (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. + + USER Used to find the real user name if no LOGNAME. + + HOME Used to determine your home directory, if set. + Otherwise LOGNAME/USER/getuid() are used to find + your home directory from the passwd file. + + + 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 move into 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 . + + 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 edit a 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 can 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 edit a file? + + Tell your Repository Administrator to create a module covering the + directory or files you care about. You'll find out that the + module name is named . Then type: + + cvs checkout + cd + emacs # Isn't Emacs a synonym for editor? + cvs commit + + If you don't use modules (in my opinion, a mistake), you can check + out a directory by substituting its relative path within the + Repository for in the example above. + + To check out a single file, you'll have to change the "cd + " to "cd to the parent of the file named in ". + + +=2B.2 If I edit multiple files, must I type "commit" for each one? + + No. You can do them all at once by name or by directory. + See 3D.2. + + + 2B.3 How do I get rid of the directory that "checkout" created? + + Change your directory to be the same as when you executed the + "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 more completely implemented "release" command, you + can just remove it. That's "rm -rf " under Unix. + + +=2B.4 How do I find out what has changed? + + There are many ways to answer this. + + To find out what you've changed in your current working directory + 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 look at a revision history containing the comments for all + 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? + + The "update" command will display files CVS doesn't know about in + your working directory marked with a '?' indicator. + + ? + + To add to the Repository, type: + + 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 Section 4C on + "Branching". You will have to use the "update -j" command. + + Retrieving changes made to the Repository on 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 + by others since you last executed "checkout", "update" or "commit" + into your working files. + + For a single file, there are five possible results when you type + the "update" command: + + 1. If neither you nor others have made changes to , "update" + will print nothing. + + 2. If you have made no changes to a file, but others have, CVS + will replace your working file with a copy of the latest + revision of that file in the Repository. 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, CVS will merge the changes + stored in the Repository since your last "checkout", "update" + or "commit" into your working 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 execute "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, CVS will merge the changes into your file as in #4 + above, but it will leave conflict indicators in 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 + rcsmerge warning: overlaps during merge + cvs update: conflicts found in + C + + This is a "conflict". The file will contain strange-looking + text marking 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 can retrieve them later? + + To "tag" the BASE revisions (the ones you last checked out, + updated, or committed) you should "cd" to the head of the working + directory you want to tag and type: + + cvs tag + + It recursively walks through your working directory tagging the + BASE revisions of all files. + + 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 names are 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. + + 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 execute "cvs -n update" fairly 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 others' work, + you should execute "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 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? ++2C.8 How do I split a file into pieces, retaining revision histories? + + + **** 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 /Repos/ 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 + 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 Section 4B for more information. + + Here is the best way to get the effect of renaming, while + preserving the change log: + + 1. Copy the RCS (",v") file directly in the Repository. + + cp $CVSROOT//,v $CVSROOT//,v + + 2. Remove the old file using CVS. + + By duplicating the file, you will preserve the change + history and the ability to retrieve earlier revisions of the + old file via the "-r " or "-D " options to + "checkout" and "update". + + cd / + rm + cvs remove + cvs commit + + 3. Retrieve and remove all the Tags from it. + + By stripping off all the old Tags, the "checkout -r" and + "update -r" commands won't retrieve revisions Tagged before + the renaming. + + cd / + cvs update + cvs log # Save the list of Tags + cvs tag -d + cvs tag -d + . . . + + + This technique can be used to rename files within one directory or + across different directories. You can apply this idea to + directories too, as long as you apply the above to each file and + don't delete the old directory. + + Of course, you have to change the build system (e.g. Makefile) in + your to know about the name change. + + + 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 "cvs -n update" (which won't modify + your working directory) will display non-added files preceded by a + '?' indicator. 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 (i.e. precede by '\') 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? + + Type this in your working directory: + + cvs tag -b + + and you will create a branch. No files have real branches in them + yet, but if you move onto the branch by typing: + + cvs update -r + + and commit a file in the normal way: + + cvs commit + + then a branch will be created in the underlying ,v file and + the new revision of will appear only on that 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 + + If you use the provided template for the "modules" file, both the + CVSROOT and the "modules" module will have the "mkmodules" program + as a "commit helper". + + After a file is committed in these modules the "mkmodules" + command will convert all the files CVSROOT directory within the + Repository into a form that is usable by CVS. + + ++2C.8 How do I split a file into pieces, retaining revision histories? + + If you and a coworker find yourselves repeatedly committing the + same file, but never for changes in the same area of the file, you + might want to split the file into two or more pieces. If you are + both changing the same section of code, splitting the file is of + no use. You should talk to each other instead. + + If you decide to split the file, here's a suggestion. In many + ways, it is similar to multiple "renamings" as described in + 2C.4 above. + + Say you want to split , which already in the Repository, + into three pieces, , and . + + 1. Copy the RCS (",v") files directly in the Repository, + creating all the new files. + + cp $CVSROOT//,v $CVSROOT//,v + cp $CVSROOT//,v $CVSROOT//,v + cvs update + + 2. Then remove all the from the new files by using: + + cvs log # Save the list of + cvs tag -d + cvs tag -d + . . . + + 3. Edit and commit all three copies of the same file into three + distinct files. This is a hand-editing job, not something + CVS can handle. [From experience, I'd suggest making sure + that only one copy of each line of code exists among the + three files, except for "include" statements, which must be + duplicated. And make sure the code compiles.] + + emacs + cvs commit + + + As in the "rename" case, by duplicating the files, you'll preserve + the change history and the ability to retrieve earlier revisions. + + Also, as in the "rename" case, you can apply this idea to + directories too, by changing to , and + in the example. + + Of course, you have to change your build system (e.g. Makefile). + + + +---------------- +-- 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 an 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.3 file 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 display every + external command (mostly RCS commands and file deletions) it + executes. When combined with the '-n' option, which prevents the + execution of any command that might modify a file, you can see + what it will do before you let it fly. The '-t' option will *not* + display every internal action, only calls to external programs. + + To see a harmless example, try typing: + + cvs -nt update + + Some systems offer a "trace" command that will display all system + calls as they happen. This is a *very* low-level interface, but + it can be useful. + + The most complete answer is to read the source, compile it + with the '-g' option and execute 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 ("-r ") or date ("-D ") can + also become sticky when they are specified on the command line. + + 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 creates sticky tags, revisions and dates + the same way "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 an old revision without updating the "sticky tag"? + + Use the '-p' option to "pipe" data to standard output. The + command "update -p -r " sends the selected revision to + your standard output (usually the terminal, unless redirected). + The '-p' affects no disk files, leaving a "sticky tag" unaltered + and avoiding all other side-effects of a normal "update". + + If you want to save the result, you can redirect "stdout" to a + file using your shell's redirection capability. In most shells + the following command works: + + cvs update -p -r 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 itself ignores sticky tags, but it + calls "cvs -n update" (which *does* pay attention to a + sticky tag) to figure out what inconsistencies exist in + the working directory. If no discrepancies exist between + the files you originally checked out (possibly marked by a + sticky tag) and what is there now, "release -d" will + delete them all. + + 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. (In + the future, "commit" might set a sticky branch tag on a newly + added file.) 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 and set the corresponding sticky tag. + Unfortunately, it doesn't work correctly in CVS 1.3. 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? + + See Section 4F.1 + + + 2D.7 How does conflict resolution work? What *really* happens if two + of us change the same file? + + While editing files, there is no conflict. You are working on + separate virtual branches of development contained in your working + directories. 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-to-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 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 execute "update" and "commit", someone + else may have committed a later revision of . You will have + to execute "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 display 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.3 file in my working directory come from? + + It was created during an "update" when CVS merged changes from the + Repository into your modified working file. + + It serves the same purpose as any "backup" file: saving your bacon + often enough to be worth retaining. It is invaluable in + recovering when things go wrong. + + Say Developers A (you) and B check out rev 1.3 of file . + You both make changes -- different changes. B commits first, so + ,v in the Repository contains revisions up through 1.4. + + At this point, there are 5 (yes, five) versions of the file of + interest to you: + + 1. Revision 1.3 (What you originally checked out.) + 2. Revision 1.4 (What you need from developer B.) + 3. Your old working file. (Before the update.) + 4. Your new working file. (After the merge caused by "update".) + 5. Revision 1.5 (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.3") 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 update -p -r 1.3 | diff - .#.1.3 + + 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 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 to 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 re-execute 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 equivalent: "cvs admin". + + + Halting a new "checkout" should cause no harm. If you don't want + it, "release" (or rm -rf) it. If you do want it, re-execute 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 + permissions 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?" + +Questions about "missing" features and side-effects not attributable to a +particular command are in Section 2D, "General Questions". + +I won't provide patches here that are longer than a few lines. Patches +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 desire to add 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 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 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 How do I restrict the "admin" command? The -i flag in the modules + file can restrict commits. What's the equivalent for "admin"? ++3B.6 I backed out a revision with "admin -o" and committed a + replacement. Why doesn't "update" retrieve the new revision? + + + **** 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. This has its own problems, such + as leaving dangling Tags and confusing the "update" command. + + +=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. + + Don't try to use the '-l' option, which will lock RCS files. + See 4D.7 for a cautionary scenario. + + The "admin -o " allows you to delete revisions, usually a + bad idea. You should commit a correction rather than back out a + revision. Outdating a revision is prone to all sorts of problems: + + 1. Discarding data is always a bad idea. Unless something in the + revision you just committed is a threat to your job or your + life, (like naming a function "_is_a_dweeb", or + including the combination to the local Mafioso's safe in a C + comment), just leave it there. No one cares about simple + mistakes -- just commit a corrected revision. + + 2. The time travel paradoxes you can cause by changing history + are not worth the trouble. Even if CVS can't interfere with + your parents' introduction, it *can* log commits in at least + two ways (history and loginfo). The reports now lie -- the + revision referred to in the logs no longer exists. + + 3. If you used "import" to place into CVS, outdating all + the revisions on the Main branch back to and including revision + 1.2 (or worse, 1.1), will produce an invalid CVS file. + + If the ,v file only contains revision 1.1 (and the + connected branch revision 1.1.1.1), then the default branch + must be set to the Vendor branch as it was when you first + imported the file. Outdating back through 1.2 doesn't restore + the branch setting. Despite the above admonition against it, + "admin -b" is the only way to recover: + + cvs admin -b1.1.1 + + 4. Although you can't outdate a physical (RCS) branch point + without removing the whole branch, you *can* outdate a revision + referred to by a magic branch tag. If you do so, you will + invalidate the branch. + + 5. If you "outdate" a tagged revision, you will invalidate all + uses of the , not just the one on . A tag is + supposed to be attached to a consistent set of files, usually a + set built as a unit. By discarding one of the files in the + set, you have destroyed the utility of the . And it + leaves a dangling tag, which points to nothing. + + 6. And even worse, if you commit a revision already tagged, you + will alter what the pointed to without using the "tag" + command. For example, if revision 1.3 has attached to it + and you "outdate" the 1.3 revision, will point to a + nonexistent revision. Although this is annoying, it is nowhere + near as much trouble as the problem that will occur when you + commit to this file again, recreating revision 1.3. The old + tag will point to the new revision, a file that was not in + existence when the was applied. And the discrepancy is + nearly undetectable. + + + If you don't understand the above, you should not use the admin + command at all. + + +-3B.5 How do I restrict the "admin" command? The -i flag in the modules + file can restrict commits. What's the equivalent for "admin"? + + At this writing, to disable the "admin" command, you will have + to change the program source code, recompile and reinstall. + + ++3B.6 I backed out a revision with "admin -o" and committed a + replacement. Why doesn't "update" retrieve the new revision? + + CVS is confused because the revision in the ./CVS/Entries file + matches the latest revision in the Repository *and* the timestamp + in the ./CVS/Entries file matches your working file. CVS believes + that your file is "up-to-date" and doesn't need to be updated. + + You can cause CVS to notice the change by "touch"ing the file. + Unfortunately what CVS will tell you is that you have a "Modified" + file. If you then "commit" the file, you will bypass the + normal CVS check for "up-to-date" and will probably commit the + revision that was originally removed by "admin -o". + + Changing a file without changing the revision number confuses CVS + no matter whether you did it by replacing the revision (using + "admin -o" and "commit" or raw RCS commands) or by applying an + editor directly to a Repository (",v") file. Don't do it unless + you are absolutely certain no one has the latest revision of the + file checked out. + + The best solution to this is to institute a program of deterrent + flogging of abusers of "admin -o". + + The "admin" command has other problems." See 3B.4 above. + + +---------------- +-- 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 checked out? +#3C.8 How can I lock files on checkout the way RCS does? ++3C.9 What is "checkout -s"? How is it different from "checkout -c"? + + + **** 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 + execute before and after helper functions based on definitions in + the modules file. + + See 1D.11. + + + 3C.3 Isn't a CVS "checkout" just a bunch of RCS checkouts? + + Like much of CVS, a similar RCS concept is used to support a CVS + function. 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 to work on. + + 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. + + 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" (which is + performed by the RCS "co" command) is closer to a "cvs update" + than to a "cvs 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 + decide not to use "modules". The answer is to use "module". + + 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 expanding into a list of relative + pathnames rather than a list of 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 without 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 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 lock files on checkout the way RCS does? + + 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". + + ++3C.9 What is "checkout -s"? How is it different from "checkout -c"? + + The '-c' and '-s' options to "checkout" both cause the modules + file to appear on standard output, but formatted differently. + + "checkout -c" lists the modules file alphabetized by the module + name. It also prints all data (including options like '-a' and + "-o ") specified in the modules file. + + "checkout -s" lists the modules file sorted by "status" field, + then by module name. The status field was intended to allow you + to mark modules with strings of your choice to get a quick sorted + report based on the data you chose to put in the status fields. I + have used it for priority ("Showstopper", etc as tied into a bug + database), for porting status ("Ported", "Compiled", etc. when + porting a large collection of modules), for "assignee" (the person + responsible for maintenance), and for "test suite" (which + automatic test procedure to run for a particular module). + + [[CVS 1.3 fails to handle all the flags you can put into the + modules file. The '-l' switch in particular causes "checkout -c" + to dump core on some systems.]] + + +---------------- +-- 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 `X' is not a branch +=3D.7 Why does "commit -r " put new files in the attic? ++3D.8 Why does "commit -r " ignore on an added file? + + + **** 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 will take multiple filenames on the + command line and commit them all with the same log message. + If the file is unchanged, CVS will skip it. + + Like all CVS commands, "commit" will work on the whole directory + by default. Just type "cvs commit" to tell CVS to commit all + modified files (i.e. the files that "update" would display + preceded by 'M') in the current directory and in all + sub-directories. + + + 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, committed 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 + executed "checkout", "update" or "commit". You must now execute + "update" to merge the other person's changes into your working + file 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 developer runs into it, usually when faced with the + "Up-to-date" error explained in the previous question. + + 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" (synonym: "rcs -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 -r " might help here) and commit it on top of the + offending revision. + + See Section 3B on "admin". + + +=3D.6 Explain: cvs commit: sticky tag `V3' for file `X' is not a branch + + The message implies two things: + + 1. You created your working directory by using "checkout -r + V3", or you recently executed "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 + 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. Branch tags are magic tags that don't create a + physical branch, but merely mark the revision to branch from when + the branch is needed. 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 sticky Tag or + 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. Sticky dates also block commits since they + never refer to a branch. + + + 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 + + (It was not a big mistake. Branch-point tags can be useful. + But the 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 + cvs tag -b . + + Then, to put your working directory onto the branch, you type: + + cvs update -r + + + You can't delete before adding , and I would + not advise deleting the 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 + or + cvs tag -d . + + + Scenario3: + + If you made the same mistake as in Scenario2, but really want + 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 + cvs rtag -d + cvs rtag -b -r + + Then, if you really must, delete the : + + cvs rtag -d + + + Note: The unwieldy mixture of "tag" and "rtag" is mostly + because you can't specify a revision (-r ) to the + "tag" command. + + See 4C.3 for more details. + + +=3D.7 Why does "commit -r " put new files in the attic? + + This was a design choice. 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. + + 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 committing the new + file to the Main branch in addition to the Branch you are working + on. This is an undesirable side-effect. + + The file can be retrieved by using the "-r " option on + a "checkout" or "update" command. + + See Section 4C, on Branching, for many more details. + + ++3D.8 Why does "commit -r " ignore on an added file? + + The sequence + + cvs add + cvs commit -r + + does not commit the new file with revision as you + might expect. For newly added files (for which "update" would + display an 'A') the '-r' option is assumed to be a branch tag. If + is numeric, it is ignored. This might or might not be + changed in future revisions of CVS, but for now, the following + commands will allow you to set the revision of the file: (with + some restrictions) + + cvs add + cvs commit + cvs commit -r + + The first commit causes CVS to look for the highest main branch + major number in all files in the directory. Normally it is '1', + but if you have a file of revision 3.27 in your directory, CVS + will find the '3' and create revision 3.1 for the first rev of + . Normally, the first revision is 1.1. + + As long as is higher than the initial (calculated as in the + above) revision, the second commit will work as expected and force + a second commit even if the file hasn't changed, setting the file + revision to . + + +---------------- +-- Section 3E -- "diff", "di", "dif" +---------------- + + **** Questions: + + 3E.1 What is "diff" for? +=3E.2 Why did "diff" display nothing when I know there are later + committed revisions in the Repository? +#3E.3 How do I display what changed in the Repository since I last + executed "checkout", "update" or "commit"? +=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 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 last checked out, + updated or committed. + + In the examples above, "-D " may be substituted wherever + "-r " appears. The revision a refers to is the + revision that existed on that date. + + +=3E.2 Why did "diff" display nothing when I know there are later + committed revisions in the Repository? + + By default, "diff" displays the difference between your working + file and the BASE revision. If you haven't made any changes to + the file since your last "checkout", "update" or "commit" there is + no difference to display. + + 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 last + executed "checkout", "update" or "commit"? + + A special tag (interpreted by CVS -- it does not appear in the Tag + list) named "BASE" always refers to the revision you last checked + out, updated or committed. 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. To be more precise, the + argument to the '-D' option is a timestamp. Many formats are + accepted. See the man page under "-D date_spec" for details. + + +=3E.5 Why can't I pass the --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. + + 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 + acquire the ability to pass them through. + + + Most of the long options have equivalent single-character options, + which do work. The "--unified" option is equivalent to '-u' in + revisions of GNU diff since 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 directory and file structure 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? + + It removes the RCS keywords, so that if the recipient of the + exported sources checks them into another set of RCS files (with + or without CVS), and then makes modifications through RCS or CVS + commands, the revision numbers that they had when you exported + them will be preserved. (That ident no longer works is just an + unfortunate side effect.) + + The theory is that you are exporting the sources to someone else + who will make independent changes, and at some point you or they + will want to know what revisions from your Repository they started + with (probably to merge changes, or to try to decide whether to + merge changes). + + A better way to handle this situation would be to give them their + own branch of your Repository. They would need to remember to + checkin the exported sources with RCS IDs intact (ci -k) so that + their changes would get revision numbers from the branch, rather + than starting at 1.1 again. Perhaps a future version of CVS will + provide a way to export sources this way. + + Contributed by Dan Franklin + + +=3F.3 Can I override the '-kv' flag CVS passes to RCS? + + Not in CVS 1.3. Maybe later. + + +=3F.4 Why the hell not? + + Export is intended for a specific purpose -- to remove all trace + of revision control on the way *out* of CVS. Maybe in the future + CVS will allow the -kv default to be overridden. + + + 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 " and + "cvs history -t "? + 3G.8 Why does "cvs history -c -t " 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 + activities. + + + 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, last Thursday, or a specific date. + - Someone changed a specific 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) grabbed 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 " and + "cvs history -t "? + + The '-t' option looks for a Tag record stored by "rtag" in the + history file and limits the search to dates after the last + of the given name was added. + + The '-r' option was intended to search all files looking for the + in the RCS files. It takes forever and needs to be + rewritten. + + + 3G.8 Why does "cvs history -c -t " 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 CVS's earlier firm belief 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 chooses the "checked out modules" report, which is + the default history report. + + +=3G.10 I can't figure out "history", can you give me concrete examples? + + Default output selects records only for the user who executes the + "history" command. To see records for other users, add one or + more "-u user" options or the '-a' option to select *all* users. + + To list (for the selected users): Type "cvs history" and: + + * Checked out modules: -o (the default) + * Files added since creation: -x A + * Modified files since creation: -c + * Modified files since last Friday: -c -D 'last Friday' + * Modified files since TAG was added: -c -t + * Modified files since TAG on files: -c -r + * Last modifier of file/Repository X? -c -l -[fp] X + * Modified files since string "str": -c -b str + * Tag history: (Actually "rtag".) -T + * History of file/Repository/module X: -[fpn] X + * Module report on "module": -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 "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 compiles files + with a suffix of ".yarg" and whose comment prefix is "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? ++3H.15 Explain: ERROR: cannot create link to : Permission denied + + + **** Answers: + +=3H.1 What is "import" for? + + The "import" command is a fast way to insert a whole tree of files + into CVS. + + The first "import" to a particular file within the Repository + creates an RCS file with a single revision on the "Vendor branch." + Subsequent "import"s of the same file within the Repository append + a new revision onto the Vendor branch. It does not, as some seem + to believe, create a new branch for each "import". All "imports" + are appended to the single Vendor branch. + + If the file hasn't changed, no new revision is created -- the new + "Release-Tag" is added to the previous revision. + + After the import is finished, files you have not changed locally + are considered to have changed in the "Main line of development". + Files you *have* changed locally must have the new Vendor code + merged into them before they are visible on the "Main line". + + See 4C.6 and 4C.15 + + +=3H.2 How am I supposed to use "import"? + + Create a source 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" + + + where is a relative directory pathname within the + Repository. + + For example, if the FSF, CVS, Make and I are still active 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 + + See 3H.14 for more details. + + +=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? + + Design choice. If you don't like the Vendor branch, you can use + the RCS "ci" command to generate all the RCS (",v") files and move + them into the Repository directly. + + Note that the CVS "Main Branch" and the RCS Main Trunk are not the + same. Placing files on the Vendor Branch doesn't keep you from + creating a development branch to work on. + + See Section 4C, on Branching. + + + 3H.4 Is there any way to import binary files? + + See 4D.1 on Binary files. + + +=3H.5 Why does "import" corrupt some binary files? + + The RCS "co" command, when it is invoked by a CVS "checkout" or + "update" (or after a "commit") command, searches for and expands a + list of keywords within the file. They are documented in the RCS + "co" man page. Strings such as "$\Id$" (or "$\Id:"), or + "$\Revision$" (or "$\Revision:") are altered to the include the + indicated information. + + [[Note: The keywords should appear in the text without the '\' + character I have inserted to *avoid* expansion here. The only + real RCS keywords in this document are at the top of the file, + where I store the Revision and Date.]] + + If RCS keyword strings show up in a binary file, they will be + altered unless you set the '-ko' option on the RCS files to tell + RCS to keep the original keyword values and not to expand new + ones. After "import", you can set the '-ko' option this way: + + cvs admin -ko + rm + cvs update + + See 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 compiles files + with a suffix of ".yarg" and whose comment prefix is "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 + two choices: + + 1. Check out the Yarg-less module, and tell all the files about + your comment prefix. Visit each directory and type: + + cvs admin -c"YARG> " *.yarg + + If *all* files in the whole directory tree are Yarg files, + you can use this instead: + + cvs admin -c"YARG> " . + + Then save any changes you made, remove all the "*.yarg" files + and grab new copies from the Repository: + + rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') + cvs update + + It might be faster to remove the whole directory and check it + out again. + + 2. Change 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. + + Then delete the imported files from the Repository and + re-"import" the sources. + + + 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 4D.8 for more details. + + + 3H.9 Why didn't "import" ignore the directories I told it to? + + See 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 "remove" (followed by "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 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 execute 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. + + First read the following, then, before executing "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 directory + structures are equivalent. + + The "comm" command, if you have it, can help figure out what + has been added or deleted between releases. + + 3. If they deleted any files, you can handle them cleanly with + "cvs remove". The command "comm -23 files.old files.new" will + show you a list of files that need to be removed. + + 4. If they renamed any files, see 4B.9 on renaming files. + + 5. When you have dealt with removed and renamed files, then you + can execute the import: + + cd + cvs import -m "Message" + + Where + + Message is the log message to be stored in the RCS files. + + is a relative path to a directory within the + Repository. The directory must be at + the same relative level within the new sources as + the you give is within the Repository. (I + realize this is not obvious. Experiment first.) + + is a Tag used to identify the Vendor who sent you + the files you are importing. All "imports" into + the same *must* use the same VendorTag. + You can find it later by using the "log" command. + + is a Tag used to identify the particular release + of the software you are importing. It must be + unique and should be mnemonic -- at least include + the revision number in it. (Note: you can't use + '.' characters in a Tag. Substitute '_' or '-'.) + + 6. *SAVE* the output from the import command. + + 7. There will be six categories of files to deal with. + (Actually there are eight, but you have already dealt with + "removed" and "renamed" files.) + + If this is the first "import" into a given directory, + only the first three of these ('I', 'L' and 'N') can occur. + + + 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 execute "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 execute"cvs commit". + + See the part of Section 4C dealing with branch merges. + + ++3H.15 Explain: ERROR: cannot create link to : Permission denied + + This error appears when you try to execute a second (or later) + "import" into the same module from a directory to which you don't + have write access. + + The "link error" is caused by a feature purposely added to + speed up the import. + + Though the error message is somewhat strange, it indicates that + "import" is supposed to be executed only in writable directories. + + +---------------- +-- 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 committed exactly 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 displays + information about the underlying RCS files, including the revision + history and Tag (what RCS calls "symbol") list. + + + 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. Non-branch + tags on a branch revision are not normally attached by CVS, to add + one you will have to explicitly tag a physical branch number + within each file. Since these branch numbers are almost never the + same in different files, this command is not all that useful. + + + 3I.4 How do I generate ChangeLogs from RCS logs? + + A program called rcs2log is distributed as part of GNU Emacs 19. + This program should also appear in the CVS FTP archive. + + +=3I.5 Why does "log" tell me a file was committed exactly 5 hours later + than I know it was? + + I can tell by this question that you were working in a time zone + that is 5 hours behind GMT (e.g. the U.S. East Coast in winter). + + RCS file dates are stored in GMT to allow users in different time + zones to agree on the meaning of a timestamp. At first glance + this doesn't seem necessary, but many companies use distributed + file systems, such as NFS or AFS, across multiple timezones. + + Some standard form must be used. GMT, as the "grid origin", is an + obvious candidate. The only other reasonable choice is to put the + timezone information in all the time stamps, but that changes the + RCS file format incompatibly, a step which has been avoided in the + last few RCS releases. + + +---------------- +-- 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 to be distributed to remote sites. Instead of "patch", + you can use the "diff" command with the '-c' context option: + + cvs diff -c -r -r . . . + + The patch command will be able to merge such a "diff" into the + remote 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. It will be upgraded slightly in the next release and + rewritten in the future. + + + 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 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 when it appears to try? + 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 when it appears to try? + + Oversight. It should be able to delete an empty directory, but + you still don't have a way to remember when it was there and 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: (csh-like syntax) + + 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 ", files with + 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 the main 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 + requires 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. + + Future versions of CVS might contain a '-f' switch that deletes + the existing file without complaining. + + +---------------- +-- 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? ++3N.3 Shouldn't the status "Needs Checkout" be "Needs Update"? + + + **** Answers: + +=3N.1 What is "status" for? + + To display the status of files, including the revision and branch + you are working on and the existence of "sticky" information. + + + 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 find the + whole filename in the line beginning with "RCS version:", which is + not limited in length. + + ++3N.3 Shouldn't the status "Needs Checkout" be "Needs Update"? + + Probably. Maybe in future revisions. + + + +---------------- +-- 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 "tag" labels 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 After a "tag " in my working directory, why doesn't "checkout + -r " somewhere else produce copy of my current files? +#3O.8 Why doesn't "tag" write a history record the way "rtag" does? + + + **** Answers: + + 3O.1 What is "tag" for? + + To add a symbolic label (a "tag") to the RCS files last checked + out, updated or committed in a working directory. + + +=3O.2 What is the difference between "tag" and "rtag"? + + The end result of both commands is that a , or symbolic name, + is attached to a particular revision of a collection of files. + + The differences lie in: + + 1. The collection of files they work on. + + "rtag" works on the collection of files referred to by a + "module" name, as defined in the "modules" file. + + "tag" works on files and directories in the current working + directory. + + Both commands recursively follow directory hierarchies within + the named files and directories. + + 2. The revisions they choose to tag. + + "rtag" places a tag on the latest committed revision of + each file on the branch specified by the '-r' option. By + default it tags the Main Branch. + + "tag" places a tag on the BASE (i.e. last checked out, updated + or committed) revision of each file found in the working + directory. + + 3. A different set of command line options. + + For example, "rtag" takes a "-r " option to retag an + existing tag. The "tag" command does not. + + 4. How it is logged. + + Currently "rtag" records the and the module in the + "history" file, while "tag" does not. + + +=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 allow CVS later to + figure out the branch point. The actual revision that is + attached to does not exist. 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. See 4C.3 on Creating a Branch. + + +-3O.4 So "tag" labels 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 may be in 2 + or more modules by name, some may be in 2 or more modules because + of the Repository tree structure) with the following revisions: + + file1 file2 file3 file4 file5 + + 1.1 1.1 1.1 1.1 /--1.1* <-*- + 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 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 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, which 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 After a "tag " in my working directory, why doesn't "checkout + -r " somewhere else produce copy of my current files? + + The only reason this would fail, other than misspelling the + string, 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 "tag" write a history record the way "rtag" does? + + The "rtag" command was originally intended 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 was 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"? Are they + different for "cvs -n 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" say 'M' both for plain modified files and for + successful (i.e. conflict-free) merges? Aren't they different? +=3P.6 After a merge ("update" or "update -j"), why doesn't CVS remember + the conflict 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 execute "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 display the status of your working files. + + Though a plain "update" also displays the status, it does so + after possibly altering your working directory. To see the + status of your working files without changing anything, type: + + cvs -n update {optional list of files} + + + 2. To merge changes made to the branch you are working on into + your working files. + + Each working directory is attached to a branch, usually the + Main branch. To merge changes made on 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 (your "working branch"). + + If you want to grab 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 {optional files} + + If you want to grab the changes made between two tags or + revisions, you type: + + cvs update -j -j {optional 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. + + A working directory is presumed to be attached to (or working + on) a particular branch, usually the Main branch. To alter + what CVS believes to be your working branch, you "move" to that + branch. + + To move to a tagged branch, type: + + cvs update -r {optional files} + + To move to the Main Branch, type: + + cvs update -A {optional files} + + + 5. To retrieve old revisions of files. + + This option is similar to 4 above but you are not restricted to + using a . You may specify any revision or Tag with + '-r' and get the specified revision or the tagged revision: + + cvs update -r {optional files} + + Or you may specify any date with '-D': + + cvs update -D {optional files} + + The '-p' option sends the revisions to standard output + (normally 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"? Are they + different for "cvs -n update"? + + "cvs update" merges changes made to the Repository, since your + last "checkout", "update" or "commit", into your working files. + You can think of it as "changing your BASE revision." + + "cvs update" prints lines beginning with: + + 'U' after replacing your unmodified file with a different + revision from the Repository. + + 'M' for two different reasons: + + 1. for files you have modified that have not changed in + the Repository. + + 2. after a merge, if it detected no conflicts. + + 'C' after a merge, if it detected conflicts. + + You will need to remove the conflicts by editing the file. + Conflicts are surrounded by <<<<< and >>>>> markers. + + + "cvs -n update" shows what it *would* do, rather than doing it. + Or, another way of looking at it, "cvs -n update" displays the + relationship between your current BASE revisions and the latest + revisions in the Repository. + + "cvs -n update" prints 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 also been changed in + the Repository. + + + See 4C.6 for what the letters mean when 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". + + + 3P.3 What's the difference between "update" and "checkout"? + + See 3C.4 above. + + +=3P.4 Why don't I get new files when I execute "update"? + + There are six reasons for nothing to happen during an "update": + + 1. Nothing on your branch changed in the Repository. + + If no one has committed anything to the branch you are working + on (normally the Main branch) since the last time you executed + "checkout", "update" or "commit", nothing will happen. + + It's like shouting "xyzzy" or "plugh" in the wrong room. + + 2. You have a "sticky" non-branch or attached to the + working files you are trying to "update". + + At some time in the past you checked out or updated your + directory with the "-r " or "-D " 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 a file named + Entries.Static, no files will be checked out that aren't + already in the Entries or Entries.Static file. + + 4. You forgot 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. :-) + + 6. Someone backed out the revision CVS thought you had in your + working directory, then committed a "replacement". CVS is now + confused because the revision in the Repository matches the + revision CVS thinks you already have. See 3B.6. + + +#3P.5 Why does "update" say 'M' both for plain modified files and for + successful (i.e. conflict-free) merges? Aren't they different? + + A design choice. Yes, they are different internally, but that + shouldn't matter. Your files are in the same condition after the + "update" as they were before -- a "diff" will display only your + modifications. And you are expected to continue onward with the + normal cycle of "emacs" (a synonym for "edit" in most of the + civilized world) and "commit". + + +=3P.6 After a merge ("update" or "update -j"), why doesn't CVS remember + the conflict and not allow you to commit the result until the + conflict is resolved? + + Maybe in a future release. There is a "sticky_conflict" patch you + might want to look at in the CVS FTP archive. + + + 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 or oversight, take your pick. Directories are + handled specially. You can aim "update" at any random directory + and "update" will traverse the whole directory tree beneath it, + looking for CVS administrative directories. When it finds one, + "update" will perform its "normal" function. + + Maybe a future release will notice a directory not under CVS, + print a '?' and skip over it. + + + 3P.9 Why are all my files deleted when I execute "update"? + + You probably executed "update -r " some time ago, then + removed from the Repository files. "update -r " will + delete a file that doesn't contain . + + 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 + + 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 do before I install CVS? + 4A.2 How do I configure the CVS programs? +=4A.3 What do I have to install? +-4A.4 How do I work around the merge problems in GNU diff version 2.1 + or later? + + + **** Answers: + +#4A.1 What do I have to do before I install CVS? + + 1. You must decide where to set up a Repository. + + Though you can construct a Repository tree structure using + links and mount points, there must be a single copy of each + real file across your entire organization. You may not "rdist" + files and expect to edit both copies. + + CVS does not support a truly 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. + + See Section 4B. For multiple Repositories, see 4D.14. + + 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. See 1B.3 for + suggestions. + + 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, + administrative files and the "modules" interface. + + Someone at your site should probably be on the info-cvs mailing + list. See 1B.5. + + + 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 want to use RCS 5.5 or greater and set the + "HAVE_RCS5" macro. + + 3. Execute the ./configure command. + + 4. Type "make". + + +=4A.3 What do I have to install? + + 1. Install the "cvs" executable and "mkmodules" from the CVS + sources. (The man page is useful too.) + + 2. Make sure you have versions of all the programs mentioned in + the config.h file, most of which are included in a standard + Unix system. + + 3. Unless you plan to reimplement RCS [:-)], you must install RCS. + + 4. Create the Repository (which you planned out in 4A.1) with the + "cvsinit" command at the top of the CVS sources. + + 5. You'll need to edit the Repository control files created by + "cvsinit". + + 6. Install any helper programs mentioned in the modules file. + + +-4A.4 How do I work around the merge problems in GNU diff version 2.1 + or later? + + See 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 stored in the Repository besides in the + $CVSROOT/CVSROOT directory? + 4B.4 How do I put sources into the Repository? +=4B.5 What file permissions should I use on (and in) 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? + 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? ++4B.19 How do I change permissions on a file in the Repository by using + a CVS command? (i.e. without using "chmod 777 $CVSROOT/dir/file") + + + **** Answers: + + +=4B.1 What do I do first? How do I create a Repository? + + First, install all the programs. (See Section 4A.) + + Then create a Repository by executing "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 a + history log, refer to modules, or use any of the "info" files for + logging, pre-commit checks, or editing templates, you can dispense + with "cvsinit" entirely. I would advise executing it. + + 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: 1. a regular expression to + match against pathnames within the Repository and + 2. a to execute for matching pathnames. + + When you execute "commit", CVS passes the + Repository pathname for each directory (and the + files to commit within that directory) to + . If exits with a non-zero + status, the commit is blocked. + + A associated with a pathname of + "DEFAULT" is executed if nothing else matches. + Every associated with a pathname of + "ALL" is executed separately. + + 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 the + commitinfo file. + + 3. editinfo contains the same two columns as commitinfo, but + the 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 is expected to read a log message + from its standard input. The can do + anything it wants with the log information, but + normally it is appended to a log file or sent to + mailing lists. + + "DEFAULT" & "ALL" work the same as in commitinfo. + + 5. cvsignore contains "ignore" patterns that are added to the + built-in ignore list. See 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 contains the "modules" database. See 1D.11, 2C.7, + 4B.7 and 4B.8 for more details. + + + 4B.3 Is there any other state stored 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. Use 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. Use "add" followed by "commit". + + This is how to add new files and directories to the Repository, + one at a time. + + 3. You can move RCS files directly into the Repository. + + It would probably be a good idea to create directories to hold + them. + + +=4B.5 What file permissions should I use on (and in) 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 directory permissions to 777. + + - Have everyone set their umasks to 0. + + (BTW, I don't suggest this. It am merely reporting it.) + + + If you are a normal Unix shop and want to use groups effectively: + + - Set all the directory permissions in the Repository to 775. + (If you are using a system that handles both System V and BSD + filesystems, you might have to set the permissions 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 permissions to 770. (or 2770) + + - umasks to 007. + + + If you work in an environment where people can't be trusted to + set their "umask" to something reasonable, you might want to set + the umask for them: + + mv /usr/local/bin/cvs /usr/local/bin/cvs.real + cat > /usr/local/bin/cvs + #!/bin/sh + umask 2 # Or whatever your site standard is. + exec /usr/local/bin/cvs.real ${1+"$@"} + ^D + + [[Future versions of CVS might sprout a "umask" configuration + variable.]] + + +=4B.6 How do I structure my Repository? + + The Repository holds your software. It can be all interrelated + 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 should 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) directories from different + places in your organization. + - check out just what you need and no more. + - 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, placing each major sub-system into a separate directory. + Later, when you know what you are doing, you can make it more + sophisticated. + + +=4B.7 How do I manage the modules file? + + An equivalent question might be, "How do I structure my sources?" + This can be a difficult question in that it is not purely + technical. + + Generally you want to think about what pieces of your system need + to be checked out together, built as one system or tagged + consistently. You should certainly make module names that + correspond to complete, buildable collections that you would tag + and release as one "product". It is also convenient to create + module names for small sections containing files that will usually + be worked on at the same time by the same person. + + Once you have defined the structure of your work, you can usually + see how to lay it out in a Repository. After that 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 recommended, to work completely without a + modules file. See 1D.11 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? + + In CVS 1.3 there is no single CVS "rename" command. + + See 2C.4 for the suggested way to rename a file or directory. + + The rest of this section covers some of the consequences of + renaming. + + A "renaming database" has been proposed that would keep track + of name changes so that "update -r " would continue to + work across the renaming. But as it stands, you have to pick + one of the following options: + + 1. Use the technique described in 2C.4. (For each file, duplicate + the file in the Repository, "remove" the old version so it + winds up in the Attic and strip all Tags off the new version.) + + - "update -r " produces the correct files. + + - The duplicated revision history can be slightly misleading. + + - A plain (i.e. without the "-r ") "checkout" or "update + -d" will create directories "renamed" this way, but you can + delete it and a plain "update" won't bring it back. + + + 2. 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. + + - "update -r " produces the wrong files or directories. + + This is not a good general solution, but if you plan never to + look back (someone may be gaining on you!), it is sometimes a + useful notion. + + If you are clever with Makefiles, you might be able to rework + them to handle either the new or old names, depending on + which ones exist at the time. Then you can move an old + onto the new, more sophisticated, revision of the Makefile. + (Yes, this changes the "released" file if 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. + + - The file exists in the working directory and in the + ./CVS/Entries file, but not in the Repository. For the old + file, "update" prints: + + cvs update: xyz.c is no longer in the repository + + and deletes the file. If the file was modified, "update" + prints: + + cvs update: conflict: xyz.c is modified but + no longer in the repository + C xyz.c + + and leaves the file alone. In the new directory, you see: + + U xyz.c + + as you would if someone else executed "add" and "commit". + + + 3. For each file, copy the working file to a new name, "remove" + the old file and "add" the new one. Since there is no way (in + CVS 1.3) to remove a directory, this only works for files. + + - This is what most people think of first. Without a "rename" + command, the remove/add technique seems obvious. + + - You lose the connection of your new working file to its past + revision history. + + +=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 named "Attic" within the + Repository. + + 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. + + You can think of the Attic as a sort of dead branch, which is only + looked at when you refer to a or . + + + 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 4B.2. + + 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. Lock files (named: "#cvs.[wr]fl.") + + 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 created 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. + + You can use other RCS branches under CVS. There is no need to + create "magic" branch tags because the physical branch already + exists. + + +=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 RCS revision histories) outside the CVSROOT + directory. + + But using raw RCS commands to change branches, tags or other + things that CVS depends on may render the files unusable. + + See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on + the "admin" command. + + + 4B.15 How do I convert from SCCS to RCS? + + You'll have to execute 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? + + There are all sorts of ways to restrict access to Repository + files, none of which are hooked directly into CVS. You can: + + 1. Set Unix groups and permissions. See 4B.5. + + 2. Try the "setgid" trick described in 4D.16. + + 3. Catch every commit using the "commitinfo" file. + + 4. Try to use the RCS access control lists, though I don't + think CVS will handle them cleanly. + + 5. Edit the source code to CVS. + + +=4B.17 What are the Repository Administrator's responsibilities? + + Generally, the Administrator should set "policy", create the + Repository and monitor its size and control files. + + Some specific responsibilities include: + + + 1. Examining the Repository once in a while to clean up: + + a. Trash files left by misguided developers who mistake the + Repository for a working directory. + + b. Non-RCS files. Other than the files CVS needs in the + $CVSROOT/CVSROOT directory, everything in the Repository + should be "under" CVS. + + c. Lock files (both CVS '#*' and RCS ',*' files) left around + after crashes. + + d. Wrong permissions, groups and ownerships. + + e. Locked files. (RCS locks, that is.) + + f. Attic files that should never have been under CVS at all. + Don't blindly delete files from Attic directories -- they + were mostly put there (via the "cvs remove") for a reason. + Files that should be deleted are binary files (e.g. '*.o', + 'core', executables) that were mistakenly inserted by + "import -I !". + + 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 the info-cvs mailing list and + what is available 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. + + 8. Executing monitor programs to check the internal consistency of + the Repository files. Ideas: + + a. Files that have a default RCS branch that is not 1.1.1 + (From an abuse of "admin -b".) + + b. Files that have only Revisions 1.1 and 1.1.1.1, with a + default branch of "MAIN". (From an abuse of "admin -o".) + + c. Existing branch tags and various branch consistency checks. + + + + 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 committing, 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. + + ++4B.19 How do I change permissions on a file in the Repository by using + a CVS command? (i.e. without using "chmod 777 $CVSROOT/dir/file") + + When you first "import" or "add"/"commit" a file, the read and + execute bits on the Repository file are inherited from the + original source file, while the write bits on the Repository file + are are turned off. This is a standard RCS action. + + After that, there is no way to alter the permissions on a file in + the Repository other than by changing the Repository file + directly. + + Whenever you "checkout" the file or retrieve a new revision via + "update" (or after a "commit"), your working file is set to match + the permissions of the Repository file, minus any "umask" bits you + have set. + + + +---------------- +-- 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 whole 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 (working) 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? ++4C.16 How do I go back to a previous version of the code on a branch? ++4C.17 Why do I get the latest files on the branch when I tried to + "update -r "? + + + **** Answers: + + 4C.1 What is a branch? + + Unfortunately, the word "branch" is an overloaded technical term. + It is used in too many different ways in three categories. It + might help to understand some of the issues by going through + the categories: + + 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 a 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 Repository source for 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 can be 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 since you executed "import". + + +=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 your own work, + but don't want your changes to affect others, create a private + branch. (Put your username in the branch tag, to make it + obvious that it is private.) + + 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 can move + onto a branch and share your work with others by "committing" + your work onto the branch. Developers not working 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? + + Suggested short form: + + 1. Attach a non-branch tag to all the revisions you want to + branch from. (i.e. the branch point revisions) + + 2. When you decide you really need a branch, attach a branch tag + to the same revisions marked by the non-branch tag. + + 3. "Checkout" or move your working directory to the branch. + + + Suggested short form using modules: + + A1. cvs rtag module + A2. cvs rtag -b -r module + A3. cvs checkout -r module + + + Suggested short form using your working directory, which contains + the revisions of your working files you want to branch from: + + B1. cvs tag + B2. cvs rtag -b -r module + B3. cvs update -r + + + The 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). + + Step #1 applies a non-branch tag to all the branch point revisions + in the module/directory. Though this is not strictly necessary, + if you don't add a non-branch tag to the revisions you branch + from, you won't be able to refer to the branch point in the + future. + + Between steps 1 & 2 you may commit files and the result is the + same because "rtag -r " applies to the + same revision that is attached to. You can use this + technique to avoid attaching *any* branch tags until you need + them. + + Step B2 has two important corollaries: + + 1. If you plan to create the branch tag before committing + anything in your working directory, you can use "cvs tag + -b " instead of the "rtag" command. + + 2. If you have trouble figuring out what "module" to use, + remember that "module" can also mean "relative path within + the Repository." If that doesn't help, you can aim it at + whatever parent directories you believe will cover all + your files. You can even aim it at the whole Repository + ($CVSROOT), if you have to. It might take some extra + time, but assuming that your Tag is a unique string and + you don't use the '-f' option to "rtag -r", "rtag" will + only add a Tag to files in which it actually *finds* the + earlier Tag. + + + Step 3 may occur any time after step 2. Unless you explicitly + remove them with "tag -d", the Tags are permanent. + + + There are two obvious ways of to choose the and + names. Since the is typed by any + developer who wants to work on the branch, you should make it mean + something to them. + + Style #1 presumes that the simple version string refers to a set + of designed, documented or promised features, not to a specific + set of files. In this case, you tag the branch with the generic + Version string and assume that whenever you refer to "Version", + you want the "latest" set of files associated with that Version, + including all patches. (You can substitute what ever you like for + "bp_", as long as your is some modification of + the .) + + Matching + + bp_V1_3 V1_3 + bp_Release2-3-5 Release2-3-5 + bp_Production4_5 Release4_5 + + + Style #2 presumes that the simple version string refers to the + specific set of files used to construct the first release of + "version". In this case, you tag the branch-point revisions with + the generic Version string and assume that whenever you refer to + this Version, you want the original set of released revisions. To + get the latest patched revisions of the release, you refer to the + branch tag "latest_". (You can substitute what + ever you like for "latest_", as long as your is some + modification of the .) + + Matching + + V1_3 latest_V1_3 + Release2-3-5 latest_Release2-3-5 + Release4_5 latest_Production4_5 + + + In both styles you can find out what you had to change since the + original release of this Version by typing: + + cvs diff -r -r + + For Style 1, this is: + + cvs diff -r bp_ -r + + For Style 2, this is: + + cvs diff -r -r latest_ + + + Notes: + + - The "-r " option tells CVS to attach a "sticky tag" to + working directory (in ./CVS/Tag) and the checked-out files (on + each line of ./CVS/Entries). + + - A "sticky" (including a ) causes most CVS + commands to act as if "-r " were on the command line. + + - A "sticky" indicates that the working directory + (and working files) are "on the branch". + + + 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 a branch, you must also create a set of procedures to + keep track of it. + + 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 will 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 whole 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: + + You are in a directory checked out (or updated) with the "-r + " option. To add to the branch named + you type: + + cvs add + cvs commit + + + Until the next release appears, you must explicitly specify the + branch_tag: + + cvs add + cvs commit -r + + One not so obvious side-effect 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 in 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 (working) on? + + Type: + cvs status + + and look at the "Sticky Tag" field for each file. If: + + 1. The *same* tag is on *every* file in your working tree, *and* + 2. That tag matches the contents of the ./CVS/Tag file, *and* + 3. That tag is a branch tag, + + then you know what branch you are working on. You can get sticky + Tag information directly from the ./CVS/Entries file instead of + "cvs status". + + If all the sticky Tags don't agree, then your directory is + temporarily inconsistent. This is a feature allowing you to make + changes (or perform merges) to individual files on multiple + branches without checking out the whole directory. + + The sticky Tag on each file in the ./CVS/Entries file (as + displayed by the "status" command) indicates what branch the + working file is on. New files should be added to the Tag stored + in ./CVS/Tag, but they are not. See the above question on adding + a new file to a branch. + + To force your entire working directory onto the same 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 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 use the CVS magic branch tag 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 a "branch point" tag at the same time as the Branch tag. + See 4C.3. + + + 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 execute 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 + you 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 you want to merge your branch back into the Main branch, you + are certain 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 3P.2 and 4C.6. + + (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 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 pairs 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. + + ++4C.16 How do I go back to a previous version of the code on a branch? + + You can avoid digging into RCS revision numbers (executing "update + -r " on each file) by trying one of these: + + 1. Use non-branch tags as you normally would. Non-branch tags + attach to specific revisions, so a "tag " command would + mark the revisions you have in your working directory, which + are on your branch. If you need to retrieve them, use "update + -r " + + Doing this overrides the sticky attached to your + working directory with a non-branch tag, which means you won't + be able to commit until you again move forward to the end of + the branch with "update -r ". + + 2. Use the "update -r :" trick. + + This is almost like using the '-D' option, but it looks for + revisions extant on only along the given branch. + + As in #1, you can't commit to this kind of working area, + because it has a sticky date referring to revisions in the + middle of a branch. + + + 3. You can branch a branch. + + If you add a branch tag to file in a working directory that was + checked out on a branch, you will branch the branch. This + works just fine, though you'll have to play some games to merge + everything back together again. You'll also create 6-part + revision numbers. (They'll be 8-part revision numbers if you + branch a branch that started out with some unmodified files the + Vendor branch. Think about it. How does revision + 1.2.4.2.4.2.2.1 grab you?) + + ++4C.17 Why do I get the latest files on the branch when I tried to + "update -r "? + + If "update -r " always retrieves the latest files on a + branch, then is a branch tag. A branch tag is supposed to + be used to grab a branch to work on. Since you can't modify a + file in the middle of a branch, checking out a will + give you the latest revision on the branch. + + If you want to "checkout" a specific collection of revisions, you + must use a "non-branch" tag. See the first part of 4C.16. + + You *can* branch off a branch, but it is rarely needed. + + + +---------------- +-- 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 (",v") files in the Repository? + 4D.3 Can I edit the ./CVS/{Entries,Repository,Tag} files? +=4D.4 Someone executed "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 access to the Repository by both CVS and RCS? +=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 in the middle of a large "commit", how do I run other + commands, like "diff" or "stat" without seeing 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 version 2.1 or later? + 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. + This can be a particular problem if you are trying to use CVS on + Frame or Interleaf (document processing systems) that produce + non-text output. + + [[I know of no solution to this other than to keep binaries in + some text form as "source" (real binaries could be uuencoded, + documents could be stored in "exported" (something like SGML) + form.]] + + + 4D.2 Can I edit the RCS (",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 commands, + including the "admin" command, which can talk directly to RCS. + + 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 in, or adding text to, log entries. (If you + have RCS 5.6 or later, you should use `cvs admin -m'.) + - Renaming or moving symbolic names. (You should `cvs admin -N' + instead.) + - Unlocking a file by changing the "locker" from someone else to + yourself. (It's safer to use `cvs admin -u -l'.) + - 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 executed "admin -o" and removed revisions to which + tags/symbols were attached. How do I fix them? + + It depends on what you mean by "fix". I can think of three ways + to fix your predicament: + + + 1. Remove the tags. + + Assuming you really wanted to get rid of the revision and its + associated tags, you can remove them with the "admin" command. + The "tag -d" command will only remove tags attached to existing + revisions. You can remove a tag, even if it is attached to a + non-existent filename, by typing: + + cvs admin -N + + 2. Retrieve the outdated revision. + + Using CVS and RCS, there is no way to reconstruct an outdated + revision. You will have to resort to backups. + + 3. Move the Tags to another revision in each file. + + If you want to move the tags to another valid revision, you + have two choices, both of which require that you find all the + revision numbers of the files you want to "tag" and execute the + following command sequences on each . + + a. Use "update" to grab the revision you want, then + execute a normal "tag" command to Tag that revision: + + cvs update -r + cvs tag + + b. Use "admin" to set the tag to a specific revision: + + cvs admin -N: + + +=4D.5 How do I move a magic branch tag? + + If the 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 re-executing the "tag" or "rtag" command + that created it. The will be moved to the place + where it would have appeared if you were tagging the file for the + first time. + + + 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 access to the Repository by both CVS and RCS? + + 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 "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 permission 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. In a two-camp society, you are asking for real trouble, + both in technical hassles to clean up and in political hassles to + soothe. + + +=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 + CVS sets the date to the one in the RCS file, the file would be + given a timestamp of 6PM and my Makefile wouldn't rebuild anything + that depended on it. Bad news. + + Note that the same logic applies to retrieving a revision out of + the repository to replace a deleted file. If CVS changes your + file in an existing working directory, whether it was because a + new revision was committed by someone else or because you deleted + your working file, the timestamp on the retrieved working file + *must* be set to the current time. + + When you first retrieve a file, there is no reason to expect any + particular timestamp on the file within your working area. But + later, when dependency checking is performed during a build, it is + more important for the timestamps on the local files to be + consistent with each other than than it is for working files to + match the timestamps on the files in the Repository. + + +#4D.9 While in the middle of a large "commit", how do I run other + commands, like "diff" or "stat" without seeing lock errors? + + Type: + cvs -n + + + The '-n' option to the main cvs command turns off lock checking, a + reasonable act given the promise offered by '-n' not to alter + anything. The "diff", "log" and "stat" commands all provide the + same information with and without the '-n' option. + + Warning: Ignoring locks can produce inconsistent information + across a collection of files if you are looking at the revisions + affected by an active commit. Be careful when creating "patches" + from the output of "cvs -n diff". If you are looking only at your + working files, tagged revisions, and BASE revisions (revisions + whose numbers are read from your CVS/Entries files), you should + get consistent results. Of course, if you catch a single file in + the middle of RCS activity, you might get some strange errors. + + Note that this is "cvs -n ". The visually similar + command "cvs -n" has no relation to the former usage and + has an entirely different meaning for each command. + + "cvs -n update" also works in the middle of a commit, providing + slightly different information from a plain "cvs update". But, of + course, it also avoids modifying anything. + + You could also use the RCS functions, "rlog" and "rcsdiff" to + display some of the information by referring directly to the + Repository files. + + You need RCS version 5 or later for the commands described above + to work entirely reliably. + + + 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 version 2.1 or later? + + A change in the overlap format was introduced in GNU diff3 + between versions 2.0 and 2.1. + + To get consistent rcsmerge behavior, you have four choices: + + 1. Go back to using GNU diff 1.15 or 2.0. If you want to use + 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 and set the + DIFF3_A macro to '1' as it tells you to in the Makefile: + + #define DIFF3_A 1 + + 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? + + You probably: + + - Use multiple Repositories. + + - Configured CVS to use absolute pathnames in the + ./CVS/Repository file. + + - Typed the "commit" command in one Repository with your + $CVSROOT pointing at the other. + + + "commit" and all other CVS commands will heed an absolute pathname + in the ./CVS/Repository file (or in 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. But each + Repository must be managed separately, creating additional work. + + Question 4A.1 provides a short description of setting up a + single Repository. A few additional considerations: + + 1. It is a good idea to start by creating a single Repository and + split it up (or create additional Repositories) only if you + believe it is really necessary. I would only create a new + Repository if the data is completely disconnected from the rest + of the main Repository. + + 2. If there is a lot of overlap among the developers working on + the collections of files you want to place in different + Repositories, or if there is any connection between those + collections, I would go out of my way to create a single + Repository. It is much easier to manage. + + 3. Disk space should not be a factor since you can build up a + Repository using symbolic links and/or remote mounts. + + 4. Each Repository is completely distinct. You can't check out + modules from different Repositories at the same time. A better + way of looking at it is that if you *can* check out two modules + or directories with a single "checkout" command (without + contortions or explicit absolute pathnames), then they are in + the same Repository. + + 5. To "checkout" modules from multiple Repositories, you must use + the "cvs -d" option on all CVS commands or alter your $CVSROOT + variable when you change focus to another Repository. If you + work with multiple Repositories, it is a good idea to configure + CVS to use absolute pathnames in the ./CVS/Repository file, + since most commands (other than "checkout") will use that file + rather than $CVSROOT. + + 6. 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. This is not a fanciful example -- a + Repository is occasionally duplicated for release purposes in + which case *all* the paths in the two Repositories are the + same. + + + 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 directory permissions to 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 s/he can't traverse the tree. (If you allow the world + execute bit (octal 001) 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. + + Note: If you are using a stupid file system that can't inherit + file groups from the parent directory (even with the "setgid" + (Octal 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 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 a different kind of sanity check performed for + different 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 + + + - 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. And it's + repeatable as many times as you like. + + + 4D.18 How do I use the "loginfo" files? + + See 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") command 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" ++4E.6 Explain: "error: RCS file name `xyz .c' contains white space" ++4E.7 Explain: cvs checkout: warning: is not (any longer) pertinent + + + **** 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. (Of course, this + won't fix filesystem failures. It will merely allow RCS (and + therefore CVS) to handle the file without error.) + + +=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, disk failure or SIGKILL signal. + + Go into the Repository and look for files with names similar to + "file.c,v", usually starting with ',', '_' or '#'. Make + sure they are really crash remnants and do not belong to + transactions in progress -- a recent last-modified timestamp + is a good indicator of a live transaction. 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 (creating ",v" files) and 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 it 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. + + ++4E.6 Explain: "error: RCS file name `xyz .c' contains white space" + + RCS 5.6 doesn't allow white space in filenames. Apparently this + restriction will be removed in RCS 5.7, but CVS may still require + that filenames have no white space in them. + + ++4E.7 Explain: cvs checkout: warning: is not (any longer) pertinent + + This message occurs in two instances: + + 1. When there is an entry in the ./CVS/Entries for file and + there is no RCS file in the Repository to back it up. + + If the working file exists, and hasn't changed (determined from + the timestamp) it is removed. + + + 2. When you try to check out a piece of the Repository with: + + cvs checkout some/place/in/repository/tree + + and at least the first element of the path (i.e. "some" in the + above) exists, but some part of the rest of it does not. + + The checkout command checks the modules file first for the + whole path, then for a prefix of the path as a module name. If + it doesn't find *any* portion of your path in the modules file, + it says: + + cvs checkout: cannot find module `' - ignored + + If it finds some set of prefix directories, it prints the + message you see. + + In practice this is usually a spelling error. + + 3. If the Repository files you are trying to check out or update + are not readable by you, the same problems can occur. + Check the permissions on the files involved. + + +---------------- +-- Section 4F -- Related Software +---------------- + + **** Questions: + ++4F.1 How do I use CVS under Emacs? Is there an Emacs cvs-mode? ++4F.2 What is GIC (Graphical Interface to CVS)? ++4F.3 What is CAVEMAN? + + + **** Answers: + +This section covers a small handful of subsystems that connect to CVS in +some way. Most are "front ends" in that they offer a different user +interface to CVS, but use CVS to perform the normal tasks. + + NOTE: The short summaries below combine details culled from public + announcements of the listed software with the personal opinions of + the author of the FAQ entry. + + ++4F.1 How do I use CVS under Emacs? Is there an Emacs cvs-mode? + + The pcl-cvs package distributed with CVS 1.3 is an emacs package + that helps with the update/commit process. When you are ready to + update, you use the 'cvs-update' command within emacs. This + executes "update" and fills a cvs-mode buffer with a line for each + file that changed. The most helpful features are: descriptive + words for what happened (i.e. Merged or Conflict rather than 'U'), + single keys bound to diffs and commits, and the ability to mark + arbitrary groups of files, possibly from different directories, + for commit as a whole. + + All the developers in my group that use emacs find pcl-cvs a much + friendlier and more helpful way to update/commit than raw cvs. + One vi user even converted to emacs just to use pcl-cvs. + + Contributed by Jeffrey M Loomis + ++4F.2 What is GIC (Graphical Interface to CVS)? + + GIC is a window interface to CVS written in Tcl/Tk, which attempts + to hide the normal CVS command line options from novice users. + + GIC works only in a single directory at a time, but it offers most + of the CVS commands you would normally use. + + GIC can be obtained by anonymous ftp to + + ftp.cpsc.ucalgary.ca:/pub/marwood/gic-1.0b5.tar.Z + + contact + David Marwood + marwood@cpsc.ucalgary.ca + + [[Does someone want to try to describe this better?]] + + ++4F.3 What is CAVEMAN? + + CAVEMAN is a front end to CVS written in PERL providing a + collection of features desired by the site where it was developed. + + - The ability to spread a "project" over multiple Repositories. + - Optional automatic tagging after each commit. + - Additional locking of files. + - Extra before and after program hooks. + - A layer of event logging. + - All sorts of error messages. + - Many changes to the semantics of commands. + + It is available via anonymous ftp on llnl.gov [128.115.18.253] as + gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary with time.) + + contact + Kathleen Dyer kdyer@llnl.gov + (510)423-6803 + (510)423-5112 FAX + + + [[Does someone want to try to describe this better?]] + + + +---------------- +-- Section 4G -- Other Systems +---------------- + + **** Questions: + + 4G.1 I use a NeXT. Is there anything I need to know? + 4G.2 I use OS/2. Is there anything I need to know? + 4G.3 I use SCO Unix. Is there anything I need to know? + 4G.4 I use AIX. Is there anything I need to know? +=4G.5 I use IRIX. Is there anything I need to know? +=4G.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. + + 4G.1 I use a NeXT. Is there anything I need to know? + + 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. + + [[Anything else?]] + + + 4G.2 I use OS/2. Is there anything I need to know? + + [[Well?]] + + + 4G.3 I use SCO Unix. Is there anything I need to know? + + [[Well?]] + + + 4G.4 I use AIX. Is there anything I need to know? + + [[Well?]] + + +=4G.5 I use IRIX. Is there anything I need to know? + + If you see "uid" numbers where you would expect user names, try + adding -lsun to the link line. Without it CVS is unable to + retrieve "passwd" data through NIS. + + +=4G.6 I use an HP system. Is there anything I need to know? + + HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. + CVS does not work with RCS version 3; it requires RCS version 4 + or later. Your best bet is to find the latest version of RCS + and install it somewhere. + + HP-UX 8.07 has a serious bug with the mmap system call and NFS + files; the bug can crash the operating system. Make sure that + you configure RCS to avoid mmap by setting has_mmap to 0 in + RCS's conf.h. This bug is fixed in HP-UX 9. + + Contributed by Paul Eggert + + If using the setgid() trick described in 4D.16, you will have to + create an entry in the /etc/privgroup file to give the group + assigned to the cvs executable setgid permission (see + setprivgrp(1m)). Additionally, if you are restricting "read" + access to the Repository by limiting access to the executable + (this requires yet another group), then you will require that + /etc/logingroup exists and is configured correctly (usually it's + just alink to /etc/group). + + Contributed by Dale Woolridge + + +============================================= +== 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, + then added all sorts of features. He continues to maintain CVS. + + Jeff Polk wrote much of the 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 (performed in + Jan/Feb, 1993), I polled hundreds of people and I rephrased all + sorts of text found on the net. Because there are so many posers + of questions, I will list only those who contribute answers or + help significantly with the content and structure of this + document. + + Unless a name is included in the answer itself, I didn't use + anyone else's answers verbatim. On the other hand, I did use + ideas and information provided by many. The people whose email + postings have added to this document or who have added to my + understanding are: + + Brian Berliner , CVS maintainer. + Paul Eggert , RCS maintainer. + + Gray Watson + Per Cederqvist + Pete Clark + + all of whom have sent me copies of their tutorials + and local CVS documentation. + + Additional contributors, who have sent me ideas, text, corrections + and support include (in alphabetical order): + + Donald Amby + Tom Cunningham + Don Dwiggins + Dan Franklin + Jeffrey M Loomis + Barry Margolin + Mark K. Mellis + Chris Moore + Gary Oberbrunner + Steve Turner + Dave Wolfe + Dale Woolridge + + Plus a myriad Thinking Machines people who posed hundreds of + questions. + + + Please send corrections. If I forgot you, remind me and I'll add + your name to the list. + + +---------------- +-- 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 executed "checkout" into an 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? ++5B.8 Why doesn't the "-I !" option work in update and import? + + + **** Answers: + + 5B.1 Why can't CVS handle deletion of directories? + + An oversight, probably. [[Fixed in a future release?]] + + +=5B.2 Why can't CVS handle the moving of sources from one place in the + directory hierarchy to another? + + A "renaming database" has been proposed to track the history of + pathname changes in the Repository. A general solution is a + difficult problem. See 4B.9 and 2C.4. + + +=5B.3 Why does "checkout" recurse indefinitely if an alias contains + its own name? + + A bug in the handling of aliases. [[I'll remove this one when + the bug is 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 any two 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 exist 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 , 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 executed "checkout" into an 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 display 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. + ++5B.8 Why doesn't the "-I !" option work in update and import? + + A bug. See the patch named "unoff/import_ignore" in the CVS FTP + archive + + + [[Section 5B 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? + + First make sure it is a bug. Talk to your friends, coworkers and + anyone you know who uses CVS. Search this FAQ for related issues. + Then test it carefully. Try out variations to narrow down the + problem. Make sure it is repeatable. Look for workarounds so you + can report them. + + If you are still sure it's a bug and you tried to fix it, skip to + the next question. Otherwise, send a message to the info-cvs + mailing list containing one of the following: + + 1. If you have a good repeatable case and you think you know what + is going on, then describe the problem in detail. Include + a workaround if you have one. + + 2. If you have no idea what is going on, go ahead and send a + question to the info-cvs mailing list. Include any information + you have describing the symptoms. + + If careful testing reveals an RCS bug rather than a CVS bug, you + can sendbug reports to: rcs-bugs@cs.purdue.edu + + +=5C.2 Where do I send fixes and patches? + + First make sure the "fix" does something useful. Have someone to + review your fix. It is better to spend a bit of one person's + thinking time than to waste the time of thousands of people trying + to understand your fix. + + If you tried to fix it and the patch is small, include the patch + in your message. Make sure the patch is based on the latest + released version of CVS. + + If you tried to fix it and the patch is large, you should think + about why it is so large. Did you add a generally useful feature, + or did it grow out of hand? + + If you still believe it is solid, send it to the maintainer of the + FTP archive (currently the author of this FAQ) for inclusion in + the CVS FTP archive and to Brian Berliner, the maintainer of CVS. + + + 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?]] + + + Paul F. Kunz has produced a version of + CVS (RCVS) that runs remotely. + + On the host "ftp.slac.stanford.edu", you can find: + Sources: pub/sources/rcvs-0.5.0.tar.Z + Paper: pub/preprints/slac-pub-5923.ps + + + [[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 incomplete sections. + + 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 could write a regression test suite. Or at least a scaffold + into which we can drop tests. + + You can write specs for new features, 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 similar software? + 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. Related Software + G. 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 + (e.g. 20's, 50's, 100's) when issuing complex CVS commands? ++1B.7 How do I get files out of the archive if I don't have FTP? + +---------------- +-- Section 1C -- How does CVS differ from other similar software? +---------------- +=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? ++1C.8 How does CVS differ from TeamNet? ++1C.9 How does CVS differ from ProFrame? ++1C.10 How does CVS differ from CaseWare/CM? ++1C.11 How does CVS differ from Sublime? + +---------------- +-- Section 1D -- What do you mean by . . .? (Definitions) +---------------- +#1D.1 What are "The Repository", "$CVSROOT" and "CVSROOT"? + 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? ++1D.12 What does "merge" mean? + + +========================================== +== 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 edit a 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 can 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? ++2C.8 How do I split a file into pieces, retaining revision histories? + +---------------- +-- 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 an 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.3 file 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 How do I restrict the "admin" command? The -i flag in the modules + file can restrict commits. What's the equivalent for "admin"? ++3B.6 I backed out a revision with "admin -o" and committed a + replacement. Why doesn't "update" retrieve the new revision? + +---------------- +-- 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 checked out? +#3C.8 How can I lock files on checkout the way RCS does? ++3C.9 What is "checkout -s"? How is it different from "checkout -c"? + +---------------- +-- 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 `X' is not a branch +=3D.7 Why does "commit -r " put new files in the attic? ++3D.8 Why does "commit -r " ignore on an added file? + +---------------- +-- Section 3E -- "diff", "di", "dif" +---------------- + 3E.1 What is "diff" for? +=3E.2 Why did "diff" display nothing when I know there are later + committed revisions in the Repository? +#3E.3 How do I display what changed in the Repository since I last + executed "checkout", "update" or "commit"? +=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 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 " and + "cvs history -t "? + 3G.8 Why does "cvs history -c -t " 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 "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 compiles files + with a suffix of ".yarg" and whose comment prefix is "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? ++3H.15 Explain: ERROR: cannot create link to : Permission denied + +---------------- +-- 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 committed exactly 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 when it appears to try? + 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? ++3N.3 Shouldn't the status "Needs Checkout" be "Needs Update"? + +---------------- +-- 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 "tag" labels 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 After a "tag " in my working directory, why doesn't "checkout + -r " somewhere else produce copy of my current files? +#3O.8 Why doesn't "tag" write a history record the way "rtag" does? + +---------------- +-- Section 3P -- "update", "up", "upd" +---------------- + 3P.1 What is "update" for? +=3P.2 What do 'U', 'M' and 'C' mean when I type "update"? Are they + different for "cvs -n 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" say 'M' both for plain modified files and for + successful (i.e. conflict-free) merges? Aren't they different? +=3P.6 After a merge ("update" or "update -j"), why doesn't CVS remember + the conflict 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 execute "update"? + + +=============================================== +== Section 4 ==== Advanced Topics ==== +=============================================== + +---------------- +-- Section 4A -- Installing CVS +---------------- +#4A.1 What do I have to do before I install CVS? + 4A.2 How do I configure the CVS programs? +=4A.3 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 stored in the Repository besides in the + $CVSROOT/CVSROOT directory? + 4B.4 How do I put sources into the Repository? +=4B.5 What file permissions should I use on (and in) 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? + 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? ++4B.19 How do I change permissions on a file in the Repository by using + a CVS command? (i.e. without using "chmod 777 $CVSROOT/dir/file") + +---------------- +-- 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 whole 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 (working) 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? ++4C.16 How do I go back to a previous version of the code on a branch? ++4C.17 Why do I get the latest files on the branch when I tried to + "update -r "? + +---------------- +-- 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 (",v") files in the Repository? + 4D.3 Can I edit the ./CVS/{Entries,Repository,Tag} files? +=4D.4 Someone executed "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 access to the Repository by both CVS and RCS? +=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 in the middle of a large "commit", how do I run other + commands, like "diff" or "stat" without seeing 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 version 2.1 or later? + 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" ++4E.6 Explain: "error: RCS file name `xyz .c' contains white space" ++4E.7 Explain: cvs checkout: warning: is not (any longer) pertinent + +---------------- +-- Section 4G -- Other Systems +---------------- + 4G.1 I use a NeXT. Is there anything I need to know? + 4G.2 I use OS/2. Is there anything I need to know? + 4G.3 I use SCO Unix. Is there anything I need to know? + 4G.4 I use AIX. Is there anything I need to know? +=4G.5 I use IRIX. Is there anything I need to know? + 4G.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 executed "checkout" into an 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? ++5B.8 Why doesn't the "-I !" option work in update and import? + +---------------- +-- 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 + +# Local Variables: +# mode: text +# fill-column: 74 +# fill-prefix: "\t" +# End: -- cgit v1.1