diff options
Diffstat (limited to 'gnu/usr.bin/cvs/doc/cvs.texinfo')
| -rw-r--r-- | gnu/usr.bin/cvs/doc/cvs.texinfo | 6931 |
1 files changed, 0 insertions, 6931 deletions
diff --git a/gnu/usr.bin/cvs/doc/cvs.texinfo b/gnu/usr.bin/cvs/doc/cvs.texinfo deleted file mode 100644 index ef125f524b6e..000000000000 --- a/gnu/usr.bin/cvs/doc/cvs.texinfo +++ /dev/null @@ -1,6931 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment cvs.texinfo,v 1.6 1995/10/12 23:39:26 kfogel Exp -@comment Documentation for CVS. -@comment Copyright (C) 1992, 1993 Signum Support AB -@comment Copyright (C) 1993 Free Software Foundation, Inc. - -@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 1, 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. - -@comment You should have received a copy of the GNU General Public License -@comment along with CVS; see the file COPYING. If not, write to -@comment the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. - -@afourpaper -@setfilename cvs.info -@settitle CVS---Concurrent Versions System -@setchapternewpage odd - -@c -- TODO list: -@c -- Fix all lines that match "^@c -- " -@c -- Document how CVS finds the binaries it executes. -@c Things to include in the index: -@c Finding RCS binaries -@c Path to RCS binaries -@c RCS, how CVS finds them -@c s/RCS/diff/ -@c -- More on binary files - -@ifinfo -Copyright @copyright{} 1992, 1993 Signum Support AB -Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@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 copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' and -this permission notice may be included in translations approved by the -Free Software Foundation instead of in the original English. -@end ifinfo - -@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} 1.6+ -@comment -release- -@sp 3 -@center Per Cederqvist -@sp 3 -@center last updated 12 Oct 1995 -@comment -date- - -@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 -Copyright @copyright{} 1992, 1993 Signum Support AB - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' and -this permission notice may be included in translations approved by the -Free Software Foundation instead of in the original English. -@end titlepage - -@comment ================================================================ -@comment The real text starts here -@comment ================================================================ - -@ifinfo -@c --------------------------------------------------------------------- -@node Top -@top - -This info manual describes how to use and administer -@sc{cvs} and is updated to release 1.4 or something -similar. -@end ifinfo - -@menu -* Preface:: About this manual -* What is CVS?:: What is CVS? -* Basic concepts:: Basic concepts of revision management -* A sample session:: A tour of basic CVS usage -* Repository:: Where all your sources are stored -* Starting a new project:: Starting a project with CVS -* Multiple developers:: How CVS helps a group of developers -* Branches:: Parallel development explained -* Merging:: How to move changes between branches -* Recursive behavior:: CVS descends directories -* Adding files:: Adding files to a module -* Removing files:: Removing files from a module -* Tracking sources:: Tracking third-party sources -* Moving files:: Moving and renaming files -* Moving directories:: Moving and renaming directories -* Keyword substitution:: CVS can include the revision inside the file -* Revision management:: Policy questions for revision management -* Invoking CVS:: Reference manual for CVS commands -* Administrative files:: Reference manual for the Administrative files -* Environment variables:: All environment variables which affect CVS -* Troubleshooting:: Some tips when nothing works -* Copying:: GNU GENERAL PUBLIC LICENSE -* Index:: Index -@end menu - -@c --------------------------------------------------------------------- -@node Preface -@unnumbered About this manual -@cindex Preface -@cindex About this manual - -Up to this point, one of the weakest parts of @sc{cvs} -has been the documentation. @sc{cvs} is a complex -program. Previous versions of the manual were written -in the manual page format, which is not really well -suited for such a complex program. - -When writing this manual, I had several goals in mind: - -@itemize @bullet -@item -No knowledge of @sc{rcs} should be necessary. - -@item -No previous knowledge of revision control software -should be necessary. All terms, such as @dfn{revision -numbers}, @dfn{revision trees} and @dfn{merging} are -explained as they are introduced. - -@item -The manual should concentrate on the things @sc{cvs} users -want to do, instead of what the @sc{cvs} commands can do. -The first part of this manual leads you through things -you might want to do while doing development, and -introduces the relevant @sc{cvs} commands as they are -needed. - -@item -Information should be easy to find. In the reference -manual in the appendices almost all information about -every @sc{cvs} command is gathered together. There is also -an extensive index, and a lot of cross references. -@end itemize - -@cindex Signum Support -@cindex Support, getting CVS support -This manual was contributed by Signum Support AB in -Sweden. Signum is yet another in the growing list of -companies that support free software. You are free to -copy both this manual and the @sc{cvs} program. -@xref{Copying}, for the details. Signum Support offers -@c -- Check this reference! It has been bogus in the past. -support contracts and binary distribution for many -programs, such as @sc{cvs}, @sc{gnu} Emacs, the -@sc{gnu} C compiler and others. You can also buy -hardcopies of this manual from us. Write to us for -more information. - -@example -Signum Support AB -Box 2044 -S-580 02 Linkoping -Sweden - -Email: info@@signum.se -Phone: +46 (0)13 - 21 46 00 -Fax: +46 (0)13 - 21 47 00 -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@menu -* Checklist:: -* Credits:: -* BUGS:: -@end menu - -@node Checklist -@unnumberedsec Checklist for the impatient reader - -@sc{cvs} is a complex system. You will need to read -the manual to be able to use all of its capabilities. -There are dangers that can easily be avoided if you -know about them, and this manual tries to warn you -about them. This checklist is intended to help you -avoid the dangers without reading the entire manual. -If you intend to read the entire manual you can skip -this table. - -@table @asis -@item Binary files -@sc{cvs} can handle binary files, but -you must have @sc{rcs} release 5.5 or later and -a release of @sc{gnu} diff that supports the @samp{-a} -flag (release 1.15 and later are OK). You must also -configure both @sc{rcs} and @sc{cvs} to handle binary -files when you install them. - -Keword substitution can be a source of trouble with -binary files. @xref{Keyword substitution}, for -solutions. - -@item The @code{admin} command -Uncareful use of the @code{admin} command can cause -@sc{cvs} to cease working. @xref{admin}, before trying -to use it. -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Credits -@unnumberedsec Credits - -@cindex Contributors (manual) -@cindex Credits (manual) -Roland Pesch, Cygnus Support <@t{pesch@@cygnus.com}> -wrote the manual pages which were distributed with -@sc{cvs} 1.3. Appendix A and B contain much text that -was extracted from them. He also read an early draft -of this manual and contributed many ideas and -corrections. - -The mailing-list @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} (@pxref{What is CVS?}) by David -G. Grubbs has been used as a check-list to make sure -that this manual is as complete as possible. (This -manual does however not include all of the material in -the @sc{faq}). The @sc{faq} contains a lot of useful -information. - -In addition, the following persons have helped by -telling me about mistakes I've made: -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}>. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node BUGS -@unnumberedsec BUGS - -@cindex Bugs, known in this manual -@cindex Known bugs in this manual -This manual is known to have room for improvement. -Here is a list of known deficiencies: - -@itemize @bullet -@item -In the examples, the output from @sc{cvs} is sometimes -displayed, sometimes not. - -@item -The input that you are supposed to type in the examples -should have a different font than the output from the -computer. - -@item -This manual should be clearer about what file -permissions you should set up in the repository, and -about setuid/setgid. - -@item -Some of the chapters are not yet complete. They are -noted by comments in the @file{cvs.texinfo} file. - -@item -@cindex Reporting bugs (manual) -@cindex Bugs, reporting (manual) -@cindex Errors, reporting (manual) -This list is not complete. If you notice any error, -omission, or something that is unclear, please send -mail to @t{bug-cvs@@prep.ai.mit.edu}. -@end itemize - -I hope that you will find this manual useful, despite -the above-mentioned shortcomings. - -@flushright - -Linkoping, October 1993 -Per Cederqvist -@end flushright - -@c --------------------------------------------------------------------- -@node What is CVS? -@chapter 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 -the same file is never modified by two people at the -same time. Unfortunately, if someone is using another -editor, that safeguard will not work. @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 @code{comp.sources.unix} in the volume 6 -release of December, 1986. While no actual code from -these shell scripts is present in the current version -of @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} via anonymous ftp from a number of -sites, for instance @t{prep.ai.mit.edu} in -@file{pub/gnu}. - -@cindex Mailing list -@cindex List, mailing list -There is a mailing list for @sc{cvs} where bug reports -can be sent, questions can be asked, an FAQ is posted, -and discussion about future enhancements to @sc{cvs} -take place. To submit a message to the list, write to -<@t{info-cvs@@prep.ai.mit.edu}>. To subscribe or -unsubscribe, write to -<@t{info-cvs-request@@prep.ai.mit.edu}>. Please be -specific about your email address. - -Work is in progress on creating a newsgroup for -@sc{cvs}-related topics. It will appear somewhere -under the @samp{gnu.} hierarchy. Gateways to and from -the mailing list will be set up. -@c -- Newsgroup? gnu.cvs.info? - -@cindex FTP site -@cindex Patches to CVS -@cindex CVS FTP site -@cindex Fixes to CVS -@cindex FAQ -@cindex CVS FAQ -The @sc{ftp} site @t{think.com} has some @sc{cvs} -material in the @file{/pub/cvs} subdirectory. -Currently (late summer 1993) it contains an excellent -@sc{faq} (Frequently Asked Questions, with answers), -and an improved (but unofficial) version of @sc{cvs}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@unnumberedsec CVS is not@dots{} - -@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. That's simply bad planning. - -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. You must use your -brain and a collection of other tools to provide a -build scheme to match your plans. - -Of course, you should place the tools created to -support such a build system (scripts, @file{Makefile}s, -etc) under @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} is not a configuration management system. - -@sc{cvs} is a source control system. The phrase -``configuration management'' is a marketing term, not -an industry-recognized set of functions. - -A true ``configuration management system'' would contain -elements of the following: - -@itemize @bullet -@item Source control. -@item Dependency tracking. -@item Build systems (i.e. What to build and how to find -things during a build. What is shared? What is local?) -@item Bug tracking. -@item Automated Testing procedures. -@item Release Engineering documentation and procedures. -@item Tape Construction. -@item Customer Installation. -@item A way for users to run different versions of the same -software on the same host at the same time. -@end itemize - -@sc{cvs} provides only the first. -@end table - -This section is taken from release 2.3 of the @sc{cvs} -@sc{faq}. - -@c --------------------------------------------------------------------- -@node Basic concepts -@chapter Basic concepts -@cindex Modules (intro) -@cindex Repository (intro) - -@sc{cvs} stores all files in a centralized -@dfn{repository}: a directory (such as -@file{/usr/local/cvsroot} or -@file{user@@remotehost:/usr/local/cvsroot}) which is -populated with a hierarchy of files and directories. -(@pxref{Remote repositories} for information about -keeping the repository on a remote machine.) - -Normally, you never access any of the files in the -repository directly. Instead, you use @sc{cvs} -commands to get your own copy of the files, and then -work on that copy. When you've finished a set of -changes, you check (or @dfn{commit}) them back into the -repository. - -The files in the repository are organized in -@dfn{modules}. Each module is made up of one or more -files, and can include files from several directories. -A typical usage is to define one module per project. - -@menu -* Revision numbers:: The meaning of a revision number -* Versions revisions releases:: Terminology used in this manual -@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 Main trunk (intro) -@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 - -@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 -@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.2.2.4 ! - / +---------+ +---------+ +---------+ +---------+ - / - / -+-----+ +-----+ +-----+ +-----+ +-----+ -! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk -+-----+ +-----+ +-----+ +-----+ +-----+ - ! - ! - ! +---------+ +---------+ +---------+ -Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! - +---------+ +---------+ +---------+ - -@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 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. - -@c --------------------------------------------------------------------- -@node A sample session -@chapter A sample session -@cindex 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) - -This section describes a typical work-session using -@sc{cvs}. It assumes that a repository is set up -(@pxref{Repository}). - -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 -@section 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 tc -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 -@section Committing your changes -@cindex Committing changes -@cindex Log message entry -@cindex CVSEDITOR, environment variable -@cindex EDITOR, environment variable - -When you have checked that the compiler is still compilable you decide -to make a new version of @file{backend.c}. - -@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. - -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 the editor defaults to -@code{vi}. If you want to avoid the overhead of -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 -@section 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) module `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 -@section 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. - -@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) module `tc': y -@end example - -@c --------------------------------------------------------------------- -@node Repository -@chapter The Repository -@cindex Repository, example -@cindex Layout of repository -@cindex Typical repository -@cindex CVSROOT, environment variable -@cindex .profile -@cindex .cshrc -@cindex .tcshrc -@cindex .bashrc -@cindex /usr/local/cvsroot -@cindex cvsroot - -Figure 3 below shows a typical setup of a repository. -Only directories are shown below. - -@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 - - -There are a couple of different 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 - - 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}, all @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 - - 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; -however, @sc{CVS} will complain if the @file{-d} -argument and the @file{CVS/Root} file disagree. - -There is nothing magical about the name -@file{/usr/local/cvsroot}. You can choose to place the -repository anywhere you like. -@xref{Remote repositories} to learn how the repository can be on a -different machine than your working copy of the sources. - -The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains -administrative files for @sc{cvs}. The other directories contain the actual -user-defined modules. - -@menu -* User modules:: The structure of the repository -* Intro administrative files:: Defining modules -* Multiple repositories:: Multiple repositories -* Creating a repository:: Creating a repository -* Remote repositories:: Accessing repositories on remote machines -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node User modules -@section User modules -@cindex User modules -@cindex Repository, user parts - -@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 -@cindex RCS, CVS uses RCS -The figure above shows the contents of the @samp{tc} -module inside the repository. As you can see all file -names end in @samp{,v}. The files are @dfn{history -files}. They contain, among other things, enough -information to recreate any revision of the file, a log -of all commit messages and the user-name of the person -who committed the revision. @sc{cvs} uses the -facilities of @sc{rcs}, a simpler version control -system, to maintain these files. For a full -description of the file format, see the @code{man} page -@cite{rcsfile(5)}. -@c -- Use this format for all references to man pages, -@c -- or use something better! - -@menu -* File permissions:: File permissions -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node File permissions -@subsection File permissions -@c -- Move this to @node Setting up -@cindex Security -@cindex File permissions -@cindex Group -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. - -This means that you can only control access to files on -a per-directory basis. - -@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. - -@cindex setuid -@cindex setgid -Since @sc{cvs} was not written to be run setuid, it is -unsafe to try to run it setuid. You cannot use the -setuid features of @sc{rcs} together with @sc{cvs}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Intro administrative files -@section The administrative files -@cindex Administrative files (intro) -@cindex Modules file -@cindex CVSROOT, module name -@cindex Defining modules (intro) - -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. - -@example -CVSROOT -i mkmodules CVSROOT -modules -i mkmodules 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 for lines in the example -above are examples of such lines. - -@cindex mkmodules -Each module definition can contain options. The @samp{-i mkmodules} is -an example of an option. It arranges for @sc{cvs} to run the -@code{mkmodules} program whenever any file in the module CVSROOT is -committed. That program is responsible for checking out read-only -copies from the @sc{rcs} @dfn{history files} of all the administrative files. -These read-only copies are used internally by @sc{cvs}. You -should never edit them directly. - -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. - -@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. -@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 directories) by -simply allowing @sc{cvs} to use the repository that was -used to check out the working directory (@pxref{Repository}). - -Notwithstanding, it can be confusing to have two or -more repositories. - -None of the examples in this manual show multiple -repositories. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Creating a repository -@section Creating a repository -@c -- Well, how do you do? - -See the instructions in the @file{INSTALL} file in the -@sc{cvs} distribution. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Remote repositories -@section Remote repositories -@cindex Repositories, remote -@cindex Remote repositories -@cindex Client/Server Operation - -The repository and your working copy of the sources can -be on different machines. To access a remote -repository, use the following format for its name: - -@example - user@@hostname:/path/to/repository -@end example - -(The @file{user@@} can be omitted if it's the same on -both the local and remote hosts.) - -The details of exactly what needs to be set up depends -on how you are connecting to the server. - -@menu -* Connecting via rsh:: Using the rsh program to connect -* Kerberos authenticated:: Direct connections with kerberos -@end menu - -@node Connecting via rsh -@subsection Connecting with rsh - -@cindex rsh -CVS uses the @file{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. - -For example, suppose you are the user @file{mozart} on -the local machine @file{anklet.grunge.com}, and the -server machine is @file{chainsaw.brickyard.com}. On -chainsaw, put the following line into the file -@file{.rhosts} in @file{bach}'s home directory: - -@example -anklet.grunge.com mozart -@end example - -Then test that rsh is working with - -@example -rsh -l bach chainsaw.brickyard.com echo $PATH -@end example - -@cindex CVS_SERVER -Next you have to make sure that rsh will be able to -find the server. Make sure that the path which rsh -printed in the above example includes the directory -containing a program named @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}. - -There is no need to edit @code{inetd.conf} or start a -@sc{cvs} server daemon. - -Continuing our example, supposing you want to access -the module @file{foo} in the repository -@file{/usr/local/cvsroot/}, on machine -@file{chainsaw.brickyard.com}, you are ready to go: - -@example -cvs -d bach@@chainsaw.brickyard.com:/user/local/cvsroot checkout foo -@end example - -@node Kerberos authenticated -@subsection Direct connection with kerberos - -@cindex kerberos -The main disadvantage of using rsh is that all the data -needs to pass through additional programs, so it may be -slower. So if you have kerberos installed you can -connect via a direct @sc{tcp} connection, -authenticating with kerberos (note that the data -transmitted is @emph{not} encrypted). - -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. - -@cindex CVS_CLIENT_PORT -You need to edit @code{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{CVS_CLIENT_PORT} environment -variable on the client. Set @code{CVS_CLIENT_PORT} to -@samp{-1} to force an rsh connection. - -@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 chainsaw.brickyard.com:/user/local/cvsroot checkout foo -@end example - -If @sc{cvs} fails to connect, it will fall back to -trying rsh. - -@c --------------------------------------------------------------------- -@node Starting a new project -@chapter Starting a project with CVS -@cindex Starting a project with CVS -@cindex Creating a project - -@comment --moduledb-- -Since @sc{cvs} 1.x is bad at renaming files and moving -them between directories, the first thing you do when -you start a new project should be to think through your -file organization. It is not impossible---just -awkward---to rename or move files. -@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 scratch:: Creating a module from scratch. -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node From files -@subsection Creating a module 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{dir}}, and you want them to appear in the -repository as @file{$CVSROOT/yoyodyne/@var{dir}}, you can do this: - -@example -$ cd @var{dir} -$ cvs import -m "Imported sources" yoyodyne/@var{dir} 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. - -@example -$ cd .. -$ mv @var{dir} @var{dir}.orig -$ cvs checkout yoyodyne/@var{dir} # @r{Explanation below} -$ ls -R yoyodyne -$ rm -r @var{dir}.orig -@end example - -@noindent -Erasing the original sources is a good idea, to make sure that you do -not accidentally edit them in @var{dir}, 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 @samp{$CVSROOT} -are reasonable, and that they belong to the proper -groups. @xref{File permissions}. - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node From scratch -@subsection Creating a module from scratch - -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 - -Then, use @code{add} to add files (and new directories) -as they appear. - -Check that the permissions @sc{cvs} sets on the -directories inside @samp{$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 modules -$ cd modules -@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 modules -@end example -@end enumerate - -@c --------------------------------------------------------------------- -@node Multiple developers -@chapter Multiple developers -@cindex Multiple developers -@cindex Team of developers -@cindex File locking -@cindex Locking files -@cindex Working copy - -When more than one person works on a software project -things often get complicated. Often, two people try to -edit the same file simultaneously. Some other version -control systems (including @sc{rcs} and @sc{sccs}) -try to solve that particular problem by introducing -@dfn{file locking}, so that only one person can edit -each file at a time. Unfortunately, file locking can -be very counter-productive. If two persons want -to edit different parts of a file, there may be no -reason to prevent either of them from doing so. - -@sc{cvs} does not use file locking. Instead, it allows many -people to 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, and explained in this chapter. - -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. It is often useful to inform the group of -commits you have done. @sc{cvs} has several ways of -automating that process. @xref{Informing others}. -@xref{Revision management}, for more tips on how to use -@sc{cvs}. - -@menu -* File status:: A file can be in several states -* Updating a file:: Bringing a file up-to-date -* Conflicts example:: An informative example -* Informing others:: To cooperate you must inform -* Concurrency:: Simultaneous repository access -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node File status -@section File status -@cindex File status -@cindex Status of a file -@cindex Four states of a file - -After you have checked out a file out from @sc{cvs}, it is in -one of these four states: - -@table @asis -@cindex Up-to-date -@item Up-to-date -The file is identical with the latest revision in the -repository. -@c -- The above is not always true if branching is used. - -@item Locally modified -@cindex Locally modified -You have edited the file, and not yet committed your changes. - -@item Needing update -@cindex Needing update -Someone else has committed a newer revision to the repository. - -@item Needing merge -@cindex Needing merge -Someone else have committed a newer revision to the repository, and you -have also made modifications to the file. -@c -- What about "added" "removed" and so on? -@end table - -You can use the @code{status} command to find out the status of a given -file. @xref{status}. - -@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{update} -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 copy of the -module. - -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"); -<<<<<<< driver.c - exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); -======= - exit(!!nerr); ->>>>>>> 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 - -@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 @samp{-i} option of the -@file{modules} file, or the @file{loginfo} file, can be -used to automate this process. @xref{modules}. -@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 -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 - -@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 for and remove files starting with -@file{#cvs.tfl}, @file{#cvs.rfl}, or @file{#cvs.wfl} -from the repository. - -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}--a -way to prevent other developers from working on a -particular file. - -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. - -One might hope for the following property - -@example -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 example - -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 - -if someone runs - -@example -cvs ci a/two.c b/three.c -@end example - -and someone else runs @code{cvs update}, the person -running update might get only the change to -@file{b/three.c} and not the change to @file{a/two.c}. - -@c --------------------------------------------------------------------- -@node Branches -@chapter Branches -@cindex Branches -@cindex Main trunk and branches -@cindex Revision tree, making branches - -So far, all revisions shown in this manual have been on -the @dfn{main trunk} -of the revision tree, i.e., all revision numbers -have been of the form @var{x}.@var{y}. One useful -feature, especially when maintaining several releases -of a software product at once, is the ability to make -branches on the revision tree. @dfn{Tags}, symbolic -names for revisions, will also be -introduced in this chapter. - -@menu -* Tags:: Tags--Symbolic revisions -* Branches motivation:: What branches are good for -* Creating a branch:: Creating a branch -* Sticky tags:: Sticky tags -@end menu - -@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) -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. - -@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 -copy of the module. That is, you should issue the -command in the directory where @file{backend.c} -resides. - -@example -$ cvs tag release-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 /usr/local/cvsroot/yoyodyne/tc/backend.c,v - Sticky Tag: (none) - Sticky Date: (none) - Sticky Options: (none) - - Existing Tags: - release-0-4 (revision: 1.4) - -@end example - -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 release-1-0 . -cvs tag: Tagging . -T Makefile -T backend.c -T driver.c -T frontend.c -T parser.c -@end example - -(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 release-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 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 - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Branches motivation -@section What branches are good for -@cindex Branches motivation -@cindex What branches are good for -@cindex Motivation for branches - -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 -bugfix 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 select 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 rtag, creating a branch using - -The @code{rtag} command can be used to create a branch. -The @code{rtag} command is much like @code{tag}, but it -does not require that you have a working copy of the -module. @xref{rtag}. (You can also use the @code{tag} -command; @pxref{tag}). - -@example -$ cvs rtag -b -r release-1-0 release-1-0-patches tc -@end example - -The @samp{-b} flag makes @code{rtag} create a branch -(rather than just a symbolic revision name). @samp{-r -release-1-0} says that this branch should be rooted at the node (in -the revision tree) that corresponds to the tag -@samp{release-1-0}. Note that the numeric revision number that matches -@samp{release-1-0} will probably be different from file to file. The -name of the new branch is @samp{release-1-0-patches}, and the -module affected is @samp{tc}. - -To fix the problem in release 1.0, you need a working -copy of the branch you just created. - -@example -$ cvs checkout -r release-1-0-patches tc -$ 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 /usr/local/cvsroot/yoyodyne/tc/driver.c,v - Sticky Tag: release-1-0-patches (branch: 1.7.2) - Sticky Date: (none) - Sticky Options: (none) - - Existing Tags: - release-1-0-patches (branch: 1.7.2) - release-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 /usr/local/cvsroot/yoyodyne/tc/backend.c,v - Sticky Tag: release-1-0-patches (branch: 1.4.2) - Sticky Date: (none) - Sticky Options: (none) - - Existing Tags: - release-1-0-patches (branch: 1.4.2) - release-1-0 (revision: 1.4) - release-0-4 (revision: 1.4) - -@end example - -@cindex Branch numbers -As the output from the @code{status} command shows the branch -number is created by adding a digit at the tail of the revision number -it is based on. (If @samp{release-1-0} corresponds to revision 1.4, the -branch's revision number will be 1.4.2. For obscure reasons @sc{cvs} always -gives branches even numbers, starting at 2. -@xref{Revision numbers}). - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Sticky tags -@section Sticky tags -@cindex Sticky tags -@cindex Tags, sticky -@cindex Branches, sticky - -The @samp{-r release-1-0-patches} flag that was given to @code{checkout} -is @dfn{sticky}, that is, it will apply to subsequent commands -in this directory. If you commit any modifications, they are -committed on the branch. You can later merge the modifications into -the main trunk. @xref{Merging}. - -@example -$ vi driver.c # @r{Fix the bugs} -$ cvs commit -m "Fixed initialization bug" driver.c -Checking in driver.c; -/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c -new revision: 1.7.2.1; previous revision: 1.7 -done -$ cvs status -v 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 /usr/local/cvsroot/yoyodyne/tc/driver.c,v - Sticky Tag: release-1-0-patches (branch: 1.7.2) - Sticky Date: (none) - Sticky Options: (none) - - Existing Tags: - release-1-0-patches (branch: 1.7.2) - release-1-0 (revision: 1.7) - -@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}. @xref{update}. - -Sticky tags are not just for branches. If you check -out a certain revision (such as 1.4) it will also -become sticky. Subsequent @samp{cvs update} will not -retrieve the latest revision until you reset the tag -with @samp{cvs update -A}. - -See the descriptions in Appendix A for more information -about sticky tags. Dates and some other options can -also be sticky. Again, see Appendix A for details. -@c -- xref to relevant part of App A. -@c -- Re-evaluate this node. - -@c --------------------------------------------------------------------- -@node Merging -@chapter Merging -@cindex Merging -@cindex Copying changes -@cindex Branches, copying changes between -@cindex Changes, copying between branches -@cindex Modifications, copying between branches - -You can include the changes made between any two -revisions into your working copy, by @dfn{merging}. -You can then commit that revision, and thus effectively -copy the changes onto another branch. - -@menu -* 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 -@end menu - -@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{branch}} flag to the @code{update} command. With one -@samp{-j @var{branch}} option it merges the changes made between the -point where the branch forked and 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}. - -The @code{checkout} command also supports the @samp{-j @var{branch}} flag. The -same effect as above could be achieved with this: - -@example -$ cvs checkout -j R1fix mod -$ cvs commit -m "Included R1fix" -@end example - -@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 - -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 - -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 @emph{remove} 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 -that make up a module. You almost always use symbolic -tags rather than revision numbers when operating on -multiple files. - -@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 @samp{cvs -update testing/testpgm.t testing/test2.t} - -@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} module -@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. - -@example -$ cvs update -l # @r{Don't update files in subdirectories} -@end example - -@c --------------------------------------------------------------------- -@node Adding files -@chapter Adding files to a module -@cindex Adding files - -To add a new file to a module, follow these steps. - -@itemize @bullet -@item -You must have a working copy of the module. -@xref{Getting the source}. - -@item -Create the new file inside your working copy of the module. - -@item -Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you -want to version control the file. - -@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. - -@item -If the file contains binary data it might be necessary -to change the default keyword substitution. -@xref{Keyword substitution}. @xref{admin examples}. -@end itemize - -You can also use the @code{add} command to add a new -directory inside a module. - -Unlike most other commands, the @code{add} command is -not recursive. You cannot even type @samp{cvs add -foo/bar}! Instead, you have to - -@example -$ cd foo -$ cvs add bar -@end example - -@xref{add}, for a more complete description of the @code{add} -command. - -@c --------------------------------------------------------------------- -@node Removing files -@chapter Removing files from a module -@cindex Removing files -@cindex Deleting files - -Modules change. New files are added, and old files -disappear. Still, you want to be able to retrieve an -exact copy of old releases of the module. - -Here is what you can do to remove a file from a module, -but remain able to retrieve old revisions: - -@itemize @bullet -@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 module. -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 - -What happens when you commit the removal of the file is -that inside the source repository, it is moved into a -subdirectory called @file{Attic}. @sc{cvs} normally doesn't -look in that directory when you run e.g. -@code{checkout}. However, if you are retrieving a -certain revision via e.g. @samp{cvs checkout -r -@var{some-tag}}, it will look at the files inside the -@file{Attic} and include any files that contain the -specified tag. - -@c --------------------------------------------------------------------- -@node Tracking sources -@chapter Tracking third-party sources -@cindex Third-party sources -@cindex Tracking sources - -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. After a successful @code{import} -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 a module for the first time -* Update imports:: Updating a module with the import command -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node First import -@section Importing a module for the first time -@cindex Importing modules - -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---@xref{import options}). The -@dfn{release tags} are symbolic names for a particular -release, such as @samp{FSF_0_04}. - -@cindex Wdiff (import example) -Suppose you use @code{wdiff} (a variant of @code{diff} -that ignores changes that only involve whitespace), 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 -$ tar xfz wdiff-0.04.tar.gz -$ cd wdiff-0.04 -$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF WDIFF_0_04 -@end example - -The vendor tag is named @samp{FSF} in the above -example, and the only release tag assigned is -@samp{WDIFF_0_04}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Update imports -@section Updating a module 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 WDIFF_0_05 -@end example - -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. - -@example -$ cvs checkout -jFSF:yesterday -jFSF 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} -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. - -Using a date, as suggested above, assumes that you do -not import more than one release of a product per -day. If you do, you can always use something like this -instead: - -@example -$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff -@end example - -@noindent -In this case, the two above commands are equivalent. - -@c --------------------------------------------------------------------- -@node Moving files -@chapter 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 -@section The Normal way to Rename - -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. (Both @var{old} and @var{new} could -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 at 1.0 again, so if that bothers you, use the -@samp{-r rev} option to commit (@pxref{commit options}) - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Inside -@section 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{module} -$ 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 of the module 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 -@section 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{module} -$ cp @var{old},v @var{new},v -# @r{Remove the old file} -$ cd ~/@var{module} -$ 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 tag names} -$ cvs tag -d @var{tag1} -$ cvs tag -d @var{tag2} -@dots{} -@end example - -By removing the tags you will be able to check out old -revisions of the module. - -@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. - -@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 itemize - -@c --------------------------------------------------------------------- -@node Moving directories -@chapter Moving and renaming directories -@cindex Moving directories -@cindex Renaming directories -@cindex Directories, moving - -If you want to be able to retrieve old versions of the -module, you must move each file in the directory -with the @sc{cvs} commands. @xref{Outside}. The old, empty -directory will remain inside the repository, but it -will not appear in your workspace when you check out -the module in the future. -@c -- rephrase - -If you really want to rename or delete a directory, you -can do it like this: - -@enumerate -@item -Inform everyone who has a copy of the module that the -directory will be renamed. They should commit all -their changes, and remove their working copies of the -module, before you take the steps below. - -@item -Rename the directory inside the repository. - -@example -$ cd $CVSROOT/@var{module} -$ 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 the module and continue -working. - -@end enumerate - -If someone had a working copy of the module 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. - -@ignore -@c --------------------------------------------------------------------- -@c @node History browsing -@chapter History browsing -@cindex History browsing -@cindex Traceability -@cindex Isolation - -@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. - -@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 - -Whenever you commit a file you specify a log message. /// -@c -- - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node history database -@section The history database - -/// - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node user-defined logging -@section User-defined logging - -/// - -@end ignore - -@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 your working -copy of a module 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{Rcs} uses 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:: RCS Keywords -* Using keywords:: Using keywords -* Avoiding substitution:: Avoiding substitution -* Substitution modes:: Substitution modes -* Log keyword:: Problems with the $@asis{}Log$ keyword. -@end menu - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Keyword list -@section RCS Keywords -@cindex RCS keywords - -This is a list of the keywords that @sc{rcs} currently -(in release 5.6.0.1) supports: - -@table @code -@cindex Author keyword -@item $@asis{Author}$ -The login name of the user who checked in the revision. - -@cindex Date keyword -@item $@asis{Date}$ -The date and time (UTC) the revision was checked in. - -@cindex Header keyword -@item $@asis{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 $@asis{Id}$ -Same as @code{$@asis{Header}$}, except that the @sc{rcs} -filename is without a path. - -@cindex Locker keyword -@item $@asis{Locker}$ -The login name of the user who locked the revision -(empty if not locked, and thus almost always useless -when you are using @sc{cvs}). - -@cindex Log keyword -@item $@asis{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{$@asis{Log:@dots{}}$}. -Each new line is prefixed with a @dfn{comment leader} -which @sc{rcs} guesses from the file name extension. -It can be changed with @code{cvs admin -c}. -@xref{admin options}. This 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 $@asis{RCSfile}$ -The name of the RCS file without a path. - -@cindex Revision keyword -@item $@asis{Revision}$ -The revision number assigned to the revision. - -@cindex Source keyword -@item $@asis{Source}$ -The full pathname of the RCS file. - -@cindex State keyword -@item $@asis{State}$ -The state assigned to the revision. States can be -assigned with @code{cvs admin -s}---@xref{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{$@asis{Id}$}, inside the -file, and commit the file. @sc{cvs} will automatically -expand the string as part of the commit operation. - -@need 800 -It is common to embed @code{$@asis{}Id$} string in the -C source code. This example shows the first few lines -of a typical file, after keyword substitution has been -performed: - -@example -static char *rcsid="$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; -/* @r{The following lines will prevent @code{gcc} version 2.@var{x}} - @r{from issuing an "unused variable" warning}. */ -#if __GNUC__ == 2 -#define USE(var) static void * use_##var = (&use_##var, (void *) &var) -USE (rcsid); -#endif -@end example - -Even though a clever optimizing compiler could remove -the unused variable @code{rcsid}, most compilers tend -to include the string in the binary. Some compilers -have a @code{#pragma} directive to include literal text -in the binary. - -@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: - $@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ -$ gcc samp.c -$ ident a.out -a.out: - $@asis{}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 @sc{rcs} keyword with the -magic @sc{sccs} phrase, like this: - -@example -static char *id="@@(#) $@asis{}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{$@asis{}Author$} to appear inside a file without -@sc{rcs} interpreting it as a keyword and expanding it -into something like @samp{$@asis{}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. (If you put binaries under -version control you are strongly encouraged to use that -option, for obvious reasons). - -In many cases you can avoid using @sc{rcs} 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{$@asis{}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 -k (RCS kflags) -@cindex Kflag - -You can control how @sc{rcs} expands keywords -through the use of the @samp{-k} option (@pxref{Common -options}). The @samp{-k} option is available with the -@code{add}, @code{checkout}, @code{diff} and -@code{update} commands. - -Five different modes are available. They are: - -@table @samp -@item -kkv -Generate keyword strings using the default form, e.g. -@code{$@asis{}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. -This option is normally not useful when @sc{cvs} is used. - -@item -kk -Generate only keyword names in keyword strings; omit -their values. For example, for the @code{Revision} -keyword, generate the string @code{$@asis{}Revision$} -instead of @code{$@asis{}Revision: 5.7 $}. This option -is useful to ignore differences due to keyword -substitution when comparing different revisions of a -file. - -@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{$@asis{}Revision: 1.1 $} instead of -@code{$@asis{}Revision: 5.7 $} if that is how the -string appeared when the file was checked in. This can -be useful for binary file formats that cannot tolerate -any changes to substrings that happen to take the form -of keyword strings. - -@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{$@asis{}Revision: 5.7 $}. -This can help generate files in programming languages -where it is hard to strip keyword delimiters like -@code{$@asis{}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. - -This option is always use by @code{cvs -export}---@pxref{export}. - -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Log keyword -@section Problems with the $@asis{}Log$ keyword. - -The @code{$@asis{}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{$@asis{}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{rcs} is not good at -handling @code{$@asis{}Log$} entries when a branch is -merged onto the main trunk. Conflicts often result -from the merging operation. - -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{$@asis{}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 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 Commit, 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 Invoking CVS -@appendix Reference manual for CVS commands -@cindex Command reference -@cindex Reference, commands -@cindex Invoking CVS - -This appendix describes every subcommand of @sc{cvs} in -detail. It also describes how to invoke CVS. - -@menu -* Structure:: Overall structure of CVS commands -* ~/.cvsrc:: Default options with the ~/.csvrc 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 a new file/directory to the repository -* admin:: Administration front end for rcs -* checkout:: Checkout sources for editing -* commit:: Check files into the repository -* diff:: Run diffs 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:: Print out 'rlog' information for files -* rdiff:: 'patch' format diffs between releases -* release:: Indicate that a Module is no longer in use -* remove:: Remove an entry from the repository -* rtag:: Add a tag to a module -* status:: Status info on the revisions -* tag:: Add a tag to checked out version -* 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 first release of @sc{cvs} consisted of a number of shell-scripts. -Today @sc{cvs} is implemented as a single program that is a front-end -to @sc{rcs} and @code{diff}. 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 program that is a front-end to @sc{rcs}. - -@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}. -@samp{-l}, when given as a @code{cvs_option}, only -affects some of the commands. When it is given as a -@code{command_option} is has a different meaning, and -is accepted by more commands. In other words, do not -take the above categorization too seriously. Look at -the documentation instead. - -@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 -.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 -u -update -P -co -P -@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}. - - - -@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 -@cindex RCSBIN, overriding -@cindex Overriding RCSBIN -@item -b @var{bindir} -Use @var{bindir} as the directory where @sc{rcs} programs are -located. Overrides the setting of the @code{$RCSBIN} environment -variable and any precompiled directory. This parameter should be -specified as an absolute pathname. - -@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. @xref{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. - -@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{diff}, -you may need to use @samp{-f} to show the tag names. -@footnote{Yes, this really should be fixed, and it's -being worked on} - -@item -H -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 a summary of all the -commands available. - -@item -l -Do not log the cvs_command in the command history (but execute it -anyway). @xref{history}, for information on command history. - -@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. - -@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 -@item -r -Make new working files 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. - -@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 -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. - -@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{Warning:} 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 -(unless you explicitly override it; @pxref{update}). - -A wide variety of date formats are supported by the underlying -@sc{rcs} facilities, similar to those described in co(1), but not -exactly the same. The @var{date_spec} is interpreted as being -in the local timezone, unless a specific timezone is specified. -Examples of valid date specifications include: - -@example - 1 month ago - 2 hours ago - 400000 seconds ago - last year - last Monday - yesterday - a fortnight ago - 3/31/92 10:00:07 PST - January 23, 1987 10:05pm - 22:00 GMT -@end example - -@samp{-D} is available with the @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}). - -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). - -@need 800 -@samp{-f} is available with these commands: @code{checkout}, -@code{export}, @code{rdiff}, @code{rtag}, and @code{update}. - -@strong{Warning:} The @code{commit} command also has a -@samp{-f} option, but it has a different behavior for -that command. @xref{commit options}. - -@item -H -Help; describe the options available for this command. This is -the only option supported for all @sc{cvs} commands. - -@item -k @var{kflag} -Alter the default @sc{rcs} processing of keywords. -@xref{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} and -@code{update} commands. - -@item -l -Local; run only in current working directory, rather than -recursing through subdirectories. - -@strong{Warning:} this is not the same -as the overall @samp{cvs -l} option, which you can specify to the -left of a cvs command! - -Available with the following commands: @code{checkout}, -@code{commit}, @code{diff}, @code{export}, @code{log}, -@code{remove}, @code{rdiff}, @code{rtag}, -@code{status}, @code{tag}, and @code{update}. - -@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 checkout/commit/tag program. (A program can be -specified to run on each of these activities, in the modules -database (@pxref{modules}); this option bypasses it). - -@strong{Warning:} this is not the same as the overall @samp{cvs -n} -option, which you can specify to the left of a cvs command! - -Available with the @code{checkout}, @code{commit}, @code{export}, -and @code{rtag} commands. - -@item -P -Prune (remove) directories that are empty after being updated, on -@code{checkout}, or @code{update}. Normally, an empty directory -(one that is void of revision-controlled files) is left alone. -Specifying @samp{-P} will cause these directories to be silently -removed from your checked-out sources. This does not remove the -directory from the repository, only from your checked out copy. -Note that this option is implied by the @samp{-r} or @samp{-D} -options of @code{checkout} and @code{export}. -@c -- implied-- - -@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 -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. -Avaliable with the following commands: @code{import}, -and @code{update}. - -@item -r @var{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. - -The tag specification is sticky when you use this 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. The -tag can be either a symbolic or numeric tag. -@xref{Tags}. - -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} history file -does not contain the specified tag. - -@strong{Warning:} this is not the same as the overall `cvs -r' option, -which you can specify to the left of a cvs command! - -@samp{-r} is available with the @code{checkout}, @code{commit}, -@code{diff}, @code{history}, @code{export}, @code{rdiff}, -@code{rtag}, and @code{update} commands. - -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node add -@appendixsec add---Add a new file/directory to the repository -@cindex Add (subcommand) - -@itemize @bullet -@item -Synopsis: add [-k kflag] [-m 'message'] files@dots{} -@item -Requires: repository, working directory. -@item -Changes: working directory. -@item -Synonym: new -@end itemize - -Use the @code{add} command to create a new file or directory in the -source repository. The files or directories specified with @code{add} -must already exist in the current directory (which must have been -created with the @code{checkout} command). 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}. - -If the argument to @code{add} refers to an immediate -sub-directory, the directory is created at the correct place in -the source repository, and the necessary @sc{cvs} administration -files are created in your working directory. If the directory -already exists in the source repository, @code{add} still creates -the administration files in your version of the directory. -This allows you to use @code{add} to add a particular directory -to your private sources even if someone else created that -directory after your checkout of the sources. You can do the -following: - -@example -$ mkdir new_directory -$ cvs add new_directory -$ cvs update new_directory -@end example - -An alternate approach using @code{update} might be: - -@example -$ cvs update -d new_directory -@end example - -(To add any available new directories to your working directory, -it's probably simpler to use @code{checkout} (@pxref{checkout}) -or @samp{update -d} (@pxref{update})). - -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 resurrect the file, unless a @code{commit} command -intervened. -@xref{remove examples} for an example. - - -Unlike most other commands @code{add} never recurses down -directories. It cannot yet handle relative paths. Instead of - -@example -$ cvs add foo/bar.c -@end example - -you have to do - -@example -$ cd foo -$ cvs add bar.c -@end example - -@menu -* add options:: add options -* add examples:: add examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node add options -@appendixsubsec add options -@cindex Add options - -There are only two options you can give to @samp{add}: - -@table @code -@item -k @var{kflag} -This option specifies the default way that this file -will be checked out. See rcs(1) and co(1). The -@var{kflag} argument (@pxref{Substitution modes}) is -stored in the @sc{rcs} file and can be changed with -@code{admin -k} (@pxref{admin options}). Specifying -@samp{-ko} is useful for checking in binaries that -should not have the @sc{rcs} id strings expanded. - -@strong{Warning:} this option is reported to be broken in -version 1.3 and 1.3-s2 of @sc{cvs}. Use @samp{admin -k} -after the commit instead. @xref{admin examples}. -@c -- broken-- - -@item -m @var{description} -Using this option, you can give 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 @sc{rcs} history -file 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 table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node add examples -@appendixsubsec add examples - -To add the file @file{backend.c} to the repository, with a -description, the following can be used. - -@example -$ cvs add -m "Optimizer and code generation passes." backend.c -$ cvs commit -m "Early version. Not yet compilable." backend.c -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node admin -@appendixsec admin---Administration front end for rcs -@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 @sc{rcs} -facilities, documented in rcs(1). @code{admin} simply passes -all its options and arguments to the @code{rcs} command; it does -no filtering or other processing. This command @emph{does} work -recursively, however, so extreme care should be used. - -If there is a group whose name matches a compiled in -value which defaults to @code{cvsadmin}, only members -of that group can use @code{cvs admin}. To disallow -@code{cvs admin} for all users, create a group with no -users in it. - -@menu -* admin options:: admin options -* admin examples:: admin examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node admin options -@appendixsubsec admin options - -Not all valid @code{rcs} options are useful together -with @sc{cvs}. Some even makes it impossible to use -@sc{cvs} until you undo the effect! - -This description of the available options is based on -the @samp{rcs(1)} man page, but modified to suit -readers that are more interrested in @sc{cvs} than -@sc{rcs}. - -@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}] -Breaks @sc{cvs}. When used with bare @sc{rcs}, this -option sets the default branch to @var{rev}. -If @var{rev} is omitted, the default branch is reset to -the (dynamically) highest branch on the trunk. Use -sticky tags instead, as in @code{cvs co -r}. -@xref{Sticky tags}. - -@item -c@var{string} -Useful with @sc{cvs}. Sets the comment leader to -@var{string}. The comment leader is printed before -every log message line generated by the keyword -@code{$@asis{}Log$} (@pxref{Keyword substitution}). -This is useful for programming languages without -multi-line comments. @sc{Rcs} initially guesses the -value of the comment leader from the file name -extension when the file is first committed. - -@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. - -@item -I -Run interactively, even if the standard input is not a -terminal. - -@item -i -Useless with @sc{cvs}. When using bare @sc{rcs}, this -is used to create and initialize a new @sc{rcs} file, -without depositing a revision. - -@item -k@var{subst} -Useful with @sc{cvs}. Set the default keyword -substitution to @var{subst}. @xref{Keyword -substitution}. Giving an explicit @samp{-k} option to -@code{cvs update} or @code{cvs checkout} overrides this -default. @code{cvs export} always uses @code{-kv}, -regardless of which keyword substitution is set with -@code{cvs admin}. - -@item -l[@var{rev}] -Probably useless with @sc{cvs}. With bare @sc{rcs}, -this option can be used to 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. - -@item -L -Probably useless with @sc{cvs}. Used with bare -@sc{rcs} to set locking to strict. Strict -locking means that the owner of an RCS file is not -exempt from locking for checkin. - -@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}. - -@item -N@var{name}[:[@var{rev}]] -Act like @samp{-n}, except override any previous -assignment of @var{name}. - -@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{rcs -n@var{name}: RCS/*} associates @var{name} with the -current latest revision of all the named RCS files; -this contrasts with @samp{rcs -n@var{name}:$ RCS/*} 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} -Potentially useful, but dangerous, with @sc{cvs} (see below). -Deletes (@dfn{outdates}) the revisions given by -@var{range}. A range consisting of a single revision -number means that revision. A range consisting of a -branch number means the latest revision on that branch. -A range of the form @samp{@var{rev1}:@var{rev2}} means -revisions @var{rev1} to @var{rev2} on the same branch, -@samp{:@var{rev}} means from the beginning of the -branch containing @var{rev} up to and including -@var{rev}, and @samp{@var{rev}:} means from revision -@var{rev} to the end of the branch containing -@var{rev}. None of the outdated revisions may have -branches or locks. - -Due to the way @sc{cvs} handles branches @var{rev} -cannot be specified symbolically if it is a branch. -@xref{Magic branch numbers}, for an explanation. - -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{$@asis{}Log$} and @samp{$@asis{}State$} keywords -(@pxref{Keyword substitution}). - -@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{-}. 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}. The descriptive text can be seen in the -output from @samp{cvs log} (@pxref{log}). - -@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. - -@item -U -Probably useless with @sc{cvs}. Used with bare -@sc{rcs} to set locking to non-strict. Non-strict -locking means that the owner of a file need not lock a -revision for checkin. - -@item -u[@var{rev}] -Probably useless with @sc{cvs}. With bare @sc{rcs}, -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 a mail message to be sent -to the original locker. The message contains a -commentary solicited from the breaker. The commentary -is terminated by end-of-file or by a line containing -@code{.} by itself. - -@item -V@var{n} -Emulate @sc{rcs} version @var{n}. Use -V@var{n} to make -an @sc{rcs} file acceptable to @sc{rcs} version @var{n} -by discarding information that would confuse version -@var{n}. - -@item -x@var{suffixes} -Useless with @sc{cvs}. Use @var{suffixes} to -characterize RCS files. -@end table - - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node admin examples -@appendixsubsec admin examples - -@appendixsubsubsec Outdating is dangerous - -First, an example of how @emph{not} to use the -@code{admin} command. It is included to stress the -fact that this command can be quite dangerous unless -you know @emph{exactly} what you are doing. - -The @samp{-o} option can be used to @dfn{outdate} old revisions -from the history file. 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! - -The next line is an example of a command that you would -@emph{not} like to execute. - -@example -$ cvs admin -o:R_1_02 . -@end example - -The above command will delete all revisions up to, and -including, the revision that corresponds to 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! - -@need 1200 -@appendixsubsubsec Handling binary files -@cindex Binary files (inhibit keyword expansion) -@cindex Inhibiting keyword expansion -@cindex Keyword expansion, inhibiting - -If you use @sc{cvs} to store binary files, where -keyword strings (@pxref{Keyword substitution}) might -accidentally appear inside the file, you should use -@code{cvs admin -ko} to make sure that they are not -modified automatically. Here is an example of how you -can create a new file using the @samp{-ko} flag: - -@example -$ echo '$@asis{}Id$' > kotest -$ cvs add -m"A test file" kotest -$ cvs ci -m"First checkin; contains a keyword" kotest -$ cvs admin -ko kotest -$ rm kotest -$ cvs update kotest -@end example - -When you check in the file @file{kotest} the keywords -are expanded. (Try the above example, and do a -@code{cat kotest} after every command!) The @code{cvs -admin -ko} command sets the default keyword -substitution method for this file, but it does not -alter the working copy of the file that you have. The -easiest way to get the unexpanded version of -@file{kotest} is to remove it and check it out again. - -@appendixsubsubsec Comment leaders -@cindex Comment leader -@cindex Log keyword, selecting comment leader -@cindex Nroff (selecting comment leader) - -If you use the @code{$@asis{}Log$} keyword and you do -not agree with the guess for comment leader that -@sc{cvs} has done, you can enforce your will with -@code{cvs admin -c}. This might be suitable for -@code{nroff} source: - -@example -$ cvs admin -c'.\" ' *.man -$ rm *.man -$ cvs update -@end example - -The two last steps are to make sure that you get the -versions with correct comment leaders in your working -files. - -@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 - -Make 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} part of the command 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. -@xref{modules}. - -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). - -Running @code{checkout} on a directory that was already -built by a prior @code{checkout} is also permitted, and -has the same effect as specifying the @samp{-d} option -to the @code{update} command, that is, any new -directories that have been created in the repository -will appear in your work area. @xref{update}. - -@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}. - -@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 @sc{rcs} keywords according to @var{kflag}. See -co(1). 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. @xref{status}. - -@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. - -@item -p -Pipe files to the standard output. - -@item -r @var{tag} -Use revision @var{tag}. This option is sticky, and implies @samp{-P}. -@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. -(If you get a working file using one of the @samp{-r}, -@samp{-D}, or @samp{-k} options, @sc{cvs} remembers the -corresponding tag, date, or @var{kflag} and continues using -it for future updates; use the @samp{-A} option to make -@sc{cvs} forget these specifications, and retrieve the -`head' revision of the file). - -@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. Unless you -also use @samp{-N}, the paths created under @var{dir} -will be as short as possible. - -@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}}. - -@xref{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. (Normally, @sc{cvs} shortens paths as -much as possible when you specify an explicit target -directory). - -@item -s -Like @samp{-c}, but include the status of all modules, -and sort it by the status string. @xref{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 -Version 1.3 Synopsis: commit [-lnR] [-m 'log_message' | --f file] [-r revision] [files@dots{}] -@item -Version 1.3.1 Synopsis: commit [-lnRf] [-m 'log_message' | --F file] [-r revision] [files@dots{}] -@c -- rename-f-F-- -@item -Requires: working directory, repository. -@item -Changes: repository. -@item -Synonym: ci -@end itemize - -@strong{Warning:} The @samp{-f @var{file}} option will -probably be renamed to @samp{-F @var{file}}, and @samp{-f} -will be given a new behavior in future releases of @sc{cvs}. -@c -- rename-f-F-- - -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} history 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 -@c -- rename-f-F-- -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 -n -Do not run any module program. - -@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. You -cannot commit to a specific revision on a branch. -@end table - -@code{commit} also supports these options: - -@table @code -@item -F @var{file} -This option is present in @sc{cvs} releases 1.3-s3 and -later. Read the log message from @var{file}, instead -of invoking an editor. - -@item -f -@c -- rename-f-F-- -This option is present in @sc{cvs} 1.3-s3 and later releases -of @sc{cvs}. Note that this is not the standard behavior of -the @samp{-f} option as defined in @xref{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 - -@item -f @var{file} -@c -- rename-f-F-- -This option is present in @sc{cvs} releases 1.3, 1.3-s1 and -1.3-s2. Note that this is not the standard behavior of -the @samp{-f} option as defined in @xref{Common options}. - -Read the log message from @var{file}, instead -of invoking an editor. - -@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 - -@appendixsubsubsec New major release number - -When you make a major release of your product, you -might want the revision numbers to track your major -release number. You should normally not care about -the revision numbers, but this is a thing that many -people want to do, and it can be done without doing any -harm. - -To bring all your files up to the @sc{rcs} revision 3.0 -(including those that haven't changed), you might do: - -@example -$ cvs commit -r 3.0 -@end example - -Note that it is generally a bad idea to try to make the -@sc{rcs} revision number equal to the current release number -of your product. You should think of the revision -number as an internal number that the @sc{cvs} package -maintains, and that you generally never need to care -much about. Using the @code{tag} and @code{rtag} -commands you can give symbolic names to the releases -instead. @xref{tag} and @xref{rtag}. - -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}. - -@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{tag} -or @pxref{rtag}). 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: - -@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: - -@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---Run diffs between revisions -@cindex Diff (subcommand) - -@itemize @bullet -@item -Synopsis: diff [-l] [rcsdiff_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 will be 0 if no differences were found, -1 if some differences were found, and 2 if any error -occurred. - -@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. - -@sc{cvs} can be configured to pass the @samp{-D} option -through to @code{rcsdiff} (which in turn passes it on -to @code{diff}. @sc{Gnu} diff uses @samp{-D} as a way to -put @code{cpp}-style @samp{#define} statements around the output -differences. There is no way short of testing to -figure out how @sc{cvs} was configured. In the default -configuration @sc{cvs} will use the @samp{-D @var{date}} option. - -@item -k @var{kflag} -Process @sc{rcs} keywords according to @var{kflag}. See -co(1). - -@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). - -One or both @samp{-r} options can be replaced by a -@samp{-D @var{date}} option, described above. -@end table - -Any other options that are found are passed through to -@code{rcsdiff}, which in turn passes them to -@code{diff}. The exact meaning of the options depends -on which @code{diff} you are using. The long options -introduced in @sc{gnu} diff 2.0 are not yet supported in -@sc{cvs}. See the documentation for your @code{diff} to see -which options are supported. - -@c -- Document some common useful diff options, such as -@c -u and -c. -@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 [-flNn] -r rev|-D date [-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. - -The keyword substitution option @samp{-kv} is always set when -export is used. This causes any @sc{rcs} keywords to be -expanded such that an import done at some other site -will not lose the keyword revision information. There -is no way to override this. Note that this breaks the -@code{ident} command (which is part of the @sc{rcs} -suite---see ident(1)) which looks for @sc{rcs} keyword -strings. If you want to be able to use @code{ident} -you must use @code{checkout} instead. - -@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. Unless you -also use @samp{-N}, the paths created under @var{dir} -will be as short as possible. - -@item -N -Only useful together with @samp{-d @var{dir}}. With this -option, @sc{cvs} will not shorten module paths in your -working directory. (Normally, @sc{cvs} shortens paths as -much as possible when you specify an explicit target -directory.) -@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{Warning:} @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{-xMACFROGWUT}. - -@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. - -@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 T -rtag -@end table - -@noindent -One of four 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 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 -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 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}. -@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) - -@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. @xref{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. - -By default, certain file names are ignored during -@code{import}: 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 files includes -files matching these names: - -@example - RCSLOG RCS SCCS - CVS* cvslog.* - tags TAGS - .make.state .nse_depinfo - *~ #* .#* ,* - *.old *.bak *.BAK *.orig *.rej .del-* - *.a *.o *.so *.Z *.elc *.ln - core -@end example - -If the file @file{$CVSROOT/CVSROOT/cvsignore} exists, -any files whose names match the specifications in that -file will also be ignored. - -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, @xref{Wrappers}. - -The outside source is saved in a first-level @sc{rcs} -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 identify the files at -the leaves created each time you execute @code{import}. - -@menu -* import options:: import options -* 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 three additional special options. - -@table @code -@item -b @var{branch} -Specify a first-level branch other than 1.1.1. Unless -the @samp{-b @var{branch}} flag is given, revisions will -@emph{always} be made to the branch 1.1.1---even if a -@var{vendortag} that matches another branch is given! -What happens in that case, is that the tag will be -reset to 1.1.1. Warning: This behavior might change -in the future. - -@item -k @var{subst} -Indicate the RCS 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 co(1) for a complete list of -valid @samp{-k} settings. - -If you are checking in sources that contain @sc{rcs} keywords, and you -wish those keywords to remain intact, use the @samp{-ko} flag when -importing the files. This setting indicates that no keyword expansion -is to be performed by @sc{rcs} when checking files out. It is also -useful for checking in binaries. - -@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. -@xref{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 examples -@appendixsubsec import examples - -@xref{Tracking sources}, and @xref{From files}. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node log -@appendixsec log---Print out 'rlog' information for files -@cindex Log (subcommand) - -@itemize @bullet -@item -Synopsis: log [-l] rlog-options [files@dots{}] -@item -Requires: repository, working directory. -@item -Changes: nothing. -@item -Synonym: rlog -@end itemize - -Display log information for files. @code{log} calls -the @sc{rcs} utility @code{rlog}, which prints all available -information about the @sc{rcs} history file. This 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 -- timezone-- - -@menu -* log options:: log options -* log examples:: log examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node log options -@appendixsubsec log options - -Only one option is interpreted by @sc{cvs} and not passed on to @code{rlog}: - -@table @code -@item -l -Local; run only in current working directory. (Default -is to run recursively). -@end table - -By default, @code{rlog} prints all information that is -available. All other options (including those that -normally behave differently) are passed through to -@code{rlog} and restrict the output. See rlog(1) for a -complete description of options. This incomplete list -(which is a slightly edited extract from rlog(1)) lists -all options that are useful in conjunction with @sc{cvs}. - -@strong{Please note:} There can be no space between the option -and its argument, since @code{rlog} parses its options -in a different way than @sc{cvs}. - -@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 following table -explains the available range formats: - -@table @code -@item @var{d1}<@var{d2} -@itemx @var{d2}>@var{d1} -Select the revisions that were deposited between -@var{d1} and @var{d2} inclusive. - -@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 date/time strings @var{d}, @var{d1}, and @var{d2} -are in the free format explained in co(1). Quoting is -normally necessary, especially for < and >. Note that -the separator is a semicolon (;). - -@item -h -Print only the @sc{rcs} pathname, working pathname, head, -default branch, access list, locks, symbolic names, and -suffix. - -@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 -R -Print only the name of the @sc{rcs} history file. - -@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{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{branch} -An argument that is a branch means all revisions on -that branch. You can unfortunately not specify a -symbolic branch here. You must specify the numeric -branch number. @xref{Magic branch numbers}, for an -explanation. - -@item @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. - -@item -s@var{states} -Print information about revisions whose state -attributes match one of the states given in the -comma-separated list @var{states}. - -@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. -@end table - -@code{rlog} prints the intersection of the revisions -selected with the options @samp{-d}, @samp{-l}, -@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 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 patch command when -patching the old sources, so that 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 -l -Local; don't descend subdirectories. - -@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. -This option is not available if your diff does not -support the unidiff format. 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 @sc{rcs} keywords according to the rules current in -@sc{rcs} version @var{vn} (the expansion format changed with -@sc{rcs} version 5). -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node rdiff examples -@appendixsubsec rdiff examples - -Suppose you receive mail from @t{foo@@bar.com} 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@@bar.com -@end example - -Suppose you have made release 1.3, and forked a branch -called @samp{R_1_3fix} for bugfixes. @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] modules@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 options -* 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 uses -@samp{rm -r @file{module}} to delete your file. This -has the very serious side-effect that any directory -that you have created inside your checked-out sources, -and not added to the repository (using the @code{add} -command; @pxref{add}) 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. - -@strong{Warning:} Any new directories that you have -created, but not added to the @sc{cvs} directory hierarchy -with the @code{add} command (@pxref{add}) will be -silently ignored (and deleted, if @samp{-d} is -specified), even if they contain files. - -@table @code -@item U @var{file} -There exists a newer revision of this file in the -repository, and you have not modified your local copy -of the file. - -@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. @xref{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. - -Note that no warning message like this is printed for -spurious directories that @sc{cvs} encounters. The -directory, and all its contents, are silently ignored. - -@c FIXME -- CVS should be fixed to print "? foo" for -@c such spurious directories -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node release examples -@appendixsubsec release examples - -Release the module, 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) module `tc': y -$ -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node remove -@appendixsec remove---Remove an entry from the repository -@cindex Remove (subcommand) - -@itemize @bullet -@item -remove [-lR] [files@dots{}] -@item -Requires: Working directory. -@item -Changes: Working directory. -@item -Synonyms: rm, delete -@end itemize - -Use this command to declare that you wish to remove -files from the source repository. Like most @sc{cvs} -commands, @samp{cvs remove} works on files in your working -directory, not directly on the repository. As a -safeguard, it also requires that you first erase the -specified files from your working directory. - -The files are not actually removed until you apply your -changes to the repository with @code{commit}; at that -point, the corresponding @sc{rcs} files in the source -repository are moved into the @file{Attic} directory -(also within the source repository). - -This command is recursive by default, scheduling all -physically removed files that it finds for removal by -the next commit. Use the @samp{-l} option to avoid -this recursion, or just specify the actual files that -you wish removed. - - -@menu -* remove options:: remove options -* remove examples:: remove examples -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node remove options -@appendixsubsec remove options - -Two of the standard options are the only options -supported by @code{remove}. - -@table @code -@item -l -Local; run only in current working directory. - -@item -R -Commit directories recursively. This is on by default. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node remove examples -@appendixsubsec remove examples - -@appendixsubsubsec Remove a couple of 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 - -@appendixsubsubsec Resurrecting removed files - -If you change your mind you can easily resurrect the -file before you commit it, using the @code{add} -command. - -@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 - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node rtag -@appendixsec rtag---Add a tag to the RCS file -@cindex Rtag (subcommand) - -@itemize @bullet -@item -rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules@dots{} -@item -Requires: repository. -@item -Changes: repository. -@item -Synonym: rfreeze -@end itemize - -You can use this command to assign symbolic tags to -particular, explicitly specified source revisions in -the repository. @code{rtag} works directly on the -repository contents (and requires no prior checkout). -Use @code{tag} instead (@pxref{tag}), to base the -selection of revisions on the contents of your -working directory. - -If you attempt to use a tag name that already exists, -@sc{cvs} will complain and not overwrite that tag. Use -the @samp{-F} option to force the new tag value. - -@menu -* rtag options:: rtag options -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node rtag options -@appendixsubsec rtag options - -These standard options are supported by @code{rtag} -(@pxref{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 -F -Overwrite an existing tag of the same name on a -different revision. This option is new in @sc{cvs} -1.4. The old behavior is matched by @samp{cvs tag -F}. - -@item -l -Local; run only in current working directory. - -@item -n -Do not run any tag program that was specified with the -@samp{-t} flag inside the @file{modules} file. -(@pxref{modules}). - -@item -R -Commit directories recursively. This is on by default. - -@item -r @var{tag} -Only tag those files that contain @var{tag}. This can -be used to rename a tag: tag only the files identified -by the old tag, then delete the old tag, leaving the -new tag on exactly the same files as the old tag. -@end table - -In addition to the above common options, these options -are available: - -@table @code -@item -a -Use the @samp{-a} option to have @code{rtag} look in the -@file{Attic} (@pxref{Removing files}) for removed files -that contain the specified tag. The tag is removed from -these files, which makes it convenient to re-use a -symbolic tag as development continues (and files get -removed from the up-coming distribution). - -@item -b -Make the tag a branch tag. @xref{Branches}. - -@item -d -Delete the tag instead of creating it. - -In general, tags (often the symbolic names of software -distributions) should not be removed, but the @samp{-d} -option is available as a means to remove completely -obsolete symbolic names if necessary (as might be the -case for an Alpha release, or if you mistagged a -module). -@end table - -@ignore -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@c @node rtag examples -@appendixsubsec rtag examples - -@c -- Examples here! -@end ignore - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node status -@appendixsec status---Status info on the revisions -@cindex Status (subcommand) - -@itemize @bullet -@item -status [-lR] [-v] [files@dots{}] -@item -Requires: working directory, repository. -@item -Changes: nothing. -@end itemize - -Display a brief report on the current status of files -with respect to the source repository, including any -sticky tags, dates, or @samp{-k} options. - -You can also use this command to determine the -potential impact of a @samp{cvs update} on your working -source directory---but remember that things might -change in the repository before you run @code{update}. - -@menu -* status options:: status options -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node status options -@appendixsubsec status options - -These standard options are supported by @code{status} -(@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. -@end table - -There is one additional option: - -@table @code -@item -v -Verbose. In addition to the information normally -displayed, print all symbolic tags, together with the -numerical value of the revision or branch they refer -to. -@end table - -@ignore -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@c @node status examples -@appendixsubsec status examples - -@c -- FIXME -@end ignore - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node tag -@appendixsec tag---Add a symbolic tag to checked out version of RCS file -@c -- //////// - unnecessary. Also -@c -- in a lot of other -@c -- places. -@cindex Tag (subcommand) - -@itemize @bullet -@item -tag [-lR] [-b] [-d] symbolic_tag [files@dots{}] -@item -Requires: working directory, repository. -@item -Changes: repository. -@item -Synonym: freeze -@end itemize - -Use this command to assign symbolic tags to the nearest -repository versions to your working sources. The tags -are applied immediately to the repository, as with -@code{rtag}, but the versions are supplied implicitly by the -@sc{cvs} records of your working files' history rather than -applied explicitly. - -One use for tags is to record a snapshot of the -current sources when the software freeze date of a -project arrives. As bugs are fixed after the freeze -date, only those changed sources that are to be part of -the release need be re-tagged. - -The symbolic tags are meant to permanently record which -revisions of which files were used in creating a -software distribution. The @code{checkout} and -@code{update} commands allow you to extract an exact -copy of a tagged release at any time in the future, -regardless of whether files have been changed, added, -or removed since the release was tagged. - -This command can also be used to delete a symbolic tag, -or to create a branch. See the options section below. - -If you attempt to use a tag name that already exists, -@sc{cvs} will complain and not overwrite that tag. Use -the @samp{-F} option to force the new tag value. - - -@menu -* tag options:: tag options -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node tag options -@appendixsubsec tag options - -These standard options are supported by @code{tag} -(@pxref{Common options}, for a complete description of -them): - -@table @code -@item -F -Overwrite an existing tag of the same name on a -different revision. This option is new in @sc{cvs} -1.4. The old behavior is matched by @samp{cvs tag -F}. - -@item -l -Local; run only in current working directory. - -@item -R -Commit directories recursively. This is on by default. -@end table - -Two special options are available: - -@table @code -@item -b -The -b option makes the tag a branch tag -(@pxref{Branches}), allowing concurrent, isolated -development. This is most useful for creating a patch -to a previously released software distribution. - -@item -d -Delete a tag. - -If you use @samp{cvs tag -d symbolic_tag}, the symbolic -tag you specify is deleted instead of being added. -Warning: Be very certain of your ground before you -delete a tag; doing this permanently discards some -historical information, which may later turn out to -be valuable. -@end table - -@ignore -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@c @node tag examples -@appendixsubsec tag examples - -@c -- FIXME -@end ignore - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node update -@appendixsec update---Bring work tree in sync with repository -@cindex Update (subcommand) - -@itemize @bullet -@item -update [-AdflPpR] [-d] [-r tag|-D date] 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 -* update examples:: update examples -@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}. - -@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 @sc{rcs} keywords according to @var{kflag}. See -co(1). 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. @xref{status}. - -@item -l -Local; run only in current working directory. @xref{Recursive behavior}. - -@item -P -Prune empty directories. - -@item -p -Pipe files to the standard output. - -@item -R -Operate recursively. This is on by default. -@xref{Recursive behavior}. - -@item -r tag -Retrieve revision @var{tag}. This option is sticky, -and implies @samp{-P}. -@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. -(If you get a working copy of a file by using one of -the @samp{-r}, @samp{-D}, or @samp{-k} options, @sc{cvs} -remembers the corresponding tag, date, or @var{kflag} and -continues using it on future updates; use the @samp{-A} -option to make @sc{cvs} forget these specifications, and -retrieve the head revision of the file). - -@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. By default, @code{update} -ignores files whose names match any of the following: - -@example - RCSLOG RCS SCCS - CVS* cvslog.* - tags TAGS - .make.state .nse_depinfo - *~ #* .#* ,* - *.old *.bak *.BAK *.orig *.rej .del-* - *.a *.o *.so *.Z *.elc *.ln - core -@end example - -Use @samp{-I !} to avoid ignoring any files at all. -@xref{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. @xref{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. - -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}}. - -@xref{Merging}. - -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node update output -@appendixsubsec update output - -@code{update} 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 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 source, and for files -that you haven't changed but are not the most recent -versions available in the repository. - -@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} -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 output of the rcsmerge(1) command -on 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 @sc{rcs} revision that your modified file started -from. (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.) - -@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}). - -Note that no warning message like this is printed for -spurious directories that @sc{cvs} encounters. The -directory, and all its contents, are silently ignored. -@end table - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node update examples -@appendixsubsec update examples - -The following line will display all files which are not -up-to-date without actually change anything in your -working directory. It can be used to check what has -been going on with the project. - -@example -$ cvs -n -q update -@end example - -@c --------------------------------------------------------------------- -@node Administrative files -@appendix Reference manual for the Administrative files -@cindex Administrative files (reference) -@cindex Files, reference manual -@cindex Reference manual (files) -@cindex CVSROOT (file) - -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. - -The most important of these files is the @file{modules} -file, which defines the modules inside the repository. - -@menu -* modules:: Defining modules -* Wrappers:: Treat directories as files -* commit files:: The commit support files -* commitinfo:: Pre-commit checking -* editinfo:: Specifying how log messages are created -* loginfo:: Where should log messages be sent? -* rcsinfo:: Templates for the log messages -* cvsignore:: Ignoring files via cvsignore -* history file:: History information -* Setting up:: Setting up the repository -@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 create a file with the right -format in @file{$CVSROOT/CVSROOT/modules,v}. The -mkmodules(1) command should be run whenever the modules -file changes, so that the appropriate files can be -generated (depending on how you have configured @sc{cvs} -operation). - -To allow convenient editing of the @file{modules} file -itself, the file should include an entry like the -following (where @var{localbin} represents the -directory where your site installs programs like -mkmodules(1)): - -@example -modules -i /@var{localbin}/mkmodules CVSROOT modules -@end example - -@noindent -This defines the name @samp{modules} as the module name -for the file itself, so that you can use - -@example -$ cvs checkout modules -@end example - -@noindent -to get a copy of the file that you can edit. You should define -similar module entries for the other configuration -files described in this appendix, except -@file{history}). - -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. - -A module definition is a single line of the -@file{modules} file, in either of two formats. In both -cases, @var{mname} represents the symbolic module name, -and the remainder of the line is its definition. - -@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. - -@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] [ &@var{module}@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. - -By explicitly specifying files in the module definition -after @var{dir}, you can select particular files from -directory @var{dir}. The sample definition for -@samp{modules} is an example of a module defined with a -single file from a particular directory. Here is -another example: - -@example -m4test unsupported/gnu/m4 foreach.m4 forloop.m4 -@end example - -@noindent -With this definition, executing @samp{cvs checkout -m4test} will create a single working directory -@file{m4test} containing the two files listed, which -both come from a common directory several levels deep -in the @sc{cvs} source repository. - -A module definition can refer to other modules by -including @samp{&@var{module}} in its definition. -@code{checkout} creates a subdirectory for each such -module, in your working directory. -@c -- Nope. "in your working directory" is wrong. What -@c -- is right? - -@table @code -@item -d @var{name} -Name the working directory something other than the -module name. - -@cindex Export program -@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. - -@cindex Checkin program -@item -i @var{prog} -Specify a program @var{prog} to run whenever files in a -module are committed. @var{prog} runs with a single -argument, the full pathname of the affected directory -in a source repository. The @file{commitinfo}, -@file{loginfo}, and @file{editinfo} files provide other -ways to call a program on commit. - -@cindex Checkout program -@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. - -@cindex Status of a module -@cindex Module status -@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 -@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}. There is no way to -specify a program to run when @code{tag} is executed. - -@cindex Update program -@item -u @var{prog} -Specify a program @var{prog} to run whenever @samp{cvs -update} is executed from the top-level directory of the -checked-out module. @var{prog} runs with a single -argument, the full path to the source repository for -this module. -@end table -@end table - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Wrappers -@appendixsec The cvswrappers file -@cindex cvswrappers (admin file) -@cindex CVSWRAPPERS, environment variable -@cindex Wrappers - -Wrappers are essentially -directories that are to be treated as "files." This -package allows such wrappers to be "processed" on the -way in and out of CVS. The intended use is to wrap up -a wrapper into a single tar, such that that tar can be -treated as a single binary file in CVS. Apparently -this is particularly useful on NEXTSTEP. To solve -the problem effectively, it was also necessary to be -able to prevent rcsmerge application at appropriate -times. - -The file @file{cvswrappers} defines the script that will be -run on a file when its name matches a regular -expresion. There are two scripts that can be run on a -file or directory. -@c FIXME: Is this talking about comb and uncom? If so, -@c mention them by name -A script to filter the directory/file before it gets -checked in and another that is run when the -file/directory gets checked out. - -The @file{cvswrappers} also specifies the merge -methodology that should be used when the file is -updated, that is should a MERGE or a straight COPY of -the diferences be used when checking into the -repository. - -The basic format of the file @file{cvswrappers} is given as -such: - -@example -wildcard [option value][option value]... - -where option is one of --f from cvs filter value: path tofilter --t to cvs filter value: path to filter --m update methodology value: MERGE or COPY - -and value is a single-quote delimited value. -@end example - -@example -*.nib -f 'uncom %s' -t 'comb %s %s' -m 'COPY' -*.rtfd -f 'uncom %s' -t 'comb %s %s' -m 'COPY' -@end example - -@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{comb} program before -checking the file into the repository. The file should -be filtered though the @file{uncom} 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). - -@noindent -The @file{comb} 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 @file{uncom} filter is called with one argument, -which is the name of the file to filter from. The end -result of the @file{uncom} filter will be a -file/directory in the users current working directory, -that represents the source before being filtered. - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node commit files -@appendixsec The commit support files -@cindex Commit files - -The @samp{-i} flag in the @file{modules} file can be -used to run a certain program whenever files are -committed (@pxref{modules}). The files described in -this section provide other, more flexible, ways to run -programs whenever something is committed. - -There are three kind of programs that can be run on -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 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}). - -@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 -* syntax:: The common syntax -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node syntax -@appendixsubsec The common syntax -@cindex Info files (syntax) -@cindex Syntax of info files -@cindex Common syntax of info files - -The four files @file{commitinfo}, @file{loginfo}, -@file{rcsinfo} and @file{editinfo} all have a common -format. The purpose of the files are described later -on. The common syntax is described here. - -Each line contains the following: -@itemize @bullet -@item -A regular expression - -@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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node commitinfo -@appendixsec Commitinfo -@cindex Commitinfo -@cindex Checking commits -@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). - -The first line with a regular expression matching the -relative path to the module will be used. If the -command returns a non-zero exit status the commit will -be aborted. - -@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 occurances 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}. - -Note: when @sc{CVS} is accessing a remote repository, -@file{commitinfo} will be run on the @emph{remote} -(i.e., server) side, not the client side (@pxref{Remote -repositories}). - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node editinfo -@appendixsec Editinfo -@cindex Editinfo -@cindex Editor, specifying per module -@cindex Per-module editor -@cindex Log messages, editing - -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 precompiled default, normally @code{vi}, will be -used. - -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, -@file{editinfo} will be run on the @emph{remote} -(i.e., server) side, not the client side (@pxref{Remote -repositories}). - -@menu -* editinfo example:: Editinfo example -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node editinfo example -@appendixsubsec 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 -@appendixsec Loginfo -@cindex Loginfo -@cindex Storing log messages -@cindex Mailing log messages -@cindex Distributing log messages -@cindex Log messages - -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. - -The filter program may use one and only one % modifier -(a la printf). If @samp{%s} is specified in the filter -program, a brief title is included (enclosed in single -quotes) showing the modified file names. - -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 occurances 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. - -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 -@end menu - -@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -@node loginfo example -@appendixsubsec 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} and mailed to @t{ceder}. - -@example -ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog -^CVSROOT Mail -s %s ceder -^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log -@end example - -The shell-script @file{/usr/local/bin/cvs-log} looks -like this: - -@example -#!/bin/sh -(echo "-----------------------------------------------------------------"; - echo -n $USER" "; - date; - echo; - sed '1s+'$@{CVSROOT@}'++') >> $1 -@end example - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node rcsinfo -@appendixsec Rcsinfo -@cindex Rcsinfo -@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{editinfo}, @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 occurances of the name @samp{ALL} appearing as a -regular expression are used in addition to the first -matching regular expression or @samp{DEFAULT}. - -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{editinfo example}, for an example @file{rcsinfo} -file. - -Note: when @sc{CVS} is accessing a remote repository, -@file{rcsinfo} will be run on the @emph{remote} -(i.e., server) side, not the client side (@pxref{Remote -repositories}). - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node cvsignore -@appendixsec Ignoring files via cvsignore -@cindex Cvsignore, 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 the following file name -patterns: - -@cindex Ignored files -@cindex Automatically ignored files -@example - RCSLOG RCS SCCS - CVS* cvslog.* - tags TAGS - .make.state .nse_depinfo - *~ #* .#* ,* - *.old *.bak *.BAK *.orig *.rej .del-* - *.a *.o *.so *.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}. - -@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{cvsinit} script is used to set up the repository. - -The file format of the @file{history} file is -unfortunately not yet documented anywhere, but it is -fairly easy to understand most of it. -@c -- document it here? - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Setting up -@appendixsec Setting up the repository -@cindex Repository, setting up -@cindex Creating a repository -@cindex Setting up a repository - -When you install @sc{cvs} for the first time, you should -follow the instructions in the @file{INSTALL} file to -set up the repository. - -If you want to set up another repository, the easiest -way to get a reasonable set of working administrative -files is to run the @code{cvsinit} shell script. It -will set up an empty repository in the directory -defined by the environment variable @code{$CVSROOT}. -(@code{cvsinit} is careful to never overwrite any -existing files in the repository, so no harm is done if -you run @code{cvsinit} on an already set-up -repository. In fact, running it on an already set-up -repository is the best way to update the various -scripts from the @samp{contrib} directory.) - -@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 -@item $CVSIGNORE -A whitespace-separated list of file name patterns that -@sc{cvs} should ignore. @xref{cvsignore}. - -@item $CVSWRAPPERS -A whitespace-separated list of file name patterns that -@sc{cvs} should treat as wrappers. @xref{Wrappers}. - -@cindex 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. - -@cindex CVSROOT -@item $CVSROOT -Should contain the full pathname to the root of the @sc{cvs} -source repository (where the @sc{rcs} history 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. - -@cindex EDITOR -@cindex CVSEDITOR -@item $EDITOR -@itemx $CVSEDITOR -Specifies the program to use for recording log messages -during commit. If not set, the default is -@samp{/usr/ucb/vi}. @code{$CVSEDITOR} overrides -@code{$EDITOR}. @code{$CVSEDITOR} does not exist in -@sc{cvs} 1.3, but the next release will probably -include it. - -@cindex PATH -@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 RCSBIN -@item $RCSBIN -Specifies the full pathname of the location of @sc{rcs} programs, -such as co(1) and ci(1). If not set, a compiled-in -value is used, or your @code{$PATH} is searched. -@end table - -@sc{cvs} is a front-end to @sc{rcs}. The following environment -variables affect @sc{rcs}: - -@table @code -@cindex LOGNAME -@item $LOGNAME -@cindex USER -@itemx $USER -If set, they affect who @sc{rcs} thinks you are. If you -have trouble checking in files it might be because your -login name differs from the setting of e.g. -@code{$LOGNAME}. - -@cindex RCSINIT -@item $RCSINIT -Options prepended to the argument list, separated by -spaces. A backslash escapes spaces within an option. -The @code{$RCSINIT} options are prepended to the -argument lists of most @sc{rcs} commands. - -@cindex TMPDIR -@item $TMPDIR -@cindex TMP -@itemx $TMP -@cindex TEMP -@itemx $TEMP -Name of the temporary directory. The environment -variables are inspected in the order they appear above -and the first value found is taken; if none of them are -set, a host-dependent default is used, typically -@file{/tmp}. -@end table - -@c --------------------------------------------------------------------- -@node Troubleshooting -@appendix Troubleshooting - -@menu -* Magic branch numbers:: Magic branch numbers -@end menu - -@ignore -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@c @node Bad administrative files -@appendixsec Bad administrative files - -@c -- Give hints on how to fix them -@end ignore - -@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@node Magic branch numbers -@appendixsec Magic branch numbers - -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.3 becomes -1.2.0.3, 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 at least four places the -hiding is incomplete. - -@itemize @bullet -@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. - -@item -The magic branch number appears in the output from -@code{cvs log}. This is much harder to fix, since -@code{cvs log} runs @code{rlog} (which is part of the -@sc{rcs} distribution), and modifying @code{rlog} to -know about magic branches would probably break someone's -habits (if they use branch 0 for their own purposes). - -@item -You cannot specify a symbolic branch name to @code{cvs log}. - -@item -You cannot specify a symbolic branch name to @code{cvs -admin}. - -@end itemize - -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 Copying -@appendix GNU GENERAL PUBLIC LICENSE -@c @include gpl.texinfo - -@c --------------------------------------------------------------------- -@node Index -@unnumbered Index -@cindex Index - -@printindex cp - -@summarycontents - -@contents - -@bye - -Local Variables: -fill-column: 55 -End: |