diff options
Diffstat (limited to 'gnu/usr.bin/cvs/FAQ')
| -rw-r--r-- | gnu/usr.bin/cvs/FAQ | 10006 |
1 files changed, 0 insertions, 10006 deletions
diff --git a/gnu/usr.bin/cvs/FAQ b/gnu/usr.bin/cvs/FAQ deleted file mode 100644 index 84d4a3a..0000000 --- a/gnu/usr.bin/cvs/FAQ +++ /dev/null @@ -1,10006 +0,0 @@ - -Archive-name: cvs-faq -Hand Revision: 3.5 <<== Include this in your comments -Last Updated: 1995/03/09 -$Revision: 1.4 $ -$Date: 1995/10/02 23:13:07 $ - -=========================================================================== -== 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: - - Although an 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 <dgg@world.std.com> - - - Major revisions contain enough alterations to render change markers - meaningless. (Major revisions are those with a final digit of '0', - such as 2.0 or 3.0.) To help readers of previous versions of this - document, minor revisions will be annotated: - - 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. - - - Trivial changes, such as question reordering or spelling and grammar - corrections are not marked. Deleted questions will simply disappear, - as will any question that can be answered by "get the latest release". - - Editorial comments are delimited by pairs of "[[" & "]]". They - contain either references to the (usually unfinished) nature of the - FAQ entry itself, version-specific comments to be removed (or - altered) when new revisions of CVS are released or snide remarks from - the editor. - - If you plan to do anything with this document other than: - - - Read it. - - Redistribute the whole document along with the date and revision. - - Post sections as answers to CVS questions (as long as you - identify it as coming from the FAQ.) - - talk to the author first. - - - -============================================ -== 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 and Merging - D. Tricks of the Trade - E. Internal errors - F. Related Software - G. Engineering - H. Other Systems - - 5. Past & Future - A. Contributors. - B. Bugs and Patches - C. Development - D. Professional Support - - 6. Table of Contents - - -Final note: - - Except for the "Past & Future" section, all answers in this - document refer to CVS version 1.4. The latest released version is - 1.5. - - -============================================ -== 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? - - - **** 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 source changes 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 saves its version-control information in RCS files stored 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 a "checkout" command, handing it a - module name or directory path (relative to the $CVSROOT variable) - you want to work on. CVS copies the latest revision of each file - in the specified module or directory out of the Repository and - into a directory tree created in your current directory. You may - specify a particular branch to work on by symbolic name if you - don't want to work on the default (main or trunk) branch. - - You may then modify files in the new directory tree, build them - into output files and test 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" produces 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 handle source control for files in three major - situations: - - 1. Multiple developers working on the same files. - - The major advantage of using CVS over the 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 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. Tracking a stream of releases from a source vendor. - - If you are making changes to sources distributed by someone - else, the CVS feature, called the Vendor Branch, allows you to - combine local modifications with repeated 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 may require work. - (e.g. GNU programs, X, CVS itself, etc.) - - - 3. Branching development. - - 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.) - - CVS's branch support is a bit primitive, but it was designed to - allow you to create branches, work on them for while and merge - them back into the main line of development. You should also - be able to merge work performed on the main branch into the - branch you are working on. 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. a tree of 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 require your Makefiles or build - procedures 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 use CVS to maintain the tools created to - support such a build system (scripts, Makefiles, etc). - - - CVS is not a substitute for management. - - You and your project leaders are expected to plan what you are - doing. Everyone involved must be aware of schedules, merge - points, branch names, release dates and the range of - procedures needed to build products. (If you produce it and - someone else uses it, it is a product.) CVS can't cover for a - failure to manage your project. - - 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 command into dropping - conflict markers into the merged file. - - CVS is not capable of figuring out distributed conflicts in - program logic. For example, if you change the arguments to - function X defined in file A and, at the same time, edit 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. - - - ----------------- --- 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 files out of the archive if I don't have FTP? - 1B.4 How do I get a copy of the latest version of CVS? - 1B.5 Is there a mailing list devoted to CVS? How do I find it? - 1B.6 What happened to the CVS Usenet newsgroup I heard about? - - - **** Answers: - - 1B.1 How do I get more information about CVS? - - 1. The first thing I would do is to read the Info file that comes - with the CVS sources under "doc". You can format and read the - cvs.texinfo file in two ways: 1. Use TeX to format it and a - "dvips" command to print it and 2. Install the cvs.info files - that are created by the Makefile and read them online using the - Emacs "info-mode" or a stand-alone "info" reader. - - 2. Then I'd run "cvsinit" to set up a Repository and read the man - page while trying out the commands. - - Type "cvs -H" for general help or "cvs -H command" for - command-specific help. - - 3. For background, you can read the original CVS paper (in the - source tree, under "doc"). It describes the purpose of CVS and - some of how it was designed. Note that the emphasis of the - document (especially on multiple vendors providing the same - sources) is somewhat out of date. - - 4. For more detailed information about "internals", read the man - pages for RCS. If you are a programmer, you can also read the - source code to CVS. - - 5. Other information and tutorials may be available in the "doc" - directory of the FTP archive described below. - - 6. For current information, and a fair amount of detail, 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 extra documentation, patches - and a copy of the latest release. - - ftp ftp.delos.com - >>> User: anonymous - >>> Passwd: <Your Internet address> - 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. - - A WWW home page is also available at http://www.delos.com/cvs. - - - 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. FTPMAIL service is available from the same host as the FTP - server described above. Send mail to "ftpmail@delos.com" - containing "help" in the body of the message. For example, - on most Unix systems, you can type: - - echo help | Mail ftpmail@delos.com - - The FTPMAIL server will respond with a document describing how - to use the server. If the "Mail" command doesn't exist on your - system, try "mailx", "/usr/ucb/mail" or "/bin/mail". - - - 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@decwrl.dec.com - 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 are - mirrors of the FSF archive on UUNET and other large Internet sites. - - Program(s) Suggested revision - ----------- ----------------------- - CVS 1.5 - RCS 5.7 (latest version available today) - GNU diff 2.7 (or later) [contained in diffutils-2.7] - GDBM 1.5 (or later) [optional] - - The GNU version of diff is suggested by both the RCS and CVS - configuration instructions because it works better than the - standard version. - - 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 can probably afford. - - 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 a mailing list devoted to CVS? How do I find it? - - 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. - Throughout 1994, the list received an average of 100 messages per - month. - - 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 is maintained in the FTP archive - mentioned above. - - - 1B.6 What happened to the CVS Usenet newsgroup I heard about? - - - A Usenet newsgroup named "gnu.cvs.info" was announced in April - 1993, with an expected creation date of August, 1993. - - As of this writing (October, 1994) it hasn't appeared. - - If the newsgroup is ever created, it and the mailing list should - be bidirectionally gatewayed, meaning that you only need access to - one of them. Anything sent to the mailing list would be - automatically posted to "gnu.cvs.info" and anything posted to the - newsgroup would be automatically mailed to "info-cvs". - - A newsgroup would be easier to use than a mailing list. If the - CVS newsgroup ever shows up, ask your system administrator whether - you get the "gnu" hierarchy. If so, select a news reader and dive - in. - - ----------------- --- 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/SparcWorks? - 1C.5 How does CVS differ from Aegis? - 1C.6 How does CVS differ from Shapetools? - 1C.7 How does CVS differ from TeamNet? - 1C.8 How does CVS differ from ProFrame? - 1C.9 How does CVS differ from CaseWare/CM? - 1C.10 How does CVS differ from Sublime? - 1C.11 How does CVS differ from PVCS? - 1C.12 How does CVS differ from CMVC? - - - **** 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 - multiple files on the command line, but they are handled by - iterating over individual files. There is no pretense of - coordinated interaction among groups of 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 distributed client-server version control system. - ClearCase is a variant DSEE tools, formerly available on Apollo - platforms. The ClearCase tool set includes a few X-based - interface tools, a command-line interface, and C programmer API. - It is currently available on Sun, HP, SGI and OSF/1 platforms. - - ClearCase uses a special Unix filesystem type, called "mvfs" - for "multi-version file system". Conceptually, mvfs adds - another dimension to a regular Unix filesystem. The new - axis is used to store the different versions of files and to - provide a tree-hierarchical view of a collection of objects that - might be scattered across any number of separate hosts on your - local network. - - Each user acquires a "view" into the file database by creating a - special mvfs mount point on their machine. Each view has a - "configuration spec" containing a set of selection rules that - specify the particular version of each file to make visible in - that view. You can think of a "view" as a work area in CVS, except - that the files don't really exist on your local disk until you - modify them. This technique conserves disk space because it - doesn't keep private copies of read-only files. - - Another advantage is that a view is "transparent" 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 (by - using what are called "unreserved checkouts" and the - checkin/checkout development model with file locking. Directories - are version-controlled objects as well as files. A graphical merge - tool is provided. Like RCS, 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 dependency lists 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. Hyper-links - between version controlled 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) - - Originally contributed by Steve Turner - Edited by the author of this FAQ. - - -#1C.4 How does CVS differ from TeamWare/SparcWorks? - - TeamWare is a configuration management tool from Sun Microsystems, - a part of SparcWorks. It uses the same copy and merge model as - CVS. The central abstraction is a workspace, which corresponds to - either a CVS branch or a checked out module. TeamWare allows you - to manipulate workspaces directly, including moving and merging - code between workspaces. You can put your workspace on tape and - continue to work with it at home, just like you can with CVS. - TeamWare is built upon and compatible with SCCS. - - TeamWare provides both a command line interface and a graphical - interface. The CodeManager tool will display the project as a - tree of workspaces, and allows you to manipulate them with drag - and drop. The other tools are VersionTool that displays and - manipulates a dag with a version history of a single file, - CheckPoint that will create symbolic tags, MakeTool, a make - compatible tool with a GUI, and FileMerge which will interactively - merge files when needed (like emerge for emacs). If you have a - sun, you can try /usr/old/mergetool for an old SunView version of - FileMerge. - - Email: sunprosig@sun.com - - Originally extracted from TeamWare - Marketing literature by Per Abrahamsen. - Edited by the author of this FAQ. - - - For more information, contact: - - SunExpress, Inc. - P.O. Box 4426 - Bridgeton, MO 63044-9863 - (800)873-7869 - - - 1C.5 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.6 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 version - controlled 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.7 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.8 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 RS6000, 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.9 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.10 How does CVS differ from Sublime? - - Produced by AT&T. - - [[Need more info here.]] - - - 1C.11 How does CVS differ from PVCS? - - PVCS works on single files like RCS and SCCS, CVS works on - complete subsystems. PVCS has a make utility (called a - configuration builder), CVS does not. PVCS has a GUI interface - for Unix, DOS, OS/2, and MS Windows. - - Intersolv, Inc. - 1700 NW 167th Place - OR 97006 - - Contributed by Per Abrahamsen - [Extracted from Intersolv Marketing literature.] - - - 1C.12 How does CVS differ from CMVC? - - CMVC is an IBM Configuration Management and Version Control - system. (Though I'm not certain that's the right acronym - expansion.) It runs on Suns, HPs, RS6000s, OS/2 and Windows. - - Other than revision control, it apparently has features to manage - releases, bug tracking and the connection between alterations and - reported bugs and feature requests. It is a client/server system, - based on a choice of commercial Relational Database systems, and - it provides a Motif or command line interface. - - Unlike CVS, it uses a strict locking protocol to serialize source - code alterations. - - ----------------- --- 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. See 4B.2 for more - information about CVSROOT files. - - - 1D.2 What is an RCS file? - - An RCS file is a text file 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. RCS file names normally end in ",v", but - that can be altered (via the RCS -x option) to conform to file - naming standards on platforms with unusual filename limitations. - - - 1D.3 What is a working file? - - A working file is 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)? - - A working directory is the place where you work and the place - from which you "commit" files. - - The "checkout" command creates a tree of working directories, - filling them with working files. Each working directory contains - a sub-directory named ./CVS containing three administrative files, - which are created by "checkout" and are always present: - - ./CVS/Entries - contains information about working files. - - ./CVS/Repository - contains the location of the directory within the - Repository that was used to create the working directory. - - ./CVS/Root - contains the value of $CVSROOT at the time you created - the working directory. - - Other files may also appear in ./CVS depending on the state of - your working directory: - - ./CVS/Tag - contains the "sticky tag" associated with the whole - directory. See 3A.2 for its main purpose. - [Created by "checkout" or "update" when using "-r <tag>".] - [Deleted by "checkout" or "update" when using '-A'.] - - ./CVS/Entries.Static - contains a fixed list of working files. If this file - exists, an "update" doesn't automatically bring newly - added files out of the Repository. - [Created and maintained by hand.] - - ./CVS/Checkin.prog - contains a program to run whenever anything in the - working directory is committed. - [Created by checkout if "-i <prog>" appears in the - modules file for the checked-out module.] - - ./CVS/Update.prog - contains a program to run whenever anything in the - working directory is updated. - [Created by checkout if "-u <prog>" appears in the - modules file for the checked-out module.] - - ./CVS/<file>,p - ./CVS/<file>,t - contain (possibly zero-length) state information about an - "add" that has not been committed. - [Created by "add".] - [Deleted by "commit" or "remove".] - - - 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. You normally execute "checkout" only once per - working directory (or tree of working directories), maintaining - them thereafter with the "update" command. - - See section 3C on the "checkout" command. - - - 1D.6 What is a revision? - - A "revision" is a version of a file that was "committed" - ("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" ("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. - - The CVS "Tag" is implemented by applying RCS "symbols" to each - individual file. The Tags on a file (or collection of files) may - be displayed using the "log" command. - - - 1D.8 What are "HEAD" and "BASE"? - - HEAD and BASE 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 - can become different in two ways: - - 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 <rev/tag>" or "-D <date>". 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 again by executing "update -A". - - - 1D.9 What is a Branch? - - In general, a branch is any mechanism that allows one or more - developers to modify a file without affecting anyone other than - those working on the same branch. - - There are four kinds of "branch" CVS can manage: - - 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 (or its - parent branch, if that is not the Main Branch) 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, its - purpose and the way it is managed are different. The major - difference is that a Release branch is normally 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 that 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 <rev> -j <rev>". (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 can be files, - directories or module substitutions. No relative paths. - - A module substitution occurs when you use a '&module-name' - reference. The module-name referred to is logically - substituted for the '&module-name' string. - - - 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 /bin/emacs.helper gnu/emacs - - The files checked out are exactly the same as the files - "checkout" would retrieve 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 /bin/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, plus exceptions. - - Example: - - my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c - - - The exception "!emacs/test" above is functionally equivalent - to specifying "!emacs/tests" on the "checkout" command line. - - - 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. - - See 4G.2 for some specific ideas about how to use the modules file. - - - 1D.12 What does "merge" mean? - - A merge is a way of combining changes made in two independent - copies of a common starting file. Checking out an RCS revision - produces a file, so for the purposes of a merge "file" and - "revision" are equivalent. So, we can say there are always three - "files" involved in a merge: - - 1. The original, starting, "base" or "branch point" file. - 2. A copy of the base file modified in one way. - 3. Another copy of the base file modified in a different way. - - 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 <branch_tag> {optional files}" command merges - changes made on the given branch into your working files, which - is presumed to be on the Main line of development. - - See 4C.6 - - 3. The "update -j <rev> -j <rev> {optional files}" command merges - the difference between two specified revisions into files in - your working directory. The two revisions <rev> are usually on - the same branch and, when updating multiple files, they are - most useful when they are Tag names rather than numeric - revisions. - - 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 most likely assigned one or more persons to - understand, baby-sit and administer the CVS programs and the data - Repository. I call these persons Repository Administrators. They - should 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 was built with the RCSBIN directory set - to null (""), and you don't set the RCSBIN - variable mentioned below, 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. - - 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. - - TMPDIR Used during import. It might also be used if your - platform's version of mktemp(3) is unusual, or - you have changed the source to use tmpnam(3). - - - - 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? - - cd <where you have some space to work> - 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: - - checkout, update, commit, diff, log, status, tag, add - - -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 <module>, all tags are named <tag> (branch tags are - named <branch_tag>) and all files are named <file>. - - The checkout command will take a relative path name in place - of a module name. If you use a relative pathname in place of - <module>, you should use the same relative path every place - you see <module> 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 <module> directory that "checkout" created? - 2B.4 How do I find out what has changed since my last update? - 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 will be told that your - module name is <module>. Then type: - - cvs checkout <module> - cd <module> - emacs <file> # Isn't Emacs a synonym for edit? - cvs commit <file> - - 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 <module> in the example above. - - To work on a single file, you'll have to change "cd <module>" to - "cd `dirname <module>`". - - - 2B.2 If I edit multiple files, must I type "commit" for each one? - - No. You can commit a list of files and directories, including - relative paths into multiple directories. You can also commit - every modified file in the current directory or in all directories - and subdirectories from your current directory downward. See 3D.2. - - - 2B.3 How do I get rid of the <module> directory that "checkout" created? - - Change your directory to be the same as when you executed the - "checkout" command that created <module>. - - If you want to get rid of the CVS control information, but leave - the files and directories, type: - - cvs release <module> - - If you want to obliterate the entire directory, type: - - cvs release -d <module> - - ("release -d" searches through the output of "cvs -n update" and - refuses to continue if the "update" command finds any modified - files or non-ignored foreign files. Foreign directories too.) - - If you don't care about keeping "history", or checking for - modified and foreign files, you can just remove the whole - directory. That's "rm -rf <module>" under Unix. - - - 2B.4 How do I find out what has changed since my last update? - - There are many ways to answer this. - - To find out what you've changed in your current working directory - since your last checkout, update or 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 mark files CVS doesn't know about in - your working directory with a '?' indicator. - - ? <file> - - To add <file> to the Repository, type: - - cvs add <file> - cvs commit <file> - - See 3A.[2-5] and 4C.8 for branch and merge considerations. - - - 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 six possible results when you type - the "update" command: - - 1. If the file is lying in your working directory, but is not - under CVS, it will do nothing but print: - - ? <file> - - 2. If neither you nor anyone else has committed changes to <file>, - since your last "checkout", "update" or "commit", "update" - will print nothing and do nothing. - - 3. If you have made no changes to a working file, but you or - others have committed changes to the Repository since your last - "checkout", "update" or "commit" of this working file, CVS will - remove your working file and replace it with a copy of the - latest revision of that file in the Repository. It will print: - - U <file> - - You might want to examine the changes (using the CVS "diff" - command) to see if they mesh with your own in related files. - - 4. If you have made changes to a working file, but no one has - changed your BASE revision (the revision you retrieved from the - Repository in your last "checkout", "update" or "commit"), - "update" will print: - - M <file> - - Nothing changes. You were told that you have a modified - file in your directory. - - 5. If you have made changes to your working file and you or others - have committed changes to the Repository, 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. "update" will print: - - RCS file: /Repository/module/<file> - retrieving revision 1.X - retrieving revision 1.Y - Merging differences between 1.X and 1.Y into <file> - M <file> - - If you execute "diff" before and after this step, you should - see the same output, since both the base file and your working - file changed in parallel. This is one of the few times the - otherwise nonsensical phrase "same difference" means something. - - 6. If both you and those who committed files (since your last - checkout, update or commit) have made changes to the same - section of a file, CVS will merge the changes into your file as - in #5 above, but it will leave conflict indicators in the file. - "update" will print: - - RCS file: /Repository/module/<file> - retrieving revision 1.X - retrieving revision 1.Y - Merging differences between 1.X and 1.Y into <file> - rcsmerge warning: overlaps during merge - cvs update: conflicts found in <file> - C <file> - - This is a "conflict". The file will contain markers - surrounding the overlapping text. The 'C' conflict indicator - is sticky -- subsequent "update" commands will continue to show - a 'C' until you edit the file. - - You must examine the overlaps with care and resolve the problem - by analyzing how to retain the features of both changes. See - 2D.7 and 3P.6 for more details on conflict resolution. - - - 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 <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 <tag> <module> - - - 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 <tag>" option. - - 2. By date, via the "-D <date>" option. - - 3. By branch tag (a type of tag with a magic format), via the - "-r <branch_tag>" option. - - 4. By date within a branch, via the "-r <branch_tag>:<date>" - option. - - 5. By an explicit branch revision number ("-r <rev>"), 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 whole branch might have been abandoned - in the past. - - 6. An explicit revision number: "-r <rev>" Though this works, it - is almost useless for more than one file. - - - You type: - - cvs checkout <option-specified-above> <module> - cd <module> - - - 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 with the - rest of the developers working on your branch. - - 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.16 on - Administrator responsibilities. - - ----------------- --- 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 non-CVS 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 non-CVS sub-directories in my working directory? - - Yes. Unless the directory exists in the Repository, "update" will - skip over them and print a '?' the way it does for files you - forgot to add. You can avoid seeing the '?' by adding the name - of the foreign directory to the ./.cvsignore file, just ask you - can do with files. - - If you explicitly mention a foreign directory on the "update" - command line, it will traverse the directory and waste a bit of - time, but if any directory or sub-directory lacks the ./CVS - administrative directory, CVS will print an error and abort. - - - 2C.2 How do I add new sub-directories to the Repository? - - The "add" command will work on directories. You type: - - mkdir <dir> - cvs add <dir> - - It will respond: - - Directory /Repos/<dir> added to the repository - - and will create both a matching directory in the Repository and a - ./CVS administrative directory within the local <dir> 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 <file> - cvs remove <file> - - CVS registers the file for removal. To complete the removal, you - must type: - - cvs commit <file> - - 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 (to some, the only acceptable) way to get the - effect of renaming, while preserving the change log: - - 1. Copy the RCS (",v") file directly in the Repository. - - cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v - - By duplicating the file, you will preserve the change - history and the ability to retrieve earlier revisions of the - old file via the "-r <tag/rev>" or "-D <date>" options to - "checkout" and "update". - - 2. Remove the old file using CVS. - - cd <working-dir>/<odir> - rm <ofile> - cvs remove <ofile> - cvs commit <ofile> - - This will move the <ofile> to the Attic associated with - <odir>. - - 3. Retrieve <nfile> and remove all the Tags from it. - - By stripping off all the old Tags, "checkout -r" and - "update -r" won't retrieve revisions Tagged before - the renaming. - - cd <working-dir>/<ndir> - cvs update <nfile> - cvs log <nfile> # Save the list of Tags - cvs tag -d <tag1> <nfile> - cvs tag -d <tag2> <nfile> - . . . - - - 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 your build system (e.g. Makefile) in - your <working-dir> to know about the name change. - - Warning: Stripping the old tags from the copied file will allow - "-r <tag>" to do the right thing, but you will still have problems - with "-D <date>" because there is no place to store the "deletion - time". See 5B.3 for more details. - - - 2C.5 How do I make sure that all the files and directories in my - working directory are really in the Repository? - - A "cvs update", or "cvs -n update" (which won't modify your - working directory) will display foreign elements, which have no - counterpart in the Repository, preceded by a '?'. To register - foreign directories, you can use "cvs add". To register foreign - files, you can use "cvs add" followed by "cvs commit". - - You could also checkout your module, or the Repository directory - associated with your working directory, a second time into another - work area and compare it to your working directory using the - (non-CVS) "diff -r" command. - - 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 modified, - update and conflict indicators ('M', 'U', and 'C' respectively) 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 <branch_tag> - - 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 <branch_tag> - - and commit a file in the normal way: - - cvs commit <file> - - then a branch will be created in the underlying <file>,v file and - the new revision of <file> 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 start with the provided template for the "modules" file, - the CVSROOT and the "modules" module will have the "mkmodules" - program as a "commit helper". After a file is committed to such a - module, "mkmodules" will convert a number of standard files (See - 4B.2) in the CVSROOT directory inside 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 <fileA>, which already in the Repository, - into three pieces, <fileA>, <fileB> and <fileC>. - - 1. Copy the RCS (",v") files directly in the Repository, - creating the new files, then bring readable copies of the - new files into the working directory via "update". - - cp $CVSROOT/<path>/<fileA>,v $CVSROOT/<path>/<fileB>,v - cp $CVSROOT/<path>/<fileA>,v $CVSROOT/<path>/<fileC>,v - cvs update <fileB> <fileC> - - 2. Then remove all the <tags> from the new files by using: - - cvs log <fileB> <fileC> # Save the list of <tag?> - cvs tag -d <tag1> <fileB> <fileC> - cvs tag -d <tag2> <fileB> <fileC> - . . . - - 3. Edit each file until it has the data you want in it. - This is a hand-editing job, not something CVS can handle. - Then commit all the files. - - [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 <fileA> <fileB> <fileC> - cvs commit <fileA> <fileB> <fileC> - - - As in the "rename" case, by duplicating the files, you'll preserve - the change history and the ability to retrieve earlier revisions. - - Of course, you have to alter your build system (e.g. Makefiles) to - take the new names and the change in contents into account. - - - ----------------- --- 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 .#<file>.1.3 file in my working directory come from? - 2D.10 What is this "ignore" business? What is it ignoring? - 2D.11 Is there a way to set user-specific configuration options? - 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" or "truss" command that will display - all system calls as they happen. This is a *very* low-level - interface that does not normally follow the execution of external - commands, but it can be useful. - - The most complete answer is to read the source, compile it - with the '-g' option and step through 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 <tag>", CVS remembers the <tag>. 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 <tag>" on the command line. - - It is most useful for a <branch_tag>, which is a sticky tag - indicating what branch you are working on. - - A revision number ("-r <rev-number>") or date ("-D <date>") 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 <tag/rev>" 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 <tag/rev> 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 works on the revision lying in the - working directory however it got there. That the revision - lying there might happen to have a sticky tag attached to - it is not the "tag" command's concern. - - - The main function that *does* read and write sticky tags is the - "update" command. You can avoid referring to or changing the - sticky tag by using the '-p' option, which sends files to your - terminal, touching nothing else. - - The "checkout" command sets sticky tags when checking out a new - module and it acts like "update" when checking out a module into - an existing directory. - - The "diff" and "commit" commands use the sticky tags, unless - overridden on the command line. They do not set sticky tags. - Note that you can only "commit" to a file checked out with a - sticky tag, if the tag identifies a branch. - - There are really two types of sticky tags, one attached to - individual files (in the ./CVS/Entries file) and one attached to - each directory (in the ./CVS/Tag file). They can differ. - - The "add" command registers the desire to add a new file. If the - "directory tag" (./CVS/Tag) file exists at the time of the "add", - the value stored in ./CVS/Tag becomes the "sticky tag" on the new - file. The file doesn't exist in the Repository until you "commit" - it, but the ./CVS/Entries file holds the sticky tag name from the - time of the "add" forward. - - - 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 copies of the file stored in the virtual "branch" - represented by your working directories. After one of you commits - a file, the other may not commit the same file until "update" has - merged the earlier committed changes into the later working file. - - For example, say you both check out rev 1.2 of <file> and make - change to your working files. Your coworker commits revision 1.3. - When you try to commit your file, CVS says: - - cvs commit: Up-to-date check failed for `<file>' - - You must merge your coworker's changes into your working file by - typing: - - cvs update <file> - - which will produce the output described in 2B.6. - - If a conflict occurs, the filename will be shown with a status of - 'C'. After you resolve any overlaps caused by the merging - process, you may then commit the file. See 3P.6 for info on - "sticky conflicts". - - Even if you get a simple 'M', you should examine the differences - before committing the file. A smooth, error-free text merge is - still no indication that the file is in proper shape. Compile and - test it at least. - - The answer to two obvious questions is "Yes". - - Yes, the first one who commits avoids the merge. Later developers - have to merge the earlier changes into their working files before - committing the merged result. Depending on how difficult the merge - is and how important the contending projects are, the order of - commits and updates might have to be carefully staged. - - And yes, between the time you execute "update" and "commit" (while - you are fixing conflicts and testing the results) someone else may - commit another revision of <file>. 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. Or hiring a manager. - - - 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 active - checkouts, who has them and where they were 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 .#<file>.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 <file>. - You both make changes -- different changes. B commits first, so - <file>,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, and you - commit the file immediately, #4 and #5 will be the same. But you - can make arbitrary 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 ".#<file>.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 - blizzard 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 <original file> - <original file with only my work added>", which can be done in the - example above by the Unix shell command: - - cvs update -p -r 1.3 <file> | diff - .#<file>.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, a sure - sign of carelessness. - - 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" business? What is it ignoring? - - The "update" and "import" commands use collections of Unix - wildcards to skip over files and directories matching any of those - patterns. - - You may add to the built-in ignore list by adding lines of - whitespace-separated 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 exclusively in directory trees where the - Makefiles are generated by "imake" or "configure" 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 generated files without known wildcard patterns. - - In any of the 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. - - A variant of the ignore-file scheme is used internally during - checkout. "Module names" found in the modules file (or on the - "checkout" command line) that begin with a '!' are ignored during - checkout. This is useful to permanently ignore (if the '!' path - is in the modules file) or temporarily ignore (if the '!' path is - on the command line) a sub-directory within a Repository - hierarchy. For example: - - cvs checkout !gnu/emacs/tests gnu/emacs - - would checkout the module (or relative path within $CVSROOT) named - "gnu/emacs", but ignore the "tests" directory within it. - - - 2D.11 Is there a way to set user-specific configuration options? - - User-specific configuration is available through use of a ".cvsrc" - file in your home directory. - - CVS searches the first column of your ~/.cvsrc file for the cvs - command name you invoked. If the command is found, the rest of - the line is treated like a set of command line options, stuffed - into the command line before the arguments you actually typed. - - For example, if you always want to see context diffs and you never - want to have to delete a file before you run "cvs remove", then - you should create a .cvsrc file containing the following: - - diff -c - remove -f - - which will add the given options to every invocation of the given - commands. - - [[The rest of this will be removed someday, when CVS changes.]] - - I would like to stop here with a comment that the command name to - use is the full, canonical one. But the command that the cvsrc - support uses is the string you typed on the command line, not the - proper command. So to get the full effect of the above example, - you should also add all the alternate command names: - - di -c - dif -c - rm -f - delete -f - - There are two other limitations that will probably be fixed when - CVS sprouts long option names: - - 1. It only affects options made available on the command line. - - There is a limited number of short options. With long option - names, there is no problem. You can have as many long options - as you like, affecting anything that looks malleable. - - 2. The existing command line options do not come in on/off pairs, - so there is no easy way to override your ~/.cvsrc configuration - for a single invocation of a command. - - Choosing a good set of long option pairs would fix this. - - - 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 - back out the "transaction" and 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. - - Hitting Control-C 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 carefully re-applying the - tags via the "cvs admin -N" command, but you'll still have - to dig up from outside sources the information you use to - determine what tag was on what revision in what file. - 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. A repeated "checkout" from above a directory acts like a - repeated "update -d" within it. - - Halting "update" half-way will give you an unpredictable - collection of files and revisions. To continue, you can rerun the - update and it should move you forward into in a known state. To - back out, you'll have to examine the output from the first - "update" command, take a look at each file that was modified and - reconstruct the previous state by editing the ./CVS/Entries file - and by using "cvs admin". 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 are a few scripts that might help you out. - - - -======================================== -== 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 new file end up in the Attic? - 3A.4 Now that it's in the Attic, how do I connect it to the Main branch? - 3A.5 How do I avoid the hassle of reconnecting an Attic-only file to - the Main Branch? - 3A.6 How do I cancel an "add"? - 3A.7 What are the ./CVS/file,p and ./CVS/file,t files for? - 3A.8 How do I "add" a binary file? - - - **** 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, 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? - - The user actions for adding a file to any branch, including the - Main Branch, are exactly the same. - - You are in a directory checked out (or updated) with the '-A' - option (to place you on the Main Branch) or the "-r <branch_tag>" - option (to place you on a branch tagged with <branch_tag>). To - add <file> to the branch you are on, you type: - - cvs add <file> - cvs commit <file> - - If no ./CVS/Tag file exists (the '-A' option deletes it), the - file will be added to the Main Branch. If a ./CVS/Tag file exists - (the "-r <branch_tag>" option creates it), the file will be added - to the branch named (i.e. tagged with) <branch_tag>. - - Unless you took steps to first add the file to the Main Branch, - your new file ends up in the Attic. - - - 3A.3 Why did my new file end up in the Attic? - - The file is thrown into the Attic to keep it from being visible - when you check out the Main Branch, since it was never committed - to the Main Branch. - - - 3A.4 Now that it's in the Attic, how do I connect it to the Main branch? - - That can be considered a kind of "merge". See 4C.8 - - - 3A.5 How do I avoid the hassle of reconnecting an Attic-only file to - the Main Branch? - - You create it on the Main Branch first, then branch it. - - If you haven't yet added the file or if you decided to delete the - new Attic file and start over, then do the following: - (If you added the file (or worse, the 157 files) to the Attic and - don't want to start over, try the procedure in 4C.8.) - - - 1. Temporarily remove the sticky branch information. Either: - - A. Move the whole directory back to the Main Branch. - [This might not be a good idea if you have modified files, - since it will require a merge in each direction.] - - cvs update -A - - *or* - - B. Move the ./CVS/Tag file out of the way. - - mv ./CVS/Tag HOLD_Tag - - 2. Add and branch the file "normally": - - cvs add <file> - cvs commit <file> - cvs tag -b <branch_tag> <file> - - [<branch_tag> is the same Branch Tag as you used on all - the other files. Look at ./CVS/Entries or the output - from "cvs stat" for sticky tags.] - - 3. Clean up the temporary step. - - A. If you moved the ./CVS/Tag file, put it back. Then - move the new file onto the branch where you are working. - - mv HOLD_Tag ./CVS/Tag - cvs update -r <branch_tag> <file> - - B. If you ran "update -A" rather than moving the ./CVS/Tag - file, move the whole directory (including the new file) back - onto the branch where you were working: - - cvs update -r <branch_tag> - - - 3A.6 How do I cancel an "add"? - - If you want to remove the file entirely and cancel the "add" at - the same time, type: - - cvs remove -f <file> - - If you want to cancel the "add", but leave the file as it was - before you typed "cvs add", then you have to fake it: - - mv <file> <file>.hold - cvs remove <file> - mv <file>.hold <file> - - - 3A.7 What are the ./CVS/file,p and ./CVS/file,t files for? - - The ./CVS/file,p and ./CVS/file,t files are created by the "add" - command to hold command line options and message text between the - time of the "add" command and the expected "commit". - - The ./CVS/file,p file is always null, since its function was - absorbed by the "options" field in the ./CVS/Entries file. If you - put something in this file it will be used as arguments to the RCS - "ci" command that commit uses to check the file in, but CVS itself - doesn't put anything there. - - The ./CVS/file,t file is null unless you specify an initial - message in an "add -m 'message'" command. The text is handed to - "rcs -i -t./CVS/file,t" to create the initial RCS file container. - - Both files must exist to commit a newly added file. If the - ./CVS/file,p file doesn't exist, CVS prints an error and aborts - the commit. If the ./CVS/file,t file doesn't exist, RCS prints an - error and CVS gets confused, but does no harm. - - To recover from missing ,p and ,t files, just create two - zero-length files and rerun the "commit". - - - 3A.8 How do I "add" a binary file? - - If you configured CVS to use the GNU version of "diff" and - "diff3", you only need to turn off RCS keyword expansion. - - First you turn off RCS keyword expansion for the initial checkin - by using "add -ko". It works like "update -ko" in creating a - "sticky" option only for the copy of the file in the current - working directory. - - cvs add -ko <file> - - Commit the file normally. The sticky -ko option will be used. - - cvs commit <file> - - Then mark the RCS file in the Repository so that keyword - expansion is turned off for all checked out versions of the file. - - cvs admin -ko <file> - - Since "admin -ko" records the keyword substitution value in the - Repository's RCS file, you no longer need the sticky option. You - can turn it off with the "update -A" command, but if you were on a - branch, you'll have to follow it "update -r <branch_tag>" to put - yourself back on the branch. - - - Managing that binary file is another problem. See 4D.1. - - - ----------------- --- 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) bypassing all safeguards and CVS - assumptions. - - - 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 use "admin -o" (for "outdate") to remove revisions - you don't care about. This has its own problems, such as leaving - dangling Tags and confusing the "update" command. - - There is some feeling among manipulators of binary files that - "admin -l" should be used to serialize access. See 3C.8. - - An interesting use for "admin" came up while maintaining CVS - itself. I import versions of CVS onto the Vendor branch of my - copy of CVS, make changes to some files and ship the diffs - (created by "cvs diff -c -r TO_BRIAN") off to Brian Berliner. - After creating the diff, I retag ("cvs tag -F TO_BRIAN") the - working directory, which is then ready to produce the next patch. - - I'll use "add.c" as an example (only because the name is short). - - When the next release came out, I discovered that the released - "add.c" (version 1.1.1.3 on the Vendor branch) was exactly the - same as my modified file (version 1.3). I didn't care about the - changelog on versions 1.2 and 1.3 (or the evidence of having done - the work), so I decided to revert the file to the state where it - looked like I had not touched the file -- where I was just using - the latest on the vendor branch after a sequence of imports. - - To do that, I removed all the revisions on the main branch, except - for the original 1.1 from which the Vendor branch sprouts: - - cvs admin -o1.2: add.c - - Then I set the RCS "default branch" back to the Vendor branch, the - way import would have created it: - - cvs admin -b1.1.1 add.c - - And I moved the "TO_BRIAN" Tag to the latest revision on the - Vendor branch, since that is the base from which further patches - would be created (if I made any): - - cvs admin -NTO_BRIAN:1.1.1.3 add.c - - Instead of 1.1.1.3, I could have used one of the "Release Tags" - last applied by "import" (3rd through Nth arguments). - - Suggestion: Practice on non-essential files. - - - - 3B.4 What should I avoid when using "admin"? - - If you know exactly what you are doing, hack away. But under - normal circumstances: - - 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. - - See 3C.8 for a short discussion of how to use "admin -l" for - serializing access to binary files. - - The "admin -o <file>" 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 "<boss's name>_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 <file> 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 <file>,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 <file> - - 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 <tag>, not just the one on <file>. 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 <tag>. 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 <tag> pointed to without using the "tag" - command. For example, if revision 1.3 has <tag> attached to it - and you "outdate" the 1.3 revision, <tag> 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 <tag> 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 while I'm working on them 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" commands are nearly equivalent in how - they treat individual files. They 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" command 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 files in the ./CVS administrative directory. - - 4. The two commands generate completely different types of records - in the "history" file. - - - 3C.5 Why can't I check out a file from within my working directory? - - Though you *can* check out a file, you normally check out a module - or directory. 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 two pathnames: 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 "modules". - - 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. - - - 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 while I'm working on them the way RCS does? - - Until the day arrives of the all-powerful merge tool, there are - still files that must be accessed serially. For those instances, - here's a potential solution: - - 1. Install a pre-commit program in the "commitinfo" file to check - for RCS locks. The program "rcslock.pl" performs this - function. It can be found in the contrib directory of the CVS - source distribution. - - 2. When you want to make a change to a file you know can't be - merged, first use "cvs admin -l" to lock the file. If you - can't acquire the lock, use the standard "locked out" protocol: - go talk to the person holding the lock. - - 3. Make sure the pre-commit program prints a message and exits - with a non-zero status if someone besides the user running - "commit" has the file locked. This non-zero exist status will - cause the "commit" to fail cleanly. - - 4. Make sure the pre-commit program exits with a zero status if - the file is either unlocked or locked by the user running - "commit". The "cvs commit" command that kicked off the - pre-commit program will take a zero exist status as an OK and - checkin the file, which has the side-effect of unlocking it. - - - ===> The following is opinion and context. Don't read it if you - are looking for a quick fix. - - The topic of locking CVS files resurfaces on the network every so - often, producing the same results each time: - - The Big Endians: - - CVS was designed to avoid locks, using a copy-modify-merge - model. Locking is not necessary and you should take the time - to learn the CVS model which many people find workable. So why - not get with the program and learn how to think the CVS way? - - The Little Endians: - - The users determine how a tool is to be used, not the - designers. We, the users, have always used locking, our bosses - demand locking, locking is good, locking is God. I don't want - to hear any more lectures on the CVS model. Make locking work. - - Any organization making active changes to a source base will - eventually face the need to do parallel development. Parallel - development implies merges. (If you plan to keep separate copies - of everything and never merge, good luck. Tell me who you work - for so I can buy stock in your disk suppliers this year and sell - your stock short next year.) - - Merges will never go away. CVS chose to make "merges" stand - front and center as an important, common occurrence in - development. It is one way of looking at things. - - For free-format text, the merge paradigm gives you a considerable - amount of freedom. It does take a bit of management, but any - project should be ready to deal with it. - - On the other hand, there are many files that can't be merged using - text merge techniques. Straight text merge programs like "diff3" - are guaranteed to fail on executables (with relative branch - statements), files with self-referential counts stored in the file - (such as TAGS files), or files with relative motion statements in - them (such as Frame MIF files, many postscript files). They - aren't all binary files. - - For these types of files, and many others, there are only two - solutions: - - 1. Complex merge tools that are intimately aware of the contents - of the files to be merged. (ClearCase, and probably others, - allow you to define your own "files types" with associated - "merge tools".) - - 2. Serialization of access to the file. The only technical - solution to the problem of serialization is "locking". - - - Since you can call a program that offers: - - "Which one do you want? A/B?" - - a "merge tool", more and more merge tools will appear which can be - hooked into a merge-intensive program like CVS. Think of a bitmap - "merge" tool that displays the bitmaps on the screen and offers a - "paint" interface to allow you to cut and paste, overlay, invert - or fuse the two images such that the result is a "merged" file. - - My conclusion is that the need for locking is temporary, awaiting - better technology. For large development groups, locking is not - an alternative to merging for text files. - - - 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 <prog>") 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). - - ----------------- --- 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 `<file>' - 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 <tag/rev>" put newly added files in the Attic? - 3D.8 Why would a "commit" of a newly added file not produce rev 1.1? - - - **** 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, directory - names and relative pathnames on the command line and commit them - all with the same log message. If a file is unchanged, even if it - is explicitly listed on the command line, 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 `<file>' - - 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 checkin of a minor alteration of a second copy of 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 the world of parallel 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 to be careful, - you should just grab an old version of the file ("update -p -r - <previous-rev>" 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 records (i.e. makes "sticky") any "-r <tag/rev>" argument - handed to the "checkout" or "update" commands. The <tag/rev> 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 {files or dirs, default is '.'} - - or you can move to the branch named <branch_tag> by: - - cvs update -r <branch_tag> {files or dirs, default is '.'} - - - Scenario2: - - If you really wanted to be on a branch and made an earlier - mistake by tagging your branch point with a non-branch tag, - you can recover by adding a new branch tag to the old - non-branch tag: - - cvs rtag -b -r <oldtag> <newtag> <module> - - (It was not a big mistake. Branch-point tags can be useful. - But the <newtag> must have a different name.) - - If you don't know the <module> name or don't use "modules", - you can also use "tag" this way: - - cvs update -r <oldtag> - cvs tag -b <newtag> . - - Then, to put your working directory onto the branch, you type: - - cvs update -r <newtag> - - - You can't delete <oldtag> before adding <newtag>, and I would - not advise deleting the <oldtag> at all, because it is useful - in referring to the branch point. If you must, you can delete - the non-branch tag by: - - cvs rtag -d <oldtag> <module> - or - cvs tag -d <oldtag> . - - - Scenario3: - - If you made the same mistake as in Scenario2 (of placing a - non-branch tag where you wanted a branch tag), but really want - <oldtag> to be the name of your branch, you can execute a - slightly different series of commands to rename it and move - your working directory onto the branch. - - Warning: This is not a way to rename a branch tag. It is a way - to turn a non-branch tag into a branch tag with the - same name. - - cvs rtag -r <oldtag> <branch_point_tag> <module> - cvs rtag -d <oldtag> <module> - cvs rtag -b -r <branch_point_tag> <oldtag> <module> - - Then, if you really must, delete the <branch_point_tag>: - - cvs rtag -d <branch_point_tag> <module> - - - - Note: The unwieldy mixture of "tag" and "rtag" is mostly - because you can't specify a revision (-r <tag>) to the - "tag" command. - - See 4C.3 for more info on creating a branch. - - - 3D.7 Why does "commit -r <tag/rev>" put newly added files in the Attic? - - If you specify "-r <rev>" (where <rev> is a dotted numeric number - like 2.4), it correctly sets the initial revision to <rev>, but it - also attaches the numeric <rev> as a sticky tag and throws the - file into the Attic. This is a bug. The obvious solution is to - move the file out of the Attic into the associated Repository - directory and "update -A" the file. There are no Tags to clean up. - - If you specify "-r <tag>" to commit a newly added file, the <tag> - is treated like a <branch_tag>, which becomes a symbolic RCS label - pointing to the string '1', which can be considered to be the - "Main branch number" when the main branch is still at revision - 1.N. The file is also thrown into the Attic. See 4C.8 for a way - to recover from this. - - In fact, a plain "commit" without the "-r" will throw a newly - added file into the Attic if you added it to a directory checked - out on a branch. See 3A.[2-5]. - - See Section 4C, on Branching, for many more details. - - - 3D.8 Why would a "commit" of a newly added file not produce rev 1.1? - - When committing a newly added file CVS looks for the highest main - branch major number in all files in the ./CVS/Entries file. - 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 <file>. Normally, the first revision is 1.1. - - ----------------- --- 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 long options, like --unified, to "diff"? - - - **** Answers: - - 3E.1 What is "diff" for? - - 1. To display the difference between a working file and its BASE - revision (the revision last checked out, updated or committed): - - cvs diff <file> - - 2. To display the difference between a working file and a - committed revision of the same file: - - cvs diff -r <tag/rev> <file> - - 3. To display the difference between two committed revisions of - the same file: - - cvs diff -r <tag1/rev1> -r <tag2/rev2> <file> - - You can specify any number of <file> arguments. Without any - <file> arguments, it compares the whole directory. - - In the examples above, "-D <date>" may be substituted wherever - "-r <tag/rev>" appears. The revision a <date> 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 <file> - - - 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 <file> - - - 3E.4 How do I display the difference between my working file and what - I checked in last Thursday? - - cvs diff -D "last Thursday" <file> - - 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 long options, like --unified, to "diff"? - - CVS only handles single character '-X' arguments, not the FSF long - options. CVS also passes through only arguments it knows about, - because a few arguments are captured and interpreted by CVS. - - 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 doesn't "export" have a '-k' flag like "import" does? - 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 as of CVS version 1.4. - - - 3F.4 Why doesn't "export" have a '-k' flag like "import" does? - - Export is intended for a specific purpose -- to remove all trace - of revision control on the way *out* of CVS. - - - 3F.5 Why does "export -D" check out every file in the Attic? - - See 5B.3 for an explanation of the same problem with "update". - - - ----------------- --- Section 3G -- "history", "hi", "his" ----------------- - - **** Questions: - - 3G.1 What is "history" for? - 3G.2 Of what use is it? - 3G.3 What is this, Big Brother? - 3G.4 I deleted my working directory and "history" still says I have - it checked out. How do I fix it? - 3G.5 So I *can* edit the History file? - 3G.6 Why does the history file grow so quickly? - 3G.7 What is the difference between "cvs history -r <tag/rev>" and - "cvs history -t <tag>"? - 3G.8 Why does "cvs history -c -t <tag>" fail to print anything? - 3G.9 "cvs history -a -o" only printed one line for each checked-out - module. Shouldn't it print all the directories where the - modules are checked out? - 3G.10 I can't figure out "history", can you give me concrete examples? - 3G.11 Can we merge history files when we merge Repositories? - - - **** 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? - - You can use "release -f" to forcibly add a "release" record to the - history file for a working directory associated with a "module". - If your version of "release" doesn't have the '-f' option, or you - checked out the directory using a relative path, you have to edit - the $CVSROOT/CVSROOT/history file. - - You can remove the last 'O' line in the history file referring - to the module in question or add an 'F' record. - - - 3G.5 So I *can* edit the History file? - - Yes, but if you are using history at all, you should take a little - care not to lose information. I normally use Emacs on the file, - since it can detect that a file has changed out from under it. - You could also copy and zero out the history file, edit the copy - and append any new records to the edited copy before replacing it. - - - 3G.6 Why does the history file grow so quickly? - - It stores 'U' records, which come in handy sometimes when you - are tracking whether people have updated each other's code - before testing. There should (and probably will sometime) be a - way to choose what kinds of events go into the history file. - - The contributed "cln_hist.pl" script will remove all the 'U' - records, plus matching pairs of 'O' and 'F' records during - your normal clean up of the history file. - - - 3G.7 What is the difference between "cvs history -r <tag/rev>" and - "cvs history -t <tag>"? - - The '-t' option looks for a Tag record stored by "rtag" in the - history file and limits the search to dates after the last <tag> - of the given name was added. - - The '-r' option was intended to search all files looking for the - <tag> in the RCS files. It takes forever and needs to be - rewritten. - - - 3G.8 Why does "cvs history -c -t <tag>" fail to print anything? - - You have been using "tag" instead of "rtag". The "tag" command - currently doesn't store a history record. This is another remnant - of CVS's earlier firm belief in "modules". But it also has a - basis in how "rtag" and "tag" were originally used. - - "rtag" was intended for large-scale tagging of large chunks of the - Repository, an event work recording. "tag" was intended for - adding and updating tags on a few files or directories, though it - could also be used to tag the entire checked-out working tree when - there is no module defined to match the tree or when the working - tree is the only place where the right collection of revisions to - tag can be found. - - - 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 <same for all users> - - cvs history -o -w What working directories have I created - and what modules are in them? - cvs history -a -o -w <same for every user> - - 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 <tag> - * Modified files since TAG on files: -c -r <tag> - * 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 - - - 3G.11 Can we merge history files when we merge Repositories? - - Assuming that the two Repositories have different sets of - pathnames, it should be possible to merge two history files by - sorting them together by the timestamp fields. - - You should be able to run: - - sort +0.1 ${dir1}/history ${dir2}/history > history - - - If you "diff" a standard history file before and after such a - sort, you might see other differences caused by garbage (split - lines, nulls, etc) in the file. If your Repository is mounted - through NFS onto multiple machines you will also see a few - differences caused by different clocks on different machines. - (Especially if you don't use NTP to keep the clocks in sync.) - - - ----------------- --- 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 I work on the - main trunk instead of a Vendor 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 retain the original $\Revision$ strings in the sources? -=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 can't I "import" 3 releases on different branches? - 3H.10 What do I do if the Vendor adds or deletes files between releases? - 3H.11 What about if the Vendor changes the names of files or - directories, or rearranges the whole structure between releases? - 3H.12 I thought "import" was for Vendor releases, why would I use it - for code of my own? Do I have to use import? - 3H.13 How do I import a large Vendor release? - 3H.14 Explain: ERROR: cannot create link to <file>: Permission denied - 3H.15 Where does the -m <message> go when the file doesn't change? - 3H.16 How do I "import" just the files ignored by a previous "import"? - 3H.17 Why did "import" ignore all the symlinks? - - - **** 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. - - If this is not the first import from this "Vendor", you should - also compare the output of "find . ! -name CVS -print | sort" - executed both at the head of a checked out working directory and - at the head of the sources to be imported. If you find any - deleted or renamed files, you have to deal with them by hand. - (See 4B.8 on renaming.) - - "cd" into your source directory and type: - - cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag> - - where <repos> is the relative directory pathname within the - Repository that corresponds to the sources you are importing. - - You might also consider using the "-I !" option to avoid ignoring - anything. It is easier to remove bogus files from the Repository - than to create a sparse tree of the ignored files and rerun - "import". - - 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.13 for more details. - - - 3H.3 Why does import put files on a branch? Why can't I work on the - main trunk instead of a Vendor branch? - - This was a Design choice. The Vendor branch is the way "import" - deals with a Vendor release. It is a solution to the Engineering - problem of how to merge multiple external releases of - Vendor-supplied sources into your ongoing work. The Vendor - releases are kept on a separate, special, "Vendor" branch and your - work is kept on the RCS trunk. New Vendor releases are imported - onto the Vendor branch and then merged into your work, if there is - any, on the trunk. - - This way, you can use CVS to find out not only about your work, - but you can also find out what the Vendor changed by diffing - between two of the Release Tags you handed to "import". - - CVS was designed to work this way. If you use CVS in some other - way, you should think carefully about what you are doing. - - 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. - - - If you are not working with 3rd party (i.e. Vendor) sources, you - can skip the "import" and avoid the Vendor branch entirely. It - works just as well to move pre-existing RCS files into Repository - directories. - - You can create a whole Repository tree by copying a directory - hierarchy of normal source files directly into the Repository and - applying CVS to it. Here's an idea you should *test* before using: - - cd <your source tree> - set source = `pwd` - set module = xyzzy <<== Your choice of directory name - mkdir $CVSROOT/$module - cd $CVSROOT/$module - (cd $source; tar cf - .) | tar xvpBf - - find . -type f -exec ci -t-Original. {} \; - - The RCS "ci" command, without -u or -l options, will turn your - source file into an RCS (",v") and delete the original source. - - - 3H.4 Is there any way to import binary files? - - If you configured CVS to use the GNU version of "diff" and - "diff3", then you can import any kind of file. - - Binary files with RCS keywords in them are a problem, since you - don't want them to expand. - - If the tree you are about to "import" is entirely filled with - binary files, you can use the '-ko' option on "import". - Otherwise, I would run the import normally, then fix the binary - files as described below in 3H.5. - - 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 <file> - rm <file> - cvs update <file> - - After an import that didn't use '-ko' (because the whole tree - wasn't of binary files) you should fix up the binary files as - described above before checking out any new copies of the files - and before updating any working directories you checked out - earlier. - - See 4D.1 on Binary files. - - - 3H.6 How do I retain the original $\Revision$ strings in the sources? - - If you want to leave old RCS keywords as they are, you can use the - '-ko' tricks described above. - - -=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 {} ';') - (or: find . -name '*.yarg' -print | xargs rm) - (or: find . -name '*.yarg' -print0 | xargs -0 rm - if you have spaces in filenames and the GNU find/xargs.) - 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? - - Use "import -d" to save the current timestamps on the files as the - RCS revision times. - - See 4D.8 for another aspect of file timestamps. - - - 3H.9 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.10 What do I do if the Vendor adds or deletes files between releases? - - Added files show up with no extra effort. To handle "removed" - files, you should always compare the tree structure of the new - release against the one you have in your Repository. If the - Vendor has removed files since the previous release, go into a - working directory containing your current version of the sources - and "cvs remove" (followed by "cvs commit" to make it really take - effect) each file that is no longer in the latest release. - - Using this scheme will allow you to "checkout" any version of - the vendor's code, with the correct revisions and files, by - using "checkout -r Version[234]". - - Renames are harder to find, since you have to compare file - contents to determine that one has occurred. If you notice one, - see 4B.8 on renaming files. - - - 3H.11 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.8 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.12 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 of whole trees. It is not necessary. You can just as - easily create ",v" files using the RCS "ci" command and move - them directly into the Repository. - - Other than the CVSROOT directory, the Repository consists entirely - of directories of ",v" files. The Repository contains no other - state information. - - See Section 4B, on Setting up and Managing the Repository. - - - 3H.13 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. - - 0. If this is not the first import of this code, before starting, - rtag the whole directory you will be changing. - - 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. - - You should examine the list first to see if any have been - renamed rather than simply deleted. - - 4. If they renamed any files, see 4B.8 on renaming files. - - 5. Remember to *SAVE* the output from the import command. - - 6. When you have dealt with removed and renamed files, then you - can execute the import: - - cd <new source> - cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag> - - - Where - - "-I !" is an optional argument that keeps "import" from - ignoring files. The comparison of the "find" - commands above will probably avoid the need for - this, but it is easier to remove files from the - Repository than to run a subset "import" to catch - just the ignored files. - [You might have to quote or backwhack the '!'.] - - Message is the log message to be stored in the RCS files. - - <repos> is a relative path to a directory within the - Repository. The directory <new source> must be at - the same relative level within the new sources as - the <repos> you give is within the Repository. (I - realize this is not obvious. Experiment first.) - - <VendorTag> is a Tag used to identify the Vendor who sent you - the files you are importing. All "imports" into - the same <repos> *must* use the same VendorTag. - You can find it later by using the "log" command. - - <ReleaseTag> 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 '-'.) - - 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 <repos> 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. If you use "-I !", nothing will be ignored. - - - 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 if this is really a new - file. - - - 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 <PreviousReleaseTag> -j <ReleaseTag> - or - cvs update -j <VendorTag:yesterday> -j <VendorTag> - - 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. - - - 8. If you are truly performing a large import, you will most - likely need help. Managing those people is another problem - area. - - Since the merge of the Vendor branch is just like any other - merge, you should read section 4C for more info about - performing and cleaning up merges. - - The larger the import, and the larger the group of people - involved, the more often you should use "tag" and "rtag" to - record even trivial milestones. See 4C.14, especially the - "paranoid" section. - - Before starting the import, you should install and test a - "commitinfo" procedure to record all commits in a file or via - Email to a mail archive. Along with the tags you placed on the - Repository before the import, this archive will help to track - what was changed, if problems occur - - There are four stages to the recovery: - - A. Parcel out the work -- Effective Emacs Engineering. - - As input to the assignment process, you might want to - examine the tree and record the last person who changed the - file. You can also research, if you don't already know, who - is expert in each area of the software. - - Examine the import log (you saved the output, right?), - estimate how much work is involved in each area and assign - groups of files to individual developers. Unless some - directory is immense, it is easier to manage if you assign - whole directories to one person. - - Keep a list. Suggest a completion date/time. Tell them to - "commit" the file when they are finished with the merge. - If you tagged the Repository before starting the import, you - should have no trouble figuring out what happened. - - If you can, find out (or tell them) which working directory - to use. You should verify that the working directory they - use is on the Main Branch ("update -A") and without modified - files. - - If you trust your crew, have them notify you by Email. Have - them send you the output from "cvs update" in their working - directory. You might have to poll some people until you are - certain they have finished, or have given up. (This is not - an invention. I've heard a false, "Yeah, sure. I finished - yesterday," more times that you'd believe.) - - When all reports are in, go on to the Source Verification - stage. - - B. Source Verification -- CVS and other Tools. - - If you didn't dictate which ones to use, find all working - directories and run "cvs -n update" in all of them. The - history command and the "commitinfo" log you set up might - help to find checked out working directories. - - Sticky conflict flags will help, but they can't recover from - sloppiness or incompetence. You might want to check - everything out into a tree and grep for the parts of the - merge conflict markers CVS doesn't look for. CVS looks for - the string '^>>>>>>> '. The merge operation also puts - '^<<<<<<< ' and '^======= ' markers in the file that - careless developers might leave there. - - If you find problems simply by looking at the source files - and working directories, start the flogging now. Resolving - the textual conflicts is the easy part. Weed the turkeys - out before reaching the next part of the cleanup -- the - resolution of logical conflicts. - - Then apply a set of post-commit tags. - - C. Logical Verification -- Diff and powerful eyeballs. - - No source control system can solve the problem of resolving - distributed conflicts in program logic. If you change the - argument template for function A (defined in file A.c) and - add new calls to function A from within function B (defined - in file B.c) using the old argument format, you are outside - the realm of CVS's competence. - - Assign someone to understand what the Vendor changed by - running "cvs diff -c -r <PreviousReleaseTag> <ReleaseTag>", - where the tags were those handed to the last two invocations - of "import". - - Then have the same person compare that output (logically or - you can actually diff the diffs) to the output of the - similar "cvs diff -c -r <pre-import-tag> <post-commit-tag>". - The two sets of differences should be almost identical. - They should both show only the work *you* have performed. - - D. Product Verification -- Build and Test. - - Don't let your help off the hook until you verify that the - merge actually produced something that can compile and pass - tests. Compiling should really be part of the logical - verification phase, but you should test the output of the - build system before declaring victory and releasing the - troops. - - - 9. After it is all built, apply another set of tags to mark the - end of the "import process". You can delete the intermediate - tags you added during source and logic testing, but keep the - "pre-import" and "post-import" tags forever. - - - Of course, experience can tell you when to skip a step. But I'd - start out by considering each one as necessary unless you can - prove otherwise. - - - - 3H.14 Explain: ERROR: cannot create link to <file>: 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. - - - 3H.15 Where does the -m <message> go when the file doesn't change? - - The <message> handed to import is used as an RCS log message, but - only if the imported file changed since the last version on the - Vendor branch. If the imported file hasn't changed, then no new - revision is created. The <ReleaseTag> is still applied, but to - the previous revision. So the Tags are still correct, but the - message is lost. - - Maybe it should be appended to the previous log message. But - currently it isn't. - - - 3H.16 How do I "import" just the files ignored by a previous "import"? - - A real answer follows, but first, an editorial: - - I am now convinced that you should always use the "-I !" - option. Removing a few extraneous files from the Repository - is a lot easier than the recovery step described below. - - - Let's assume your original import procedure was: - (We assume there is enough disk space in /tmp.) - - cd <head-of-vendor-tree> - cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP - - To import just the files ignored by "import", I would do this: - - 1. Create a list of the ignored files to import: - - cd <head-of-vendor-tree> - awk '/^I / {print $2}' /tmp/IMP | sed 's|^gnu/xyz/||' > /tmp/IG - [Edit the IG file to contain just the files you want.] - - 2. Then create a sparse directory by handing your list to the GNU - version of "tar", installed in many places as "gtar": - - mkdir /tmp/FIXUP - gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf -) - - 3. Then rerun the import. Use the exact same command, but execute - it in the sparse directory tree you just created. And this - time, tell it not to ignore anything. - - cd /tmp/FIXUP - cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 - - - 3H.17 Why did "import" ignore all the symlinks? - - This is another design choice. - - Like the Unix "tar" command, "import" could sprout an option to - follow symbolic links, but I don't think CVS will ever follow - symbolic links by default. - - Two possible future enhancements have been seriously discussed: - - 1. Treat symbolic links as data in its parent directory (the way - ClearCase does) in some sort of per-directory control file. - - 2. Treat symbolic links as version-controlled elements themselves, - whose data is the value of readlink(2). - - For now, they are simply ignored. - - If you want to save and reconstruct symlinks, you might want to - define a "checkout" or "update" program in the modules file which - could consult a file kept under CVS in your working directory and - make sure the specified links are in place. - - - ----------------- --- 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 (RCS calls it a "symbol") list. - - - 3I.2 How do I extract the log entries between two revisions? - - If both <rev1> and <rev2> are on the same branch, you can get - what you are looking for with: (If they aren't on the same branch - you'll either get an error or a display of the whole change log.) - - cvs log -r<rev1>:<rev2> <file> - - If you want all the revisions on the branch from <rev1> to the end - of the branch <rev1> is on, you can use: - - cvs log -r<rev1>: <file> - - (If <rev1> is a numeric RCS symbol attached to a branch revision - with an even number of '.'s in it, you get the whole branch.) - - If you want all the revisions on the branch from the beginning of - the branch <rev2> is on up to revision <rev2>, you can use: - - cvs log -r:<rev2> <file> - - - Note: Depending on whether <rev1> and <rev2> are: - - - numeric or symbolic - - in the file or not - - on the same branch or not - - the RCS "rlog" (and therefore the "cvs log") command will - display some combination of: - - - error messages - - (intuitively correct) partial log listings - - a display of the entire change log. - - - 3I.3 How do I extract the log entries on a whole branch? - - cvs log -r<rev> <file> - - where <rev> 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. - - The intuitive command (at least from the CVS perspective): - - cvs log -r<branch_tag> <file> - - does not work. - - - 3I.4 How do I generate ChangeLogs from RCS logs? - - A program called rcs2log is distributed as part of GNU Emacs 19. - A (possibly older) version of this program appears in the contrib - directory of the cvs source tree. - - - 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 <rev/tag> -r <rev/tag> <file1> . . . - - The patch command will be able to merge such a "diff" into the - remote source files. - - If you configured CVS to use a version of "diff" that supports the - '-u' option, you can produce a more compact "patch" in "unidiff" - format. The latest revisions of the patch command can parse and - apply patches in "unidiff" format. - - - ----------------- --- Section 3K -- "release", "re", "rel" ----------------- - - - **** Questions: - - 3K.1 What is "release" for? - 3K.2 Why can't I reverse a "cvs checkout path/name/subdir" with a - "cvs release path/name/subdir" without an "unknown module name"? - 3K.3 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.4 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.5 Why doesn't "release -d module" reverse a "checkout module"? - 3K.6 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 can't I reverse a "cvs checkout path/name/subdir" with a - "cvs release path/name/subdir" without an "unknown module name"? - - A simplistic implementation. (I can say this -- I wrote it.) - - The "release" function was written for CVS 1.2 under the - assumption that the "module name" is a first class, unavoidable - interface to the Repository, allowing no way to retrieve anything - other than by module name. 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 that - assumption. It needs to be revised. - - - 3K.3 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. - - This isn't really a limitation in "release", per se. CVS doesn't - try to keep track of which files in which directories are "checked - out" and which are just lying there. You can delete directories - and "update" will not bring them back unless you add a special - "-d" option. - - In other words, CVS doesn't keep track of how you adjust the - partition between files you consider part of your working set and - files that were checked out because they are part of the same - module or directory. And neither does "release". - - In future CVS releases, "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.4 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.5 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.6 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 an - error message and tells me to remove the file by hand. - - - **** 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 <date>" 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 <oldtag>", files with <oldtag> - attached to some revision will be taken from the normal Repository - area and from the Attic. That's why you can't "add" a file with - the same name. "remove" only moves a file off the main branch, it - doesn't obliterate it. - - - 3L.5 Why doesn't "remove" delete the file? Instead, it prints an - error message and tells me to remove the file by hand. - - 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 unless you specify the '-f' (force) - option, which deletes the file before performing "cvs remove". - - - ----------------- --- Section 3M -- "rtag", "rt", "rfreeze" ----------------- - -(See the "tag" section below for the general questions about Tagging, which - "tag" and "rtag" share in common.) - - - **** Questions: - - 3M.1 What is "rtag" for? - 3M.2 Why use "rtag"? It assumes no one is changing the Repository. - 3M.3 What revision does "rtag -r <tag1> <tag2>" actually put the tag on? - 3M.4 What happens if the tags are the same in "rtag -r <tag> <tag>"? - 3M.5 Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or - duplicate a magic branch tag? - - - **** 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 use "rtag"? It assumes no one is changing the 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. - - - 3M.3 What revision does "rtag -r <tag1> <tag2>" actually put the tag on? - - In short, the '-r' option is another way to select the revision to - tag. The revision is selected the same way for all commands that - accept a "-r <tag/rev>" option. - - Depending on whether <tag1> is a <branch_tag>, or a non-branch - <tag> and on whether you use the '-b' option to "rtag", you get - four different results: - - 1. rtag -r <tag1> <tag2> - - Adds the non-branch tag <tag2> to the same revision that the - non-branch tag <tag1> is attached to. - - Example: - <tag1> --> TT1 - <tag2> --> TT2 - <file> --> Symbols: TT1:1.4 - After --> Symbols: TT1:1.4,TT2:1.4 - - - 2. rtag -r <branch_tag1> <tag2> - - Adds the non-branch tag <tag2> to the HEAD of (the highest - revision number on) the branch labelled with tag <branch_tag1>. - - Example: - <branch_tag1> --> BR1 - <tag2> --> TT2 - <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD) - After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5 - - If the branch tagged by <branch_tag1> has not been created, - then the tag shows up on the branch point revision: - - Example: - <branch_tag1> --> BR1 - <tag2> --> TT2 - <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) - After --> Symbols: BR1:1.2.0.2,TT2:1.2 - - - 3. rtag -b -r <tag1> <branch_tag2> - - Adds the magic branch tag <branch_tag2> to the revision that - the non-branch tag <tag1> is attached to, preparing it to be a - branch point. - - Example: - <tag1> --> TT1 - <branch_tag2> --> BR2 - <file> --> Symbol: TT1:1.4 - After --> Symbol: TT1:1.4, BR2:1.4.0.2 - - - 4. rtag -b -r <branch_tag1> <branch_tag2> - - Adds the magic branch tag <branch_tag2> to the revision at the - HEAD of (the highest revision number on) the branch labelled - with <branch_tag1>, preparing it to be a branch point. - - Example: - <branch_tag1> --> BR1 - <branch_tag2> --> BR2 - <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD) - After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2 - - If the branch tagged by <branch_tag1> has not been created, - then the tag shows up as a second branch off the same - branch point revision: - - Example: - <branch_tag1> --> BR1 - <tag2> --> TT2 - <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) - After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4 - - - - In all four cases above, if <tag2> already exists on the file, you - get an error unless you specify the '-F' option. - - In all four cases, if <tag1> does not exist on the file, <tag2> is - not added unless you specify the '-f' option. - - - 3M.4 What happens if the tags are the same in "rtag -r <tag> <tag>"? - - Again, there are four cases depending on whether <tag> is a - branch tag, or a non-branch tag and on whether you use the - '-b' option to "rtag": - - 1. rtag -r <tag> <tag> - - Is a no-op. It does nothing even with '-F' specified. - - If you add the '-f' option ("rtag -f -r <tag> <tag>"), then - <tag> is attached to the latest revision on the Main Branch if - the file does *not* already have <tag> on some revision. - - If the <tag> is already on the file, using "rtag -f" is still - a no-op. - - - 2. rtag -r <branch_tag> <branch_tag> - - Produces an error, since the <branch_tag> is already on some - revision of the file. - - But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic - branch tag into a non-branch tag. - - Symbols: BR1:1.4.0.2 - becomes - Symbols: BR1:1.4 - - - 3. rtag -b -r <tag> <tag> - - Produces an error, since the <tag> is already on the file. - - But, "rtag -F -b -r <tag> <tag>" turns the non-branch - tag into a magic branch tag. - - Symbols: BR1:1.4 - becomes - Symbols: BR1:1.4.0.2 - - - 4. rtag -b -r <branch_tag> <branch_tag> - - Produces an error, since the <branch_tag> is already on the - file. - - But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the - branch number. It essentially removes the branch and creates a - new one by the same name. - - Symbols: BR1:1.2.0.4 - becomes - Symbols: BR1:1.2.0.6 - - - - 3M.5 Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or - duplicate a magic branch tag? - - None of the "tag" or "rtag" options rename anything. They only - apply (or, with the '-F' option, move) tags to specific revisions - in the file. - - See 3M.[3-4] above for details of how it works. - - To rename a non-branch tag, see 3O.9. - To rename a magic branch tag, see 4D.5 - - - ----------------- --- 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 Why does it print "Sticky" lines when the values are "(none)"? - 3N.4 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 Why does it print "Sticky" lines when the values are "(none)"? - - Oversight. It should probably elide lines without information. - - - 3N.4 Shouldn't the status "Needs Checkout" be "Needs Update"? - - Probably. - - [[Did this show up in CVS 1.4?]] - - - ----------------- --- 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 "{r}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 <tag>" in my working directory, why doesn't "checkout - -r <tag>" somewhere else produce copies of my current files? - 3O.8 Why doesn't "tag" write a history record the way "rtag" does? - 3O.9 How do I rename a <tag>? - - - **** 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 <tag>, or symbolic name, - is attached to a single revision in each 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, or a relative - path within the Repository. - - "tag" works on files and directories specified on the command - line within the user's working directory. (Default is '.') - - 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. (The BASE revision of a file is the one stored in - the ./CVS/Entries file.) - - 3. A different set of command line options. - - For example, "rtag" takes a "-r <oldtag>" option to retag an - existing tag. The "tag" command does not. - - 4. How it is logged. - - Currently "rtag" records the <tag> 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? - - This is probably an oversight, or a disbelief in the need for it. - 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 <tag> 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. You might want to add non-branch tags as a - habit and add branch tags later, possibly immediate after adding - the non-branch tag. See 4C.3 on Creating a Branch. - - - 3O.4 So "{r}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* <-*- <tag> - 1.2*- 1.2 1.2 -1.2*- - 1.3 \- 1.3*- 1.3 / 1.3 - 1.4 \ 1.4 / 1.4 - \-1.5*- 1.5 - 1.6 - - At some time in the past, the '*' versions were tagged. Think - of the <tag> as a handle attached to the curve drawn through the - tagged revisions. When you pull on the handle, you get all the - tagged revisions. Another way to look at it is that you draw a - straight line through the set of revisions you care about and - shuffle the other revisions accordingly. Like this: - - file1 file2 file3 file4 file5 - - 1.1 - 1.2 - 1.1 1.3 _ - 1.1 1.2 1.4 1.1 / - 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here - 1.3 1.6 1.3 \_ - 1.4 1.4 - 1.5 - - I find that using these visual aids, it is much easier to - understand what a <tag> is and what it is useful for. - - - 3O.5 How do I get "tag" and "rtag" to send mail the way "commit" does? - - The "commit" command is supported by two files ("commitinfo" - and "loginfo") not used by other commands. To do logging the - same way for "tag" and "rtag" would require another file like - loginfo, 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 <tag>" in my working directory, why doesn't "checkout - -r <tag>" somewhere else produce copies of my current files? - - The only reason this would fail, other than misspelling the <tag> - 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 generally more useful than "rtag", so - the model has changed. Future revisions of CVS will probably - store both kinds of tags in the history file. - - - 3O.9 How do I rename a <tag>? - - For a procedure to rename a branch tag, See section 4D.5 - The following covers only non-branch tags. - - First, pick a <newtag> that is not in use. You could reuse - (i.e. move) an existing tag to the new revisions using the '-F' - option, but that will confuse matters when both tags are not - already on a file. (It will probably confuse "rtag -f" too.) - - Use "rtag" to place <newtag> only on revisions attached to - <oldtag> in the whole Repository, then delete the old one. - - cvs rtag -r <oldtag> <newtag> world - cvs rtag -d <oldtag> world. - - - You can also checkout or update your working directory to the - <oldtag> and "tag" rather than "rtag" the result. But that - will take longer and it has the chance of producing conflicts. - - cvs update -r <oldtag> - cvs tag <newtag> - cvs tag -d <oldtag> - cvs update -A (or cvs update -r <previous_tag>) - - ----------------- --- 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 What's a "sticky conflict"? How does it know a conflict occurred? - 3P.7 Is there a feature to tell me what I have changed, added and - removed without changing anything? - 3P.8 Why were all my files deleted when I executed "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 by others 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 - since your last checkout, update or commit, type: - - cvs update {optional list of files} - - - 3. To merge changes made on 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 <branch_tag> {optional files} - - If you want to grab the changes made between two tags or - revisions, you type: - - cvs update -j <tag1> -j <tag2> {optional files} - - (If you are working with a single file, the Tags could also be - revisions numbers. Unless you take great care to match - revision numbers across different files (a waste of time given - the way Tags work), using revision numbers in place 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 <branch_tag> {optional files} - - To move to the Main Branch, type: - - cvs update -A {optional files} - - If you have modified files in your working directory, this is - not a clean move. CVS will attempt to merge the changes - necessary to make it look like you made the same changes to the - new branch as you made in the old one. But if you do this - twice without resolving the merge conflicts each time, you can - lose work. - - - 5. To retrieve old revisions of files. - - This option is similar to 4 above but you are not restricted to - using a <branch_tag>. You may specify any revision or <tag> - with '-r' and get the specified revision or the tagged - revision: - - cvs update -r <tag/rev> {optional files} - - Or you may specify any date with '-D': - - cvs update -D <date> {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. See 2D.7 and - 3P.6 for more info on conflict resolution and "sticky - conflicts." - - "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 (identified in - your ./CVS/Entries file) and the HEAD revisions (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 <tag> or <date> 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 <tag>" or "-D <date>" option. Until you - do it again with a different tag or date, or go back to the - Main Branch with "update -A", you will never again see any - updates. - - 3. The ./CVS/Entries.Static file exists and you are expecting a - new file. - - If your ./CVS administrative directory contains 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". - - On most Unix systems, your disk caches are now furiously being - flushed by multiple update daemons, destroying performance and - proving to management that you need more CPU power. :-) - - On HP systems you might be asked what package you want to - install from the "update server". - - 6. Someone removed (using "admin -o") your BASE revision (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 your BASE revision when the - files themselves don't match. 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 parts - two and three of the normal development cycle: "emacs" (a synonym - for "edit" in most of the civilized world) and "commit". - - - 3P.6 What's a "sticky conflict"? How does it know a conflict occurred? - - When a "cvs update" (or an "update -j") creates a conflict, it - prints a 'C' and stores the timestamp of the file after the merge - in a special field in the ./CVS/Entries file. - - This conflict indication implies that the merge command altered - your working file to contain conflict markers surrounding the - overlapping code segments. For example, say that - - - Two developers acquire revision 1.2 of <file> via "checkout" or - "update". - - - Developer A changes line 1 from "9999" to "5555", then commits - the file, creating revision 1.3. - - - Developer B changes line 1 from "9999" to "7777", then tries to - commit the file, but is blocked because the file is not up to - date. Developer B then runs "update" and sees the conflict - marker 'C'. The beginning of the file would look like this: - - <<<<<<< <file> The working <file> in question. - 7777 Change made to the working <file>. - ======= - 5555 Change made in the first commit (1.3) - >>>>>>> 1.3 The revision created by the first commit. - - The conflict is "sticky", which means that until the conflict is - cleared, the "update" command will continue to display the file's - status as 'C' and the "status" command will show the file's status - as "Unresolved Conflict". - - Until the conflict is cleared, "commit" is blocked for this file. - - The sticky conflict indicator can be cleared by: - - 1. Resolving the conflict by editing the file. Two things must - happen before the conflict is considered resolved: - - The timestamp of the file must change. - *and* - The file must contain no conflict markers. (The string - searched for in the file is the regexp: "^>>>>>>> ".) - - After clearing the sticky conflict indicator, you may then - commit the file normally. - - 2. Removing the file and running "update". This throws away the - local changes and accepts the latest committed file on this - branch. No commit is needed. - - 3. Forcing the commit to happen by using "commit -f". This is - probably a mistake since there are few lines of real - text that begin with ">>>>>>> ". - - - 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 were all my files deleted when I executed "update"? - - You probably executed "update -r <tag>" some time ago, then - removed <tag> from the Repository files. "update -r <tag>" will - delete a file that doesn't contain <tag>. - - A way to fix this is to "cd" into your working directory and - type: - - cvs update -A - - If you don't want the latest revisions on the Main (or Vendor) - Branch, then decide what Tag (normal or branch) you want and type: - - cvs update -r <the_tag_you_want> - - Another way to make a file disappear is to execute "update -D - <date>" where <date> 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 4G.3 - - 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.4 for - suggestions. - - 4. Read the README, INSTALL and ChangeLog files to see what you - are getting into. - - 5. Make sure you have versions of all the programs mentioned in - the "cvs/src/options.h" and "cvs/src/rcs.h" files. - - 6. 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 ChangeLogs in each directory, - the Makefile.in files and the "cvsinit.sh" program. - - 2. Edit the "options.h" file in the "src" directory. - - You might need to specify a few site-specific pieces of - information including the names of a number of functions. - - Hint1: You probably 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.6.0.1 or greater and set the - "HAVE_RCS5" macro. - - 3. Execute the ./configure command. - - 4. Type "make". - - 5. After running "make" you might try running the "sanity.sh" - script: - ./src/sanity.sh `pwd`/src/cvs - - It writes into /tmp/cvs-sanity by default. - - 6. Finish reading the INSTALL file and test out the system. - - - 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. If you plan to report - bugs, you should also install "cvsbug". - - 2. Make sure you have versions of all the programs mentioned in - the options.h file, most of which are included in a standard - Unix system. - - 3. Unless you plan to reimplement RCS [:-)], you must install RCS. - - It is a very good idea to examine the RCS installation - instructions and make sure you are using the GNU versions of - "diff" and "diff3" or merges (an important part of CVS) will - not work as well as you'd like. - - 4. Set your $CVSROOT environment variable and 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 1B.4 If you use recent versions of RCS and "diff", you won't - run into the above. If you do, see 5B.8 - - ----------------- --- 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 Why would anyone use "modules"? They are too restrictive. I - want to be able to select just the files I want to edit. - 4B.8 How do I rename a file or directory? What are the consequences? - 4B.9 What are "Attic" directories? - 4B.10 Is it OK to remove anything from the Repository? - 4B.11 Can I convert to CVS from RCS without losing my revision history? - 4B.12 Can I move RCS files with branches in them into the Repository? - 4B.13 Can I use raw RCS commands on the Repository? - 4B.14 How do I convert from SCCS to RCS? - 4B.15 How do I limit access to the Repository? - 4B.16 What are the Repository Administrator's responsibilities? - 4B.17 How do I move the whole Repository? - 4B.18 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". To to your work directory and type: - - cvs checkout CVSROOT - - Then read 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 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 eight Repository control (or "database") files of - interest in the CVSROOT directory: - - 1. modules contains the "modules" database. See 1D.11, 2C.7, - 4B.6 and 4B.7 for more details. - - 2. commitinfo contains two columns: 1. a regular expression to - match against pathnames within the Repository and - 2. a <command> 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 - <command>. If <command> exits with a non-zero - status, the commit is blocked. - - A <command> associated with a pathname of - "DEFAULT" is executed if nothing else matches. - Every <command> associated with a pathname of - "ALL" is executed separately. - - 3. 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. - - 4. editinfo contains the same two columns as commitinfo, but - the <command> in the second column is intended to - do some consistency checking on the commit log. - - "DEFAULT" works as in commitinfo. - - 5. loginfo contains the same two columns as commitinfo, but - the <command> is expected to read a log message - from its standard input. The <command> 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. - - 6. cvsignore contains "ignore" patterns that are added to the - built-in ignore list. See 2D.10. - - 7. checkoutlist contains a list of other files kept under RCS in - $CVSROOT/CVSROOT that should be checked out by - mkmodules to provide a readable copy. - - 8. 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. This file is the only - one in the above list that is not under RCS. - - - 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, - a few at a time. Directories don't need to be committed. - - 3. You can move RCS files directly into the Repository. - - You should create a directory hierarchy to hold them, but you - can just move arbitrary ",v" files into the Repository. The - only "state" in the Repository other than within ",v" files is - in the required CVSROOT directory at the top of the Repository. - - - 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. I 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.) - - If you are using one of the many recent versions of Unix that - don't allow you to use the full octal mode, then you'll have - to type: chmod u=rwx,g=rwx,o=rx,g+s <dir> - - - 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, including root. - - - 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 - - - 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 many 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 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.8 How do I rename a file or directory? What are the consequences? - - In CVS there is no single "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 <tag>" 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 <tag>" produces the correct files. - - - The duplicated revision history can be slightly misleading. - - - A plain (i.e. without the "-r <tag>") "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 <tag>" 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 <tag> - onto the new, more sophisticated, revision of the Makefile. - (Yes, this changes the "released" file if <tag> 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 in the - working directory and use the "cvs remove" to get rid of the - old old file and "cvs add" to add the new one. Since there is - no way for CVS 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.9 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 <tag> or <date>. - - - 4B.10 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 the Phantom Zone. You'll need - to contact Jor-el to get them back. - - 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.<pid>") - - 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.11 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.12 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.13 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.14 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.15 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. - - Techniques for limiting access include: - - 1. Training, management and good backups. - - The best form of Repository control is a combination of: - - - A reliable backup scheme (verify it!) - - Enough training to ensure your developers are competent - and knowledgeable about all areas of your sources. - - Effective management of the boundaries and grey areas. - - In many cases, technical solutions to "security" problems are - inadequate. You should first try to avoid them. - - Personal Opinion: In an environment where "unknowns" are - allowed to touch important sources the "owner" of the CVS - Repository must be a large, loud, vigorous lout with a - well-balanced truncheon and the right to use it. Don't - underestimate the effectiveness of letting everyone know they - will be strapped into the stocks on the Town Common and pelted - with vegetables if they break something they don't understand - without first asking the experts. - - 2. Set Unix groups and permissions. See 4B.5. - You can set different owners, groups and permissions for each - sub-directory within the Repository if that helps. - - 3. Catch invocations of "commit" by defining pre-commit programs - in the "commitinfo" file. This is fairly powerful, since it - can block commits based on anything you can program. Take a - look at the programs in the "contrib" directory of the CVS - source tree. - - 4. Use multiple Repositories, each with its own protection scheme. - If you use NFS (or AFS) you can even use "export" restrictions - to various groups of machines to keep (for example) the - Engineering Repository off the Customer Service machines. - - 5. Try the "setgid" trick described in 4D.13. - - 6. Try to use the RCS access control lists, though I don't - think CVS will handle them cleanly. - - 7. Edit the source code to CVS to add your own access control. - - - 4B.16 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, every file in the Repository - should be an RCS file. - - 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. Storing site-specific ignore patterns in the - $CVSROOT/CVSROOT/cvsignore file. - - 4. Storing the names of non-standard CVSROOT files (See 4B.2) in - the $CVSROOT/CVSROOT/checkoutlist - - 5. Maintaining the other Repository control files: commitinfo, - loginfo, rcsinfo and editinfo. - - 6. Pruning the history file every once in a while. (Try the - "cln_hist.pl" script in the "contrib" directory.) - - 7. Staying aware of developments on the info-cvs mailing list and - what is available in the FTP and WWW archives. - - 8. Running "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. - - 9. 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.17 How do I move the whole Repository? - - Copy or move the tree. (On Unix systems, a set of piped "tar" - commands works great. If the Repository does not contain any - symlinks, which it normally doesn't, you can also use "cp -r".) - - If you can avoid changing $CVSROOT (i.e. the "logical" pathname of - the Repository) by replacing the old location with a symbolic link - to the new location, you don't have to do anything else. - - (You could also mount the new location on top of the old location - if you are using NFS or some other filesystem that allows it.) - - - If you must change $CVSROOT, you must also tell everyone to change - the CVSROOT environment variable in all running shells and in any - personal configuration files ('.' files on Unix) where it is set. - - The Repository itself contains no references to its own name, - except possibly in some of the files in the CVSROOT directory. If - your modules (or loginfo, commitinfo, etc.) file mentions helper - programs directly in the Repository, you'll have to change the - pathnames to point to the new Repository location. - - The main changes you'll have to make are to all the CVS - administrative files (./CVS/Repository and ./CVS/Root) in every - working directory ever checked out from the previous location of - the Repository you just moved. - - You have three choices: - - 1. If all ./CVS/Repository files in all working directories - contain relative pathnames, you don't have to do anything else. - - 2. 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. - - 3. Use "find . ( -name Repository -o -name Root )" and a - PERL or shell script to run through all the ./CVS/Repository - and ./CVS/Root files and edit the values in the files. - - - 4B.18 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 using CVS (or RCS) commands. You have to change - the permissions on both your working file and on the Repository - file from which it was retrieved. - - 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 and Merging ----------------- - - **** 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 merge onto the Main Branch a file that exists only on a - branch other than the Main Branch? (i.e. it is in the Attic) - 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 Once I've found the files I want, how do I start changing them? - I keep getting warnings about sticky tags. - 4C.18 Why do I get the latest files on the branch when I tried to - "update -r <tag>"? - 4C.19 How can I avoid a merge? I just want to move the latest revision - on my working branch directly onto the trunk. - 4C.20 How to I avoid merge collisions in the RCS $\Log$ data? - 4C.21 Why should I trust automatic merges? - 4C.22 How does CVS decide if it can safely perform a merge? - 4C.23 After resolving merge conflicts in a file, what if I want to keep - my previous version, and not take any of the branch changes? - - - **** 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 private - "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 <branch_tag>" 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 you should create a branch: - - 1. When you expect to take a long time or make a large set of - changes that the merging process will be difficult. Both - "long" and "large" are defined in your own environment. - - 2. When 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. When 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. When 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 technique: - - 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 "update" your working directory onto the branch. - - - A. Suggested procedure when using modules: - - 1. cvs rtag <branch_point_tag> module - 2. cvs rtag -b -r <branch_point_tag> <branch_tag> <module> - 3. cvs checkout -r <branch_tag> module - - - B. Suggested procedure when using your working directory, which - contains the revisions of your working files you want to branch - from: - - 1. cvs tag <branch_point_tag> - 2. cvs rtag -b -r <branch_point_tag> <branch_tag> <module> - 3. cvs update -r <branch_tag> - - - In each procedure above, 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 changes. The result would be - same because "rtag -r <oldtag> <newtag>" applies <newtag> to the - same revision that <oldtag> is attached to. You can use this - technique to avoid attaching *any* branch tags until you need - them. - - Step B.2 has two corollaries: - - 1. If you plan to create the branch tag before committing - anything in your working directory, you can use "cvs tag -b - <branch_tag>" instead of the "rtag" command. - - 2. The <module> can be a relative path to a directory - from which your working directory was checked out. - - If you have trouble figuring out what <module> to use (or - pathname to use in its place), you can aim it at whatever - parent directories you believe will cover all your work. - - If you are sure the <branch_tag> is not being used anywhere - else, 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>. - - In each procedure above, Step #3 may occur any time after step 2. - Unless you explicitly remove them with "tag -d", a <tag> is - permanent. - - - The <branch_tag> is an unusual creature. It labels a branch in a - way that allows you to "checkout" the branch, to "commit" files to - the end of the branch and to refer to the end of the branch. It - does not label the base of the branch (the branch point). - - There are two obvious ways to choose the <branch_point_tag> and - <branch_tag> names. But keep in mind that the <branch_tag> 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 whatever you like for - "bp_", as long as your <branch_point_tag> is some modification of - the <branch_tag>.) - - <branch_point_tag> Matching <branch_tag> - - 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_<branch_point_tag>". (You can substitute what - ever you like for "latest_", as long as your <branch_tag> is some - modification of the <branch_point_tag>.) - - <branch_point_tag> Matching <branch_tag> - - 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 <branch_point_tag> -r <branch_tag> - - For Style 1, this is: - - cvs diff -r bp_<branch_tag> -r <branch_tag> - - For Style 2, this is: - - cvs diff -r <branch_point_tag> -r latest_<branch_point_tag> - - - Notes on "being on a branch": - - - "update -r <tag>" 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" <tag> (including a <branch_tag>) causes most CVS - commands to act as if "-r <tag>" were on the command line. - - - A "sticky" <branch_tag> 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 <branch_tag> <module> - cd <module> - - If you already have a working directory: - - cd <working_directory> - cvs update <== Optional, to bring it up to date. - cvs update -j <branch_tag> - - 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 careful. - There are 5 different ways to look at the problem. - - A. The way to merge *all* changes made on the trunk into a working - branch is to move to the branch you want via "checkout -r" or - "update -r": - - cvs update -r <branch_tag> {optional files} - - Then merge the changes from the trunk into your working branch - using the pseudo-tag named "HEAD": - - cvs up -j HEAD {optional files} - - You will get everything from the branch point of the branch - named <branch_tag> up to the HEAD of the main branch. This is - still kind of strange. If the file is on a branch, HEAD should - be the latest thing on the branch, not the HEAD of MAIN. But - that's not the way CVS (currently) works. - - If you run "cvs up -j HEAD" again after adding more revisions - to the trunk, you may get overlaps for the text you have - already merged. It depends on your version of your RCS "merge" - command (actually the "co -j" option, which depends on the - version of "diff3" you configured RCS to use). - - - B. You can merge the difference between any two <tags> using - two "-j" options on "update" or "checkout". - - Identify the two tags on the branch you want to merge from. - - cvs update -j <tag1> -j <tag2> {optional files} - - This step assumes you were careful about tagging milestones. - You can use this technique for any two <tags> on the same - branch, even the trunk. It is also possible to use tags on - different branches, but you'll have to ponder the meaning of - the difference between those two tags. - - In place of one of the <tags>, you can use a <branch_tag> to - refer to the latest revision on that branch. See 4C.11 and - 4C.3 for info on branch points. - - Merges can also be performed by handing RCS revisions to the - '-j' options, but since revision numbers aren't the same in all - files, merging by number is normally limited to one file. Sets - of files with the exact same trees of branches and revision - numbers would work too, but that's a rare situation. - - - C. To "take" revisions from other branches instead of merging - them, see 4C.19 for an idea. - - - D. A way to gain the effect of merging the main to the branch is - to merge the branch into the main using the normal - - cvs update -A {optional files} - cvs update -j <branch_tag> {optional files} - cvs commit - cvs tag -F -b <same_branch_tag> {optional files} - - See part B of 4D.5 - - - E. Other oddities. - - This also works, but is probably not officially supported: - - cvs update -j N {optional files} - - where N is a number. This will merge all the changes from the - branch point up to the highest revision on the main branch - starting with N. For example, if your highest trunk revision - is 1.52, you can use this to grab revisions from the trunk: - - cvs update -j 1 {optional files} - - Another example: Say you have a branch point at rev 1.2 for a - branch named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, - 3.1, 3.2. Then: - - cvs update -j 1 {optional files} - - will merge the changes from 1.2 to 1.4 - - cvs update -j 2 {optional files} - - will merge the changes from 1.2 to 2.3 - - cvs update -j 3 {optional files} - - will merge the changes from 1.2 to 3.2, which in this example, is - equivalent to the use of "-j HEAD" in part A above. - - The intuitive (at least to me): - - cvs up -j MAIN (or TRUNK) {optional files} - - doesn't work. If the trunk (i.e. "main branch") had an - implicit branch named "MAIN", you could use: - - cvs up -j MAIN:10/26 -j MAIN:now {optional files} - - and refer to date-stamped revisions on the trunk using the - <branch_tag>:<date> support that works on other branches. - - You might also think you could place an explicit tag on branch - 1 (or higher) (e.g. MAINHACK:1) and use it in place of the - implicit "MAIN", but I haven't found the right combination. - - [[If you find working techniques, I'll add them here.]] - - - 4C.8 How do I merge onto the Main Branch a file that exists only on a - branch other than the Main Branch? (i.e. it is in the Attic) - - For how such a file can exist, see 3A.2 and 3A.3. - - For how to avoid creating such a file, see 3A.5. - - Though you might think that the "update -j" command could perform - the "merge" of a file from the side branch to the Main Branch, it - isn't (yet) smart enough. Unfortunately, there is no single CVS - command to do this -- it takes three steps: - - 1. To move something onto the Main Branch from the Attic, you have - to physically move the file from the Attic to the main - Repository directory associated with your working directory. - - It is exactly like resurrecting a removed file. See 3L.4 - - 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`) - - 2. Now that the file is physically in the right place within the - Repository, "update -A" will make it appear in your working - directory on the Main Branch. Do that now. - - 3. You now have a choice. The act of physically moving the file - has fused together the <branch_tag> branch and the Main Branch - for this file. You can continue that way, making changes along - the RCS Main Branch which CVS will (for this type of file only) - treat as both the Main Branch and the <branch_tag> branch. - - The other choice, which I would suggest, is to re-tag the file - with <branch_tag>, restoring a normal-looking magic branch tag - to the file: - - cvs tag -F -b <branch_tag> <file> - - - After you have done the above, you can run "update -A" or "update - -r <branch_tag>" to resume whatever you were doing before you - started this procedure. - - Caveat: The final result is a file whose revision tree doesn't - look like it was ever on any branch but the Main Branch until the - above "tag -F -b" command was executed. CVS and RCS have no way - of saving the history of the actions you have just performed. - - - 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 are added to the Tag stored - in ./CVS/Tag. - - To force your entire working directory onto the same branch, type: - - cvs update -r <branch_tag> - - - 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 you don't regularly attend group meetings in - which the branch to be worked on is a major topic of discussion, - then the group is not managing branches properly. - - We created a couple major branches a few months ago and even the - customer service people refer to the "XYZ branch" as a shorthand - for "continuing development on the XYZ project". - - - 4C.11 How do I refer to the revision where I branched so I can see - what changed since the Branch Point on another branch? - - Given the current <branch_tag> format, there is no direct way to - refer to the branch point, which is more useful in many ways - than referring to the branch, which always refers to the latest - revision on the branch. - - When CVS adds a branch tag, it attaches an RCS symbol to a - non-existent revision number containing the revision number of the - branch point as a prefix. (See Section 3O, on the "tag" command.) - RCS can't 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 the $CVSROOT/CVSROOT directory. - - You tell "checkout" or "update" what branch you want to check out - via the "-r <tag>" option. 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 force a "merge" to 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. - - A. 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 <module> - cd <module> - cvs tag -b <branch_tag> - cvs update -r <branch_tag> - >>> 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 <branch_tag> - >>> 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 these two commands: - - cvs checkout -j <branch_tag> <module> - cd <module> - - - B. The paranoid way is more difficult, but it can catch all sorts - of problems. You created the branch this way: - - cvs checkout <module> - cd <module> - cvs tag <branch_point_tag> - cvs tag -b <branch_tag> - cvs update -r <branch_tag> - >>> Edit away. - cvs commit <<== Onto branch - - The extra tag command places a non-branch tag on the Branch - Point, an act that makes it easier to do "diffs" later. Now we - decide to perform the merge: - - cvs tag <latest_on_branch_tag> - cvs update -A - *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag> - >>> *1* shows all the changes on the branch. - *2* cvs diff -r <branch_point_tag> -r HEAD - >>> *2* shows the changes on the trunk since branching. - cvs tag <premerge_tag> - cvs update -j <branch_tag> - >>> Edit the 'C' files and remove the overlaps. - *3* cvs diff - >>> Verify that *3* matches *1*, except for line numbers. - cvs commit - cvs tag <just_merge_changes_tag> - >>> Edit some more to make it all compile and work. - cvs commit - cvs tag <after_merge_cleanup_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. - - See 3H.13 for some more information about dealing with merges - after import. The last part of the procedure is applicable to any - large merge. - - - 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 <rev>" 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 <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 <non-branch-tag>" - - Doing this overrides the sticky <branch_tag> 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 <branch_tag>". - - 2. Use the "update -r <branch_tag>:<date>" trick. - - This is almost like using the '-D' option, but it looks for - revisions extant on <date> 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 on - the Vendor branch. Think about it. How does revision - 1.2.4.2.4.2.2.1 grab you?) - - - 4C.17 Once I've found the files I want, how do I start changing them? - I keep getting warnings about sticky tags. - - What you probably did was type "cvs update -r <tag>" where <tag> - is a non-branch tag. "update" created a sticky tag for a specific - revision, not a branch. To start working right there, you have to - create a branch to work on. - - You have two choices. - - A. You can do it in place and keep working: - - cvs tag -b <branch_tag> <<== To tag the current files. - cvs update -r <branch_tab> <<== To move onto the branch. - - B. You can do it "externally" and create a new working directory: - - cvs rtag -b -r <tag> <branch_tag> <module> - cvs checkout -r <branch_tag> <module> - - <module> can be a relative path within the Repository. - - <tag> in the above is the non-branch tag you placed earlier - that caused the error in your question. Be warned that - if <tag> is not set on all the files (or all the right - revisions) you won't get exactly what you wanted. - - - 4C.18 Why do I get the latest files on the branch when I tried to - "update -r <tag>"? - - If "update -r <tag>" always retrieves the latest files on a - branch, then <tag> is really 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 - <branch_tag> 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. - - - 4C.19 How can I avoid a merge? I just want to move the latest revision - on my working branch directly onto the trunk. - - There is no direct way to do this using CVS, though the technique - is not difficult using shell commands. Here's one way: - - 1. Move your working directory to the Main Branch. - - cvs update -A - - 2. Use "update -p" to grab the latest revision on the branch and - write it over your working files. Make sure you don't have an - modified files -- you will lose them. The following is in - "csh" syntax. Change the wildcard to grab the files you want - - foreach i (Makefile *.cc *.hh) - cvs update -p -r <branch_tag> $i > $i - end - - 3. Commit all the working files onto the Main Branch. - - cvs commit -m 'Moved branch <branch_tag> onto MAIN' - - You should experiment with the above before blasting everything. - - - 4C.20 How to I avoid merge collisions in the RCS $\Log$ data? - - In short, you can't. The RCS $\Log$ keyword is handled - differently from all other RCS keywords. - - On the info-cvs mailing list, there is a periodic discussion that - goes something like this: - - Question: How do I deal with $\Log$? - Answer1: You can't do much with it. Here's how it works. . . - Answer2: I've found a limited way to use it. . . - Answer3: Get rid of it. $\Log$ is an abomination. - - I tend to lean toward answer #3. There are only two sets of - people who would ever have access to logs stored within sources - files, developers and source customers. - - For developers: - - 1. Log entries within sources files are notoriously incomplete, - rushed, poorly phrased and in many cases incorrect, making them - useless for debugging or file maintenance. I remember a maxim - from "Software Tools" (I believe): "Read the code, not the - comments." No managerial order or plan for programmer - discipline will affect this in the real world. - - 2. Log entries are usually in an unreadable mixture of styles. - Many log entries are just plain meaningless. Some are foolish. - Some are even insulting. Examples: - - "Corrected spelling of misspelling." - "Bug fix." - "Reversed stupid change in previous revisions." - "If Joe could do his job, this would already have worked." - - 3. Log entries are not managed well by the tools. Any merge can - cause conflicts in the $\Log$ data. Branch merges produce - incomplete logs. They can be edited into chaos and they are - not regenerated. They waste space duplicating information - available to the developer with a single command. - - 4. Even if correct when originally entered, as changes are made to - the file, log entries become false over time. Humans are not - good at reading down through a list and remembering only the - last change affecting something. Over time *most* of the log - is wrong. - - 5. Even if still correct, the log data is almost useless to - developers without the code diffs. If you can get code diffs, - you can display the log. - - - For source customers the problem is even worse. The last thing - you want to show customers is a hodge-podge of tiny comments about - large changes followed by a series of emergency fixes before - delivery. If you distribute sources, then you should provide - documentation, or changelogs reviewed by people who won't let - comments like "Fixed for stupid customer." out the door. - - Conclusion: Though some people would prefer to see in this FAQ - techniques for making the $\Log$ entries the best they can be, I - believe them to be a lost cause. My suggestion is to hunt down, - root out and destroy all occurrences of $\Log$ and the unusable - data attached to it wherever you may find it. - - - 4C.21 Why should I trust automatic merges? - - Some developers have the feeling that three-way merging doesn't - work. They fear and distrust 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 obviate. - - 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. - - - 4C.22 How does CVS decide if it can safely perform a merge? - - CVS can merge any text file, possibly discovering a conflict and - leaving overlaps for you to edit. Editing the conflict markers - out of the file is a moment's work, but resolving the conflict - could take an arbitrary amount of time. CVS works to determine if - it *should* merge, not if it *can*. - - See 2B.6 for how the merge proceeds. - - - 4C.23 After resolving merge conflicts in a file, what if I want to keep - my previous version, and not take any of the branch changes? - - If you want to retain your previous version, a version on the - MAIN branch greater than 1.1 (one you committed there), just throw - the merged file away and "cvs update" the file. - - You don't need to commit something to remember it. The tags you - place before and after the merge should give all the handles you - need to find various versions. You don't have to create a new - version of the file. - - If you want to retain the previous Vendor revision, you can grab a - copy of it using "cvs update -p" and commit it or use the - technique described in 3B.3 to revert back to the Vendor branch. - - - ----------------- --- 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 or rename 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 Where did the ./CVS/Entries.Static file come from? What is it for? - 4D.11 Why did I get the wrong Repository in the loginfo message? - 4D.12 How do I run CVS setuid so I can only allow access through the - CVS program itself? - 4D.13 How about using groups and setgid() then? - 4D.14 How do I use the "commitinfo" file? - 4D.15 How do I use the "loginfo" files? - 4D.16 How can I keep people with restrictive umask values from blocking - access to the Repository? - 4D.17 Why do timestamps sometimes get set to the date of the revision, - sometimes not? The inconsistency causes unnecessary recompiles. - - - **** 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 may also need to apply the '-ko' flag to the files to avoid - expanding RCS keywords, which can be done via: - - cvs admin -ko filename - - - 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. - - See 3C.8 for a way to serialize access to binary files. - See 3A.8 for adding binary files, 3H.4 for importing binary files - and 3B.4 for some more information about "admin". - - - 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 never realized how much help a wide-open revision - control system 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 revision, by typing: - - cvs admin -N<tag> <file> - - 2. Retrieve the outdated revision. - - You should first look in your backup system for recent versions - of the file. If you can't use them, you can carefully extract - each revision that followed the earliest outdated revision - using RCS (or "cvs admin") commands and reconstruct the file - with all the right revisions, branches and tags. This is a lot - of work. - - You *can't* insert a revision into the current RCS file. - - 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 <file>. - - a. Use "update" to grab the revision you want, then - execute a normal "tag" command to Tag that revision: - - cvs update -r <rev> <file> - cvs tag <tag> <file> - - b. Use "admin" to set the tag to a specific revision: - - cvs admin -N<tag>:<rev> <file> - - - 4D.5 How do I move or rename a magic branch tag? - - (To rename a non-branch <tag> see 3O.9.) - - Before reading this, read 3M.3 and 3M.4 and understand exactly - how tag and rtag use '-r' and why it won't do the right job here. - - A. First, I have to explain exactly what a magic branch tag is. - - A magic <branch_tag> is an artificial tag attached to a - non-existent revision on a non-existent branch number zero. It - looks like this: - - TAG1:<X>.0.Y - - <X> is the "branch point revision", a normal revision with an - odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc) - - Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches, - other than the Vendor branch, are even numbered. - - TAG1 is considered by CVS to be attached to revision <X>. The - first "update -r TAG1 <file>" after applying TAG1 will produce - a copy of revision <X> with a sticky tag of TAG1. The first - "commit" to that file will cause CVS to construct an RCS branch - named <X>.Y and check in revision <X>.Y.1 on the new branch. - - Note: TAG1 is *not* considered to be attached to <X> by RCS, - which explains why you can't refer directly to the branch point - revision for some CVS commands. - - - B. Moving a magic <branch_tag> is the act of reapplying the same - tag to different revisions in the file: - - TAG1:<X>.0.Y - to - TAG1:<X>.0.Z or TAG1:<A>.0.B - - You can move a magic branch tag to the revisions of your choice - by using "update" to find the revisions you want to tag and - reapplying the tag to all the files with the '-F' option to - force it to move the existing <branch_tag>. - - cvs update -r <tag/rev> (or '-A' for the Main Branch) - cvs tag -F -b <branch_tag> - - If the earlier location of TAG1 refers to a physical branch - within any RCS file, moving it will make the existing branch in - the file seem to disappear from CVS's view. This is not a good - idea unless you really want to forget the existence of those - RCS branches. - - If the "update" above retrieves the original branch point - revision (<X>), the "tag" command above will create the tag: - - TAG1:<X>.0.Z - - Where Z is 2 greater than the highest magic branch already on - revision <X>. The TAG1 branch will still have the same branch - point (i.e. revision <X>), but the first commit to the new TAG1 - branch will create a different RCS branch number (<X>.Z instead - of <X>.Y). - - - C. Renaming a magic <branch_tag> is the act of changing - - TAG1:<X>.0.Y - to - TAG2:<X>.0.Y - - There is no harm in changing a tag name as long as you forget - that TAG1 ever existed and you clean up any working directories - with sticky TAG1 tags on them by using "update -A", "update -r - <other_tag>" or by removing the working directories. - - On the other hand, actually changing the tag is not easy. - - See 3M.3 for why the seemingly obvious solution won't work: - - cvs tag -b -r <old_branch_tag> <new_branch_tag> - - The only direct way to rename a magic tag is to use the "admin" - command on each file: (You might want to use '-n'. Read "man - rcs" and look at the '-n' and '-N' options.) - - cvs admin -N<new_branch_tag>:<old_branch_tag> . - cvs tag -d <old_branch_tag> - - But you have to be careful because "admin" is different from - other CVS commands: - - 1. "admin" can be used recursively, but only by specifying - directory names in its argument list (e.g. '.'), - - 2. Where "rtag -r <old_branch_tag>" would interpret - <old_branch_tag> as a magic CVS branch tag, "admin" is a - direct interface to RCS which sees a magic branch tag as - a simple (though non-existent) RCS revision number. - - This is good for us in this particular case, but different - from normal CVS. - - 3. "admin" also skips the Attic and produces different kinds - of errors than CVS usually does. (Because they are coming - directly from RCS.) - - - The other way to rename a magic <branch_tag> is to edit the - Repository files with a script of some kind. I've done it in - the past, but I'll leave it as an exercise for the reader. - - - 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 (or parent branch) 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. - - See 3C.8 for a way to avoid machetes aroused by lock collisions. - - 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 - committed earlier by CVS users. - - 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. Branch merges will also be a major problem. - - - 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: You committed a source file at 5PM. Bubba updated his - copy of the file, grabbing your changes, then changed and - committed a new revision of the file at 6PM. At 7PM, you compile - your file. Then you execute "update". If CVS sets the date to - the one in the RCS file, the file would be given a timestamp of - 6PM and your 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. - See 4D.17 for some more about timestamps. - - - 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 <command> - - - The '-n' option to the main cvs command turns off lock checking, a - reasonable act for read-only commands given the promise offered by - '-n' not to alter anything. The "diff", "log" and "stat" commands - provide the same information (for files that are not being - committed) when used 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 the suggested command is "cvs -n <command>". The - visually similar command "cvs <command> -n" has no relation to the - suggested 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 reliably. - - - 4D.10 Where did the ./CVS/Entries.Static file come from? What is it for? - - Each CVS working directory contains a ./CVS/Entries file listing - the files managed by CVS in that working directory. Normally, if - the "update" command finds a file in the Repository that is not in - the ./CVS/Entries file, "update" copies the appropriate revision - of the "new" file out of the Repository and adds the filename to - the Entries file. This happens for files: - - 1. Added to the Repository from another working directory. - 2. Dragged out of the Attic when switching branches with - "update -A" or "update -r". - 3. Whose names were deleted from the ./CVS/Entries file. - - If the ./CVS/Entries.Static file exists, CVS will only bring out - revisions of files that are contained in either ./CVS/Entries or - ./CVS/Entries.Static. If a Repository file is found in *neither* - file, it is ignored. - - The ./CVS/Entries.Static file is created when you check out an - individual file or a module that creates working directories that - don't contain all files in the corresponding Repository directory. - In those cases, without an ./CVS/Entries.Static file, a simple - "update" would bring more files out of the Repository than the - original "checkout" wanted. - - The ./CVS/Entries.Static file can be removed by hand. It is - automatically removed if you run "update -d" to create new - directories (even if no new directories are created). - (Internally, since "checkout" turns on the '-d' flag and calls the - "update" routine, a "checkout" of a module or directory that - writes into an existing directory will also remove the - ./CVS/Entries.Static file.) - - - 4D.11 Why did I get the wrong Repository in the loginfo message? - - You probably: - - 1. Use multiple Repositories. - - 2. Configured CVS to use absolute pathnames in the - ./CVS/Repository file. - - 3. Configured CVS not to use the ./CVS/Root file. - - 4. Typed the "commit" command in one Repository with your - $CVSROOT pointing at another. - - "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. - - If you avoid even one of the four steps above, you won't see this - problem. If you configure ./CVS/Root, you won't be allowed to - execute the program causing the error. - - - 4D.12 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.13 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". (This example uses "cvsg". You - can name it as you wish.) - - 2. Put *no* users in the "cvsg" group. You can put Repository - administrators in this group if you 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 {} \; - - On some systems you might have to type: - - find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \; - - 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 enable the world - execute bit (mode 2771) on directories, users can traverse the - tree and 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 with the setuid() method the problem of - keeping "admin" from breaking things. - - - 4D.14 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 any function called from - within the commitinfo file 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. - - If you want to serialize binary files, you might consider - something like the rcslock.pl program in the contrib directory - of the CVS sources. - - - 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. Some examples exist in the - contrib directory. - - - 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 -- you can have as many ALL lines as you like. - - - 4D.15 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(3)") 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 - - - 4D.16 How can I keep people with restrictive umask values from blocking - access to the Repository? - - If a user creates a new file with restricted permissions - (e.g. 0600), and commits it, the Repository will have a file in it - that is unreadable by everyone. The 0600 example would be - unreadable by *anyone* but root and the user who created it. - - There are 3 solutions to this: - - 0. Let it happen. This is a valid way to protect things. If - everyone is working alone, a umask of 077 is OK. If everyone - is working only in small groups, a umask of 007 is OK. - - 1. Train your users not to create such things if you expect to - share them. - - 2. See 4B.5 for a small script that will reset the umask. - - I personally don't like the idea of a program automatically - *loosening* security. It would be better for you all to talk - about the issue and decide how to work together. - - - 4D.17 Why do timestamps sometimes get set to the date of the revision, - sometimes not? The inconsistency causes unnecessary recompiles. - - The "checkout" command normally sets the timestamp of a working - file to match the timestamp stored on the revision in the - Repository's RCS file. - - The "commit" command retains the timestamp of the file, if the - act of checking it in didn't change it (by expanding keywords). - - The "update" command sets the time to the revision time the first - time it sees the file. After that, it sets the time of the file - to the current time. See 4D.8 for a reason why. - - Here's a two-line PERL program to set timestamps on files based on - other timestamps. I've found this program useful. When you are - certain you don't want a source file to be recompiled, you can set - its timestamp to the stamp on the object file. - - #!/usr/local/bin/perl - # - # Set timestamp of args 2nd-Last to that of the first arg. - # - ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime) - = stat(shift); - utime($atime,$mtime,@ARGV); - - - ----------------- --- Section 4E -- Internal errors ----------------- - - **** 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 Explain: "co error, line 2: Missing access list" - 4E.4 Explain: "error: RCS file name `xyz .c' contains white space" - 4E.5 Explain: cvs checkout: warning: <X> is not (any longer) pertinent - 4E.6 Why did a Repository file change from <file>,v to ,<file>,? - - - **** 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 if they - are old. - - - 4E.3 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. - - HP decided to "standardize" on an ancient version of RCS some time - ago. You can't use it for CVS. See 4H.6. - - Since the error comes from having a later version of RCS than HP - supports, you probably did install the later version but must have - recently changed your $PATH or installed the HP package that has - RCS in it. - - You should either reconfigure CVS to use absolute pathnames to the - proper versions of the RCS programs that CVS uses, or change your - PATH to look there first. If you haven't installed the latest - version of RCS, you should upgrade. See 1B.4 - - - 4E.4 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.5 Explain: cvs checkout: warning: <X> is not (any longer) pertinent - - This message occurs in three instances: - - 1. When there is an entry in the ./CVS/Entries for file <X> 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 `<module/path>' - 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. - - - - 4E.6 Why did a Repository file change from <file>,v to ,<file>,? - - This is an RCS problem, since the ,<file>, syntax for file names - is used by RCS and not CVS. - - RCS constructs a new <file>,v in a temporary file named ,<file>, - (which doubles as a lock file) then renames it to <file>,v when it - is done. The only way this is reliable is if your system's - version of rename(2) is an atomic, as required by POSIX. - - If your system has a non-atomic (and therefore non-POSIX) - rename(2) system call, RCS runs uses an internal version of this - algorithm to approximate the atomic rename: - - rm <file>,v; ln ,<file>, <file>,v; rm ,<file>, - - If the system crashes, or you lose your NFS connection between the - first "rm", but before the "ln", you can be left only with the - ,<file>, file. If the crash or network failure occurs between the - "ln" and the final "rm", you could be left with a pair of linked - names. - - Recovery: - - If only the ,<file>, exists, rename it to <file>,v. - - - If both ,<file>, and <file>,v exist and are linked, remove the - ,<file>, file. - - - If both ,<file>, and <file>,v exist and are separate files, look - at the dates, "diff" them and make your best guess. This sounds - like the remnants of two separate events. - - - ----------------- --- 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 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' - or 'C'), 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 provides a graphical user interface to the Concurrent Version - System (CVS), a powerful revision control system. GIC is - implemented in the Tcl/Tk programming language and is intended to - augment the sometimes cumbersome CVS command line interface. - Novices should find GIC to be much easier to learn than the CVS - command line. - - While GIC is easy to use, it does not contain any documentation on - CVS. Users of GIC must first learn the concepts of CVS such as - modules and merging, as well as the simple functions, such as - committing and updating. The CVS manual page and the README file - are good places to look. - - contact - David Marwood - marwood@cpsc.ucalgary.ca - - [Extracted from an announcement by David Marwood.] - - GIC can be obtained by anonymous ftp to (on the date of this FAQ) - - ftp.cpsc.ucalgary.ca:/pub/users/marwood/gic-1.1.tar.Z - ftp.cpsc.ucalgary.ca:/pub/users/marwood/gic-1.2b1.tar.Z - - - 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 ftp.llnl.gov [128.115.54.18] - in gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.) - - contact - Kathleen Dyer kdyer@llnl.gov - (510)423-6803 - (510)423-5112 FAX - - [[Does someone want to elaborate?]] - - ----------------- --- Section 4G -- Engineering ----------------- - - **** Questions: - - 4G.1 Where can I find out about Software Engineering? - 4G.2 How do I flexibly arrange the modules file to describe my sources? - 4G.3 Can I have multiple source repositories, one for each project? - 4G.4 Who should administer the Repository and manage the modules file? - 4G.5 Isn't disk space a big factor? CVS copies files out of the - Repository, duplicating everything. - - - **** Answers: - -This section is really beyond the scope of CVS, but so many people ask -questions about how to do Software Configuration and Engineering that I -thought I'd try to include some information. If you have any -improvements, references or ideas, speak up. - - - - 4G.1 Where can I find out about Software Engineering? - - A couple different people suggested this book: - - Software Configuration Management: Coordination for Team - Productivity; Wayne A. Babich; Addison Wesley; 1986; - ISBN 0-201-10161-0 - - - A number of others suggested Appendix B of the book "Decline and - Fall of the American Programmer" by Ed Yourdon, called "The - Programmer's Bookshelf". It list 87 books you are expected to - have read. Since they publish many of the books, Prentice-Hall - distributes this list as "Prentice Hall Professional Technical - reference PTR-125-AA3. - - One interesting item from the Yourdon book: The total number - of professional computer books sold is less than the number - of programmers currently in the United States. It wasn't clear - from the book whether this meant "per year" or not, but it is - still frightening. - - - 4G.2 How do I flexibly arrange the modules file to describe my sources? - - An equivalent question might be, "How do I structure my sources?" - This can be a difficult question especially in the areas that are - more political than technical. - - Generally you want to think about which pieces of your system need - to be checked out together, built as one system or tagged as a - consistent whole. You should certainly create 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 of the Repository containing - files that will all be worked on at the same time by the same - person or group. - - 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 for some info about the modules - file. - - Here are a few types of modules. You should experiment to see - what kind of structure each of these produces. They all have - different uses. - - 1. Connected projects in one group with two separate helper - directories. The helper directories can contain build tools, - header files, libraries, or whatever you like. - - These are all aliases that checkout relative pathnames. The - equivalent results could be produced by placing the selected - relative pathnames on the "cvs checkout" command line. - - pr1 -a P1 HELPERS - pr2 -a P2 HELPERS - pr3 -a P3 HELPERS - pr12 -a P1 P2 HELPERS - pr13 -a P1 P3 HELPERS - pr23 -a P2 P3 HELPERS - - P1 -a group1/proj1 - P2 -a group1/proj2 - P3 -a group1/proj3 - HELPERS -a group1/helper1 group1/helper2 MAKEFILE - MAKEFILE -a group1/Makefile - - Actual Repository directory structure: (from $CVSROOT down) - - group1/ - Makefile - The top level Makefile. - helper1/ - helper2/ - Helper files and dirs - proj1/ - Files and dirs - proj2/ - Files and dirs - proj3/ - Files and dirs - - "checkout group1" produces a duplicate of the above. - "checkout projX" produces all but "projY" and "projZ". - "checkout projXY" produces all but "projZ". - - - 2. Here is the exact same set of module names describing the same - Repository layout using module names (and aliases containing - module names) instead of merely aliases for relative pathnames. - - There is one difference in the result. The name of the top - level directory in the checked out working tree will match the - "module" name (e.g. pr1) instead of always being "group1" as it - was in the first example above. - - pr1 group1 proj1 &HELPERS - pr2 group1 proj2 &HELPERS - pr3 group1 proj3 &HELPERS - pr12 group1 proj1 proj2 &HELPERS - pr13 group1 proj1 proj3 &HELPERS - pr23 group1 proj2 proj3 &HELPERS - - HELPERS -a helper1 helper2 group1-Makefile - helper1 group1/helper1 - helper2 group1/helper2 - group1-Makefile -d . group1 Makefile - - The above line (with the -d in it) says that when the - module named "group1-Makefile" is checked out, the file - named Makefile file will be found in a directory named - $CVSROOT/group1 and will be checked out into a directory - named '.', which obviously already exists. - - The & references say to interpret those pathnames relative - to the directory where the whole module is stored. For - the "pr1" module, that directory is "group1", so the - &HELPERS reference winds up placing Makefile in '.' - relative to "group1". - - - 3. A short one containing the basic "module" actions: - - m1 head/path file1 dir2 file3 dir4 file5 - - When checked out, a directory named "m1" appears in your - current directory. Elements named file1, dir2, file3, - dir4, and file5 appear in it. They were originally taken - as relative paths from $CVSROOT/head/path. - - - 4. Here's another way to construct a working directory out of - pieces of the Repository: - - projX projX Makefile &projX_inc &projX_src &projX_doc - - # The first line selects a single file within projX, plus - # the contents of three other modules. Those three other - # modules rename their directories. - - projX_inc -d include projX/inc - projX_src -d source projX/src - projX_doc -d documentation projX/doc - - - 5. A Unix tree. This is similar to what CVS was developed for and - the way I have used it for years. - - # Top level - unix unix - u_bin unix/bin - u_etc unix/etc - u_man unix/man - usr-bin unix/usr.bin - - # Subdirs of top level dirs. (tiny subset) - ls unix/bin/ls - fsck unix/etc/fsck - man8 unix/man/man8 - - # Programs without subdirs. (tiny subset) - cat unix/bin Makefile cat.c - uniq unix/usr.bin Makefile uniq.c - - # /usr/local/src - localsrc localsrc - gnu localsrc/gnu - public localsrc/public - X11 localsrc/X11 - - # GNU and PD tools - cvs localsrc/gnu/cvs - emacs localsrc/gnu/emacs - rcs localsrc/gnu/rcs - btoa localsrc/public/btoa - tcsh localsrc/public/tcsh - - # X11 related items. - tvtwm localsrc/X11/contrib/tvtwm - - "unix" was checked out and built from the top down, using a set - of Makefiles that knew about the whole structure. "localsrc" - was kept checked out in /usr/local/src. - - At any time I could run "checkout ls" or "checkout cat" and get - a simple directory with only that tool in it, plus a subset - Makefile that knew how to build that tool against the installed - (or alternate, via environment variables) headers and libraries. - - I found it very handy to be able to run "ls" and see the three - tools I was porting that week. - - - 4G.3 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. - - If you have two modules or directories by the same name at the - same relative path inside two different Repositories, you are - asking for disaster. You could unexpectedly 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. - - - 4G.4 Who should administer the Repository and manage the modules file? - - This is a "management style" question. In large or traditional - groups, the CVS procedures are warped to conform to local - conventions. In small groups, in groups with strong personalities - or on new projects the choice of source control procedures can - help create some of the working environment. Here is a taxonomy - of environments I have worked in or helped set up: - - Situation 1. - - A small number of competent developers working on a medium - size project. We all got along and we all respected each - other (at least technically). Anyone edited anything. - - Modules and Repository admin was mostly left to me. I never - found a problem in minor changes made by anyone else. - - - Situation 2. - - A large number of experienced developers sprinkled with - wackos. Many of the developers didn't want to deal with any - kind of source control. They wanted a full-service source - control system that caused them zero thought. - - I learned "big stick" diplomacy here. There was a small - number of "designated" (by me) people who were allowed to do - *anything* other than "update" and "commit". Even "checkouts" - were controlled. This is where I found "history" and - "release" the most useful. - - Situation 3. - - A small number of developers who wanted me to "help", but who - didn't want to deal with anything other than their favorite - algorithms. - - I didn't have the time to baby-sit this group, so I designated - one of them to be my official contact and made him do it all. - He felt sullied by the requirement to pay attention to - anything other than his pet coding projects, but enjoyed the - "status" of being the only one who could touch the control - files without my kicking the chair out from under him. - - Situation 4. - - A huge number of developers of covering the whole spectrum of - competence and experience split into 20 groups, none of which - cooperated with the others, working on 57 different projects, - most of which didn't inter-operate. - - Managing it in any coherent way was not my responsibility (and - beyond my tolerance for chaos). Too many people. So I - privately designated a person in each group to be the contact - and kept watch on the Repository activity. When something - went wrong, I notified the contact for the group and told him - what was happening and *he* kept his troops in line. They - were tougher with their own group that I would have been. - - Eventually only a few people were willing to touch the control - files, since they were flamed from all directions if they - screwed up. - - Situation 5. - - In a medium group of really *serious*, and seriously - overworked, people, someone else was designated the "master". - I convinced the master I knew what I was doing and went on my - way. - - No one else in the world was allowed to touch anything. - - Situation 6. - - In a large amorphous group of beginners, experts and clowns, - over whom no one had official control, I was forced to employ - a group of relative beginners (who became experts rather - quickly) to police the world. The ultimate in locking the - barn after the horse was stolen, we kept Chaos from destroying - us only by use of superior firepower. - - - - My choice, if allowed, is to let anyone touch anything. I keep - backups of important items and let people know individually - whether I want them to touch things or not. If someone on my "no - touch" list touches and succeeds, they are allowed more slack. If - they screw up after being warned, their screwup becomes public. - After a few months, I usually have no trouble keeping the world - running smoothly, at least from my (and CVS's) perspective. - - - 4G.5 Isn't disk space a big factor? CVS copies files out of the - Repository, duplicating everything. - - Everyone knows that disk space is getting cheaper. How do we - reconcile this with the equally well-known problem that *all* disk - is *always* filled up? - - In my opinion, the main reason disk space will never be an - unlimited resource is that it is the major variable in - organizational time/space tradeoffs. It isn't a problem of waste - or an aspect of Murphy's law, as some claim it is, but rather a - direct consequence of good management. Disk space is, and will - always be, a limited resource. - - First, the cost of *deploying* that disk is not dropping as fast - as the cost of the storage medium. The cost of machines to hold - the disks and the networks to connect them are dropping more - slowly than disk media. And the cost of the human time necessary - to manage the machines, networks, disks, and the developers using - them, is not dropping at all. The cost of human time continues to - rise. - - If management decides that expensive human time can be saved by - using all that new disk space to keep the last three releases - online, then that's what it will be used for. If each release - takes up a Gigabyte and you support 30 platforms, a simple - time-saving suggestion has just grabbed 100 Gigabytes of disk - space. And we've ignored the potential disk storage needed to - support "better Customer Service", another management refrain. - - Even at 30 cents per Megabyte (next year's price), you've just - used up $30,000 of disk space. And that doesn't count the - computers, tape drives and humans necessary to maintain and deploy - all of it. Spending money to save time has its own overhead, too. - - - Binaries are getting bigger. Graphics and data collection devices - can eat up any amount of disk. There are more tools available, - more libraries, more raw data than you can ever store. My home - computer has a Gigabyte of disk on it. It could easily handle 30. - - The "economy" of disk storage media will never remove the need to - manage disk space. - - - So, here's an un-reviewed suggestion originally from Graydon Dodson - <grdodson@lexmark.com>, which I've altered and edited heavily. - - - Keep a directory where the whole tree is checked out. (It might - be built and tested once in a while to make sure it is worth - linking to, but that doesn't affect the source control aspect of - this procedure). Let's call it /master/build. - - - Write a tool that creates a tree of directories (like the X11 - "lndir" command) filled with links to the checked out files in - the /master/build tree. - - This tool should also provide real copies of, not symlinks to, - all the files within the CVS administrative directories. - - - You could also provide a way for the tool to take a list of - whole directories that you will never change, for which it would - create a single symlink to the directory and not a subtree of - symlinks to files. Or you could rm -r pieces of the resulting - working directory yourself and replace it with links. - - - If you want to edit a file, you have to grab a real copy and - keep it until your revision shows up in the /master/build tree. - I'd create a script to do this: cvsgrab <file> - - #!/bin/csh -f - set f = $1 - if (! -l $f) then - echo "file $f is not a symlink" - exit 1 - endif - rm $f - set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'` - cvs update -p -r $rev $f > $f - - You can't do a plain "cvs update" since that would grab newer - revisions from the Repository, not the revision you wanted to - start with. After the file is no longer a symlink, you can work - normally. You'll have to run "update" before "commit" anyway if - there are newer revisions. - - - Presumably there would also be a tool to traverse the link tree - and revert it to links if there are no modified files and/or if - all the real files match the revision of the /master/build tree. - - - To avoid confusing CVS when the /master/build revisions are - updated but your CVS/Entries files is not, CVS would have to - change to handle symlinks. It currently causes problems with - this scenario: - - 1. ./<file> is a symlink. - 2. ./CVS/Entries says you are revision 1.2. - 3. The corresponding CVS/Entries file in /master/build - says the latest revision is 1.3. - 4. cvs update <file> shows a 'C' conflict flag. - - ----------------- --- Section 4H -- Other Systems ----------------- - - **** Questions: - - 4H.1 I use a NeXT. Is there anything I need to know? - 4H.2 I use OS/2 and/or DOS. Is there anything I need to know? - 4H.3 I use SCO Unix. Is there anything I need to know? - 4H.4 I use AIX. Is there anything I need to know? - 4H.5 I use IRIX. Is there anything I need to know? - 4H.6 I use an HP system. Is there anything I need to know? - 4H.7 I use AFS. Is there anything I need to know? - 4H.8 I use A/UX. 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. - - 4H.1 I use a NeXT. Is there anything I need to know? - - NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather - than the files used 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. - - Some time ago, <Bob_Vadnais@pdh.com> posted a palette named - CVSPalette that claimed to resolve this problem. It was intended - to preserve the CVS administrative directories within nib - documents (directories) that Interface Builder usually removes. - - CVSPalette is no longer in its announced place: - - ftp.cs.orst.edu:/pub/next/submissions - - though I did find two other interesting files on ftp.cs.orst.edu: - - /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z - - which is a port of CVS 1.3 (along with RCS and diff) and: - - /software/NeXT/sources/programming/cvs.postamble-2.4.gz - - which appears to be a set of wrappers for CVS commands that claim - to allow you to use CVS effectively (and without need for the - "command line") on a NeXT machine. - - - [[Anyone know the truth about CVS and NeXT?]] - - - 4H.2 I use OS/2 and/or DOS. Is there anything I need to know? - - You can share RCS files between Unix and DOS while avoiding the - MS-DOS file name limits by setting your RCSINIT environment - variable to '-x/,v'. New RCS files will be created without the - standard ",v" suffix, though files ending in ",v" will still be - found if there is no matching file in the same directory without - the ",v". - - Erik van Linstee <linstee@dutecaj.et.tudelft.nl> offers an - OS/2 and a DOS port of CVS 1.3 in: - - ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools - or - ftp.rrzn.uni-hannover.de:/pub/os2-local - - The files are named: - - cvs13p?[bs].zip - - Where the ? stands for the patch level (currently 8) and the b is - for the binaries, the s for the sources. - - There are three binaries. An OS/2 only one (32-bit), a DOS only one - (16-bit) and an EMX one that runs on both (32-bit). - - There are many differences between the Unix and the DOS versions - of CVS. Read the material that comes with the DOS version before - using it. - - [[Updates?]]. - - - 4H.3 I use SCO Unix. Is there anything I need to know? - - On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the - configure program detects POSIXness and configures in the use of - POSIX signals. Workaround : Edit out the check for POSIXness in - the configure script. [[You could also remove all occurrences of - "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]] - - SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks - the use of log.pl as it gets invoked by /bin/sh instead of - !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into - a shell script which invokes perl with log.perl (renamed from - log.pl) as input. - Contributed by Joe Drumgoole - - - 4H.4 I use AIX. Is there anything I need to know? - - The only report on AIX claims to have no trouble using it in - concert with SunOS and IRIX platforms. - - - 4H.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. - - - 4H.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.13, 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 - - - 4H.7 I use AFS. Is there anything I need to know? - - There is a problem with the way CVS performs its locking when the - files are within AFS. When your current PTS id != your uid, the - locks are not deleted. The stat() system call returns the PTS id - of the owner. If that id != your uid, CVS assumes you did not lock - it, and leaves the lock files alone. The next time you try to use - it, it complains that someone has the repository locked. - - Contributed by Michael Ganzberger - - [[This was against CVS 1.3. Is it still in CVS 1.4?]] - - - 4H.8 I use A/UX. Is there anything I need to know? - - [[??]] - - - - -============================================= -== 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 <berliner@sun.com> converted a collection of - scripts written by Dick Grune <dick@cs.vu.nl> into a C program, - then added all sorts of features. He continues to maintain CVS. - - Jeff Polk <polk@bsdi.com> wrote much of the code added between - revisions 1.2 and 1.3. Many others were involved at some level. - - david d zuhn <zoo@armadillo.com> fixed a number of bugs, added - some of the new features, reworked the whole thing to be more - portable, and provided much of the energy to push CVS 1.4 out - the door. - - Jim Kingdon implemented CVS 1.5's remote repository access - features, fixed many bugs, and managed the release of version 1.5. - - Take a look at the README and the ChangeLog files in the CVS - sources for more contributors. - - - 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. Between 2/93 and 10/93, I - released about 20 versions, with corrections and additions from - the info-cvs mailing list and private correspondence. - - Between 10/93 and 10/94 I extracted frequently asked questions - from the 1200 mail messages to the info-cvs mailing list, - turned them into focused questions and tried to answer them. - - 93/02/?? ~4000 lines - 93/06/?? ~5000 lines - 93/10/23 7839 lines 278K - 94/10/29 9856 lines 360K - 95/05/09 9981 lines 365K - - 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. - - If I used someone else's text verbatim, I mentioned it in the - given answer. The people whose email postings have added to this - document or who have added to my understanding are: - - Brian Berliner <berliner@sun.com>, CVS maintainer. - Paul Eggert <eggert@twinsun.com>, RCS maintainer. - - Gray Watson <gray@antaire.com> - Per Cederqvist <ceder@signum.se> - Pete Clark <pclark@is.com> - - 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): - - Per Abrahamsen <amanda@iesd.auc.dk> - Donald Amby <amby@mixcom.mixcom.com> - Mark D Baushke <mdb@cisco.com> - Jim Blandy <jimb@cyclic.com> - Tom Cunningham <tomc@bouwsma,sps.mot.com> - Graydon Dodson <grdodson@lexmark.com> - Joe Drumgoole <joed@splatter.demon.co.uk> - Don Dwiggins <dwig@markv.com> - Bryant Eastham <bryant@ced.utah.edu> - Dan Franklin <dan@diamond.bbn.com> - Michael Ganzberger <ganzbergermd@ES.net> - Steve Harris <vsh%etnibsd@uunet.uu.net> - Erik van Linstee <linstee@dutecaj.et.tudelft.nl> - Jeffrey M Loomis <jml@world.std.com> - Barry Margolin <barmar@near.net> - Mark K. Mellis <mkm@ncd.com> - Chris Moore <Chris.Moore@src.bae.co.uk> - Gary Oberbrunner <garyo@avs.com> - Steve Turner <stevet@carrier.sps.mot.com> - Dave Wolfe <dwolfe@pffft.sps.mot.com> - Dale Woolridge <dwoolridge@cid.aes.doe.ca> - - - - 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 When I typed "cvs update -D <date>", 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.4 When I typed "cvs update -D <date>" in my branch, why did it - screw up all my files? - 5B.5 When I executed "checkout" into an existing directory I got "No - such file or directory" errors. Why? - 5B.6 Why does "update" send all output to the terminal after 26 files - have been updated? - 5B.7 Why does the merge occasionally resurrect lines of code? - 5B.8 Why does the merge fail when my "rcsmerge" program is - configured to use GNU diff version 2.1 or later? - - - **** 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.8. - - - 5B.3 When I typed "cvs update -D <date>", 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 <date>: - - 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 <tag>, or even "-r HEAD" than to use a - date spec. - - If you must use "-D <date>", then you should either archive and - delete Attic files (losing some past history) or construct your - Makefiles to work with an explicit list of files and let the old - source files stay in the working directory. The contents of the - revision-controlled Makefile can then be considered to contain - deletion "information". - - - 5B.4 When I typed "cvs update -D <date>" 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. - - In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only - works with the Main Branch and the Vendor Branch. - - [[Is this fixed in CVS 1.4? This is one item I didn't check.]] - - - 5B.5 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.6 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.7 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. - - This is an old problem which you can avoid by upgrading to the - latest GNU "diffutils" package. If you were using GNU diff - version 1.15 and plan to upgrade to the latest GNU diff program, - see the next question. - - - 5B.8 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 that causes RCS versions before - 5.6.0.1 to fail during a merge. - - To get consistent rcsmerge behavior, you have four choices: - - 1. Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or - 5.6. 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. - - ----------------- --- Section 5C -- Development ----------------- - - - **** 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 new features? - 5C.5 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. - - - 5C.2 Where do I send fixes and patches? - - First make sure the "fix" does something useful. Have someone - review your fix. Spend a bit of one person's time in a detailed - analysis of your vast idea before displaying a half-vast idea to - hundreds of people. - - 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, produce a patch file using the - CVS commands "patch" or "diff -c". [[You *are* keeping CVS under - CVS, right?]] The patch should be based on the latest released - version of CVS. Then use the "cvsbug" program (provided with the - CVS sources) to send it to the CVS maintainers. A self-contained - patch that provides a single useful feature or correction might - show up independently in the patches directory of the FTP archive. - - If careful testing reveals an RCS bug rather than a CVS bug, you - can send bug reports to: rcs-bugs@cs.purdue.edu - - - 5C.3 Where do I send ideas for future development? - - If you have a bright idea, discuss it on the info-cvs mailing - list. If you have the time to implement something you can test, - send the diffs along too as described above. - - -=5C.4 What plans are there for new features? - - A "rename" or "per-directory" database has been bandied about on - the net for years. It is needed, but it is a lot of work. - - CVS version 1.5 supports remote repository access, but Paul - F. Kunz <Paul_Kunz@slac.stanford.edu> has produced another version - (rCVS) that also runs remotely. It is available for testing. - - On the host "preprint.slac.stanford.edu", you can find: - Paper: slacpubs/5000/slac-pub-5923.ps.Z - - This was for a conference in Sept, 1993, before first beta. - - On the host "ftp.slac.stanford.edu", you can find: - Sources: pub/sources/rcvs-0.8.1.tar.Z - - With the caveat that until version 1.0 is available, rCVS should - be considered an unreliable Beta release, you are invited to - grab a copy and test it. - - - [[Others?]] - - - 5C.5 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 5D -- Professional Support ----------------- - - - **** Questions: - -+5D.1 Doesn't Cygnus support CVS? -+5D.2 What is Cyclic Software doing with CVS? - - - **** Answers: - -+5D.1 Doesn't Cygnus support CVS? - - Cygnus is a company that supports a variety of FSF software. It - uses a version of CVS and people from Cygnus are on the info-cvs - mailing list. - - [[Could someone from Cygnus state Cygnus's official and unofficial - relationship with CVS?]] - - -+5D.2 What is Cyclic Software doing with CVS? - - Cyclic Software exists to provide support for CVS. Here's a copy - of their product line sheet: - - - Cyclic Software - Standard Support - - Cyclic Software offers support contracts for CVS. This - includes: - - * Full source, binaries, and documentation for CVS, RCS, GNU - diffutils, patch, and gzip -- that is, CVS and everything it - wants to run -- via FTP or tape; - - * guaranteed responses for bugs within 5 business days; - - * guaranteed fixes for reproducible bugs within 10 business days. - - (By "reproducible bugs", we mean instances where the software - clearly does not behave as documentation or reasonable - expectations indicate it should, and that we are able to - reproduce this misbehavior reliably. Naturally, we will make - every possible effort to reproduce the bugs you report; our - experience has been that it's usually not difficult.) - - We charge a fixed fee for: - - * one year - - * one host type (hardware & operating system) - - * twenty users at your site, with two of those users designated - as "contacts" for CVS, to reduce communication problems. - - If the host type is not one we have access to for testing - purposes, you can either lend us a machine of the appropriate type - for the duration of the contract, or pay an additional fee - up-front. We have access to Solaris, Irix, HP-UX, Linux and - Ultrix. (This list is subject to change; contact us for details.) - - If the above fee structure is not well-suited to your - organization, please say so. We're interested in tailoring our - services to be as useful to you as possible. - - Training - - We offer on-site training in the use of CVS at a daily rate, - plus expenses (inc. travel, accommodations). The classes target - new and intermediate users of CVS; we feel advanced users benefit - more from a written manual and the source code. - - Custom Enhancements - - We will implement enhancements to CVS or its documentation, and - port CVS to new architectures. Our rates for this work depend on - the amount of work to be done. - - We strongly prefer to work on enhancements suitable for - incorporation into the general CVS release upon completion; we - will help you design the enhancement in a way that makes this - possible. - - Short-Term Consulting - - We will do short-term consulting at hourly rates. These rates - are calculated to include the overhead of dealing in short time - periods. Therefore, in sufficiently large projects, we recommend - arranging a long-term support contract instead of dealing on an - hourly basis. - - Anything Else - - Cyclic Software is interested in arranging contracts for work - in other areas, to be produced as free software. Everything is - negotiable. - - How To Contact Us - - (Email is preferred.) - - Email: <info@cyclic.com> - Phone: +1 812 335 9023 - Web: http://www.cyclic.com - SnailMail: Cyclic Software - P.O. Box 804 - Bloomington, IN 47402-0804 - USA - - Contributed by Jim Blandy - - - -================================================= -== 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 and Merging - D. Tricks of the Trade - E. Internal errors - F. Related Software - G. Engineering - H. Other Systems - - 5. Past & Future - A. Contributors. - B. Bugs and Patches - C. Development - D. Professional Support - - 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? - ----------------- --- 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 files out of the archive if I don't have FTP? - 1B.4 How do I get a copy of the latest version of CVS? - 1B.5 Is there a mailing list devoted to CVS? How do I find it? - 1B.6 What happened to the CVS Usenet newsgroup I heard about? - ----------------- --- 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/SparcWorks? - 1C.5 How does CVS differ from Aegis? - 1C.6 How does CVS differ from Shapetools? - 1C.7 How does CVS differ from TeamNet? - 1C.8 How does CVS differ from ProFrame? - 1C.9 How does CVS differ from CaseWare/CM? - 1C.10 How does CVS differ from Sublime? - 1C.11 How does CVS differ from PVCS? - 1C.12 How does CVS differ from CMVC? - ----------------- --- 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 <module> directory that "checkout" created? - 2B.4 How do I find out what has changed since my last update? - 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 non-CVS 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 .#<file>.1.3 file in my working directory come from? - 2D.10 What is this "ignore" business? What is it ignoring? - 2D.11 Is there a way to set user-specific configuration options? - 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 new file end up in the Attic? - 3A.4 Now that it's in the Attic, how do I connect it to the Main branch? - 3A.5 How do I avoid the hassle of reconnecting an Attic-only file to - the Main Branch? - 3A.6 How do I cancel an "add"? - 3A.7 What are the ./CVS/file,p and ./CVS/file,t files for? - 3A.8 How do I "add" a binary file? - ----------------- --- 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 while I'm working on them 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 `<file>' - 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 <tag/rev>" put newly added files in the Attic? - 3D.8 Why would a "commit" of a newly added file not produce rev 1.1? - ----------------- --- 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 long options, like --unified, 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 doesn't "export" have a '-k' flag like "import" does? - 3F.5 Why does "export -D" check out every file in the Attic? - ----------------- --- Section 3G -- "history", "hi", "his" ----------------- - 3G.1 What is "history" for? - 3G.2 Of what use is it? - 3G.3 What is this, Big Brother? - 3G.4 I deleted my working directory and "history" still says I have - it checked out. How do I fix it? - 3G.5 So I *can* edit the History file? - 3G.6 Why does the history file grow so quickly? - 3G.7 What is the difference between "cvs history -r <tag/rev>" and - "cvs history -t <tag>"? - 3G.8 Why does "cvs history -c -t <tag>" fail to print anything? - 3G.9 "cvs history -a -o" only printed one line for each checked-out - module. Shouldn't it print all the directories where the - modules are checked out? - 3G.10 I can't figure out "history", can you give me concrete examples? - 3G.11 Can we merge history files when we merge Repositories? - ----------------- --- 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 I work on the - main trunk instead of a Vendor 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 retain the original $\Revision$ strings in the sources? -=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 can't I "import" 3 releases on different branches? - 3H.10 What do I do if the Vendor adds or deletes files between releases? - 3H.11 What about if the Vendor changes the names of files or - directories, or rearranges the whole structure between releases? - 3H.12 I thought "import" was for Vendor releases, why would I use it - for code of my own? Do I have to use import? - 3H.13 How do I import a large Vendor release? - 3H.14 Explain: ERROR: cannot create link to <file>: Permission denied - 3H.15 Where does the -m <message> go when the file doesn't change? - 3H.16 How do I "import" just the files ignored by a previous "import"? - 3H.17 Why did "import" ignore all the symlinks? - ----------------- --- 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 can't I reverse a "cvs checkout path/name/subdir" with a - "cvs release path/name/subdir" without an "unknown module name"? - 3K.3 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.4 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.5 Why doesn't "release -d module" reverse a "checkout module"? - 3K.6 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 an - error message and tells me to remove the file by hand. - ----------------- --- Section 3M -- "rtag", "rt", "rfreeze" ----------------- - 3M.1 What is "rtag" for? - 3M.2 Why use "rtag"? It assumes no one is changing the Repository. - 3M.3 What revision does "rtag -r <tag1> <tag2>" actually put the tag on? - 3M.4 What happens if the tags are the same in "rtag -r <tag> <tag>"? - 3M.5 Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or - duplicate a magic branch tag? - ----------------- --- 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 Why does it print "Sticky" lines when the values are "(none)"? - 3N.4 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 "{r}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 <tag>" in my working directory, why doesn't "checkout - -r <tag>" somewhere else produce copies of my current files? - 3O.8 Why doesn't "tag" write a history record the way "rtag" does? - 3O.9 How do I rename a <tag>? - ----------------- --- 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 What's a "sticky conflict"? How does it know a conflict occurred? - 3P.7 Is there a feature to tell me what I have changed, added and - removed without changing anything? - 3P.8 Why were all my files deleted when I executed "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 work around the merge problems in GNU diff version 2.1 - or later? - ----------------- --- 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 Why would anyone use "modules"? They are too restrictive. I - want to be able to select just the files I want to edit. - 4B.8 How do I rename a file or directory? What are the consequences? - 4B.9 What are "Attic" directories? - 4B.10 Is it OK to remove anything from the Repository? - 4B.11 Can I convert to CVS from RCS without losing my revision history? - 4B.12 Can I move RCS files with branches in them into the Repository? - 4B.13 Can I use raw RCS commands on the Repository? - 4B.14 How do I convert from SCCS to RCS? - 4B.15 How do I limit access to the Repository? - 4B.16 What are the Repository Administrator's responsibilities? - 4B.17 How do I move the whole Repository? - 4B.18 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 and Merging ----------------- - 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 merge onto the Main Branch a file that exists only on a - branch other than the Main Branch? (i.e. it is in the Attic) - 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 Once I've found the files I want, how do I start changing them? - I keep getting warnings about sticky tags. - 4C.18 Why do I get the latest files on the branch when I tried to - "update -r <tag>"? - 4C.19 How can I avoid a merge? I just want to move the latest revision - on my working branch directly onto the trunk. - 4C.20 How to I avoid merge collisions in the RCS $\Log$ data? - 4C.21 Why should I trust automatic merges? - 4C.22 How does CVS decide if it can safely perform a merge? - 4C.23 After resolving merge conflicts in a file, what if I want to keep - my previous version, and not take any of the branch changes? - ----------------- --- 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 or rename 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 Where did the ./CVS/Entries.Static file come from? What is it for? - 4D.11 Why did I get the wrong Repository in the loginfo message? - 4D.12 How do I run CVS setuid so I can only allow access through the - CVS program itself? - 4D.13 How about using groups and setgid() then? - 4D.14 How do I use the "commitinfo" file? - 4D.15 How do I use the "loginfo" files? - 4D.16 How can I keep people with restrictive umask values from blocking - access to the Repository? - 4D.17 Why do timestamps sometimes get set to the date of the revision, - sometimes not? The inconsistency causes unnecessary recompiles. - ----------------- --- Section 4E -- Internal errors ----------------- - 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 Explain: "co error, line 2: Missing access list" - 4E.4 Explain: "error: RCS file name `xyz .c' contains white space" - 4E.5 Explain: cvs checkout: warning: <X> is not (any longer) pertinent - 4E.6 Why did a Repository file change from <file>,v to ,<file>,? - ----------------- --- Section 4F -- Related Software ----------------- - 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? - ----------------- --- Section 4G -- Engineering ----------------- - 4G.1 Where can I find out about Software Engineering? - 4G.2 How do I flexibly arrange the modules file to describe my sources? - 4G.3 Can I have multiple source repositories, one for each project? - 4G.4 Who should administer the Repository and manage the modules file? - 4G.5 Isn't disk space a big factor? CVS copies files out of the - Repository, duplicating everything. - ----------------- --- Section 4H -- Other Systems ----------------- - 4H.1 I use a NeXT. Is there anything I need to know? - 4H.2 I use OS/2 and/or DOS. Is there anything I need to know? - 4H.3 I use SCO Unix. Is there anything I need to know? - 4H.4 I use AIX. Is there anything I need to know? - 4H.5 I use IRIX. Is there anything I need to know? - 4H.6 I use an HP system. Is there anything I need to know? - 4H.7 I use AFS. Is there anything I need to know? - 4H.8 I use A/UX. 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 When I typed "cvs update -D <date>", 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.4 When I typed "cvs update -D <date>" in my branch, why did it - screw up all my files? - 5B.5 When I executed "checkout" into an existing directory I got "No - such file or directory" errors. Why? - 5B.6 Why does "update" send all output to the terminal after 26 files - have been updated? - 5B.7 Why does the merge occasionally resurrect lines of code? - 5B.8 Why does the merge fail when my "rcsmerge" program is - configured to use GNU diff version 2.1 or later? - ----------------- --- 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 new features? - 5C.5 I have some time and I'd like to help. What can I do for you? - ----------------- --- Section 5D -- Professional Support ----------------- -+5D.1 Doesn't Cygnus support CVS? -+5D.2 What is Cyclic Software doing with CVS? - - -================================================= -== 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: |
