diff options
Diffstat (limited to 'contrib/cvs/doc/cvs.texinfo')
| -rw-r--r-- | contrib/cvs/doc/cvs.texinfo | 14892 |
1 files changed, 0 insertions, 14892 deletions
diff --git a/contrib/cvs/doc/cvs.texinfo b/contrib/cvs/doc/cvs.texinfo deleted file mode 100644 index 6b1840a..0000000 --- a/contrib/cvs/doc/cvs.texinfo +++ /dev/null @@ -1,14892 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment Documentation for CVS. -@setfilename cvs.info -@macro copyleftnotice -@noindent -Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, - 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 - Free Software Foundation, Inc. - -@multitable @columnfractions .12 .88 -@item Portions -@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, - 2006, 2007 Derek R. Price, -@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 - Ximbiot @url{http://ximbiot.com}, -@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, -@item @tab and Copyright @copyright{} others. -@end multitable - -@ignore -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Free Software Foundation. -@end macro - -@comment This file is part of the CVS distribution. - -@comment CVS is free software; you can redistribute it and/or modify -@comment it under the terms of the GNU General Public License as published by -@comment the Free Software Foundation; either version 2, or (at your option) -@comment any later version. - -@comment CVS is distributed in the hope that it will be useful, -@comment but WITHOUT ANY WARRANTY; without even the implied warranty of -@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -@comment GNU General Public License for more details. - -@c See ../README for A4 vs. US letter size. -@c When we provided A4 postscript, and people tried to -@c print it on US letter, the usual complaint was that the -@c page numbers would get cut off. -@c If one prints US letter on A4, reportedly there is -@c some extra space at the top and/or bottom, and the side -@c margins are a bit narrow, but no text is lost. -@c -@c See -@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html -@c for more on paper sizes. Insuring that margins are -@c big enough to print on either A4 or US letter does -@c indeed seem to be the usual approach (RFC2346). - -@c This document seems to get overfull hboxes with some -@c frequency (probably because the tendency is to -@c sanity-check it with "make info" and run TeX less -@c often). The big ugly boxes just seem to add insult -@c to injury, and I'm not aware of them helping to fix -@c the overfull hboxes at all. -@finalout - -@include version.texi -@settitle CVS---Concurrent Versions System v@value{VERSION} -@setchapternewpage odd - -@c -- TODO list: -@c -- Fix all lines that match "^@c -- " -@c -- Also places marked with FIXME should be manual -@c problems (as opposed to FIXCVS for CVS problems). - -@c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by -@c @asis when generating info and dvi, and by <i></i> in the generated html, -@c such that keywords are not expanded in the generated html. -@ifnothtml -@macro splitrcskeyword {arg} -@asis{}\arg\ -@end macro -@end ifnothtml - -@ifhtml -@macro splitrcskeyword {arg} -@i{}\arg\ -@end macro -@end ifhtml - -@dircategory GNU Packages -@direntry -* CVS: (cvs). Concurrent Versions System -@end direntry -@dircategory Individual utilities -@direntry -* cvs: (cvs)CVS commands. Concurrent Versions System -@end direntry - -@comment The titlepage section does not appear in the Info file. -@titlepage -@sp 4 -@comment The title is printed in a large font. -@center @titlefont{Version Management} -@sp -@center @titlefont{with} -@sp -@center @titlefont{CVS} -@sp 2 -@center for @sc{cvs} @value{VERSION} -@comment -release- -@sp 3 -@center Per Cederqvist et al - -@comment The following two commands start the copyright page -@comment for the printed manual. This will not appear in the Info file. -@page -@vskip 0pt plus 1filll -@copyleftnotice -@end titlepage - -@summarycontents - -@contents - -@comment ================================================================ -@comment The real text starts here -@comment ================================================================ - -@ifnottex -@c --------------------------------------------------------------------- -@node Top -@top - -This info manual describes how to use and administer -@sc{cvs} version @value{VERSION}. -@end ifnottex - -@ifinfo -@copyleftnotice -@end ifinfo - -@c This menu is pretty long. Not sure how easily that -@c can be fixed (no brilliant ideas right away)... -@menu -* Overview:: An introduction to CVS -* Repository:: Where all your sources are stored -* Starting a new project:: Starting a project with CVS -* Revisions:: Numeric and symbolic names for revisions -* Branching and merging:: Diverging/rejoining branches of development -* Recursive behavior:: CVS descends directories -* Adding and removing:: Adding/removing/renaming files/directories -* History browsing:: Viewing the history of files in various ways - -CVS and the Real World. ------------------------ -* Binary files:: CVS can handle binary files -* Multiple developers:: How CVS helps a group of developers -* Revision management:: Policy questions for revision management -* Keyword substitution:: CVS can include the revision inside the file -* Tracking sources:: Tracking third-party sources -* Builds:: Issues related to CVS and builds -* Special Files:: Devices, links and other non-regular files - -References. ------------ -* CVS commands:: CVS commands share some things -* Invoking CVS:: Quick reference to CVS commands -* Administrative files:: Reference manual for the Administrative files -* Environment variables:: All environment variables which affect CVS -* Compatibility:: Upgrading CVS versions -* Troubleshooting:: Some tips when nothing works -* Credits:: Some of the contributors to this manual -* BUGS:: Dealing with bugs in CVS or this manual -* Index:: Index -@end menu - -@c --------------------------------------------------------------------- -@node Overview -@chapter Overview -@cindex Overview - -This chapter is for people who have never used -@sc{cvs}, and perhaps have never used version control -software before. - -If you are already familiar with @sc{cvs} and are just -trying to learn a particular feature or remember a -certain command, you can probably skip everything here. - -@menu -* What is CVS?:: What you can do with @sc{cvs} -* What is CVS not?:: Problems @sc{cvs} doesn't try to solve -* A sample session:: A tour of basic @sc{cvs} usage -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node What is CVS? -@section What is CVS? -@cindex What is CVS? -@cindex Introduction to CVS -@cindex CVS, introduction to - -@sc{cvs} is a version control system. Using it, you can -record the history of your source files. - -@c -- /// -@c -- ///Those who cannot remember the past are condemned to repeat it. -@c -- /// -- George Santayana -@c -- ////// - -@c -- Insert history quote here! -For example, bugs sometimes creep in when -software is modified, and you might not detect the bug -until a long time after you make the modification. -With @sc{cvs}, you can easily retrieve old versions to see -exactly which change caused the bug. This can -sometimes be a big help. - -You could of course save every version of every file -you have ever created. This would -however waste an enormous amount of disk space. @sc{cvs} -stores all the versions of a file in a single file in a -clever way that only stores the differences between -versions. - -@sc{cvs} also helps you if you are part of a group of people working -on the same project. It is all too easy to overwrite -each others' changes unless you are extremely careful. -Some editors, like @sc{gnu} Emacs, try to make sure that -two people never modify the same file at the -same time. Unfortunately, if someone is using another -editor, that safeguard will not work. @sc{cvs} solves this problem -by insulating the different developers from each other. Every -developer works in his own directory, and @sc{cvs} merges -the work when each developer is done. - -@cindex History of CVS -@cindex CVS, history of -@cindex Credits (CVS program) -@cindex Contributors (CVS program) -@sc{cvs} started out as a bunch of shell scripts written by -Dick Grune, posted to the newsgroup -@code{comp.sources.unix} in the volume 6 -release of July, 1986. While no actual code from -these shell scripts is present in the current version -of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms -come from them. - -In April, 1989, Brian Berliner designed and coded @sc{cvs}. -Jeff Polk later helped Brian with the design of the @sc{cvs} -module and vendor branch support. - -@cindex Source, getting CVS source -You can get @sc{cvs} in a variety of ways, including -free download from the Internet. For more information -on downloading @sc{cvs} and other @sc{cvs} topics, see: - -@example -@url{http://cvs.nongnu.org/} -@end example - -@cindex Mailing list -@cindex List, mailing list -@cindex Newsgroups -There is a mailing list, known as @email{info-cvs@@nongnu.org}, -devoted to @sc{cvs}. To subscribe or -unsubscribe -write to -@email{info-cvs-request@@nongnu.org}. -If you prefer a Usenet group, there is a one-way mirror (posts to the email -list are usually sent to the news group, but not vice versa) of -@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}. The right -Usenet group for posts is @url{news:comp.software.config-mgmt} which is for -@sc{cvs} discussions (along with other configuration -management systems). In the future, it might be -possible to create a -@code{comp.software.config-mgmt.cvs}, but probably only -if there is sufficient @sc{cvs} traffic on -@url{news:comp.software.config-mgmt}. -@c Other random data is that the tale was very -@c skeptical of comp.software.config-mgmt.cvs when the -@c subject came up around 1995 or so (for one -@c thing, because creating it would be a "reorg" which -@c would need to take a more comprehensive look at the -@c whole comp.software.config-mgmt.* hierarchy). - -You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list, -described in more detail in @ref{BUGS}. To subscribe -send mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way -Usenet mirror (posts to the Usenet group are usually sent to the email list and -vice versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node What is CVS not? -@section What is CVS not? -@cindex What is CVS not? - -@sc{cvs} can do a lot of things for you, but it does -not try to be everything for everyone. - -@table @asis -@item @sc{cvs} is not a build system. - -Though the structure of your repository and modules -file interact with your build system -(e.g. @file{Makefile}s), they are essentially -independent. - -@sc{cvs} does not dictate how you build anything. It -merely stores files for retrieval in a tree structure -you devise. - -@sc{cvs} does not dictate how to use disk space in the -checked out working directories. If you write your -@file{Makefile}s or scripts in every directory so they -have to know the relative positions of everything else, -you wind up requiring the entire repository to be -checked out. - -If you modularize your work, and construct a build -system that will share files (via links, mounts, -@code{VPATH} in @file{Makefile}s, etc.), you can -arrange your disk usage however you like. - -But you have to remember that @emph{any} such system is -a lot of work to construct and maintain. @sc{cvs} does -not address the issues involved. - -Of course, you should place the tools created to -support such a build system (scripts, @file{Makefile}s, -etc.) under @sc{cvs}. - -Figuring out what files need to be rebuilt when -something changes is, again, something to be handled -outside the scope of @sc{cvs}. One traditional -approach is to use @code{make} for building, and use -some automated tool for generating the dependencies which -@code{make} uses. - -See @ref{Builds}, for more information on doing builds -in conjunction with @sc{cvs}. - -@item @sc{cvs} is not a substitute for management. - -Your managers and project leaders are expected to talk -to you frequently enough to make certain you are aware -of schedules, merge points, branch names and release -dates. If they don't, @sc{cvs} can't help. - -@sc{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. - -@item @sc{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. - -@sc{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 @dfn{conflict} is purely textual, arising -when two changes to the same base file are near enough -to spook the merge (i.e., @code{diff3}) command. - -@sc{cvs} does not claim to help at all in figuring out -non-textual or distributed conflicts in program logic. - -For example: Say you change the arguments to function -@code{X} defined in file @file{A}. At the same time, -someone edits file @file{B}, adding new calls to -function @code{X} using the old arguments. You are -outside the realm of @sc{cvs}'s competence. - -Acquire the habit of reading specs and talking to your -peers. - - -@item @sc{cvs} does not have change control - -Change control refers to a number of things. First of -all it can mean @dfn{bug-tracking}, that is being able -to keep a database of reported bugs and the status of -each one (Is it fixed? In what release? Has the bug -submitter agreed that it is fixed?). For interfacing -@sc{cvs} to an external bug-tracking system, see the -@file{rcsinfo} and @file{verifymsg} files -(@pxref{Administrative files}). - -Another aspect of change control is keeping track of -the fact that changes to several files were in fact -changed together as one logical change. If you check -in several files in a single @code{cvs commit} -operation, @sc{cvs} then forgets that those files were -checked in together, and the fact that they have the -same log message is the only thing tying them -together. Keeping a @sc{gnu} style @file{ChangeLog} -can help somewhat. -@c FIXME: should have an xref to a section which talks -@c more about keeping ChangeLog's with CVS, but that -@c section hasn't been written yet. - -Another aspect of change control, in some systems, is -the ability to keep track of the status of each -change. Some changes have been written by a developer, -others have been reviewed by a second developer, and so -on. Generally, the way to do this with @sc{cvs} is to -generate a diff (using @code{cvs diff} or @code{diff}) -and email it to someone who can then apply it using the -@code{patch} utility. This is very flexible, but -depends on mechanisms outside @sc{cvs} to make sure -nothing falls through the cracks. - -@item @sc{cvs} is not an automated testing program - -It should be possible to enforce mandatory use of a -test suite using the @code{commitinfo} file. I haven't -heard a lot about projects trying to do that or whether -there are subtle gotchas, however. - -@item @sc{cvs} does not have a built-in process model - -Some systems provide ways to ensure that changes or -releases go through various steps, with various -approvals as needed. Generally, one can accomplish -this with @sc{cvs} but it might be a little more work. -In some cases you'll want to use the @file{commitinfo}, -@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} -files, to require that certain steps be performed -before cvs will allow a checkin. Also consider whether -features such as branches and tags can be used to -perform tasks such as doing work in a development tree -and then merging certain changes over to a stable tree -only once they have been proven. -@end table - -@c --------------------------------------------------------------------- -@node A sample session -@section A sample session -@cindex Example of a work-session -@cindex Getting started -@cindex Work-session, example of -@cindex tc, Trivial Compiler (example) -@cindex Trivial Compiler (example) - -@c I think an example is a pretty good way to start. But -@c somewhere in here, maybe after the sample session, -@c we need something which is kind of -@c a "roadmap" which is more directed at sketching out -@c the functionality of CVS and pointing people to -@c various other parts of the manual. As it stands now -@c people who read in order get dumped right into all -@c manner of hair regarding remote repositories, -@c creating a repository, etc. -@c -@c The following was in the old Basic concepts node. I don't -@c know how good a job it does at introducing modules, -@c or whether they need to be introduced so soon, but -@c something of this sort might go into some -@c introductory material somewhere. -@ignore -@cindex Modules (intro) -The repository contains directories and files, in an -arbitrary tree. The @dfn{modules} feature can be used -to group together a set of directories or files into a -single entity (@pxref{modules}). A typical usage is to -define one module per project. -@end ignore - -As a way of introducing @sc{cvs}, we'll go through a -typical work-session using @sc{cvs}. The first thing -to understand is that @sc{cvs} stores all files in a -centralized @dfn{repository} (@pxref{Repository}); this -section assumes that a repository is set up. -@c I'm not sure that the sentence concerning the -@c repository quite tells the user what they need to -@c know at this point. Might need to expand on "centralized" -@c slightly (maybe not here, maybe further down in the example?) - -Suppose you are working on a simple compiler. The source -consists of a handful of C files and a @file{Makefile}. -The compiler is called @samp{tc} (Trivial Compiler), -and the repository is set up so that there is a module -called @samp{tc}. - -@menu -* Getting the source:: Creating a workspace -* Committing your changes:: Making your work available to others -* Cleaning up:: Cleaning up -* Viewing differences:: Viewing differences -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Getting the source -@subsection Getting the source -@cindex Getting the source -@cindex Checking out source -@cindex Fetching source -@cindex Source, getting from CVS -@cindex Checkout, example - -The first thing you must do is to get your own working copy of the -source for @samp{tc}. For this, you use the @code{checkout} command: - -@example -$ cvs checkout tc -@end example - -@noindent -This will create a new directory called @file{tc} and populate it with -the source files. - -@example -$ cd tc -$ ls -CVS Makefile backend.c driver.c frontend.c parser.c -@end example - -The @file{CVS} directory is used internally by -@sc{cvs}. Normally, you should not modify or remove -any of the files in it. - -You start your favorite editor, hack away at @file{backend.c}, and a couple -of hours later you have added an optimization pass to the compiler. -A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that -you want to edit. @xref{Multiple developers}, for an explanation. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Committing your changes -@subsection Committing your changes -@cindex Committing changes to files -@cindex Log message entry - -When you have checked that the compiler is still compilable you decide -to make a new version of @file{backend.c}. This will -store your new @file{backend.c} in the repository and -make it available to anyone else who is using that same -repository. - -@example -$ cvs commit backend.c -@end example - -@noindent -@sc{cvs} starts an editor, to allow you to enter a log -message. You type in ``Added an optimization pass.'', -save the temporary file, and exit the editor. - -@cindex CVSEDITOR, environment variable -@cindex EDITOR, environment variable -The environment variable @code{$CVSEDITOR} determines -which editor is started. If @code{$CVSEDITOR} is not -set, then if the environment variable @code{$EDITOR} is -set, it will be used. If both @code{$CVSEDITOR} and -@code{$EDITOR} are not set then there is a default -which will vary with your operating system, for example -@code{vi} for unix or @code{notepad} for Windows -NT/95. - -@cindex VISUAL, environment variable -In addition, @sc{cvs} checks the @code{$VISUAL} environment -variable. Opinions vary on whether this behavior is desirable and -whether future releases of @sc{cvs} should check @code{$VISUAL} or -ignore it. You will be OK either way if you make sure that -@code{$VISUAL} is either unset or set to the same thing as -@code{$EDITOR}. - -@c This probably should go into some new node -@c containing detailed info on the editor, rather than -@c the intro. In fact, perhaps some of the stuff with -@c CVSEDITOR and -m and so on should too. -When @sc{cvs} starts the editor, it includes a list of -files which are modified. For the @sc{cvs} client, -this list is based on comparing the modification time -of the file against the modification time that the file -had when it was last gotten or updated. Therefore, if -a file's modification time has changed but its contents -have not, it will show up as modified. The simplest -way to handle this is simply not to worry about it---if -you proceed with the commit @sc{cvs} will detect that -the contents are not modified and treat it as an -unmodified file. The next @code{update} will clue -@sc{cvs} in to the fact that the file is unmodified, -and it will reset its stored timestamp so that the file -will not show up in future editor sessions. -@c FIXCVS: Might be nice if "commit" and other commands -@c would reset that timestamp too, but currently commit -@c doesn't. -@c FIXME: Need to talk more about the process of -@c prompting for the log message. Like show an example -@c of what it pops up in the editor, for example. Also -@c a discussion of how to get the "a)bort, c)ontinue, -@c e)dit" prompt and what to do with it. Might also -@c work in the suggestion that if you want a diff, you -@c should make it before running commit (someone -@c suggested that the diff pop up in the editor. I'm -@c not sure that is better than telling people to run -@c "cvs diff" first if that is what they want, but if -@c we want to tell people that, the manual possibly -@c should say it). - -If you want to avoid -starting an editor you can specify the log message on -the command line using the @samp{-m} flag instead, like -this: - -@example -$ cvs commit -m "Added an optimization pass" backend.c -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Cleaning up -@subsection Cleaning up -@cindex Cleaning up -@cindex Working copy, removing -@cindex Removing your working copy -@cindex Releasing your working copy - -Before you turn to other tasks you decide to remove your working copy of -tc. One acceptable way to do that is of course - -@example -$ cd .. -$ rm -r tc -@end example - -@noindent -but a better way is to use the @code{release} command (@pxref{release}): - -@example -$ cd .. -$ cvs release -d tc -M driver.c -? tc -You have [1] altered files in this repository. -Are you sure you want to release (and delete) directory `tc': n -** `release' aborted by user choice. -@end example - -The @code{release} command checks that all your modifications have been -committed. If history logging is enabled it also makes a note in the -history file. @xref{history file}. - -When you use the @samp{-d} flag with @code{release}, it -also removes your working copy. - -In the example above, the @code{release} command wrote a couple of lines -of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. -That is nothing to worry about: @file{tc} is the executable compiler, -and it should not be stored in the repository. @xref{cvsignore}, -for information about how to make that warning go away. -@xref{release output}, for a complete explanation of -all possible output from @code{release}. - -@samp{M driver.c} is more serious. It means that the -file @file{driver.c} has been modified since it was -checked out. - -The @code{release} command always finishes by telling -you how many modified files you have in your working -copy of the sources, and then asks you for confirmation -before deleting any files or making any note in the -history file. - -You decide to play it safe and answer @kbd{n @key{RET}} -when @code{release} asks for confirmation. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Viewing differences -@subsection Viewing differences -@cindex Viewing differences -@cindex Diff - -You do not remember modifying @file{driver.c}, so you want to see what -has happened to that file. - -@example -$ cd tc -$ cvs diff driver.c -@end example - -This command runs @code{diff} to compare the version of @file{driver.c} -that you checked out with your working copy. When you see the output -you remember that you added a command line option that enabled the -optimization pass. You check it in, and release the module. -@c FIXME: we haven't yet defined the term "check in". - -@example -$ cvs commit -m "Added an optimization pass" driver.c -Checking in driver.c; -/usr/local/cvsroot/tc/driver.c,v <-- driver.c -new revision: 1.2; previous revision: 1.1 -done -$ cd .. -$ cvs release -d tc -? tc -You have [0] altered files in this repository. -Are you sure you want to release (and delete) directory `tc': y -@end example - -@c --------------------------------------------------------------------- -@node Repository -@chapter The Repository -@cindex Repository (intro) -@cindex Repository, example -@cindex Layout of repository -@cindex Typical repository -@cindex /usr/local/cvsroot, as example repository -@cindex cvsroot - -The @sc{cvs} @dfn{repository} stores a complete copy of -all the files and directories which are under version -control. - -Normally, you never access any of the files in the -repository directly. Instead, you use @sc{cvs} -commands to get your own copy of the files into a -@dfn{working directory}, and then -work on that copy. When you've finished a set of -changes, you check (or @dfn{commit}) them back into the -repository. The repository then contains the changes -which you have made, as well as recording exactly what -you changed, when you changed it, and other such -information. Note that the repository is not a -subdirectory of the working directory, or vice versa; -they should be in separate locations. -@c Need some example, e.g. repository -@c /usr/local/cvsroot; working directory -@c /home/joe/sources. But this node is too long -@c as it is; need a little reorganization... - -@cindex :local:, setting up -@sc{cvs} can access a repository by a variety of -means. It might be on the local computer, or it might -be on a computer across the room or across the world. -To distinguish various ways to access a repository, the -repository name can start with an @dfn{access method}. -For example, the access method @code{:local:} means to -access a repository directory, so the repository -@code{:local:/usr/local/cvsroot} means that the -repository is in @file{/usr/local/cvsroot} on the -computer running @sc{cvs}. For information on other -access methods, see @ref{Remote repositories}. - -@c Can se say this more concisely? Like by passing -@c more of the buck to the Remote repositories node? -If the access method is omitted, then if the repository -starts with @samp{/}, then @code{:local:} is -assumed. If it does not start with @samp{/} then either -@code{:ext:} or @code{:server:} is assumed. For -example, if you have a local repository in -@file{/usr/local/cvsroot}, you can use -@code{/usr/local/cvsroot} instead of -@code{:local:/usr/local/cvsroot}. But if (under -Windows NT, for example) your local repository is -@file{c:\src\cvsroot}, then you must specify the access -method, as in @code{:local:c:/src/cvsroot}. - -@c This might appear to go in Repository storage, but -@c actually it is describing something which is quite -@c user-visible, when you do a "cvs co CVSROOT". This -@c isn't necessary the perfect place for that, though. -The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains -administrative files for @sc{cvs}. The other directories contain the actual -user-defined modules. - -@menu -* Specifying a repository:: Telling CVS where your repository is -* Repository storage:: The structure of the repository -* Working directory storage:: The structure of working directories -* Intro administrative files:: Defining modules -* Multiple repositories:: Multiple repositories -* Creating a repository:: Creating a repository -* Backing up:: Backing up a repository -* Moving a repository:: Moving a repository -* Remote repositories:: Accessing repositories on remote machines -* Read-only access:: Granting read-only access to the repository -* Server temporary directory:: The server creates temporary directories -@end menu - -@node Specifying a repository -@section Telling CVS where your repository is - -There are several ways to tell @sc{cvs} -where to find the repository. You can name the -repository on the command line explicitly, with the -@code{-d} (for "directory") option: - -@example -cvs -d /usr/local/cvsroot checkout yoyodyne/tc -@end example - -@cindex .profile, setting CVSROOT in -@cindex .cshrc, setting CVSROOT in -@cindex .tcshrc, setting CVSROOT in -@cindex .bashrc, setting CVSROOT in -@cindex CVSROOT, environment variable - Or you can set the @code{$CVSROOT} environment -variable to an absolute path to the root of the -repository, @file{/usr/local/cvsroot} in this example. -To set @code{$CVSROOT}, @code{csh} and @code{tcsh} -users should have this line in their @file{.cshrc} or -@file{.tcshrc} files: - -@example -setenv CVSROOT /usr/local/cvsroot -@end example - -@noindent -@code{sh} and @code{bash} users should instead have these lines in their -@file{.profile} or @file{.bashrc}: - -@example -CVSROOT=/usr/local/cvsroot -export CVSROOT -@end example - -@cindex Root file, in CVS directory -@cindex CVS/Root file - A repository specified with @code{-d} will -override the @code{$CVSROOT} environment variable. -Once you've checked a working copy out from the -repository, it will remember where its repository is -(the information is recorded in the -@file{CVS/Root} file in the working copy). - -The @code{-d} option and the @file{CVS/Root} file both -override the @code{$CVSROOT} environment variable. If -@code{-d} option differs from @file{CVS/Root}, the -former is used. Of course, for proper operation they -should be two ways of referring to the same repository. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Repository storage -@section How data is stored in the repository -@cindex Repository, how data is stored - -For most purposes it isn't important @emph{how} -@sc{cvs} stores information in the repository. In -fact, the format has changed in the past, and is likely -to change in the future. Since in almost all cases one -accesses the repository via @sc{cvs} commands, such -changes need not be disruptive. - -However, in some cases it may be necessary to -understand how @sc{cvs} stores data in the repository, -for example you might need to track down @sc{cvs} locks -(@pxref{Concurrency}) or you might need to deal with -the file permissions appropriate for the repository. - -@menu -* Repository files:: What files are stored in the repository -* File permissions:: File permissions -* Windows permissions:: Issues specific to Windows -* Attic:: Some files are stored in the Attic -* CVS in repository:: Additional information in CVS directory -* Locks:: CVS locks control concurrent accesses -* CVSROOT storage:: A few things about CVSROOT are different -@end menu - -@node Repository files -@subsection Where files are stored within the repository - -@c @cindex Filenames, legal -@c @cindex Legal filenames -@c Somewhere we need to say something about legitimate -@c characters in filenames in working directory and -@c repository. Not "/" (not even on non-unix). And -@c here is a specific set of issues: -@c Files starting with a - are handled inconsistently. They can not -@c be added to a repository with an add command, because it they are -@c interpreted as a switch. They can appear in a repository if they are -@c part of a tree that is imported. They can not be removed from the tree -@c once they are there. -@c Note that "--" *is* supported (as a -@c consequence of using GNU getopt). Should document -@c this somewhere ("Common options"?). The other usual technique, -@c "./-foo", isn't as effective, at least for "cvs add" -@c which doesn't support pathnames containing "/". - -The overall structure of the repository is a directory -tree corresponding to the directories in the working -directory. For example, supposing the repository is in - -@example -/usr/local/cvsroot -@end example - -@noindent -here is a possible directory tree (showing only the -directories): - -@example -@t{/usr} - | - +--@t{local} - | | - | +--@t{cvsroot} - | | | - | | +--@t{CVSROOT} - | (administrative files) - | - +--@t{gnu} - | | - | +--@t{diff} - | | (source code to @sc{gnu} diff) - | | - | +--@t{rcs} - | | (source code to @sc{rcs}) - | | - | +--@t{cvs} - | (source code to @sc{cvs}) - | - +--@t{yoyodyne} - | - +--@t{tc} - | | - | +--@t{man} - | | - | +--@t{testing} - | - +--(other Yoyodyne software) -@end example - -With the directories are @dfn{history files} for each file -under version control. The name of the history file is -the name of the corresponding file with @samp{,v} -appended to the end. Here is what the repository for -the @file{yoyodyne/tc} directory might look like: -@c FIXME: Should also mention CVS (CVSREP) -@c FIXME? Should we introduce Attic with an xref to -@c Attic? Not sure whether that is a good idea or not. -@example - @code{$CVSROOT} - | - +--@t{yoyodyne} - | | - | +--@t{tc} - | | | - +--@t{Makefile,v} - +--@t{backend.c,v} - +--@t{driver.c,v} - +--@t{frontend.c,v} - +--@t{parser.c,v} - +--@t{man} - | | - | +--@t{tc.1,v} - | - +--@t{testing} - | - +--@t{testpgm.t,v} - +--@t{test2.t,v} -@end example - -@cindex History files -@cindex RCS history files -@c The first sentence, about what history files -@c contain, is kind of redundant with our intro to what the -@c repository does in node Repository.... -The history files contain, among other things, enough -information to recreate any revision of the file, a log -of all commit messages and the user-name of the person -who committed the revision. The history files are -known as @dfn{RCS files}, because the first program to -store files in that format was a version control system -known as @sc{rcs}. For a full -description of the file format, see the @code{man} page -@cite{rcsfile(5)}, distributed with @sc{rcs}, or the -file @file{doc/RCSFILES} in the @sc{cvs} source -distribution. This -file format has become very common---many systems other -than @sc{cvs} or @sc{rcs} can at least import history -files in this format. -@c FIXME: Think about including documentation for this -@c rather than citing it? In the long run, getting -@c this to be a standard (not sure if we can cope with -@c a standards process as formal as IEEE/ANSI/ISO/etc, -@c though...) is the way to go, so maybe citing is -@c better. - -The @sc{rcs} files used in @sc{cvs} differ in a few -ways from the standard format. The biggest difference -is magic branches; for more information see @ref{Magic -branch numbers}. Also in @sc{cvs} the valid tag names -are a subset of what @sc{rcs} accepts; for @sc{cvs}'s -rules see @ref{Tags}. - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node File permissions -@subsection File permissions -@c -- Move this to @node Creating a repository or similar -@cindex Security, file permissions in repository -@cindex File permissions, general -@cindex Permissions, general -@c FIXME: we need to somehow reflect "permissions in -@c repository" versus "permissions in working -@c directory" in the index entries. -@cindex Group, UNIX file permissions, in repository -@cindex Read-only files, in repository -All @samp{,v} files are created read-only, and you -should not change the permission of those files. The -directories inside the repository should be writable by -the persons that have permission to modify the files in -each directory. This normally means that you must -create a UNIX group (see group(5)) consisting of the -persons that are to edit the files in a project, and -set up the repository so that it is that group that -owns the directory. -(On some systems, you also need to set the set-group-ID-on-execution bit -on the repository directories (see chmod(1)) so that newly-created files -and directories get the group-ID of the parent directory rather than -that of the current process.) - -@c See also comment in commitinfo node regarding cases -@c which are really awkward with unix groups. - -This means that you can only control access to files on -a per-directory basis. - -Note that users must also have write access to check -out files, because @sc{cvs} needs to create lock files -(@pxref{Concurrency}). You can use LockDir in CVSROOT/config -to put the lock files somewhere other than in the repository -if you want to allow read-only access to some directories -(@pxref{config}). - -@c CVS seems to use CVSUMASK in picking permissions for -@c val-tags, but maybe we should say more about this. -@c Like val-tags gets created by someone who doesn't -@c have CVSUMASK set right? -@cindex CVSROOT/val-tags file, and read-only access to projects -@cindex val-tags file, and read-only access to projects -Also note that users must have write access to the -@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep -track of what tags are valid tag names (it is sometimes -updated when tags are used, as well as when they are -created). - -Each @sc{rcs} file will be owned by the user who last -checked it in. This has little significance; what -really matters is who owns the directories. - -@cindex CVSUMASK, environment variable -@cindex Umask, for repository files -@sc{cvs} tries to set up reasonable file permissions -for new directories that are added inside the tree, but -you must fix the permissions manually when a new -directory should have different permissions than its -parent directory. If you set the @code{CVSUMASK} -environment variable, that will control the file -permissions which @sc{cvs} uses in creating directories -and/or files in the repository. @code{CVSUMASK} does -not affect the file permissions in the working -directory; such files have the permissions which are -typical for newly created files, except that sometimes -@sc{cvs} creates them read-only (see the sections on -watches, @ref{Setting a watch}; -r, @ref{Global -options}; or @code{CVSREAD}, @ref{Environment variables}). -@c FIXME: Need more discussion of which -@c group should own the file in the repository. -@c Include a somewhat detailed example of the usual -@c case where CVSUMASK is 007, the developers are all -@c in a group, and that group owns stuff in the -@c repository. Need to talk about group ownership of -@c newly-created directories/files (on some unices, -@c such as SunOS4, setting the setgid bit on the -@c directories will make files inherit the directory's -@c group. On other unices, your mileage may vary. I -@c can't remember what POSIX says about this, if -@c anything). - -Note that using the client/server @sc{cvs} -(@pxref{Remote repositories}), there is no good way to -set @code{CVSUMASK}; the setting on the client machine -has no effect. If you are connecting with @code{rsh}, you -can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as -described in the documentation for your operating -system. This behavior might change in future versions -of @sc{cvs}; do not rely on the setting of -@code{CVSUMASK} on the client having no effect. -@c FIXME: need to explain what a umask is or cite -@c someplace which does. -@c -@c There is also a larger (largely separate) issue -@c about the meaning of CVSUMASK in a non-unix context. -@c For example, whether there is -@c an equivalent which fits better into other -@c protection schemes like POSIX.6, VMS, &c. -@c -@c FIXME: Need one place which discusses this -@c read-only files thing. Why would one use -r or -@c CVSREAD? Why would one use watches? How do they -@c interact? -@c -@c FIXME: We need to state -@c whether using CVSUMASK removes the need for manually -@c fixing permissions (in fact, if we are going to mention -@c manually fixing permission, we better document a lot -@c better just what we mean by "fix"). - -Using pserver, you will generally need stricter -permissions on the @sc{cvsroot} directory and -directories above it in the tree; see @ref{Password -authentication security}. - -@cindex Setuid -@cindex Setgid -@cindex Security, setuid -@cindex Installed images (VMS) -Some operating systems have features which allow a -particular program to run with the ability to perform -operations which the caller of the program could not. -For example, the set user ID (setuid) or set group ID -(setgid) features of unix or the installed image -feature of VMS. @sc{cvs} was not written to use such -features and therefore attempting to install @sc{cvs} in -this fashion will provide protection against only -accidental lapses; anyone who is trying to circumvent -the measure will be able to do so, and depending on how -you have set it up may gain access to more than just -@sc{cvs}. You may wish to instead consider pserver. It -shares some of the same attributes, in terms of -possibly providing a false sense of security or opening -security holes wider than the ones you are trying to -fix, so read the documentation on pserver security -carefully if you are considering this option -(@ref{Password authentication security}). - -@node Windows permissions -@subsection File Permission issues specific to Windows -@cindex Windows, and permissions -@cindex File permissions, Windows-specific -@cindex Permissions, Windows-specific - -Some file permission issues are specific to Windows -operating systems (Windows 95, Windows NT, and -presumably future operating systems in this family. -Some of the following might apply to OS/2 but I'm not -sure). - -If you are using local @sc{cvs} and the repository is on a -networked file system which is served by the Samba SMB -server, some people have reported problems with -permissions. Enabling WRITE=YES in the samba -configuration is said to fix/workaround it. -Disclaimer: I haven't investigated enough to know the -implications of enabling that option, nor do I know -whether there is something which @sc{cvs} could be doing -differently in order to avoid the problem. If you find -something out, please let us know as described in -@ref{BUGS}. - -@node Attic -@subsection The attic -@cindex Attic - -You will notice that sometimes @sc{cvs} stores an -@sc{rcs} file in the @code{Attic}. For example, if the -@sc{cvsroot} is @file{/usr/local/cvsroot} and we are -talking about the file @file{backend.c} in the -directory @file{yoyodyne/tc}, then the file normally -would be in - -@example -/usr/local/cvsroot/yoyodyne/tc/backend.c,v -@end example - -@noindent -but if it goes in the attic, it would be in - -@example -/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v -@end example - -@noindent -@cindex Dead state -instead. It should not matter from a user point of -view whether a file is in the attic; @sc{cvs} keeps -track of this and looks in the attic when it needs to. -But in case you want to know, the rule is that the RCS -file is stored in the attic if and only if the head -revision on the trunk has state @code{dead}. A -@code{dead} state means that file has been removed, or -never added, for that revision. For example, if you -add a file on a branch, it will have a trunk revision -in @code{dead} state, and a branch revision in a -non-@code{dead} state. -@c Probably should have some more concrete examples -@c here, or somewhere (not sure exactly how we should -@c arrange the discussion of the dead state, versus -@c discussion of the attic). - -@node CVS in repository -@subsection The CVS directory in the repository -@cindex CVS directory, in repository - -The @file{CVS} directory in each repository directory -contains information such as file attributes (in a file -called @file{CVS/fileattr}. In the -future additional files may be added to this directory, -so implementations should silently ignore additional -files. - -This behavior is implemented only by @sc{cvs} 1.7 and -later; for details see @ref{Watches Compatibility}. - -The format of the @file{fileattr} file is a series of entries -of the following form (where @samp{@{} and @samp{@}} -means the text between the braces can be repeated zero -or more times): - -@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} - @{; @var{attrname} = @var{attrval}@} <linefeed> - -@var{ent-type} is @samp{F} for a file, in which case the entry specifies the -attributes for that file. - -@var{ent-type} is @samp{D}, -and @var{filename} empty, to specify default attributes -to be used for newly added files. - -Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older -will delete them any time it writes file attributes. -@sc{cvs} 1.10 and later will preserve them. - -Note that the order of the lines is not significant; -a program writing the fileattr file may -rearrange them at its convenience. - -There is currently no way of quoting tabs or line feeds in the -filename, @samp{=} in @var{attrname}, -@samp{;} in @var{attrval}, etc. Note: some implementations also -don't handle a NUL character in any of the fields, but -implementations are encouraged to allow it. - -By convention, @var{attrname} starting with @samp{_} is for an attribute given -special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes -(or will be, once implementations start supporting user-defined attributes). - -Built-in attributes: - -@table @code -@item _watched -Present means the file is watched and should be checked out -read-only. - -@item _watchers -Users with watches for this file. Value is -@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} -where @var{watcher} is a username, and @var{type} -is zero or more of edit,unedit,commit separated by -@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). - -@item _editors -Users editing this file. Value is -@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} -where @var{editor} is a username, and @var{val} is -@var{time}+@var{hostname}+@var{pathname}, where -@var{time} is when the @code{cvs edit} command (or -equivalent) happened, -and @var{hostname} and @var{pathname} are for the working directory. -@end table - -Example: - -@c FIXME: sanity.sh should contain a similar test case -@c so we can compare this example from something from -@c Real Life(TM). See cvsclient.texi (under Notify) for more -@c discussion of the date format of _editors. -@example -Ffile1 _watched=;_watchers=joe>edit,mary>commit -Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs -D _watched= -@end example - -@noindent -means that the file @file{file1} should be checked out -read-only. Furthermore, joe is watching for edits and -mary is watching for commits. The file @file{file2} -should be checked out read-only; sue started editing it -on 8 Jan 1975 in the directory @file{/home/sue/cvs} on -the machine @code{workstn1}. Future files which are -added should be checked out read-only. To represent -this example here, we have shown a space after -@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact -there must be a single tab character there and no spaces. - -@node Locks -@subsection CVS locks in the repository - -@cindex #cvs.rfl, technical details -@cindex #cvs.wfl, technical details -@cindex #cvs.lock, technical details -@cindex Locks, cvs, technical details -For an introduction to @sc{cvs} locks focusing on -user-visible behavior, see @ref{Concurrency}. The -following section is aimed at people who are writing -tools which want to access a @sc{cvs} repository without -interfering with other tools accessing the same -repository. If you find yourself confused by concepts -described here, like @dfn{read lock}, @dfn{write lock}, -and @dfn{deadlock}, you might consult the literature on -operating systems or databases. - -@cindex #cvs.tfl -Any file in the repository with a name starting -with @file{#cvs.rfl.} is a read lock. Any file in -the repository with a name starting with -@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} -(before @sc{cvs} 1.5) also created files with names starting -with @file{#cvs.tfl}, but they are not discussed here. -The directory @file{#cvs.lock} serves as a master -lock. That is, one must obtain this lock first before -creating any of the other locks. - -To obtain a read lock, first create the @file{#cvs.lock} -directory. This operation must be atomic (which should -be true for creating a directory under most operating -systems). If it fails because the directory already -existed, wait for a while and try again. After -obtaining the @file{#cvs.lock} lock, create a file -whose name is @file{#cvs.rfl.} followed by information -of your choice (for example, hostname and process -identification number). Then remove the -@file{#cvs.lock} directory to release the master lock. -Then proceed with reading the repository. When you are -done, remove the @file{#cvs.rfl} file to release the -read lock. - -To obtain a write lock, first create the -@file{#cvs.lock} directory, as with read locks. Then -check that there are no files whose names start with -@file{#cvs.rfl.}. If there are, remove -@file{#cvs.lock}, wait for a while, and try again. If -there are no readers, then create a file whose name is -@file{#cvs.wfl} followed by information of your choice -(for example, hostname and process identification -number). Hang on to the @file{#cvs.lock} lock. Proceed -with writing the repository. When you are done, first -remove the @file{#cvs.wfl} file and then the -@file{#cvs.lock} directory. Note that unlike the -@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just -informational; it has no effect on the locking operation -beyond what is provided by holding on to the -@file{#cvs.lock} lock itself. - -Note that each lock (write lock or read lock) only locks -a single directory in the repository, including -@file{Attic} and @file{CVS} but not including -subdirectories which represent other directories under -version control. To lock an entire tree, you need to -lock each directory (note that if you fail to obtain -any lock you need, you must release the whole tree -before waiting and trying again, to avoid deadlocks). - -Note also that @sc{cvs} expects write locks to control -access to individual @file{foo,v} files. @sc{rcs} has -a scheme where the @file{,foo,} file serves as a lock, -but @sc{cvs} does not implement it and so taking out a -@sc{cvs} write lock is recommended. See the comments at -rcs_internal_lockfile in the @sc{cvs} source code for -further discussion/rationale. - -@node CVSROOT storage -@subsection How files are stored in the CVSROOT directory -@cindex CVSROOT, storage of files - -The @file{$CVSROOT/CVSROOT} directory contains the -various administrative files. In some ways this -directory is just like any other directory in the -repository; it contains @sc{rcs} files whose names end -in @samp{,v}, and many of the @sc{cvs} commands operate -on it the same way. However, there are a few -differences. - -For each administrative file, in addition to the -@sc{rcs} file, there is also a checked out copy of the -file. For example, there is an @sc{rcs} file -@file{loginfo,v} and a file @file{loginfo} which -contains the latest revision contained in -@file{loginfo,v}. When you check in an administrative -file, @sc{cvs} should print - -@example -cvs commit: Rebuilding administrative file database -@end example - -@noindent -and update the checked out copy in -@file{$CVSROOT/CVSROOT}. If it does not, there is -something wrong (@pxref{BUGS}). To add your own files -to the files to be updated in this fashion, you can add -them to the @file{checkoutlist} administrative file -(@pxref{checkoutlist}). - -@cindex modules.db -@cindex modules.pag -@cindex modules.dir -By default, the @file{modules} file behaves as -described above. If the modules file is very large, -storing it as a flat text file may make looking up -modules slow (I'm not sure whether this is as much of a -concern now as when @sc{cvs} first evolved this -feature; I haven't seen benchmarks). Therefore, by -making appropriate edits to the @sc{cvs} source code -one can store the modules file in a database which -implements the @code{ndbm} interface, such as Berkeley -db or GDBM. If this option is in use, then the modules -database will be stored in the files @file{modules.db}, -@file{modules.pag}, and/or @file{modules.dir}. -@c I think fileattr also will use the database stuff. -@c Anything else? - -For information on the meaning of the various -administrative files, see @ref{Administrative files}. - -@node Working directory storage -@section How data is stored in the working directory - -@c FIXME: Somewhere we should discuss timestamps (test -@c case "stamps" in sanity.sh). But not here. Maybe -@c in some kind of "working directory" chapter which -@c would encompass the "Builds" one? But I'm not sure -@c whether that is a good organization (is it based on -@c what the user wants to do?). - -@cindex CVS directory, in working directory -While we are discussing @sc{cvs} internals which may -become visible from time to time, we might as well talk -about what @sc{cvs} puts in the @file{CVS} directories -in the working directories. As with the repository, -@sc{cvs} handles this information and one can usually -access it via @sc{cvs} commands. But in some cases it -may be useful to look at it, and other programs, such -as the @code{jCVS} graphical user interface or the -@code{VC} package for emacs, may need to look at it. -Such programs should follow the recommendations in this -section if they hope to be able to work with other -programs which use those files, including future -versions of the programs just mentioned and the -command-line @sc{cvs} client. - -The @file{CVS} directory contains several files. -Programs which are reading this directory should -silently ignore files which are in the directory but -which are not documented here, to allow for future -expansion. - -The files are stored according to the text file -convention for the system in question. This means that -working directories are not portable between systems -with differing conventions for storing text files. -This is intentional, on the theory that the files being -managed by @sc{cvs} probably will not be portable between -such systems either. - -@table @file -@item Root -This file contains the current @sc{cvs} root, as -described in @ref{Specifying a repository}. - -@cindex Repository file, in CVS directory -@cindex CVS/Repository file -@item Repository -This file contains the directory within the repository -which the current directory corresponds with. It can -be either an absolute pathname or a relative pathname; -@sc{cvs} has had the ability to read either format -since at least version 1.3 or so. The relative -pathname is relative to the root, and is the more -sensible approach, but the absolute pathname is quite -common and implementations should accept either. For -example, after the command - -@example -cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc -@end example - -@noindent -@file{Root} will contain - -@example -:local:/usr/local/cvsroot -@end example - -@noindent -and @file{Repository} will contain either - -@example -/usr/local/cvsroot/yoyodyne/tc -@end example - -@noindent -or - -@example -yoyodyne/tc -@end example - -If the particular working directory does not correspond -to a directory in the repository, then @file{Repository} -should contain @file{CVSROOT/Emptydir}. -@cindex Emptydir, in CVSROOT directory -@cindex CVSROOT/Emptydir directory - -@cindex Entries file, in CVS directory -@cindex CVS/Entries file -@item Entries -This file lists the files and directories in the -working directory. -The first character of each line indicates what sort of -line it is. If the character is unrecognized, programs -reading the file should silently skip that line, to -allow for future expansion. - -If the first character is @samp{/}, then the format is: - -@example -/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate} -@end example - -@noindent -where @samp{[} and @samp{]} are not part of the entry, -but instead indicate that the @samp{+} and conflict -marker are optional. @var{name} is the name of the -file within the directory. @var{revision} is the -revision that the file in the working derives from, or -@samp{0} for an added file, or @samp{-} followed by a -revision for a removed file. @var{timestamp} is the -timestamp of the file at the time that @sc{cvs} created -it; if the timestamp differs with the actual -modification time of the file it means the file has -been modified. It is stored in -the format used by the ISO C asctime() function (for -example, @samp{Sun Apr 7 01:29:26 1996}). One may -write a string which is not in that format, for -example, @samp{Result of merge}, to indicate that the -file should always be considered to be modified. This -is not a special case; to see whether a file is -modified a program should take the timestamp of the file -and simply do a string compare with @var{timestamp}. -If there was a conflict, @var{conflict} can be set to -the modification time of the file after the file has been -written with conflict markers (@pxref{Conflicts example}). -Thus if @var{conflict} is subsequently the same as the actual -modification time of the file it means that the user -has obviously not resolved the conflict. @var{options} -contains sticky options (for example @samp{-kb} for a -binary file). @var{tagdate} contains @samp{T} followed -by a tag name, or @samp{D} for a date, followed by a -sticky tag or date. Note that if @var{timestamp} -contains a pair of timestamps separated by a space, -rather than a single timestamp, you are dealing with a -version of @sc{cvs} earlier than @sc{cvs} 1.5 (not -documented here). - -The timezone on the timestamp in CVS/Entries (local or -universal) should be the same as the operating system -stores for the timestamp of the file itself. For -example, on Unix the file's timestamp is in universal -time (UT), so the timestamp in CVS/Entries should be -too. On @sc{vms}, the file's timestamp is in local -time, so @sc{cvs} on @sc{vms} should use local time. -This rule is so that files do not appear to be modified -merely because the timezone changed (for example, to or -from summer time). -@c See comments and calls to gmtime() and friends in -@c src/vers_ts.c (function time_stamp). - -If the first character of a line in @file{Entries} is -@samp{D}, then it indicates a subdirectory. @samp{D} -on a line all by itself indicates that the program -which wrote the @file{Entries} file does record -subdirectories (therefore, if there is such a line and -no other lines beginning with @samp{D}, one knows there -are no subdirectories). Otherwise, the line looks -like: - -@example -D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} -@end example - -@noindent -where @var{name} is the name of the subdirectory, and -all the @var{filler} fields should be silently ignored, -for future expansion. Programs which modify -@code{Entries} files should preserve these fields. - -The lines in the @file{Entries} file can be in any order. - -@cindex Entries.Log file, in CVS directory -@cindex CVS/Entries.Log file -@item Entries.Log -This file does not record any information beyond that -in @file{Entries}, but it does provide a way to update -the information without having to rewrite the entire -@file{Entries} file, including the ability to preserve -the information even if the program writing -@file{Entries} and @file{Entries.Log} abruptly aborts. -Programs which are reading the @file{Entries} file -should also check for @file{Entries.Log}. If the latter -exists, they should read @file{Entries} and then apply -the changes mentioned in @file{Entries.Log}. After -applying the changes, the recommended practice is to -rewrite @file{Entries} and then delete @file{Entries.Log}. -The format of a line in @file{Entries.Log} is a single -character command followed by a space followed by a -line in the format specified for a line in -@file{Entries}. The single character command is -@samp{A} to indicate that the entry is being added, -@samp{R} to indicate that the entry is being removed, -or any other character to indicate that the entire line -in @file{Entries.Log} should be silently ignored (for -future expansion). If the second character of the line -in @file{Entries.Log} is not a space, then it was -written by an older version of @sc{cvs} (not documented -here). - -Programs which are writing rather than reading can -safely ignore @file{Entries.Log} if they so choose. - -@cindex Entries.Backup file, in CVS directory -@cindex CVS/Entries.Backup file -@item Entries.Backup -This is a temporary file. Recommended usage is to -write a new entries file to @file{Entries.Backup}, and -then to rename it (atomically, where possible) to @file{Entries}. - -@cindex Entries.Static file, in CVS directory -@cindex CVS/Entries.Static file -@item Entries.Static -The only relevant thing about this file is whether it -exists or not. If it exists, then it means that only -part of a directory was gotten and @sc{cvs} will -not create additional files in that directory. To -clear it, use the @code{update} command with the -@samp{-d} option, which will get the additional files -and remove @file{Entries.Static}. -@c FIXME: This needs to be better documented, in places -@c other than Working Directory Storage. -@c FIXCVS: The fact that this setting exists needs to -@c be more visible to the user. For example "cvs -@c status foo", in the case where the file would be -@c gotten except for Entries.Static, might say -@c something to distinguish this from other cases. -@c One thing that periodically gets suggested is to -@c have "cvs update" print something when it skips -@c files due to Entries.Static, but IMHO that kind of -@c noise pretty much makes the Entries.Static feature -@c useless. - -@cindex Tag file, in CVS directory -@cindex CVS/Tag file -@cindex Sticky tags/dates, per-directory -@cindex Per-directory sticky tags/dates -@item Tag -This file contains per-directory sticky tags or dates. -The first character is @samp{T} for a branch tag, -@samp{N} for a non-branch tag, or @samp{D} for a date, -or another character to mean the file should be -silently ignored, for future expansion. This character -is followed by the tag or date. Note that -per-directory sticky tags or dates are used for things -like applying to files which are newly added; they -might not be the same as the sticky tags or dates on -individual files. For general information on sticky -tags and dates, see @ref{Sticky tags}. -@c FIXME: This needs to be much better documented, -@c preferably not in the context of "working directory -@c storage". -@c FIXME: The Sticky tags node needs to discuss, or xref to -@c someplace which discusses, per-directory sticky -@c tags and the distinction with per-file sticky tags. - -@cindex Notify file, in CVS directory -@cindex CVS/Notify file -@item Notify -This file stores notifications (for example, for -@code{edit} or @code{unedit}) which have not yet been -sent to the server. Its format is not yet documented -here. - -@cindex Notify.tmp file, in CVS directory -@cindex CVS/Notify.tmp file -@item Notify.tmp -This file is to @file{Notify} as @file{Entries.Backup} -is to @file{Entries}. That is, to write @file{Notify}, -first write the new contents to @file{Notify.tmp} and -then (atomically where possible), rename it to -@file{Notify}. - -@cindex Base directory, in CVS directory -@cindex CVS/Base directory -@item Base -If watches are in use, then an @code{edit} command -stores the original copy of the file in the @file{Base} -directory. This allows the @code{unedit} command to -operate even if it is unable to communicate with the -server. - -@cindex Baserev file, in CVS directory -@cindex CVS/Baserev file -@item Baserev -The file lists the revision for each of the files in -the @file{Base} directory. The format is: - -@example -B@var{name}/@var{rev}/@var{expansion} -@end example - -@noindent -where @var{expansion} should be ignored, to allow for -future expansion. - -@cindex Baserev.tmp file, in CVS directory -@cindex CVS/Baserev.tmp file -@item Baserev.tmp -This file is to @file{Baserev} as @file{Entries.Backup} -is to @file{Entries}. That is, to write @file{Baserev}, -first write the new contents to @file{Baserev.tmp} and -then (atomically where possible), rename it to -@file{Baserev}. - -@cindex Template file, in CVS directory -@cindex CVS/Template file -@item Template -This file contains the template specified by the -@file{rcsinfo} file (@pxref{rcsinfo}). It is only used -by the client; the non-client/server @sc{cvs} consults -@file{rcsinfo} directly. -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Intro administrative files -@section The administrative files -@cindex Administrative files (intro) -@cindex Modules file -@cindex CVSROOT, module name -@cindex Defining modules (intro) - -@c FIXME: this node should be reorganized into "general -@c information about admin files" and put the "editing -@c admin files" stuff up front rather than jumping into -@c the details of modules right away. Then the -@c Administrative files node can go away, the information -@c on each admin file distributed to a place appropriate -@c to its function, and this node can contain a table -@c listing each file and a @ref to its detailed description. - -The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative -files}. @xref{Administrative files}, for a complete description. -You can use @sc{cvs} without any of these files, but -some commands work better when at least the -@file{modules} file is properly set up. - -The most important of these files is the @file{modules} -file. It defines all modules in the repository. This -is a sample @file{modules} file. - -@c FIXME: The CVSROOT line is a goofy example now that -@c mkmodules doesn't exist. -@example -CVSROOT CVSROOT -modules CVSROOT modules -cvs gnu/cvs -rcs gnu/rcs -diff gnu/diff -tc yoyodyne/tc -@end example - -The @file{modules} file is line oriented. In its -simplest form each line contains the name of the -module, whitespace, and the directory where the module -resides. The directory is a path relative to -@code{$CVSROOT}. The last four lines in the example -above are examples of such lines. - -@c FIXME: might want to introduce the concept of options in modules file -@c (the old example which was here, -i mkmodules, is obsolete). - -The line that defines the module called @samp{modules} -uses features that are not explained here. -@xref{modules}, for a full explanation of all the -available features. - -@c FIXME: subsection without node is bogus -@subsection Editing administrative files -@cindex Editing administrative files -@cindex Administrative files, editing them - -You edit the administrative files in the same way that you would edit -any other module. Use @samp{cvs checkout CVSROOT} to get a working -copy, edit it, and commit your changes in the normal way. - -It is possible to commit an erroneous administrative -file. You can often fix the error and check in a new -revision, but sometimes a particularly bad error in the -administrative file makes it impossible to commit new -revisions. If and when this happens, you can correct -the problem by temporarily copying a corrected administrative file -directly into the @code{$CVSROOT/CVSROOT} repository directory, -then committing the same correction via a checkout of the @file{CVSROOT} -module. It is important that the correction also be made via the -checked out copy, or the next checkout and commit to the -<code>CVSROOT</code> module will overwrite the correction that was -copied directly into the repository, possibly breaking things in such -a way as to prevent commits again. -@c @xref{Bad administrative files} for a hint -@c about how to solve such situations. -@c -- administrative file checking-- - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Multiple repositories -@section Multiple repositories -@cindex Multiple repositories -@cindex Repositories, multiple -@cindex Many repositories -@cindex Parallel repositories -@cindex Disjoint repositories -@cindex CVSROOT, multiple repositories - -In some situations it is a good idea to have more than -one repository, for instance if you have two -development groups that work on separate projects -without sharing any code. All you have to do to have -several repositories is to specify the appropriate -repository, using the @code{CVSROOT} environment -variable, the @samp{-d} option to @sc{cvs}, or (once -you have checked out a working directory) by simply -allowing @sc{cvs} to use the repository that was used -to check out the working directory -(@pxref{Specifying a repository}). - -The big advantage of having multiple repositories is -that they can reside on different servers. With @sc{cvs} -version 1.10, a single command cannot recurse into -directories from different repositories. With development -versions of @sc{cvs}, you can check out code from multiple -servers into your working directory. @sc{cvs} will -recurse and handle all the details of making -connections to as many server machines as necessary to -perform the requested command. Here is an example of -how to set up a working directory: - -@example -cvs -d server1:/cvs co dir1 -cd dir1 -cvs -d server2:/root co sdir -cvs update -@end example - -The @code{cvs co} commands set up the working -directory, and then the @code{cvs update} command will -contact server2, to update the dir1/sdir subdirectory, -and server1, to update everything else. - -@c FIXME: Does the FAQ have more about this? I have a -@c dim recollection, but I'm too lazy to check right now. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Creating a repository -@section Creating a repository - -@cindex Repository, setting up -@cindex Creating a repository -@cindex Setting up a repository - -This section describes how to set up a @sc{cvs} repository for any -sort of access method. After completing the setup described in this -section, you should be able to access your @sc{cvs} repository immediately -via the local access method and several remote access methods. For -more information on setting up remote access to the repository you create -in this section, please read the section on @xref{Remote repositories}. - -To set up a @sc{cvs} repository, first choose the -machine and disk on which you want to store the -revision history of the source files. CPU and memory -requirements are modest, so most machines should be -adequate. For details see @ref{Server requirements}. -@c Possible that we should be providing a quick rule of -@c thumb, like the 32M memory for the server. That -@c might increase the number of people who are happy -@c with the answer, without following the xref. - -To estimate disk space -requirements, if you are importing RCS files from -another system, the size of those files is the -approximate initial size of your repository, or if you -are starting without any version history, a rule of -thumb is to allow for the server approximately three -times the size of the code to be under @sc{cvs} for the -repository (you will eventually outgrow this, but not -for a while). On the machines on which the developers -will be working, you'll want disk space for -approximately one working directory for each developer -(either the entire tree or a portion of it, depending -on what each developer uses). - -The repository should be accessible -(directly or via a networked file system) from all -machines which want to use @sc{cvs} in server or local -mode; the client machines need not have any access to -it other than via the @sc{cvs} protocol. It is not -possible to use @sc{cvs} to read from a repository -which one only has read access to; @sc{cvs} needs to be -able to create lock files (@pxref{Concurrency}). - -@cindex init (subcommand) -To create a repository, run the @code{cvs init} -command. It will set up an empty repository in the -@sc{cvs} root specified in the usual way -(@pxref{Repository}). For example, - -@example -cvs -d /usr/local/cvsroot init -@end example - -@code{cvs init} is careful to never overwrite any -existing files in the repository, so no harm is done if -you run @code{cvs init} on an already set-up -repository. - -@code{cvs init} will enable history logging; if you -don't want that, remove the history file after running -@code{cvs init}. @xref{history file}. - -@node Backing up -@section Backing up a repository -@cindex Repository, backing up -@cindex Backing up, repository - -There is nothing particularly magical about the files -in the repository; for the most part it is possible to -back them up just like any other files. However, there -are a few issues to consider. - -@cindex Locks, cvs, and backups -@cindex #cvs.rfl, and backups -The first is that to be paranoid, one should either not -use @sc{cvs} during the backup, or have the backup -program lock @sc{cvs} while doing the backup. To not -use @sc{cvs}, you might forbid logins to machines which -can access the repository, turn off your @sc{cvs} -server, or similar mechanisms. The details would -depend on your operating system and how you have -@sc{cvs} set up. To lock @sc{cvs}, you would create -@file{#cvs.rfl} locks in each repository directory. -See @ref{Concurrency}, for more on @sc{cvs} locks. -Having said all this, if you just back up without any -of these precautions, the results are unlikely to be -particularly dire. Restoring from backup, the -repository might be in an inconsistent state, but this -would not be particularly hard to fix manually. - -When you restore a repository from backup, assuming -that changes in the repository were made after the time -of the backup, working directories which were not -affected by the failure may refer to revisions which no -longer exist in the repository. Trying to run @sc{cvs} -in such directories will typically produce an error -message. One way to get those changes back into the -repository is as follows: - -@itemize @bullet -@item -Get a new working directory. - -@item -Copy the files from the working directory from before -the failure over to the new working directory (do not -copy the contents of the @file{CVS} directories, of -course). - -@item -Working in the new working directory, use commands such -as @code{cvs update} and @code{cvs diff} to figure out -what has changed, and then when you are ready, commit -the changes into the repository. -@end itemize - -@node Moving a repository -@section Moving a repository -@cindex Repository, moving -@cindex Moving a repository -@cindex Copying a repository - -Just as backing up the files in the repository is -pretty much like backing up any other files, if you -need to move a repository from one place to another it -is also pretty much like just moving any other -collection of files. - -The main thing to consider is that working directories -point to the repository. The simplest way to deal with -a moved repository is to just get a fresh working -directory after the move. Of course, you'll want to -make sure that the old working directory had been -checked in before the move, or you figured out some -other way to make sure that you don't lose any -changes. If you really do want to reuse the existing -working directory, it should be possible with manual -surgery on the @file{CVS/Repository} files. You can -see @ref{Working directory storage}, for information on -the @file{CVS/Repository} and @file{CVS/Root} files, but -unless you are sure you want to bother, it probably -isn't worth it. -@c FIXME: Surgery on CVS/Repository should be avoided -@c by making RELATIVE_REPOS the default. -@c FIXME-maybe: might want some documented way to -@c change the CVS/Root files in some particular tree. -@c But then again, I don't know, maybe just having -@c people do this in perl/shell/&c isn't so bad... - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Remote repositories -@section Remote repositories -@cindex Repositories, remote -@cindex Remote repositories -@cindex Client/Server Operation -@cindex Server, CVS -@cindex Remote repositories, port specification -@cindex Repositories, remote, port specification -@cindex Client/Server Operation, port specification -@cindex pserver (client/server connection method), port specification -@cindex kserver (client/server connection method), port specification -@cindex gserver (client/server connection method), port specification -@cindex port, specifying for remote repositories - - Your working copy of the sources can be on a -different machine than the repository. Using @sc{cvs} -in this manner is known as @dfn{client/server} -operation. You run @sc{cvs} on a machine which can -mount your working directory, known as the -@dfn{client}, and tell it to communicate to a machine -which can mount the repository, known as the -@dfn{server}. Generally, using a remote -repository is just like using a local one, except that -the format of the repository name is: - -@example -[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository -@end example - -Specifying a password in the repository name is not recommended during -checkout, since this will cause @sc{cvs} to store a cleartext copy of the -password in each created directory. @code{cvs login} first instead -(@pxref{Password authentication client}). - -The details of exactly what needs to be set up depend -on how you are connecting to the server. - -If @var{method} is not specified, and the repository -name contains @samp{:}, then the default is @code{ext} -or @code{server}, depending on your platform; both are -described in @ref{Connecting via rsh}. -@c Should we try to explain which platforms are which? -@c Platforms like unix and VMS, which only allow -@c privileged programs to bind to sockets <1024 lose on -@c :server: -@c Platforms like Mac and VMS, whose rsh program is -@c unusable or nonexistent, lose on :ext: -@c Platforms like OS/2 and NT probably could plausibly -@c default either way (modulo -b troubles). - -@c FIXME: We need to have a better way of explaining -@c what method to use. This presentation totally -@c obscures the fact that :ext: and CVS_RSH is the way to -@c use SSH, for example. Plus it incorrectly implies -@c that you need an @code{rsh} binary on the client to use -@c :server:. -@c Also note that rsh not pserver is the right choice if you want -@c users to be able to create their own repositories -@c (because of the --allow-root related issues). -@menu -* Server requirements:: Memory and other resources for servers -* Connecting via rsh:: Using the @code{rsh} program to connect -* Password authenticated:: Direct connections using passwords -* GSSAPI authenticated:: Direct connections using GSSAPI -* Kerberos authenticated:: Direct connections with Kerberos -* Connecting via fork:: Using a forked @code{cvs server} to connect -@end menu - -@node Server requirements -@subsection Server requirements - -The quick answer to what sort of machine is suitable as -a server is that requirements are modest---a server -with 32M of memory or even less can handle a fairly -large source tree with a fair amount of activity. -@c Say something about CPU speed too? I'm even less sure -@c what to say on that subject... - -The real answer, of course, is more complicated. -Estimating the known areas of large memory consumption -should be sufficient to estimate memory requirements. -There are two such areas documented here; other memory -consumption should be small by comparison (if you find -that is not the case, let us know, as described in -@ref{BUGS}, so we can update this documentation). - -The first area of big memory consumption is large -checkouts, when using the @sc{cvs} server. The server -consists of two processes for each client that it is -serving. Memory consumption on the child process -should remain fairly small. Memory consumption on the -parent process, particularly if the network connection -to the client is slow, can be expected to grow to -slightly more than the size of the sources in a single -directory, or two megabytes, whichever is larger. -@c "two megabytes" of course is SERVER_HI_WATER. But -@c we don't mention that here because we are -@c documenting the default configuration of CVS. If it -@c is a "standard" thing to change that value, it -@c should be some kind of run-time configuration. -@c -@c See cvsclient.texi for more on the design decision -@c to not have locks in place while waiting for the -@c client, which is what results in memory consumption -@c as high as this. - -Multiplying the size of each @sc{cvs} server by the -number of servers which you expect to have active at -one time should give an idea of memory requirements for -the server. For the most part, the memory consumed by -the parent process probably can be swap space rather -than physical memory. -@c Has anyone verified that notion about swap space? -@c I say it based pretty much on guessing that the -@c ->text of the struct buffer_data only gets accessed -@c in a first in, first out fashion, but I haven't -@c looked very closely. - -@c What about disk usage in /tmp on the server? I think that -@c it can be substantial, but I haven't looked at this -@c again and tried to figure it out ("cvs import" is -@c probably the worst case...). - -The second area of large memory consumption is -@code{diff}, when checking in large files. This is -required even for binary files. The rule of thumb is -to allow about ten times the size of the largest file -you will want to check in, although five times may be -adequate. For example, if you want to check in a file -which is 10 megabytes, you should have 100 megabytes of -memory on the machine doing the checkin (the server -machine for client/server, or the machine running -@sc{cvs} for non-client/server). This can be swap -space rather than physical memory. Because the memory -is only required briefly, there is no particular need -to allow memory for more than one such checkin at a -time. -@c The 5-10 times rule of thumb is from Paul Eggert for -@c GNU diff. I don't think it is in the GNU diff -@c manual or anyplace like that. -@c -@c Probably we could be saying more about -@c non-client/server CVS. -@c I would guess for non-client/server CVS in an NFS -@c environment the biggest issues are the network and -@c the NFS server. - -Resource consumption for the client is even more -modest---any machine with enough capacity to run the -operating system in question should have little -trouble. -@c Is that true? I think the client still wants to -@c (bogusly) store entire files in memory at times. - -For information on disk space requirements, see -@ref{Creating a repository}. - -@node Connecting via rsh -@subsection Connecting with rsh or ssh - -@cindex ssh -@sc{cvs} may use the @samp{ssh} protocol to perform -these operations, so the remote user host needs to have -a either an agent like @code{ssh-agent} to hold -credentials or a @file{.shosts} file which grants -access to the local user. Note that the program that -@sc{cvs} uses for this purpose may be specified using -the @file{--with-ssh} flag to configure. - -@cindex rsh -@sc{cvs} uses the @samp{rsh} protocol to perform these -operations, so the remote user host needs to have a -@file{.rhosts} file which grants access to the local -user. Note that the program that @sc{cvs} uses for this -purpose may be specified using the @file{--with-rsh} -flag to configure. - -For example, suppose you are the user @samp{mozart} on -the local machine @samp{toe.example.com}, and the -server machine is @samp{faun.example.org}. On -faun, put the following line into the file -@file{.rhosts} in @samp{bach}'s home directory: - -@example -toe.example.com mozart -@end example - -@noindent -Then test that @samp{rsh} is working with - -@example -rsh -l bach faun.example.org 'echo $PATH' -@end example - -@noindent -To test that @samp{ssh} is working use - -@example -ssh -l bach faun.example.org 'echo $PATH' -@end example - -@cindex CVS_SERVER, environment variable -Next you have to make sure that @code{rsh} will be able -to find the server. Make sure that the path which -@code{rsh} printed in the above example includes the -directory containing a program named @code{cvs} which -is the server. You need to set the path in -@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} -or @file{.profile}. Alternately, you can set the -environment variable @code{CVS_SERVER} on the client -machine to the filename of the server you want to use, -for example @file{/usr/local/bin/cvs-1.6}. -@c FIXME: there should be a way to specify the -@c program in CVSROOT, not CVS_SERVER, so that one can use -@c different ones for different roots. e.g. ":server;cvs=cvs-1.6:" -@c instead of ":server:". - -There is no need to edit @file{inetd.conf} or start a -@sc{cvs} server daemon. - -@cindex :server:, setting up -@cindex :ext:, setting up -@cindex :extssh:, setting up -@cindex Kerberos, using kerberized rsh -@cindex SSH (rsh replacement) -@cindex rsh replacements (Kerberized, SSH, &c) -There are three access methods that you use in @code{CVSROOT} -for rsh or ssh. @code{:server:} specifies an internal rsh -client, which is supported only by some @sc{cvs} ports. -@code{:extssh:} specifies an external ssh program. By -default this is @code{ssh} (unless otherwise specified -by the @file{--with-ssh} flag to configure) but you may set the -@code{CVS_SSH} environment variable to invoke another -program or wrapper script. -@code{:ext:} specifies an external rsh program. By -default this is @code{rsh} (unless otherwise specified -by the @file{--with-rsh} flag to configure) but you may set the -@code{CVS_RSH} environment variable to invoke another -program which can access the remote server (for -example, @code{remsh} on HP-UX 9 because @code{rsh} is -something different). It must be a program which can -transmit data to and from the server without modifying -it; for example the Windows NT @code{rsh} is not -suitable since it by default translates between CRLF -and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} -to @code{rsh} to get around this, but since this could -potentially cause problems for programs other than the -standard @code{rsh}, it may change in the future. If -you set @code{CVS_RSH} to @code{SSH} or some other rsh -replacement, the instructions in the rest of this -section concerning @file{.rhosts} and so on are likely -to be inapplicable; consult the documentation for your rsh -replacement. -@c FIXME: there should be a way to specify the -@c program in CVSROOT, not CVS_RSH, so that one can use -@c different ones for different roots. e.g. -@c ":ext;CVS_RSH=remsh:" instead of ":ext:". -@c See also the comment in src/client.c for rationale -@c concerning "rsh" being the default and never -@c "remsh". - -Continuing our example, supposing you want to access -the module @file{foo} in the repository -@file{/usr/local/cvsroot/}, on machine -@file{faun.example.org}, you are ready to go: - -@example -cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo -@end example - -@noindent -(The @file{bach@@} can be omitted if the username is -the same on both the local and remote hosts.) - -@c Should we mention "rsh host echo hi" and "rsh host -@c cat" (the latter followed by typing text and ^D) -@c as troubleshooting techniques? Probably yes -@c (people tend to have trouble setting this up), -@c but this kind of thing can be hard to spell out. - -@node Password authenticated -@subsection Direct connection with password authentication - -The @sc{cvs} client can also connect to the server -using a password protocol. This is particularly useful -if using @code{rsh} is not feasible (for example, -the server is behind a firewall), and Kerberos also is -not available. - - To use this method, it is necessary to make -some adjustments on both the server and client sides. - -@menu -* Password authentication server:: Setting up the server -* Password authentication client:: Using the client -* Password authentication security:: What this method does and does not do -@end menu - -@node Password authentication server -@subsubsection Setting up the server for password authentication - -First of all, you probably want to tighten the -permissions on the @file{$CVSROOT} and -@file{$CVSROOT/CVSROOT} directories. See @ref{Password -authentication security}, for more details. - -@cindex pserver (subcommand) -@cindex Remote repositories, port specification -@cindex Repositories, remote, port specification -@cindex Client/Server Operation, port specification -@cindex pserver (client/server connection method), port specification -@cindex kserver (client/server connection method), port specification -@cindex gserver (client/server connection method), port specification -@cindex port, specifying for remote repositories -@cindex Password server, setting up -@cindex Authenticating server, setting up -@cindex inetd, configuring for pserver -@cindex xinetd, configuring for pserver -@c FIXME: this isn't quite right regarding port -@c numbers; CVS looks up "cvspserver" in -@c /etc/services (on unix, but what about non-unix?). -On the server side, the file @file{/etc/inetd.conf} -needs to be edited so @code{inetd} knows to run the -command @code{cvs pserver} when it receives a -connection on the right port. By default, the port -number is 2401; it would be different if your client -were compiled with @code{CVS_AUTH_PORT} defined to -something else, though. This can also be specified in the CVSROOT variable -(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT -environment variable (@pxref{Environment variables}). - - If your @code{inetd} allows raw port numbers in -@file{/etc/inetd.conf}, then the following (all on a -single line in @file{inetd.conf}) should be sufficient: - -@example -2401 stream tcp nowait root /usr/local/bin/cvs -cvs -f --allow-root=/usr/cvsroot pserver -@end example - -@noindent -(You could also use the -@samp{-T} option to specify a temporary directory.) - -The @samp{--allow-root} option specifies the allowable -@sc{cvsroot} directory. Clients which attempt to use a -different @sc{cvsroot} directory will not be allowed to -connect. If there is more than one @sc{cvsroot} -directory which you want to allow, repeat the option. -(Unfortunately, many versions of @code{inetd} have very small -limits on the number of arguments and/or the total length -of the command. The usual solution to this problem is -to have @code{inetd} run a shell script which then invokes -@sc{cvs} with the necessary arguments.) - - If your @code{inetd} wants a symbolic service -name instead of a raw port number, then put this in -@file{/etc/services}: - -@example -cvspserver 2401/tcp -@end example - -@noindent -and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. - -If your system uses @code{xinetd} instead of @code{inetd}, -the procedure is slightly different. -Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: - -@example -service cvspserver -@{ - port = 2401 - socket_type = stream - protocol = tcp - wait = no - user = root - passenv = PATH - server = /usr/local/bin/cvs - server_args = -f --allow-root=/usr/cvsroot pserver -@} -@end example - -@noindent -(If @code{cvspserver} is defined in @file{/etc/services}, you can omit -the @code{port} line.) - - Once the above is taken care of, restart your -@code{inetd}, or do whatever is necessary to force it -to reread its initialization files. - -If you are having trouble setting this up, see -@ref{Connection}. - -@cindex CVS passwd file -@cindex passwd (admin file) -Because the client stores and transmits passwords in -cleartext (almost---see @ref{Password authentication -security}, for details), a separate @sc{cvs} password -file is generally used, so people don't compromise -their regular passwords when they access the -repository. This file is -@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro -administrative files}). It uses a colon-separated -format, similar to @file{/etc/passwd} on Unix systems, -except that it has fewer fields: @sc{cvs} username, -optional password, and an optional system username for -@sc{cvs} to run as if authentication succeeds. Here is -an example @file{passwd} file with five entries: - -@example -anonymous: -bach:ULtgRLXo7NRxs -spwang:1sOp854gDF3DY -melissa:tGX1fS8sun6rY:pubcvs -qproj:XR4EZcEs0szik:pubcvs -@end example - -@noindent -(The passwords are encrypted according to the standard -Unix @code{crypt()} function, so it is possible to -paste in passwords directly from regular Unix -@file{/etc/passwd} files.) - -The first line in the example will grant access to any -@sc{cvs} client attempting to authenticate as user -@code{anonymous}, no matter what password they use, -including an empty password. (This is typical for -sites granting anonymous read-only access; for -information on how to do the "read-only" part, see -@ref{Read-only access}.) - -The second and third lines will grant access to -@code{bach} and @code{spwang} if they supply their -respective plaintext passwords. - -@cindex User aliases -The fourth line will grant access to @code{melissa}, if -she supplies the correct password, but her @sc{cvs} -operations will actually run on the server side under -the system user @code{pubcvs}. Thus, there need not be -any system user named @code{melissa}, but there -@emph{must} be one named @code{pubcvs}. - -The fifth line shows that system user identities can be -shared: any client who successfully authenticates as -@code{qproj} will actually run as @code{pubcvs}, just -as @code{melissa} does. That way you could create a -single, shared system user for each project in your -repository, and give each developer their own line in -the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} -username on each line would be different, but the -system username would be the same. The reason to have -different @sc{cvs} usernames is that @sc{cvs} will log their -actions under those names: when @code{melissa} commits -a change to a project, the checkin is recorded in the -project's history under the name @code{melissa}, not -@code{pubcvs}. And the reason to have them share a -system username is so that you can arrange permissions -in the relevant area of the repository such that only -that account has write-permission there. - -If the system-user field is present, all -password-authenticated @sc{cvs} commands run as that -user; if no system user is specified, @sc{cvs} simply -takes the @sc{cvs} username as the system username and -runs commands as that user. In either case, if there -is no such user on the system, then the @sc{cvs} -operation will fail (regardless of whether the client -supplied a valid password). - -The password and system-user fields can both be omitted -(and if the system-user field is omitted, then also -omit the colon that would have separated it from the -encrypted password). For example, this would be a -valid @file{$CVSROOT/CVSROOT/passwd} file: - -@example -anonymous::pubcvs -fish:rKa5jzULzmhOo:kfogel -sussman:1sOp854gDF3DY -@end example - -@noindent -When the password field is omitted or empty, then the -client's authentication attempt will succeed with any -password, including the empty string. However, the -colon after the @sc{cvs} username is always necessary, -even if the password is empty. - -@sc{cvs} can also fall back to use system authentication. -When authenticating a password, the server first checks -for the user in the @file{$CVSROOT/CVSROOT/passwd} -file. If it finds the user, it will use that entry for -authentication as described above. But if it does not -find the user, or if the @sc{cvs} @file{passwd} file -does not exist, then the server can try to authenticate -the username and password using the operating system's -user-lookup routines (this "fallback" behavior can be -disabled by setting @code{SystemAuth=no} in the -@sc{cvs} @file{config} file, @pxref{config}). Be -aware, however, that falling back to system -authentication might be a security risk: @sc{cvs} -operations would then be authenticated with that user's -regular login password, and the password flies across -the network in plaintext. See @ref{Password -authentication security} for more on this. - -Right now, the only way to put a password in the -@sc{cvs} @file{passwd} file is to paste it there from -somewhere else. Someday, there may be a @code{cvs -passwd} command. - -Unlike many of the files in @file{$CVSROOT/CVSROOT}, it -is normal to edit the @file{passwd} file in-place, -rather than via @sc{cvs}. This is because of the -possible security risks of having the @file{passwd} -file checked out to people's working copies. If you do -want to include the @file{passwd} file in checkouts of -@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. - -@c We might also suggest using the @code{htpasswd} command -@c from freely available web servers as well, but that -@c would open up a can of worms in that the users next -@c questions are likely to be "where do I get it?" and -@c "how do I use it?" -@c Also note that htpasswd, at least the version I had, -@c likes to clobber the third field. - -@node Password authentication client -@subsubsection Using the client with password authentication -@cindex Login (subcommand) -@cindex Password client, using -@cindex Authenticated client, using -@cindex :pserver:, setting up -To run a @sc{cvs} command on a remote repository via -the password-authenticating server, one specifies the -@code{pserver} protocol, optional username, repository host, an -optional port number, and path to the repository. For example: - -@example -cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj -@end example - -@noindent -or - -@example -CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot -cvs checkout someproj -@end example - -However, unless you're connecting to a public-access -repository (i.e., one where that username doesn't -require a password), you'll need to supply a password or @dfn{log in} first. -Logging in verifies your password with the repository and stores it in a file. -It's done with the @code{login} command, which will -prompt you interactively for the password if you didn't supply one as part of -@var{$CVSROOT}: - -@example -cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login -CVS password: -@end example - -@noindent -or - -@example -cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login -@end example - -After you enter the password, @sc{cvs} verifies it with -the server. If the verification succeeds, then that -combination of username, host, repository, and password -is permanently recorded, so future transactions with -that repository won't require you to run @code{cvs -login}. (If verification fails, @sc{cvs} will exit -complaining that the password was incorrect, and -nothing will be recorded.) - -The records are stored, by default, in the file -@file{$HOME/.cvspass}. That file's format is -human-readable, and to a degree human-editable, but -note that the passwords are not stored in -cleartext---they are trivially encoded to protect them -from "innocent" compromise (i.e., inadvertent viewing -by a system administrator or other non-malicious -person). - -@cindex CVS_PASSFILE, environment variable -You can change the default location of this file by -setting the @code{CVS_PASSFILE} environment variable. -If you use this variable, make sure you set it -@emph{before} @code{cvs login} is run. If you were to -set it after running @code{cvs login}, then later -@sc{cvs} commands would be unable to look up the -password for transmission to the server. - -Once you have logged in, all @sc{cvs} commands using -that remote repository and username will authenticate -with the stored password. So, for example - -@example -cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo -@end example - -@noindent -should just work (unless the password changes on the -server side, in which case you'll have to re-run -@code{cvs login}). - -Note that if the @samp{:pserver:} were not present in -the repository specification, @sc{cvs} would assume it -should use @code{rsh} to connect with the server -instead (@pxref{Connecting via rsh}). - -Of course, once you have a working copy checked out and -are running @sc{cvs} commands from within it, there is -no longer any need to specify the repository -explicitly, because @sc{cvs} can deduce the repository -from the working copy's @file{CVS} subdirectory. - -@c FIXME: seems to me this needs somewhat more -@c explanation. -@cindex Logout (subcommand) -The password for a given remote repository can be -removed from the @code{CVS_PASSFILE} by using the -@code{cvs logout} command. - -@node Password authentication security -@subsubsection Security considerations with password authentication - -@cindex Security, of pserver -The passwords are stored on the client side in a -trivial encoding of the cleartext, and transmitted in -the same encoding. The encoding is done only to -prevent inadvertent password compromises (i.e., a -system administrator accidentally looking at the file), -and will not prevent even a naive attacker from gaining -the password. - -@c FIXME: The bit about "access to the repository -@c implies general access to the system is *not* specific -@c to pserver; it applies to kerberos and SSH and -@c everything else too. Should reorganize the -@c documentation to make this clear. -The separate @sc{cvs} password file (@pxref{Password -authentication server}) allows people -to use a different password for repository access than -for login access. On the other hand, once a user has -non-read-only -access to the repository, she can execute programs on -the server system through a variety of means. Thus, repository -access implies fairly broad system access as well. It -might be possible to modify @sc{cvs} to prevent that, -but no one has done so as of this writing. -@c OpenBSD uses chroot() and copies the repository to -@c provide anonymous read-only access (for details see -@c http://www.openbsd.org/anoncvs.shar). While this -@c closes the most obvious holes, I'm not sure it -@c closes enough holes to recommend it (plus it is -@c *very* easy to accidentally screw up a setup of this -@c type). - -Note that because the @file{$CVSROOT/CVSROOT} directory -contains @file{passwd} and other files which are used -to check security, you must control the permissions on -this directory as tightly as the permissions on -@file{/etc}. The same applies to the @file{$CVSROOT} -directory itself and any directory -above it in the tree. Anyone who has write access to -such a directory will have the ability to become any -user on the system. Note that these permissions are -typically tighter than you would use if you are not -using pserver. -@c TODO: Would be really nice to document/implement a -@c scheme where the CVS server can run as some non-root -@c user, e.g. "cvs". CVSROOT/passwd would contain a -@c bunch of entries of the form foo:xxx:cvs (or the "cvs" -@c would be implicit). This would greatly reduce -@c security risks such as those hinted at in the -@c previous paragraph. I think minor changes to CVS -@c might be required but mostly this would just need -@c someone who wants to play with it, document it, &c. - -In summary, anyone who gets the password gets -repository access (which may imply some measure of general system -access as well). The password is available to anyone -who can sniff network packets or read a protected -(i.e., user read-only) file. If you want real -security, get Kerberos. - -@node GSSAPI authenticated -@subsection Direct connection with GSSAPI - -@cindex GSSAPI -@cindex Security, GSSAPI -@cindex :gserver:, setting up -@cindex Kerberos, using :gserver: -GSSAPI is a generic interface to network security -systems such as Kerberos 5. -If you have a working GSSAPI library, you can have -@sc{cvs} connect via a direct @sc{tcp} connection, -authenticating with GSSAPI. - -To do this, @sc{cvs} needs to be compiled with GSSAPI -support; when configuring @sc{cvs} it tries to detect -whether GSSAPI libraries using Kerberos version 5 are -present. You can also use the @file{--with-gssapi} -flag to configure. - -The connection is authenticated using GSSAPI, but the -message stream is @emph{not} authenticated by default. -You must use the @code{-a} global option to request -stream authentication. - -The data transmitted is @emph{not} encrypted by -default. Encryption support must be compiled into both -the client and the server; use the -@file{--enable-encrypt} configure option to turn it on. -You must then use the @code{-x} global option to -request encryption. - -GSSAPI connections are handled on the server side by -the same server which handles the password -authentication server; see @ref{Password authentication -server}. If you are using a GSSAPI mechanism such as -Kerberos which provides for strong authentication, you -will probably want to disable the ability to -authenticate via cleartext passwords. To do so, create -an empty @file{CVSROOT/passwd} password file, and set -@code{SystemAuth=no} in the config file -(@pxref{config}). - -The GSSAPI server uses a principal name of -cvs/@var{hostname}, where @var{hostname} is the -canonical name of the server host. You will have to -set this up as required by your GSSAPI mechanism. - -To connect using GSSAPI, use the @samp{:gserver:} method. For -example, - -@example -cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo -@end example - -@node Kerberos authenticated -@subsection Direct connection with Kerberos - -@cindex Kerberos, using :kserver: -@cindex Security, Kerberos -@cindex :kserver:, setting up -The easiest way to use Kerberos is to use the Kerberos -@code{rsh}, as described in @ref{Connecting via rsh}. -The main disadvantage of using rsh is that all the data -needs to pass through additional programs, so it may be -slower. So if you have Kerberos installed you can -connect via a direct @sc{tcp} connection, -authenticating with Kerberos. - -This section concerns the Kerberos network security -system, version 4. Kerberos version 5 is supported via -the GSSAPI generic network security interface, as -described in the previous section. - -To do this, @sc{cvs} needs to be compiled with Kerberos -support; when configuring @sc{cvs} it tries to detect -whether Kerberos is present or you can use the -@file{--with-krb4} flag to configure. - -The data transmitted is @emph{not} encrypted by -default. Encryption support must be compiled into both -the client and server; use the -@file{--enable-encryption} configure option to turn it -on. You must then use the @code{-x} global option to -request encryption. - -@cindex CVS_CLIENT_PORT -You need to edit @file{inetd.conf} on the server -machine to run @code{cvs kserver}. The client uses -port 1999 by default; if you want to use another port -specify it in the @code{CVSROOT} (@pxref{Remote repositories}) -or the @code{CVS_CLIENT_PORT} environment variable -(@pxref{Environment variables}) on the client. - -@cindex kinit -When you want to use @sc{cvs}, get a ticket in the -usual way (generally @code{kinit}); it must be a ticket -which allows you to log into the server machine. Then -you are ready to go: - -@example -cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo -@end example - -Previous versions of @sc{cvs} would fall back to a -connection via rsh; this version will not do so. - -@node Connecting via fork -@subsection Connecting with fork - -@cindex fork, access method -@cindex :fork:, setting up -This access method allows you to connect to a -repository on your local disk via the remote protocol. -In other words it does pretty much the same thing as -@code{:local:}, but various quirks, bugs and the like are -those of the remote @sc{cvs} rather than the local -@sc{cvs}. - -For day-to-day operations you might prefer either -@code{:local:} or @code{:fork:}, depending on your -preferences. Of course @code{:fork:} comes in -particularly handy in testing or -debugging @code{cvs} and the remote protocol. -Specifically, we avoid all of the network-related -setup/configuration, timeouts, and authentication -inherent in the other remote access methods but still -create a connection which uses the remote protocol. - -To connect using the @code{fork} method, use -@samp{:fork:} and the pathname to your local -repository. For example: - -@example -cvs -d :fork:/usr/local/cvsroot checkout foo -@end example - -@cindex CVS_SERVER, and :fork: -As with @code{:ext:}, the server is called @samp{cvs} -by default, or the value of the @code{CVS_SERVER} -environment variable. - -@c --------------------------------------------------------------------- -@node Read-only access -@section Read-only repository access -@cindex Read-only repository access -@cindex readers (admin file) -@cindex writers (admin file) - - It is possible to grant read-only repository -access to people using the password-authenticated -server (@pxref{Password authenticated}). (The -other access methods do not have explicit support for -read-only users because those methods all assume login -access to the repository machine anyway, and therefore -the user can do whatever local file permissions allow -her to do.) - - A user who has read-only access can do only -those @sc{cvs} operations which do not modify the -repository, except for certain ``administrative'' files -(such as lock files and the history file). It may be -desirable to use this feature in conjunction with -user-aliasing (@pxref{Password authentication server}). - -Unlike with previous versions of @sc{cvs}, read-only -users should be able merely to read the repository, and -not to execute programs on the server or otherwise gain -unexpected levels of access. Or to be more accurate, -the @emph{known} holes have been plugged. Because this -feature is new and has not received a comprehensive -security audit, you should use whatever level of -caution seems warranted given your attitude concerning -security. - - There are two ways to specify read-only access -for a user: by inclusion, and by exclusion. - - "Inclusion" means listing that user -specifically in the @file{$CVSROOT/CVSROOT/readers} -file, which is simply a newline-separated list of -users. Here is a sample @file{readers} file: - -@example -melissa -splotnik -jrandom -@end example - -@noindent - (Don't forget the newline after the last user.) - - "Exclusion" means explicitly listing everyone -who has @emph{write} access---if the file - -@example -$CVSROOT/CVSROOT/writers -@end example - -@noindent -exists, then only -those users listed in it have write access, and -everyone else has read-only access (of course, even the -read-only users still need to be listed in the -@sc{cvs} @file{passwd} file). The -@file{writers} file has the same format as the -@file{readers} file. - - Note: if your @sc{cvs} @file{passwd} -file maps cvs users onto system users (@pxref{Password -authentication server}), make sure you deny or grant -read-only access using the @emph{cvs} usernames, not -the system usernames. That is, the @file{readers} and -@file{writers} files contain cvs usernames, which may -or may not be the same as system usernames. - - Here is a complete description of the server's -behavior in deciding whether to grant read-only or -read-write access: - - If @file{readers} exists, and this user is -listed in it, then she gets read-only access. Or if -@file{writers} exists, and this user is NOT listed in -it, then she also gets read-only access (this is true -even if @file{readers} exists but she is not listed -there). Otherwise, she gets full read-write access. - - Of course there is a conflict if the user is -listed in both files. This is resolved in the more -conservative way, it being better to protect the -repository too much than too little: such a user gets -read-only access. - -@node Server temporary directory -@section Temporary directories for the server -@cindex Temporary directories, and server -@cindex Server, temporary directories - -While running, the @sc{cvs} server creates temporary -directories. They are named - -@example -cvs-serv@var{pid} -@end example - -@noindent -where @var{pid} is the process identification number of -the server. -They are located in the directory specified by -the @samp{-T} global option (@pxref{Global options}), -the @code{TMPDIR} environment variable (@pxref{Environment variables}), -or, failing that, @file{/tmp}. - -In most cases the server will remove the temporary -directory when it is done, whether it finishes normally -or abnormally. However, there are a few cases in which -the server does not or cannot remove the temporary -directory, for example: - -@itemize @bullet -@item -If the server aborts due to an internal server error, -it may preserve the directory to aid in debugging - -@item -If the server is killed in a way that it has no way of -cleaning up (most notably, @samp{kill -KILL} on unix). - -@item -If the system shuts down without an orderly shutdown, -which tells the server to clean up. -@end itemize - -In cases such as this, you will need to manually remove -the @file{cvs-serv@var{pid}} directories. As long as -there is no server running with process identification -number @var{pid}, it is safe to do so. - -@c --------------------------------------------------------------------- -@node Starting a new project -@chapter Starting a project with CVS -@cindex Starting a project with CVS -@cindex Creating a project - -@comment --moduledb-- -Because renaming files and moving them between -directories is somewhat inconvenient, the first thing -you do when you start a new project should be to think -through your file organization. It is not impossible -to rename or move files, but it does increase the -potential for confusion and @sc{cvs} does have some -quirks particularly in the area of renaming -directories. @xref{Moving files}. - -What to do next depends on the situation at hand. - -@menu -* Setting up the files:: Getting the files into the repository -* Defining the module:: How to make a module of the files -@end menu -@c -- File permissions! - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Setting up the files -@section Setting up the files - -The first step is to create the files inside the repository. This can -be done in a couple of different ways. - -@c -- The contributed scripts -@menu -* From files:: This method is useful with old projects - where files already exists. -* From other version control systems:: Old projects where you want to - preserve history from another system. -* From scratch:: Creating a directory tree from scratch. -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node From files -@subsection Creating a directory tree from a number of files -@cindex Importing files - -When you begin using @sc{cvs}, you will probably already have several -projects that can be -put under @sc{cvs} control. In these cases the easiest way is to use the -@code{import} command. An example is probably the easiest way to -explain how to use it. If the files you want to install in -@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the -repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: - -@example -$ cd @var{wdir} -$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start -@end example - -Unless you supply a log message with the @samp{-m} -flag, @sc{cvs} starts an editor and prompts for a -message. The string @samp{yoyo} is a @dfn{vendor tag}, -and @samp{start} is a @dfn{release tag}. They may fill -no purpose in this context, but since @sc{cvs} requires -them they must be present. @xref{Tracking sources}, for -more information about them. - -You can now verify that it worked, and remove your -original source directory. -@c FIXME: Need to say more about "verify that it -@c worked". What should the user look for in the output -@c from "diff -r"? - -@example -$ cd .. -$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} -$ diff -r @var{wdir} yoyodyne/@var{rdir} -$ rm -r @var{wdir} -@end example - -@noindent -Erasing the original sources is a good idea, to make sure that you do -not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. -Of course, it would be wise to make sure that you have -a backup of the sources before you remove them. - -The @code{checkout} command can either take a module -name as argument (as it has done in all previous -examples) or a path name relative to @code{$CVSROOT}, -as it did in the example above. - -It is a good idea to check that the permissions -@sc{cvs} sets on the directories inside @code{$CVSROOT} -are reasonable, and that they belong to the proper -groups. @xref{File permissions}. - -If some of the files you want to import are binary, you -may want to use the wrappers features to specify which -files are binary and which are not. @xref{Wrappers}. - -@c The node name is too long, but I am having trouble -@c thinking of something more concise. -@node From other version control systems -@subsection Creating Files From Other Version Control Systems -@cindex Importing files, from other version control systems - -If you have a project which you are maintaining with -another version control system, such as @sc{rcs}, you -may wish to put the files from that project into -@sc{cvs}, and preserve the revision history of the -files. - -@table @asis -@cindex RCS, importing files from -@item From RCS -If you have been using @sc{rcs}, find the @sc{rcs} -files---usually a file named @file{foo.c} will have its -@sc{rcs} file in @file{RCS/foo.c,v} (but it could be -other places; consult the @sc{rcs} documentation for -details). Then create the appropriate directories in -@sc{cvs} if they do not already exist. Then copy the -files into the appropriate directories in the @sc{cvs} -repository (the name in the repository must be the name -of the source file with @samp{,v} added; the files go -directly in the appropriate directory of the repository, -not in an @file{RCS} subdirectory). This is one of the -few times when it is a good idea to access the @sc{cvs} -repository directly, rather than using @sc{cvs} -commands. Then you are ready to check out a new -working directory. -@c Someday there probably should be a "cvs import -t -@c rcs" or some such. It could even create magic -@c branches. It could also do something about the case -@c where the RCS file had a (non-magic) "0" branch. - -The @sc{rcs} file should not be locked when you move it -into @sc{cvs}; if it is, @sc{cvs} will have trouble -letting you operate on it. -@c What is the easiest way to unlock your files if you -@c have them locked? Especially if you have a lot of them? -@c This is a CVS bug/misfeature; importing RCS files -@c should ignore whether they are locked and leave them in -@c an unlocked state. Yet another reason for a separate -@c "import RCS file" command. - -@c How many is "many"? Or do they just import RCS files? -@item From another version control system -Many version control systems have the ability to export -@sc{rcs} files in the standard format. If yours does, -export the @sc{rcs} files and then follow the above -instructions. - -Failing that, probably your best bet is to write a -script that will check out the files one revision at a -time using the command line interface to the other -system, and then check the revisions into @sc{cvs}. -The @file{sccs2rcs} script mentioned below may be a -useful example to follow. - -@cindex SCCS, importing files from -@item From SCCS -There is a script in the @file{contrib} directory of -the @sc{cvs} source distribution called @file{sccs2rcs} -which converts @sc{sccs} files to @sc{rcs} files. -Note: you must run it on a machine which has both -@sc{sccs} and @sc{rcs} installed, and like everything -else in contrib it is unsupported (your mileage may -vary). - -@cindex PVCS, importing files from -@item From PVCS -There is a script in the @file{contrib} directory of -the @sc{cvs} source distribution called @file{pvcs_to_rcs} -which converts @sc{pvcs} archives to @sc{rcs} files. -You must run it on a machine which has both -@sc{pvcs} and @sc{rcs} installed, and like everything -else in contrib it is unsupported (your mileage may -vary). See the comments in the script for details. -@end table -@c CMZ and/or PATCHY were systems that were used in the -@c high energy physics community (especially for -@c CERNLIB). CERN has replaced them with CVS, but the -@c CAR format seems to live on as a way to submit -@c changes. There is a program car2cvs which converts -@c but I'm not sure where one gets a copy. -@c Not sure it is worth mentioning here, since it would -@c appear to affect only one particular community. -@c Best page for more information is: -@c http://wwwcn1.cern.ch/asd/cvs/index.html -@c See also: -@c http://ecponion.cern.ch/ecpsa/cernlib.html - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node From scratch -@subsection Creating a directory tree from scratch - -@c Also/instead should be documenting -@c $ cvs co -l . -@c $ mkdir tc -@c $ cvs add tc -@c $ cd tc -@c $ mkdir man -@c $ cvs add man -@c etc. -@c Using import to create the directories only is -@c probably a somewhat confusing concept. -For a new project, the easiest thing to do is probably -to create an empty directory structure, like this: - -@example -$ mkdir tc -$ mkdir tc/man -$ mkdir tc/testing -@end example - -After that, you use the @code{import} command to create -the corresponding (empty) directory structure inside -the repository: - -@example -$ cd tc -$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start -@end example - -This will add yoyodyne/@var{dir} as a directory under -@code{$CVSROOT}. - -Use @code{checkout} to get the new project. Then, use @code{add} -to add files (and new directories) as needed. - -@example -$ cd .. -$ cvs co yoyodyne/@var{dir} -@end example - -Check that the permissions @sc{cvs} sets on the -directories inside @code{$CVSROOT} are reasonable. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Defining the module -@section Defining the module -@cindex Defining a module -@cindex Editing the modules file -@cindex Module, defining -@cindex Modules file, changing - -The next step is to define the module in the -@file{modules} file. This is not strictly necessary, -but modules can be convenient in grouping together -related files and directories. - -In simple cases these steps are sufficient to define a module. - -@enumerate -@item -Get a working copy of the modules file. - -@example -$ cvs checkout CVSROOT/modules -$ cd CVSROOT -@end example - -@item -Edit the file and insert a line that defines the module. @xref{Intro -administrative files}, for an introduction. @xref{modules}, for a full -description of the modules file. You can use the -following line to define the module @samp{tc}: - -@example -tc yoyodyne/tc -@end example - -@item -Commit your changes to the modules file. - -@example -$ cvs commit -m "Added the tc module." modules -@end example - -@item -Release the modules module. - -@example -$ cd .. -$ cvs release -d CVSROOT -@end example -@end enumerate - -@c --------------------------------------------------------------------- -@node Revisions -@chapter Revisions - -For many uses of @sc{cvs}, one doesn't need to worry -too much about revision numbers; @sc{cvs} assigns -numbers such as @code{1.1}, @code{1.2}, and so on, and -that is all one needs to know. However, some people -prefer to have more knowledge and control concerning -how @sc{cvs} assigns revision numbers. - -If one wants to keep track of a set of revisions -involving more than one file, such as which revisions -went into a particular release, one uses a @dfn{tag}, -which is a symbolic revision which can be assigned to a -numeric revision in each file. - -@menu -* Revision numbers:: The meaning of a revision number -* Versions revisions releases:: Terminology used in this manual -* Assigning revisions:: Assigning revisions -* Tags:: Tags--Symbolic revisions -* Tagging the working directory:: The cvs tag command -* Tagging by date/tag:: The cvs rtag command -* Modifying tags:: Adding, renaming, and deleting tags -* Tagging add/remove:: Tags with adding and removing files -* Sticky tags:: Certain tags are persistent -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Revision numbers -@section Revision numbers -@cindex Revision numbers -@cindex Revision tree -@cindex Linear development -@cindex Number, revision- -@cindex Decimal revision number -@cindex Branch number -@cindex Number, branch - -Each version of a file has a unique @dfn{revision -number}. Revision numbers look like @samp{1.1}, -@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. -A revision number always has an even number of -period-separated decimal integers. By default revision -1.1 is the first revision of a file. Each successive -revision is given a new number by increasing the -rightmost number by one. The following figure displays -a few revisions, with newer revisions to the right. - -@example - +-----+ +-----+ +-----+ +-----+ +-----+ - ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! - +-----+ +-----+ +-----+ +-----+ +-----+ -@end example - -It is also possible to end up with numbers containing -more than one period, for example @samp{1.3.2.2}. Such -revisions represent revisions on branches -(@pxref{Branching and merging}); such revision numbers -are explained in detail in @ref{Branches and -revisions}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Versions revisions releases -@section Versions, revisions and releases -@cindex Revisions, versions and releases -@cindex Versions, revisions and releases -@cindex Releases, revisions and versions - -A file can have several versions, as described above. -Likewise, a software product can have several versions. -A software product is often given a version number such -as @samp{4.1.1}. - -Versions in the first sense are called @dfn{revisions} -in this document, and versions in the second sense are -called @dfn{releases}. To avoid confusion, the word -@dfn{version} is almost never used in this document. - -@node Assigning revisions -@section Assigning revisions - -@c We avoid the "major revision" terminology. It seems -@c like jargon. Hopefully "first number" is clear enough. -By default, @sc{cvs} will assign numeric revisions by -leaving the first number the same and incrementing the -second number. For example, @code{1.1}, @code{1.2}, -@code{1.3}, etc. - -When adding a new file, the second number will always -be one and the first number will equal the highest -first number of any file in that directory. For -example, the current directory contains files whose -highest numbered revisions are @code{1.7}, @code{3.1}, -and @code{4.12}, then an added file will be given the -numeric revision @code{4.1}. -(When using client/server @sc{cvs}, -only files that are actually sent to the server are considered.) - -@c This is sort of redundant with something we said a -@c while ago. Somewhere we need a better way of -@c introducing how the first number can be anything -@c except "1", perhaps. Also I don't think this -@c presentation is clear on why we are discussing releases -@c and first numbers of numeric revisions in the same -@c breath. -Normally there is no reason to care -about the revision numbers---it is easier to treat them -as internal numbers that @sc{cvs} maintains, and tags -provide a better way to distinguish between things like -release 1 versus release 2 of your product -(@pxref{Tags}). However, if you want to set the -numeric revisions, the @samp{-r} option to @code{cvs -commit} can do that. The @samp{-r} option implies the -@samp{-f} option, in the sense that it causes the -files to be committed even if they are not modified. - -For example, to bring all your files up to -revision 3.0 (including those that haven't changed), -you might invoke: - -@example -$ cvs commit -r 3.0 -@end example - -Note that the number you specify with @samp{-r} must be -larger than any existing revision number. That is, if -revision 3.0 exists, you cannot @samp{cvs commit --r 1.3}. If you want to maintain several releases in -parallel, you need to use a branch (@pxref{Branching and merging}). - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Tags -@section Tags--Symbolic revisions -@cindex Tags - -The revision numbers live a life of their own. They -need not have anything at all to do with the release -numbers of your software product. Depending -on how you use @sc{cvs} the revision numbers might change several times -between two releases. As an example, some of the -source files that make up @sc{rcs} 5.6 have the following -revision numbers: -@cindex RCS revision numbers - -@example -ci.c 5.21 -co.c 5.9 -ident.c 5.3 -rcs.c 5.12 -rcsbase.h 5.11 -rcsdiff.c 5.10 -rcsedit.c 5.11 -rcsfcmp.c 5.9 -rcsgen.c 5.10 -rcslex.c 5.11 -rcsmap.c 5.2 -rcsutil.c 5.10 -@end example - -@cindex tag, command, introduction -@cindex Tag, symbolic name -@cindex Symbolic name (tag) -@cindex Name, symbolic (tag) -@cindex HEAD, as reserved tag name -@cindex BASE, as reserved tag name -You can use the @code{tag} command to give a symbolic name to a -certain revision of a file. You can use the @samp{-v} flag to the -@code{status} command to see all tags that a file has, and -which revision numbers they represent. Tag names must -start with an uppercase or lowercase letter and can -contain uppercase and lowercase letters, digits, -@samp{-}, and @samp{_}. The two tag names @code{BASE} -and @code{HEAD} are reserved for use by @sc{cvs}. It -is expected that future names which are special to -@sc{cvs} will be specially named, for example by -starting with @samp{.}, rather than being named analogously to -@code{BASE} and @code{HEAD}, to avoid conflicts with -actual tag names. -@c Including a character such as % or = has also been -@c suggested as the naming convention for future -@c special tag names. Starting with . is nice because -@c that is not a legal tag name as far as RCS is concerned. -@c FIXME: CVS actually accepts quite a few characters -@c in tag names, not just the ones documented above -@c (see RCS_check_tag). RCS -@c defines legitimate tag names by listing illegal -@c characters rather than legal ones. CVS is said to lose its -@c mind if you try to use "/" (try making such a tag sticky -@c and using "cvs status" client/server--see remote -@c protocol format for entries line for probable cause). -@c TODO: The testsuite -@c should test for whatever are documented above as -@c officially-OK tag names, and CVS should at least reject -@c characters that won't work, like "/". - -You'll want to choose some convention for naming tags, -based on information such as the name of the program -and the version number of the release. For example, -one might take the name of the program, immediately -followed by the version number with @samp{.} changed to -@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name -@code{cvs1-9}. If you choose a consistent convention, -then you won't constantly be guessing whether a tag is -@code{cvs-1-9} or @code{cvs1_9} or what. You might -even want to consider enforcing your convention in the -@file{taginfo} file (@pxref{taginfo}). -@c Might be nice to say more about using taginfo this -@c way, like giving an example, or pointing out any particular -@c issues which arise. - -@cindex Adding a tag -@cindex Tag, example -The following example shows how you can add a tag to a -file. The commands must be issued inside your working -directory. That is, you should issue the -command in the directory where @file{backend.c} -resides. - -@example -$ cvs tag rel-0-4 backend.c -T backend.c -$ cvs status -v backend.c -=================================================================== -File: backend.c Status: Up-to-date - - Version: 1.4 Tue Dec 1 14:39:01 1992 - RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v - Sticky Tag: (none) - Sticky Date: (none) - Sticky Options: (none) - - Existing Tags: - rel-0-4 (revision: 1.4) - -@end example - -For a complete summary of the syntax of @code{cvs tag}, -including the various options, see @ref{Invoking CVS}. - -There is seldom reason to tag a file in isolation. A more common use is -to tag all the files that constitute a module with the same tag at -strategic points in the development life-cycle, such as when a release -is made. - -@example -$ cvs tag rel-1-0 . -cvs tag: Tagging . -T Makefile -T backend.c -T driver.c -T frontend.c -T parser.c -@end example - -@noindent -(When you give @sc{cvs} a directory as argument, it generally applies the -operation to all the files in that directory, and (recursively), to any -subdirectories that it may contain. @xref{Recursive behavior}.) - -@cindex Retrieving an old revision using tags -@cindex Tag, retrieving old revisions -The @code{checkout} command has a flag, @samp{-r}, that lets you check out -a certain revision of a module. This flag makes it easy to -retrieve the sources that make up release 1.0 of the module @samp{tc} at -any time in the future: - -@example -$ cvs checkout -r rel-1-0 tc -@end example - -@noindent -This is useful, for instance, if someone claims that there is a bug in -that release, but you cannot find the bug in the current working copy. - -You can also check out a module as it was at any given date. -@xref{checkout options}. When specifying @samp{-r} to -any of these commands, you will need beware of sticky -tags; see @ref{Sticky tags}. - -When you tag more than one file with the same tag you -can think about the tag as "a curve drawn through a -matrix of filename vs.@: revision number." Say we have 5 -files with the following revisions: - -@example -@group - 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 -@end group -@end example - -At some time in the past, the @code{*} versions were tagged. -You can 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 "sight" through a set of -revisions that is "flat" along the tagged revisions, -like this: - -@example -@group - 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 -@end group -@end example - -@node Tagging the working directory -@section Specifying what to tag from the working directory - -@cindex tag (subcommand) -The example in the previous section demonstrates one of -the most common ways to choose which revisions to tag. -Namely, running the @code{cvs tag} command without -arguments causes @sc{cvs} to select the revisions which -are checked out in the current working directory. For -example, if the copy of @file{backend.c} in working -directory was checked out from revision 1.4, then -@sc{cvs} will tag revision 1.4. Note that the tag is -applied immediately to revision 1.4 in the repository; -tagging is not like modifying a file, or other -operations in which one first modifies the working -directory and then runs @code{cvs commit} to transfer -that modification to the repository. - -One potentially surprising aspect of the fact that -@code{cvs tag} operates on the repository is that you -are tagging the checked-in revisions, which may differ -from locally modified files in your working directory. -If you want to avoid doing this by mistake, specify the -@samp{-c} option to @code{cvs tag}. If there are any -locally modified files, @sc{cvs} will abort with an -error before it tags any files: - -@example -$ cvs tag -c rel-0-4 -cvs tag: backend.c is locally modified -cvs [tag aborted]: correct the above errors first! -@end example - -@node Tagging by date/tag -@section Specifying what to tag by date or revision -@cindex rtag (subcommand) - -The @code{cvs rtag} command tags the repository as of a -certain date or time (or can be used to tag the latest -revision). @code{rtag} works directly on the -repository contents (it requires no prior checkout and -does not look for a working directory). - -The following options specify which date or revision to -tag. See @ref{Common options}, for a complete -description of them. - -@table @code -@item -D @var{date} -Tag the most recent revision no later than @var{date}. - -@item -f -Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}} -flags. If no matching revision is found, use the most -recent revision (instead of ignoring the file). - -@item -r @var{tag} -Only tag those files that contain existing tag @var{tag}. -@end table - -The @code{cvs tag} command also allows one to specify -files by revision or date, using the same @samp{-r}, -@samp{-D}, and @samp{-f} options. However, this -feature is probably not what you want. The reason is -that @code{cvs tag} chooses which files to tag based on -the files that exist in the working directory, rather -than the files which existed as of the given tag/date. -Therefore, you are generally better off using @code{cvs -rtag}. The exceptions might be cases like: - -@example -cvs tag -r 1.4 backend.c -@end example - -@node Modifying tags -@section Deleting, moving, and renaming tags - -@c Also see: -@c "How do I move or rename a magic branch tag?" -@c in the FAQ (I think the issues it talks about still -@c apply, but this could use some sanity.sh work). - -Normally one does not modify tags. They exist in order -to record the history of the repository and so deleting -them or changing their meaning would, generally, not be -what you want. - -However, there might be cases in which one uses a tag -temporarily or accidentally puts one in the wrong -place. Therefore, one might delete, move, or rename a -tag. - -@noindent -@strong{WARNING: The commands in this section are -dangerous; they permanently discard historical -information and it can be difficult or impossible to -recover from errors. If you are a @sc{cvs} -administrator, you may consider restricting these -commands with the @file{taginfo} file (@pxref{taginfo}).} - -@cindex Deleting tags -@cindex Deleting branch tags -@cindex Removing tags -@cindex Removing branch tags -@cindex Tags, deleting -@cindex Branch tags, deleting -To delete a tag, specify the @samp{-d} option to either -@code{cvs tag} or @code{cvs rtag}. For example: - -@example -cvs rtag -d rel-0-4 tc -@end example - -@noindent -deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. -In the event that branch tags are encountered within the repository -with the given name, a warning message will be issued and the branch -tag will not be deleted. If you are absolutely certain you know what -you are doing, the @code{-B} option may be specified to allow deletion -of branch tags. In that case, any non-branch tags encountered will -trigger warnings and will not be deleted. - -@noindent -@strong{WARNING: Moving branch tags is very dangerous! If you think -you need the @code{-B} option, think again and ask your @sc{cvs} -administrator about it (if that isn't you). There is almost certainly -another way to accomplish what you want to accomplish.} - -@cindex Moving tags -@cindex Moving branch tags -@cindex Tags, moving -@cindex Branch tags, moving -When we say @dfn{move} a tag, we mean to make the same -name point to different revisions. For example, the -@code{stable} tag may currently point to revision 1.4 -of @file{backend.c} and perhaps we want to make it -point to revision 1.6. To move a non-branch tag, specify the -@samp{-F} option to either @code{cvs tag} or @code{cvs -rtag}. For example, the task just mentioned might be -accomplished as: - -@example -cvs tag -r 1.6 -F stable backend.c -@end example - -@noindent -If any branch tags are encountered in the repository -with the given name, a warning is issued and the branch -tag is not disturbed. If you are absolutely certain you -wish to move the branch tag, the @code{-B} option may be specified. -In that case, non-branch tags encountered with the given -name are ignored with a warning message. - -@noindent -@strong{WARNING: Moving branch tags is very dangerous! If you think you -need the @code{-B} option, think again and ask your @sc{cvs} -administrator about it (if that isn't you). There is almost certainly -another way to accomplish what you want to accomplish.} - -@cindex Renaming tags -@cindex Tags, renaming -When we say @dfn{rename} a tag, we mean to make a -different name point to the same revisions as the old -tag. For example, one may have misspelled the tag name -and want to correct it (hopefully before others are -relying on the old spelling). To rename a tag, first -create a new tag using the @samp{-r} option to -@code{cvs rtag}, and then delete the old name. (Caution: -this method will not work with branch tags.) -This leaves the new tag on exactly the -same files as the old tag. For example: - -@example -cvs rtag -r old-name-0-4 rel-0-4 tc -cvs rtag -d old-name-0-4 tc -@end example - -@node Tagging add/remove -@section Tagging and adding and removing files - -The subject of exactly how tagging interacts with -adding and removing files is somewhat obscure; for the -most part @sc{cvs} will keep track of whether files -exist or not without too much fussing. By default, -tags are applied to only files which have a revision -corresponding to what is being tagged. Files which did -not exist yet, or which were already removed, simply -omit the tag, and @sc{cvs} knows to treat the absence -of a tag as meaning that the file didn't exist as of -that tag. - -However, this can lose a small amount of information. -For example, suppose a file was added and then removed. -Then, if the tag is missing for that file, there is no -way to know whether the tag refers to the time before -the file was added, or the time after it was removed. -If you specify the @samp{-r} option to @code{cvs rtag}, -then @sc{cvs} tags the files which have been removed, -and thereby avoids this problem. For example, one -might specify @code{-r HEAD} to tag the head. - -On the subject of adding and removing files, the -@code{cvs rtag} command has a @samp{-a} option which -means to clear the tag from removed files that would -not otherwise be tagged. For example, one might -specify this option in conjunction with @samp{-F} when -moving a tag. If one moved a tag without @samp{-a}, -then the tag in the removed files might still refer to -the old revision, rather than reflecting the fact that -the file had been removed. I don't think this is -necessary if @samp{-r} is specified, as noted above. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Sticky tags -@section Sticky tags -@cindex Sticky tags -@cindex Tags, sticky - -@c A somewhat related issue is per-directory sticky -@c tags (see comment at CVS/Tag in node Working -@c directory storage); we probably want to say -@c something like "you can set a sticky tag for only -@c some files, but you don't want to" or some such. - -Sometimes a working copy's revision has extra data -associated with it, for example it might be on a branch -(@pxref{Branching and merging}), or restricted to -versions prior to a certain date by @samp{checkout -D} -or @samp{update -D}. Because this data persists -- -that is, it applies to subsequent commands in the -working copy -- we refer to it as @dfn{sticky}. - -Most of the time, stickiness is an obscure aspect of -@sc{cvs} that you don't need to think about. However, -even if you don't want to use the feature, you may need -to know @emph{something} about sticky tags (for -example, how to avoid them!). - -You can use the @code{status} command to see if any -sticky tags or dates are set: - -@example -$ cvs status driver.c -=================================================================== -File: driver.c Status: Up-to-date - - Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 - RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v - Sticky Tag: rel-1-0-patches (branch: 1.7.2) - Sticky Date: (none) - Sticky Options: (none) - -@end example - -@cindex Resetting sticky tags -@cindex Sticky tags, resetting -@cindex Deleting sticky tags -The sticky tags will remain on your working files until -you delete them with @samp{cvs update -A}. The -@samp{-A} option merges local changes into the version of the -file from the head of the trunk, removing any sticky tags, -dates, or options (other than sticky @samp{-k} options on locally -modified files). See @ref{update} for more on the operation -of @code{cvs update}. - -@cindex Sticky date -The most common use of sticky tags is to identify which -branch one is working on, as described in -@ref{Accessing branches}. However, non-branch -sticky tags have uses as well. For example, -suppose that you want to avoid updating your working -directory, to isolate yourself from possibly -destabilizing changes other people are making. You -can, of course, just refrain from running @code{cvs -update}. But if you want to avoid updating only a -portion of a larger tree, then sticky tags can help. -If you check out a certain revision (such as 1.4) it -will become sticky. Subsequent @code{cvs update} -commands will -not retrieve the latest revision until you reset the -tag with @code{cvs update -A}. Likewise, use of the -@samp{-D} option to @code{update} or @code{checkout} -sets a @dfn{sticky date}, which, similarly, causes that -date to be used for future retrievals. - -People often want to retrieve an old version of -a file without setting a sticky tag. This can -be done with the @samp{-p} option to @code{checkout} or -@code{update}, which sends the contents of the file to -standard output. For example: -@example -$ cvs update -p -r 1.1 file1 >file1 -=================================================================== -Checking out file1 -RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v -VERS: 1.1 -*************** -$ -@end example - -However, this isn't the easiest way, if you are asking -how to undo a previous checkin (in this example, put -@file{file1} back to the way it was as of revision -1.1). In that case you are better off using the -@samp{-j} option to @code{update}; for further -discussion see @ref{Merging two revisions}. - -@c --------------------------------------------------------------------- -@node Branching and merging -@chapter Branching and merging -@cindex Branching -@cindex Merging -@cindex Copying changes -@cindex Main trunk and branches -@cindex Revision tree, making branches -@cindex Branches, copying changes between -@cindex Changes, copying between branches -@cindex Modifications, copying between branches - -@sc{cvs} allows you to isolate changes onto a separate -line of development, known as a @dfn{branch}. When you -change files on a branch, those changes do not appear -on the main trunk or other branches. - -Later you can move changes from one branch to another -branch (or the main trunk) by @dfn{merging}. Merging -involves first running @code{cvs update -j}, to merge -the changes into the working directory. -You can then commit that revision, and thus effectively -copy the changes onto another branch. - -@menu -* Branches motivation:: What branches are good for -* Creating a branch:: Creating a branch -* Accessing branches:: Checking out and updating branches -* Branches and revisions:: Branches are reflected in revision numbers -* Magic branch numbers:: Magic branch numbers -* Merging a branch:: Merging an entire branch -* Merging more than once:: Merging from a branch several times -* Merging two revisions:: Merging differences between two revisions -* Merging adds and removals:: What if files are added or removed? -* Merging and keywords:: Avoiding conflicts due to keyword substitution -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Branches motivation -@section What branches are good for -@cindex Branches motivation -@cindex What branches are good for -@cindex Motivation for branches - -@c FIXME: this node mentions one way to use branches, -@c but it is by no means the only way. For example, -@c the technique of committing a new feature on a branch, -@c until it is ready for the main trunk. The whole -@c thing is generally speaking more akin to the -@c "Revision management" node although it isn't clear to -@c me whether policy matters should be centralized or -@c distributed throughout the relevant sections. -Suppose that release 1.0 of tc has been made. You are continuing to -develop tc, planning to create release 1.1 in a couple of months. After a -while your customers start to complain about a fatal bug. You check -out release 1.0 (@pxref{Tags}) and find the bug -(which turns out to have a trivial fix). However, the current revision -of the sources are in a state of flux and are not expected to be stable -for at least another month. There is no way to make a -bug fix release based on the newest sources. - -The thing to do in a situation like this is to create a @dfn{branch} on -the revision trees for all the files that make up -release 1.0 of tc. You can then make -modifications to the branch without disturbing the main trunk. When the -modifications are finished you can elect to either incorporate them on -the main trunk, or leave them on the branch. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Creating a branch -@section Creating a branch -@cindex Creating a branch -@cindex Branch, creating a -@cindex tag, creating a branch using -@cindex rtag, creating a branch using - -You can create a branch with @code{tag -b}; for -example, assuming you're in a working copy: - -@example -$ cvs tag -b rel-1-0-patches -@end example - -@c FIXME: we should be more explicit about the value of -@c having a tag on the branchpoint. For example -@c "cvs tag rel-1-0-patches-branchpoint" before -@c the "cvs tag -b". This points out that -@c rel-1-0-patches is a pretty awkward name for -@c this example (more so than for the rtag example -@c below). - -This splits off a branch based on the current revisions -in the working copy, assigning that branch the name -@samp{rel-1-0-patches}. - -It is important to understand that branches get created -in the repository, not in the working copy. Creating a -branch based on current revisions, as the above example -does, will @emph{not} automatically switch the working -copy to be on the new branch. For information on how -to do that, see @ref{Accessing branches}. - -You can also create a branch without reference to any -working copy, by using @code{rtag}: - -@example -$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc -@end example - -@samp{-r rel-1-0} says that this branch should be -rooted at the revision that -corresponds to the tag @samp{rel-1-0}. It need not -be the most recent revision -- it's often useful to -split a branch off an old revision (for example, when -fixing a bug in a past release otherwise known to be -stable). - -As with @samp{tag}, the @samp{-b} flag tells -@code{rtag} to create a branch (rather than just a -symbolic revision name). Note that the numeric -revision number that matches @samp{rel-1-0} will -probably be different from file to file. - -So, the full effect of the command is to create a new -branch -- named @samp{rel-1-0-patches} -- in module -@samp{tc}, rooted in the revision tree at the point tagged -by @samp{rel-1-0}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Accessing branches -@section Accessing branches -@cindex Check out a branch -@cindex Retrieve a branch -@cindex Access a branch -@cindex Identifying a branch -@cindex Branch, check out -@cindex Branch, retrieving -@cindex Branch, accessing -@cindex Branch, identifying - -You can retrieve a branch in one of two ways: by -checking it out fresh from the repository, or by -switching an existing working copy over to the branch. - -To check out a branch from the repository, invoke -@samp{checkout} with the @samp{-r} flag, followed by -the tag name of the branch (@pxref{Creating a branch}): - -@example -$ cvs checkout -r rel-1-0-patches tc -@end example - -Or, if you already have a working copy, you can switch -it to a given branch with @samp{update -r}: - -@example -$ cvs update -r rel-1-0-patches tc -@end example - -@noindent -or equivalently: - -@example -$ cd tc -$ cvs update -r rel-1-0-patches -@end example - -It does not matter if the working copy was originally -on the main trunk or on some other branch -- the above -command will switch it to the named branch. And -similarly to a regular @samp{update} command, -@samp{update -r} merges any changes you have made, -notifying you of conflicts where they occur. - -Once you have a working copy tied to a particular -branch, it remains there until you tell it otherwise. -This means that changes checked in from the working -copy will add new revisions on that branch, while -leaving the main trunk and other branches unaffected. - -@cindex Branches, sticky -To find out what branch a working copy is on, you can -use the @samp{status} command. In its output, look for -the field named @samp{Sticky tag} (@pxref{Sticky tags}) --- that's @sc{cvs}'s way of telling you the branch, if -any, of the current working files: - -@example -$ cvs status -v driver.c backend.c -=================================================================== -File: driver.c Status: Up-to-date - - Version: 1.7 Sat Dec 5 18:25:54 1992 - RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v - Sticky Tag: rel-1-0-patches (branch: 1.7.2) - Sticky Date: (none) - Sticky Options: (none) - - Existing Tags: - rel-1-0-patches (branch: 1.7.2) - rel-1-0 (revision: 1.7) - -=================================================================== -File: backend.c Status: Up-to-date - - Version: 1.4 Tue Dec 1 14:39:01 1992 - RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v - Sticky Tag: rel-1-0-patches (branch: 1.4.2) - Sticky Date: (none) - Sticky Options: (none) - - Existing Tags: - rel-1-0-patches (branch: 1.4.2) - rel-1-0 (revision: 1.4) - rel-0-4 (revision: 1.4) - -@end example - -Don't be confused by the fact that the branch numbers -for each file are different (@samp{1.7.2} and -@samp{1.4.2} respectively). The branch tag is the -same, @samp{rel-1-0-patches}, and the files are -indeed on the same branch. The numbers simply reflect -the point in each file's revision history at which the -branch was made. In the above example, one can deduce -that @samp{driver.c} had been through more changes than -@samp{backend.c} before this branch was created. - -See @ref{Branches and revisions} for details about how -branch numbers are constructed. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Branches and revisions -@section Branches and revisions -@cindex Branch number -@cindex Number, branch -@cindex Revision numbers (branches) - -Ordinarily, a file's revision history is a linear -series of increments (@pxref{Revision numbers}): - -@example - +-----+ +-----+ +-----+ +-----+ +-----+ - ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! - +-----+ +-----+ +-----+ +-----+ +-----+ -@end example - -However, @sc{cvs} is not limited to linear development. The -@dfn{revision tree} can be split into @dfn{branches}, -where each branch is a self-maintained line of -development. Changes made on one branch can easily be -moved back to the main trunk. - -Each branch has a @dfn{branch number}, consisting of an -odd number of period-separated decimal integers. The -branch number is created by appending an integer to the -revision number where the corresponding branch forked -off. Having branch numbers allows more than one branch -to be forked off from a certain revision. - -@need 3500 -All revisions on a branch have revision numbers formed -by appending an ordinal number to the branch number. -The following figure illustrates branching with an -example. - -@example -@c This example used to have a 1.2.2.4 revision, which -@c might help clarify that development can continue on -@c 1.2.2. Might be worth reinstating if it can be done -@c without overfull hboxes. -@group - +-------------+ - Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! - / +-------------+ - / - / - +---------+ +---------+ +---------+ -Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! - / +---------+ +---------+ +---------+ - / - / -+-----+ +-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk -+-----+ +-----+ +-----+ +-----+ +-----+ - ! - ! - ! +---------+ +---------+ +---------+ -Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! - +---------+ +---------+ +---------+ - -@end group -@end example - -@c -- However, at least for me the figure is not enough. I suggest more -@c -- text to accompany it. "A picture is worth a thousand words", so you -@c -- have to make sure the reader notices the couple of hundred words -@c -- *you* had in mind more than the others! - -@c -- Why an even number of segments? This section implies that this is -@c -- how the main trunk is distinguished from branch roots, but you never -@c -- explicitly say that this is the purpose of the [by itself rather -@c -- surprising] restriction to an even number of segments. - -The exact details of how the branch number is -constructed is not something you normally need to be -concerned about, but here is how it works: When -@sc{cvs} creates a branch number it picks the first -unused even integer, starting with 2. So when you want -to create a branch from revision 6.4 it will be -numbered 6.4.2. All branch numbers ending in a zero -(such as 6.4.0) are used internally by @sc{cvs} -(@pxref{Magic branch numbers}). The branch 1.1.1 has a -special meaning. @xref{Tracking sources}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Magic branch numbers -@section Magic branch numbers - -@c Want xref to here from "log"? - -This section describes a @sc{cvs} feature called -@dfn{magic branches}. For most purposes, you need not -worry about magic branches; @sc{cvs} handles them for -you. However, they are visible to you in certain -circumstances, so it may be useful to have some idea of -how it works. - -Externally, branch numbers consist of an odd number of -dot-separated decimal integers. @xref{Revision -numbers}. That is not the whole truth, however. For -efficiency reasons @sc{cvs} sometimes inserts an extra 0 -in the second rightmost position (1.2.4 becomes -1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so -on). - -@sc{cvs} does a pretty good job at hiding these so -called magic branches, but in a few places the hiding -is incomplete: - -@itemize @bullet -@ignore -@c This is in ignore as I'm taking their word for it, -@c that this was fixed -@c a long time ago. But before deleting this -@c entirely, I'd rather verify it (and add a test -@c case to the testsuite). -@item -The magic branch can appear in the output from -@code{cvs status} in vanilla @sc{cvs} 1.3. This is -fixed in @sc{cvs} 1.3-s2. - -@end ignore -@item -The magic branch number appears in the output from -@code{cvs log}. -@c What output should appear instead? - -@item -You cannot specify a symbolic branch name to @code{cvs -admin}. - -@end itemize - -@c Can CVS do this automatically the first time -@c you check something in to that branch? Should -@c it? -You can use the @code{admin} command to reassign a -symbolic name to a branch the way @sc{rcs} expects it -to be. If @code{R4patches} is assigned to the branch -1.4.2 (magic branch number 1.4.0.2) in file -@file{numbers.c} you can do this: - -@example -$ cvs admin -NR4patches:1.4.2 numbers.c -@end example - -It only works if at least one revision is already -committed on the branch. Be very careful so that you -do not assign the tag to the wrong number. (There is -no way to see how the tag was assigned yesterday). - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Merging a branch -@section Merging an entire branch -@cindex Merging a branch -@cindex -j (merging branches) - -You can merge changes made on a branch into your working copy by giving -the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one -@samp{-j @var{branchname}} option it merges the changes made between the -greatest common ancestor (GCA) of the branch and the destination revision (in -the simple case below the GCA is the point where the branch forked) and the -newest revision on that branch into your working copy. - -@cindex Join -The @samp{-j} stands for ``join''. - -@cindex Branch merge example -@cindex Example, branch merge -@cindex Merge, branch example -Consider this revision tree: - -@example -+-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk -+-----+ +-----+ +-----+ +-----+ - ! - ! - ! +---------+ +---------+ -Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! - +---------+ +---------+ -@end example - -@noindent -The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The -following example assumes that the module @samp{mod} contains only one -file, @file{m.c}. - -@example -$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} - -$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} - # @r{i.e. the changes between revision 1.2} - # @r{and 1.2.2.2, into your working copy} - # @r{of the file.} - -$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} -@end example - -A conflict can result from a merge operation. If that -happens, you should resolve it before committing the -new revision. @xref{Conflicts example}. - -If your source files contain keywords (@pxref{Keyword substitution}), -you might be getting more conflicts than strictly necessary. See -@ref{Merging and keywords}, for information on how to avoid this. - -The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The -same effect as above could be achieved with this: - -@example -$ cvs checkout -j R1fix mod -$ cvs commit -m "Included R1fix" -@end example - -It should be noted that @code{update -j @var{tagname}} will also work but may -not produce the desired result. @xref{Merging adds and removals}, for more. - -@node Merging more than once -@section Merging from a branch several times - -Continuing our example, the revision tree now looks -like this: - -@example -+-----+ +-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk -+-----+ +-----+ +-----+ +-----+ +-----+ - ! * - ! * - ! +---------+ +---------+ -Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! - +---------+ +---------+ -@end example - -@noindent -where the starred line represents the merge from the -@samp{R1fix} branch to the main trunk, as just -discussed. - -Now suppose that development continues on the -@samp{R1fix} branch: - -@example -+-----+ +-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk -+-----+ +-----+ +-----+ +-----+ +-----+ - ! * - ! * - ! +---------+ +---------+ +---------+ -Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! - +---------+ +---------+ +---------+ -@end example - -@noindent -and then you want to merge those new changes onto the -main trunk. If you just use the @code{cvs update -j -R1fix m.c} command again, @sc{cvs} will attempt to -merge again the changes which you have already merged, -which can have undesirable side effects. - -So instead you need to specify that you only want to -merge the changes on the branch which have not yet been -merged into the trunk. To do that you specify two -@samp{-j} options, and @sc{cvs} merges the changes from -the first revision to the second revision. For -example, in this case the simplest way would be - -@example -cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} - # @r{head of the R1fix branch} -@end example - -The problem with this is that you need to specify the -1.2.2.2 revision manually. A slightly better approach -might be to use the date the last merge was done: - -@example -cvs update -j R1fix:yesterday -j R1fix m.c -@end example - -Better yet, tag the R1fix branch after every merge into -the trunk, and then use that tag for subsequent merges: - -@example -cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Merging two revisions -@section Merging differences between any two revisions -@cindex Merging two revisions -@cindex Revisions, merging differences between -@cindex Differences, merging - -With two @samp{-j @var{revision}} flags, the @code{update} -(and @code{checkout}) command can merge the differences -between any two revisions into your working file. - -@cindex Undoing a change -@cindex Removing a change -@example -$ cvs update -j 1.5 -j 1.3 backend.c -@end example - -@noindent -will undo all changes made between revision -1.3 and 1.5. Note the order of the revisions! - -If you try to use this option when operating on -multiple files, remember that the numeric revisions will -probably be very different between the various files. -You almost always use symbolic -tags rather than revision numbers when operating on -multiple files. - -@cindex Restoring old version of removed file -@cindex Resurrecting old version of dead file -Specifying two @samp{-j} options can also undo file -removals or additions. For example, suppose you have -a file -named @file{file1} which existed as revision 1.1, and -you then removed it (thus adding a dead revision 1.2). -Now suppose you want to add it again, with the same -contents it had previously. Here is how to do it: - -@example -$ cvs update -j 1.2 -j 1.1 file1 -U file1 -$ cvs commit -m test -Checking in file1; -/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 -new revision: 1.3; previous revision: 1.2 -done -$ -@end example - -@node Merging adds and removals -@section Merging can add or remove files - -If the changes which you are merging involve removing -or adding some files, @code{update -j} will reflect -such additions or removals. - -@c FIXME: This example needs a lot more explanation. -@c We also need other examples for some of the other -@c cases (not all--there are too many--as long as we present a -@c coherent general principle). -For example: -@example -cvs update -A -touch a b c -cvs add a b c ; cvs ci -m "added" a b c -cvs tag -b branchtag -cvs update -r branchtag -touch d ; cvs add d -rm a ; cvs rm a -cvs ci -m "added d, removed a" -cvs update -A -cvs update -jbranchtag -@end example - -After these commands are executed and a @samp{cvs commit} is done, -file @file{a} will be removed and file @file{d} added in the main branch. -@c (which was determined by trying it) - -Note that using a single static tag (@samp{-j @var{tagname}}) -rather than a dynamic tag (@samp{-j @var{branchname}}) to merge -changes from a branch will usually not remove files which were removed on the -branch since @sc{cvs} does not automatically add static tags to dead revisions. -The exception to this rule occurs when -a static tag has been attached to a dead revision manually. Use the branch tag -to merge all changes from the branch or use two static tags as merge endpoints -to be sure that all intended changes are propagated in the merge. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Merging and keywords -@section Merging and keywords -@cindex Merging, and keyword substitution -@cindex Keyword substitution, and merging -@cindex -j (merging branches), and keyword substitution -@cindex -kk, to avoid conflicts during a merge - -If you merge files containing keywords (@pxref{Keyword -substitution}), you will normally get numerous -conflicts during the merge, because the keywords are -expanded differently in the revisions which you are -merging. - -Therefore, you will often want to specify the -@samp{-kk} (@pxref{Substitution modes}) switch to the -merge command line. By substituting just the name of -the keyword, not the expanded value of that keyword, -this option ensures that the revisions which you are -merging will be the same as each other, and avoid -spurious conflicts. - -For example, suppose you have a file like this: - -@example - +---------+ - _! 1.1.2.1 ! <- br1 - / +---------+ - / - / -+-----+ +-----+ -! 1.1 !----! 1.2 ! -+-----+ +-----+ -@end example - -@noindent -and your working directory is currently on the trunk -(revision 1.2). Then you might get the following -results from a merge: - -@example -$ cat file1 -key $@splitrcskeyword{Revision}: 1.2 $ -. . . -$ cvs update -j br1 -U file1 -RCS file: /cvsroot/first-dir/file1,v -retrieving revision 1.1 -retrieving revision 1.1.2.1 -Merging differences between 1.1 and 1.1.2.1 into file1 -rcsmerge: warning: conflicts during merge -$ cat file1 -@asis{}<<<<<<< file1 -key $@splitrcskeyword{Revision}: 1.2 $ -@asis{}======= -key $@splitrcskeyword{Revision}: 1.1.2.1 $ -@asis{}>>>>>>> 1.1.2.1 -. . . -@end example - -What happened was that the merge tried to merge the -differences between 1.1 and 1.1.2.1 into your working -directory. So, since the keyword changed from -@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, -@sc{cvs} tried to merge that change into your working -directory, which conflicted with the fact that your -working directory had contained @code{Revision: 1.2}. - -Here is what happens if you had used @samp{-kk}: - -@example -$ cat file1 -key $@splitrcskeyword{Revision}: 1.2 $ -. . . -$ cvs update -kk -j br1 -U file1 -RCS file: /cvsroot/first-dir/file1,v -retrieving revision 1.1 -retrieving revision 1.1.2.1 -Merging differences between 1.1 and 1.1.2.1 into file1 -$ cat file1 -key $@splitrcskeyword{Revision}$ -. . . -@end example - -What is going on here is that revision 1.1 and 1.1.2.1 -both expand as plain @code{Revision}, and therefore -merging the changes between them into the working -directory need not change anything. Therefore, there -is no conflict. - -There is, however, one major caveat with using -@samp{-kk} on merges. Namely, it overrides whatever -keyword expansion mode @sc{cvs} would normally have -used. In particular, this is a problem if the mode had -been @samp{-kb} for a binary file. Therefore, if your -repository contains binary files, you will need to deal -with the conflicts rather than using @samp{-kk}. - -@ignore -The following seems rather confusing, possibly buggy, -and in general, in need of much more thought before it -is a recommended technique. For one thing, does it -apply on Windows as well as on Unix? - -Unchanged binary files will undergo the same keyword substitution -but will not be checked in on a subsequent -@code{cvs commit}. Be aware that binary files containing keyword -strings which are present in or below the working directory -will most likely remain corrupt until repaired, however. A simple -@code{cvs update -A} is sufficient to fix these otherwise unaltered binary files -if the merge is being done to the main branch but -this must be done after the merge has been committed or the merge itself -will be lost. - -For Example: -@example -cvs update -Akk -jbranchtag -cvs commit -cvs update -A -@end example - -@noindent -will update the current directory from the main trunk of the -repository, substituting the base keyword strings for keywords, -and merge changes made on the branch @samp{branchtag} into the new -work files, performing the same keyword substitution on that file set before -comparing the two sets. The final @code{cvs update -A} will restore any -corrupted binary files as well as resetting the sticky @samp{-kk} tags which -were present on the files in and below the working directory. -Unfortunately, this doesn't work as well with an arbitrary branch tag, as the -@samp{-r @var{branchtag}} switch does not reset the sticky @samp{-kk} -switches attached to the working files as @samp{-A} does. The workaround -for this is to release the working directory after the merge has been -committed and check it out again. -@end ignore - -As a result of using @samp{-kk} during the merge, each file examined by the -update will have @samp{-kk} set as sticky options. Running @code{update -A} -will clear the sticky options on unmodified files, but it will not clear -the sticky options on modified files. To get back to the default keyword -substitution for modified files, you must commit the results of the merge -and then run @code{update -A}. - -@c --------------------------------------------------------------------- -@node Recursive behavior -@chapter Recursive behavior -@cindex Recursive (directory descending) -@cindex Directory, descending -@cindex Descending directories -@cindex Subdirectories - -Almost all of the subcommands of @sc{cvs} work -recursively when you specify a directory as an -argument. For instance, consider this directory -structure: - -@example - @code{$HOME} - | - +--@t{tc} - | | - +--@t{CVS} - | (internal @sc{cvs} files) - +--@t{Makefile} - +--@t{backend.c} - +--@t{driver.c} - +--@t{frontend.c} - +--@t{parser.c} - +--@t{man} - | | - | +--@t{CVS} - | | (internal @sc{cvs} files) - | +--@t{tc.1} - | - +--@t{testing} - | - +--@t{CVS} - | (internal @sc{cvs} files) - +--@t{testpgm.t} - +--@t{test2.t} -@end example - -@noindent -If @file{tc} is the current working directory, the -following is true: - -@itemize @bullet -@item -@samp{cvs update testing} is equivalent to - -@example -cvs update testing/testpgm.t testing/test2.t -@end example - -@item -@samp{cvs update testing man} updates all files in the -subdirectories - -@item -@samp{cvs update .} or just @samp{cvs update} updates -all files in the @code{tc} directory -@end itemize - -If no arguments are given to @code{update} it will -update all files in the current working directory and -all its subdirectories. In other words, @file{.} is a -default argument to @code{update}. This is also true -for most of the @sc{cvs} subcommands, not only the -@code{update} command. - -The recursive behavior of the @sc{cvs} subcommands can be -turned off with the @samp{-l} option. -Conversely, the @samp{-R} option can be used to force recursion if -@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). - -@example -$ cvs update -l # @r{Don't update files in subdirectories} -@end example - -@c --------------------------------------------------------------------- -@node Adding and removing -@chapter Adding, removing, and renaming files and directories - -In the course of a project, one will often add new -files. Likewise with removing or renaming, or with -directories. The general concept to keep in mind in -all these cases is that instead of making an -irreversible change you want @sc{cvs} to record the -fact that a change has taken place, just as with -modifying an existing file. The exact mechanisms to do -this in @sc{cvs} vary depending on the situation. - -@menu -* Adding files:: Adding files -* Removing files:: Removing files -* Removing directories:: Removing directories -* Moving files:: Moving and renaming files -* Moving directories:: Moving and renaming directories -@end menu - -@node Adding files -@section Adding files to a directory -@cindex Adding files - -To add a new file to a directory, follow these steps. - -@itemize @bullet -@item -You must have a working copy of the directory. -@xref{Getting the source}. - -@item -Create the new file inside your working copy of the directory. - -@item -Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you -want to version control the file. If the file contains -binary data, specify @samp{-kb} (@pxref{Binary files}). - -@item -Use @samp{cvs commit @var{filename}} to actually check -in the file into the repository. Other developers -cannot see the file until you perform this step. -@end itemize - -You can also use the @code{add} command to add a new -directory. -@c FIXCVS and/or FIXME: Adding a directory doesn't -@c require the commit step. This probably can be -@c considered a CVS bug, but it is possible we should -@c warn people since this behavior probably won't be -@c changing right away. - -Unlike most other commands, the @code{add} command is -not recursive. You have to explicitly name files and -directories that you wish to add to the repository. -However, each directory will need to be added -separately before you will be able to add new files -to those directories. - -@example -$ mkdir -p foo/bar -$ cp ~/myfile foo/bar/myfile -$ cvs add foo foo/bar -$ cvs add foo/bar/myfile -@end example - -@cindex add (subcommand) -@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} - -Schedule @var{files} to be added to the repository. -The files or directories specified with @code{add} must -already exist in the current directory. To add a whole -new directory hierarchy to the source repository (for -example, files received from a third-party vendor), use -the @code{import} command instead. @xref{import}. - -The added files are not placed in the source repository -until you use @code{commit} to make the change -permanent. Doing an @code{add} on a file that was -removed with the @code{remove} command will undo the -effect of the @code{remove}, unless a @code{commit} -command intervened. @xref{Removing files}, for an -example. - -The @samp{-k} option specifies the default way that -this file will be checked out; for more information see -@ref{Substitution modes}. - -@c As noted in BUGS, -m is broken client/server (Nov -@c 96). Also see testsuite log2-* tests. -The @samp{-m} option specifies a description for the -file. This description appears in the history log (if -it is enabled, @pxref{history file}). It will also be -saved in the version history inside the repository when -the file is committed. The @code{log} command displays -this description. The description can be changed using -@samp{admin -t}. @xref{admin}. If you omit the -@samp{-m @var{description}} flag, an empty string will -be used. You will not be prompted for a description. -@end deffn - -For example, the following commands add the file -@file{backend.c} to the repository: - -@c This example used to specify -@c -m "Optimizer and code generation passes." -@c to the cvs add command, but that doesn't work -@c client/server (see log2 in sanity.sh). Should fix CVS, -@c but also seems strange to document things which -@c don't work... -@example -$ cvs add backend.c -$ cvs commit -m "Early version. Not yet compilable." backend.c -@end example - -When you add a file it is added only on the branch -which you are working on (@pxref{Branching and merging}). You can -later merge the additions to another branch if you want -(@pxref{Merging adds and removals}). -@c Should we mention that earlier versions of CVS -@c lacked this feature (1.3) or implemented it in a buggy -@c way (well, 1.8 had many bugs in cvs update -j)? -@c Should we mention the bug/limitation regarding a -@c file being a regular file on one branch and a directory -@c on another? -@c FIXME: This needs an example, or several, here or -@c elsewhere, for it to make much sense. -@c Somewhere we need to discuss the aspects of death -@c support which don't involve branching, I guess. -@c Like the ability to re-create a release from a tag. - -@c --------------------------------------------------------------------- -@node Removing files -@section Removing files -@cindex Removing files -@cindex Deleting files - -@c FIXME: this node wants to be split into several -@c smaller nodes. Could make these children of -@c "Adding and removing", probably (death support could -@c be its own section, for example, as could the -@c various bits about undoing mistakes in adding and -@c removing). -Directories change. New files are added, and old files -disappear. Still, you want to be able to retrieve an -exact copy of old releases. - -Here is what you can do to remove a file, -but remain able to retrieve old revisions: - -@itemize @bullet -@c FIXME: should probably be saying something about -@c having a working directory in the first place. -@item -Make sure that you have not made any uncommitted -modifications to the file. @xref{Viewing differences}, -for one way to do that. You can also use the -@code{status} or @code{update} command. If you remove -the file without committing your changes, you will of -course not be able to retrieve the file as it was -immediately before you deleted it. - -@item -Remove the file from your working copy of the directory. -You can for instance use @code{rm}. - -@item -Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that -you really want to delete the file. - -@item -Use @samp{cvs commit @var{filename}} to actually -perform the removal of the file from the repository. -@end itemize - -@c FIXME: Somehow this should be linked in with a more -@c general discussion of death support. I don't know -@c whether we want to use the term "death support" or -@c not (we can perhaps get by without it), but we do -@c need to discuss the "dead" state in "cvs log" and -@c related subjects. The current discussion is -@c scattered around, and not xref'd to each other. -@c FIXME: I think this paragraph wants to be moved -@c later down, at least after the first example. -When you commit the removal of the file, @sc{cvs} -records the fact that the file no longer exists. It is -possible for a file to exist on only some branches and -not on others, or to re-add another file with the same -name later. @sc{cvs} will correctly create or not create -the file, based on the @samp{-r} and @samp{-D} options -specified to @code{checkout} or @code{update}. - -@c FIXME: This style seems to clash with how we -@c document things in general. -@cindex Remove (subcommand) -@deffn Command {cvs remove} [options] files @dots{} - -Schedule file(s) to be removed from the repository -(files which have not already been removed from the -working directory are not processed). This command -does not actually remove the file from the repository -until you commit the removal. For a full list of -options, see @ref{Invoking CVS}. -@end deffn - -Here is an example of removing several files: - -@example -$ cd test -$ rm *.c -$ cvs remove -cvs remove: Removing . -cvs remove: scheduling a.c for removal -cvs remove: scheduling b.c for removal -cvs remove: use 'cvs commit' to remove these files permanently -$ cvs ci -m "Removed unneeded files" -cvs commit: Examining . -cvs commit: Committing . -@end example - -As a convenience you can remove the file and @code{cvs -remove} it in one step, by specifying the @samp{-f} -option. For example, the above example could also be -done like this: - -@example -$ cd test -$ cvs remove -f *.c -cvs remove: scheduling a.c for removal -cvs remove: scheduling b.c for removal -cvs remove: use 'cvs commit' to remove these files permanently -$ cvs ci -m "Removed unneeded files" -cvs commit: Examining . -cvs commit: Committing . -@end example - -If you execute @code{remove} for a file, and then -change your mind before you commit, you can undo the -@code{remove} with an @code{add} command. -@ignore -@c is this worth saying or not? Somehow it seems -@c confusing to me. -Of course, -since you have removed your copy of file in the working -directory, @sc{cvs} does not necessarily bring back the -contents of the file from right before you executed -@code{remove}; instead it gets the file from the -repository again. -@end ignore - -@c FIXME: what if you change your mind after you commit -@c it? (answer is also "cvs add" but we don't say that...). -@c We need some index entries for thinks like "undoing -@c removal" too. - -@example -$ ls -CVS ja.h oj.c -$ rm oj.c -$ cvs remove oj.c -cvs remove: scheduling oj.c for removal -cvs remove: use 'cvs commit' to remove this file permanently -$ cvs add oj.c -U oj.c -cvs add: oj.c, version 1.1.1.1, resurrected -@end example - -If you realize your mistake before you run the -@code{remove} command you can use @code{update} to -resurrect the file: - -@example -$ rm oj.c -$ cvs update oj.c -cvs update: warning: oj.c was lost -U oj.c -@end example - -When you remove a file it is removed only on the branch -which you are working on (@pxref{Branching and merging}). You can -later merge the removals to another branch if you want -(@pxref{Merging adds and removals}). - -@node Removing directories -@section Removing directories -@cindex Removing directories -@cindex Directories, removing - -In concept, removing directories is somewhat similar to -removing files---you want the directory to not exist in -your current working directories, but you also want to -be able to retrieve old releases in which the directory -existed. - -The way that you remove a directory is to remove all -the files in it. You don't remove the directory -itself; there is no way to do that. -Instead you specify the @samp{-P} option to -@code{cvs update} or @code{cvs checkout}, -which will cause @sc{cvs} to remove empty -directories from working directories. -(Note that @code{cvs export} always removes empty directories.) -Probably the -best way to do this is to always specify @samp{-P}; if -you want an empty directory then put a dummy file (for -example @file{.keepme}) in it to prevent @samp{-P} from -removing it. - -@c I'd try to give a rationale for this, but I'm not -@c sure there is a particularly convincing one. What -@c we would _like_ is for CVS to do a better job of version -@c controlling whether directories exist, to eliminate the -@c need for -P and so that a file can be a directory in -@c one revision and a regular file in another. -Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} -options of @code{checkout}. This way, -@sc{cvs} will be able to correctly create the directory -or not depending on whether the particular version you -are checking out contains any files in that directory. - -@c --------------------------------------------------------------------- -@node Moving files -@section Moving and renaming files -@cindex Moving files -@cindex Renaming files -@cindex Files, moving - -Moving files to a different directory or renaming them -is not difficult, but some of the ways in which this -works may be non-obvious. (Moving or renaming a -directory is even harder. @xref{Moving directories}.). - -The examples below assume that the file @var{old} is renamed to -@var{new}. - -@menu -* Outside:: The normal way to Rename -* Inside:: A tricky, alternative way -* Rename by copying:: Another tricky, alternative way -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Outside -@subsection The Normal way to Rename - -@c More rename issues. Not sure whether these are -@c worth documenting; I'm putting them here because -@c it seems to be as good a place as any to try to -@c set down the issues. -@c * "cvs annotate" will annotate either the new -@c file or the old file; it cannot annotate _each -@c line_ based on whether it was last changed in the -@c new or old file. Unlike "cvs log", where the -@c consequences of having to select either the new -@c or old name seem fairly benign, this may be a -@c real advantage to having CVS know about renames -@c other than as a deletion and an addition. - -The normal way to move a file is to copy @var{old} to -@var{new}, and then issue the normal @sc{cvs} commands -to remove @var{old} from the repository, and add -@var{new} to it. -@c The following sentence is not true: one must cd into -@c the directory to run "cvs add". -@c (Both @var{old} and @var{new} could -@c contain relative paths, for example @file{foo/bar.c}). - -@example -$ mv @var{old} @var{new} -$ cvs remove @var{old} -$ cvs add @var{new} -$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} -@end example - -This is the simplest way to move a file, it is not -error-prone, and it preserves the history of what was -done. Note that to access the history of the file you -must specify the old or the new name, depending on what -portion of the history you are accessing. For example, -@code{cvs log @var{old}} will give the log up until the -time of the rename. - -When @var{new} is committed its revision numbers will -start again, usually at 1.1, so if that bothers you, -use the @samp{-r rev} option to commit. For more -information see @ref{Assigning revisions}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Inside -@subsection Moving the history file - -This method is more dangerous, since it involves moving -files inside the repository. Read this entire section -before trying it out! - -@example -$ cd $CVSROOT/@var{dir} -$ mv @var{old},v @var{new},v -@end example - -@noindent -Advantages: - -@itemize @bullet -@item -The log of changes is maintained intact. - -@item -The revision numbers are not affected. -@end itemize - -@noindent -Disadvantages: - -@itemize @bullet -@item -Old releases cannot easily be fetched from the -repository. (The file will show up as @var{new} even -in revisions from the time before it was renamed). - -@item -There is no log information of when the file was renamed. - -@item -Nasty things might happen if someone accesses the history file -while you are moving it. Make sure no one else runs any of the @sc{cvs} -commands while you move it. -@end itemize - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Rename by copying -@subsection Copying the history file - -This way also involves direct modifications to the -repository. It is safe, but not without drawbacks. - -@example -# @r{Copy the @sc{rcs} file inside the repository} -$ cd $CVSROOT/@var{dir} -$ cp @var{old},v @var{new},v -# @r{Remove the old file} -$ cd ~/@var{dir} -$ rm @var{old} -$ cvs remove @var{old} -$ cvs commit @var{old} -# @r{Remove all tags from @var{new}} -$ cvs update @var{new} -$ cvs log @var{new} # @r{Remember the non-branch tag names} -$ cvs tag -d @var{tag1} @var{new} -$ cvs tag -d @var{tag2} @var{new} -@dots{} -@end example - -By removing the tags you will be able to check out old -revisions. - -@noindent -Advantages: - -@itemize @bullet -@item -@c FIXME: Is this true about -D now that we have death -@c support? See 5B.3 in the FAQ. -Checking out old revisions works correctly, as long as -you use @samp{-r@var{tag}} and not @samp{-D@var{date}} -to retrieve the revisions. - -@item -The log of changes is maintained intact. - -@item -The revision numbers are not affected. -@end itemize - -@noindent -Disadvantages: - -@itemize @bullet -@item -You cannot easily see the history of the file across the rename. - -@ignore -@c Is this true? I don't see how the revision numbers -@c _could_ start over, when new,v is just old,v with -@c the tags deleted. -@c If there is some need to reinstate this text, -@c it is "usually 1.1", not "1.0" and it needs an -@c xref to Assigning revisions -@item -Unless you use the @samp{-r rev} (@pxref{commit -options}) flag when @var{new} is committed its revision -numbers will start at 1.0 again. -@end ignore -@end itemize - -@c --------------------------------------------------------------------- -@node Moving directories -@section Moving and renaming directories -@cindex Moving directories -@cindex Renaming directories -@cindex Directories, moving - -The normal way to rename or move a directory is to -rename or move each file within it as described in -@ref{Outside}. Then check out with the @samp{-P} -option, as described in @ref{Removing directories}. - -If you really want to hack the repository to rename or -delete a directory in the repository, you can do it -like this: - -@enumerate -@item -Inform everyone who has a checked out copy of the directory that the -directory will be renamed. They should commit all their changes in all their -copies of the project containing the directory to be removed, and remove -all their working copies of said project, before you take the steps below. - -@item -Rename the directory inside the repository. - -@example -$ cd $CVSROOT/@var{parent-dir} -$ mv @var{old-dir} @var{new-dir} -@end example - -@item -Fix the @sc{cvs} administrative files, if necessary (for -instance if you renamed an entire module). - -@item -Tell everyone that they can check out again and continue -working. - -@end enumerate - -If someone had a working copy the @sc{cvs} commands will -cease to work for him, until he removes the directory -that disappeared inside the repository. - -It is almost always better to move the files in the -directory instead of moving the directory. If you move the -directory you are unlikely to be able to retrieve old -releases correctly, since they probably depend on the -name of the directories. - -@c --------------------------------------------------------------------- -@node History browsing -@chapter History browsing -@cindex History browsing -@cindex Traceability -@cindex Isolation - -@ignore -@c This is too long for an introduction (goal is -@c one 20x80 character screen), and also mixes up a -@c variety of issues (parallel development, history, -@c maybe even touches on process control). - -@c -- @quote{To lose ones history is to lose ones soul.} -@c -- /// -@c -- ///Those who cannot remember the past are condemned to repeat it. -@c -- /// -- George Santayana -@c -- /// - -@sc{cvs} tries to make it easy for a group of people to work -together. This is done in two ways: - -@itemize @bullet -@item -Isolation---You have your own working copy of the -source. You are not affected by modifications made by -others until you decide to incorporate those changes -(via the @code{update} command---@pxref{update}). - -@item -Traceability---When something has changed, you can -always see @emph{exactly} what changed. -@end itemize - -There are several features of @sc{cvs} that together lead -to traceability: - -@itemize @bullet -@item -Each revision of a file has an accompanying log -message. - -@item -All commits are optionally logged to a central history -database. - -@item -Logging information can be sent to a user-defined -program (@pxref{loginfo}). -@end itemize - -@c -- More text here. - -This chapter should talk about the history file, the -@code{log} command, the usefulness of ChangeLogs -even when you run @sc{cvs}, and things like that. - -@end ignore - -@c kind of lame, in a lot of ways the above text inside -@c the @ignore motivates this chapter better -Once you have used @sc{cvs} to store a version control -history---what files have changed when, how, and by -whom, there are a variety of mechanisms for looking -through the history. - -@c FIXME: should also be talking about how you look at -@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). -@menu -* log messages:: Log messages -* history database:: The history database -* user-defined logging:: User-defined logging -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node log messages -@section Log messages - -@c FIXME: @xref to place where we talk about how to -@c specify message to commit. -Whenever you commit a file you specify a log message. - -@c FIXME: bring the information here, and get rid of or -@c greatly shrink the "log" node. -To look through the log messages which have been -specified for every revision which has been committed, -use the @code{cvs log} command (@pxref{log}). - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node history database -@section The history database - -@c FIXME: bring the information from the history file -@c and history nodes here. Rewrite it to be motivated -@c better (start out by clearly explaining what gets -@c logged in history, for example). -You can use the history file (@pxref{history file}) to -log various @sc{cvs} actions. To retrieve the -information from the history file, use the @code{cvs -history} command (@pxref{history}). - -Note: you can control what is logged to this file by using the -@samp{LogHistory} keyword in the @file{CVSROOT/config} file -(@pxref{config}). - -@c -@c The history database has many problems: -@c * It is very unclear what field means what. This -@c could be improved greatly by better documentation, -@c but there are still non-orthogonalities (for -@c example, tag does not record the "repository" -@c field but most records do). -@c * Confusion about files, directories, and modules. -@c Some commands record one, some record others. -@c * File removal is not logged. There is an 'R' -@c record type documented, but CVS never uses it. -@c * Tags are only logged for the "cvs rtag" command, -@c not "cvs tag". The fix for this is not completely -@c clear (see above about modules vs. files). -@c * Are there other cases of operations that are not -@c logged? One would hope for all changes to the -@c repository to be logged somehow (particularly -@c operations like tagging, "cvs admin -k", and other -@c operations which do not record a history that one -@c can get with "cvs log"). Operations on the working -@c directory, like export, get, and release, are a -@c second category also covered by the current "cvs -@c history". -@c * The history file does not record the options given -@c to a command. The most serious manifestation of -@c this is perhaps that it doesn't record whether a command -@c was recursive. It is not clear to me whether one -@c wants to log at a level very close to the command -@c line, as a sort of way of logging each command -@c (more or less), or whether one wants -@c to log more at the level of what was changed (or -@c something in between), but either way the current -@c information has pretty big gaps. -@c * Further details about a tag--like whether it is a -@c branch tag or, if a non-branch tag, which branch it -@c is on. One can find out this information about the -@c tag as it exists _now_, but if the tag has been -@c moved, one doesn't know what it was like at the time -@c the history record was written. -@c * Whether operating on a particular tag, date, or -@c options was implicit (sticky) or explicit. -@c -@c Another item, only somewhat related to the above, is a -@c way to control what is logged in the history file. -@c This is probably the only good way to handle -@c different people having different ideas about -@c information/space tradeoffs. -@c -@c It isn't really clear that it makes sense to try to -@c patch up the history file format as it exists now to -@c include all that stuff. It might be better to -@c design a whole new CVSROOT/nhistory file and "cvs -@c nhistory" command, or some such, or in some other -@c way trying to come up with a clean break from the -@c past, which can address the above concerns. Another -@c open question is how/whether this relates to -@c taginfo/loginfo/etc. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node user-defined logging -@section User-defined logging - -@c FIXME: probably should centralize this information -@c here, at least to some extent. Maybe by moving the -@c loginfo, etc., nodes here and replacing -@c the "user-defined logging" node with one node for -@c each method. -You can customize @sc{cvs} to log various kinds of -actions, in whatever manner you choose. These -mechanisms operate by executing a script at various -times. The script might append a message to a file -listing the information and the programmer who created -it, or send mail to a group of developers, or, perhaps, -post a message to a particular newsgroup. To log -commits, use the @file{loginfo} file (@pxref{loginfo}). -To log tags, use the @file{taginfo} file (@pxref{taginfo}). -@c FIXME: What is difference between doing it in the -@c modules file and using loginfo/taginfo? Why should -@c user use one or the other? -To log checkouts, exports, and tags, -respectively, you can also use the -@samp{-o}, @samp{-e}, and @samp{-t} options in the -modules file. For a more flexible way of giving -notifications to various users, which requires less in -the way of keeping centralized scripts up to date, use -the @code{cvs watch add} command (@pxref{Getting -Notified}); this command is useful even if you are not -using @code{cvs watch on}. - -@c --------------------------------------------------------------------- -@node Binary files -@chapter Handling binary files -@cindex Binary files - -The most common use for @sc{cvs} is to store text -files. With text files, @sc{cvs} can merge revisions, -display the differences between revisions in a -human-visible fashion, and other such operations. -However, if you are willing to give up a few of these -abilities, @sc{cvs} can store binary files. For -example, one might store a web site in @sc{cvs} -including both text files and binary images. - -@menu -* Binary why:: More details on issues with binary files -* Binary howto:: How to store them -@end menu - -@node Binary why -@section The issues with binary files - -While the need to manage binary files may seem obvious -if the files that you customarily work with are binary, -putting them into version control does present some -additional issues. - -One basic function of version control is to show the -differences between two revisions. For example, if -someone else checked in a new version of a file, you -may wish to look at what they changed and determine -whether their changes are good. For text files, -@sc{cvs} provides this functionality via the @code{cvs -diff} command. For binary files, it may be possible to -extract the two revisions and then compare them with a -tool external to @sc{cvs} (for example, word processing -software often has such a feature). If there is no -such tool, one must track changes via other mechanisms, -such as urging people to write good log messages, and -hoping that the changes they actually made were the -changes that they intended to make. - -Another ability of a version control system is the -ability to merge two revisions. For @sc{cvs} this -happens in two contexts. The first is when users make -changes in separate working directories -(@pxref{Multiple developers}). The second is when one -merges explicitly with the @samp{update -j} command -(@pxref{Branching and merging}). - -In the case of text -files, @sc{cvs} can merge changes made independently, -and signal a conflict if the changes conflict. With -binary files, the best that @sc{cvs} can do is present -the two different copies of the file, and leave it to -the user to resolve the conflict. The user may choose -one copy or the other, or may run an external merge -tool which knows about that particular file format, if -one exists. -Note that having the user merge relies primarily on the -user to not accidentally omit some changes, and thus is -potentially error prone. - -If this process is thought to be undesirable, the best -choice may be to avoid merging. To avoid the merges -that result from separate working directories, see the -discussion of reserved checkouts (file locking) in -@ref{Multiple developers}. To avoid the merges -resulting from branches, restrict use of branches. - -@node Binary howto -@section How to store binary files - -There are two issues with using @sc{cvs} to store -binary files. The first is that @sc{cvs} by default -converts line endings between the canonical form in -which they are stored in the repository (linefeed -only), and the form appropriate to the operating system -in use on the client (for example, carriage return -followed by line feed for Windows NT). - -The second is that a binary file might happen to -contain data which looks like a keyword (@pxref{Keyword -substitution}), so keyword expansion must be turned -off. - -@c FIXME: the third is that one can't do merges with -@c binary files. xref to Multiple Developers and the -@c reserved checkout issues. - -The @samp{-kb} option available with some @sc{cvs} -commands insures that neither line ending conversion -nor keyword expansion will be done. - -Here is an example of how you can create a new file -using the @samp{-kb} flag: - -@example -$ echo '$@splitrcskeyword{Id}$' > kotest -$ cvs add -kb -m"A test file" kotest -$ cvs ci -m"First checkin; contains a keyword" kotest -@end example - -If a file accidentally gets added without @samp{-kb}, -one can use the @code{cvs admin} command to recover. -For example: - -@example -$ echo '$@splitrcskeyword{Id}$' > kotest -$ cvs add -m"A test file" kotest -$ cvs ci -m"First checkin; contains a keyword" kotest -$ cvs admin -kb kotest -$ cvs update -A kotest -# @r{For non-unix systems:} -# @r{Copy in a good copy of the file from outside CVS} -$ cvs commit -m "make it binary" kotest -@end example - -@c Trying to describe this for both unix and non-unix -@c in the same description is very confusing. Might -@c want to split the two, or just ditch the unix "shortcut" -@c (unixheads don't do much with binary files, anyway). -@c This used to say "(Try the above example, and do a -@c @code{cat kotest} after every command)". But that -@c only really makes sense for the unix case. -When you check in the file @file{kotest} the file is -not preserved as a binary file, because you did not -check it in as a binary file. The @code{cvs -admin -kb} command sets the default keyword -substitution method for this file, but it does not -alter the working copy of the file that you have. If you need to -cope with line endings (that is, you are using -@sc{cvs} on a non-unix system), then you need to -check in a new copy of the file, as shown by the -@code{cvs commit} command above. -On unix, the @code{cvs update -A} command suffices. -@c FIXME: should also describe what the *other users* -@c need to do, if they have checked out copies which -@c have been corrupted by lack of -kb. I think maybe -@c "cvs update -kb" or "cvs -@c update -A" would suffice, although the user who -@c reported this suggested removing the file, manually -@c removing it from CVS/Entries, and then "cvs update" -(Note that you can use @code{cvs log} to determine the default keyword -substitution method for a file and @code{cvs status} to determine -the keyword substitution method for a working copy.) - -However, in using @code{cvs admin -k} to change the -keyword expansion, be aware that the keyword expansion -mode is not version controlled. This means that, for -example, that if you have a text file in old releases, -and a binary file with the same name in new releases, -@sc{cvs} provides no way to check out the file in text -or binary mode depending on what version you are -checking out. There is no good workaround for this -problem. - -You can also set a default for whether @code{cvs add} -and @code{cvs import} treat a file as binary based on -its name; for example you could say that files who -names end in @samp{.exe} are binary. @xref{Wrappers}. -There is currently no way to have @sc{cvs} detect -whether a file is binary based on its contents. The -main difficulty with designing such a feature is that -it is not clear how to distinguish between binary and -non-binary files, and the rules to apply would vary -considerably with the operating system. -@c For example, it would be good on MS-DOS-family OSes -@c for anything containing ^Z to be binary. Having -@c characters with the 8th bit set imply binary is almost -@c surely a bad idea in the context of ISO-8859-* and -@c other such character sets. On VMS or the Mac, we -@c could use the OS's file typing. This is a -@c commonly-desired feature, and something of this sort -@c may make sense. But there are a lot of pitfalls here. -@c -@c Another, probably better, way to tell is to read the -@c file in text mode, write it to a temp file in text -@c mode, and then do a binary mode compare of the two -@c files. If they differ, it is a binary file. This -@c might have problems on VMS (or some other system -@c with several different text modes), but in general -@c should be relatively portable. The only other -@c downside I can think of is that it would be fairly -@c slow, but that is perhaps a small price to pay for -@c not having your files corrupted. Another issue is -@c what happens if you import a text file with bare -@c linefeeds on Windows. Such files will show up on -@c Windows sometimes (I think some native windows -@c programs even write them, on occasion). Perhaps it -@c is reasonable to treat such files as binary; after -@c all it is something of a presumption to assume that -@c the user would want the linefeeds converted to CRLF. - -@c --------------------------------------------------------------------- -@node Multiple developers -@chapter Multiple developers -@cindex Multiple developers -@cindex Team of developers -@cindex File locking -@cindex Locking files -@cindex Working copy -@cindex Reserved checkouts -@cindex Unreserved checkouts -@cindex RCS-style locking - -When more than one person works on a software project -things often get complicated. Often, two people try to -edit the same file simultaneously. One solution, known -as @dfn{file locking} or @dfn{reserved checkouts}, is -to allow only one person to edit each file at a time. -This is the only solution with some version control -systems, including @sc{rcs} and @sc{sccs}. Currently -the usual way to get reserved checkouts with @sc{cvs} -is the @code{cvs admin -l} command (@pxref{admin -options}). This is not as nicely integrated into -@sc{cvs} as the watch features, described below, but it -seems that most people with a need for reserved -checkouts find it adequate. -@c Or "find it better than worrying about implementing -@c nicely integrated reserved checkouts" or ...? -It also may be possible to use the watches -features described below, together with suitable -procedures (not enforced by software), to avoid having -two people edit at the same time. - -@c Our unreserved checkout model might not -@c be quite the same as others. For example, I -@c think that some systems will tend to create a branch -@c in the case where CVS prints "up-to-date check failed". -@c It isn't clear to me whether we should try to -@c explore these subtleties; it could easily just -@c confuse people. -The default model with @sc{cvs} is known as -@dfn{unreserved checkouts}. In this model, developers -can edit their own @dfn{working copy} of a file -simultaneously. The first person that commits his -changes has no automatic way of knowing that another -has started to edit it. Others will get an error -message when they try to commit the file. They must -then use @sc{cvs} commands to bring their working copy -up to date with the repository revision. This process -is almost automatic. - -@c FIXME? should probably use the word "watch" here, to -@c tie this into the text below and above. -@sc{cvs} also supports mechanisms which facilitate -various kinds of communication, without actually -enforcing rules like reserved checkouts do. - -The rest of this chapter describes how these various -models work, and some of the issues involved in -choosing between them. - -@ignore -Here is a draft reserved checkout design or discussion -of the issues. This seems like as good a place as any -for this. - -Might want a cvs lock/cvs unlock--in which the names -differ from edit/unedit because the network must be up -for these to work. unedit gives an error if there is a -reserved checkout in place (so that people don't -accidentally leave locks around); unlock gives an error -if one is not in place (this is more arguable; perhaps -it should act like unedit in that case). - -On the other hand, might want it so that emacs, -scripts, etc., can get ready to edit a file without -having to know which model is in use. In that case we -would have a "cvs watch lock" (or .cvsrc?) (that is, -three settings, "on", "off", and "lock"). Having cvs -watch lock set would cause a get to record in the CVS -directory which model is in use, and cause "cvs edit" -to change behaviors. We'd want a way to query which -setting is in effect (this would be handy even if it is -only "on" or "off" as presently). If lock is in -effect, then commit would require a lock before -allowing a checkin; chmod wouldn't suffice (might be -debatable--see chmod comment below, in watches--but it -is the way people expect RCS to work and I can't think -of any significant downside. On the other hand, maybe -it isn't worth bothering, because people who are used -to RCS wouldn't think to use chmod anyway). - -Implementation: use file attributes or use RCS -locking. The former avoids more dependence on RCS -behaviors we will need to re-implement as we librarify -RCS, and makes it easier to import/export RCS files (in -that context, want to ignore the locker field). But -note that RCS locks are per-branch, which is the -correct behavior (this is also an issue for the "watch -on" features; they should be per-branch too). - -Here are a few more random notes about implementation -details, assuming "cvs watch lock" and - -CVS/Watched file? Or try to fit this into CVS/Entries somehow? -Cases: (1) file is checked out (unreserved or with watch on) by old -version of @sc{cvs}, now we do something with new one, (2) file is checked -out by new version, now we do something with old one. - -Remote protocol would have a "Watched" analogous to "Mode". Of course -it would apply to all Updated-like requests. How do we keep this -setting up to date? I guess that there wants to be a Watched request, -and the server would send a new one if it isn't up to date? (Ugh--hard -to implement and slows down "cvs -q update"--is there an easier way?) - -"cvs edit"--checks CVS/Watched, and if watch lock, then sends -"edit-lock" request. Which comes back with a Checked-in with -appropriate Watched (off, on, lock, locked, or some such?), or error -message if already locked. - -"cvs commit"--only will commit if off/on/locked. lock is not OK. - -Doc: -note that "cvs edit" must be connected to network if watch lock is in -effect. - -Talk about what to do if someone has locked a file and you want to -edit that file. (breaking locks, or lack thereof). - - -One other idea (which could work along with the -existing "cvs admin -l" reserved checkouts, as well as -the above): - -"cvs editors" could show who has the file locked, if -someone does. - -@end ignore - -@menu -* File status:: A file can be in several states -* Updating a file:: Bringing a file up-to-date -* Conflicts example:: An informative example -* Informing others:: To cooperate you must inform -* Concurrency:: Simultaneous repository access -* Watches:: Mechanisms to track who is editing files -* Choosing a model:: Reserved or unreserved checkouts? -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node File status -@section File status -@cindex File status -@cindex Status of a file - -@c Shouldn't this start with an example or something, -@c introducing the unreserved checkout model? Before we -@c dive into listing states? -Based on what operations you have performed on a -checked out file, and what operations others have -performed to that file in the repository, one can -classify a file in a number of states. The states, as -reported by the @code{status} command, are: - -@c The order of items is chosen to group logically -@c similar outputs together. -@c People who want alphabetical can use the index... -@table @asis -@cindex Up-to-date -@item Up-to-date -The file is identical with the latest revision in the -repository for the branch in use. -@c FIXME: should we clarify "in use"? The answer is -@c sticky tags, and trying to distinguish branch sticky -@c tags from non-branch sticky tags seems rather awkward -@c here. -@c FIXME: What happens with non-branch sticky tags? Is -@c a stuck file "Up-to-date" or "Needs checkout" or what? - -@item Locally Modified -@cindex Locally Modified -You have edited the file, and not yet committed your changes. - -@item Locally Added -@cindex Locally Added -You have added the file with @code{add}, and not yet -committed your changes. -@c There are many cases involving the file being -@c added/removed/modified in the working directory, and -@c added/removed/modified in the repository, which we -@c don't try to describe here. I'm not sure that "cvs -@c status" produces a non-confusing output in most of -@c those cases. - -@item Locally Removed -@cindex Locally Removed -You have removed the file with @code{remove}, and not yet -committed your changes. - -@item Needs Checkout -@cindex Needs Checkout -Someone else has committed a newer revision to the -repository. The name is slightly misleading; you will -ordinarily use @code{update} rather than -@code{checkout} to get that newer revision. - -@item Needs Patch -@cindex Needs Patch -@c See also newb-123j0 in sanity.sh (although that case -@c should probably be changed rather than documented). -Like Needs Checkout, but the @sc{cvs} server will send -a patch rather than the entire file. Sending a patch or -sending an entire file accomplishes the same thing. - -@item Needs Merge -@cindex Needs Merge -Someone else has committed a newer revision to the repository, and you -have also made modifications to the file. - -@item Unresolved Conflict -@cindex Unresolved Conflict -@c FIXCVS - This file status needs to be changed to some more informative -@c text that distinguishes it more clearly from each of the Locally Added, -@c File had conflicts on merge, and Unknown status types, but an exact and -@c succinct wording escapes me at the moment. -A file with the same name as this new file has been added to the repository -from a second workspace. This file will need to be moved out of the way -to allow an @code{update} to complete. - -@item File had conflicts on merge -@cindex File had conflicts on merge -@c is it worth saying that this message was "Unresolved -@c Conflict" in CVS 1.9 and earlier? I'm inclined to -@c think that is unnecessarily confusing to new users. -This is like Locally Modified, except that a previous -@code{update} command gave a conflict. If you have not -already done so, you need to -resolve the conflict as described in @ref{Conflicts example}. - -@item Unknown -@cindex Unknown -@sc{cvs} doesn't know anything about this file. For -example, you have created a new file and have not run -@code{add}. -@c -@c "Entry Invalid" and "Classify Error" are also in the -@c status.c. The latter definitely indicates a CVS bug -@c (should it be worded more like "internal error" so -@c people submit bug reports if they see it?). The former -@c I'm not as sure; I haven't tracked down whether/when it -@c appears in "cvs status" output. - -@end table - -To help clarify the file status, @code{status} also -reports the @code{Working revision} which is the -revision that the file in the working directory derives -from, and the @code{Repository revision} which is the -latest revision in the repository for the branch in -use. -@c FIXME: should we clarify "in use"? The answer is -@c sticky tags, and trying to distinguish branch sticky -@c tags from non-branch sticky tags seems rather awkward -@c here. -@c FIXME: What happens with non-branch sticky tags? -@c What is the Repository Revision there? See the -@c comment at vn_rcs in cvs.h, which is kind of -@c confused--we really need to document better what this -@c field contains. -@c Q: Should we document "New file!" and other such -@c outputs or are they self-explanatory? -@c FIXME: what about the date to the right of "Working -@c revision"? It doesn't appear with client/server and -@c seems unnecessary (redundant with "ls -l") so -@c perhaps it should be removed for non-client/server too? -@c FIXME: Need some examples. -@c FIXME: Working revision can also be something like -@c "-1.3" for a locally removed file. Not at all -@c self-explanatory (and it is possible that CVS should -@c be changed rather than documenting this). - -@c Would be nice to have an @example showing output -@c from cvs status, with comments showing the xref -@c where each part of the output is described. This -@c might fit in nicely if it is desirable to split this -@c node in two; one to introduce "cvs status" and one -@c to list each of the states. -The options to @code{status} are listed in -@ref{Invoking CVS}. For information on its @code{Sticky tag} -and @code{Sticky date} output, see @ref{Sticky tags}. -For information on its @code{Sticky options} output, -see the @samp{-k} option in @ref{update options}. - -You can think of the @code{status} and @code{update} -commands as somewhat complementary. You use -@code{update} to bring your files up to date, and you -can use @code{status} to give you some idea of what an -@code{update} would do (of course, the state of the -repository might change before you actually run -@code{update}). In fact, if you want a command to -display file status in a more brief format than is -displayed by the @code{status} command, you can invoke - -@cindex update, to display file status -@example -$ cvs -n -q update -@end example - -The @samp{-n} option means to not actually do the -update, but merely to display statuses; the @samp{-q} -option avoids printing the name of each directory. For -more information on the @code{update} command, and -these options, see @ref{Invoking CVS}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Updating a file -@section Bringing a file up to date -@cindex Bringing a file up to date -@cindex Updating a file -@cindex Merging a file -@cindex Update, introduction - -When you want to update or merge a file, use the @code{cvs update -d} -command. For files that are not up to date this is roughly equivalent -to a @code{checkout} command: the newest revision of the file is -extracted from the repository and put in your working directory. The -@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} -that you wish it to create directories added by other developers. - -Your modifications to a file are never lost when you -use @code{update}. If no newer revision exists, -running @code{update} has no effect. If you have -edited the file, and a newer revision is available, -@sc{cvs} will merge all changes into your working copy. - -For instance, imagine that you checked out revision 1.4 and started -editing it. In the meantime someone else committed revision 1.5, and -shortly after that revision 1.6. If you run @code{update} on the file -now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into -your file. - -@cindex Overlap -If any of the changes between 1.4 and 1.6 were made too -close to any of the changes you have made, an -@dfn{overlap} occurs. In such cases a warning is -printed, and the resulting file includes both -versions of the lines that overlap, delimited by -special markers. -@xref{update}, for a complete description of the -@code{update} command. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Conflicts example -@section Conflicts example -@cindex Merge, an example -@cindex Example of merge -@cindex driver.c (merge example) - -Suppose revision 1.4 of @file{driver.c} contains this: - -@example -#include <stdio.h> - -void main() -@{ - parse(); - if (nerr == 0) - gencode(); - else - fprintf(stderr, "No code generated.\n"); - exit(nerr == 0 ? 0 : 1); -@} -@end example - -@noindent -Revision 1.6 of @file{driver.c} contains this: - -@example -#include <stdio.h> - -int main(int argc, - char **argv) -@{ - parse(); - if (argc != 1) - @{ - fprintf(stderr, "tc: No args expected.\n"); - exit(1); - @} - if (nerr == 0) - gencode(); - else - fprintf(stderr, "No code generated.\n"); - exit(!!nerr); -@} -@end example - -@noindent -Your working copy of @file{driver.c}, based on revision -1.4, contains this before you run @samp{cvs update}: -@c -- Really include "cvs"? - -@example -#include <stdlib.h> -#include <stdio.h> - -void main() -@{ - init_scanner(); - parse(); - if (nerr == 0) - gencode(); - else - fprintf(stderr, "No code generated.\n"); - exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); -@} -@end example - -@noindent -You run @samp{cvs update}: -@c -- Really include "cvs"? - -@example -$ cvs update driver.c -RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v -retrieving revision 1.4 -retrieving revision 1.6 -Merging differences between 1.4 and 1.6 into driver.c -rcsmerge warning: overlaps during merge -cvs update: conflicts found in driver.c -C driver.c -@end example - -@noindent -@cindex Conflicts (merge example) -@sc{cvs} tells you that there were some conflicts. -Your original working file is saved unmodified in -@file{.#driver.c.1.4}. The new version of -@file{driver.c} contains this: - -@example -#include <stdlib.h> -#include <stdio.h> - -int main(int argc, - char **argv) -@{ - init_scanner(); - parse(); - if (argc != 1) - @{ - fprintf(stderr, "tc: No args expected.\n"); - exit(1); - @} - if (nerr == 0) - gencode(); - else - fprintf(stderr, "No code generated.\n"); -@asis{}<<<<<<< driver.c - exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); -@asis{}======= - exit(!!nerr); -@asis{}>>>>>>> 1.6 -@} -@end example - -@noindent -@cindex Markers, conflict -@cindex Conflict markers -@cindex <<<<<<< -@cindex >>>>>>> -@cindex ======= - -Note how all non-overlapping modifications are incorporated in your working -copy, and that the overlapping section is clearly marked with -@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. - -@cindex Resolving a conflict -@cindex Conflict resolution -You resolve the conflict by editing the file, removing the markers and -the erroneous line. Suppose you end up with this file: -@c -- Add xref to the pcl-cvs manual when it talks -@c -- about this. -@example -#include <stdlib.h> -#include <stdio.h> - -int main(int argc, - char **argv) -@{ - init_scanner(); - parse(); - if (argc != 1) - @{ - fprintf(stderr, "tc: No args expected.\n"); - exit(1); - @} - if (nerr == 0) - gencode(); - else - fprintf(stderr, "No code generated.\n"); - exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); -@} -@end example - -@noindent -You can now go ahead and commit this as revision 1.7. - -@example -$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c -Checking in driver.c; -/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c -new revision: 1.7; previous revision: 1.6 -done -@end example - -For your protection, @sc{cvs} will refuse to check in a -file if a conflict occurred and you have not resolved -the conflict. Currently to resolve a conflict, you -must change the timestamp on the file. In previous -versions of @sc{cvs}, you also needed to -insure that the file contains no conflict markers. -Because -your file may legitimately contain conflict markers (that -is, occurrences of @samp{>>>>>>> } at the start of a -line that don't mark a conflict), the current -version of @sc{cvs} will print a warning and proceed to -check in the file. -@c The old behavior was really icky; the only way out -@c was to start hacking on -@c the @code{CVS/Entries} file or other such workarounds. -@c -@c If the timestamp thing isn't considered nice enough, -@c maybe there should be a "cvs resolved" command -@c which clears the conflict indication. For a nice user -@c interface, this should be invoked by an interactive -@c merge tool like emerge rather than by the user -@c directly--such a tool can verify that the user has -@c really dealt with each conflict. - -@cindex emerge -If you use release 1.04 or later of pcl-cvs (a @sc{gnu} -Emacs front-end for @sc{cvs}) you can use an Emacs -package called emerge to help you resolve conflicts. -See the documentation for pcl-cvs. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Informing others -@section Informing others about commits -@cindex Informing others -@cindex Spreading information -@cindex Mail, automatic mail on commit - -It is often useful to inform others when you commit a -new revision of a file. The @file{loginfo} file can be -used to automate this process. -@xref{loginfo}. You can use these features of @sc{cvs} -to, for instance, instruct @sc{cvs} to mail a -message to all developers, or post a message to a local -newsgroup. -@c -- More text would be nice here. - -@node Concurrency -@section Several developers simultaneously attempting to run CVS - -@cindex Locks, cvs, introduction -@c For a discussion of *why* CVS creates locks, see -@c the comment at the start of src/lock.c -If several developers try to run @sc{cvs} at the same -time, one may get the following message: - -@example -[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo -@end example - -@cindex #cvs.rfl, removing -@cindex #cvs.wfl, removing -@cindex #cvs.lock, removing -@sc{cvs} will try again every 30 seconds, and either -continue with the operation or print the message again, -if it still needs to wait. If a lock seems to stick -around for an undue amount of time, find the person -holding the lock and ask them about the cvs command -they are running. If they aren't running a cvs -command, look in the repository directory mentioned in -the message and remove files which they own whose names -start with @file{#cvs.rfl}, -@file{#cvs.wfl}, or @file{#cvs.lock}. - -Note that these locks are to protect @sc{cvs}'s -internal data structures and have no relationship to -the word @dfn{lock} in the sense used by -@sc{rcs}---which refers to reserved checkouts -(@pxref{Multiple developers}). - -Any number of people can be reading from a given -repository at a time; only when someone is writing do -the locks prevent other people from reading or writing. - -@cindex Atomic transactions, lack of -@cindex Transactions, atomic, lack of -@c the following talks about what one might call commit/update -@c atomicity. -@c Probably also should say something about -@c commit/commit atomicity, that is, "An update will -@c not get partial versions of more than one commit". -@c CVS currently has this property and I guess we can -@c make it a documented feature. -@c For example one person commits -@c a/one.c and b/four.c and another commits a/two.c and -@c b/three.c. Then an update cannot get the new a/one.c -@c and a/two.c and the old b/four.c and b/three.c. -One might hope for the following property: - -@quotation -If someone commits some changes in one cvs command, -then an update by someone else will either get all the -changes, or none of them. -@end quotation - -@noindent -but @sc{cvs} does @emph{not} have this property. For -example, given the files - -@example -a/one.c -a/two.c -b/three.c -b/four.c -@end example - -@noindent -if someone runs - -@example -cvs ci a/two.c b/three.c -@end example - -@noindent -and someone else runs @code{cvs update} at the same -time, the person running @code{update} might get only -the change to @file{b/three.c} and not the change to -@file{a/two.c}. - -@node Watches -@section Mechanisms to track who is editing files -@cindex Watches - -For many groups, use of @sc{cvs} in its default mode is -perfectly satisfactory. Users may sometimes go to -check in a modification only to find that another -modification has intervened, but they deal with it and -proceed with their check in. Other groups prefer to be -able to know who is editing what files, so that if two -people try to edit the same file they can choose to -talk about who is doing what when rather than be -surprised at check in time. The features in this -section allow such coordination, while retaining the -ability of two developers to edit the same file at the -same time. - -@c Some people might ask why CVS does not enforce the -@c rule on chmod, by requiring a cvs edit before a cvs -@c commit. The main reason is that it could always be -@c circumvented--one could edit the file, and -@c then when ready to check it in, do the cvs edit and put -@c in the new contents and do the cvs commit. One -@c implementation note: if we _do_ want to have cvs commit -@c require a cvs edit, we should store the state on -@c whether the cvs edit has occurred in the working -@c directory, rather than having the server try to keep -@c track of what working directories exist. -@c FIXME: should the above discussion be part of the -@c manual proper, somewhere, not just in a comment? -For maximum benefit developers should use @code{cvs -edit} (not @code{chmod}) to make files read-write to -edit them, and @code{cvs release} (not @code{rm}) to -discard a working directory which is no longer in use, -but @sc{cvs} is not able to enforce this behavior. - -@c I'm a little dissatisfied with this presentation, -@c because "watch on"/"edit"/"editors" are one set of -@c functionality, and "watch add"/"watchers" is another -@c which is somewhat orthogonal even though they interact in -@c various ways. But I think it might be -@c confusing to describe them separately (e.g. "watch -@c add" with loginfo). I don't know. - -@menu -* Setting a watch:: Telling CVS to watch certain files -* Getting Notified:: Telling CVS to notify you -* Editing files:: How to edit a file which is being watched -* Watch information:: Information about who is watching and editing -* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier -@end menu - -@node Setting a watch -@subsection Telling CVS to watch certain files - -To enable the watch features, you first specify that -certain files are to be watched. - -@cindex watch on (subcommand) -@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} - -@cindex Read-only files, and watches -Specify that developers should run @code{cvs edit} -before editing @var{files}. @sc{cvs} will create working -copies of @var{files} read-only, to remind developers -to run the @code{cvs edit} command before working on -them. - -If @var{files} includes the name of a directory, @sc{cvs} -arranges to watch all files added to the corresponding -repository directory, and sets a default for files -added in the future; this allows the user to set -notification policies on a per-directory basis. The -contents of the directory are processed recursively, -unless the @code{-l} option is given. -The @code{-R} option can be used to force recursion if the @code{-l} -option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). - -If @var{files} is omitted, it defaults to the current directory. - -@cindex watch off (subcommand) -@end deffn - -@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} - -Do not create @var{files} read-only on checkout; thus, -developers will not be reminded to use @code{cvs edit} -and @code{cvs unedit}. -@ignore -@sc{cvs} will check out @var{files} -read-write as usual, unless other permissions override -due to the @code{PreservePermissions} option being -enabled in the @file{config} administrative file -(@pxref{Special Files}, @pxref{config}) -@end ignore - -The @var{files} and options are processed as for @code{cvs -watch on}. - -@end deffn - -@node Getting Notified -@subsection Telling CVS to notify you - -You can tell @sc{cvs} that you want to receive -notifications about various actions taken on a file. -You can do this without using @code{cvs watch on} for -the file, but generally you will want to use @code{cvs -watch on}, to remind developers to use the @code{cvs edit} -command. - -@cindex watch add (subcommand) -@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} - -Add the current user to the list of people to receive notification of -work done on @var{files}. - -The @code{-a} option specifies what kinds of events @sc{cvs} should notify -the user about. @var{action} is one of the following: - -@table @code - -@item edit -Another user has applied the @code{cvs edit} command (described -below) to a watched file. - -@item commit -Another user has committed changes to one of the named @var{files}. - -@item unedit -Another user has abandoned editing a file (other than by committing changes). -They can do this in several ways, by: - -@itemize @bullet - -@item -applying the @code{cvs unedit} command (described below) to the file - -@item -applying the @code{cvs release} command (@pxref{release}) to the file's parent directory -(or recursively to a directory more than one level up) - -@item -deleting the file and allowing @code{cvs update} to recreate it - -@end itemize - -@item all -All of the above. - -@item none -None of the above. (This is useful with @code{cvs edit}, -described below.) - -@end table - -The @code{-a} option may appear more than once, or not at all. If -omitted, the action defaults to @code{all}. - -The @var{files} and options are processed as for -@code{cvs watch on}. - -@end deffn - - -@cindex watch remove (subcommand) -@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} - -Remove a notification request established using @code{cvs watch add}; -the arguments are the same. If the @code{-a} option is present, only -watches for the specified actions are removed. - -@end deffn - -@cindex notify (admin file) -When the conditions exist for notification, @sc{cvs} -calls the @file{notify} administrative file. Edit -@file{notify} as one edits the other administrative -files (@pxref{Intro administrative files}). This -file follows the usual conventions for administrative -files (@pxref{syntax}), where each line is a regular -expression followed by a command to execute. The -command should contain a single occurrence of @samp{%s} -which will be replaced by the user to notify; the rest -of the information regarding the notification will be -supplied to the command on standard input. The -standard thing to put in the @code{notify} file is the -single line: - -@example -ALL mail %s -s "CVS notification" -@end example - -@noindent -This causes users to be notified by electronic mail. -@c FIXME: should it be this hard to set up this -@c behavior (and the result when one fails to do so, -@c silent failure to notify, so non-obvious)? Should -@c CVS give a warning if no line in notify matches (and -@c document the use of "DEFAULT :" for the case where -@c skipping the notification is indeed desired)? - -@cindex users (admin file) -Note that if you set this up in the straightforward -way, users receive notifications on the server machine. -One could of course write a @file{notify} script which -directed notifications elsewhere, but to make this -easy, @sc{cvs} allows you to associate a notification -address for each user. To do so create a file -@file{users} in @file{CVSROOT} with a line for each -user in the format @var{user}:@var{value}. Then -instead of passing the name of the user to be notified -to @file{notify}, @sc{cvs} will pass the @var{value} -(normally an email address on some other machine). - -@sc{cvs} does not notify you for your own changes. -Currently this check is done based on whether the user -name of the person taking the action which triggers -notification matches the user name of the person -getting notification. In fact, in general, the watches -features only track one edit by each user. It probably -would be more useful if watches tracked each working -directory separately, so this behavior might be worth -changing. -@c "behavior might be worth changing" is an effort to -@c point to future directions while also not promising -@c that "they" (as in "why don't they fix CVS to....") -@c will do this. -@c one implementation issue is identifying whether a -@c working directory is same or different. Comparing -@c pathnames/hostnames is hopeless, but having the server -@c supply a serial number which the client stores in the -@c CVS directory as a magic cookie should work. - -@node Editing files -@subsection How to edit a file which is being watched - -@cindex Checkout, as term for getting ready to edit -Since a file which is being watched is checked out -read-only, you cannot simply edit it. To make it -read-write, and inform others that you are planning to -edit it, use the @code{cvs edit} command. Some systems -call this a @dfn{checkout}, but @sc{cvs} uses that term -for obtaining a copy of the sources (@pxref{Getting the -source}), an operation which those systems call a -@dfn{get} or a @dfn{fetch}. -@c Issue to think about: should we transition CVS -@c towards the "get" terminology? "cvs get" is already a -@c synonym for "cvs checkout" and that section of the -@c manual refers to "Getting the source". If this is -@c done, needs to be done gingerly (for example, we should -@c still accept "checkout" in .cvsrc files indefinitely -@c even if the CVS's messages are changed from "cvs checkout: " -@c to "cvs get: "). -@c There is a concern about whether "get" is not as -@c good for novices because it is a more general term -@c than "checkout" (and thus arguably harder to assign -@c a technical meaning for). - -@cindex edit (subcommand) -@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} - -Prepare to edit the working files @var{files}. @sc{cvs} makes the -@var{files} read-write, and notifies users who have requested -@code{edit} notification for any of @var{files}. - -The @code{cvs edit} command accepts the same options as the -@code{cvs watch add} command, and establishes a temporary watch for the -user on @var{files}; @sc{cvs} will remove the watch when @var{files} are -@code{unedit}ed or @code{commit}ted. If the user does not wish to -receive notifications, she should specify @code{-a none}. - -The @var{files} and the options are processed as for the @code{cvs -watch} commands. - -@ignore -@strong{Caution: If the @code{PreservePermissions} -option is enabled in the repository (@pxref{config}), -@sc{cvs} will not change the permissions on any of the -@var{files}. The reason for this change is to ensure -that using @samp{cvs edit} does not interfere with the -ability to store file permissions in the @sc{cvs} -repository.} -@end ignore - -@end deffn - -Normally when you are done with a set of changes, you -use the @code{cvs commit} command, which checks in your -changes and returns the watched files to their usual -read-only state. But if you instead decide to abandon -your changes, or not to make any changes, you can use -the @code{cvs unedit} command. - -@cindex unedit (subcommand) -@cindex Abandoning work -@cindex Reverting to repository version -@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} - -Abandon work on the working files @var{files}, and revert them to the -repository versions on which they are based. @sc{cvs} makes those -@var{files} read-only for which users have requested notification using -@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} -notification for any of @var{files}. - -The @var{files} and options are processed as for the -@code{cvs watch} commands. - -If watches are not in use, the @code{unedit} command -probably does not work, and the way to revert to the -repository version is with the command @code{cvs update -C file} -(@pxref{update}). -The meaning is -not precisely the same; the latter may also -bring in some changes which have been made in the -repository since the last time you updated. -@c It would be a useful enhancement to CVS to make -@c unedit work in the non-watch case as well. -@end deffn - -When using client/server @sc{cvs}, you can use the -@code{cvs edit} and @code{cvs unedit} commands even if -@sc{cvs} is unable to successfully communicate with the -server; the notifications will be sent upon the next -successful @sc{cvs} command. - -@node Watch information -@subsection Information about who is watching and editing - -@cindex watchers (subcommand) -@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} - -List the users currently watching changes to @var{files}. The report -includes the files being watched, and the mail address of each watcher. - -The @var{files} and options are processed as for the -@code{cvs watch} commands. - -@end deffn - - -@cindex editors (subcommand) -@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} - -List the users currently working on @var{files}. The report -includes the mail address of each user, the time when the user began -working with the file, and the host and path of the working directory -containing the file. - -The @var{files} and options are processed as for the -@code{cvs watch} commands. - -@end deffn - -@node Watches Compatibility -@subsection Using watches with old versions of CVS - -@cindex CVS 1.6, and watches -If you use the watch features on a repository, it -creates @file{CVS} directories in the repository and -stores the information about watches in that directory. -If you attempt to use @sc{cvs} 1.6 or earlier with the -repository, you get an error message such as the -following (all on one line): - -@example -cvs update: cannot open CVS/Entries for reading: -No such file or directory -@end example - -@noindent -and your operation will likely be aborted. To use the -watch features, you must upgrade all copies of @sc{cvs} -which use that repository in local or server mode. If -you cannot upgrade, use the @code{watch off} and -@code{watch remove} commands to remove all watches, and -that will restore the repository to a state which -@sc{cvs} 1.6 can cope with. - -@node Choosing a model -@section Choosing between reserved or unreserved checkouts -@cindex Choosing, reserved or unreserved checkouts - -Reserved and unreserved checkouts each have pros and -cons. Let it be said that a lot of this is a matter of -opinion or what works given different groups' working -styles, but here is a brief description of some of the -issues. There are many ways to organize a team of -developers. @sc{cvs} does not try to enforce a certain -organization. It is a tool that can be used in several -ways. - -Reserved checkouts can be very counter-productive. If -two persons want to edit different parts of a file, -there may be no reason to prevent either of them from -doing so. Also, it is common for someone to take out a -lock on a file, because they are planning to edit it, -but then forget to release the lock. - -@c "many groups"? specifics? cites to papers on this? -@c some way to weasel-word it a bit more so we don't -@c need facts :-)? -People, especially people who are familiar with -reserved checkouts, often wonder how often conflicts -occur if unreserved checkouts are used, and how -difficult they are to resolve. The experience with -many groups is that they occur rarely and usually are -relatively straightforward to resolve. - -The rarity of serious conflicts may be surprising, until one realizes -that they occur only when two developers disagree on the proper design -for a given section of code; such a disagreement suggests that the -team has not been communicating properly in the first place. In order -to collaborate under @emph{any} source management regimen, developers -must agree on the general design of the system; given this agreement, -overlapping changes are usually straightforward to merge. - -In some cases unreserved checkouts are clearly -inappropriate. If no merge tool exists for the kind of -file you are managing (for example word processor files -or files edited by Computer Aided Design programs), and -it is not desirable to change to a program which uses a -mergeable data format, then resolving conflicts is -going to be unpleasant enough that you generally will -be better off to simply avoid the conflicts instead, by -using reserved checkouts. - -The watches features described above in @ref{Watches} -can be considered to be an intermediate model between -reserved checkouts and unreserved checkouts. When you -go to edit a file, it is possible to find out who else -is editing it. And rather than having the system -simply forbid both people editing the file, it can tell -you what the situation is and let you figure out -whether it is a problem in that particular case or not. -Therefore, for some groups it can be considered the -best of both the reserved checkout and unreserved -checkout worlds. - -@c --------------------------------------------------------------------- -@node Revision management -@chapter Revision management -@cindex Revision management - -@c -- This chapter could be expanded a lot. -@c -- Experiences are very welcome! - -If you have read this far, you probably have a pretty -good grasp on what @sc{cvs} can do for you. This -chapter talks a little about things that you still have -to decide. - -If you are doing development on your own using @sc{cvs} -you could probably skip this chapter. The questions -this chapter takes up become more important when more -than one person is working in a repository. - -@menu -* When to commit:: Some discussion on the subject -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node When to commit -@section When to commit? -@cindex When to commit -@cindex Committing, when to -@cindex Policy - -Your group should decide which policy to use regarding -commits. Several policies are possible, and as your -experience with @sc{cvs} grows you will probably find -out what works for you. - -If you commit files too quickly you might commit files -that do not even compile. If your partner updates his -working sources to include your buggy file, he will be -unable to compile the code. On the other hand, other -persons will not be able to benefit from the -improvements you make to the code if you commit very -seldom, and conflicts will probably be more common. - -It is common to only commit files after making sure -that they can be compiled. Some sites require that the -files pass a test suite. Policies like this can be -enforced using the commitinfo file -(@pxref{commitinfo}), but you should think twice before -you enforce such a convention. By making the -development environment too controlled it might become -too regimented and thus counter-productive to the real -goal, which is to get software written. - -@c --------------------------------------------------------------------- -@node Keyword substitution -@chapter Keyword substitution -@cindex Keyword substitution -@cindex Keyword expansion -@cindex Identifying files - -@comment Be careful when editing this chapter. -@comment Remember that this file is kept under -@comment version control, so we must not accidentally -@comment include a valid keyword in the running text. - -As long as you edit source files inside a working -directory you can always find out the state of -your files via @samp{cvs status} and @samp{cvs log}. -But as soon as you export the files from your -development environment it becomes harder to identify -which revisions they are. - -@sc{cvs} can use a mechanism known as @dfn{keyword -substitution} (or @dfn{keyword expansion}) to help -identifying the files. Embedded strings of the form -@code{$@var{keyword}$} and -@code{$@var{keyword}:@dots{}$} in a file are replaced -with strings of the form -@code{$@var{keyword}:@var{value}$} whenever you obtain -a new revision of the file. - -@menu -* Keyword list:: Keywords -* Using keywords:: Using keywords -* Avoiding substitution:: Avoiding substitution -* Substitution modes:: Substitution modes -* Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Keyword list -@section Keyword List -@cindex Keyword List - -@c FIXME: need some kind of example here I think, -@c perhaps in a -@c "Keyword intro" node. The intro in the "Keyword -@c substitution" node itself seems OK, but to launch -@c into a list of the keywords somehow seems too abrupt. - -This is a list of the keywords: - -@table @code -@cindex Author keyword -@item $@splitrcskeyword{Author}$ -The login name of the user who checked in the revision. - -@cindex Date keyword -@item $@splitrcskeyword{Date}$ -The date and time (UTC) the revision was checked in. - -@cindex Header keyword -@item $@splitrcskeyword{Header}$ -A standard header containing the full pathname of the -@sc{rcs} file, the revision number, the date (UTC), the -author, the state, and the locker (if locked). Files -will normally never be locked when you use @sc{cvs}. - -@cindex Id keyword -@item $@splitrcskeyword{Id}$ -Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} -filename is without a path. - -@cindex Name keyword -@item $@splitrcskeyword{Name}$ -Tag name used to check out this file. The keyword is -expanded only if one checks out with an explicit tag -name. For example, when running the command @code{cvs -co -r first}, the keyword expands to @samp{Name: first}. - -@cindex Locker keyword -@item $@splitrcskeyword{Locker}$ -The login name of the user who locked the revision -(empty if not locked, which is the normal case unless -@code{cvs admin -l} is in use). - -@cindex Log keyword -@item $@splitrcskeyword{Log}$ -The log message supplied during commit, preceded by a -header containing the @sc{rcs} filename, the revision -number, the author, and the date (UTC). Existing log -messages are @emph{not} replaced. Instead, the new log -message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}. -Each new line is prefixed with the same string which -precedes the @code{$Log} keyword. For example, if the -file contains: - -@example - /* Here is what people have been up to: - * - * $@splitrcskeyword{Log}: frob.c,v $ - * Revision 1.1 1997/01/03 14:23:51 joe - * Add the superfrobnicate option - * - */ -@end example - -@noindent -then additional lines which are added when expanding -the @code{$Log} keyword will be preceded by @samp{ * }. -Unlike previous versions of @sc{cvs} and @sc{rcs}, the -@dfn{comment leader} from the @sc{rcs} file is not used. -The @code{$Log} keyword is useful for -accumulating a complete change log in a source file, -but for several reasons it can be problematic. -@xref{Log keyword}. - -@cindex RCSfile keyword -@item $@splitrcskeyword{RCSfile}$ -The name of the RCS file without a path. - -@cindex Revision keyword -@item $@splitrcskeyword{Revision}$ -The revision number assigned to the revision. - -@cindex Source keyword -@item $@splitrcskeyword{Source}$ -The full pathname of the RCS file. - -@cindex State keyword -@item $@splitrcskeyword{State}$ -The state assigned to the revision. States can be -assigned with @code{cvs admin -s}---see @ref{admin options}. - -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Using keywords -@section Using keywords - -To include a keyword string you simply include the -relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the -file, and commit the file. @sc{cvs} will automatically (Or, -more accurately, as part of the update run that -automatically happens after a commit.) -expand the string as part of the commit operation. - -It is common to embed the @code{$@splitrcskeyword{Id}$} string in -the source files so that it gets passed through to -generated files. For example, if you are managing -computer program source code, you might include a -variable which is initialized to contain that string. -Or some C compilers may provide a @code{#pragma ident} -directive. Or a document management system might -provide a way to pass a string through to generated -files. - -@c Would be nice to give an example, but doing this in -@c portable C is not possible and the problem with -@c picking any one language (VMS HELP files, Ada, -@c troff, whatever) is that people use CVS for all -@c kinds of files. - -@cindex Ident (shell command) -The @code{ident} command (which is part of the @sc{rcs} -package) can be used to extract keywords and their -values from a file. This can be handy for text files, -but it is even more useful for extracting keywords from -binary files. - -@example -$ ident samp.c -samp.c: - $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ -$ gcc samp.c -$ ident a.out -a.out: - $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ -@end example - -@cindex What (shell command) -S@sc{ccs} is another popular revision control system. -It has a command, @code{what}, which is very similar to -@code{ident} and used for the same purpose. Many sites -without @sc{rcs} have @sc{sccs}. Since @code{what} -looks for the character sequence @code{@@(#)} it is -easy to include keywords that are detected by either -command. Simply prefix the keyword with the -magic @sc{sccs} phrase, like this: - -@example -static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Avoiding substitution -@section Avoiding substitution - -Keyword substitution has its disadvantages. Sometimes -you might want the literal text string -@samp{$@splitrcskeyword{Author}$} to appear inside a file without -@sc{cvs} interpreting it as a keyword and expanding it -into something like @samp{$@splitrcskeyword{Author}: ceder $}. - -There is unfortunately no way to selectively turn off -keyword substitution. You can use @samp{-ko} -(@pxref{Substitution modes}) to turn off keyword -substitution entirely. - -In many cases you can avoid using keywords in -the source, even though they appear in the final -product. For example, the source for this manual -contains @samp{$@@asis@{@}Author$} whenever the text -@samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff} -and @code{troff} you can embed the null-character -@code{\&} inside the keyword for a similar effect. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Substitution modes -@section Substitution modes -@cindex Keyword substitution, changing modes -@cindex -k (keyword substitution) -@cindex Kflag - -@c FIXME: This could be made more coherent, by expanding it -@c with more examples or something. -Each file has a stored default substitution mode, and -each working directory copy of a file also has a -substitution mode. The former is set by the @samp{-k} -option to @code{cvs add} and @code{cvs admin}; the -latter is set by the @samp{-k} or @samp{-A} options to @code{cvs -checkout} or @code{cvs update}. -@code{cvs diff} and @code{cvs rdiff} also -have @samp{-k} options. -For some examples, -see @ref{Binary files}, and @ref{Merging and keywords}. -@c The fact that -A is overloaded to mean both reset -@c sticky options and reset sticky tags/dates is -@c somewhat questionable. Perhaps there should be -@c separate options to reset sticky options (e.g. -k -@c A") and tags/dates (someone suggested -r HEAD could -@c do this instead of setting a sticky tag of "HEAD" -@c as in the status quo but I haven't thought much -@c about that idea. Of course -r .reset or something -@c could be coined if this needs to be a new option). -@c On the other hand, having -A mean "get things back -@c into the state after a fresh checkout" has a certain -@c appeal, and maybe there is no sufficient reason for -@c creeping featurism in this area. - -The modes available are: - -@table @samp -@item -kkv -Generate keyword strings using the default form, e.g. -@code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision} -keyword. - -@item -kkvl -Like @samp{-kkv}, except that a locker's name is always -inserted if the given revision is currently locked. -The locker's name is only relevant if @code{cvs admin --l} is in use. - -@item -kk -Generate only keyword names in keyword strings; omit -their values. For example, for the @code{Revision} -keyword, generate the string @code{$@splitrcskeyword{Revision}$} -instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option -is useful to ignore differences due to keyword -substitution when comparing different revisions of a -file (@pxref{Merging and keywords}). - -@item -ko -Generate the old keyword string, present in the working -file just before it was checked in. For example, for -the @code{Revision} keyword, generate the string -@code{$@splitrcskeyword{Revision}: 1.1 $} instead of -@code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the -string appeared when the file was checked in. - -@item -kb -Like @samp{-ko}, but also inhibit conversion of line -endings between the canonical form in which they are -stored in the repository (linefeed only), and the form -appropriate to the operating system in use on the -client. For systems, like unix, which use linefeed -only to terminate lines, this is the same as -@samp{-ko}. For more information on binary files, see -@ref{Binary files}. - -@item -kv -Generate only keyword values for keyword strings. For -example, for the @code{Revision} keyword, generate the string -@code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. -This can help generate files in programming languages -where it is hard to strip keyword delimiters like -@code{$@splitrcskeyword{Revision}: $} from a string. However, -further keyword substitution cannot be performed once -the keyword names are removed, so this option should be -used with care. - -One often would like to use @samp{-kv} with @code{cvs -export}---@pxref{export}. But be aware that doesn't -handle an export containing binary files correctly. - -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Log keyword -@section Problems with the $@splitrcskeyword{Log}$ keyword. - -The @code{$@splitrcskeyword{Log}$} keyword is somewhat -controversial. As long as you are working on your -development system the information is easily accessible -even if you do not use the @code{$@splitrcskeyword{Log}$} -keyword---just do a @code{cvs log}. Once you export -the file the history information might be useless -anyhow. - -A more serious concern is that @sc{cvs} is not good at -handling @code{$@splitrcskeyword{Log}$} entries when a branch is -merged onto the main trunk. Conflicts often result -from the merging operation. -@c Might want to check whether the CVS implementation -@c of RCS_merge has this problem the same way rcsmerge -@c does. I would assume so.... - -People also tend to "fix" the log entries in the file -(correcting spelling mistakes and maybe even factual -errors). If that is done the information from -@code{cvs log} will not be consistent with the -information inside the file. This may or may not be a -problem in real life. - -It has been suggested that the @code{$@splitrcskeyword{Log}$} -keyword should be inserted @emph{last} in the file, and -not in the files header, if it is to be used at all. -That way the long list of change messages will not -interfere with everyday source file browsing. - -@c --------------------------------------------------------------------- -@node Tracking sources -@chapter Tracking third-party sources -@cindex Third-party sources -@cindex Tracking sources - -@c FIXME: Need discussion of added and removed files. -@c FIXME: This doesn't really adequately introduce the -@c concepts of "vendor" and "you". They don't *have* -@c to be separate organizations or separate people. -@c We want a description which is somewhat more based on -@c the technical issues of which sources go where, but -@c also with enough examples of how this relates to -@c relationships like customer-supplier, developer-QA, -@c maintainer-contributor, or whatever, to make it -@c seem concrete. -If you modify a program to better fit your site, you -probably want to include your modifications when the next -release of the program arrives. @sc{cvs} can help you with -this task. - -@cindex Vendor -@cindex Vendor branch -@cindex Branch, vendor- -In the terminology used in @sc{cvs}, the supplier of the -program is called a @dfn{vendor}. The unmodified -distribution from the vendor is checked in on its own -branch, the @dfn{vendor branch}. @sc{cvs} reserves branch -1.1.1 for this use. - -When you modify the source and commit it, your revision -will end up on the main trunk. When a new release is -made by the vendor, you commit it on the vendor branch -and copy the modifications onto the main trunk. - -Use the @code{import} command to create and update -the vendor branch. When you import a new file, -the vendor branch is made the `head' revision, so -anyone that checks out a copy of the file gets that -revision. When a local modification is committed it is -placed on the main trunk, and made the `head' -revision. - -@menu -* First import:: Importing for the first time -* Update imports:: Updating with the import command -* Reverting local changes:: Reverting to the latest vendor release -* Binary files in imports:: Binary files require special handling -* Keywords in imports:: Keyword substitution might be undesirable -* Multiple vendor branches:: What if you get sources from several places? -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node First import -@section Importing for the first time -@cindex Importing modules - -@c Should mention naming conventions for vendor tags, -@c release tags, and perhaps directory names. -Use the @code{import} command to check in the sources -for the first time. When you use the @code{import} -command to track third-party sources, the @dfn{vendor -tag} and @dfn{release tags} are useful. The -@dfn{vendor tag} is a symbolic name for the branch -(which is always 1.1.1, unless you use the @samp{-b -@var{branch}} flag---see @ref{Multiple vendor branches}.). The -@dfn{release tags} are symbolic names for a particular -release, such as @samp{FSF_0_04}. - -@c I'm not completely sure this belongs here. But -@c we need to say it _somewhere_ reasonably obvious; it -@c is a common misconception among people first learning CVS -Note that @code{import} does @emph{not} change the -directory in which you invoke it. In particular, it -does not set up that directory as a @sc{cvs} working -directory; if you want to work with the sources import -them first and then check them out into a different -directory (@pxref{Getting the source}). - -@cindex wdiff (import example) -Suppose you have the sources to a program called -@code{wdiff} in a directory @file{wdiff-0.04}, -and are going to make private modifications that you -want to be able to use even when new releases are made -in the future. You start by importing the source to -your repository: - -@example -$ cd wdiff-0.04 -$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 -@end example - -The vendor tag is named @samp{FSF_DIST} in the above -example, and the only release tag assigned is -@samp{WDIFF_0_04}. -@c FIXME: Need to say where fsf/wdiff comes from. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Update imports -@section Updating with the import command - -When a new release of the source arrives, you import it into the -repository with the same @code{import} command that you used to set up -the repository in the first place. The only difference is that you -specify a different release tag this time: - -@example -$ tar xfz wdiff-0.05.tar.gz -$ cd wdiff-0.05 -$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 -@end example - -@strong{WARNING: If you use a release tag that already exists in one of the -repository archives, files removed by an import may not be detected.} - -For files that have not been modified locally, the newly created -revision becomes the head revision. If you have made local -changes, @code{import} will warn you that you must merge the changes -into the main trunk, and tell you to use @samp{checkout -j} to do so: - -@c FIXME: why "wdiff" here and "fsf/wdiff" in the -@c "import"? I think the assumption is that one has -@c "wdiff fsf/wdiff" or some such in modules, but it -@c would be better to not use modules in this example. -@example -$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff -@end example - -@noindent -The above command will check out the latest revision of -@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} -since yesterday into the working copy. If any conflicts arise during -the merge they should be resolved in the normal way (@pxref{Conflicts -example}). Then, the modified files may be committed. - -However, it is much better to use the two release tags rather than using -a date on the branch as suggested above: - -@example -$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff -@end example - -@noindent -The reason this is better is that -using a date, as suggested above, assumes that you do -not import more than one release of a product per day. -More importantly, using the release tags allows @sc{cvs} to detect files -that were removed between the two vendor releases and mark them for -removal. Since @code{import} has no way to detect removed files, you -should do a merge like this even if @code{import} doesn't tell you to. - -@node Reverting local changes -@section Reverting to the latest vendor release - -You can also revert local changes completely and return -to the latest vendor release by changing the `head' -revision back to the vendor branch on all files. For -example, if you have a checked-out copy of the sources -in @file{~/work.d/wdiff}, and you want to revert to the -vendor's version for all the files in that directory, -you would type: - -@example -$ cd ~/work.d/wdiff -$ cvs admin -bFSF_DIST . -@end example - -@noindent -You must specify the @samp{-bFSF_DIST} without any space -after the @samp{-b}. @xref{admin options}. - -@node Binary files in imports -@section How to handle binary files with cvs import - -Use the @samp{-k} wrapper option to tell import which -files are binary. @xref{Wrappers}. - -@node Keywords in imports -@section How to handle keyword substitution with cvs import - -The sources which you are importing may contain -keywords (@pxref{Keyword substitution}). For example, -the vendor may use @sc{cvs} or some other system -which uses similar keyword expansion syntax. If you -just import the files in the default fashion, then -the keyword expansions supplied by the vendor will -be replaced by keyword expansions supplied by your -own copy of @sc{cvs}. It may be more convenient to -maintain the expansions supplied by the vendor, so -that this information can supply information about -the sources that you imported from the vendor. - -To maintain the keyword expansions supplied by the -vendor, supply the @samp{-ko} option to @code{cvs -import} the first time you import the file. -This will turn off keyword expansion -for that file entirely, so if you want to be more -selective you'll have to think about what you want -and use the @samp{-k} option to @code{cvs update} or -@code{cvs admin} as appropriate. -@c Supplying -ko to import if the file already existed -@c has no effect. Not clear to me whether it should -@c or not. - -@node Multiple vendor branches -@section Multiple vendor branches - -All the examples so far assume that there is only one -vendor from which you are getting sources. In some -situations you might get sources from a variety of -places. For example, suppose that you are dealing with -a project where many different people and teams are -modifying the software. There are a variety of ways to -handle this, but in some cases you have a bunch of -source trees lying around and what you want to do more -than anything else is just to all put them in @sc{cvs} so -that you at least have them in one place. - -For handling situations in which there may be more than -one vendor, you may specify the @samp{-b} option to -@code{cvs import}. It takes as an argument the vendor -branch to import to. The default is @samp{-b 1.1.1}. - -For example, suppose that there are two teams, the red -team and the blue team, that are sending you sources. -You want to import the red team's efforts to branch -1.1.1 and use the vendor tag RED. You want to import -the blue team's efforts to branch 1.1.3 and use the -vendor tag BLUE. So the commands you might use are: - -@example -$ cvs import dir RED RED_1-0 -$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 -@end example - -Note that if your vendor tag does not match your -@samp{-b} option, @sc{cvs} will not detect this case! For -example, - -@example -$ cvs import -b 1.1.3 dir RED RED_1-0 -@end example - -@noindent -Be careful; this kind of mismatch is sure to sow -confusion or worse. I can't think of a useful purpose -for the ability to specify a mismatch here, but if you -discover such a use, don't. @sc{cvs} is likely to make this -an error in some future release. - -@c Probably should say more about the semantics of -@c multiple branches. What about the default branch? -@c What about joining (perhaps not as useful with -@c multiple branches, or perhaps it is. Either way -@c should be mentioned). - -@c I'm not sure about the best location for this. In -@c one sense, it might belong right after we've introduced -@c CVS's basic version control model, because people need -@c to figure out builds right away. The current location -@c is based on the theory that it kind of akin to the -@c "Revision management" section. -@node Builds -@chapter How your build system interacts with CVS -@cindex Builds -@cindex make - -As mentioned in the introduction, @sc{cvs} does not -contain software for building your software from source -code. This section describes how various aspects of -your build system might interact with @sc{cvs}. - -@c Is there a way to discuss this without reference to -@c tools other than CVS? I'm not sure there is; I -@c wouldn't think that people who learn CVS first would -@c even have this concern. -One common question, especially from people who are -accustomed to @sc{rcs}, is how to make their build get -an up to date copy of the sources. The answer to this -with @sc{cvs} is two-fold. First of all, since -@sc{cvs} itself can recurse through directories, there -is no need to modify your @file{Makefile} (or whatever -configuration file your build tool uses) to make sure -each file is up to date. Instead, just use two -commands, first @code{cvs -q update} and then -@code{make} or whatever the command is to invoke your -build tool. Secondly, you do not necessarily -@emph{want} to get a copy of a change someone else made -until you have finished your own work. One suggested -approach is to first update your sources, then -implement, build and -test the change you were thinking of, and then commit -your sources (updating first if necessary). By -periodically (in between changes, using the approach -just described) updating your entire tree, you ensure -that your sources are sufficiently up to date. - -@cindex Bill of materials -One common need is to record which versions of which -source files went into a particular build. This kind -of functionality is sometimes called @dfn{bill of -materials} or something similar. The best way to do -this with @sc{cvs} is to use the @code{tag} command to -record which versions went into a given build -(@pxref{Tags}). - -Using @sc{cvs} in the most straightforward manner -possible, each developer will have a copy of the entire -source tree which is used in a particular build. If -the source tree is small, or if developers are -geographically dispersed, this is the preferred -solution. In fact one approach for larger projects is -to break a project down into smaller -@c I say subsystem instead of module because they may or -@c may not use the modules file. -separately-compiled subsystems, and arrange a way of -releasing them internally so that each developer need -check out only those subsystems which they are -actively working on. - -Another approach is to set up a structure which allows -developers to have their own copies of some files, and -for other files to access source files from a central -location. Many people have come up with some such a -@c two such people are paul@sander.cupertino.ca.us (for -@c a previous employer) -@c and gunnar.tornblom@se.abb.com (spicm and related tools), -@c but as far as I know -@c no one has nicely packaged or released such a system (or -@c instructions for constructing one). -system using features such as the symbolic link feature -found in many operating systems, or the @code{VPATH} -feature found in many versions of @code{make}. One build -tool which is designed to help with this kind of thing -is Odin (see -@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). -@c Should we be saying more about Odin? Or how you use -@c it with CVS? Also, the Prime Time Freeware for Unix -@c disk (see http://www.ptf.com/) has Odin (with a nice -@c paragraph summarizing it on the web), so that might be a -@c semi-"official" place to point people. -@c -@c Of course, many non-CVS systems have this kind of -@c functionality, for example OSF's ODE -@c (http://www.osf.org/ode/) or mk -@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html -@c He has changed providers in the past; a search engine search -@c for "Peter Ziobrzynski" probably won't get too many -@c spurious hits :-). A more stable URL might be -@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure -@c there is any point in mentioning them here unless they -@c can work with CVS. - -@c --------------------------------------------------------------------- -@node Special Files -@chapter Special Files - -@cindex Special files -@cindex Device nodes -@cindex Ownership, saving in CVS -@cindex Permissions, saving in CVS -@cindex Hard links -@cindex Symbolic links - -In normal circumstances, @sc{cvs} works only with regular -files. Every file in a project is assumed to be -persistent; it must be possible to open, read and close -them; and so on. @sc{cvs} also ignores file permissions and -ownerships, leaving such issues to be resolved by the -developer at installation time. In other words, it is -not possible to "check in" a device into a repository; -if the device file cannot be opened, @sc{cvs} will refuse to -handle it. Files also lose their ownerships and -permissions during repository transactions. - -@ignore -If the configuration variable @code{PreservePermissions} -(@pxref{config}) is set in the repository, @sc{cvs} will -save the following file characteristics in the -repository: - -@itemize @bullet -@item user and group ownership -@item permissions -@item major and minor device numbers -@item symbolic links -@item hard link structure -@end itemize - -Using the @code{PreservePermissions} option affects the -behavior of @sc{cvs} in several ways. First, some of the -new operations supported by @sc{cvs} are not accessible to -all users. In particular, file ownership and special -file characteristics may only be changed by the -superuser. When the @code{PreservePermissions} -configuration variable is set, therefore, users will -have to be `root' in order to perform @sc{cvs} operations. - -When @code{PreservePermissions} is in use, some @sc{cvs} -operations (such as @samp{cvs status}) will not -recognize a file's hard link structure, and so will -emit spurious warnings about mismatching hard links. -The reason is that @sc{cvs}'s internal structure does not -make it easy for these operations to collect all the -necessary data about hard links, so they check for file -conflicts with inaccurate data. - -A more subtle difference is that @sc{cvs} considers a file -to have changed only if its contents have changed -(specifically, if the modification time of the working -file does not match that of the repository's file). -Therefore, if only the permissions, ownership or hard -linkage have changed, or if a device's major or minor -numbers have changed, @sc{cvs} will not notice. In order to -commit such a change to the repository, you must force -the commit with @samp{cvs commit -f}. This also means -that if a file's permissions have changed and the -repository file is newer than the working copy, -performing @samp{cvs update} will silently change the -permissions on the working copy. - -Changing hard links in a @sc{cvs} repository is particularly -delicate. Suppose that file @file{foo} is linked to -file @file{old}, but is later relinked to file -@file{new}. You can wind up in the unusual situation -where, although @file{foo}, @file{old} and @file{new} -have all had their underlying link patterns changed, -only @file{foo} and @file{new} have been modified, so -@file{old} is not considered a candidate for checking -in. It can be very easy to produce inconsistent -results this way. Therefore, we recommend that when it -is important to save hard links in a repository, the -prudent course of action is to @code{touch} any file -whose linkage or status has changed since the last -checkin. Indeed, it may be wise to @code{touch *} -before each commit in a directory with complex hard -link structures. - -It is worth noting that only regular files may -be merged, for reasons that hopefully are obvious. If -@samp{cvs update} or @samp{cvs checkout -j} attempts to -merge a symbolic link with a regular file, or two -device files for different kinds of devices, @sc{cvs} will -report a conflict and refuse to perform the merge. At -the same time, @samp{cvs diff} will not report any -differences between these files, since no meaningful -textual comparisons can be made on files which contain -no text. - -The @code{PreservePermissions} features do not work -with client/server @sc{cvs}. Another limitation is -that hard links must be to other files within the same -directory; hard links across directories are not -supported. -@end ignore - -@c --------------------------------------------------------------------- -@c ----- START MAN 1 ----- -@node CVS commands -@appendix Guide to CVS commands - -This appendix describes the overall structure of -@sc{cvs} commands, and describes some commands in -detail (others are described elsewhere; for a quick -reference to @sc{cvs} commands, @pxref{Invoking CVS}). -@c The idea is that we want to move the commands which -@c are described here into the main body of the manual, -@c in the process reorganizing the manual to be -@c organized around what the user wants to do, not -@c organized around CVS commands. -@c -@c Note that many users do expect a manual which is -@c organized by command. At least some users do. -@c One good addition to the "organized by command" -@c section (if any) would be "see also" links. -@c The awk manual might be a good example; it has a -@c reference manual which is more verbose than Invoking -@c CVS but probably somewhat less verbose than CVS -@c Commands. - -@menu -* Structure:: Overall structure of CVS commands -* Exit status:: Indicating CVS's success or failure -* ~/.cvsrc:: Default options with the ~/.cvsrc file -* Global options:: Options you give to the left of cvs_command -* Common options:: Options you give to the right of cvs_command -* add:: Add files and directories to the repository -* admin:: Administration -* annotate:: What revision modified each line of a file? -* checkout:: Checkout sources for editing -* commit:: Check files into the repository -* diff:: Show differences between revisions -* export:: Export sources from CVS, similar to checkout -* history:: Show status of files and users -* import:: Import sources into CVS, using vendor branches -* log:: Show log messages for files -* rdiff:: 'patch' format diffs between releases -* release:: Indicate that a directory is no longer in use -* remove:: Remove files from active development -* update:: Bring work tree in sync with repository -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Structure -@appendixsec Overall structure of CVS commands -@cindex Structure -@cindex CVS command structure -@cindex Command structure -@cindex Format of CVS commands - -The overall format of all @sc{cvs} commands is: - -@example -cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] -@end example - -@table @code -@item cvs -The name of the @sc{cvs} program. - -@item cvs_options -Some options that affect all sub-commands of @sc{cvs}. These are -described below. - -@item cvs_command -One of several different sub-commands. Some of the commands have -aliases that can be used instead; those aliases are noted in the -reference manual for that command. There are only two situations -where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a -list of available commands, and @samp{cvs -v} displays version -information on @sc{cvs} itself. - -@item command_options -Options that are specific for the command. - -@item command_args -Arguments to the commands. -@end table - -There is unfortunately some confusion between -@code{cvs_options} and @code{command_options}. -When given as a @code{cvs_option}, some options only -affect some of the commands. When given as a -@code{command_option} it may have a different meaning, and -be accepted by more commands. In other words, do not -take the above categorization too seriously. Look at -the documentation instead. - -@node Exit status -@appendixsec CVS's exit status -@cindex Exit status, of CVS - -@sc{cvs} can indicate to the calling environment whether it -succeeded or failed by setting its @dfn{exit status}. -The exact way of testing the exit status will vary from -one operating system to another. For example in a unix -shell script the @samp{$?} variable will be 0 if the -last command returned a successful exit status, or -greater than 0 if the exit status indicated failure. - -If @sc{cvs} is successful, it returns a successful status; -if there is an error, it prints an error message and -returns a failure status. The one exception to this is -the @code{cvs diff} command. It will return a -successful status if it found no differences, or a -failure status if there were differences or if there -was an error. Because this behavior provides no good -way to detect errors, in the future it is possible that -@code{cvs diff} will be changed to behave like the -other @sc{cvs} commands. -@c It might seem like checking whether cvs -q diff -@c produces empty or non-empty output can tell whether -@c there were differences or not. But it seems like -@c there are cases with output but no differences -@c (testsuite basica-8b). It is not clear to me how -@c useful it is for a script to be able to check -@c whether there were differences. -@c FIXCVS? In previous versions of CVS, cvs diff -@c returned 0 for no differences, 1 for differences, or -@c 2 for errors. Is this behavior worth trying to -@c bring back (but what does it mean for VMS?)? - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node ~/.cvsrc -@appendixsec Default options and the ~/.cvsrc file -@cindex .cvsrc file -@cindex Option defaults - -There are some @code{command_options} that are used so -often that you might have set up an alias or some other -means to make sure you always specify that option. One -example (the one that drove the implementation of the -@file{.cvsrc} support, actually) is that many people find the -default output of the @samp{diff} command to be very -hard to read, and that either context diffs or unidiffs -are much easier to understand. - -The @file{~/.cvsrc} file is a way that you can add -default options to @code{cvs_commands} within cvs, -instead of relying on aliases or other shell scripts. - -The format of the @file{~/.cvsrc} file is simple. The -file is searched for a line that begins with the same -name as the @code{cvs_command} being executed. If a -match is found, then the remainder of the line is split -up (at whitespace characters) into separate options and -added to the command arguments @emph{before} any -options from the command line. - -If a command has two names (e.g., @code{checkout} and -@code{co}), the official name, not necessarily the one -used on the command line, will be used to match against -the file. So if this is the contents of the user's -@file{~/.cvsrc} file: - -@example -log -N -diff -uN -rdiff -u -update -Pd -checkout -P -release -d -@end example - -@noindent -the command @samp{cvs checkout foo} would have the -@samp{-P} option added to the arguments, as well as -@samp{cvs co foo}. - -With the example file above, the output from @samp{cvs -diff foobar} will be in unidiff format. @samp{cvs diff --c foobar} will provide context diffs, as usual. -Getting "old" format diffs would be slightly more -complicated, because @code{diff} doesn't have an option -to specify use of the "old" format, so you would need -@samp{cvs -f diff foobar}. - -In place of the command name you can use @code{cvs} to -specify global options (@pxref{Global options}). For -example the following line in @file{.cvsrc} - -@example -cvs -z6 -@end example - -@noindent -causes @sc{cvs} to use compression level 6. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Global options -@appendixsec Global options -@cindex Options, global -@cindex Global options -@cindex Left-hand options - -The available @samp{cvs_options} (that are given to the -left of @samp{cvs_command}) are: - -@table @code -@item --allow-root=@var{rootdir} -Specify legal @sc{cvsroot} directory. See -@ref{Password authentication server}. - -@cindex Authentication, stream -@cindex Stream authentication -@item -a -Authenticate all communication between the client and -the server. Only has an effect on the @sc{cvs} client. -As of this writing, this is only implemented when using -a GSSAPI connection (@pxref{GSSAPI authenticated}). -Authentication prevents certain sorts of attacks -involving hijacking the active @sc{tcp} connection. -Enabling authentication does not enable encryption. - -@cindex RCSBIN, overriding -@cindex Overriding RCSBIN -@item -b @var{bindir} -In @sc{cvs} 1.9.18 and older, this specified that -@sc{rcs} programs are in the @var{bindir} directory. -Current versions of @sc{cvs} do not run @sc{rcs} -programs; for compatibility this option is accepted, -but it does nothing. - -@cindex TMPDIR, overriding -@cindex Overriding TMPDIR -@item -T @var{tempdir} -Use @var{tempdir} as the directory where temporary files are -located. Overrides the setting of the @code{$TMPDIR} environment -variable and any precompiled directory. This parameter should be -specified as an absolute pathname. -(When running client/server, @samp{-T} affects only the local process; -specifying @samp{-T} for the client has no effect on the server and -vice versa.) - -@cindex CVSROOT, overriding -@cindex Overriding CVSROOT -@item -d @var{cvs_root_directory} -Use @var{cvs_root_directory} as the root directory -pathname of the repository. Overrides the setting of -the @code{$CVSROOT} environment variable. See @ref{Repository}. - -@cindex EDITOR, overriding -@cindex Overriding EDITOR -@item -e @var{editor} -Use @var{editor} to enter revision log information. Overrides the -setting of the @code{$CVSEDITOR} and @code{$EDITOR} -environment variables. For more information, see -@ref{Committing your changes}. - -@item -f -Do not read the @file{~/.cvsrc} file. This -option is most often used because of the -non-orthogonality of the @sc{cvs} option set. For -example, the @samp{cvs log} option @samp{-N} (turn off -display of tag names) does not have a corresponding -option to turn the display on. So if you have -@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, -you may need to use @samp{-f} to show the tag names. - -@item -H -@itemx --help -Display usage information about the specified @samp{cvs_command} -(but do not actually execute the command). If you don't specify -a command name, @samp{cvs -H} displays overall help for -@sc{cvs}, including a list of other help options. -@c It seems to me it is better to document it this way -@c rather than trying to update this documentation -@c every time that we add a --help-foo option. But -@c perhaps that is confusing... - -@cindex Read-only mode -@item -n -Do not change any files. Attempt to execute the -@samp{cvs_command}, but only to issue reports; do not remove, -update, or merge any existing files, or create any new files. - -Note that @sc{cvs} will not necessarily produce exactly -the same output as without @samp{-n}. In some cases -the output will be the same, but in other cases -@sc{cvs} will skip some of the processing that would -have been required to produce the exact same output. - -@item -Q -Cause the command to be really quiet; the command will only -generate output for serious problems. - -@item -q -Cause the command to be somewhat quiet; informational messages, -such as reports of recursion through subdirectories, are -suppressed. - -@cindex Read-only files, and -r -@item -r -Make new working files read-only. Same effect -as if the @code{$CVSREAD} environment variable is set -(@pxref{Environment variables}). The default is to -make working files writable, unless watches are on -(@pxref{Watches}). - -@item -s @var{variable}=@var{value} -Set a user variable (@pxref{Variables}). - -@cindex Trace -@item -t -Trace program execution; display messages showing the steps of -@sc{cvs} activity. Particularly useful with @samp{-n} to explore the -potential impact of an unfamiliar command. - -@item -v -@item --version -Display version and copyright information for @sc{cvs}. - -@cindex CVSREAD, overriding -@cindex Overriding CVSREAD -@item -w -Make new working files read-write. Overrides the -setting of the @code{$CVSREAD} environment variable. -Files are created read-write by default, unless @code{$CVSREAD} is -set or @samp{-r} is given. -@c Note that -w only overrides -r and CVSREAD; it has -@c no effect on files which are readonly because of -@c "cvs watch on". My guess is that is the way it -@c should be (or should "cvs -w get" on a watched file -@c be the same as a get and a cvs edit?), but I'm not -@c completely sure whether to document it this way. - -@item -x -@cindex Encryption -Encrypt all communication between the client and the -server. Only has an effect on the @sc{cvs} client. As -of this writing, this is only implemented when using a -GSSAPI connection (@pxref{GSSAPI authenticated}) or a -Kerberos connection (@pxref{Kerberos authenticated}). -Enabling encryption implies that message traffic is -also authenticated. Encryption support is not -available by default; it must be enabled using a -special configure option, @file{--enable-encryption}, -when you build @sc{cvs}. - -@item -z @var{gzip-level} -@cindex Compression -@cindex Gzip -Set the compression level. -Valid levels are 1 (high speed, low compression) to -9 (low speed, high compression), or 0 to disable -compression (the default). -Only has an effect on the @sc{cvs} client. - -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Common options -@appendixsec Common command options -@cindex Common options -@cindex Right-hand options - -This section describes the @samp{command_options} that -are available across several @sc{cvs} commands. These -options are always given to the right of -@samp{cvs_command}. Not all -commands support all of these options; each option is -only supported for commands where it makes sense. -However, when a command has one of these options you -can almost always count on the same behavior of the -option as in other commands. (Other command options, -which are listed with the individual commands, may have -different behavior from one @sc{cvs} command to the other). - -@strong{The @samp{history} command is an exception; it supports -many options that conflict even with these standard options.} - -@table @code -@cindex Dates -@cindex Time -@cindex Specifying dates -@item -D @var{date_spec} -Use the most recent revision no later than @var{date_spec}. -@var{date_spec} is a single argument, a date description -specifying a date in the past. - -The specification is @dfn{sticky} when you use it to make a -private copy of a source file; that is, when you get a working -file using @samp{-D}, @sc{cvs} records the date you specified, so that -further updates in the same directory will use the same date -(for more information on sticky tags/dates, @pxref{Sticky tags}). - -@samp{-D} is available with the @code{annotate}, @code{checkout}, -@code{diff}, @code{export}, @code{history}, -@code{rdiff}, @code{rtag}, and @code{update} commands. -(The @code{history} command uses this option in a -slightly different way; @pxref{history options}). - -@c What other formats should we accept? I don't want -@c to start accepting a whole mess of non-standard -@c new formats (there are a lot which are in wide use in -@c one context or another), but practicality does -@c dictate some level of flexibility. -@c * POSIX.2 (e.g. touch, ls output, date) and other -@c POSIX and/or de facto unix standards (e.g. at). The -@c practice here is too inconsistent to be of any use. -@c * VMS dates. This is not a formal standard, but -@c there is a published specification (see SYS$ASCTIM -@c and SYS$BINTIM in the _VMS System Services Reference -@c Manual_), it is implemented consistently in VMS -@c utilities, and VMS users will expect CVS running on -@c VMS to support this format (and if we're going to do -@c that, better to make CVS support it on all -@c platforms. Maybe). -@c -@c NOTE: The tar manual has some documentation for -@c getdate.y (just for our info; we don't want to -@c attempt to document all the formats accepted by -@c getdate.y). -@c -@c One more note: In output, CVS should consistently -@c use one date format, and that format should be one that -@c it accepts in input as well. The former isn't -@c really true (see survey below), and I'm not -@c sure that either of those formats is accepted in -@c input. -@c -@c cvs log -@c current 1996/01/02 13:45:31 -@c Internet 02 Jan 1996 13:45:31 UT -@c ISO 1996-01-02 13:45:31 -@c cvs ann -@c current 02-Jan-96 -@c Internet-like 02 Jan 96 -@c ISO 96-01-02 -@c cvs status -@c current Tue Jun 11 02:54:53 1996 -@c Internet [Tue,] 11 Jun 1996 02:54:53 -@c ISO 1996-06-11 02:54:53 -@c note: date possibly should be omitted entirely for -@c other reasons. -@c cvs editors -@c current Tue Jun 11 02:54:53 1996 GMT -@c cvs history -@c current 06/11 02:54 +0000 -@c any others? -@c There is a good chance the proper solution has to -@c involve at least some level of letting the user -@c decide which format (with the default being the -@c formats CVS has always used; changing these might be -@c _very_ disruptive since scripts may very well be -@c parsing them). -@c -@c Another random bit of prior art concerning dates is -@c the strptime function which takes templates such as -@c "%m/%d/%y", and apparent a variant of getdate() -@c which also honors them. See -@c X/Open CAE Specification, System Interfaces and -@c Headers Issue 4, Version 2 (September 1994), in the -@c entry for getdate() on page 231 - -@cindex Timezone, in input -@cindex Zone, time, in input -A wide variety of date formats are supported by -@sc{cvs}. The most standard ones are ISO8601 (from the -International Standards Organization) and the Internet -e-mail standard (specified in RFC822 as amended by -RFC1123). - -@c Probably should be doing more to spell out just what -@c the rules are, rather than just giving examples. -@c But I want to keep this simple too. -@c So I don't know.... -@c A few specific issues: (1) Maybe should reassure -@c people that years after 2000 -@c work (they are in the testsuite, so they do indeed -@c work). (2) What do two digit years -@c mean? Where do we accept them? (3) Local times can -@c be ambiguous or nonexistent if they fall during the -@c hour when daylight savings time goes into or out of -@c effect. Pretty obscure, so I'm not at all sure we -@c should be documenting the behavior in that case. -ISO8601 dates have many variants but a few examples -are: - -@example -1972-09-24 -1972-09-24 20:05 -@end example -@c I doubt we really accept all ISO8601 format dates -@c (for example, decimal hours like 1972-09-24 20,2) -@c I'm not sure we should, many of them are pretty -@c bizarre and it has lots of gratuitous multiple ways -@c to specify the same thing. - -There are a lot more ISO8601 date formats, and @sc{cvs} -accepts many of them, but you probably don't want to -hear the @emph{whole} long story :-). - -@c Citing a URL here is kind of problematic given how -@c much they change and people who have old versions of -@c this manual, but in case we want to reinstate an -@c ISO8601 URL, a few are: -@c http://www.saqqara.demon.co.uk/datefmt.htm -@c http://www.cl.cam.ac.uk/~mgk25/iso-time.html -@c Citing some other ISO8601 source is probably even -@c worse :-). - -In addition to the dates allowed in Internet e-mail -itself, @sc{cvs} also allows some of the fields to be -omitted. For example: -@c FIXME: Need to figure out better, and document, -@c what we want to allow the user to omit. -@c NOTE: "omit" does not imply "reorder". -@c FIXME: Need to cite a web page describing how to get -@c RFC's. - -@example -24 Sep 1972 20:05 -24 Sep -@end example - -The date is interpreted as being in the -local timezone, unless a specific timezone is -specified. - -These two date formats are preferred. However, -@sc{cvs} currently accepts a wide variety of other date -formats. They are intentionally not documented here in -any detail, and future versions of @sc{cvs} might not -accept all of them. -@c We should document and testsuite "now" and -@c "yesterday". "now" is mentioned in the FAQ and -@c "yesterday" is mentioned in this document (and the -@c message from "cvs import" suggesting a merge -@c command). What else? Probably some/all of the "3 -@c weeks ago" family. -@c -@c Maybe at -@c some point have CVS start give warnings on "unofficial" -@c formats (many of which might be typos or user -@c misunderstandings, and/or formats people never/rarely -@c use to specify dates)? - -One such format is -@code{@var{month}/@var{day}/@var{year}}. This may -confuse people who are accustomed to having the month -and day in the other order; @samp{1/4/96} is January 4, -not April 1. - -Remember to quote the argument to the @samp{-D} -flag so that your shell doesn't interpret spaces as -argument separators. A command using the @samp{-D} -flag can look like this: - -@example -$ cvs diff -D "1 hour ago" cvs.texinfo -@end example - -@cindex Forcing a tag match -@item -f -When you specify a particular date or tag to @sc{cvs} commands, they -normally ignore files that do not contain the tag (or did not -exist prior to the date) that you specified. Use the @samp{-f} option -if you want files retrieved even when there is no match for the -tag or date. (The most recent revision of the file -will be used). - -Note that even with @samp{-f}, a tag that you specify -must exist (that is, in some file, not necessary in -every file). This is so that @sc{cvs} will continue to -give an error if you mistype a tag name. - -@need 800 -@samp{-f} is available with these commands: -@code{annotate}, @code{checkout}, @code{export}, -@code{rdiff}, @code{rtag}, and @code{update}. - -@strong{WARNING: The @code{commit} and @code{remove} -commands also have a -@samp{-f} option, but it has a different behavior for -those commands. See @ref{commit options}, and -@ref{Removing files}.} - -@item -k @var{kflag} -Alter the default processing of keywords. -See @ref{Keyword substitution}, for the meaning of -@var{kflag}. Your @var{kflag} specification is -@dfn{sticky} when you use it to create a private copy -of a source file; that is, when you use this option -with the @code{checkout} or @code{update} commands, -@sc{cvs} associates your selected @var{kflag} with the -file, and continues to use it with future update -commands on the same file until you specify otherwise. - -The @samp{-k} option is available with the @code{add}, -@code{checkout}, @code{diff}, @code{rdiff}, @code{import} and -@code{update} commands. - -@item -l -Local; run only in current working directory, rather than -recursing through subdirectories. - -Available with the following commands: @code{annotate}, @code{checkout}, -@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, -@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, -@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, -and @code{watchers}. - -@cindex Editor, avoiding invocation of -@cindex Avoiding editor invocation -@item -m @var{message} -Use @var{message} as log information, instead of -invoking an editor. - -Available with the following commands: @code{add}, -@code{commit} and @code{import}. - -@item -n -Do not run any tag program. (A program can be -specified to run in the modules -database (@pxref{modules}); this option bypasses it). - -@strong{This is not the same as the @samp{cvs -n} -program option, which you can specify to the left of a cvs command!} - -Available with the @code{checkout}, @code{export}, -and @code{rtag} commands. - -@item -P -Prune empty directories. See @ref{Removing directories}. - -@item -p -Pipe the files retrieved from the repository to standard output, -rather than writing them in the current directory. Available -with the @code{checkout} and @code{update} commands. - -@item -R -Process directories recursively. This is on by default. - -Available with the following commands: @code{annotate}, @code{checkout}, -@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, -@code{rdiff}, @code{remove}, @code{rtag}, -@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, -and @code{watchers}. - -@item -r @var{tag} -@cindex HEAD, special tag -@cindex BASE, special tag -Use the revision specified by the @var{tag} argument instead of the -default @dfn{head} revision. As well as arbitrary tags defined -with the @code{tag} or @code{rtag} command, two special tags are -always available: @samp{HEAD} refers to the most recent version -available in the repository, and @samp{BASE} refers to the -revision you last checked out into the current working directory. - -@c FIXME: What does HEAD really mean? I believe that -@c the current answer is the head of the default branch -@c for all cvs commands except diff. For diff, it -@c seems to be (a) the head of the trunk (or the default -@c branch?) if there is no sticky tag, (b) the head of the -@c branch for the sticky tag, if there is a sticky tag. -@c (b) is ugly as it differs -@c from what HEAD means for other commands, but people -@c and/or scripts are quite possibly used to it. -@c See "head" tests in sanity.sh. -@c Probably the best fix is to introduce two new -@c special tags, ".thead" for the head of the trunk, -@c and ".bhead" for the head of the current branch. -@c Then deprecate HEAD. This has the advantage of -@c not surprising people with a change to HEAD, and a -@c side benefit of also phasing out the poorly-named -@c HEAD (see discussion of reserved tag names in node -@c "Tags"). Of course, .thead and .bhead should be -@c carefully implemented (with the implementation the -@c same for "diff" as for everyone else), test cases -@c written (similar to the ones in "head"), new tests -@c cases written for things like default branches, &c. - -The tag specification is sticky when you use this -@c option -with @code{checkout} or @code{update} to make your own -copy of a file: @sc{cvs} remembers the tag and continues to use it on -future update commands, until you specify otherwise (for more information -on sticky tags/dates, @pxref{Sticky tags}). - -The tag can be either a symbolic or numeric tag, as -described in @ref{Tags}, or the name of a branch, as -described in @ref{Branching and merging}. -When a command expects a specific revision, -the name of a branch is interpreted as the most recent -revision on that branch. - -Specifying the @samp{-q} global option along with the -@samp{-r} command option is often useful, to suppress -the warning messages when the @sc{rcs} file -does not contain the specified tag. - -@strong{This is not the same as the overall @samp{cvs -r} option, -which you can specify to the left of a @sc{cvs} command!} - -@samp{-r} is available with the @code{annotate}, @code{checkout}, -@code{commit}, @code{diff}, @code{history}, @code{export}, @code{rdiff}, -@code{rtag}, and @code{update} commands. - -@item -W -Specify file names that should be filtered. You can -use this option repeatedly. The spec can be a file -name pattern of the same type that you can specify in -the @file{.cvswrappers} file. -Available with the following commands: @code{import}, -and @code{update}. - -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node add -@appendixsec add---Add files and directories to the repository -@cindex add (subcommand) - -@itemize @bullet -@item -Synopsis: add [-k rcs-kflag] [-m message] files... -@item -Requires: repository, working directory. -@item -Changes: repository, working directory. -@end itemize - -The @code{add} command is used to present new files -and directories for addition into the @sc{cvs} -repository. When @code{add} is used on a directory, -a new directory is created in the repository -immediately. When used on a file, only the working -directory is updated. Changes to the repository are -not made until the @code{commit} command is used on -the newly added file. - -The @code{add} command also resurrects files that -have been previously removed. This can be done -before or after the @code{commit} command is used -to finalize the removal of files. Resurrected files -are restored into the working directory at the time -the @code{add} command is executed. - -@menu -* add options:: add options -* add examples:: add examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node add options -@appendixsubsec add options - -These standard options are supported by @code{add} -(@pxref{Common options}, for a complete description of -them): - -@table @code -@item -k @var{kflag} -Process keywords according to @var{kflag}. See -@ref{Keyword substitution}. -This option is sticky; future updates of -this file in this working directory will use the same -@var{kflag}. The @code{status} command can be viewed -to see the sticky options. For more information on -the @code{status} command, @xref{Invoking CVS}. - -@item -m @var{message} -Use @var{message} as the log message, instead of -invoking an editor. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node add examples -@appendixsubsec add examples - -@appendixsubsubsec Adding a directory - -@example -$ mkdir doc -$ cvs add doc -Directory /path/to/repository/doc added to the repository -@end example - -@appendixsubsubsec Adding a file - -@example - -$ >TODO -$ cvs add TODO -cvs add: scheduling file `TODO' for addition -cvs add: use 'cvs commit' to add this file permanently -@end example - -@appendixsubsubsec Undoing a @code{remove} command - -@example -$ rm -f makefile -$ cvs remove makefile -cvs remove: scheduling `makefile' for removal -cvs remove: use 'cvs commit' to remove this file permanently -$ cvs add makefile -U makefile -cvs add: makefile, version 1.2, resurrected -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node admin -@appendixsec admin---Administration -@cindex Admin (subcommand) - -@itemize @bullet -@item -Requires: repository, working directory. -@item -Changes: repository. -@item -Synonym: rcs -@end itemize - -This is the @sc{cvs} interface to assorted -administrative facilities. Some of them have -questionable usefulness for @sc{cvs} but exist for -historical purposes. Some of the questionable options -are likely to disappear in the future. This command -@emph{does} work recursively, so extreme care should be -used. - -@cindex cvsadmin -On unix, if there is a group named @code{cvsadmin}, -only members of that group can run @code{cvs admin} -(except for the @code{cvs admin -k} command, which can -be run by anybody). This group should exist on the -server, or any system running the non-client/server -@sc{cvs}. To disallow @code{cvs admin} for all users, -create a group with no users in it. On NT, the -@code{cvsadmin} feature does not exist and all users -can run @code{cvs admin}. - -@menu -* admin options:: admin options -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node admin options -@appendixsubsec admin options - -Some of these options have questionable usefulness for -@sc{cvs} but exist for historical purposes. Some even -make it impossible to use @sc{cvs} until you undo the -effect! - -@table @code -@item -A@var{oldfile} -Might not work together with @sc{cvs}. Append the -access list of @var{oldfile} to the access list of the -@sc{rcs} file. - -@item -a@var{logins} -Might not work together with @sc{cvs}. Append the -login names appearing in the comma-separated list -@var{logins} to the access list of the @sc{rcs} file. - -@item -b[@var{rev}] -Set the default branch to @var{rev}. In @sc{cvs}, you -normally do not manipulate default branches; sticky -tags (@pxref{Sticky tags}) are a better way to decide -which branch you want to work on. There is one reason -to run @code{cvs admin -b}: to revert to the vendor's -version when using vendor branches (@pxref{Reverting -local changes}). -There can be no space between @samp{-b} and its argument. -@c Hmm, we don't document the usage where rev is -@c omitted. Maybe that usage can/should be deprecated -@c (and replaced with -bHEAD or something?) (so we can toss -@c the optional argument). Note that -bHEAD does not -@c work, as of 17 Sep 1997, but probably will once "cvs -@c admin" is internal to CVS. - -@cindex Comment leader -@item -c@var{string} -Sets the comment leader to @var{string}. The comment -leader is not used by current versions of @sc{cvs} or -@sc{rcs} 5.7. Therefore, you can almost surely not -worry about it. See @ref{Keyword substitution}. - -@item -e[@var{logins}] -Might not work together with @sc{cvs}. Erase the login -names appearing in the comma-separated list -@var{logins} from the access list of the RCS file. If -@var{logins} is omitted, erase the entire access list. -There can be no space between @samp{-e} and its argument. - -@item -I -Run interactively, even if the standard input is not a -terminal. This option does not work with the -client/server @sc{cvs} and is likely to disappear in -a future release of @sc{cvs}. - -@item -i -Useless with @sc{cvs}. This creates and initializes a -new @sc{rcs} file, without depositing a revision. With -@sc{cvs}, add files with the @code{cvs add} command -(@pxref{Adding files}). - -@item -k@var{subst} -Set the default keyword -substitution to @var{subst}. See @ref{Keyword -substitution}. Giving an explicit @samp{-k} option to -@code{cvs update}, @code{cvs export}, or @code{cvs -checkout} overrides this default. - -@item -l[@var{rev}] -Lock the revision with number @var{rev}. If a branch -is given, lock the latest revision on that branch. If -@var{rev} is omitted, lock the latest revision on the -default branch. There can be no space between -@samp{-l} and its argument. - -This can be used in conjunction with the -@file{rcslock.pl} script in the @file{contrib} -directory of the @sc{cvs} source distribution to -provide reserved checkouts (where only one user can be -editing a given file at a time). See the comments in -that file for details (and see the @file{README} file -in that directory for disclaimers about the unsupported -nature of contrib). According to comments in that -file, locking must set to strict (which is the default). - -@item -L -Set locking to strict. Strict locking means that the -owner of an RCS file is not exempt from locking for -checkin. For use with @sc{cvs}, strict locking must be -set; see the discussion under the @samp{-l} option above. - -@cindex Changing a log message -@cindex Replacing a log message -@cindex Correcting a log message -@cindex Fixing a log message -@cindex Log message, correcting -@item -m@var{rev}:@var{msg} -Replace the log message of revision @var{rev} with -@var{msg}. - -@c The rcs -M option, to suppress sending mail, has never been -@c documented as a cvs admin option. - -@item -N@var{name}[:[@var{rev}]] -Act like @samp{-n}, except override any previous -assignment of @var{name}. For use with magic branches, -see @ref{Magic branch numbers}. - -@item -n@var{name}[:[@var{rev}]] -Associate the symbolic name @var{name} with the branch -or revision @var{rev}. It is normally better to use -@samp{cvs tag} or @samp{cvs rtag} instead. Delete the -symbolic name if both @samp{:} and @var{rev} are -omitted; otherwise, print an error message if -@var{name} is already associated with another number. -If @var{rev} is symbolic, it is expanded before -association. A @var{rev} consisting of a branch number -followed by a @samp{.} stands for the current latest -revision in the branch. A @samp{:} with an empty -@var{rev} stands for the current latest revision on the -default branch, normally the trunk. For example, -@samp{cvs admin -n@var{name}:} associates @var{name} with the -current latest revision of all the RCS files; -this contrasts with @samp{cvs admin -n@var{name}:$} which -associates @var{name} with the revision numbers -extracted from keyword strings in the corresponding -working files. - -@cindex Deleting revisions -@cindex Outdating revisions -@cindex Saving space -@item -o@var{range} -Deletes (@dfn{outdates}) the revisions given by -@var{range}. - -Note that this command can be quite dangerous unless -you know @emph{exactly} what you are doing (for example -see the warnings below about how the -@var{rev1}:@var{rev2} syntax is confusing). - -If you are short on disc this option might help you. -But think twice before using it---there is no way short -of restoring the latest backup to undo this command! -If you delete different revisions than you planned, -either due to carelessness or (heaven forbid) a @sc{cvs} -bug, there is no opportunity to correct the error -before the revisions are deleted. It probably would be -a good idea to experiment on a copy of the repository -first. - -Specify @var{range} in one of the following ways: - -@table @code -@item @var{rev1}::@var{rev2} -Collapse all revisions between rev1 and rev2, so that -@sc{cvs} only stores the differences associated with going -from rev1 to rev2, not intermediate steps. For -example, after @samp{-o 1.3::1.5} one can retrieve -revision 1.3, revision 1.5, or the differences to get -from 1.3 to 1.5, but not the revision 1.4, or the -differences between 1.3 and 1.4. Other examples: -@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no -effect, because there are no intermediate revisions to -remove. - -@item ::@var{rev} -Collapse revisions between the beginning of the branch -containing @var{rev} and @var{rev} itself. The -branchpoint and @var{rev} are left intact. For -example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, -revision 1.3.2.5, and everything in between, but leaves -1.3 and 1.3.2.6 intact. - -@item @var{rev}:: -Collapse revisions between @var{rev} and the end of the -branch containing @var{rev}. Revision @var{rev} is -left intact but the head revision is deleted. - -@item @var{rev} -Delete the revision @var{rev}. For example, @samp{-o -1.3} is equivalent to @samp{-o 1.2::1.4}. - -@item @var{rev1}:@var{rev2} -Delete the revisions from @var{rev1} to @var{rev2}, -inclusive, on the same branch. One will not be able to -retrieve @var{rev1} or @var{rev2} or any of the -revisions in between. For example, the command -@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. -It means to delete revisions up to, and including, the -tag R_1_02. But beware! If there are files that have not -changed between R_1_02 and R_1_03 the file will have -@emph{the same} numerical revision number assigned to -the tags R_1_02 and R_1_03. So not only will it be -impossible to retrieve R_1_02; R_1_03 will also have to -be restored from the tapes! In most cases you want to -specify @var{rev1}::@var{rev2} instead. - -@item :@var{rev} -Delete revisions from the beginning of the -branch containing @var{rev} up to and including -@var{rev}. - -@item @var{rev}: -Delete revisions from revision @var{rev}, including -@var{rev} itself, to the end of the branch containing -@var{rev}. -@end table - -None of the revisions to be deleted may have -branches or locks. - -If any of the revisions to be deleted have symbolic -names, and one specifies one of the @samp{::} syntaxes, -then @sc{cvs} will give an error and not delete any -revisions. If you really want to delete both the -symbolic names and the revisions, first delete the -symbolic names with @code{cvs tag -d}, then run -@code{cvs admin -o}. If one specifies the -non-@samp{::} syntaxes, then @sc{cvs} will delete the -revisions but leave the symbolic names pointing to -nonexistent revisions. This behavior is preserved for -compatibility with previous versions of @sc{cvs}, but -because it isn't very useful, in the future it may -change to be like the @samp{::} case. - -Due to the way @sc{cvs} handles branches @var{rev} -cannot be specified symbolically if it is a branch. -See @ref{Magic branch numbers} for an explanation. -@c FIXME: is this still true? I suspect not. - -Make sure that no-one has checked out a copy of the -revision you outdate. Strange things will happen if he -starts to edit it and tries to check it back in. For -this reason, this option is not a good way to take back -a bogus commit; commit a new revision undoing the bogus -change instead (@pxref{Merging two revisions}). - -@item -q -Run quietly; do not print diagnostics. - -@item -s@var{state}[:@var{rev}] -Useful with @sc{cvs}. Set the state attribute of the -revision @var{rev} to @var{state}. If @var{rev} is a -branch number, assume the latest revision on that -branch. If @var{rev} is omitted, assume the latest -revision on the default branch. Any identifier is -acceptable for @var{state}. A useful set of states is -@samp{Exp} (for experimental), @samp{Stab} (for -stable), and @samp{Rel} (for released). By default, -the state of a new revision is set to @samp{Exp} when -it is created. The state is visible in the output from -@var{cvs log} (@pxref{log}), and in the -@samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords -(@pxref{Keyword substitution}). Note that @sc{cvs} -uses the @code{dead} state for its own purposes (@pxref{Attic}); to -take a file to or from the @code{dead} state use -commands like @code{cvs remove} and @code{cvs add} -(@pxref{Adding and removing}), not @code{cvs admin -s}. - -@item -t[@var{file}] -Useful with @sc{cvs}. Write descriptive text from the -contents of the named @var{file} into the RCS file, -deleting the existing text. The @var{file} pathname -may not begin with @samp{-}. The descriptive text can be seen in the -output from @samp{cvs log} (@pxref{log}). -There can be no space between @samp{-t} and its argument. - -If @var{file} is omitted, -obtain the text from standard input, terminated by -end-of-file or by a line containing @samp{.} by itself. -Prompt for the text if interaction is possible; see -@samp{-I}. - -@item -t-@var{string} -Similar to @samp{-t@var{file}}. Write descriptive text -from the @var{string} into the @sc{rcs} file, deleting -the existing text. -There can be no space between @samp{-t} and its argument. - -@c The rcs -T option, do not update last-mod time for -@c minor changes, has never been documented as a -@c cvs admin option. - -@item -U -Set locking to non-strict. Non-strict locking means -that the owner of a file need not lock a revision for -checkin. For use with @sc{cvs}, strict locking must be -set; see the discussion under the @samp{-l} option -above. - -@item -u[@var{rev}] -See the option @samp{-l} above, for a discussion of -using this option with @sc{cvs}. Unlock the revision -with number @var{rev}. If a branch is given, unlock -the latest revision on that branch. If @var{rev} is -omitted, remove the latest lock held by the caller. -Normally, only the locker of a revision may unlock it; -somebody else unlocking a revision breaks the lock. -This causes the original locker to be sent a @code{commit} -notification (@pxref{Getting Notified}). -There can be no space between @samp{-u} and its argument. - -@item -V@var{n} -In previous versions of @sc{cvs}, this option meant to -write an @sc{rcs} file which would be acceptable to -@sc{rcs} version @var{n}, but it is now obsolete and -specifying it will produce an error. -@c Note that -V without an argument has never been -@c documented as a cvs admin option. - -@item -x@var{suffixes} -In previous versions of @sc{cvs}, this was documented -as a way of specifying the names of the @sc{rcs} -files. However, @sc{cvs} has always required that the -@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so -this option has never done anything useful. - -@c The rcs -z option, to specify the timezone, has -@c never been documented as a cvs admin option. -@end table - - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node annotate -@appendixsec annotate---What revision modified each line of a file? -@cindex annotate (subcommand) - -@itemize @bullet -@item -Synopsis: annotate [options] files@dots{} -@item -Requires: repository. -@item -Synonym: blame -@item -Changes: nothing. -@end itemize - -For each file in @var{files}, print the head revision -of the trunk, together with information on the last -modification for each line. - -@menu -* annotate options:: annotate options -* annotate example:: annotate example -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node annotate options -@appendixsubsec annotate options - -These standard options are supported by @code{annotate} -(@pxref{Common options} for a complete description of -them): - -@table @code -@item -l -Local directory only, no recursion. - -@item -R -Process directories recursively. - -@item -f -Use head revision if tag/date not found. - -@item -F -Annotate binary files. - -@item -r @var{revision} -Annotate file as of specified revision/tag. - -@item -D @var{date} -Annotate file as of specified date. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node annotate example -@appendixsubsec annotate example - -For example: - -@example -$ cvs annotate ssfile -Annotations for ssfile -*************** -1.1 (mary 27-Mar-96): ssfile line 1 -1.2 (joe 28-Mar-96): ssfile line 2 -@end example - -The file @file{ssfile} currently contains two lines. -The @code{ssfile line 1} line was checked in by -@code{mary} on March 27. Then, on March 28, @code{joe} -added a line @code{ssfile line 2}, without modifying -the @code{ssfile line 1} line. This report doesn't -tell you anything about lines which have been deleted -or replaced; you need to use @code{cvs diff} for that -(@pxref{diff}). - -The options to @code{cvs annotate} are listed in -@ref{Invoking CVS}, and can be used to select the files -and revisions to annotate. The options are described -in more detail there and in @ref{Common options}. - -@c FIXME: maybe an example using the options? Just -@c what it means to select a revision might be worth a -@c few words of explanation ("you want to see who -@c changed this line *before* 1.4"...). - - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node checkout -@appendixsec checkout---Check out sources for editing -@cindex checkout (subcommand) -@cindex co (subcommand) - -@itemize @bullet -@item -Synopsis: checkout [options] modules@dots{} -@item -Requires: repository. -@item -Changes: working directory. -@item -Synonyms: co, get -@end itemize - -Create or update a working directory containing copies of the -source files specified by @var{modules}. You must execute -@code{checkout} before using most of the other @sc{cvs} -commands, since most of them operate on your working -directory. - -The @var{modules} are either -symbolic names for some -collection of source directories and files, or paths to -directories or files in the repository. The symbolic -names are defined in the @samp{modules} file. -See @ref{modules}. -@c Needs an example, particularly of the non-"modules" -@c case but probably of both. - -@c FIXME: this seems like a very odd place to introduce -@c people to how CVS works. The bit about unreserved -@c checkouts is also misleading as it depends on how -@c things are set up. -Depending on the modules you specify, @code{checkout} may -recursively create directories and populate them with -the appropriate source files. You can then edit these -source files at any time (regardless of whether other -software developers are editing their own copies of the -sources); update them to include new changes applied by -others to the source repository; or commit your work as -a permanent change to the source repository. - -Note that @code{checkout} is used to create -directories. The top-level directory created is always -added to the directory where @code{checkout} is -invoked, and usually has the same name as the specified -module. In the case of a module alias, the created -sub-directory may have a different name, but you can be -sure that it will be a sub-directory, and that -@code{checkout} will show the relative path leading to -each file as it is extracted into your private work -area (unless you specify the @samp{-Q} global option). - -The files created by @code{checkout} are created -read-write, unless the @samp{-r} option to @sc{cvs} -(@pxref{Global options}) is specified, the -@code{CVSREAD} environment variable is specified -(@pxref{Environment variables}), or a watch is in -effect for that file (@pxref{Watches}). - -Note that running @code{checkout} on a directory that was already -built by a prior @code{checkout} is also permitted. -This is similar to specifying the @samp{-d} option -to the @code{update} command in the sense that new -directories that have been created in the repository -will appear in your work area. -However, @code{checkout} takes a module name whereas -@code{update} takes a directory name. Also -to use @code{checkout} this way it must be run from the -top level directory (where you originally ran -@code{checkout} from), so before you run -@code{checkout} to update an existing directory, don't -forget to change your directory to the top level -directory. - -For the output produced by the @code{checkout} command, -@xref{update output}. - -@menu -* checkout options:: checkout options -* checkout examples:: checkout examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node checkout options -@appendixsubsec checkout options - -These standard options are supported by @code{checkout} -(@pxref{Common options} for a complete description of -them): - -@table @code -@item -D @var{date} -Use the most recent revision no later than @var{date}. -This option is sticky, and implies @samp{-P}. See -@ref{Sticky tags} for more information on sticky tags/dates. - -@item -f -Only useful with the @samp{-D @var{date}} or @samp{-r -@var{tag}} flags. If no matching revision is found, -retrieve the most recent revision (instead of ignoring -the file). - -@item -k @var{kflag} -Process keywords according to @var{kflag}. See -@ref{Keyword substitution}. -This option is sticky; future updates of -this file in this working directory will use the same -@var{kflag}. The @code{status} command can be viewed -to see the sticky options. See @ref{Invoking CVS} for -more information on the @code{status} command. - -@item -l -Local; run only in current working directory. - -@item -n -Do not run any checkout program (as specified -with the @samp{-o} option in the modules file; -@pxref{modules}). - -@item -P -Prune empty directories. See @ref{Moving directories}. - -@item -p -Pipe files to the standard output. - -@item -R -Checkout directories recursively. This option is on by default. - -@item -r @var{tag} -Use revision @var{tag}. This option is sticky, and implies @samp{-P}. -See @ref{Sticky tags}, for more information on sticky tags/dates. -@end table - -In addition to those, you can use these special command -options with @code{checkout}: - -@table @code -@item -A -Reset any sticky tags, dates, or @samp{-k} options. -Does not reset sticky @samp{-k} options on modified files. -See @ref{Sticky tags} for more information on sticky tags/dates. - -@item -c -Copy the module file, sorted, to the standard output, -instead of creating or modifying any files or -directories in your working directory. - -@item -d @var{dir} -Create a directory called @var{dir} for the working -files, instead of using the module name. In general, -using this flag is equivalent to using @samp{mkdir -@var{dir}; cd @var{dir}} followed by the checkout -command without the @samp{-d} flag. - -There is an important exception, however. It is very -convenient when checking out a single item to have the -output appear in a directory that doesn't contain empty -intermediate directories. In this case @emph{only}, -@sc{cvs} tries to ``shorten'' pathnames to avoid those empty -directories. - -For example, given a module @samp{foo} that contains -the file @samp{bar.c}, the command @samp{cvs co -d dir -foo} will create directory @samp{dir} and place -@samp{bar.c} inside. Similarly, given a module -@samp{bar} which has subdirectory @samp{baz} wherein -there is a file @samp{quux.c}, the command @samp{cvs co --d dir bar/baz} will create directory @samp{dir} and -place @samp{quux.c} inside. - -Using the @samp{-N} flag will defeat this behavior. -Given the same module definitions above, @samp{cvs co --N -d dir foo} will create directories @samp{dir/foo} -and place @samp{bar.c} inside, while @samp{cvs co -N -d -dir bar/baz} will create directories @samp{dir/bar/baz} -and place @samp{quux.c} inside. - -@item -j @var{tag} -With two @samp{-j} options, merge changes from the -revision specified with the first @samp{-j} option to -the revision specified with the second @samp{j} option, -into the working directory. - -With one @samp{-j} option, merge changes from the -ancestor revision to the revision specified with the -@samp{-j} option, into the working directory. The -ancestor revision is the common ancestor of the -revision which the working directory is based on, and -the revision specified in the @samp{-j} option. - -In addition, each -j option can contain an optional -date specification which, when used with branches, can -limit the chosen revision to one within a specific -date. An optional date is specified by adding a colon -(:) to the tag: -@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. - -See @ref{Branching and merging}. - -@item -N -Only useful together with @samp{-d @var{dir}}. With -this option, @sc{cvs} will not ``shorten'' module paths -in your working directory when you check out a single -module. See the @samp{-d} flag for examples and a -discussion. - -@item -s -Like @samp{-c}, but include the status of all modules, -and sort it by the status string. See @ref{modules}, for -info about the @samp{-s} option that is used inside the -modules file to set the module status. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node checkout examples -@appendixsubsec checkout examples - -Get a copy of the module @samp{tc}: - -@example -$ cvs checkout tc -@end example - -Get a copy of the module @samp{tc} as it looked one day -ago: - -@example -$ cvs checkout -D yesterday tc -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node commit -@appendixsec commit---Check files into the repository -@cindex commit (subcommand) - -@itemize @bullet -@item -Synopsis: commit [-lRf] [-m 'log_message' | --F file] [-r revision] [files@dots{}] -@item -Requires: working directory, repository. -@item -Changes: repository. -@item -Synonym: ci -@end itemize - -Use @code{commit} when you want to incorporate changes -from your working source files into the source -repository. - -If you don't specify particular files to commit, all of -the files in your working current directory are -examined. @code{commit} is careful to change in the -repository only those files that you have really -changed. By default (or if you explicitly specify the -@samp{-R} option), files in subdirectories are also -examined and committed if they have changed; you can -use the @samp{-l} option to limit @code{commit} to the -current directory only. - -@code{commit} verifies that the selected files are up -to date with the current revisions in the source -repository; it will notify you, and exit without -committing, if any of the specified files must be made -current first with @code{update} (@pxref{update}). -@code{commit} does not call the @code{update} command -for you, but rather leaves that for you to do when the -time is right. - -When all is well, an editor is invoked to allow you to -enter a log message that will be written to one or more -logging programs (@pxref{modules}, and @pxref{loginfo}) -and placed in the @sc{rcs} file inside the -repository. This log message can be retrieved with the -@code{log} command; @xref{log}. You can specify the -log message on the command line with the @samp{-m -@var{message}} option, and thus avoid the editor invocation, -or use the @samp{-F @var{file}} option to specify -that the argument file contains the log message. - -@menu -* commit options:: commit options -* commit examples:: commit examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node commit options -@appendixsubsec commit options - -These standard options are supported by @code{commit} -(@pxref{Common options} for a complete description of -them): - -@table @code -@item -l -Local; run only in current working directory. - -@item -R -Commit directories recursively. This is on by default. - -@item -r @var{revision} -Commit to @var{revision}. @var{revision} must be -either a branch, or a revision on the main trunk that -is higher than any existing revision number -(@pxref{Assigning revisions}). You -cannot commit to a specific revision on a branch. -@c FIXME: Need xref for branch case. -@end table - -@code{commit} also supports these options: - -@table @code -@item -F @var{file} -Read the log message from @var{file}, instead -of invoking an editor. - -@item -f -Note that this is not the standard behavior of -the @samp{-f} option as defined in @ref{Common options}. - -Force @sc{cvs} to commit a new revision even if you haven't -made any changes to the file. If the current revision -of @var{file} is 1.7, then the following two commands -are equivalent: - -@example -$ cvs commit -f @var{file} -$ cvs commit -r 1.8 @var{file} -@end example - -@c This is odd, but it's how CVS has worked for some -@c time. -The @samp{-f} option disables recursion (i.e., it -implies @samp{-l}). To force @sc{cvs} to commit a new -revision for all files in all subdirectories, you must -use @samp{-f -R}. - -@item -m @var{message} -Use @var{message} as the log message, instead of -invoking an editor. -@end table - -@need 2000 -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node commit examples -@appendixsubsec commit examples - -@c FIXME: this material wants to be somewhere -@c in "Branching and merging". - -@appendixsubsubsec Committing to a branch - -You can commit to a branch revision (one that has an -even number of dots) with the @samp{-r} option. To -create a branch revision, use the @samp{-b} option -of the @code{rtag} or @code{tag} commands -(@pxref{Branching and merging}). Then, either @code{checkout} or -@code{update} can be used to base your sources on the -newly created branch. From that point on, all -@code{commit} changes made within these working sources -will be automatically added to a branch revision, -thereby not disturbing main-line development in any -way. For example, if you had to create a patch to the -1.2 version of the product, even though the 2.0 version -is already under development, you might do: - -@example -$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module -$ cvs checkout -r FCS1_2_Patch product_module -$ cd product_module -[[ hack away ]] -$ cvs commit -@end example - -@noindent -This works automatically since the @samp{-r} option is -sticky. - -@appendixsubsubsec Creating the branch after editing - -Say you have been working on some extremely -experimental software, based on whatever revision you -happened to checkout last week. If others in your -group would like to work on this software with you, but -without disturbing main-line development, you could -commit your change to a new branch. Others can then -checkout your experimental stuff and utilize the full -benefit of @sc{cvs} conflict resolution. The scenario might -look like: - -@c FIXME: Should we be recommending tagging the branchpoint? -@example -[[ hacked sources are present ]] -$ cvs tag -b EXPR1 -$ cvs update -r EXPR1 -$ cvs commit -@end example - -The @code{update} command will make the @samp{-r -EXPR1} option sticky on all files. Note that your -changes to the files will never be removed by the -@code{update} command. The @code{commit} will -automatically commit to the correct branch, because the -@samp{-r} is sticky. You could also do like this: - -@c FIXME: Should we be recommending tagging the branchpoint? -@example -[[ hacked sources are present ]] -$ cvs tag -b EXPR1 -$ cvs commit -r EXPR1 -@end example - -@noindent -but then, only those files that were changed by you -will have the @samp{-r EXPR1} sticky flag. If you hack -away, and commit without specifying the @samp{-r EXPR1} -flag, some files may accidentally end up on the main -trunk. - -To work with you on the experimental change, others -would simply do - -@example -$ cvs checkout -r EXPR1 whatever_module -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node diff -@appendixsec diff---Show differences between revisions -@cindex diff (subcommand) - -@itemize @bullet -@item -Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}] -@item -Requires: working directory, repository. -@item -Changes: nothing. -@end itemize - -The @code{diff} command is used to compare different -revisions of files. The default action is to compare -your working files with the revisions they were based -on, and report any differences that are found. - -If any file names are given, only those files are -compared. If any directories are given, all files -under them will be compared. - -The exit status for diff is different than for other -@sc{cvs} commands; for details @xref{Exit status}. - -@menu -* diff options:: diff options -* diff examples:: diff examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node diff options -@appendixsubsec diff options - -These standard options are supported by @code{diff} -(@pxref{Common options} for a complete description of -them): - -@table @code -@item -D @var{date} -Use the most recent revision no later than @var{date}. -See @samp{-r} for how this affects the comparison. - -@item -k @var{kflag} -Process keywords according to @var{kflag}. See -@ref{Keyword substitution}. - -@item -l -Local; run only in current working directory. - -@item -R -Examine directories recursively. This option is on by -default. - -@item -r @var{tag} -Compare with revision @var{tag}. Zero, one or two -@samp{-r} options can be present. With no @samp{-r} -option, the working file will be compared with the -revision it was based on. With one @samp{-r}, that -revision will be compared to your current working file. -With two @samp{-r} options those two revisions will be -compared (and your working file will not affect the -outcome in any way). -@c We should be a lot more explicit, with examples, -@c about the difference between "cvs diff" and "cvs -@c diff -r HEAD". This often confuses new users. - -One or both @samp{-r} options can be replaced by a -@samp{-D @var{date}} option, described above. -@end table - -@c Conceptually, this is a disaster. There are 3 -@c zillion diff formats that we support via the diff -@c library. It is not obvious to me that we should -@c document them all. Maybe just the most common ones -@c like -c and -u, and think about phasing out the -@c obscure ones. -@c FIXCVS: also should be a way to specify an external -@c diff program (which can be different for different -@c file types) and pass through -@c arbitrary options, so that the user can do -@c "--pass=-Z --pass=foo" or something even if CVS -@c doesn't know about the "-Z foo" option to diff. -@c This would fit nicely with deprecating/eliminating -@c the obscure options of the diff library, because it -@c would let people specify an external GNU diff if -@c they are into that sort of thing. -The following options specify the format of the -output. They have the same meaning as in GNU diff. -Most options have two equivalent names, one of which is a single letter -preceded by @samp{-}, and the other of which is a long name preceded by -@samp{--}. - -@table @samp -@item -@var{lines} -Show @var{lines} (an integer) lines of context. This option does not -specify an output format by itself; it has no effect unless it is -combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper -operation, @code{patch} typically needs at least two lines of context. - -@item -a -Treat all files as text and compare them line-by-line, even if they -do not seem to be text. - -@item -b -Ignore trailing white space and consider all other sequences of one or -more white space characters to be equivalent. - -@item -B -Ignore changes that just insert or delete blank lines. - -@item --binary -Read and write data in binary mode. - -@item --brief -Report only whether the files differ, not the details of the -differences. - -@item -c -Use the context output format. - -@item -C @var{lines} -@itemx --context@r{[}=@var{lines}@r{]} -Use the context output format, showing @var{lines} (an integer) lines of -context, or three if @var{lines} is not given. -For proper operation, @code{patch} typically needs at least two lines of -context. - -@item --changed-group-format=@var{format} -Use @var{format} to output a line group containing differing lines from -both files in if-then-else format. See @ref{Line group formats}. - -@item -d -Change the algorithm to perhaps find a smaller set of changes. This makes -@code{diff} slower (sometimes much slower). - -@item -e -@itemx --ed -Make output that is a valid @code{ed} script. - -@item --expand-tabs -Expand tabs to spaces in the output, to preserve the alignment of tabs -in the input files. - -@item -f -Make output that looks vaguely like an @code{ed} script but has changes -in the order they appear in the file. - -@item -F @var{regexp} -In context and unified format, for each hunk of differences, show some -of the last preceding line that matches @var{regexp}. - -@item --forward-ed -Make output that looks vaguely like an @code{ed} script but has changes -in the order they appear in the file. - -@item -H -Use heuristics to speed handling of large files that have numerous -scattered small changes. - -@item --horizon-lines=@var{lines} -Do not discard the last @var{lines} lines of the common prefix -and the first @var{lines} lines of the common suffix. - -@item -i -Ignore changes in case; consider upper- and lower-case letters -equivalent. - -@item -I @var{regexp} -Ignore changes that just insert or delete lines that match @var{regexp}. - -@item --ifdef=@var{name} -Make merged if-then-else output using @var{name}. - -@item --ignore-all-space -Ignore white space when comparing lines. - -@item --ignore-blank-lines -Ignore changes that just insert or delete blank lines. - -@item --ignore-case -Ignore changes in case; consider upper- and lower-case to be the same. - -@item --ignore-matching-lines=@var{regexp} -Ignore changes that just insert or delete lines that match @var{regexp}. - -@item --ignore-space-change -Ignore trailing white space and consider all other sequences of one or -more white space characters to be equivalent. - -@item --initial-tab -Output a tab rather than a space before the text of a line in normal or -context format. This causes the alignment of tabs in the line to look -normal. - -@item -L @var{label} -Use @var{label} instead of the file name in the context format -and unified format headers. - -@item --label=@var{label} -Use @var{label} instead of the file name in the context format -and unified format headers. - -@item --left-column -Print only the left column of two common lines in side by side format. - -@item --line-format=@var{format} -Use @var{format} to output all input lines in if-then-else format. -See @ref{Line formats}. - -@item --minimal -Change the algorithm to perhaps find a smaller set of changes. This -makes @code{diff} slower (sometimes much slower). - -@item -n -Output RCS-format diffs; like @samp{-f} except that each command -specifies the number of lines affected. - -@item -N -@itemx --new-file -In directory comparison, if a file is found in only one directory, -treat it as present but empty in the other directory. - -@item --new-group-format=@var{format} -Use @var{format} to output a group of lines taken from just the second -file in if-then-else format. See @ref{Line group formats}. - -@item --new-line-format=@var{format} -Use @var{format} to output a line taken from just the second file in -if-then-else format. See @ref{Line formats}. - -@item --old-group-format=@var{format} -Use @var{format} to output a group of lines taken from just the first -file in if-then-else format. See @ref{Line group formats}. - -@item --old-line-format=@var{format} -Use @var{format} to output a line taken from just the first file in -if-then-else format. See @ref{Line formats}. - -@item -p -Show which C function each change is in. - -@item --rcs -Output RCS-format diffs; like @samp{-f} except that each command -specifies the number of lines affected. - -@item --report-identical-files -@itemx -s -Report when two files are the same. - -@item --show-c-function -Show which C function each change is in. - -@item --show-function-line=@var{regexp} -In context and unified format, for each hunk of differences, show some -of the last preceding line that matches @var{regexp}. - -@item --side-by-side -Use the side by side output format. - -@item --speed-large-files -Use heuristics to speed handling of large files that have numerous -scattered small changes. - -@item --suppress-common-lines -Do not print common lines in side by side format. - -@item -t -Expand tabs to spaces in the output, to preserve the alignment of tabs -in the input files. - -@item -T -Output a tab rather than a space before the text of a line in normal or -context format. This causes the alignment of tabs in the line to look -normal. - -@item --text -Treat all files as text and compare them line-by-line, even if they -do not appear to be text. - -@item -u -Use the unified output format. - -@item --unchanged-group-format=@var{format} -Use @var{format} to output a group of common lines taken from both files -in if-then-else format. @xref{Line group formats}. - -@item --unchanged-line-format=@var{format} -Use @var{format} to output a line common to both files in if-then-else -format. @xref{Line formats}. - -@item -U @var{lines} -@itemx --unified@r{[}=@var{lines}@r{]} -Use the unified output format, showing @var{lines} (an integer) lines of -context, or three if @var{lines} is not given. -For proper operation, @code{patch} typically needs at least two lines of -context. - -@item -w -Ignore white space when comparing lines. - -@item -W @var{columns} -@itemx --width=@var{columns} -Use an output width of @var{columns} in side by side format. - -@item -y -Use the side by side output format. -@end table - -@menu -* Line group formats:: Line group formats -* Line formats:: Line formats -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node Line group formats -@appendixsubsubsec Line group formats - -Line group formats let you specify formats suitable for many -applications that allow if-then-else input, including programming -languages and text formatting languages. A line group format specifies -the output format for a contiguous group of similar lines. - -For example, the following command compares the TeX file @file{myfile} -with the original version from the repository, -and outputs a merged file in which old regions are -surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new -regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. - -@example -cvs diff \ - --old-group-format='\begin@{em@} -%<\end@{em@} -' \ - --new-group-format='\begin@{bf@} -%>\end@{bf@} -' \ - myfile -@end example - -The following command is equivalent to the above example, but it is a -little more verbose, because it spells out the default line group formats. - -@example -cvs diff \ - --old-group-format='\begin@{em@} -%<\end@{em@} -' \ - --new-group-format='\begin@{bf@} -%>\end@{bf@} -' \ - --unchanged-group-format='%=' \ - --changed-group-format='\begin@{em@} -%<\end@{em@} -\begin@{bf@} -%>\end@{bf@} -' \ - myfile -@end example - -Here is a more advanced example, which outputs a diff listing with -headers containing line numbers in a ``plain English'' style. - -@example -cvs diff \ - --unchanged-group-format='' \ - --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: -%<' \ - --new-group-format='-------- %dN line%(N=1?:s) added after %de: -%>' \ - --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: -%<-------- to: -%>' \ - myfile -@end example - -To specify a line group format, use one of the options -listed below. You can specify up to four line group formats, one for -each kind of line group. You should quote @var{format}, because it -typically contains shell metacharacters. - -@table @samp -@item --old-group-format=@var{format} -These line groups are hunks containing only lines from the first file. -The default old group format is the same as the changed group format if -it is specified; otherwise it is a format that outputs the line group as-is. - -@item --new-group-format=@var{format} -These line groups are hunks containing only lines from the second -file. The default new group format is same as the changed group -format if it is specified; otherwise it is a format that outputs the -line group as-is. - -@item --changed-group-format=@var{format} -These line groups are hunks containing lines from both files. The -default changed group format is the concatenation of the old and new -group formats. - -@item --unchanged-group-format=@var{format} -These line groups contain lines common to both files. The default -unchanged group format is a format that outputs the line group as-is. -@end table - -In a line group format, ordinary characters represent themselves; -conversion specifications start with @samp{%} and have one of the -following forms. - -@table @samp -@item %< -stands for the lines from the first file, including the trailing newline. -Each line is formatted according to the old line format (@pxref{Line formats}). - -@item %> -stands for the lines from the second file, including the trailing newline. -Each line is formatted according to the new line format. - -@item %= -stands for the lines common to both files, including the trailing newline. -Each line is formatted according to the unchanged line format. - -@item %% -stands for @samp{%}. - -@item %c'@var{C}' -where @var{C} is a single character, stands for @var{C}. -@var{C} may not be a backslash or an apostrophe. -For example, @samp{%c':'} stands for a colon, even inside -the then-part of an if-then-else format, which a colon would -normally terminate. - -@item %c'\@var{O}' -where @var{O} is a string of 1, 2, or 3 octal digits, -stands for the character with octal code @var{O}. -For example, @samp{%c'\0'} stands for a null character. - -@item @var{F}@var{n} -where @var{F} is a @code{printf} conversion specification and @var{n} is one -of the following letters, stands for @var{n}'s value formatted with @var{F}. - -@table @samp -@item e -The line number of the line just before the group in the old file. - -@item f -The line number of the first line in the group in the old file; -equals @var{e} + 1. - -@item l -The line number of the last line in the group in the old file. - -@item m -The line number of the line just after the group in the old file; -equals @var{l} + 1. - -@item n -The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. - -@item E, F, L, M, N -Likewise, for lines in the new file. - -@end table - -The @code{printf} conversion specification can be @samp{%d}, -@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, -lower case hexadecimal, or upper case hexadecimal output -respectively. After the @samp{%} the following options can appear in -sequence: a @samp{-} specifying left-justification; an integer -specifying the minimum field width; and a period followed by an -optional integer specifying the minimum number of digits. -For example, @samp{%5dN} prints the number of new lines in the group -in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. - -@item (@var{A}=@var{B}?@var{T}:@var{E}) -If @var{A} equals @var{B} then @var{T} else @var{E}. -@var{A} and @var{B} are each either a decimal constant -or a single letter interpreted as above. -This format spec is equivalent to @var{T} if -@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. - -For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to -@samp{no lines} if @var{N} (the number of lines in the group in the -new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} -otherwise. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node Line formats -@appendixsubsubsec Line formats - -Line formats control how each line taken from an input file is -output as part of a line group in if-then-else format. - -For example, the following command outputs text with a one-column -change indicator to the left of the text. The first column of output -is @samp{-} for deleted lines, @samp{|} for added lines, and a space -for unchanged lines. The formats contain newline characters where -newlines are desired on output. - -@example -cvs diff \ - --old-line-format='-%l -' \ - --new-line-format='|%l -' \ - --unchanged-line-format=' %l -' \ - myfile -@end example - -To specify a line format, use one of the following options. You should -quote @var{format}, since it often contains shell metacharacters. - -@table @samp -@item --old-line-format=@var{format} -formats lines just from the first file. - -@item --new-line-format=@var{format} -formats lines just from the second file. - -@item --unchanged-line-format=@var{format} -formats lines common to both files. - -@item --line-format=@var{format} -formats all lines; in effect, it sets all three above options simultaneously. -@end table - -In a line format, ordinary characters represent themselves; -conversion specifications start with @samp{%} and have one of the -following forms. - -@table @samp -@item %l -stands for the contents of the line, not counting its trailing -newline (if any). This format ignores whether the line is incomplete. - -@item %L -stands for the contents of the line, including its trailing newline -(if any). If a line is incomplete, this format preserves its -incompleteness. - -@item %% -stands for @samp{%}. - -@item %c'@var{C}' -where @var{C} is a single character, stands for @var{C}. -@var{C} may not be a backslash or an apostrophe. -For example, @samp{%c':'} stands for a colon. - -@item %c'\@var{O}' -where @var{O} is a string of 1, 2, or 3 octal digits, -stands for the character with octal code @var{O}. -For example, @samp{%c'\0'} stands for a null character. - -@item @var{F}n -where @var{F} is a @code{printf} conversion specification, -stands for the line number formatted with @var{F}. -For example, @samp{%.5dn} prints the line number using the -@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for -more about printf conversion specifications. - -@end table - -The default line format is @samp{%l} followed by a newline character. - -If the input contains tab characters and it is important that they line -up on output, you should ensure that @samp{%l} or @samp{%L} in a line -format is just after a tab stop (e.g.@: by preceding @samp{%l} or -@samp{%L} with a tab character), or you should use the @samp{-t} or -@samp{--expand-tabs} option. - -Taken together, the line and line group formats let you specify many -different formats. For example, the following command uses a format -similar to @code{diff}'s normal format. You can tailor this command -to get fine control over @code{diff}'s output. - -@example -cvs diff \ - --old-line-format='< %l -' \ - --new-line-format='> %l -' \ - --old-group-format='%df%(f=l?:,%dl)d%dE -%<' \ - --new-group-format='%dea%dF%(F=L?:,%dL) -%>' \ - --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) -%<--- -%>' \ - --unchanged-group-format='' \ - myfile -@end example - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node diff examples -@appendixsubsec diff examples - -The following line produces a Unidiff (@samp{-u} flag) -between revision 1.14 and 1.19 of -@file{backend.c}. Due to the @samp{-kk} flag no -keywords are substituted, so differences that only depend -on keyword substitution are ignored. - -@example -$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c -@end example - -Suppose the experimental branch EXPR1 was based on a -set of files tagged RELEASE_1_0. To see what has -happened on that branch, the following can be used: - -@example -$ cvs diff -r RELEASE_1_0 -r EXPR1 -@end example - -A command like this can be used to produce a context -diff between two releases: - -@example -$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs -@end example - -If you are maintaining ChangeLogs, a command like the following -just before you commit your changes may help you write -the ChangeLog entry. All local modifications that have -not yet been committed will be printed. - -@example -$ cvs diff -u | less -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node export -@appendixsec export---Export sources from CVS, similar to checkout -@cindex export (subcommand) - -@itemize @bullet -@item -Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{} -@item -Requires: repository. -@item -Changes: current directory. -@end itemize - -This command is a variant of @code{checkout}; use it -when you want a copy of the source for module without -the @sc{cvs} administrative directories. For example, you -might use @code{export} to prepare source for shipment -off-site. This command requires that you specify a -date or tag (with @samp{-D} or @samp{-r}), so that you -can count on reproducing the source you ship to others -(and thus it always prunes empty directories). - -One often would like to use @samp{-kv} with @code{cvs -export}. This causes any keywords to be -expanded such that an import done at some other site -will not lose the keyword revision information. But be -aware that doesn't handle an export containing binary -files correctly. Also be aware that after having used -@samp{-kv}, one can no longer use the @code{ident} -command (which is part of the @sc{rcs} suite---see -ident(1)) which looks for keyword strings. If -you want to be able to use @code{ident} you must not -use @samp{-kv}. - -@menu -* export options:: export options -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node export options -@appendixsubsec export options - -These standard options are supported by @code{export} -(@pxref{Common options}, for a complete description of -them): - -@table @code -@item -D @var{date} -Use the most recent revision no later than @var{date}. - -@item -f -If no matching revision is found, retrieve the most -recent revision (instead of ignoring the file). - -@item -l -Local; run only in current working directory. - -@item -n -Do not run any checkout program. - -@item -R -Export directories recursively. This is on by default. - -@item -r @var{tag} -Use revision @var{tag}. -@end table - -In addition, these options (that are common to -@code{checkout} and @code{export}) are also supported: - -@table @code -@item -d @var{dir} -Create a directory called @var{dir} for the working -files, instead of using the module name. -See @ref{checkout options} for complete details on how -@sc{cvs} handles this flag. - -@item -k @var{subst} -Set keyword expansion mode (@pxref{Substitution modes}). - -@item -N -Only useful together with @samp{-d @var{dir}}. -See @ref{checkout options} for complete details on how -@sc{cvs} handles this flag. -@end table - -@ignore -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@c @node export examples -@appendixsubsec export examples - -Contributed examples are gratefully accepted. -@c -- Examples here!! -@end ignore - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node history -@appendixsec history---Show status of files and users -@cindex history (subcommand) - -@itemize @bullet -@item -Synopsis: history [-report] [-flags] [-options args] [files@dots{}] -@item -Requires: the file @file{$CVSROOT/CVSROOT/history} -@item -Changes: nothing. -@end itemize - -@sc{cvs} can keep a history file that tracks each use of the -@code{checkout}, @code{commit}, @code{rtag}, -@code{update}, and @code{release} commands. You can -use @code{history} to display this information in -various formats. - -Logging must be enabled by creating the file -@file{$CVSROOT/CVSROOT/history}. - -@strong{@code{history} uses @samp{-f}, @samp{-l}, -@samp{-n}, and @samp{-p} in ways that conflict with the -normal use inside @sc{cvs} (@pxref{Common options}).} - -@menu -* history options:: history options -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node history options -@appendixsubsec history options - -Several options (shown above as @samp{-report}) control what -kind of report is generated: - -@table @code -@item -c -Report on each time commit was used (i.e., each time -the repository was modified). - -@item -e -Everything (all record types). Equivalent to -specifying @samp{-x} with all record types. Of course, -@samp{-e} will also include record types which are -added in a future version of @sc{cvs}; if you are -writing a script which can only handle certain record -types, you'll want to specify @samp{-x}. - -@item -m @var{module} -Report on a particular module. (You can meaningfully -use @samp{-m} more than once on the command line.) - -@item -o -Report on checked-out modules. This is the default report type. - -@item -T -Report on all tags. - -@item -x @var{type} -Extract a particular set of record types @var{type} from the @sc{cvs} -history. The types are indicated by single letters, -which you may specify in combination. - -Certain commands have a single record type: - -@table @code -@item F -release -@item O -checkout -@item E -export -@item T -rtag -@end table - -@noindent -One of five record types may result from an update: - -@table @code -@item C -A merge was necessary but collisions were -detected (requiring manual merging). -@item G -A merge was necessary and it succeeded. -@item U -A working file was copied from the repository. -@item P -A working file was patched to match the repository. -@item W -The working copy of a file was deleted during -update (because it was gone from the repository). -@end table - -@noindent -One of three record types results from commit: - -@table @code -@item A -A file was added for the first time. -@item M -A file was modified. -@item R -A file was removed. -@end table -@end table - -The options shown as @samp{-flags} constrain or expand -the report without requiring option arguments: - -@table @code -@item -a -Show data for all users (the default is to show data -only for the user executing @code{history}). - -@item -l -Show last modification only. - -@item -w -Show only the records for modifications done from the -same working directory where @code{history} is -executing. -@end table - -The options shown as @samp{-options @var{args}} constrain the report -based on an argument: - -@table @code -@item -b @var{str} -Show data back to a record containing the string -@var{str} in either the module name, the file name, or -the repository path. - -@item -D @var{date} -Show data since @var{date}. This is slightly different -from the normal use of @samp{-D @var{date}}, which -selects the newest revision older than @var{date}. - -@item -f @var{file} -Show data for a particular file -(you can specify several @samp{-f} options on the same command line). -This is equivalent to specifying the file on the command line. - -@item -n @var{module} -Show data for a particular module -(you can specify several @samp{-n} options on the same command line). - -@item -p @var{repository} -Show data for a particular source repository (you -can specify several @samp{-p} options on the same command -line). - -@item -r @var{rev} -Show records referring to revisions since the revision -or tag named @var{rev} appears in individual @sc{rcs} -files. Each @sc{rcs} file is searched for the revision or -tag. - -@item -t @var{tag} -Show records since tag @var{tag} was last added to the -history file. This differs from the @samp{-r} flag -above in that it reads only the history file, not the -@sc{rcs} files, and is much faster. - -@item -u @var{name} -Show records for user @var{name}. - -@item -z @var{timezone} -Show times in the selected records using the specified -time zone instead of UTC. -@end table - -@ignore -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@c @node history examples -@appendixsubsec history examples - -Contributed examples will gratefully be accepted. -@c -- Examples here! -@end ignore - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node import -@appendixsec import---Import sources into CVS, using vendor branches -@cindex import (subcommand) - -@c FIXME: This node is way too long for one which has subnodes. - -@itemize @bullet -@item -Synopsis: import [-options] repository vendortag releasetag@dots{} -@item -Requires: Repository, source distribution directory. -@item -Changes: repository. -@end itemize - -Use @code{import} to incorporate an entire source -distribution from an outside source (e.g., a source -vendor) into your source repository directory. You can -use this command both for initial creation of a -repository, and for wholesale updates to the module -from the outside source. See @ref{Tracking sources} for -a discussion on this subject. - -The @var{repository} argument gives a directory name -(or a path to a directory) under the @sc{cvs} root directory -for repositories; if the directory did not exist, -import creates it. - -When you use import for updates to source that has been -modified in your source repository (since a prior -import), it will notify you of any files that conflict -in the two branches of development; use @samp{checkout --j} to reconcile the differences, as import instructs -you to do. - -If @sc{cvs} decides a file should be ignored -(@pxref{cvsignore}), it does not import it and prints -@samp{I } followed by the filename (@pxref{import output} for a -complete description of the output). - -If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, -any file whose names match the specifications in that -file will be treated as packages and the appropriate -filtering will be performed on the file/directory -before being imported. See @ref{Wrappers}. - -The outside source is saved in a first-level -branch, by default 1.1.1. Updates are leaves of this -branch; for example, files from the first imported -collection of source will be revision 1.1.1.1, then -files from the first imported update will be revision -1.1.1.2, and so on. - -At least three arguments are required. -@var{repository} is needed to identify the collection -of source. @var{vendortag} is a tag for the entire -branch (e.g., for 1.1.1). You must also specify at -least one @var{releasetag} to uniquely identify the files at -the leaves created each time you execute @code{import}. The -@var{releasetag} should be new, not previously existing in the -repository file, and uniquely identify the imported release, - -@c I'm not completely sure this belongs here. But -@c we need to say it _somewhere_ reasonably obvious; it -@c is a common misconception among people first learning CVS -Note that @code{import} does @emph{not} change the -directory in which you invoke it. In particular, it -does not set up that directory as a @sc{cvs} working -directory; if you want to work with the sources import -them first and then check them out into a different -directory (@pxref{Getting the source}). - -@menu -* import options:: import options -* import output:: import output -* import examples:: import examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node import options -@appendixsubsec import options - -This standard option is supported by @code{import} -(@pxref{Common options} for a complete description): - -@table @code -@item -m @var{message} -Use @var{message} as log information, instead of -invoking an editor. -@end table - -There are the following additional special options. - -@table @code -@item -b @var{branch} -See @ref{Multiple vendor branches}. - -@item -k @var{subst} -Indicate the keyword expansion mode desired. This -setting will apply to all files created during the -import, but not to any files that previously existed in -the repository. See @ref{Substitution modes} for a -list of valid @samp{-k} settings. - -@item -I @var{name} -Specify file names that should be ignored during -import. You can use this option repeatedly. To avoid -ignoring any files at all (even those ignored by -default), specify `-I !'. - -@var{name} can be a file name pattern of the same type -that you can specify in the @file{.cvsignore} file. -See @ref{cvsignore}. -@c -- Is this really true? - -@item -W @var{spec} -Specify file names that should be filtered during -import. You can use this option repeatedly. - -@var{spec} can be a file name pattern of the same type -that you can specify in the @file{.cvswrappers} -file. @xref{Wrappers}. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node import output -@appendixsubsec import output - -@code{import} keeps you informed of its progress by printing a line -for each file, preceded by one character indicating the status of the file: - -@table @code -@item U @var{file} -The file already exists in the repository and has not been locally -modified; a new revision has been created (if necessary). - -@item N @var{file} -The file is a new file which has been added to the repository. - -@item C @var{file} -The file already exists in the repository but has been locally modified; -you will have to merge the changes. - -@item I @var{file} -The file is being ignored (@pxref{cvsignore}). - -@cindex Symbolic link, importing -@cindex Link, symbolic, importing -@c FIXME: also (somewhere else) probably -@c should be documenting what happens if you "cvs add" -@c a symbolic link. Also maybe what happens if -@c you manually create symbolic links within the -@c repository (? - not sure why we'd want to suggest -@c doing that). -@item L @var{file} -The file is a symbolic link; @code{cvs import} ignores symbolic links. -People periodically suggest that this behavior should -be changed, but if there is a consensus on what it -should be changed to, it doesn't seem to be apparent. -(Various options in the @file{modules} file can be used -to recreate symbolic links on checkout, update, etc.; -@pxref{modules}.) -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node import examples -@appendixsubsec import examples - -See @ref{Tracking sources}, and @ref{From files}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node log -@appendixsec log---Print out log information for files -@cindex log (subcommand) - -@itemize @bullet -@item -Synopsis: log [options] [files@dots{}] -@item -Requires: repository, working directory. -@item -Changes: nothing. -@end itemize - -Display log information for files. @code{log} used to -call the @sc{rcs} utility @code{rlog}. Although this -is no longer true in the current sources, this history -determines the format of the output and the options, -which are not quite in the style of the other @sc{cvs} -commands. - -@cindex Timezone, in output -@cindex Zone, time, in output -@c Kind of a funny place to document the timezone used -@c in output from commands other than @code{log}. -@c There is also more we need to say about this, -@c including what happens in a client/server environment. -The output includes the location of the @sc{rcs} file, -the @dfn{head} revision (the latest revision on the -trunk), all symbolic names (tags) and some other -things. For each revision, the revision number, the -author, the number of lines added/deleted and the log -message are printed. All times are displayed in -Coordinated Universal Time (UTC). (Other parts of -@sc{cvs} print times in the local timezone). -@c FIXCVS: need a better way to control the timezone -@c used in output. Previous/current versions of CVS did/do -@c sometimes support -z in RCSINIT, and/or an -@c undocumented (except by reference to 'rlog') -z option -@c to cvs log, but this has not been a consistent, -@c documented feature. Perhaps a new global option, -@c where LT means the client's timezone, which the -@c client then communicates to the server, is the -@c right solution. - -@strong{@code{log} uses @samp{-R} in a way that conflicts -with the normal use inside @sc{cvs} (@pxref{Common options}).} - -@menu -* log options:: log options -* log examples:: log examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node log options -@appendixsubsec log options - -By default, @code{log} prints all information that is -available. All other options restrict the output. Note that the revision -selection options (@code{-b}, @code{-d}, @code{-r}, @code{-s}, and @code{-w}) -have no -effect, other than possibly causing a search for files in Attic directories, -when used in conjunction with the options that restrict the output to only -@code{log} header fields (@code{-h}, @code{-R}, and @code{-t}) -unless the @code{-S} option is also specified. - -@table @code -@item -b -Print information about the revisions on the default -branch, normally the highest branch on the trunk. - -@item -d @var{dates} -Print information about revisions with a checkin -date/time in the range given by the -semicolon-separated list of dates. The date formats -accepted are those accepted by the @samp{-D} option to -many other @sc{cvs} commands (@pxref{Common options}). -Dates can be combined into ranges as follows: - -@c Should we be thinking about accepting ISO8601 -@c ranges? For example "1972-09-10/1972-09-12". -@table @code -@item @var{d1}<@var{d2} -@itemx @var{d2}>@var{d1} -Select the revisions that were deposited between -@var{d1} and @var{d2}. - -@item <@var{d} -@itemx @var{d}> -Select all revisions dated @var{d} or earlier. - -@item @var{d}< -@itemx >@var{d} -Select all revisions dated @var{d} or later. - -@item @var{d} -Select the single, latest revision dated @var{d} or -earlier. -@end table - -The @samp{>} or @samp{<} characters may be followed by -@samp{=} to indicate an inclusive range rather than an -exclusive one. - -Note that the separator is a semicolon (;). - -@item -h -Print only the name of the @sc{rcs} file, name -of the file in the working directory, head, -default branch, access list, locks, symbolic names, and -suffix. - -@item -l -Local; run only in current working directory. (Default -is to run recursively). - -@item -N -Do not print the list of tags for this file. This -option can be very useful when your site uses a lot of -tags, so rather than "more"'ing over 3 pages of tag -information, the log information is presented without -tags at all. - -@item -n -Print the list of tags for this file. This option can -be very useful when your @file{.cvsrc} file has a -@samp{log -N} entry as a way to get a full list of all -of the tags. - -@item -R -Print only the name of the @sc{rcs} file. - -@c Note that using a bare revision (in addition to not -@c being explicitly documented here) is potentially -@c confusing; it shows the log message to get from the -@c previous revision to that revision. "-r1.3 -r1.6" -@c (equivalent to "-r1.3,1.6") is even worse; it -@c prints the messages to get from 1.2 to 1.3 and 1.5 -@c to 1.6. By analogy with "cvs diff", users might -@c expect that it is more like specifying a range. -@c It is not 100% clear to me how much of this should -@c be documented (for example, multiple -r options -@c perhaps could/should be deprecated given the false -@c analogy with "cvs diff"). -@c In general, this section should be rewritten to talk -@c about messages to get from revision rev1 to rev2, -@c rather than messages for revision rev2 (that is, the -@c messages are associated with a change not a static -@c revision and failing to make this distinction causes -@c much confusion). -@item -r@var{revisions} -Print information about revisions given in the -comma-separated list @var{revisions} of revisions and -ranges. The following table explains the available -range formats: - -@table @code -@item @var{rev1}:@var{rev2} -Revisions @var{rev1} to @var{rev2} (which must be on -the same branch). - -@item @var{rev1}::@var{rev2} -The same, but excluding @var{rev1}. - -@item :@var{rev} -@itemx ::@var{rev} -Revisions from the beginning of the branch up to -and including @var{rev}. - -@item @var{rev}: -Revisions starting with @var{rev} to the end of the -branch containing @var{rev}. - -@item @var{rev}:: -Revisions starting just after @var{rev} to the end of the -branch containing @var{rev}. - -@item @var{branch} -An argument that is a branch means all revisions on -that branch. - -@item @var{branch1}:@var{branch2} -@itemx @var{branch1}::@var{branch2} -A range of branches means all revisions -on the branches in that range. - -@item @var{branch}. -The latest revision in @var{branch}. -@end table - -A bare @samp{-r} with no revisions means the latest -revision on the default branch, normally the trunk. -There can be no space between the @samp{-r} option and -its argument. - -@item -S -Suppress the header if no revisions are selected. - -@item -s @var{states} -Print information about revisions whose state -attributes match one of the states given in the -comma-separated list @var{states}. Individual states may -be any text string, though @sc{cvs} commonly only uses two -states, @samp{Exp} and @samp{dead}. See @ref{admin options} -for more information. - -@item -t -Print the same as @samp{-h}, plus the descriptive text. - -@item -w@var{logins} -Print information about revisions checked in by users -with login names appearing in the comma-separated list -@var{logins}. If @var{logins} is omitted, the user's -login is assumed. There can be no space between the -@samp{-w} option and its argument. -@end table - -@code{log} prints the intersection of the revisions -selected with the options @samp{-d}, @samp{-s}, and -@samp{-w}, intersected with the union of the revisions -selected by @samp{-b} and @samp{-r}. - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node log examples -@appendixsubsec log examples - -Contributed examples are gratefully accepted. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node rdiff -@appendixsec rdiff---'patch' format diffs between releases -@cindex rdiff (subcommand) - -@itemize @bullet -@item -rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{} -@item -Requires: repository. -@item -Changes: nothing. -@item -Synonym: patch -@end itemize - -Builds a Larry Wall format patch(1) file between two -releases, that can be fed directly into the @code{patch} -program to bring an old release up-to-date with the new -release. (This is one of the few @sc{cvs} commands that -operates directly from the repository, and doesn't -require a prior checkout.) The diff output is sent to -the standard output device. - -You can specify (using the standard @samp{-r} and -@samp{-D} options) any combination of one or two -revisions or dates. If only one revision or date is -specified, the patch file reflects differences between -that revision or date and the current head revisions in -the @sc{rcs} file. - -Note that if the software release affected is contained -in more than one directory, then it may be necessary to -specify the @samp{-p} option to the @code{patch} command when -patching the old sources, so that @code{patch} is able to find -the files that are located in other directories. - -@menu -* rdiff options:: rdiff options -* rdiff examples:: rdiff examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node rdiff options -@appendixsubsec rdiff options - -These standard options are supported by @code{rdiff} -(@pxref{Common options} for a complete description of -them): - -@table @code -@item -D @var{date} -Use the most recent revision no later than @var{date}. - -@item -f -If no matching revision is found, retrieve the most -recent revision (instead of ignoring the file). - -@item -k @var{kflag} -Process keywords according to @var{kflag}. See -@ref{Keyword substitution}. - -@item -l -Local; don't descend subdirectories. - -@item -R -Examine directories recursively. This option is on by default. - -@item -r @var{tag} -Use revision @var{tag}. -@end table - -In addition to the above, these options are available: - -@table @code -@item -c -Use the context diff format. This is the default format. - -@item -s -Create a summary change report instead of a patch. The -summary includes information about files that were -changed or added between the releases. It is sent to -the standard output device. This is useful for finding -out, for example, which files have changed between two -dates or revisions. - -@item -t -A diff of the top two revisions is sent to the standard -output device. This is most useful for seeing what the -last change to a file was. - -@item -u -Use the unidiff format for the context diffs. -Remember that old versions -of the @code{patch} program can't handle the unidiff -format, so if you plan to post this patch to the net -you should probably not use @samp{-u}. - -@item -V @var{vn} -Expand keywords according to the rules current in -@sc{rcs} version @var{vn} (the expansion format changed with -@sc{rcs} version 5). Note that this option is no -longer accepted. @sc{cvs} will always expand keywords the -way that @sc{rcs} version 5 does. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node rdiff examples -@appendixsubsec rdiff examples - -Suppose you receive mail from @t{foo@@example.net} asking for an -update from release 1.2 to 1.4 of the tc compiler. You -have no such patches on hand, but with @sc{cvs} that can -easily be fixed with a command such as this: - -@example -$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ -> Mail -s 'The patches you asked for' foo@@example.net -@end example - -Suppose you have made release 1.3, and forked a branch -called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1} -corresponds to release 1.3.1, which was made some time -ago. Now, you want to see how much development has been -done on the branch. This command can be used: - -@example -$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name -cvs rdiff: Diffing module-name -File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 -File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 -File bar.h,v changed from revision 1.29.2.1 to 1.2 -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node release -@appendixsec release---Indicate that a Module is no longer in use -@cindex release (subcommand) - -@itemize @bullet -@item -release [-d] directories@dots{} -@item -Requires: Working directory. -@item -Changes: Working directory, history log. -@end itemize - -This command is meant to safely cancel the effect of -@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it -isn't strictly necessary to use this command. You can -always simply delete your working directory, if you -like; but you risk losing changes you may have -forgotten, and you leave no trace in the @sc{cvs} history -file (@pxref{history file}) that you've abandoned your -checkout. - -Use @samp{cvs release} to avoid these problems. This -command checks that no uncommitted changes are -present; that you are executing it from immediately -above a @sc{cvs} working directory; and that the repository -recorded for your files is the same as the repository -defined in the module database. - -If all these conditions are true, @samp{cvs release} -leaves a record of its execution (attesting to your -intentionally abandoning your checkout) in the @sc{cvs} -history log. - -@menu -* release options:: release options -* release output:: release output -* release examples:: release examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node release options -@appendixsubsec release options - -The @code{release} command supports one command option: - -@table @code -@item -d -Delete your working copy of the file if the release -succeeds. If this flag is not given your files will -remain in your working directory. - -@strong{WARNING: The @code{release} command deletes -all directories and files recursively. This -has the very serious side-effect that any directory -created inside checked-out sources, and not added to -the repository (using the @code{add} command; -@pxref{Adding files}) will be silently deleted---even -if it is non-empty!} -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node release output -@appendixsubsec release output - -Before @code{release} releases your sources it will -print a one-line message for any file that is not -up-to-date. - -@table @code -@item U @var{file} -@itemx P @var{file} -There exists a newer revision of this file in the -repository, and you have not modified your local copy -of the file (@samp{U} and @samp{P} mean the same thing). - -@item A @var{file} -The file has been added to your private copy of the -sources, but has not yet been committed to the -repository. If you delete your copy of the sources -this file will be lost. - -@item R @var{file} -The file has been removed from your private copy of the -sources, but has not yet been removed from the -repository, since you have not yet committed the -removal. See @ref{commit}. - -@item M @var{file} -The file is modified in your working directory. There -might also be a newer revision inside the repository. - -@item ? @var{file} -@var{file} is in your working directory, but does not -correspond to anything in the source repository, and is -not in the list of files for @sc{cvs} to ignore (see the -description of the @samp{-I} option, and -@pxref{cvsignore}). If you remove your working -sources, this file will be lost. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node release examples -@appendixsubsec release examples - -Release the @file{tc} directory, and delete your local working copy -of the files. - -@example -$ cd .. # @r{You must stand immediately above the} - # @r{sources when you issue @samp{cvs release}.} -$ cvs release -d tc -You have [0] altered files in this repository. -Are you sure you want to release (and delete) directory `tc': y -$ -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node remove -@appendixsec remove---Remove files from active use -@cindex remove (subcommand) - -@itemize @bullet -@item -Synopsis: remove [-flR] [files...] -@item -Requires: repository, working directory. -@item -Changes: working directory. -@end itemize - -The @code{remove} command is used to remove unwanted -files from active use. The user normally deletes the -files from the working directory prior to invocation -of the @code{remove} command. Only the working -directory is updated. Changes to the repository are -not made until the @code{commit} command is run. - -The @code{remove} command does not delete files from -from the repository. @sc{cvs} keeps all historical -data in the repository so that it is possible to -reconstruct previous states of the projects under -revision control. - -To undo @sc{cvs} @code{remove} or to resurrect files -that were previously removed, @xref{add}. - -@menu -* remove options:: remove options -* remove examples:: remove examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node remove options -@appendixsubsec remove options - -These standard options are supported by @code{remove} -(@pxref{Common options} for a complete description of -them): - -@table @code -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Process directories recursively. See @ref{Recursive behavior}. - -@end table - -In addition, these options are also supported: - -@table @code -@item -f -Note that this is not the standard behavior of -the @samp{-f} option as defined in @ref{Common options}. - -Delete files before removing them. - -Entire directory hierarchies are easily removed -using @samp{-f}, but take note that it is not as -easy to resurrect directory hierarchies as it is -to remove them. - -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node remove examples -@appendixsubsec remove examples - -@appendixsubsubsec Removing a file - -@example -$ cvs remove remove.me -cvs remove: file `remove.me' still in working directory -cvs remove: 1 file exists; remove it first -$ rm -f remove.me -$ cvs remove remove.me -cvs remove: scheduling `remove.me' for removal -cvs remove: use 'cvs commit' to remove this file permanently - -$ ls remove.it -remove.it -$ cvs remove -f remove.it -cvs remove: scheduling `remove.it' for removal -cvs remove: use 'cvs commit' to remove this file permanently -@end example - -@appendixsubsubsec Removing entire directories -@example -$ tree -d a -a -|-- CVS -`-- b - `-- CVS - -3 directories -$ cvs remove -f a -cvs remove: Removing a -cvs remove: Removing a/b -cvs remove: scheduling `a/b/c' for removal -cvs remove: use 'cvs commit' to remove this file permanently -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node update -@appendixsec update---Bring work tree in sync with repository -@cindex update (subcommand) - -@itemize @bullet -@item -update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files@dots{} -@item -Requires: repository, working directory. -@item -Changes: working directory. -@end itemize - -After you've run checkout to create your private copy -of source from the common repository, other developers -will continue changing the central source. From time -to time, when it is convenient in your development -process, you can use the @code{update} command from -within your working directory to reconcile your work -with any revisions applied to the source repository -since your last checkout or update. - -@menu -* update options:: update options -* update output:: update output -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node update options -@appendixsubsec update options - -These standard options are available with @code{update} -(@pxref{Common options} for a complete description of -them): - -@table @code -@item -D date -Use the most recent revision no later than @var{date}. -This option is sticky, and implies @samp{-P}. -See @ref{Sticky tags} for more information on sticky tags/dates. - -@item -f -Only useful with the @samp{-D @var{date}} or @samp{-r -@var{tag}} flags. If no matching revision is found, -retrieve the most recent revision (instead of ignoring -the file). - -@item -k @var{kflag} -Process keywords according to @var{kflag}. See -@ref{Keyword substitution}. -This option is sticky; future updates of -this file in this working directory will use the same -@var{kflag}. The @code{status} command can be viewed -to see the sticky options. See @ref{Invoking CVS} for -more information on the @code{status} command. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -P -Prune empty directories. See @ref{Moving directories}. - -@item -p -Pipe files to the standard output. - -@item -R -Update directories recursively (default). See @ref{Recursive -behavior}. - -@item -r rev -Retrieve revision/tag @var{rev}. This option is sticky, -and implies @samp{-P}. -See @ref{Sticky tags}, for more information on sticky tags/dates. -@end table - -@need 800 -These special options are also available with -@code{update}. - -@table @code -@item -A -Reset any sticky tags, dates, or @samp{-k} options. -Does not reset sticky @samp{-k} options on modified files. -See @ref{Sticky tags} for more information on sticky tags/dates. - -@item -C -Overwrite locally modified files with clean copies from -the repository (the modified file is saved in -@file{.#@var{file}.@var{revision}}, however). - -@item -d -Create any directories that exist in the repository if -they're missing from the working directory. Normally, -@code{update} acts only on directories and files that -were already enrolled in your working directory. - -This is useful for updating directories that were -created in the repository since the initial checkout; -but it has an unfortunate side effect. If you -deliberately avoided certain directories in the -repository when you created your working directory -(either through use of a module name or by listing -explicitly the files and directories you wanted on the -command line), then updating with @samp{-d} will create -those directories, which may not be what you want. - -@item -I @var{name} -Ignore files whose names match @var{name} (in your -working directory) during the update. You can specify -@samp{-I} more than once on the command line to specify -several files to ignore. Use @samp{-I !} to avoid -ignoring any files at all. See @ref{cvsignore} for other -ways to make @sc{cvs} ignore some files. - -@item -W@var{spec} -Specify file names that should be filtered during -update. You can use this option repeatedly. - -@var{spec} can be a file name pattern of the same type -that you can specify in the @file{.cvswrappers} -file. See @ref{Wrappers}. - -@item -j@var{revision} -With two @samp{-j} options, merge changes from the -revision specified with the first @samp{-j} option to -the revision specified with the second @samp{j} option, -into the working directory. - -With one @samp{-j} option, merge changes from the -ancestor revision to the revision specified with the -@samp{-j} option, into the working directory. The -ancestor revision is the common ancestor of the -revision which the working directory is based on, and -the revision specified in the @samp{-j} option. - -Note that using a single @samp{-j @var{tagname}} option rather than -@samp{-j @var{branchname}} to merge changes from a branch will -often not remove files which were removed on the branch. -See @ref{Merging adds and removals} for more information. - -In addition, each @samp{-j} option can contain an optional -date specification which, when used with branches, can -limit the chosen revision to one within a specific -date. An optional date is specified by adding a colon -(:) to the tag: -@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. - -See @ref{Branching and merging}. - -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node update output -@appendixsubsec update output - -@code{update} and @code{checkout} keep you informed of -their progress by printing a line for each file, preceded -by one character indicating the status of the file: - -@table @code -@item U @var{file} -The file was brought up to date with respect to the -repository. This is done for any file that exists in -the repository but not in your working directory, and for files -that you haven't changed but are not the most recent -versions available in the repository. - -@item P @var{file} -Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire -file. This accomplishes the same thing as @samp{U} using less bandwidth. - -@item A @var{file} -The file has been added to your private copy of the -sources, and will be added to the source repository -when you run @code{commit} on the file. This is a -reminder to you that the file needs to be committed. - -@item R @var{file} -The file has been removed from your private copy of the -sources, and will be removed from the source repository -when you run @code{commit} on the file. This is a -reminder to you that the file needs to be committed. - -@item M @var{file} -The file is modified in your working directory. - -@samp{M} can indicate one of two states for a file -you're working on: either there were no modifications -to the same file in the repository, so that your file -remains as you last saw it; or there were modifications -in the repository as well as in your copy, but they -were merged successfully, without conflict, in your -working directory. - -@sc{cvs} will print some messages if it merges your work, -and a backup copy of your working file (as it looked -before you ran @code{update}) will be made. The exact -name of that file is printed while @code{update} runs. - -@item C @var{file} -@cindex .# files -@cindex __ files (VMS) -A conflict was detected while trying to merge your -changes to @var{file} with changes from the source -repository. @var{file} (the copy in your working -directory) is now the result of attempting to merge -the two revisions; an unmodified copy of your file -is also in your working directory, with the name -@file{.#@var{file}.@var{revision}} where @var{revision} -is the revision that your modified file started -from. Resolve the conflict as described in -@ref{Conflicts example}. -@c "some systems" as in out-of-the-box OSes? Not as -@c far as I know. We need to advise sysadmins as well -@c as users how to set up this kind of purge, if that is -@c what they want. -@c We also might want to think about cleaner solutions, -@c like having CVS remove the .# file once the conflict -@c has been resolved or something like that. -(Note that some systems automatically purge -files that begin with @file{.#} if they have not been -accessed for a few days. If you intend to keep a copy -of your original file, it is a very good idea to rename -it.) Under @sc{vms}, the file name starts with -@file{__} rather than @file{.#}. - -@item ? @var{file} -@var{file} is in your working directory, but does not -correspond to anything in the source repository, and is -not in the list of files for @sc{cvs} to ignore (see the -description of the @samp{-I} option, and -@pxref{cvsignore}). -@end table - -@c ----- END MAN 1 ----- -@c --------------------------------------------------------------------- -@node Invoking CVS -@appendix Quick reference to CVS commands -@cindex Command reference -@cindex Reference, commands -@cindex Invoking CVS - -This appendix describes how to invoke @sc{cvs}, with -references to where each command or feature is -described in detail. For other references run the -@code{cvs --help} command, or see @ref{Index}. - -A @sc{cvs} command looks like: - -@example -cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] -@end example - -Global options: - -@table @code -@item --allow-root=@var{rootdir} -Specify legal @sc{cvsroot} directory (server only) (not -in @sc{cvs} 1.9 and older). See @ref{Password -authentication server}. - -@item -a -Authenticate all communication (client only) (not in @sc{cvs} -1.9 and older). See @ref{Global options}. - -@item -b -Specify RCS location (@sc{cvs} 1.9 and older). See -@ref{Global options}. - -@item -d @var{root} -Specify the @sc{cvsroot}. See @ref{Repository}. - -@item -e @var{editor} -Edit messages with @var{editor}. See @ref{Committing -your changes}. - -@item -f -Do not read the @file{~/.cvsrc} file. See @ref{Global -options}. - -@item -H -@itemx --help -Print a help message. See @ref{Global options}. - -@item -n -Do not change any files. See @ref{Global options}. - -@item -Q -Be really quiet. See @ref{Global options}. - -@item -q -Be somewhat quiet. See @ref{Global options}. - -@item -r -Make new working files read-only. See @ref{Global options}. - -@item -s @var{variable}=@var{value} -Set a user variable. See @ref{Variables}. - -@item -T @var{tempdir} -Put temporary files in @var{tempdir}. See @ref{Global -options}. - -@item -t -Trace @sc{cvs} execution. See @ref{Global options}. - -@item -v -@item --version -Display version and copyright information for @sc{cvs}. - -@item -w -Make new working files read-write. See @ref{Global -options}. - -@item -x -Encrypt all communication (client only). -See @ref{Global options}. - -@item -z @var{gzip-level} -@cindex Compression -@cindex Gzip -Set the compression level (client only). -See @ref{Global options}. -@end table - -Keyword expansion modes (@pxref{Substitution modes}): - -@example --kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ --kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ --kk $@splitrcskeyword{Id}$ --kv file1,v 1.1 1993/12/09 03:21:13 joe Exp --ko @i{no expansion} --kb @i{no expansion, file is binary} -@end example - -Keywords (@pxref{Keyword list}): - -@example -$@splitrcskeyword{Author}: joe $ -$@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ -$@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ -$@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ -$@splitrcskeyword{Locker}: harry $ -$@splitrcskeyword{Name}: snapshot_1_14 $ -$@splitrcskeyword{RCSfile}: file1,v $ -$@splitrcskeyword{Revision}: 1.1 $ -$@splitrcskeyword{Source}: /home/files/file1,v $ -$@splitrcskeyword{State}: Exp $ -$@splitrcskeyword{Log}: file1,v $ -Revision 1.1 1993/12/09 03:30:17 joe -Initial revision - -@end example - -@c The idea behind this table is that we want each item -@c to be a sentence or two at most. Preferably a -@c single line. -@c -@c In some cases refs to "foo options" are just to get -@c this thing written quickly, not because the "foo -@c options" node is really the best place to point. -Commands, command options, and command arguments: - -@table @code -@c ------------------------------------------------------------ -@item add [@var{options}] [@var{files}@dots{}] -Add a new file/directory. See @ref{Adding files}. - -@table @code -@item -k @var{kflag} -Set keyword expansion. - -@item -m @var{msg} -Set file description. -@end table - -@c ------------------------------------------------------------ -@item admin [@var{options}] [@var{files}@dots{}] -Administration of history files in the repository. See -@ref{admin}. -@c This list omits those options which are not -@c documented as being useful with CVS. That might be -@c a mistake... - -@table @code -@item -b[@var{rev}] -Set default branch. See @ref{Reverting local changes}. - -@item -c@var{string} -Set comment leader. - -@item -k@var{subst} -Set keyword substitution. See @ref{Keyword -substitution}. - -@item -l[@var{rev}] -Lock revision @var{rev}, or latest revision. - -@item -m@var{rev}:@var{msg} -Replace the log message of revision @var{rev} with -@var{msg}. - -@item -o@var{range} -Delete revisions from the repository. See -@ref{admin options}. - -@item -q -Run quietly; do not print diagnostics. - -@item -s@var{state}[:@var{rev}] -Set the state. See @ref{admin options} for more information on possible -states. - -@c Does not work for client/server CVS -@item -t -Set file description from standard input. - -@item -t@var{file} -Set file description from @var{file}. - -@item -t-@var{string} -Set file description to @var{string}. - -@item -u[@var{rev}] -Unlock revision @var{rev}, or latest revision. -@end table - -@c ------------------------------------------------------------ -@item annotate [@var{options}] [@var{files}@dots{}] -Show last revision where each line was modified. See -@ref{annotate}. - -@table @code -@item -D @var{date} -Annotate the most recent revision no later than -@var{date}. See @ref{Common options}. - -@item -F -Force annotation of binary files. (Without this option, -binary files are skipped with a message.) - -@item -f -Use head revision if tag/date not found. See -@ref{Common options}. - -@item -l -Local; run only in current working directory. @xref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{tag} -Annotate revision @var{tag}. See @ref{Common options}. -@end table - -@c ------------------------------------------------------------ -@item checkout [@var{options}] @var{modules}@dots{} -Get a copy of the sources. See @ref{checkout}. - -@table @code -@item -A -Reset any sticky tags/date/options. See @ref{Sticky -tags} and @ref{Keyword substitution}. - -@item -c -Output the module database. See @ref{checkout options}. - -@item -D @var{date} -Check out revisions as of @var{date} (is sticky). See -@ref{Common options}. - -@item -d @var{dir} -Check out into @var{dir}. See @ref{checkout options}. - -@item -f -Use head revision if tag/date not found. See -@ref{Common options}. - -@c Probably want to use rev1/rev2 style like for diff -@c -r. Here and in on-line help. -@item -j @var{rev} -Merge in changes. See @ref{checkout options}. - -@item -k @var{kflag} -Use @var{kflag} keyword expansion. See -@ref{Substitution modes}. - -@item -l -Local; run only in current working directory. @xref{Recursive behavior}. - -@item -N -Don't ``shorten'' module paths if -d specified. See -@ref{checkout options}. - -@item -n -Do not run module program (if any). See @ref{checkout options}. - -@item -P -Prune empty directories. See @ref{Moving directories}. - -@item -p -Check out files to standard output (avoids -stickiness). See @ref{checkout options}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{tag} -Checkout revision @var{tag} (is sticky). See @ref{Common options}. - -@item -s -Like -c, but include module status. See @ref{checkout options}. -@end table - -@c ------------------------------------------------------------ -@item commit [@var{options}] [@var{files}@dots{}] -Check changes into the repository. See @ref{commit}. - -@table @code -@item -F @var{file} -Read log message from @var{file}. See @ref{commit options}. - -@item -f -@c What is this "disables recursion"? It is from the -@c on-line help; is it documented in this manual? -Force the file to be committed; disables recursion. -See @ref{commit options}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -m @var{msg} -Use @var{msg} as log message. See @ref{commit options}. - -@item -n -Do not run module program (if any). See @ref{commit options}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{rev} -Commit to @var{rev}. See @ref{commit options}. -@c FIXME: should be dragging over text from -@c commit options, especially if it can be cleaned up -@c and made concise enough. -@end table - -@c ------------------------------------------------------------ -@item diff [@var{options}] [@var{files}@dots{}] -Show differences between revisions. See @ref{diff}. -In addition to the options shown below, accepts a wide -variety of options to control output style, for example -@samp{-c} for context diffs. - -@table @code -@item -D @var{date1} -Diff revision for date against working file. See -@ref{diff options}. - -@item -D @var{date2} -Diff @var{rev1}/@var{date1} against @var{date2}. See -@ref{diff options}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -N -Include diffs for added and removed files. See -@ref{diff options}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{rev1} -Diff revision for @var{rev1} against working file. See -@ref{diff options}. - -@item -r @var{rev2} -Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}. -@end table - -@c ------------------------------------------------------------ -@item edit [@var{options}] [@var{files}@dots{}] -Get ready to edit a watched file. See @ref{Editing files}. - -@table @code -@item -a @var{actions} -Specify actions for temporary watch, where -@var{actions} is @code{edit}, @code{unedit}, -@code{commit}, @code{all}, or @code{none}. See -@ref{Editing files}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. -@end table - -@c ------------------------------------------------------------ -@item editors [@var{options}] [@var{files}@dots{}] -See who is editing a watched file. See @ref{Watch information}. - -@table @code -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. -@end table - -@c ------------------------------------------------------------ -@item export [@var{options}] @var{modules}@dots{} -Export files from @sc{cvs}. See @ref{export}. - -@table @code -@item -D @var{date} -Check out revisions as of @var{date}. See -@ref{Common options}. - -@item -d @var{dir} -Check out into @var{dir}. See @ref{export options}. - -@item -f -Use head revision if tag/date not found. See -@ref{Common options}. - -@item -k @var{kflag} -Use @var{kflag} keyword expansion. See -@ref{Substitution modes}. - -@item -l -Local; run only in current working directory. @xref{Recursive behavior}. - -@item -N -Don't ``shorten'' module paths if -d specified. See -@ref{export options}. - -@item -n -Do not run module program (if any). See @ref{export options}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{tag} -Checkout revision @var{tag}. See @ref{Common options}. -@end table - -@c ------------------------------------------------------------ -@item history [@var{options}] [@var{files}@dots{}] -Show repository access history. See @ref{history}. - -@table @code -@item -a -All users (default is self). See @ref{history options}. - -@item -b @var{str} -Back to record with @var{str} in module/file/repos -field. See @ref{history options}. - -@item -c -Report on committed (modified) files. See @ref{history options}. - -@item -D @var{date} -Since @var{date}. See @ref{history options}. - -@item -e -Report on all record types. See @ref{history options}. - -@item -l -Last modified (committed or modified report). See @ref{history options}. - -@item -m @var{module} -Report on @var{module} (repeatable). See @ref{history options}. - -@item -n @var{module} -In @var{module}. See @ref{history options}. - -@item -o -Report on checked out modules. See @ref{history options}. - -@item -p @var{repository} -In @var{repository}. See @ref{history options}. - -@item -r @var{rev} -Since revision @var{rev}. See @ref{history options}. - -@item -T -@c What the @#$@# is a TAG? Same as a tag? This -@c wording is also in the online-line help. -Produce report on all TAGs. See @ref{history options}. - -@item -t @var{tag} -Since tag record placed in history file (by anyone). -See @ref{history options}. - -@item -u @var{user} -For user @var{user} (repeatable). See @ref{history options}. - -@item -w -Working directory must match. See @ref{history options}. - -@item -x @var{types} -Report on @var{types}, one or more of -@code{TOEFWUPCGMAR}. See @ref{history options}. - -@item -z @var{zone} -Output for time zone @var{zone}. See @ref{history options}. -@end table - -@c ------------------------------------------------------------ -@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} -Import files into @sc{cvs}, using vendor branches. See -@ref{import}. - -@table @code -@item -b @var{bra} -Import to vendor branch @var{bra}. See -@ref{Multiple vendor branches}. - -@item -d -Use the file's modification time as the time of -import. See @ref{import options}. - -@item -k @var{kflag} -Set default keyword substitution mode. See -@ref{import options}. - -@item -m @var{msg} -Use @var{msg} for log message. See -@ref{import options}. - -@item -I @var{ign} -More files to ignore (! to reset). See -@ref{import options}. - -@item -W @var{spec} -More wrappers. See @ref{import options}. -@end table - -@c ------------------------------------------------------------ -@item init -Create a @sc{cvs} repository if it doesn't exist. See -@ref{Creating a repository}. - -@c ------------------------------------------------------------ -@item kserver -Kerberos authenticated server. -See @ref{Kerberos authenticated}. - -@c ------------------------------------------------------------ -@item log [@var{options}] [@var{files}@dots{}] -Print out history information for files. See @ref{log}. - -@table @code -@item -b -Only list revisions on the default branch. See @ref{log options}. - -@item -d @var{dates} -Specify dates (@var{d1}<@var{d2} for range, @var{d} for -latest before). See @ref{log options}. - -@item -h -Only print header. See @ref{log options}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -N -Do not list tags. See @ref{log options}. - -@item -R -Only print name of RCS file. See @ref{log options}. - -@item -r@var{revs} -Only list revisions @var{revs}. See @ref{log options}. - -@item -s @var{states} -Only list revisions with specified states. See @ref{log options}. - -@item -t -Only print header and descriptive text. See @ref{log -options}. - -@item -w@var{logins} -Only list revisions checked in by specified logins. See @ref{log options}. -@end table - -@c ------------------------------------------------------------ -@item login -Prompt for password for authenticating server. See -@ref{Password authentication client}. - -@c ------------------------------------------------------------ -@item logout -Remove stored password for authenticating server. See -@ref{Password authentication client}. - -@c ------------------------------------------------------------ -@item pserver -Password authenticated server. -See @ref{Password authentication server}. - -@c ------------------------------------------------------------ -@item rannotate [@var{options}] [@var{modules}@dots{}] -Show last revision where each line was modified. See -@ref{annotate}. - -@table @code -@item -D @var{date} -Annotate the most recent revision no later than -@var{date}. See @ref{Common options}. - -@item -F -Force annotation of binary files. (Without this option, -binary files are skipped with a message.) - -@item -f -Use head revision if tag/date not found. See -@ref{Common options}. - -@item -l -Local; run only in current working directory. @xref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive behavior}. - -@item -r @var{tag} -Annotate revision @var{tag}. See @ref{Common options}. -@end table - -@c ------------------------------------------------------------ -@item rdiff [@var{options}] @var{modules}@dots{} -Show differences between releases. See @ref{rdiff}. - -@table @code -@item -c -Context diff output format (default). See @ref{rdiff options}. - -@item -D @var{date} -Select revisions based on @var{date}. See @ref{Common options}. - -@item -f -Use head revision if tag/date not found. See -@ref{Common options}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{rev} -Select revisions based on @var{rev}. See @ref{Common options}. - -@item -s -Short patch - one liner per file. See @ref{rdiff options}. - -@item -t -Top two diffs - last change made to the file. See -@ref{diff options}. - -@item -u -Unidiff output format. See @ref{rdiff options}. - -@item -V @var{vers} -Use RCS Version @var{vers} for keyword expansion (obsolete). See -@ref{rdiff options}. -@end table - -@c ------------------------------------------------------------ -@item release [@var{options}] @var{directory} -Indicate that a directory is no longer in use. See -@ref{release}. - -@table @code -@item -d -Delete the given directory. See @ref{release options}. -@end table - -@c ------------------------------------------------------------ -@item remove [@var{options}] [@var{files}@dots{}] -Remove an entry from the repository. See @ref{Removing files}. - -@table @code -@item -f -Delete the file before removing it. See @ref{Removing files}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. -@end table - -@c ------------------------------------------------------------ -@item rlog [@var{options}] [@var{files}@dots{}] -Print out history information for modules. See @ref{log}. - -@table @code -@item -b -Only list revisions on the default branch. See @ref{log options}. - -@item -d @var{dates} -Specify dates (@var{d1}<@var{d2} for range, @var{d} for -latest before). See @ref{log options}. - -@item -h -Only print header. See @ref{log options}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -N -Do not list tags. See @ref{log options}. - -@item -R -Only print name of RCS file. See @ref{log options}. - -@item -r@var{revs} -Only list revisions @var{revs}. See @ref{log options}. - -@item -s @var{states} -Only list revisions with specified states. See @ref{log options}. - -@item -t -Only print header and descriptive text. See @ref{log options}. - -@item -w@var{logins} -Only list revisions checked in by specified logins. See @ref{log options}. -@end table - -@c ------------------------------------------------------------ -@item rtag [@var{options}] @var{tag} @var{modules}@dots{} -Add a symbolic tag to a module. -See @ref{Revisions} and @ref{Branching and merging}. - -@table @code -@item -a -Clear tag from removed files that would not otherwise -be tagged. See @ref{Tagging add/remove}. - -@item -b -Create a branch named @var{tag}. See @ref{Branching and merging}. - -@item -B -Used in conjunction with -F or -d, enables movement and deletion of -branch tags. Use with extreme caution. - -@item -D @var{date} -Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. - -@item -d -Delete @var{tag}. See @ref{Modifying tags}. - -@item -F -Move @var{tag} if it already exists. See @ref{Modifying tags}. - -@item -f -Force a head revision match if tag/date not found. -See @ref{Tagging by date/tag}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -n -No execution of tag program. See @ref{Common options}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{rev} -Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. -@end table - -@c ------------------------------------------------------------ -@item server -Rsh server. See @ref{Connecting via rsh}. - -@c ------------------------------------------------------------ -@item status [@var{options}] @var{files}@dots{} -Display status information in a working directory. See -@ref{File status}. - -@table @code -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -v -Include tag information for file. See @ref{Tags}. -@end table - -@c ------------------------------------------------------------ -@item tag [@var{options}] @var{tag} [@var{files}@dots{}] -Add a symbolic tag to checked out version of files. -See @ref{Revisions} and @ref{Branching and merging}. - -@table @code -@item -b -Create a branch named @var{tag}. See @ref{Branching and merging}. - -@item -c -Check that working files are unmodified. See -@ref{Tagging the working directory}. - -@item -D @var{date} -Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. - -@item -d -Delete @var{tag}. See @ref{Modifying tags}. - -@item -F -Move @var{tag} if it already exists. See @ref{Modifying tags}. - -@item -f -Force a head revision match if tag/date not found. -See @ref{Tagging by date/tag}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{rev} -Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. -@end table - -@c ------------------------------------------------------------ -@item unedit [@var{options}] [@var{files}@dots{}] -Undo an edit command. See @ref{Editing files}. - -@table @code -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive behavior}. -@end table - -@c ------------------------------------------------------------ -@item update [@var{options}] [@var{files}@dots{}] -Bring work tree in sync with repository. See -@ref{update}. - -@table @code -@item -A -Reset any sticky tags/date/options. See @ref{Sticky -tags} and @ref{Keyword substitution}. - -@item -C -Overwrite locally modified files with clean copies from -the repository (the modified file is saved in -@file{.#@var{file}.@var{revision}}, however). - -@item -D @var{date} -Check out revisions as of @var{date} (is sticky). See -@ref{Common options}. - -@item -d -Create directories. See @ref{update options}. - -@item -f -Use head revision if tag/date not found. See -@ref{Common options}. - -@item -I @var{ign} -More files to ignore (! to reset). See -@ref{import options}. - -@c Probably want to use rev1/rev2 style like for diff -@c -r. Here and in on-line help. -@item -j @var{rev} -Merge in changes. See @ref{update options}. - -@item -k @var{kflag} -Use @var{kflag} keyword expansion. See -@ref{Substitution modes}. - -@item -l -Local; run only in current working directory. @xref{Recursive behavior}. - -@item -P -Prune empty directories. See @ref{Moving directories}. - -@item -p -Check out files to standard output (avoids -stickiness). See @ref{update options}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. - -@item -r @var{tag} -Checkout revision @var{tag} (is sticky). See @ref{Common options}. - -@item -W @var{spec} -More wrappers. See @ref{import options}. -@end table - -@c ------------------------------------------------------------ -@item version -@cindex version (subcommand) - -Display the version of @sc{cvs} being used. If the repository -is remote, display both the client and server versions. - -@c ------------------------------------------------------------ -@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] - -on/off: turn on/off read-only checkouts of files. See -@ref{Setting a watch}. - -add/remove: add or remove notification on actions. See -@ref{Getting Notified}. - -@table @code -@item -a @var{actions} -Specify actions for temporary watch, where -@var{actions} is @code{edit}, @code{unedit}, -@code{commit}, @code{all}, or @code{none}. See -@ref{Editing files}. - -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. -@end table - -@c ------------------------------------------------------------ -@item watchers [@var{options}] [@var{files}@dots{}] -See who is watching a file. See @ref{Watch information}. - -@table @code -@item -l -Local; run only in current working directory. See @ref{Recursive behavior}. - -@item -R -Operate recursively (default). @xref{Recursive -behavior}. -@end table - -@end table - -@c --------------------------------------------------------------------- -@node Administrative files -@appendix Reference manual for Administrative files -@cindex Administrative files (reference) -@cindex Files, reference manual -@cindex Reference manual (files) -@cindex CVSROOT (file) - -@c FIXME? Somewhere there needs to be a more "how-to" -@c guide to writing these. I think the triggers -@c (commitinfo, loginfo, taginfo, &c) are perhaps a -@c different case than files like modules. One -@c particular issue that people sometimes are -@c (unnecessarily?) worried about is performance, and -@c the impact of writing in perl or sh or ____. -Inside the repository, in the directory -@file{$CVSROOT/CVSROOT}, there are a number of -supportive files for @sc{cvs}. You can use @sc{cvs} in a limited -fashion without any of them, but if they are set up -properly they can help make life easier. For a -discussion of how to edit them, see @ref{Intro -administrative files}. - -The most important of these files is the @file{modules} -file, which defines the modules inside the repository. - -@menu -* modules:: Defining modules -* Wrappers:: Specify binary-ness based on file name -* Trigger Scripts:: Some notes on the commit support files and - taginfo, referenced below. -* commit files:: The commit support files (commitinfo, - verifymsg, editinfo, loginfo) -* taginfo:: Verifying/Logging tags -* rcsinfo:: Templates for the log messages -* cvsignore:: Ignoring files via cvsignore -* checkoutlist:: Adding your own administrative files -* history file:: History information -* Variables:: Various variables are expanded -* config:: Miscellaneous CVS configuration -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node modules -@appendixsec The modules file -@cindex Modules (admin file) -@cindex Defining modules (reference manual) - -The @file{modules} file records your definitions of -names for collections of source code. @sc{cvs} will -use these definitions if you use @sc{cvs} to update the -modules file (use normal commands like @code{add}, -@code{commit}, etc). - -The @file{modules} file may contain blank lines and -comments (lines beginning with @samp{#}) as well as -module definitions. Long lines can be continued on the -next line by specifying a backslash (@samp{\}) as the -last character on the line. - -There are three basic types of modules: alias modules, -regular modules, and ampersand modules. The difference -between them is the way that they map files in the -repository to files in the working directory. In all -of the following examples, the top-level repository -contains a directory called @file{first-dir}, which -contains two files, @file{file1} and @file{file2}, and a -directory @file{sdir}. @file{first-dir/sdir} contains -a file @file{sfile}. - -@c FIXME: should test all the examples in this section. - -@menu -* Alias modules:: The simplest kind of module -* Regular modules:: -* Ampersand modules:: -* Excluding directories:: Excluding directories from a module -* Module options:: Regular and ampersand modules can take options -* Module program options:: How the modules ``program options'' programs - are run. -@end menu - -@node Alias modules -@appendixsubsec Alias modules -@cindex Alias modules -@cindex -a, in modules file - -Alias modules are the simplest kind of module: - -@table @code -@item @var{mname} -a @var{aliases}@dots{} -This represents the simplest way of defining a module -@var{mname}. The @samp{-a} flags the definition as a -simple alias: @sc{cvs} will treat any use of @var{mname} (as -a command argument) as if the list of names -@var{aliases} had been specified instead. -@var{aliases} may contain either other module names or -paths. When you use paths in aliases, @code{checkout} -creates all intermediate directories in the working -directory, just as if the path had been specified -explicitly in the @sc{cvs} arguments. -@end table - -For example, if the modules file contains: - -@example -amodule -a first-dir -@end example - -@noindent -then the following two commands are equivalent: - -@example -$ cvs co amodule -$ cvs co first-dir -@end example - -@noindent -and they each would provide output such as: - -@example -cvs checkout: Updating first-dir -U first-dir/file1 -U first-dir/file2 -cvs checkout: Updating first-dir/sdir -U first-dir/sdir/sfile -@end example - -@node Regular modules -@appendixsubsec Regular modules -@cindex Regular modules - -@table @code -@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] -In the simplest case, this form of module definition -reduces to @samp{@var{mname} @var{dir}}. This defines -all the files in directory @var{dir} as module mname. -@var{dir} is a relative path (from @code{$CVSROOT}) to a -directory of source in the source repository. In this -case, on checkout, a single directory called -@var{mname} is created as a working directory; no -intermediate directory levels are used by default, even -if @var{dir} was a path involving several directory -levels. -@end table - -For example, if a module is defined by: - -@example -regmodule first-dir -@end example - -@noindent -then regmodule will contain the files from first-dir: - -@example -$ cvs co regmodule -cvs checkout: Updating regmodule -U regmodule/file1 -U regmodule/file2 -cvs checkout: Updating regmodule/sdir -U regmodule/sdir/sfile -$ -@end example - -By explicitly specifying files in the module definition -after @var{dir}, you can select particular files from -directory @var{dir}. Here is -an example: - -@example -regfiles first-dir/sdir sfile -@end example - -@noindent -With this definition, getting the regfiles module -will create a single working directory -@file{regfiles} containing the file listed, which -comes from a directory deeper -in the @sc{cvs} source repository: - -@example -$ cvs co regfiles -U regfiles/sfile -$ -@end example - -@node Ampersand modules -@appendixsubsec Ampersand modules -@cindex Ampersand modules -@cindex &, in modules file - -A module definition can refer to other modules by -including @samp{&@var{module}} in its definition. -@example -@var{mname} [ options ] @var{&module}@dots{} -@end example - -Then getting the module creates a subdirectory for each such -module, in the directory containing the module. For -example, if modules contains - -@example -ampermod &first-dir -@end example - -@noindent -then a checkout will create an @code{ampermod} directory -which contains a directory called @code{first-dir}, -which in turns contains all the directories and files -which live there. For example, the command - -@example -$ cvs co ampermod -@end example - -@noindent -will create the following files: - -@example -ampermod/first-dir/file1 -ampermod/first-dir/file2 -ampermod/first-dir/sdir/sfile -@end example - -There is one quirk/bug: the messages that @sc{cvs} -prints omit the @file{ampermod}, and thus do not -correctly display the location to which it is checking -out the files: - -@example -$ cvs co ampermod -cvs checkout: Updating first-dir -U first-dir/file1 -U first-dir/file2 -cvs checkout: Updating first-dir/sdir -U first-dir/sdir/sfile -$ -@end example - -Do not rely on this buggy behavior; it may get fixed in -a future release of @sc{cvs}. - -@c FIXCVS: What happens if regular and & modules are -@c combined, as in "ampermodule first-dir &second-dir"? -@c When I tried it, it seemed to just ignore the -@c "first-dir". I think perhaps it should be an error -@c (but this needs further investigation). -@c In addition to discussing what each one does, we -@c should put in a few words about why you would use one or -@c the other in various situations. - -@node Excluding directories -@appendixsubsec Excluding directories -@cindex Excluding directories, in modules file -@cindex !, in modules file - -An alias module may exclude particular directories from -other modules by using an exclamation mark (@samp{!}) -before the name of each directory to be excluded. - -For example, if the modules file contains: - -@example -exmodule -a !first-dir/sdir first-dir -@end example - -@noindent -then checking out the module @samp{exmodule} will check -out everything in @samp{first-dir} except any files in -the subdirectory @samp{first-dir/sdir}. -@c Note that the "!first-dir/sdir" sometimes must be listed -@c before "first-dir". That seems like a probable bug, in which -@c case perhaps it should be fixed (to allow either -@c order) rather than documented. See modules4 in testsuite. - -@node Module options -@appendixsubsec Module options -@cindex Options, in modules file - -Either regular modules or ampersand modules can contain -options, which supply additional information concerning -the module. - -@table @code -@cindex -d, in modules file -@item -d @var{name} -Name the working directory something other than the -module name. -@c FIXME: Needs a bunch of examples, analogous to the -@c examples for alias, regular, and ampersand modules -@c which show where the files go without -d. - -@cindex Export program -@cindex -e, in modules file -@item -e @var{prog} -Specify a program @var{prog} to run whenever files in a -module are exported. @var{prog} runs with a single -argument, the module name. -@c FIXME: Is it run on server? client? - -@cindex Checkout program -@cindex -o, in modules file -@item -o @var{prog} -Specify a program @var{prog} to run whenever files in a -module are checked out. @var{prog} runs with a single -argument, the module name. See @ref{Module program options} for -information on how @var{prog} is called. -@c FIXME: Is it run on server? client? - -@cindex Status of a module -@cindex Module status -@cindex -s, in modules file -@item -s @var{status} -Assign a status to the module. When the module file is -printed with @samp{cvs checkout -s} the modules are -sorted according to primarily module status, and -secondarily according to the module name. This option -has no other meaning. You can use this option for -several things besides status: for instance, list the -person that is responsible for this module. - -@cindex Tag program -@cindex -t, in modules file -@item -t @var{prog} -Specify a program @var{prog} to run whenever files in a -module are tagged with @code{rtag}. @var{prog} runs -with two arguments: the module name and the symbolic -tag specified to @code{rtag}. It is not run -when @code{tag} is executed. Generally you will find -that the @file{taginfo} file is a better solution (@pxref{taginfo}). -@c FIXME: Is it run on server? client? -@c Problems with -t include: -@c * It is run after the tag not before -@c * It doesn't get passed all the information that -@c taginfo does ("mov", &c). -@c * It only is run for rtag, not tag. -@end table - -You should also see @pxref{Module program options} about how the -``program options'' programs are run. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Module program options -@appendixsubsec How the modules file ``program options'' programs are run -@cindex Modules file program options -@cindex -t, in modules file -@cindex -o, in modules file -@cindex -e, in modules file - -@noindent -For checkout, rtag, and export, the program is server-based, and as such the -following applies:- - -If using remote access methods (pserver, ext, etc.), -@sc{cvs} will execute this program on the server from a temporary -directory. The path is searched for this program. - -If using ``local access'' (on a local or remote NFS file system, i.e., -repository set just to a path), -the program will be executed from the newly checked-out tree, if -found there, or alternatively searched for in the path if not. - -The programs are all run after the operation has effectively -completed. - - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Wrappers -@appendixsec The cvswrappers file -@cindex cvswrappers (admin file) -@cindex CVSWRAPPERS, environment variable -@cindex Wrappers - -@c FIXME: need some better way of separating this out -@c by functionality. -m is -@c one feature, and -k is a another. And this discussion -@c should be better motivated (e.g. start with the -@c problems, then explain how the feature solves it). - -Wrappers refers to a @sc{cvs} feature which lets you -control certain settings based on the name of the file -which is being operated on. The settings are @samp{-k} -for binary files, and @samp{-m} for nonmergeable text -files. - -The @samp{-m} option -specifies the merge methodology that should be used when -a non-binary file is updated. @code{MERGE} means the usual -@sc{cvs} behavior: try to merge the files. @code{COPY} -means that @code{cvs update} will refuse to merge -files, as it also does for files specified as binary -with @samp{-kb} (but if the file is specified as -binary, there is no need to specify @samp{-m 'COPY'}). -@sc{cvs} will provide the user with the -two versions of the files, and require the user using -mechanisms outside @sc{cvs}, to insert any necessary -changes. - -@strong{WARNING: Do not use @code{COPY} with -@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will -copy one version of your file over the other, wiping -out the previous contents.} -@c Ordinarily we don't document the behavior of old -@c versions. But this one is so dangerous, I think we -@c must. I almost renamed it to -m 'NOMERGE' so we -@c could say "never use -m 'COPY'". -The @samp{-m} wrapper option only affects behavior when -merging is done on update; it does not affect how files -are stored. See @ref{Binary files}, for more on -binary files. - -The basic format of the file @file{cvswrappers} is: - -@c FIXME: @example is all wrong for this. Use @deffn or -@c something more sensible. -@example -wildcard [option value][option value]... - -where option is one of --m update methodology value: MERGE or COPY --k keyword expansion value: expansion mode - -and value is a single-quote delimited value. -@end example - -@ignore -@example -*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' -*.c -t 'indent %s %s' -@end example -@c When does the filter need to be an absolute pathname -@c and when will something like the above work? I -@c suspect it relates to the PATH of the server (which -@c in turn depends on all kinds of stuff, e.g. inetd -@c for pserver). I'm not sure whether/where to discuss -@c this. -@c FIXME: What do the %s's stand for? - -@noindent -The above example of a @file{cvswrappers} file -states that all files/directories that end with a @code{.nib} -should be filtered with the @file{wrap} program before -checking the file into the repository. The file should -be filtered though the @file{unwrap} program when the -file is checked out of the repository. The -@file{cvswrappers} file also states that a @code{COPY} -methodology should be used when updating the files in -the repository (that is, no merging should be performed). - -@c What pitfalls arise when using indent this way? Is -@c it a winning thing to do? Would be nice to at least -@c hint at those issues; we want our examples to tell -@c how to solve problems, not just to say that cvs can -@c do certain things. -The last example line says that all files that end with -@code{.c} should be filtered with @file{indent} -before being checked into the repository. Unlike the previous -example, no filtering of the @code{.c} file is done when -it is checked out of the repository. -@noindent -The @code{-t} filter is called with two arguments, -the first is the name of the file/directory to filter -and the second is the pathname to where the resulting -filtered file should be placed. - -@noindent -The @code{-f} filter is called with one argument, -which is the name of the file to filter from. The end -result of this filter will be a file in the users directory -that they can work on as they normally would. - -Note that the @samp{-t}/@samp{-f} features do not -conveniently handle one portion of @sc{cvs}'s operation: -determining when files are modified. @sc{cvs} will still -want a file (or directory) to exist, and it will use -its modification time to determine whether a file is -modified. If @sc{cvs} erroneously thinks a file is -unmodified (for example, a directory is unchanged but -one of the files within it is changed), you can force -it to check in the file anyway by specifying the -@samp{-f} option to @code{cvs commit} (@pxref{commit -options}). -@c This is, of course, a serious design flaw in -t/-f. -@c Probably the whole functionality needs to be -@c redesigned (starting from requirements) to fix this. -@end ignore - -@c FIXME: We don't document -W or point to where it is -@c documented. Or .cvswrappers. -For example, the following command imports a -directory, treating files whose name ends in -@samp{.exe} as binary: - -@example -cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag -@end example - -@c Another good example, would be storing files -@c (e.g. binary files) compressed in the repository. -@c :::::::::::::::::: -@c cvswrappers -@c :::::::::::::::::: -@c *.t12 -m 'COPY' -@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' -@c -@c :::::::::::::::::: -@c gunzipcp -@c :::::::::::::::::: -@c : -@c [ -f $1 ] || exit 1 -@c zcat $1 > /tmp/.#$1.$$ -@c mv /tmp/.#$1.$$ $1 -@c -@c :::::::::::::::::: -@c gzipcp -@c :::::::::::::::::: -@c : -@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` -@c if [ ! -d $DIRNAME ] ; then -@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` -@c fi -@c gzip -c $DIRNAME > $2 -@c One catch--"cvs diff" will not invoke the wrappers -@c (probably a CVS bug, although I haven't thought it out). - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node Trigger Scripts -@appendixsec The Trigger Scripts -@cindex Info files -@cindex Trigger scripts - -Several of the administrative files support triggers, or the launching external -scripts or programs at specific times before or after particular events. The -individual files are discussed in the later sections, @ref{commit files} and -@ref{taginfo}, but some of the common elements are discussed here. - -All the trigger scripts are launched in a copy of the user sandbox being -committed, on the server, in client-server mode. In local mode, the scripts -are actually launched directly from the user sandbox directory being committed. -For most intents and purposes, the same scripts can be run in both locations -without alteration. - -@menu -* syntax:: The common syntax -* Trigger Script Security:: Trigger script security -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node syntax -@appendixsubsec The common syntax -@cindex Info files (syntax) -@cindex Syntax of info files -@cindex Common syntax of info files - -@c FIXME: having this so totally separate from the -@c Variables node is rather bogus. - -The administrative files such as @file{commitinfo}, -@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., -all have a common format. The purpose of the files are -described later on. The common syntax is described -here. - -@cindex Regular expression syntax -Each line contains the following: -@itemize @bullet -@item -@c Say anything about DEFAULT and ALL? Right now we -@c leave that to the description of each file (and in fact -@c the practice is inconsistent which is really annoying). -A regular expression. This is a basic regular -expression in the syntax used by GNU emacs. -@c FIXME: What we probably should be saying is "POSIX Basic -@c Regular Expression with the following extensions (`\(' -@c `\|' '+' etc)" -@c rather than define it with reference to emacs. -@c The reference to emacs is not strictly speaking -@c true, as we don't support \=, \s, or \S. Also it isn't -@c clear we should document and/or promise to continue to -@c support all the obscure emacs extensions like \<. -@c Also need to better cite (or include) full -@c documentation for the syntax. -@c Also see comment in configure.in about what happens to the -@c syntax if we pick up a system-supplied regexp matcher. - -@item -A whitespace separator---one or more spaces and/or tabs. - -@item -A file name or command-line template. -@end itemize - -@noindent -Blank lines are ignored. Lines that start with the -character @samp{#} are treated as comments. Long lines -unfortunately can @emph{not} be broken in two parts in -any way. - -The first regular expression that matches the current -directory name in the repository is used. The rest of the line -is used as a file name or command-line as appropriate. - -@c FIXME: need an example. In particular, show what -@c the regular expression is matched against (one -@c ordinarily clueful person got confused about whether it -@c includes the filename--"directory name" above should be -@c unambiguous but there is nothing like an example to -@c confirm people's understanding of this sort of thing). - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node Trigger Script Security -@appendixsubsec Security and the Trigger Scripts -@cindex Info files, security -@cindex Trigger scripts, security - -Security is a huge subject, and implementing a secure system is a non-trivial -task. This section will barely touch on all the issues involved, but it is -well to note that, as with any script you will be allowing an untrusted -user to run on your server, there are measures you can take to help prevent -your trigger scripts from being abused. - -For instance, since the CVS trigger scripts all run in a copy of the user's -sandbox on the server, a naively coded Perl trigger script which attempts to -use a Perl module that is not installed on the system can be hijacked by any -user with commit access who is checking in a file with the correct name. Other -scripting languages may be vulnerable to similar hacks. - -One way to make a script more secure, at least with Perl, is to use scripts -which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. -In the most basic terms, this causes Perl to avoid running code that may have -come from an external source. Please run the @code{perldoc perlsec} command -for more on Perl security. Again, other languages may implement other security -verification hooks which look more or less like Perl's "taint-check" mechanism. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node commit files -@appendixsec The commit support files -@cindex Committing, administrative support files - -There are three kinds of trigger scripts (@pxref{Trigger Scripts}) that can be -run at various times during a commit. They are specified in files in the -repository, as described below. The following table summarizes the -file names and the purpose of the corresponding programs. - -@table @file -@item commitinfo -The program is responsible for checking that the commit -is allowed. If it exits with a non-zero exit status -the commit will be aborted. - -@item verifymsg -The specified program is used to evaluate the log message, -and possibly verify that it contains all required -fields. This is most useful in combination with the -@file{rcsinfo} file, which can hold a log message -template (@pxref{rcsinfo}). - -@item editinfo -The specified program is used to edit the log message, -and possibly verify that it contains all required -fields. This is most useful in combination with the -@file{rcsinfo} file, which can hold a log message -template (@pxref{rcsinfo}). (obsolete) - -@item loginfo -The specified program is called when the commit is -complete. It receives the log message and some -additional information and can store the log message in -a file, or mail it to appropriate persons, or maybe -post it to a local newsgroup, or@dots{} Your -imagination is the limit! -@end table - -@menu -* commitinfo:: Pre-commit checking -* verifymsg:: How are log messages evaluated? -* editinfo:: Specifying how log messages are created - (obsolete) -* loginfo:: Where should log messages be sent? -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node commitinfo -@appendixsubsec Commitinfo -@cindex @file{commitinfo} -@cindex Commits, precommit verification of -@cindex Precommit checking - -The @file{commitinfo} file defines programs to execute -whenever @samp{cvs commit} is about to execute. These -programs are used for pre-commit checking to verify -that the modified, added and removed files are really -ready to be committed. This could be used, for -instance, to verify that the changed files conform to -to your site's standards for coding practice. - -As mentioned earlier, each line in the -@file{commitinfo} file consists of a regular expression -and a command-line template. The template can include -a program name and any number of arguments you wish to -supply to it. The full path to the current source -repository is appended to the template, followed by the -file names of any files involved in the commit (added, -removed, and modified files). - -@cindex Exit status, of commitinfo -The first line with a regular expression matching the -directory within the repository will be used. If the -command returns a non-zero exit status the commit will -be aborted. -@c FIXME: need example(s) of what "directory within the -@c repository" means. - -@cindex DEFAULT in commitinfo -If the repository name does not match any of the -regular expressions in this file, the @samp{DEFAULT} -line is used, if it is specified. - -@cindex ALL in commitinfo -All occurrences of the name @samp{ALL} appearing as a -regular expression are used in addition to the first -matching regular expression or the name @samp{DEFAULT}. - -@cindex @file{commitinfo}, working directory -@cindex @file{commitinfo}, command environment -The command will be run in the root of the workspace -containing the new versions of any files the user would like -to modify (commit), @emph{or in a copy of the workspace on -the server (@pxref{Remote repositories})}. If a file is -being removed, there will be no copy of the file under the -current directory. If a file is being added, there will be -no corresponding archive file in the repository unless the -file is being resurrected. - -Note that both the repository directory and the corresponding -Attic (@pxref{Attic}) directory may need to be checked to -locate the archive file corresponding to any given file being -committed. Much of the information about the specific commit -request being made, including the destination branch, commit -message, and command line options specified, is not available -to the command. - -@c FIXME: should discuss using commitinfo to control -@c who has checkin access to what (e.g. Joe can check into -@c directories a, b, and c, and Mary can check into -@c directories b, c, and d--note this case cannot be -@c conveniently handled with unix groups). Of course, -@c adding a new set of features to CVS might be a more -@c natural way to fix this problem than telling people to -@c use commitinfo. -@c FIXME: Should make some reference, especially in -@c the context of controlling who has access, to the fact -@c that commitinfo can be circumvented. Perhaps -@c mention SETXID (but has it been carefully examined -@c for holes?). This fits in with the discussion of -@c general CVS security in "Password authentication -@c security" (the bit which is not pserver-specific). - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node verifymsg -@appendixsubsec Verifying log messages -@cindex @file{verifymsg} (admin file) -@cindex Log message, verifying - -Once you have entered a log message, you can evaluate -that message to check for specific content, such as -a bug ID. Use the @file{verifymsg} file to -specify a program that is used to verify the log message. -This program could be a simple script that checks -that the entered message contains the required fields. - -The @file{verifymsg} file is often most useful together -with the @file{rcsinfo} file, which can be used to -specify a log message template. - -Each line in the @file{verifymsg} file consists of a -regular expression and a command-line template. The -template must include a program name, and can include -any number of arguments. The full path to the current -log message template file is appended to the template. - -One thing that should be noted is that the @samp{ALL} -keyword is not supported. If more than one matching -line is found, the first one is used. This can be -useful for specifying a default verification script in a -directory, and then overriding it in a subdirectory. - -@cindex DEFAULT in @file{verifymsg} -If the repository name does not match any of the -regular expressions in this file, the @samp{DEFAULT} -line is used, if it is specified. - -@cindex Exit status, of @file{verifymsg} -If the verification script exits with a non-zero exit status, -the commit is aborted. - -@cindex @file{verifymsg}, changing the log message -In the default configuration, CVS allows the -verification script to change the log message. This is -controlled via the RereadLogAfterVerify CVSROOT/config -option. - -When @samp{RereadLogAfterVerify=always} or -@samp{RereadLogAfterVerify=stat}, the log message will -either always be reread after the verification script -is run or reread only if the log message file status -has changed. - -@xref{config}, for more on CVSROOT/config options. - -It is NOT a good idea for a @file{verifymsg} script to -interact directly with the user in the various -client/server methods. For the @code{pserver} method, -there is no protocol support for communicating between -@file{verifymsg} and the client on the remote end. For the -@code{ext} and @code{server} methods, it is possible -for CVS to become confused by the characters going -along the same channel as the CVS protocol -messages. See @ref{Remote repositories}, for more -information on client/server setups. In addition, at the time -the @file{verifymsg} script runs, the CVS -server has locks in place in the repository. If control is -returned to the user here then other users may be stuck waiting -for access to the repository. - -This option can be useful if you find yourself using an -rcstemplate that needs to be modified to remove empty -elements or to fill in default values. It can also be -useful if the rcstemplate has changed in the repository -and the CVS/Template was not updated, but is able to be -adapted to the new format by the verification script -that is run by @file{verifymsg}. - -An example of an update might be to change all -occurrences of 'BugId:' to be 'DefectId:' (which can be -useful if the rcstemplate has recently been changed and -there are still checked-out user trees with cached -copies in the CVS/Template file of the older version). - -Another example of an update might be to delete a line -that contains 'BugID: none' from the log message after -validation of that value as being allowed is made. - -The following is a little silly example of a -@file{verifymsg} file, together with the corresponding -@file{rcsinfo} file, the log message template and an -verification script. We begin with the log message template. -We want to always record a bug-id number on the first -line of the log message. The rest of log message is -free text. The following template is found in the file -@file{/usr/cvssupport/tc.template}. - -@example -BugId: -@end example - -The script @file{/usr/cvssupport/bugid.verify} is used to -evaluate the log message. - -@example -#!/bin/sh -# -# bugid.verify filename -# -# Verify that the log message contains a valid bugid -# on the first line. -# -if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then - exit 0 -elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then - # It is okay to allow commits with 'BugId: none', - # but do not put that text into the real log message. - grep -v '^BugId:[ ]*none$' > $1.rewrite - mv $1.rewrite $1 - exit 0 -else - echo "No BugId found." - exit 1 -fi -@end example - -The @file{verifymsg} file contains this line: - -@example -^tc /usr/cvssupport/bugid.verify -@end example - -The @file{rcsinfo} file contains this line: - -@example -^tc /usr/cvssupport/tc.template -@end example - -The @file{config} file contains this line: - -@example -RereadLogAfterVerify=always -@end example - - - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node editinfo -@appendixsubsec Editinfo -@cindex editinfo (admin file) -@cindex Editor, specifying per module -@cindex Per-module editor -@cindex Log messages, editing - -@strong{The @file{editinfo} feature has been -rendered obsolete. To set a default editor for log -messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables -(@pxref{Environment variables}) or the @samp{-e} global -option (@pxref{Global options}). See @ref{verifymsg}, -for information on the use of the @file{verifymsg} -feature for evaluating log messages.} - -If you want to make sure that all log messages look the -same way, you can use the @file{editinfo} file to -specify a program that is used to edit the log message. -This program could be a custom-made editor that always -enforces a certain style of the log message, or maybe a -simple shell script that calls an editor, and checks -that the entered message contains the required fields. - -If no matching line is found in the @file{editinfo} -file, the editor specified in the environment variable -@code{$CVSEDITOR} is used instead. If that variable is -not set, then the environment variable @code{$EDITOR} -is used instead. If that variable is not -set a default will be used. See @ref{Committing your changes}. - -The @file{editinfo} file is often most useful together -with the @file{rcsinfo} file, which can be used to -specify a log message template. - -Each line in the @file{editinfo} file consists of a -regular expression and a command-line template. The -template must include a program name, and can include -any number of arguments. The full path to the current -log message template file is appended to the template. - -One thing that should be noted is that the @samp{ALL} -keyword is not supported. If more than one matching -line is found, the first one is used. This can be -useful for specifying a default edit script in a -module, and then overriding it in a subdirectory. - -@cindex DEFAULT in editinfo -If the repository name does not match any of the -regular expressions in this file, the @samp{DEFAULT} -line is used, if it is specified. - -If the edit script exits with a non-zero exit status, -the commit is aborted. - -Note: when @sc{cvs} is accessing a remote repository, -or when the @samp{-m} or @samp{-F} options to @code{cvs -commit} are used, @file{editinfo} will not be consulted. -There is no good workaround for this; use -@file{verifymsg} instead. - -@menu -* editinfo example:: Editinfo example -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node editinfo example -@appendixsubsubsec Editinfo example - -The following is a little silly example of a -@file{editinfo} file, together with the corresponding -@file{rcsinfo} file, the log message template and an -editor script. We begin with the log message template. -We want to always record a bug-id number on the first -line of the log message. The rest of log message is -free text. The following template is found in the file -@file{/usr/cvssupport/tc.template}. - -@example -BugId: -@end example - -The script @file{/usr/cvssupport/bugid.edit} is used to -edit the log message. - -@example -#!/bin/sh -# -# bugid.edit filename -# -# Call $EDITOR on FILENAME, and verify that the -# resulting file contains a valid bugid on the first -# line. -if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi -if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi -$CVSEDITOR $1 -until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1 -do echo -n "No BugId found. Edit again? ([y]/n)" - read ans - case $@{ans@} in - n*) exit 1;; - esac - $CVSEDITOR $1 -done -@end example - -The @file{editinfo} file contains this line: - -@example -^tc /usr/cvssupport/bugid.edit -@end example - -The @file{rcsinfo} file contains this line: - -@example -^tc /usr/cvssupport/tc.template -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node loginfo -@appendixsubsec Loginfo -@cindex loginfo (admin file) -@cindex Storing log messages -@cindex Mailing log messages -@cindex Distributing log messages -@cindex Log messages - -@c "cvs commit" is not quite right. What we -@c mean is "when the repository gets changed" which -@c also includes "cvs import" and "cvs add" on a directory. -The @file{loginfo} file is used to control where -@samp{cvs commit} log information is sent. The first -entry on a line is a regular expression which is tested -against the directory that the change is being made to, -relative to the @code{$CVSROOT}. If a match is found, then -the remainder of the line is a filter program that -should expect log information on its standard input. -Note that the filter program @strong{must} read @strong{all} -of the log information or @sc{cvs} may fail with a broken pipe signal. - -If the repository name does not match any of the -regular expressions in this file, the @samp{DEFAULT} -line is used, if it is specified. - -All occurrences of the name @samp{ALL} appearing as a -regular expression are used in addition to the first -matching regular expression or @samp{DEFAULT}. - -The first matching regular expression is used. - -@xref{commit files}, for a description of the syntax of -the @file{loginfo} file. - -The user may specify a format string as -part of the filter. The string is composed of a -@samp{%} followed by a space, or followed by a single -format character, or followed by a set of format -characters surrounded by @samp{@{} and @samp{@}} as -separators. The format characters are: - -@table @t -@item s -file name -@item V -old version number (pre-checkin) -@item v -new version number (post-checkin) -@end table - -All other characters that appear in a format string -expand to an empty field (commas separating fields are -still provided). - -For example, some valid format strings are @samp{%}, -@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. - -The output will be a space separated string of tokens enclosed in -quotation marks (@t{"}). -Any embedded dollar signs (@t{$}), backticks (@t{`}), -backslashes (@t{\}), or quotation marks will be preceded -by a backslash (this allows the shell to correctly parse it -as a single string, reguardless of the characters it contains). -For backwards compatibility, the first -token will be the repository subdirectory. The rest of the -tokens will be comma-delimited lists of the information -requested in the format string. For example, if -@samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%@{sVv@}} -is the format string, and three files (@t{ChangeLog}, -@t{Makefile}, @t{foo.c}) were modified, the output -might be: - -@example -"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13" -@end example - -As another example, @samp{%@{@}} means that only the -name of the repository will be generated. - -Note: when @sc{cvs} is accessing a remote repository, -@file{loginfo} will be run on the @emph{remote} -(i.e., server) side, not the client side (@pxref{Remote -repositories}). - -@menu -* loginfo example:: Loginfo example -* Keeping a checked out copy:: Updating a tree on every checkin -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node loginfo example -@appendixsubsubsec Loginfo example - -The following @file{loginfo} file, together with the -tiny shell-script below, appends all log messages -to the file @file{$CVSROOT/CVSROOT/commitlog}, -and any commits to the administrative files (inside -the @file{CVSROOT} directory) are also logged in -@file{/usr/adm/cvsroot-log}. -Commits to the @file{prog1} directory are mailed to @t{ceder}. - -@c FIXME: is it a CVS feature or bug that only the -@c first matching line is used? It is documented -@c above, but is it useful? For example, if we wanted -@c to run both "cvs-log" and "Mail" for the CVSROOT -@c directory, it is kind of awkward if -@c only the first matching line is used. -@example -ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER -^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log -^prog1 Mail -s %s ceder -@end example - -The shell-script @file{/usr/local/bin/cvs-log} looks -like this: - -@example -#!/bin/sh -(echo "------------------------------------------------------"; - echo -n $2" "; - date; - echo; - cat) >> $1 -@end example - -@node Keeping a checked out copy -@appendixsubsubsec Keeping a checked out copy - -@c What other index entries? It seems like -@c people might want to use a lot of different -@c words for this functionality. -@cindex Keeping a checked out copy -@cindex Checked out copy, keeping -@cindex Web pages, maintaining with CVS - -It is often useful to maintain a directory tree which -contains files which correspond to the latest version -in the repository. For example, other developers might -want to refer to the latest sources without having to -check them out, or you might be maintaining a web site -with @sc{cvs} and want every checkin to cause the files -used by the web server to be updated. -@c Can we offer more details on the web example? Or -@c point the user at how to figure it out? This text -@c strikes me as sufficient for someone who already has -@c some idea of what we mean but not enough for the naive -@c user/sysadmin to understand it and set it up. - -The way to do this is by having loginfo invoke -@code{cvs update}. Doing so in the naive way will -cause a problem with locks, so the @code{cvs update} -must be run in the background. -@c Should we try to describe the problem with locks? -@c It seems like a digression for someone who just -@c wants to know how to make it work. -@c Another choice which might work for a single file -@c is to use "cvs -n update -p" which doesn't take -@c out locks (I think) but I don't see many advantages -@c of that and we might as well document something which -@c works for multiple files. -Here is an example for unix (this should all be on one line): - -@example -^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs; - cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 -@end example - -This will cause checkins to repository directories -starting with @code{cyclic-pages} to update the checked -out tree in @file{/u/www/local-docs}. -@c More info on some of the details? The "sleep 2" is -@c so if we are lucky the lock will be gone by the time -@c we start and we can wait 2 seconds instead of 30. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node rcsinfo -@appendixsec Rcsinfo -@cindex rcsinfo (admin file) -@cindex Form for log message -@cindex Log message template -@cindex Template for log message - -The @file{rcsinfo} file can be used to specify a form to -edit when filling out the commit log. The -@file{rcsinfo} file has a syntax similar to the -@file{verifymsg}, @file{commitinfo} and @file{loginfo} -files. @xref{syntax}. Unlike the other files the second -part is @emph{not} a command-line template. Instead, -the part after the regular expression should be a full pathname to -a file containing the log message template. - -If the repository name does not match any of the -regular expressions in this file, the @samp{DEFAULT} -line is used, if it is specified. - -All occurrences of the name @samp{ALL} appearing as a -regular expression are used in addition to the first -matching regular expression or @samp{DEFAULT}. - -@c FIXME: should be offering advice, somewhere around -@c here, about where to put the template file. The -@c verifymsg example uses /usr/cvssupport but doesn't -@c say anything about what that directory is for or -@c whether it is hardwired into CVS or who creates -@c it or anything. In particular we should say -@c how to version control the template file. A -@c probably better answer than the /usr/cvssupport -@c stuff is to use checkoutlist (with xref to the -@c checkoutlist doc). -@c Also I am starting to see a connection between -@c this and the Keeping a checked out copy node. -@c Probably want to say something about that. -The log message template will be used as a default log -message. If you specify a log message with @samp{cvs -commit -m @var{message}} or @samp{cvs commit -f -@var{file}} that log message will override the -template. - -@xref{verifymsg}, for an example @file{rcsinfo} -file. - -When @sc{cvs} is accessing a remote repository, -the contents of @file{rcsinfo} at the time a directory -is first checked out will specify a template which does -not then change. If you edit @file{rcsinfo} or its -templates, you may need to check out a new working -directory. -@c Would be nice to fix CVS so this isn't needed. For -@c example, a mechanism analogous to CVS/Entries, where -@c the client keeps track of what version of the template -@c it has. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node taginfo -@appendixsec Taginfo -@cindex taginfo (admin file) -@cindex Tags, logging -@cindex Tags, verifying -The @file{taginfo} file defines programs to execute -when someone executes a @code{tag} or @code{rtag} -command. The @file{taginfo} file has the standard form -for trigger scripts (@pxref{Trigger Scripts}), -where each line is a regular expression -followed by a command to execute (@pxref{syntax}). The arguments passed -to the command are, in order, the @var{tagname}, -@var{operation} (@code{add} for @code{tag}, -@code{mov} for @code{tag -F}, and @code{del} for -@code{tag -d}), @var{repository}, and any remaining are -pairs of @var{filename} @var{revision}. A non-zero -exit of the filter program will cause the tag to be -aborted. - -Here is an example of using the @file{taginfo} file -to log @code{tag} and @code{rtag} -commands. In the @file{taginfo} file put: - -@example -ALL /usr/local/cvsroot/CVSROOT/loggit -@end example - -@noindent -Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the -following script: - -@example -#!/bin/sh -echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node cvsignore -@appendixsec Ignoring files via cvsignore -@cindex cvsignore (admin file), global -@cindex Global cvsignore -@cindex Ignoring files -@c -- This chapter should maybe be moved to the -@c tutorial part of the manual? - -There are certain file names that frequently occur -inside your working copy, but that you don't want to -put under @sc{cvs} control. Examples are all the object -files that you get while you compile your sources. -Normally, when you run @samp{cvs update}, it prints a -line for each file it encounters that it doesn't know -about (@pxref{update output}). - -@sc{cvs} has a list of files (or sh(1) file name patterns) -that it should ignore while running @code{update}, -@code{import} and @code{release}. -@c -- Are those the only three commands affected? -This list is constructed in the following way. - -@itemize @bullet -@item -The list is initialized to include certain file name -patterns: names associated with @sc{cvs} -administration, or with other common source control -systems; common names for patch files, object files, -archive files, and editor backup files; and other names -that are usually artifacts of assorted utilities. -Currently, the default list of ignored file name -patterns is: - -@cindex Ignored files -@cindex Automatically ignored files -@example - RCS SCCS CVS CVS.adm - RCSLOG cvslog.* - tags TAGS - .make.state .nse_depinfo - *~ #* .#* ,* _$* *$ - *.old *.bak *.BAK *.orig *.rej .del-* - *.a *.olb *.o *.obj *.so *.exe - *.Z *.elc *.ln - core -@end example - -@item -The per-repository list in -@file{$CVSROOT/CVSROOT/cvsignore} is appended to -the list, if that file exists. - -@item -The per-user list in @file{.cvsignore} in your home -directory is appended to the list, if it exists. - -@item -Any entries in the environment variable -@code{$CVSIGNORE} is appended to the list. - -@item -Any @samp{-I} options given to @sc{cvs} is appended. - -@item -As @sc{cvs} traverses through your directories, the contents -of any @file{.cvsignore} will be appended to the list. -The patterns found in @file{.cvsignore} are only valid -for the directory that contains them, not for -any sub-directories. -@end itemize - -In any of the 5 places listed above, a single -exclamation mark (@samp{!}) clears the ignore list. -This can be used if you want to store any file which -normally is ignored by @sc{cvs}. - -Specifying @samp{-I !} to @code{cvs import} will import -everything, which is generally what you want to do if -you are importing files from a pristine distribution or -any other source which is known to not contain any -extraneous files. However, looking at the rules above -you will see there is a fly in the ointment; if the -distribution contains any @file{.cvsignore} files, then -the patterns from those files will be processed even if -@samp{-I !} is specified. The only workaround is to -remove the @file{.cvsignore} files in order to do the -import. Because this is awkward, in the future -@samp{-I !} might be modified to override -@file{.cvsignore} files in each directory. - -Note that the syntax of the ignore files consists of a -series of lines, each of which contains a space -separated list of filenames. This offers no clean way -to specify filenames which contain spaces, but you can -use a workaround like @file{foo?bar} to match a file -named @file{foo bar} (it also matches @file{fooxbar} -and the like). Also note that there is currently no -way to specify comments. -@c FIXCVS? I don't _like_ this syntax at all, but -@c changing it raises all the usual compatibility -@c issues and I'm also not sure what to change it to. - -@node checkoutlist -@appendixsec The checkoutlist file -@cindex checkoutlist - -It may be helpful to use @sc{cvs} to maintain your own -files in the @file{CVSROOT} directory. For example, -suppose that you have a script @file{logcommit.pl} -which you run by including the following line in the -@file{commitinfo} administrative file: - -@example -ALL $CVSROOT/CVSROOT/logcommit.pl -@end example - -To maintain @file{logcommit.pl} with @sc{cvs} you would -add the following line to the @file{checkoutlist} -administrative file: - -@example -logcommit.pl -@end example - -The format of @file{checkoutlist} is one line for each -file that you want to maintain using @sc{cvs}, giving -the name of the file, followed optionally by more whitespace -and any error message that should print if the file cannot be -checked out into CVSROOT after a commit: - -@example -logcommit.pl Could not update CVSROOT/logcommit.pl. -@end example - -After setting up @file{checkoutlist} in this fashion, -the files listed there will function just like -@sc{cvs}'s built-in administrative files. For example, -when checking in one of the files you should get a -message such as: - -@example -cvs commit: Rebuilding administrative file database -@end example - -@noindent -and the checked out copy in the @file{CVSROOT} -directory should be updated. - -Note that listing @file{passwd} (@pxref{Password -authentication server}) in @file{checkoutlist} is not -recommended for security reasons. - -For information about keeping a checkout out copy in a -more general context than the one provided by -@file{checkoutlist}, see @ref{Keeping a checked out -copy}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node history file -@appendixsec The history file -@cindex History file -@cindex Log information, saving - -The file @file{$CVSROOT/CVSROOT/history} is used -to log information for the @code{history} command -(@pxref{history}). This file must be created to turn -on logging. This is done automatically if the -@code{cvs init} command is used to set up the -repository (@pxref{Creating a repository}). - -The file format of the @file{history} file is -documented only in comments in the @sc{cvs} source -code, but generally programs should use the @code{cvs -history} command to access it anyway, in case the -format changes with future releases of @sc{cvs}. - -@node Variables -@appendixsec Expansions in administrative files -@cindex Internal variables -@cindex Variables - -Sometimes in writing an administrative file, you might -want the file to be able to know various things based -on environment @sc{cvs} is running in. There are -several mechanisms to do that. - -To find the home directory of the user running @sc{cvs} -(from the @code{HOME} environment variable), use -@samp{~} followed by @samp{/} or the end of the line. -Likewise for the home directory of @var{user}, use -@samp{~@var{user}}. These variables are expanded on -the server machine, and don't get any reasonable -expansion if pserver (@pxref{Password authenticated}) -is in use; therefore user variables (see below) may be -a better choice to customize behavior based on the user -running @sc{cvs}. -@c Based on these limitations, should we deprecate ~? -@c What is it good for? Are people using it? - -One may want to know about various pieces of -information internal to @sc{cvs}. A @sc{cvs} internal -variable has the syntax @code{$@{@var{variable}@}}, -where @var{variable} starts with a letter and consists -of alphanumeric characters and @samp{_}. If the -character following @var{variable} is a -non-alphanumeric character other than @samp{_}, the -@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} -internal variables are: - -@table @code -@item CVSROOT -@cindex CVSROOT, internal variable -This is the absolute path to the current @sc{cvs} root directory. -@xref{Repository}, for a description of the various -ways to specify this, but note that the internal -variable contains just the directory and not any -of the access method information. - -@item RCSBIN -@cindex RCSBIN, internal variable -In @sc{cvs} 1.9.18 and older, this specified the -directory where @sc{cvs} was looking for @sc{rcs} -programs. Because @sc{cvs} no longer runs @sc{rcs} -programs, specifying this internal variable is now an -error. - -@item CVSEDITOR -@cindex CVSEDITOR, internal variable -@itemx EDITOR -@cindex EDITOR, internal variable -@itemx VISUAL -@cindex VISUAL, internal variable -These all expand to the same value, which is the editor -that @sc{cvs} is using. @xref{Global options}, for how -to specify this. - -@item USER -@cindex USER, internal variable -Username of the user running @sc{cvs} (on the @sc{cvs} -server machine). -When using pserver, this is the user specified in the repository -specification which need not be the same as the username the -server is running as (@pxref{Password authentication server}). -Do not confuse this with the environment variable of the same name. -@end table - -If you want to pass a value to the administrative files -which the user who is running @sc{cvs} can specify, -use a user variable. -@cindex User variables -To expand a user variable, the -administrative file contains -@code{$@{=@var{variable}@}}. To set a user variable, -specify the global option @samp{-s} to @sc{cvs}, with -argument @code{@var{variable}=@var{value}}. It may be -particularly useful to specify this option via -@file{.cvsrc} (@pxref{~/.cvsrc}). - -For example, if you want the administrative file to -refer to a test directory you might create a user -variable @code{TESTDIR}. Then if @sc{cvs} is invoked -as - -@example -cvs -s TESTDIR=/work/local/tests -@end example - -@noindent -and the -administrative file contains @code{sh -$@{=TESTDIR@}/runtests}, then that string is expanded -to @code{sh /work/local/tests/runtests}. - -All other strings containing @samp{$} are reserved; -there is no way to quote a @samp{$} character so that -@samp{$} represents itself. - -Environment variables passed to administrative files are: - -@table @code -@cindex environment variables, passed to administrative files - -@item CVS_USER -@cindex CVS_USER, environment variable -The @sc{cvs}-specific username provided by the user, if it -can be provided (currently just for the pserver access -method), and to the empty string otherwise. (@code{CVS_USER} -and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} -is used to map @sc{cvs} usernames to system usernames.) - -@item LOGNAME -@cindex LOGNAME, environment variable -The username of the system user. - -@item USER -@cindex USER, environment variable -Same as @code{LOGNAME}. -Do not confuse this with the internal variable of the same name. -@end table - -@node config -@appendixsec The CVSROOT/config configuration file - -@cindex config, in CVSROOT -@cindex CVSROOT/config - -The administrative file @file{config} contains various -miscellaneous settings which affect the behavior of -@sc{cvs}. The syntax is slightly different from the -other administrative files. Variables are not -expanded. Lines which start with @samp{#} are -considered comments. -@c FIXME: where do we define comments for the other -@c administrative files. -Other lines consist of a keyword, @samp{=}, and a -value. Note that this syntax is very strict. -Extraneous spaces or tabs are not permitted. -@c See comments in parseinfo.c:parse_config for more -@c discussion of this strictness. - -Currently defined keywords are: - -@table @code -@cindex RCSBIN, in CVSROOT/config -@item RCSBIN=@var{bindir} -For @sc{cvs} 1.9.12 through 1.9.18, this setting told -@sc{cvs} to look for @sc{rcs} programs in the -@var{bindir} directory. Current versions of @sc{cvs} -do not run @sc{rcs} programs; for compatibility this -setting is accepted, but it does nothing. - -@cindex SystemAuth, in CVSROOT/config -@item SystemAuth=@var{value} -If @var{value} is @samp{yes}, then pserver should check -for users in the system's user database if not found in -@file{CVSROOT/passwd}. If it is @samp{no}, then all -pserver users must exist in @file{CVSROOT/passwd}. -The default is @samp{yes}. For more on pserver, see -@ref{Password authenticated}. - -@ignore -@cindex PreservePermissions, in CVSROOT/config -@item PreservePermissions=@var{value} -Enable support for saving special device files, -symbolic links, file permissions and ownerships in the -repository. The default value is @samp{no}. -@xref{Special Files}, for the full implications of using -this keyword. -@end ignore - -@cindex TopLevelAdmin, in CVSROOT/config -@item TopLevelAdmin=@var{value} -Modify the @samp{checkout} command to create a -@samp{CVS} directory at the top level of the new -working directory, in addition to @samp{CVS} -directories created within checked-out directories. -The default value is @samp{no}. - -This option is useful if you find yourself performing -many commands at the top level of your working -directory, rather than in one of the checked out -subdirectories. The @file{CVS} directory created there -will mean you don't have to specify @code{CVSROOT} for -each command. It also provides a place for the -@file{CVS/Template} file (@pxref{Working directory -storage}). - -@cindex LockDir, in CVSROOT/config -@item LockDir=@var{directory} -Put @sc{cvs} lock files in @var{directory} rather than -directly in the repository. This is useful if you want -to let users read from the repository while giving them -write access only to @var{directory}, not to the -repository. -It can also be used to put the locks on a very fast -in-memory file system to speed up locking and unlocking -the repository. -You need to create @var{directory}, but -@sc{cvs} will create subdirectories of @var{directory} as it -needs them. For information on @sc{cvs} locks, see -@ref{Concurrency}. - -@c Mention this in Compatibility section? -Before enabling the LockDir option, make sure that you -have tracked down and removed any copies of @sc{cvs} 1.9 or -older. Such versions neither support LockDir, nor will -give an error indicating that they don't support it. -The result, if this is allowed to happen, is that some -@sc{cvs} users will put the locks one place, and others will -put them another place, and therefore the repository -could become corrupted. @sc{cvs} 1.10 does not support -LockDir but it will print a warning if run on a -repository with LockDir enabled. - -@cindex LogHistory, in CVSROOT/config -@item LogHistory=@var{value} -Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). -Default of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log -all transactions. Any subset of the default is -legal. (For example, to only log transactions that modify the -@file{*,v} files, use @samp{LogHistory=TMAR}.) - -@cindex RereadLogAfterVerify, in CVSROOT/config -@cindex @file{verifymsg}, changing the log message -@item RereadLogAfterVerify=@var{value} -Modify the @samp{commit} command such that CVS will reread the -log message after running the program specified by @file{verifymsg}. -@var{value} may be one of @samp{yes} or @samp{always}, indicating that -the log message should always be reread; @samp{no} -or @samp{never}, indicating that it should never be -reread; or @var{value} may be @samp{stat}, indicating -that the file should be checked with the file system -@samp{stat()} function to see if it has changed (see warning below) -before rereading. The default value is @samp{always}. - -@strong{The `stat' mode can cause CVS to pause for up to -one extra second per directory committed. This can be less IO and -CPU intensive but is not recommended for use with large repositories} - -@xref{verifymsg}, for more information on how verifymsg -may be used. - -@cindex IgnoreUnknownConfigKeys, in CVSROOT/config -@item IgnoreUnknownConfigKeys=@var{value} -If @var{value} is @samp{yes}, then @sc{cvs} should -ignore any keywords in @file{CVSROOT/config} which it -does not recognize. This option is intended primarily -for transitions between versions of @sc{cvs} which -support more configuration options in an environment -where a read-only mirror of the current @sc{cvs} server -may be maintained by someone else who is not yet ready -to upgrade to the same version. It is recommended that -this option be used only for a short time so that -problems with the @file{CVSROOT/config} file will be -found quickly. The default is @samp{no}. -@end table - -@c --------------------------------------------------------------------- -@node Environment variables -@appendix All environment variables which affect CVS -@cindex Environment variables -@cindex Reference manual for variables - -This is a complete list of all environment variables -that affect @sc{cvs}. - -@table @code -@cindex CVSIGNORE, environment variable -@item $CVSIGNORE -A whitespace-separated list of file name patterns that -@sc{cvs} should ignore. @xref{cvsignore}. - -@cindex CVSWRAPPERS, environment variable -@item $CVSWRAPPERS -A whitespace-separated list of file name patterns that -@sc{cvs} should treat as wrappers. @xref{Wrappers}. - -@cindex CVSREAD, environment variable -@cindex Read-only files, and CVSREAD -@item $CVSREAD -If this is set, @code{checkout} and @code{update} will -try hard to make the files in your working directory -read-only. When this is not set, the default behavior -is to permit modification of your working files. - -@item $CVSUMASK -Controls permissions of files in the repository. See -@ref{File permissions}. - -@item $CVSROOT -Should contain the full pathname to the root of the @sc{cvs} -source repository (where the @sc{rcs} files are -kept). This information must be available to @sc{cvs} for -most commands to execute; if @code{$CVSROOT} is not set, -or if you wish to override it for one invocation, you -can supply it on the command line: @samp{cvs -d cvsroot -cvs_command@dots{}} Once you have checked out a working -directory, @sc{cvs} stores the appropriate root (in -the file @file{CVS/Root}), so normally you only need to -worry about this when initially checking out a working -directory. - -@item $CVSEDITOR -@cindex CVSEDITOR, environment variable -@itemx $EDITOR -@cindex EDITOR, environment variable -@itemx $VISUAL -@cindex VISUAL, environment variable -Specifies the program to use for recording log messages -during commit. @code{$CVSEDITOR} overrides -@code{$EDITOR}, which overrides @code{$VISUAL}. -See @ref{Committing your changes} for more or -@ref{Global options} for alternative ways of specifying a -log editor. - -@cindex PATH, environment variable -@item $PATH -If @code{$RCSBIN} is not set, and no path is compiled -into @sc{cvs}, it will use @code{$PATH} to try to find all -programs it uses. - -@cindex HOME, environment variable -@item $HOME -@cindex HOMEPATH, environment variable -@item $HOMEPATH -@cindex HOMEDRIVE, environment variable -@item $HOMEDRIVE -Used to locate the directory where the @file{.cvsrc} -file, and other such files, are searched. On Unix, @sc{cvs} -just checks for @code{HOME}. On Windows NT, the system will -set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, -for example to @file{\joe}. On Windows 95, you'll -probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. -@c We are being vague about whether HOME works on -@c Windows; see long comment in windows-NT/filesubr.c. - -@cindex CVS_RSH, environment variable -@item $CVS_RSH -Specifies the external program which @sc{cvs} connects with, -when @code{:ext:} access method is specified. -@pxref{Connecting via rsh}. - -@cindex CVS_SSH, environment variable -@item $CVS_SSH -Specifies the external program which @sc{cvs} connects with, -when @code{:extssh:} access method is specified. -@pxref{Connecting via rsh}. - -@item $CVS_SERVER -Used in client-server mode when accessing a remote -repository using @sc{rsh}. It specifies the name of -the program to start on the server side (and any -necessary arguments) when accessing a remote repository -using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. -The default value for @code{:ext:} and @code{:server:} is @code{cvs}; -the default value for @code{:fork:} is the name used to run the client. -@pxref{Connecting via rsh} - -@item $CVS_PASSFILE -Used in client-server mode when accessing the @code{cvs -login server}. Default value is @file{$HOME/.cvspass}. -@pxref{Password authentication client} - -@item $CVS_CLIENT_PORT -Used in client-server mode to set the port to use when accessing the server -via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol -if the port is not specified in the CVSROOT. -@pxref{Remote repositories} - -@cindex CVS_RCMD_PORT, environment variable -@item $CVS_RCMD_PORT -Used in client-server mode. If set, specifies the port -number to be used when accessing the @sc{rcmd} demon on -the server side. (Currently not used for Unix clients). - -@cindex CVS_CLIENT_LOG, environment variable -@item $CVS_CLIENT_LOG -Used for debugging only in client-server -mode. If set, everything sent to the server is logged -into @file{@code{$CVS_CLIENT_LOG}.in} and everything -sent from the server is logged into -@file{@code{$CVS_CLIENT_LOG}.out}. - -@cindex CVS_SERVER_SLEEP, environment variable -@item $CVS_SERVER_SLEEP -Used only for debugging the server side in -client-server mode. If set, delays the start of the -server child process the specified amount of -seconds so that you can attach to it with a debugger. - -@cindex CVS_IGNORE_REMOTE_ROOT, environment variable -@item $CVS_IGNORE_REMOTE_ROOT -For @sc{cvs} 1.10 and older, setting this variable -prevents @sc{cvs} from overwriting the @file{CVS/Root} -file when the @samp{-d} global option is specified. -Later versions of @sc{cvs} do not rewrite -@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no -effect. - -@cindex COMSPEC, environment variable -@item $COMSPEC -Used under OS/2 only. It specifies the name of the -command interpreter and defaults to @sc{cmd.exe}. - -@cindex TMPDIR, environment variable -@item $TMPDIR -@cindex TMP, environment variable -@itemx $TMP -@cindex TEMP, environment variable -@itemx $TEMP -@cindex Temporary files, location of -@c This is quite nuts. We don't talk about tempnam -@c or mkstemp which we sometimes use. The discussion -@c of "Global options" is semi-incoherent. -@c I'm not even sure those are the only inaccuracies. -@c Furthermore, the conventions are -@c pretty crazy and they should be simplified. -Directory in which temporary files are located. -The @sc{cvs} server uses -@code{TMPDIR}. @xref{Global options}, for a -description of how to specify this. -Some parts of @sc{cvs} will always use @file{/tmp} (via -the @code{tmpnam} function provided by the system). - -On Windows NT, @code{TMP} is used (via the @code{_tempnam} -function provided by the system). - -The @code{patch} program which is used by the @sc{cvs} -client uses @code{TMPDIR}, and if it is not set, uses -@file{/tmp} (at least with GNU patch 2.1). Note that -if your server and client are both running @sc{cvs} -1.9.10 or later, @sc{cvs} will not invoke an external -@code{patch} program. -@end table - -@node Compatibility -@appendix Compatibility between CVS Versions - -@cindex CVS, versions of -@cindex Versions, of CVS -@cindex Compatibility, between CVS versions -@c We don't mention versions older than CVS 1.3 -@c on the theory that it would clutter it up for the vast -@c majority of people, who don't have anything that old. -@c -The repository format is compatible going back to -@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if -you have copies of @sc{cvs} 1.6 or older and you want -to use the optional developer communication features. -@c If you "cvs rm" and commit using 1.3, then you'll -@c want to run "rcs -sdead <file,v>" on each of the -@c files in the Attic if you then want 1.5 and -@c later to recognize those files as dead (I think the -@c symptom if this is not done is that files reappear -@c in joins). (Wait: the above will work but really to -@c be strictly correct we should suggest checking -@c in a new revision rather than just changing the -@c state of the head revision, shouldn't we?). -@c The old convert.sh script was for this, but it never -@c did get updated to reflect use of the RCS "dead" -@c state. -@c Note: this is tricky to document without confusing -@c people--need to carefully say what CVS version we -@c are talking about and keep in mind the distinction -@c between a -@c repository created with 1.3 and on which one now -@c uses 1.5+, and a repository on which one wants to -@c use both versions side by side (e.g. during a -@c transition period). -@c Wait, can't CVS just detect the case in which a file -@c is in the Attic but the head revision is not dead? -@c Not sure whether this should produce a warning or -@c something, and probably needs further thought, but -@c it would appear that the situation can be detected. -@c -@c We might want to separate out the 1.3 compatibility -@c section (for repository & working directory) from the -@c rest--that might help avoid confusing people who -@c are upgrading (for example) from 1.6 to 1.8. -@c -@c A minor incompatibility is if a current version of CVS -@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will -@c see this as if there is no tag. Seems to me this is -@c too obscure to mention. - -The working directory format is compatible going back -to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 -and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on -a working directory checked out with @sc{cvs} 1.3, -@sc{cvs} will convert it, but to go back to @sc{cvs} -1.3 you need to check out a new working directory with -@sc{cvs} 1.3. - -The remote protocol is interoperable going back to @sc{cvs} 1.5, but no -further (1.5 was the first official release with the remote protocol, -but some older versions might still be floating around). In many -cases you need to upgrade both the client and the server to take -advantage of new features and bug fixes, however. - -@c Perhaps should be saying something here about the -@c "D" lines in Entries (written by CVS 1.9; 1.8 and -@c older don't use them). These are supposed to be -@c compatible in both directions, but I'm not sure -@c they quite are 100%. One common gripe is if you -@c "rm -r" a directory and 1.9 gets confused, as it -@c still sees it in Entries. That one is fixed in -@c (say) 1.9.6. Someone else reported problems with -@c starting with a directory which was checked out with -@c an old version, and then using a new version, and -@c some "D" lines appeared, but not for every -@c directory, causing some directories to be skipped. -@c They weren't sure how to reproduce this, though. - -@c --------------------------------------------------------------------- -@node Troubleshooting -@appendix Troubleshooting - -If you are having trouble with @sc{cvs}, this appendix -may help. If there is a particular error message which -you are seeing, then you can look up the message -alphabetically. If not, you can look through the -section on other problems to see if your problem is -mentioned there. - -@menu -* Error messages:: Partial list of CVS errors -* Connection:: Trouble making a connection to a CVS server -* Other problems:: Problems not readily listed by error message -@end menu - -@ignore -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@c @node Bad administrative files -@appendixsec Bad administrative files - -@c -- Give hints on how to fix them -@end ignore - -@node Error messages -@appendixsec Partial list of error messages - -Here is a partial list of error messages that you may -see from @sc{cvs}. It is not a complete list---@sc{cvs} -is capable of printing many, many error messages, often -with parts of them supplied by the operating system, -but the intention is to list the common and/or -potentially confusing error messages. - -The messages are alphabetical, but introductory text -such as @samp{cvs update: } is not considered in -ordering them. - -In some cases the list includes messages printed by old -versions of @sc{cvs} (partly because users may not be -sure which version of @sc{cvs} they are using at any -particular moment). -@c If we want to start retiring messages, perhaps we -@c should pick a cutoff version (for example, no more -@c messages which are specific to versions before 1.9) -@c and then move the old messages to an "old messages" -@c node rather than deleting them completely. - -@table @code -@c FIXME: What is the correct way to format a multiline -@c error message here? Maybe @table is the wrong -@c choice? Texinfo gurus? -@item @var{file}:@var{line}: Assertion '@var{text}' failed -The exact format of this message may vary depending on -your system. It indicates a bug in @sc{cvs}, which can -be handled as described in @ref{BUGS}. - -@item cvs @var{command}: authorization failed: server @var{host} rejected access -This is a generic response when trying to connect to a -pserver server which chooses not to provide a -specific reason for denying authorization. Check that -the username and password specified are correct and -that the @code{CVSROOT} specified is allowed by @samp{--allow-root} -in @file{inetd.conf}. See @ref{Password authenticated}. - -@item cvs @var{command}: conflict: removed @var{file} was modified by second party -This message indicates that you removed a file, and -someone else modified it. To resolve the conflict, -first run @samp{cvs add @var{file}}. If desired, look -at the other party's modification to decide whether you -still want to remove it. If you don't want to remove -it, stop here. If you do want to remove it, proceed -with @samp{cvs remove @var{file}} and commit your -removal. -@c Tests conflicts2-142b* in sanity.sh test for this. - -@item cannot change permissions on temporary directory -@example -Operation not permitted -@end example -This message has been happening in a non-reproducible, -occasional way when we run the client/server testsuite, -both on Red Hat Linux 3.0.3 and 4.1. We haven't been -able to figure out what causes it, nor is it known -whether it is specific to Linux (or even to this -particular machine!). If the problem does occur on -other unices, @samp{Operation not permitted} would be -likely to read @samp{Not owner} or whatever the system -in question uses for the unix @code{EPERM} error. If -you have any information to add, please let us know as -described in @ref{BUGS}. If you experience this error -while using @sc{cvs}, retrying the operation which -produced it should work fine. -@c This has been seen in a variety of tests, including -@c multibranch-2, multibranch-5, and basic1-24-rm-rm, -@c so it doesn't seem particularly specific to any one -@c test. - -@item cvs [server aborted]: Cannot check out files into the repository itself -The obvious cause for this message (especially for -non-client/server @sc{cvs}) is that the @sc{cvs} root -is, for example, @file{/usr/local/cvsroot} and you try -to check out files when you are in a subdirectory, such -as @file{/usr/local/cvsroot/test}. However, there is a -more subtle cause, which is that the temporary -directory on the server is set to a subdirectory of the -root (which is also not allowed). If this is the -problem, set the temporary directory to somewhere else, -for example @file{/var/tmp}; see @code{TMPDIR} in -@ref{Environment variables}, for how to set the -temporary directory. - -@item cannot commit files as 'root' -See @samp{'root' is not allowed to commit files}. - -@c For one example see basica-1a10 in the testsuite -@c For another example, "cvs co ." on NT; see comment -@c at windows-NT/filesubr.c (expand_wild). -@c For another example, "cvs co foo/bar" where foo exists. -@item cannot open CVS/Entries for reading: No such file or directory -This generally indicates a @sc{cvs} internal error, and -can be handled as with other @sc{cvs} bugs -(@pxref{BUGS}). Usually there is a workaround---the -exact nature of which would depend on the situation but -which hopefully could be figured out. - -@c This is more obscure than it might sound; it only -@c happens if you run "cvs init" from a directory which -@c contains a CVS/Root file at the start. -@item cvs [init aborted]: cannot open CVS/Root: No such file or directory -This message is harmless. Provided it is not -accompanied by other errors, the operation has -completed successfully. This message should not occur -with current versions of @sc{cvs}, but it is documented -here for the benefit of @sc{cvs} 1.9 and older. - -@item cvs server: cannot open /root/.cvsignore: Permission denied -@itemx cvs [server aborted]: can't chdir(/root): Permission denied -See @ref{Connection}. - -@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument -This message has been reported as intermittently -happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is -unknown; if you know more about what causes it, let us -know as described in @ref{BUGS}. - -@item cvs [@var{command} aborted]: cannot start server via rcmd -This, unfortunately, is a rather nonspecific error -message which @sc{cvs} 1.9 will print if you are -running the @sc{cvs} client and it is having trouble -connecting to the server. Current versions of @sc{cvs} -should print a much more specific error message. If -you get this message when you didn't mean to run the -client at all, you probably forgot to specify -@code{:local:}, as described in @ref{Repository}. - -@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ -@sc{cvs} 1.9 and older will print this message -when trying to check in a binary file if -@sc{rcs} is not correctly installed. Re-read the -instructions that came with your @sc{rcs} distribution -and the @sc{install} file in the @sc{cvs} -distribution. Alternately, upgrade to a current -version of @sc{cvs}, which checks in files itself -rather than via @sc{rcs}. - -@item cvs checkout: could not check out @var{file} -With @sc{cvs} 1.9, this can mean that the @code{co} program -(part of @sc{rcs}) returned a failure. It should be -preceded by another error message, however it has been -observed without another error message and the cause is -not well-understood. With the current version of @sc{cvs}, -which does not run @code{co}, if this message occurs -without another error message, it is definitely a @sc{cvs} -bug (@pxref{BUGS}). -@c My current suspicion is that the RCS in the rcs (not -@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ -@c CD is bad (remains to be confirmed). -@c There is also a report of something which looks -@c very similar on SGI, Irix 5.2, so I dunno. - -@item cvs [login aborted]: could not find out home directory -This means that you need to set the environment -variables that @sc{cvs} uses to locate your home directory. -See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in -@ref{Environment variables}. - -@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory -@sc{cvs} 1.9 and older will print this message if there was -a problem finding the @code{rcsmerge} program. Make -sure that it is in your @code{PATH}, or upgrade to a -current version of @sc{cvs}, which does not require -an external @code{rcsmerge} program. - -@item cvs [update aborted]: could not patch @var{file}: No such file or directory -This means that there was a problem finding the -@code{patch} program. Make sure that it is in your -@code{PATH}. Note that despite appearances the message -is @emph{not} referring to whether it can find @var{file}. -If both the client and the server are running a current -version of @sc{cvs}, then there is no need for an -external patch program and you should not see this -message. But if either client or server is running -@sc{cvs} 1.9, then you need @code{patch}. - -@item cvs update: could not patch @var{file}; will refetch -This means that for whatever reason the client was -unable to apply a patch that the server sent. The -message is nothing to be concerned about, because -inability to apply the patch only slows things down and -has no effect on what @sc{cvs} does. -@c xref to update output. Or File status? -@c Or some place else that -@c explains this whole "patch"/P/Needs Patch thing? - -@item dying gasps from @var{server} unexpected -There is a known bug in the server for @sc{cvs} 1.9.18 -and older which can cause this. For me, this was -reproducible if I used the @samp{-t} global option. It -was fixed by Andy Piper's 14 Nov 1997 change to -src/filesubr.c, if anyone is curious. -If you see the message, -you probably can just retry the operation which failed, -or if you have discovered information concerning its -cause, please let us know as described in @ref{BUGS}. - -@item end of file from server (consult above messages if any) -The most common cause for this message is if you are -using an external @code{rsh} or @code{ssh} program and it exited with -an error. In this case the @code{rsh} program should -have printed a message, which will appear before the -above message. For more information on setting up a -@sc{cvs} client and server, see @ref{Remote repositories}. - -@item cvs [update aborted]: EOF in key in RCS file @var{file},v -@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v -This means that there is a syntax error in the given -@sc{rcs} file. Note that this might be true even if @sc{rcs} can -read the file OK; @sc{cvs} does more error checking of -errors in the RCS file. That is why you may see this -message when upgrading from @sc{cvs} 1.9 to @sc{cvs} -1.10. The likely cause for the original corruption is -hardware, the operating system, or the like. Of -course, if you find a case in which @sc{cvs} seems to -corrupting the file, by all means report it, -(@pxref{BUGS}). -There are quite a few variations of this error message, -depending on exactly where in the @sc{rcs} file @sc{cvs} -finds the syntax error. - -@cindex mkmodules -@item cvs commit: Executing 'mkmodules' -This means that your repository is set up for a version -of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} -1.8 or later, the above message will be preceded by - -@example -cvs commit: Rebuilding administrative file database -@end example - -If you see both messages, the database is being rebuilt -twice, which is unnecessary but harmless. If you wish -to avoid the duplication, and you have no versions of -@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} -every place it appears in your @code{modules} -file. For more information on the @code{modules} file, -see @ref{modules}. - -@c This message comes from "co", and I believe is -@c possible only with older versions of CVS which call -@c co. The problem with being able to create the bogus -@c RCS file still exists, though (and I think maybe -@c there is a different symptom(s) now). -@c FIXME: Would be nice to have a more exact wording -@c for this message. -@item missing author -Typically this can happen if you created an RCS file -with your username set to empty. @sc{cvs} will, bogusly, -create an illegal RCS file with no value for the author -field. The solution is to make sure your username is -set to a non-empty value and re-create the RCS file. -@c "make sure your username is set" is complicated in -@c and of itself, as there are the environment -@c variables the system login name, &c, and it depends -@c on the version of CVS. - -@item cvs [checkout aborted]: no such tag @var{tag} -This message means that @sc{cvs} isn't familiar with -the tag @var{tag}. Usually this means that you have -mistyped a tag name; however there are (relatively -obscure) cases in which @sc{cvs} will require you to -@c Search sanity.sh for "no such tag" to see some of -@c the relatively obscure cases. -try a few other @sc{cvs} commands involving that tag, -before you find one which will cause @sc{cvs} to update -@cindex CVSROOT/val-tags file, forcing tags into -@cindex val-tags file, forcing tags into -the @file{val-tags} file; see discussion of val-tags in -@ref{File permissions}. You only need to worry about -this once for a given tag; when a tag is listed in -@file{val-tags}, it stays there. Note that using -@samp{-f} to not require tag matches does not override -this check; see @ref{Common options}. - -@item *PANIC* administration files missing -This typically means that there is a directory named -@sc{cvs} but it does not contain the administrative files -which @sc{cvs} puts in a CVS directory. If the problem is -that you created a CVS directory via some mechanism -other than @sc{cvs}, then the answer is simple, use a name -other than @sc{cvs}. If not, it indicates a @sc{cvs} bug -(@pxref{BUGS}). - -@item rcs error: Unknown option: -x,v/ -This message will be followed by a usage message for -@sc{rcs}. It means that you have an old version of -@sc{rcs} (probably supplied with your operating -system), as well as an old version of @sc{cvs}. -@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and -later; current versions of @sc{cvs} do not run @sc{rcs} programs. -@c For more information on installing @sc{cvs}, see -@c (FIXME: where? it depends on whether you are -@c getting binaries or sources or what). -@c The message can also say "ci error" or something -@c instead of "rcs error", I suspect. - -@item cvs [server aborted]: received broken pipe signal -This message can be caused by a loginfo program that fails to -read all of the log information from its standard input. -If you find it happening in any other circumstances, -please let us know as described in @ref{BUGS}. - -@item 'root' is not allowed to commit files -When committing a permanent change, @sc{cvs} makes a log entry of -who committed the change. If you are committing the change logged -in as "root" (not under "su" or other root-priv giving program), -@sc{cvs} cannot determine who is actually making the change. -As such, by default, @sc{cvs} disallows changes to be committed by users -logged in as "root". (You can disable this option by passing the -@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. -On some systems this means editing the appropriate @file{config.h} file -before building @sc{cvs}.) - -@item Terminated with fatal signal 11 -This message usually indicates that @sc{cvs} (the server, if you're -using client/server mode) has run out of (virtual) memory. -Although @sc{cvs} tries to catch the error and issue a more meaningful -message, there are many circumstances where that is not possible. -If you appear to have lots of memory available to the system, -the problem is most likely that you're running into a system-wide -limit on the amount of memory a single process can use or a -similar process-specific limit. -The mechanisms for displaying and setting such limits vary from -system to system, so you'll have to consult an expert for your -particular system if you don't know how to do that. - -@item Too many arguments! -This message is typically printed by the @file{log.pl} -script which is in the @file{contrib} directory in the -@sc{cvs} source distribution. In some versions of -@sc{cvs}, @file{log.pl} has been part of the default -@sc{cvs} installation. The @file{log.pl} script gets -called from the @file{loginfo} administrative file. -Check that the arguments passed in @file{loginfo} match -what your version of @file{log.pl} expects. In -particular, the @file{log.pl} from @sc{cvs} 1.3 and -older expects the log file as an argument whereas the -@file{log.pl} from @sc{cvs} 1.5 and newer expects the -log file to be specified with a @samp{-f} option. Of -course, if you don't need @file{log.pl} you can just -comment it out of @file{loginfo}. - -@item cvs [update aborted]: unexpected EOF reading @var{file},v -See @samp{EOF in key in RCS file}. - -@item cvs [login aborted]: unrecognized auth response from @var{server} -This message typically means that the server is not set -up properly. For example, if @file{inetd.conf} points -to a nonexistent cvs executable. To debug it further, -find the log file which inetd writes -(@file{/var/log/messages} or whatever inetd uses on -your system). For details, see @ref{Connection}, and -@ref{Password authentication server}. - -@item cvs commit: Up-to-date check failed for `@var{file}' -This means that someone else has committed a change to -that file since the last time that you did a @code{cvs -update}. So before proceeding with your @code{cvs -commit} you need to @code{cvs update}. @sc{cvs} will merge -the changes that you made and the changes that the -other person made. If it does not detect any conflicts -it will report @samp{M @var{file}} and you are ready -to @code{cvs commit}. If it detects conflicts it will -print a message saying so, will report @samp{C @var{file}}, -and you need to manually resolve the -conflict. For more details on this process see -@ref{Conflicts example}. - -@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 -@example -Only one of [exEX3] allowed -@end example -This indicates a problem with the installation of -@code{diff3} and @code{rcsmerge}. Specifically -@code{rcsmerge} was compiled to look for GNU diff3, but -it is finding unix diff3 instead. The exact text of -the message will vary depending on the system. The -simplest solution is to upgrade to a current version of -@sc{cvs}, which does not rely on external -@code{rcsmerge} or @code{diff3} programs. - -@item warning: unrecognized response `@var{text}' from cvs server -If @var{text} contains a valid response (such as -@samp{ok}) followed by an extra carriage return -character (on many systems this will cause the second -part of the message to overwrite the first part), then -it probably means that you are using the @samp{:ext:} -access method with a version of rsh, such as most -non-unix rsh versions, which does not by default -provide a transparent data stream. In such cases you -probably want to try @samp{:server:} instead of -@samp{:ext:}. If @var{text} is something else, this -may signify a problem with your @sc{cvs} server. -Double-check your installation against the instructions -for setting up the @sc{cvs} server. -@c FIXCVS: should be printing CR as \r or \015 or some -@c such, probably. - -@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} -This is a normal message, not an error. See -@ref{Concurrency}, for more details. - -@item cvs commit: warning: editor session failed -@cindex Exit status, of editor -This means that the editor which @sc{cvs} is using exits with a nonzero -exit status. Some versions of vi will do this even when there was not -a problem editing the file. If so, point the -@code{CVSEDITOR} environment variable to a small script -such as: - -@example -#!/bin/sh -vi $* -exit 0 -@end example - -@item cvs update: warning: @var{file} was lost -This means that the working copy of @var{file} has been deleted -but it has not been removed from @sc{cvs}. -This is nothing to be concerned about, -the update will just recreate the local file from the repository. -(This is a convenient way to discard local changes to a file: -just delete it and then run @code{cvs update}.) - -@item cvs update: warning: @var{file} is not (any longer) pertinent -This means that the working copy of @var{file} has been deleted, -it has not been removed from @sc{cvs} in the current working directory, -but it has been removed from @sc{cvs} in some other working directory. -This is nothing to be concerned about, -the update would have removed the local file anyway. - -@end table - -@node Connection -@appendixsec Trouble making a connection to a CVS server - -This section concerns what to do if you are having -trouble making a connection to a @sc{cvs} server. If -you are running the @sc{cvs} command line client -running on Windows, first upgrade the client to -@sc{cvs} 1.9.12 or later. The error reporting in -earlier versions provided much less information about -what the problem was. If the client is non-Windows, -@sc{cvs} 1.9 should be fine. - -If the error messages are not sufficient to track down -the problem, the next steps depend largely on which -access method you are using. - -@table @code -@cindex :ext:, troubleshooting -@item :ext: -Try running the rsh program from the command line. For -example: "rsh servername cvs -v" should print @sc{cvs} -version information. If this doesn't work, you need to -fix it before you can worry about @sc{cvs} problems. - -@cindex :server:, troubleshooting -@item :server: -You don't need a command line rsh program to use this -access method, but if you have an rsh program around, -it may be useful as a debugging tool. Follow the -directions given for :ext:. - -@cindex :pserver:, troubleshooting -@item :pserver: -Errors along the lines of "connection refused" typically indicate -that inetd isn't even listening for connections on port 2401 -whereas errors like "connection reset by peer", -"received broken pipe signal", "recv() from server: EOF", -or "end of file from server" -typically indicate that inetd is listening for -connections but is unable to start @sc{cvs} (this is frequently -caused by having an incorrect path in @file{inetd.conf} -or by firewall software rejecting the connection). -"unrecognized auth response" errors are caused by a bad command -line in @file{inetd.conf}, typically an invalid option or forgetting -to put the @samp{pserver} command at the end of the line. -Another less common problem is invisible control characters that -your editor "helpfully" added without you noticing. - -One good debugging tool is to "telnet servername -2401". After connecting, send any text (for example -"foo" followed by return). If @sc{cvs} is working -correctly, it will respond with - -@example -cvs [pserver aborted]: bad auth protocol start: foo -@end example - -If instead you get: - -@example -Usage: cvs [cvs-options] command [command-options-and-arguments] -... -@end example - -@noindent -then you're missing the @samp{pserver} command at the end of the -line in @file{inetd.conf}; check to make sure that the entire command -is on one line and that it's complete. - -Likewise, if you get something like: - -@example -Unknown command: `pserved' - -CVS commands are: - add Add a new file/directory to the repository -... -@end example - -@noindent -then you've misspelled @samp{pserver} in some way. If it isn't -obvious, check for invisible control characters (particularly -carriage returns) in @file{inetd.conf}. - -If it fails to work at all, then make sure inetd is working -right. Change the invocation in @file{inetd.conf} to run the -echo program instead of cvs. For example: - -@example -2401 stream tcp nowait root /bin/echo echo hello -@end example - -After making that change and instructing inetd to -re-read its configuration file, "telnet servername -2401" should show you the text hello and then the -server should close the connection. If this doesn't -work, you need to fix it before you can worry about -@sc{cvs} problems. - -On AIX systems, the system will often have its own -program trying to use port 2401. This is AIX's problem -in the sense that port 2401 is registered for use with -@sc{cvs}. I hear that there is an AIX patch available -to address this problem. - -Another good debugging tool is the @samp{-d} -(debugging) option to inetd. Consult your system -documentation for more information. - -If you seem to be connecting but get errors like: - -@example -cvs server: cannot open /root/.cvsignore: Permission denied -cvs [server aborted]: can't chdir(/root): Permission denied -@end example - -@noindent -then you probably haven't specified @samp{-f} in @file{inetd.conf}. -(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by -your system setting the @code{$HOME} environment variable -for programs being run by inetd. In this case, you can either -have inetd run a shell script that unsets @code{$HOME} and then runs -@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine -environment.) - -If you can connect successfully for a while but then can't, -you've probably hit inetd's rate limit. -(If inetd receives too many requests for the same service -in a short period of time, it assumes that something is wrong -and temporarily disables the service.) -Check your inetd documentation to find out how to adjust the -rate limit (some versions of inetd have a single rate limit, -others allow you to set the limit for each service separately.) -@end table - -@node Other problems -@appendixsec Other common problems - -Here is a list of problems which do not fit into the -above categories. They are in no particular order. - -@itemize @bullet -@item -On Windows, if there is a 30 second or so delay when -you run a @sc{cvs} command, it may mean that you have -your home directory set to @file{C:/}, for example (see -@code{HOMEDRIVE} and @code{HOMEPATH} in -@ref{Environment variables}). @sc{cvs} expects the home -directory to not end in a slash, for example @file{C:} -or @file{C:\cvs}. -@c FIXCVS: CVS should at least detect this and print an -@c error, presumably. - -@item -If you are running @sc{cvs} 1.9.18 or older, and -@code{cvs update} finds a conflict and tries to -merge, as described in @ref{Conflicts example}, but -doesn't tell you there were conflicts, then you may -have an old version of @sc{rcs}. The easiest solution -probably is to upgrade to a current version of -@sc{cvs}, which does not rely on external @sc{rcs} -programs. -@end itemize - -@c --------------------------------------------------------------------- -@node Credits -@appendix Credits - -@cindex Contributors (manual) -@cindex Credits (manual) -Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> -wrote the manual pages which were distributed with -@sc{cvs} 1.3. Much of their text was copied into this -manual. He also read an early draft -of this manual and contributed many ideas and -corrections. - -The mailing-list @code{info-cvs} is sometimes -informative. I have included information from postings -made by the following persons: -David G. Grubbs <@t{dgg@@think.com}>. - -Some text has been extracted from the man pages for -@sc{rcs}. - -The @sc{cvs} @sc{faq} by David G. Grubbs has provided -useful material. The @sc{faq} is no longer maintained, -however, and this manual is about the closest thing there -is to a successor (with respect to documenting how to -use @sc{cvs}, at least). - -In addition, the following persons have helped by -telling me about mistakes I've made: - -@display -Roxanne Brunskill <@t{rbrunski@@datap.ca}>, -Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, -Karl Pingle <@t{pingle@@acuson.com}>, -Thomas A Peterson <@t{tap@@src.honeywell.com}>, -Inge Wallin <@t{ingwa@@signum.se}>, -Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> -and Michael Brown <@t{brown@@wi.extrel.com}>. -@end display - -The list of contributors here is not comprehensive; for a more -complete list of who has contributed to this manual see -the file @file{doc/ChangeLog} in the @sc{cvs} source -distribution. - -@c --------------------------------------------------------------------- -@node BUGS -@appendix Dealing with bugs in CVS or this manual - -@cindex Bugs in this manual or CVS -Neither @sc{cvs} nor this manual is perfect, and they -probably never will be. If you are having trouble -using @sc{cvs}, or think you have found a bug, there -are a number of things you can do about it. Note that -if the manual is unclear, that can be considered a bug -in the manual, so these problems are often worth doing -something about as well as problems with @sc{cvs} itself. - -@cindex Reporting bugs -@cindex Bugs, reporting -@cindex Errors, reporting -@itemize @bullet -@item -If you want someone to help you and fix bugs that you -report, there are companies which will do that for a -fee. One such company is: - -@cindex Ximbiot -@cindex Support, getting CVS support -@example -Ximbiot LLC -Suite 230 -200 Diversion St. -Rochester Hills, MI 48307-6636 -USA -Email: info@@ximbiot.com -Phone: (248) 835-1260 -Fax: (248) 835-1263 -@url{http://ximbiot.com/} - -@end example - -@item -If you got @sc{cvs} through a distributor, such as an -operating system vendor or a vendor of freeware -@sc{cd-rom}s, you may wish to see whether the -distributor provides support. Often, they will provide -no support or minimal support, but this may vary from -distributor to distributor. - -@item -If you have the skills and time to do so, you may wish -to fix the bug yourself. If you wish to submit your -fix for inclusion in future releases of @sc{cvs}, see -the file @sc{hacking} in the @sc{cvs} source -distribution. It contains much more information on the -process of submitting fixes. - -@item -There may be resources on the net which can help. A -good place to start is: - -@example -@url{http://cvs.nongnu.org/} -@end example - -If you are so inspired, increasing the information -available on the net is likely to be appreciated. For -example, before the standard @sc{cvs} distribution -worked on Windows 95, there was a web page with some -explanation and patches for running @sc{cvs} on Windows -95, and various people helped out by mentioning this -page on mailing lists or newsgroups when the subject -came up. - -@item -It is also possible to report bugs to @email{bug-cvs@@nongnu.org}. -Note that someone may or may not want to do anything -with your bug report---if you need a solution consider -one of the options mentioned above. People probably do -want to hear about bugs which are particularly severe -in consequences and/or easy to fix, however. You can -also increase your odds by being as clear as possible -about the exact nature of the bug and any other -relevant information. The way to report bugs is to -send email to @email{bug-cvs@@nongnu.org}. Note -that submissions to @email{bug-cvs@@nongnu.org} may be distributed -under the terms of the @sc{gnu} Public License, so if -you don't like this, don't submit them. There is -usually no justification for sending mail directly to -one of the @sc{cvs} maintainers rather than to -@email{bug-cvs@@nongnu.org}; those maintainers who want to hear -about such bug reports read @email{bug-cvs@@nongnu.org}. Also note -that sending a bug report to other mailing lists or -newsgroups is @emph{not} a substitute for sending it to -@email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on -whatever forum you prefer, but there are not -necessarily any maintainers reading bug reports sent -anywhere except @email{bug-cvs@@nongnu.org}. -@end itemize - -@cindex Known bugs in this manual or CVS -People often ask if there is a list of known bugs or -whether a particular bug is a known one. The file -@sc{bugs} in the @sc{cvs} source distribution is one -list of known bugs, but it doesn't necessarily try to -be comprehensive. Perhaps there will never be a -comprehensive, detailed list of known bugs. - -@c --------------------------------------------------------------------- -@node Index -@unnumbered Index -@cindex Index - -@printindex cp - -@bye - -Local Variables: -fill-column: 55 -End: |
