117721Speter\input texinfo @c -*-texinfo-*- 217721Speter@comment Documentation for CVS. 3128266Speter@setfilename cvs.info 4128266Speter@macro copyleftnotice 5128266Speter@noindent 6128266SpeterCopyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 7177391Sobrien 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 8175261Sobrien Free Software Foundation, Inc. 917721Speter 10128266Speter@multitable @columnfractions .12 .88 11128266Speter@item Portions 12177391Sobrien@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 13177391Sobrien 2006, 2007 Derek R. Price, 14177391Sobrien@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 15130303Speter Ximbiot @url{http://ximbiot.com}, 16128266Speter@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 17128266Speter@item @tab and Copyright @copyright{} others. 18128266Speter@end multitable 19128266Speter 20128266Speter@ignore 21128266SpeterPermission is granted to process this file through Tex and print the 22128266Speterresults, provided the printed document carries copying permission 23128266Speternotice identical to this one except for the removal of this paragraph 24128266Speter(this paragraph not being relevant to the printed manual). 25128266Speter 26128266Speter@end ignore 27128266SpeterPermission is granted to make and distribute verbatim copies of 28128266Speterthis manual provided the copyright notice and this permission notice 29128266Speterare preserved on all copies. 30128266Speter 31128266SpeterPermission is granted to copy and distribute modified versions of this 32128266Spetermanual under the conditions for verbatim copying, provided also that the 33128266Speterentire resulting derived work is distributed under the terms of a 34128266Speterpermission notice identical to this one. 35128266Speter 36128266SpeterPermission is granted to copy and distribute translations of this manual 37128266Speterinto another language, under the above conditions for modified versions, 38128266Speterexcept that this permission notice may be stated in a translation 39128266Speterapproved by the Free Software Foundation. 40128266Speter@end macro 41128266Speter 4217721Speter@comment This file is part of the CVS distribution. 4317721Speter 4417721Speter@comment CVS is free software; you can redistribute it and/or modify 4517721Speter@comment it under the terms of the GNU General Public License as published by 4654427Speter@comment the Free Software Foundation; either version 2, or (at your option) 4717721Speter@comment any later version. 4817721Speter 4917721Speter@comment CVS is distributed in the hope that it will be useful, 5017721Speter@comment but WITHOUT ANY WARRANTY; without even the implied warranty of 5117721Speter@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 5217721Speter@comment GNU General Public License for more details. 5317721Speter 5425839Speter@c See ../README for A4 vs. US letter size. 5525839Speter@c When we provided A4 postscript, and people tried to 5625839Speter@c print it on US letter, the usual complaint was that the 5725839Speter@c page numbers would get cut off. 5825839Speter@c If one prints US letter on A4, reportedly there is 5925839Speter@c some extra space at the top and/or bottom, and the side 6025839Speter@c margins are a bit narrow, but no text is lost. 6144852Speter@c 6225839Speter@c See 6325839Speter@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html 6425839Speter@c for more on paper sizes. Insuring that margins are 6525839Speter@c big enough to print on either A4 or US letter does 6654427Speter@c indeed seem to be the usual approach (RFC2346). 6717721Speter 6825839Speter@c This document seems to get overfull hboxes with some 6925839Speter@c frequency (probably because the tendency is to 7025839Speter@c sanity-check it with "make info" and run TeX less 7125839Speter@c often). The big ugly boxes just seem to add insult 7225839Speter@c to injury, and I'm not aware of them helping to fix 7325839Speter@c the overfull hboxes at all. 7425839Speter@finalout 7525839Speter 76102840Speter@include version.texi 77102840Speter@settitle CVS---Concurrent Versions System v@value{VERSION} 7817721Speter@setchapternewpage odd 7917721Speter 8017721Speter@c -- TODO list: 8117721Speter@c -- Fix all lines that match "^@c -- " 8232785Speter@c -- Also places marked with FIXME should be manual 8332785Speter@c problems (as opposed to FIXCVS for CVS problems). 8417721Speter 85128266Speter@c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by 86128266Speter@c @asis when generating info and dvi, and by <i></i> in the generated html, 87128266Speter@c such that keywords are not expanded in the generated html. 88128266Speter@ifnothtml 89128266Speter@macro splitrcskeyword {arg} 90128266Speter@asis{}\arg\ 91128266Speter@end macro 92128266Speter@end ifnothtml 9344852Speter 94128266Speter@ifhtml 95128266Speter@macro splitrcskeyword {arg} 96128266Speter@i{}\arg\ 97128266Speter@end macro 98128266Speter@end ifhtml 9917721Speter 100128266Speter@dircategory GNU Packages 101128266Speter@direntry 102128266Speter* CVS: (cvs). Concurrent Versions System 103128266Speter@end direntry 104128266Speter@dircategory Individual utilities 105128266Speter@direntry 106128266Speter* cvs: (cvs)CVS commands. Concurrent Versions System 107128266Speter@end direntry 10817721Speter 10917721Speter@comment The titlepage section does not appear in the Info file. 11017721Speter@titlepage 11117721Speter@sp 4 11217721Speter@comment The title is printed in a large font. 11317721Speter@center @titlefont{Version Management} 11417721Speter@sp 11517721Speter@center @titlefont{with} 11617721Speter@sp 11717721Speter@center @titlefont{CVS} 11817721Speter@sp 2 119102840Speter@center for @sc{cvs} @value{VERSION} 12017721Speter@comment -release- 12117721Speter@sp 3 12217721Speter@center Per Cederqvist et al 12317721Speter 12417721Speter@comment The following two commands start the copyright page 12517721Speter@comment for the printed manual. This will not appear in the Info file. 12617721Speter@page 12717721Speter@vskip 0pt plus 1filll 128128266Speter@copyleftnotice 12917721Speter@end titlepage 13017721Speter 131175261Sobrien@summarycontents 132175261Sobrien 133175261Sobrien@contents 134175261Sobrien 13517721Speter@comment ================================================================ 13617721Speter@comment The real text starts here 13717721Speter@comment ================================================================ 13817721Speter 139102840Speter@ifnottex 14017721Speter@c --------------------------------------------------------------------- 14117721Speter@node Top 14244852Speter@top 14317721Speter 14417721SpeterThis info manual describes how to use and administer 145102840Speter@sc{cvs} version @value{VERSION}. 146102840Speter@end ifnottex 14717721Speter 148128266Speter@ifinfo 149128266Speter@copyleftnotice 150128266Speter@end ifinfo 151128266Speter 15225839Speter@c This menu is pretty long. Not sure how easily that 15332785Speter@c can be fixed (no brilliant ideas right away)... 15417721Speter@menu 15532785Speter* Overview:: An introduction to CVS 15617721Speter* Repository:: Where all your sources are stored 15717721Speter* Starting a new project:: Starting a project with CVS 15832785Speter* Revisions:: Numeric and symbolic names for revisions 15932785Speter* Branching and merging:: Diverging/rejoining branches of development 16017721Speter* Recursive behavior:: CVS descends directories 16132785Speter* Adding and removing:: Adding/removing/renaming files/directories 16217721Speter* History browsing:: Viewing the history of files in various ways 16332785Speter 16432785SpeterCVS and the Real World. 16532785Speter----------------------- 16632785Speter* Binary files:: CVS can handle binary files 16732785Speter* Multiple developers:: How CVS helps a group of developers 16832785Speter* Revision management:: Policy questions for revision management 16917721Speter* Keyword substitution:: CVS can include the revision inside the file 17032785Speter* Tracking sources:: Tracking third-party sources 17125839Speter* Builds:: Issues related to CVS and builds 17234461Speter* Special Files:: Devices, links and other non-regular files 17332785Speter 17432785SpeterReferences. 17532785Speter----------- 17625839Speter* CVS commands:: CVS commands share some things 17725839Speter* Invoking CVS:: Quick reference to CVS commands 17817721Speter* Administrative files:: Reference manual for the Administrative files 17917721Speter* Environment variables:: All environment variables which affect CVS 18032785Speter* Compatibility:: Upgrading CVS versions 18117721Speter* Troubleshooting:: Some tips when nothing works 18232785Speter* Credits:: Some of the contributors to this manual 18332785Speter* BUGS:: Dealing with bugs in CVS or this manual 18417721Speter* Index:: Index 18517721Speter@end menu 18617721Speter 18717721Speter@c --------------------------------------------------------------------- 18832785Speter@node Overview 18932785Speter@chapter Overview 19032785Speter@cindex Overview 19117721Speter 19232785SpeterThis chapter is for people who have never used 19332785Speter@sc{cvs}, and perhaps have never used version control 19432785Spetersoftware before. 19517721Speter 19632785SpeterIf you are already familiar with @sc{cvs} and are just 19732785Spetertrying to learn a particular feature or remember a 19832785Spetercertain command, you can probably skip everything here. 19917721Speter 20017721Speter@menu 20132785Speter* What is CVS?:: What you can do with @sc{cvs} 20232785Speter* What is CVS not?:: Problems @sc{cvs} doesn't try to solve 20332785Speter* A sample session:: A tour of basic @sc{cvs} usage 20417721Speter@end menu 20517721Speter 20617721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 20717721Speter@node What is CVS? 20832785Speter@section What is CVS? 20917721Speter@cindex What is CVS? 21017721Speter@cindex Introduction to CVS 21117721Speter@cindex CVS, introduction to 21217721Speter 21317721Speter@sc{cvs} is a version control system. Using it, you can 21417721Speterrecord the history of your source files. 21517721Speter 21617721Speter@c -- /// 21717721Speter@c -- ///Those who cannot remember the past are condemned to repeat it. 21817721Speter@c -- /// -- George Santayana 21917721Speter@c -- ////// 22017721Speter 22117721Speter@c -- Insert history quote here! 22217721SpeterFor example, bugs sometimes creep in when 22317721Spetersoftware is modified, and you might not detect the bug 22417721Speteruntil a long time after you make the modification. 22517721SpeterWith @sc{cvs}, you can easily retrieve old versions to see 22617721Speterexactly which change caused the bug. This can 22717721Spetersometimes be a big help. 22817721Speter 22917721SpeterYou could of course save every version of every file 23017721Speteryou have ever created. This would 23117721Speterhowever waste an enormous amount of disk space. @sc{cvs} 23217721Speterstores all the versions of a file in a single file in a 23317721Speterclever way that only stores the differences between 23417721Speterversions. 23517721Speter 23617721Speter@sc{cvs} also helps you if you are part of a group of people working 23717721Speteron the same project. It is all too easy to overwrite 23817721Spetereach others' changes unless you are extremely careful. 23917721SpeterSome editors, like @sc{gnu} Emacs, try to make sure that 240175261Sobrientwo people never modify the same file at the 24117721Spetersame time. Unfortunately, if someone is using another 24217721Spetereditor, that safeguard will not work. @sc{cvs} solves this problem 24317721Speterby insulating the different developers from each other. Every 24417721Speterdeveloper works in his own directory, and @sc{cvs} merges 24517721Speterthe work when each developer is done. 24617721Speter 24717721Speter@cindex History of CVS 24817721Speter@cindex CVS, history of 24917721Speter@cindex Credits (CVS program) 25017721Speter@cindex Contributors (CVS program) 25117721Speter@sc{cvs} started out as a bunch of shell scripts written by 25225839SpeterDick Grune, posted to the newsgroup 25325839Speter@code{comp.sources.unix} in the volume 6 254128266Speterrelease of July, 1986. While no actual code from 25517721Speterthese shell scripts is present in the current version 25617721Speterof @sc{cvs} much of the @sc{cvs} conflict resolution algorithms 25717721Spetercome from them. 25817721Speter 25917721SpeterIn April, 1989, Brian Berliner designed and coded @sc{cvs}. 26017721SpeterJeff Polk later helped Brian with the design of the @sc{cvs} 26117721Spetermodule and vendor branch support. 26217721Speter 26317721Speter@cindex Source, getting CVS source 26432785SpeterYou can get @sc{cvs} in a variety of ways, including 265130303Speterfree download from the Internet. For more information 26632785Speteron downloading @sc{cvs} and other @sc{cvs} topics, see: 26732785Speter 26825839Speter@example 269175261Sobrien@url{http://cvs.nongnu.org/} 27025839Speter@end example 27117721Speter 27217721Speter@cindex Mailing list 27317721Speter@cindex List, mailing list 27425839Speter@cindex Newsgroups 275175261SobrienThere is a mailing list, known as @email{info-cvs@@nongnu.org}, 27625839Speterdevoted to @sc{cvs}. To subscribe or 27744852Speterunsubscribe 27844852Speterwrite to 279175261Sobrien@email{info-cvs-request@@nongnu.org}. 280130303SpeterIf you prefer a Usenet group, there is a one-way mirror (posts to the email 281175261Sobrienlist are usually sent to the news group, but not vice versa) of 282175261Sobrien@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}. The right 283130303SpeterUsenet group for posts is @url{news:comp.software.config-mgmt} which is for 28425839Speter@sc{cvs} discussions (along with other configuration 28525839Spetermanagement systems). In the future, it might be 28625839Speterpossible to create a 28725839Speter@code{comp.software.config-mgmt.cvs}, but probably only 28825839Speterif there is sufficient @sc{cvs} traffic on 289128266Speter@url{news:comp.software.config-mgmt}. 290128266Speter@c Other random data is that the tale was very 29125839Speter@c skeptical of comp.software.config-mgmt.cvs when the 29225839Speter@c subject came up around 1995 or so (for one 29325839Speter@c thing, because creating it would be a "reorg" which 29425839Speter@c would need to take a more comprehensive look at the 29525839Speter@c whole comp.software.config-mgmt.* hierarchy). 29617721Speter 297175261SobrienYou can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list, 29825839Speterdescribed in more detail in @ref{BUGS}. To subscribe 299175261Sobriensend mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way 300130303SpeterUsenet mirror (posts to the Usenet group are usually sent to the email list and 301175261Sobrienvice versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}. 30217721Speter 30317721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 30432785Speter@node What is CVS not? 30532785Speter@section What is CVS not? 30632785Speter@cindex What is CVS not? 30717721Speter 30817721Speter@sc{cvs} can do a lot of things for you, but it does 30917721Speternot try to be everything for everyone. 31017721Speter 31117721Speter@table @asis 31217721Speter@item @sc{cvs} is not a build system. 31317721Speter 31417721SpeterThough the structure of your repository and modules 31517721Speterfile interact with your build system 31617721Speter(e.g. @file{Makefile}s), they are essentially 31717721Speterindependent. 31817721Speter 31917721Speter@sc{cvs} does not dictate how you build anything. It 32017721Spetermerely stores files for retrieval in a tree structure 32117721Speteryou devise. 32217721Speter 32317721Speter@sc{cvs} does not dictate how to use disk space in the 32417721Speterchecked out working directories. If you write your 32517721Speter@file{Makefile}s or scripts in every directory so they 32617721Speterhave to know the relative positions of everything else, 32717721Speteryou wind up requiring the entire repository to be 32825839Speterchecked out. 32917721Speter 33017721SpeterIf you modularize your work, and construct a build 33117721Spetersystem that will share files (via links, mounts, 33217721Speter@code{VPATH} in @file{Makefile}s, etc.), you can 33317721Speterarrange your disk usage however you like. 33417721Speter 33517721SpeterBut you have to remember that @emph{any} such system is 33617721Spetera lot of work to construct and maintain. @sc{cvs} does 33725839Speternot address the issues involved. 33817721Speter 33917721SpeterOf course, you should place the tools created to 34017721Spetersupport such a build system (scripts, @file{Makefile}s, 341177391Sobrienetc.) under @sc{cvs}. 34217721Speter 34325839SpeterFiguring out what files need to be rebuilt when 34425839Spetersomething changes is, again, something to be handled 34525839Speteroutside the scope of @sc{cvs}. One traditional 34625839Speterapproach is to use @code{make} for building, and use 34725839Spetersome automated tool for generating the dependencies which 34825839Speter@code{make} uses. 34925839Speter 35025839SpeterSee @ref{Builds}, for more information on doing builds 35125839Speterin conjunction with @sc{cvs}. 35225839Speter 35317721Speter@item @sc{cvs} is not a substitute for management. 35417721Speter 35517721SpeterYour managers and project leaders are expected to talk 35617721Speterto you frequently enough to make certain you are aware 35717721Speterof schedules, merge points, branch names and release 35817721Speterdates. If they don't, @sc{cvs} can't help. 35917721Speter 36017721Speter@sc{cvs} is an instrument for making sources dance to 36117721Speteryour tune. But you are the piper and the composer. No 36217721Speterinstrument plays itself or writes its own music. 36317721Speter 36417721Speter@item @sc{cvs} is not a substitute for developer communication. 36517721Speter 36617721SpeterWhen faced with conflicts within a single file, most 36717721Speterdevelopers manage to resolve them without too much 36817721Spetereffort. But a more general definition of ``conflict'' 36917721Speterincludes problems too difficult to solve without 37017721Spetercommunication between developers. 37117721Speter 37217721Speter@sc{cvs} cannot determine when simultaneous changes 37317721Speterwithin a single file, or across a whole collection of 37417721Speterfiles, will logically conflict with one another. Its 37517721Speterconcept of a @dfn{conflict} is purely textual, arising 37617721Speterwhen two changes to the same base file are near enough 377177391Sobriento spook the merge (i.e., @code{diff3}) command. 37817721Speter 37917721Speter@sc{cvs} does not claim to help at all in figuring out 38017721Speternon-textual or distributed conflicts in program logic. 38117721Speter 38217721SpeterFor example: Say you change the arguments to function 38317721Speter@code{X} defined in file @file{A}. At the same time, 38417721Spetersomeone edits file @file{B}, adding new calls to 38517721Speterfunction @code{X} using the old arguments. You are 38617721Speteroutside the realm of @sc{cvs}'s competence. 38717721Speter 38817721SpeterAcquire the habit of reading specs and talking to your 38917721Speterpeers. 39017721Speter 39117721Speter 39225839Speter@item @sc{cvs} does not have change control 39317721Speter 39425839SpeterChange control refers to a number of things. First of 39525839Speterall it can mean @dfn{bug-tracking}, that is being able 39625839Speterto keep a database of reported bugs and the status of 397177391Sobrieneach one (Is it fixed? In what release? Has the bug 39825839Spetersubmitter agreed that it is fixed?). For interfacing 39925839Speter@sc{cvs} to an external bug-tracking system, see the 40025839Speter@file{rcsinfo} and @file{verifymsg} files 40125839Speter(@pxref{Administrative files}). 40217721Speter 40325839SpeterAnother aspect of change control is keeping track of 40425839Speterthe fact that changes to several files were in fact 40525839Speterchanged together as one logical change. If you check 40625839Speterin several files in a single @code{cvs commit} 40725839Speteroperation, @sc{cvs} then forgets that those files were 40825839Speterchecked in together, and the fact that they have the 40925839Spetersame log message is the only thing tying them 41025839Spetertogether. Keeping a @sc{gnu} style @file{ChangeLog} 41125839Spetercan help somewhat. 41225839Speter@c FIXME: should have an xref to a section which talks 41325839Speter@c more about keeping ChangeLog's with CVS, but that 41425839Speter@c section hasn't been written yet. 41517721Speter 41625839SpeterAnother aspect of change control, in some systems, is 41725839Speterthe ability to keep track of the status of each 41825839Speterchange. Some changes have been written by a developer, 41925839Speterothers have been reviewed by a second developer, and so 42025839Speteron. Generally, the way to do this with @sc{cvs} is to 42125839Spetergenerate a diff (using @code{cvs diff} or @code{diff}) 42225839Speterand email it to someone who can then apply it using the 42325839Speter@code{patch} utility. This is very flexible, but 42425839Speterdepends on mechanisms outside @sc{cvs} to make sure 42525839Speternothing falls through the cracks. 42617721Speter 42725839Speter@item @sc{cvs} is not an automated testing program 42817721Speter 42925839SpeterIt should be possible to enforce mandatory use of a 430130303Spetertest suite using the @code{commitinfo} file. I haven't 43125839Speterheard a lot about projects trying to do that or whether 43225839Speterthere are subtle gotchas, however. 43317721Speter 434130303Speter@item @sc{cvs} does not have a built-in process model 43517721Speter 43625839SpeterSome systems provide ways to ensure that changes or 43725839Speterreleases go through various steps, with various 43825839Speterapprovals as needed. Generally, one can accomplish 43925839Speterthis with @sc{cvs} but it might be a little more work. 44025839SpeterIn some cases you'll want to use the @file{commitinfo}, 44125839Speter@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} 44225839Speterfiles, to require that certain steps be performed 44325839Speterbefore cvs will allow a checkin. Also consider whether 44425839Speterfeatures such as branches and tags can be used to 44525839Speterperform tasks such as doing work in a development tree 44625839Speterand then merging certain changes over to a stable tree 44725839Speteronly once they have been proven. 44825839Speter@end table 44917721Speter 45017721Speter@c --------------------------------------------------------------------- 45117721Speter@node A sample session 45232785Speter@section A sample session 45317721Speter@cindex Example of a work-session 45417721Speter@cindex Getting started 45517721Speter@cindex Work-session, example of 45617721Speter@cindex tc, Trivial Compiler (example) 45717721Speter@cindex Trivial Compiler (example) 45817721Speter 45925839Speter@c I think an example is a pretty good way to start. But 46025839Speter@c somewhere in here, maybe after the sample session, 46125839Speter@c we need something which is kind of 46225839Speter@c a "roadmap" which is more directed at sketching out 46325839Speter@c the functionality of CVS and pointing people to 46425839Speter@c various other parts of the manual. As it stands now 46525839Speter@c people who read in order get dumped right into all 46625839Speter@c manner of hair regarding remote repositories, 46725839Speter@c creating a repository, etc. 46844852Speter@c 46925839Speter@c The following was in the old Basic concepts node. I don't 47025839Speter@c know how good a job it does at introducing modules, 47144852Speter@c or whether they need to be introduced so soon, but 47225839Speter@c something of this sort might go into some 47325839Speter@c introductory material somewhere. 47425839Speter@ignore 47525839Speter@cindex Modules (intro) 47625839SpeterThe repository contains directories and files, in an 47725839Speterarbitrary tree. The @dfn{modules} feature can be used 47825839Speterto group together a set of directories or files into a 47925839Spetersingle entity (@pxref{modules}). A typical usage is to 48025839Speterdefine one module per project. 48125839Speter@end ignore 48217721Speter 48325839SpeterAs a way of introducing @sc{cvs}, we'll go through a 48425839Spetertypical work-session using @sc{cvs}. The first thing 48525839Speterto understand is that @sc{cvs} stores all files in a 48625839Spetercentralized @dfn{repository} (@pxref{Repository}); this 48725839Spetersection assumes that a repository is set up. 48825839Speter@c I'm not sure that the sentence concerning the 48925839Speter@c repository quite tells the user what they need to 49025839Speter@c know at this point. Might need to expand on "centralized" 49125839Speter@c slightly (maybe not here, maybe further down in the example?) 49225839Speter 49317721SpeterSuppose you are working on a simple compiler. The source 49417721Speterconsists of a handful of C files and a @file{Makefile}. 49517721SpeterThe compiler is called @samp{tc} (Trivial Compiler), 49617721Speterand the repository is set up so that there is a module 49717721Spetercalled @samp{tc}. 49817721Speter 49917721Speter@menu 50017721Speter* Getting the source:: Creating a workspace 50117721Speter* Committing your changes:: Making your work available to others 50217721Speter* Cleaning up:: Cleaning up 50317721Speter* Viewing differences:: Viewing differences 50417721Speter@end menu 50517721Speter 50617721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 50717721Speter@node Getting the source 50832785Speter@subsection Getting the source 50917721Speter@cindex Getting the source 51017721Speter@cindex Checking out source 51117721Speter@cindex Fetching source 51217721Speter@cindex Source, getting from CVS 51317721Speter@cindex Checkout, example 51417721Speter 51517721SpeterThe first thing you must do is to get your own working copy of the 51617721Spetersource for @samp{tc}. For this, you use the @code{checkout} command: 51717721Speter 51817721Speter@example 51917721Speter$ cvs checkout tc 52017721Speter@end example 52117721Speter 52217721Speter@noindent 52317721SpeterThis will create a new directory called @file{tc} and populate it with 52417721Speterthe source files. 52517721Speter 52617721Speter@example 52717721Speter$ cd tc 52825839Speter$ ls 52917721SpeterCVS Makefile backend.c driver.c frontend.c parser.c 53017721Speter@end example 53117721Speter 53217721SpeterThe @file{CVS} directory is used internally by 53317721Speter@sc{cvs}. Normally, you should not modify or remove 53417721Speterany of the files in it. 53517721Speter 53617721SpeterYou start your favorite editor, hack away at @file{backend.c}, and a couple 53717721Speterof hours later you have added an optimization pass to the compiler. 53817721SpeterA note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that 53925839Speteryou want to edit. @xref{Multiple developers}, for an explanation. 54017721Speter 54117721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 54217721Speter@node Committing your changes 54332785Speter@subsection Committing your changes 544107484Speter@cindex Committing changes to files 54517721Speter@cindex Log message entry 54617721Speter 54717721SpeterWhen you have checked that the compiler is still compilable you decide 54825839Speterto make a new version of @file{backend.c}. This will 54925839Speterstore your new @file{backend.c} in the repository and 55025839Spetermake it available to anyone else who is using that same 55125839Speterrepository. 55217721Speter 55317721Speter@example 55417721Speter$ cvs commit backend.c 55517721Speter@end example 55617721Speter 55717721Speter@noindent 55817721Speter@sc{cvs} starts an editor, to allow you to enter a log 55917721Spetermessage. You type in ``Added an optimization pass.'', 56017721Spetersave the temporary file, and exit the editor. 56117721Speter 562128266Speter@cindex CVSEDITOR, environment variable 563128266Speter@cindex EDITOR, environment variable 56417721SpeterThe environment variable @code{$CVSEDITOR} determines 56517721Speterwhich editor is started. If @code{$CVSEDITOR} is not 56617721Speterset, then if the environment variable @code{$EDITOR} is 56717721Speterset, it will be used. If both @code{$CVSEDITOR} and 56825839Speter@code{$EDITOR} are not set then there is a default 56925839Speterwhich will vary with your operating system, for example 57025839Speter@code{vi} for unix or @code{notepad} for Windows 57125839SpeterNT/95. 57225839Speter 57354427Speter@cindex VISUAL, environment variable 57454427SpeterIn addition, @sc{cvs} checks the @code{$VISUAL} environment 57554427Spetervariable. Opinions vary on whether this behavior is desirable and 57654427Speterwhether future releases of @sc{cvs} should check @code{$VISUAL} or 57754427Speterignore it. You will be OK either way if you make sure that 57854427Speter@code{$VISUAL} is either unset or set to the same thing as 57954427Speter@code{$EDITOR}. 58054427Speter 58125839Speter@c This probably should go into some new node 58225839Speter@c containing detailed info on the editor, rather than 58325839Speter@c the intro. In fact, perhaps some of the stuff with 58425839Speter@c CVSEDITOR and -m and so on should too. 58525839SpeterWhen @sc{cvs} starts the editor, it includes a list of 58625839Speterfiles which are modified. For the @sc{cvs} client, 58725839Speterthis list is based on comparing the modification time 58825839Speterof the file against the modification time that the file 58925839Speterhad when it was last gotten or updated. Therefore, if 59025839Spetera file's modification time has changed but its contents 59125839Speterhave not, it will show up as modified. The simplest 59225839Speterway to handle this is simply not to worry about it---if 59325839Speteryou proceed with the commit @sc{cvs} will detect that 59425839Speterthe contents are not modified and treat it as an 59525839Speterunmodified file. The next @code{update} will clue 59625839Speter@sc{cvs} in to the fact that the file is unmodified, 59725839Speterand it will reset its stored timestamp so that the file 59825839Speterwill not show up in future editor sessions. 59925839Speter@c FIXCVS: Might be nice if "commit" and other commands 60025839Speter@c would reset that timestamp too, but currently commit 60125839Speter@c doesn't. 60232785Speter@c FIXME: Need to talk more about the process of 60332785Speter@c prompting for the log message. Like show an example 60432785Speter@c of what it pops up in the editor, for example. Also 60532785Speter@c a discussion of how to get the "a)bort, c)ontinue, 60632785Speter@c e)dit" prompt and what to do with it. Might also 60732785Speter@c work in the suggestion that if you want a diff, you 60832785Speter@c should make it before running commit (someone 60932785Speter@c suggested that the diff pop up in the editor. I'm 61032785Speter@c not sure that is better than telling people to run 61132785Speter@c "cvs diff" first if that is what they want, but if 61232785Speter@c we want to tell people that, the manual possibly 61332785Speter@c should say it). 61425839Speter 61525839SpeterIf you want to avoid 61617721Speterstarting an editor you can specify the log message on 61717721Speterthe command line using the @samp{-m} flag instead, like 61817721Speterthis: 61917721Speter 62017721Speter@example 62117721Speter$ cvs commit -m "Added an optimization pass" backend.c 62217721Speter@end example 62317721Speter 62417721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 62517721Speter@node Cleaning up 62632785Speter@subsection Cleaning up 62717721Speter@cindex Cleaning up 62817721Speter@cindex Working copy, removing 62917721Speter@cindex Removing your working copy 63017721Speter@cindex Releasing your working copy 63117721Speter 63217721SpeterBefore you turn to other tasks you decide to remove your working copy of 63317721Spetertc. One acceptable way to do that is of course 63417721Speter 63517721Speter@example 63617721Speter$ cd .. 63717721Speter$ rm -r tc 63817721Speter@end example 63917721Speter 64017721Speter@noindent 64117721Speterbut a better way is to use the @code{release} command (@pxref{release}): 64217721Speter 64317721Speter@example 64417721Speter$ cd .. 64517721Speter$ cvs release -d tc 64617721SpeterM driver.c 64717721Speter? tc 64817721SpeterYou have [1] altered files in this repository. 64954427SpeterAre you sure you want to release (and delete) directory `tc': n 65017721Speter** `release' aborted by user choice. 65117721Speter@end example 65217721Speter 65317721SpeterThe @code{release} command checks that all your modifications have been 65417721Spetercommitted. If history logging is enabled it also makes a note in the 65517721Speterhistory file. @xref{history file}. 65617721Speter 65717721SpeterWhen you use the @samp{-d} flag with @code{release}, it 65817721Speteralso removes your working copy. 65917721Speter 66017721SpeterIn the example above, the @code{release} command wrote a couple of lines 66117721Speterof output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. 66217721SpeterThat is nothing to worry about: @file{tc} is the executable compiler, 66317721Speterand it should not be stored in the repository. @xref{cvsignore}, 66417721Speterfor information about how to make that warning go away. 66517721Speter@xref{release output}, for a complete explanation of 66617721Speterall possible output from @code{release}. 66717721Speter 66817721Speter@samp{M driver.c} is more serious. It means that the 66917721Speterfile @file{driver.c} has been modified since it was 67017721Speterchecked out. 67117721Speter 67217721SpeterThe @code{release} command always finishes by telling 67317721Speteryou how many modified files you have in your working 67417721Spetercopy of the sources, and then asks you for confirmation 67517721Speterbefore deleting any files or making any note in the 67617721Speterhistory file. 67717721Speter 67817721SpeterYou decide to play it safe and answer @kbd{n @key{RET}} 67917721Speterwhen @code{release} asks for confirmation. 68017721Speter 68117721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 68217721Speter@node Viewing differences 68332785Speter@subsection Viewing differences 68417721Speter@cindex Viewing differences 68517721Speter@cindex Diff 68617721Speter 68717721SpeterYou do not remember modifying @file{driver.c}, so you want to see what 68817721Speterhas happened to that file. 68917721Speter 69017721Speter@example 69117721Speter$ cd tc 69217721Speter$ cvs diff driver.c 69317721Speter@end example 69417721Speter 69517721SpeterThis command runs @code{diff} to compare the version of @file{driver.c} 69617721Speterthat you checked out with your working copy. When you see the output 69717721Speteryou remember that you added a command line option that enabled the 69817721Speteroptimization pass. You check it in, and release the module. 69925839Speter@c FIXME: we haven't yet defined the term "check in". 70017721Speter 70117721Speter@example 70217721Speter$ cvs commit -m "Added an optimization pass" driver.c 70317721SpeterChecking in driver.c; 70417721Speter/usr/local/cvsroot/tc/driver.c,v <-- driver.c 70517721Speternew revision: 1.2; previous revision: 1.1 70617721Speterdone 70717721Speter$ cd .. 70817721Speter$ cvs release -d tc 70917721Speter? tc 71017721SpeterYou have [0] altered files in this repository. 71154427SpeterAre you sure you want to release (and delete) directory `tc': y 71217721Speter@end example 71317721Speter 71417721Speter@c --------------------------------------------------------------------- 71517721Speter@node Repository 71617721Speter@chapter The Repository 71725839Speter@cindex Repository (intro) 71817721Speter@cindex Repository, example 71917721Speter@cindex Layout of repository 72017721Speter@cindex Typical repository 72125839Speter@cindex /usr/local/cvsroot, as example repository 72217721Speter@cindex cvsroot 72317721Speter 72425839SpeterThe @sc{cvs} @dfn{repository} stores a complete copy of 72525839Speterall the files and directories which are under version 72625839Spetercontrol. 72717721Speter 72825839SpeterNormally, you never access any of the files in the 72925839Speterrepository directly. Instead, you use @sc{cvs} 73025839Spetercommands to get your own copy of the files into a 73125839Speter@dfn{working directory}, and then 73225839Speterwork on that copy. When you've finished a set of 73325839Speterchanges, you check (or @dfn{commit}) them back into the 73425839Speterrepository. The repository then contains the changes 73525839Speterwhich you have made, as well as recording exactly what 73625839Speteryou changed, when you changed it, and other such 73725839Speterinformation. Note that the repository is not a 73825839Spetersubdirectory of the working directory, or vice versa; 73925839Speterthey should be in separate locations. 74025839Speter@c Need some example, e.g. repository 74125839Speter@c /usr/local/cvsroot; working directory 74225839Speter@c /home/joe/sources. But this node is too long 74325839Speter@c as it is; need a little reorganization... 74417721Speter 74534461Speter@cindex :local:, setting up 74666525Speter@sc{cvs} can access a repository by a variety of 74725839Spetermeans. It might be on the local computer, or it might 74825839Speterbe on a computer across the room or across the world. 74925839SpeterTo distinguish various ways to access a repository, the 75025839Speterrepository name can start with an @dfn{access method}. 75125839SpeterFor example, the access method @code{:local:} means to 75225839Speteraccess a repository directory, so the repository 75325839Speter@code{:local:/usr/local/cvsroot} means that the 75425839Speterrepository is in @file{/usr/local/cvsroot} on the 75525839Spetercomputer running @sc{cvs}. For information on other 75625839Speteraccess methods, see @ref{Remote repositories}. 75717721Speter 75825839Speter@c Can se say this more concisely? Like by passing 75925839Speter@c more of the buck to the Remote repositories node? 76025839SpeterIf the access method is omitted, then if the repository 761102840Speterstarts with @samp{/}, then @code{:local:} is 762102840Speterassumed. If it does not start with @samp{/} then either 76325839Speter@code{:ext:} or @code{:server:} is assumed. For 76425839Speterexample, if you have a local repository in 76525839Speter@file{/usr/local/cvsroot}, you can use 76625839Speter@code{/usr/local/cvsroot} instead of 76725839Speter@code{:local:/usr/local/cvsroot}. But if (under 76825839SpeterWindows NT, for example) your local repository is 76925839Speter@file{c:\src\cvsroot}, then you must specify the access 770102840Spetermethod, as in @code{:local:c:/src/cvsroot}. 77125839Speter 77225839Speter@c This might appear to go in Repository storage, but 77325839Speter@c actually it is describing something which is quite 77425839Speter@c user-visible, when you do a "cvs co CVSROOT". This 77525839Speter@c isn't necessary the perfect place for that, though. 77625839SpeterThe repository is split in two parts. @file{$CVSROOT/CVSROOT} contains 77725839Speteradministrative files for @sc{cvs}. The other directories contain the actual 77825839Speteruser-defined modules. 77925839Speter 78025839Speter@menu 78125839Speter* Specifying a repository:: Telling CVS where your repository is 78225839Speter* Repository storage:: The structure of the repository 78325839Speter* Working directory storage:: The structure of working directories 78425839Speter* Intro administrative files:: Defining modules 78525839Speter* Multiple repositories:: Multiple repositories 78625839Speter* Creating a repository:: Creating a repository 78725839Speter* Backing up:: Backing up a repository 78826801Speter* Moving a repository:: Moving a repository 78925839Speter* Remote repositories:: Accessing repositories on remote machines 79025839Speter* Read-only access:: Granting read-only access to the repository 79125839Speter* Server temporary directory:: The server creates temporary directories 79225839Speter@end menu 79325839Speter 79425839Speter@node Specifying a repository 79525839Speter@section Telling CVS where your repository is 79625839Speter 79732785SpeterThere are several ways to tell @sc{cvs} 79817721Speterwhere to find the repository. You can name the 79917721Speterrepository on the command line explicitly, with the 80017721Speter@code{-d} (for "directory") option: 80117721Speter 80217721Speter@example 80317721Spetercvs -d /usr/local/cvsroot checkout yoyodyne/tc 80417721Speter@end example 80517721Speter 80625839Speter@cindex .profile, setting CVSROOT in 80725839Speter@cindex .cshrc, setting CVSROOT in 80825839Speter@cindex .tcshrc, setting CVSROOT in 80925839Speter@cindex .bashrc, setting CVSROOT in 81025839Speter@cindex CVSROOT, environment variable 81117721Speter Or you can set the @code{$CVSROOT} environment 81217721Spetervariable to an absolute path to the root of the 81317721Speterrepository, @file{/usr/local/cvsroot} in this example. 81432785SpeterTo set @code{$CVSROOT}, @code{csh} and @code{tcsh} 81517721Speterusers should have this line in their @file{.cshrc} or 81617721Speter@file{.tcshrc} files: 81717721Speter 81817721Speter@example 81917721Spetersetenv CVSROOT /usr/local/cvsroot 82017721Speter@end example 82117721Speter 82217721Speter@noindent 82317721Speter@code{sh} and @code{bash} users should instead have these lines in their 82417721Speter@file{.profile} or @file{.bashrc}: 82517721Speter 82617721Speter@example 82717721SpeterCVSROOT=/usr/local/cvsroot 82817721Speterexport CVSROOT 82917721Speter@end example 83017721Speter 83125839Speter@cindex Root file, in CVS directory 83225839Speter@cindex CVS/Root file 83317721Speter A repository specified with @code{-d} will 83417721Speteroverride the @code{$CVSROOT} environment variable. 83517721SpeterOnce you've checked a working copy out from the 83617721Speterrepository, it will remember where its repository is 83717721Speter(the information is recorded in the 83844852Speter@file{CVS/Root} file in the working copy). 83917721Speter 84025839SpeterThe @code{-d} option and the @file{CVS/Root} file both 84125839Speteroverride the @code{$CVSROOT} environment variable. If 84225839Speter@code{-d} option differs from @file{CVS/Root}, the 84354427Speterformer is used. Of course, for proper operation they 84454427Spetershould be two ways of referring to the same repository. 84517721Speter 84625839Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 84725839Speter@node Repository storage 84825839Speter@section How data is stored in the repository 84925839Speter@cindex Repository, how data is stored 85017721Speter 85125839SpeterFor most purposes it isn't important @emph{how} 85225839Speter@sc{cvs} stores information in the repository. In 85325839Speterfact, the format has changed in the past, and is likely 85425839Speterto change in the future. Since in almost all cases one 85532785Speteraccesses the repository via @sc{cvs} commands, such 85625839Speterchanges need not be disruptive. 85717721Speter 85825839SpeterHowever, in some cases it may be necessary to 85925839Speterunderstand how @sc{cvs} stores data in the repository, 86025839Speterfor example you might need to track down @sc{cvs} locks 86125839Speter(@pxref{Concurrency}) or you might need to deal with 86225839Speterthe file permissions appropriate for the repository. 86325839Speter 86417721Speter@menu 86525839Speter* Repository files:: What files are stored in the repository 86625839Speter* File permissions:: File permissions 86732785Speter* Windows permissions:: Issues specific to Windows 86825839Speter* Attic:: Some files are stored in the Attic 86932785Speter* CVS in repository:: Additional information in CVS directory 87032785Speter* Locks:: CVS locks control concurrent accesses 87132785Speter* CVSROOT storage:: A few things about CVSROOT are different 87217721Speter@end menu 87317721Speter 87425839Speter@node Repository files 87525839Speter@subsection Where files are stored within the repository 87617721Speter 87766525Speter@c @cindex Filenames, legal 87866525Speter@c @cindex Legal filenames 87932785Speter@c Somewhere we need to say something about legitimate 88044852Speter@c characters in filenames in working directory and 88132785Speter@c repository. Not "/" (not even on non-unix). And 88232785Speter@c here is a specific set of issues: 88332785Speter@c Files starting with a - are handled inconsistently. They can not 88432785Speter@c be added to a repository with an add command, because it they are 88532785Speter@c interpreted as a switch. They can appear in a repository if they are 88632785Speter@c part of a tree that is imported. They can not be removed from the tree 88732785Speter@c once they are there. 88832785Speter@c Note that "--" *is* supported (as a 88932785Speter@c consequence of using GNU getopt). Should document 89032785Speter@c this somewhere ("Common options"?). The other usual technique, 89132785Speter@c "./-foo", isn't as effective, at least for "cvs add" 89232785Speter@c which doesn't support pathnames containing "/". 89332785Speter 89425839SpeterThe overall structure of the repository is a directory 89525839Spetertree corresponding to the directories in the working 89625839Speterdirectory. For example, supposing the repository is in 89725839Speter 89817721Speter@example 89925839Speter/usr/local/cvsroot 90025839Speter@end example 90125839Speter 90225839Speter@noindent 90325839Speterhere is a possible directory tree (showing only the 90425839Speterdirectories): 90525839Speter 90625839Speter@example 90725839Speter@t{/usr} 90825839Speter | 90925839Speter +--@t{local} 91025839Speter | | 91125839Speter | +--@t{cvsroot} 91244852Speter | | | 91325839Speter | | +--@t{CVSROOT} 91444852Speter | (administrative files) 91544852Speter | 91625839Speter +--@t{gnu} 91744852Speter | | 91825839Speter | +--@t{diff} 91944852Speter | | (source code to @sc{gnu} diff) 92044852Speter | | 92125839Speter | +--@t{rcs} 92225839Speter | | (source code to @sc{rcs}) 92344852Speter | | 92425839Speter | +--@t{cvs} 92544852Speter | (source code to @sc{cvs}) 92644852Speter | 92725839Speter +--@t{yoyodyne} 92844852Speter | 92925839Speter +--@t{tc} 93025839Speter | | 93125839Speter | +--@t{man} 93225839Speter | | 93325839Speter | +--@t{testing} 93444852Speter | 93525839Speter +--(other Yoyodyne software) 93644852Speter@end example 93725839Speter 93825839SpeterWith the directories are @dfn{history files} for each file 93925839Speterunder version control. The name of the history file is 94025839Speterthe name of the corresponding file with @samp{,v} 94125839Speterappended to the end. Here is what the repository for 94225839Speterthe @file{yoyodyne/tc} directory might look like: 94325839Speter@c FIXME: Should also mention CVS (CVSREP) 94425839Speter@c FIXME? Should we introduce Attic with an xref to 94525839Speter@c Attic? Not sure whether that is a good idea or not. 94625839Speter@example 94717721Speter @code{$CVSROOT} 94817721Speter | 94917721Speter +--@t{yoyodyne} 95017721Speter | | 95117721Speter | +--@t{tc} 95217721Speter | | | 95317721Speter +--@t{Makefile,v} 95417721Speter +--@t{backend.c,v} 95517721Speter +--@t{driver.c,v} 95617721Speter +--@t{frontend.c,v} 95717721Speter +--@t{parser.c,v} 95817721Speter +--@t{man} 95917721Speter | | 96017721Speter | +--@t{tc.1,v} 96144852Speter | 96217721Speter +--@t{testing} 96317721Speter | 96417721Speter +--@t{testpgm.t,v} 96517721Speter +--@t{test2.t,v} 96617721Speter@end example 96717721Speter 96817721Speter@cindex History files 96917721Speter@cindex RCS history files 97025839Speter@c The first sentence, about what history files 97125839Speter@c contain, is kind of redundant with our intro to what the 97225839Speter@c repository does in node Repository.... 97325839SpeterThe history files contain, among other things, enough 97417721Speterinformation to recreate any revision of the file, a log 97517721Speterof all commit messages and the user-name of the person 97625839Speterwho committed the revision. The history files are 97725839Speterknown as @dfn{RCS files}, because the first program to 97825839Speterstore files in that format was a version control system 97925839Speterknown as @sc{rcs}. For a full 98017721Speterdescription of the file format, see the @code{man} page 98132785Speter@cite{rcsfile(5)}, distributed with @sc{rcs}, or the 98232785Speterfile @file{doc/RCSFILES} in the @sc{cvs} source 98332785Speterdistribution. This 98425839Speterfile format has become very common---many systems other 98525839Speterthan @sc{cvs} or @sc{rcs} can at least import history 98625839Speterfiles in this format. 98725839Speter@c FIXME: Think about including documentation for this 98825839Speter@c rather than citing it? In the long run, getting 98925839Speter@c this to be a standard (not sure if we can cope with 99025839Speter@c a standards process as formal as IEEE/ANSI/ISO/etc, 99125839Speter@c though...) is the way to go, so maybe citing is 99225839Speter@c better. 99317721Speter 99425839SpeterThe @sc{rcs} files used in @sc{cvs} differ in a few 99525839Speterways from the standard format. The biggest difference 99625839Speteris magic branches; for more information see @ref{Magic 99725839Speterbranch numbers}. Also in @sc{cvs} the valid tag names 99825839Speterare a subset of what @sc{rcs} accepts; for @sc{cvs}'s 99925839Speterrules see @ref{Tags}. 100017721Speter 100117721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100217721Speter@node File permissions 100317721Speter@subsection File permissions 100425839Speter@c -- Move this to @node Creating a repository or similar 100532785Speter@cindex Security, file permissions in repository 100632785Speter@cindex File permissions, general 100766525Speter@cindex Permissions, general 100832785Speter@c FIXME: we need to somehow reflect "permissions in 100932785Speter@c repository" versus "permissions in working 101032785Speter@c directory" in the index entries. 1011130303Speter@cindex Group, UNIX file permissions, in repository 101266525Speter@cindex Read-only files, in repository 101317721SpeterAll @samp{,v} files are created read-only, and you 101417721Spetershould not change the permission of those files. The 101517721Speterdirectories inside the repository should be writable by 101617721Speterthe persons that have permission to modify the files in 101717721Spetereach directory. This normally means that you must 101817721Spetercreate a UNIX group (see group(5)) consisting of the 101917721Speterpersons that are to edit the files in a project, and 102017721Speterset up the repository so that it is that group that 102117721Speterowns the directory. 1022102840Speter(On some systems, you also need to set the set-group-ID-on-execution bit 1023102840Speteron the repository directories (see chmod(1)) so that newly-created files 1024102840Speterand directories get the group-ID of the parent directory rather than 1025102840Speterthat of the current process.) 1026102840Speter 102725839Speter@c See also comment in commitinfo node regarding cases 102825839Speter@c which are really awkward with unix groups. 102917721Speter 103017721SpeterThis means that you can only control access to files on 103117721Spetera per-directory basis. 103217721Speter 103325839SpeterNote that users must also have write access to check 103425839Speterout files, because @sc{cvs} needs to create lock files 1035102840Speter(@pxref{Concurrency}). You can use LockDir in CVSROOT/config 1036102840Speterto put the lock files somewhere other than in the repository 1037102840Speterif you want to allow read-only access to some directories 1038102840Speter(@pxref{config}). 103925839Speter 104025839Speter@c CVS seems to use CVSUMASK in picking permissions for 104125839Speter@c val-tags, but maybe we should say more about this. 104225839Speter@c Like val-tags gets created by someone who doesn't 104325839Speter@c have CVSUMASK set right? 1044128266Speter@cindex CVSROOT/val-tags file, and read-only access to projects 1045128266Speter@cindex val-tags file, and read-only access to projects 104625839SpeterAlso note that users must have write access to the 104766525Speter@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep 104825839Spetertrack of what tags are valid tag names (it is sometimes 104925839Speterupdated when tags are used, as well as when they are 105032785Spetercreated). 105125839Speter 105232785SpeterEach @sc{rcs} file will be owned by the user who last 105332785Speterchecked it in. This has little significance; what 105432785Speterreally matters is who owns the directories. 105532785Speter 105632785Speter@cindex CVSUMASK, environment variable 105766525Speter@cindex Umask, for repository files 105817721Speter@sc{cvs} tries to set up reasonable file permissions 105917721Speterfor new directories that are added inside the tree, but 106017721Speteryou must fix the permissions manually when a new 106117721Speterdirectory should have different permissions than its 106225839Speterparent directory. If you set the @code{CVSUMASK} 1063177391Sobrienenvironment variable, that will control the file 106425839Speterpermissions which @sc{cvs} uses in creating directories 106525839Speterand/or files in the repository. @code{CVSUMASK} does 106625839Speternot affect the file permissions in the working 106725839Speterdirectory; such files have the permissions which are 106825839Spetertypical for newly created files, except that sometimes 106925839Speter@sc{cvs} creates them read-only (see the sections on 107025839Speterwatches, @ref{Setting a watch}; -r, @ref{Global 107166525Speteroptions}; or @code{CVSREAD}, @ref{Environment variables}). 107232785Speter@c FIXME: Need more discussion of which 107332785Speter@c group should own the file in the repository. 107426801Speter@c Include a somewhat detailed example of the usual 107526801Speter@c case where CVSUMASK is 007, the developers are all 107626801Speter@c in a group, and that group owns stuff in the 107726801Speter@c repository. Need to talk about group ownership of 107826801Speter@c newly-created directories/files (on some unices, 107926801Speter@c such as SunOS4, setting the setgid bit on the 108026801Speter@c directories will make files inherit the directory's 108126801Speter@c group. On other unices, your mileage may vary. I 108226801Speter@c can't remember what POSIX says about this, if 108326801Speter@c anything). 108417721Speter 108525839SpeterNote that using the client/server @sc{cvs} 108625839Speter(@pxref{Remote repositories}), there is no good way to 108725839Speterset @code{CVSUMASK}; the setting on the client machine 108825839Speterhas no effect. If you are connecting with @code{rsh}, you 108925839Spetercan set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as 109025839Speterdescribed in the documentation for your operating 109125839Spetersystem. This behavior might change in future versions 109225839Speterof @sc{cvs}; do not rely on the setting of 109325839Speter@code{CVSUMASK} on the client having no effect. 109425839Speter@c FIXME: need to explain what a umask is or cite 109525839Speter@c someplace which does. 109644852Speter@c 109732785Speter@c There is also a larger (largely separate) issue 109832785Speter@c about the meaning of CVSUMASK in a non-unix context. 109932785Speter@c For example, whether there is 110032785Speter@c an equivalent which fits better into other 110132785Speter@c protection schemes like POSIX.6, VMS, &c. 110244852Speter@c 110325839Speter@c FIXME: Need one place which discusses this 110425839Speter@c read-only files thing. Why would one use -r or 110532785Speter@c CVSREAD? Why would one use watches? How do they 110632785Speter@c interact? 110744852Speter@c 110825839Speter@c FIXME: We need to state 110925839Speter@c whether using CVSUMASK removes the need for manually 111025839Speter@c fixing permissions (in fact, if we are going to mention 111125839Speter@c manually fixing permission, we better document a lot 111225839Speter@c better just what we mean by "fix"). 111325839Speter 111432785SpeterUsing pserver, you will generally need stricter 111532785Speterpermissions on the @sc{cvsroot} directory and 111632785Speterdirectories above it in the tree; see @ref{Password 111732785Speterauthentication security}. 111832785Speter 111966525Speter@cindex Setuid 112066525Speter@cindex Setgid 112166525Speter@cindex Security, setuid 112266525Speter@cindex Installed images (VMS) 112332785SpeterSome operating systems have features which allow a 112432785Speterparticular program to run with the ability to perform 112532785Speteroperations which the caller of the program could not. 112632785SpeterFor example, the set user ID (setuid) or set group ID 112732785Speter(setgid) features of unix or the installed image 112881404Speterfeature of VMS. @sc{cvs} was not written to use such 112981404Speterfeatures and therefore attempting to install @sc{cvs} in 113032785Speterthis fashion will provide protection against only 113132785Speteraccidental lapses; anyone who is trying to circumvent 113232785Speterthe measure will be able to do so, and depending on how 113332785Speteryou have set it up may gain access to more than just 113481404Speter@sc{cvs}. You may wish to instead consider pserver. It 113532785Spetershares some of the same attributes, in terms of 113632785Speterpossibly providing a false sense of security or opening 113732785Spetersecurity holes wider than the ones you are trying to 113832785Speterfix, so read the documentation on pserver security 113932785Spetercarefully if you are considering this option 114032785Speter(@ref{Password authentication security}). 114117721Speter 114232785Speter@node Windows permissions 114332785Speter@subsection File Permission issues specific to Windows 114432785Speter@cindex Windows, and permissions 114532785Speter@cindex File permissions, Windows-specific 114666525Speter@cindex Permissions, Windows-specific 114732785Speter 114832785SpeterSome file permission issues are specific to Windows 114932785Speteroperating systems (Windows 95, Windows NT, and 115032785Speterpresumably future operating systems in this family. 115132785SpeterSome of the following might apply to OS/2 but I'm not 115232785Spetersure). 115332785Speter 115481404SpeterIf you are using local @sc{cvs} and the repository is on a 115532785Speternetworked file system which is served by the Samba SMB 115632785Speterserver, some people have reported problems with 115732785Speterpermissions. Enabling WRITE=YES in the samba 115832785Speterconfiguration is said to fix/workaround it. 115932785SpeterDisclaimer: I haven't investigated enough to know the 116032785Speterimplications of enabling that option, nor do I know 116181404Speterwhether there is something which @sc{cvs} could be doing 116232785Speterdifferently in order to avoid the problem. If you find 116332785Spetersomething out, please let us know as described in 116432785Speter@ref{BUGS}. 116532785Speter 116625839Speter@node Attic 116725839Speter@subsection The attic 116866525Speter@cindex Attic 116925839Speter 117025839SpeterYou will notice that sometimes @sc{cvs} stores an 117125839Speter@sc{rcs} file in the @code{Attic}. For example, if the 117225839Speter@sc{cvsroot} is @file{/usr/local/cvsroot} and we are 117325839Spetertalking about the file @file{backend.c} in the 117425839Speterdirectory @file{yoyodyne/tc}, then the file normally 117525839Speterwould be in 117625839Speter 117725839Speter@example 117825839Speter/usr/local/cvsroot/yoyodyne/tc/backend.c,v 117925839Speter@end example 118025839Speter 1181102840Speter@noindent 118225839Speterbut if it goes in the attic, it would be in 118325839Speter 118425839Speter@example 118525839Speter/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v 118625839Speter@end example 118725839Speter 1188102840Speter@noindent 118966525Speter@cindex Dead state 119025839Speterinstead. It should not matter from a user point of 119125839Speterview whether a file is in the attic; @sc{cvs} keeps 119225839Spetertrack of this and looks in the attic when it needs to. 119325839SpeterBut in case you want to know, the rule is that the RCS 119425839Speterfile is stored in the attic if and only if the head 119525839Speterrevision on the trunk has state @code{dead}. A 119625839Speter@code{dead} state means that file has been removed, or 119725839Speternever added, for that revision. For example, if you 119825839Speteradd a file on a branch, it will have a trunk revision 119925839Speterin @code{dead} state, and a branch revision in a 120025839Speternon-@code{dead} state. 120125839Speter@c Probably should have some more concrete examples 120225839Speter@c here, or somewhere (not sure exactly how we should 120325839Speter@c arrange the discussion of the dead state, versus 120425839Speter@c discussion of the attic). 120525839Speter 120632785Speter@node CVS in repository 120732785Speter@subsection The CVS directory in the repository 120832785Speter@cindex CVS directory, in repository 120932785Speter 121032785SpeterThe @file{CVS} directory in each repository directory 121132785Spetercontains information such as file attributes (in a file 121254427Spetercalled @file{CVS/fileattr}. In the 121332785Speterfuture additional files may be added to this directory, 121432785Speterso implementations should silently ignore additional 121532785Speterfiles. 121632785Speter 121732785SpeterThis behavior is implemented only by @sc{cvs} 1.7 and 121832785Speterlater; for details see @ref{Watches Compatibility}. 121932785Speter 1220130303SpeterThe format of the @file{fileattr} file is a series of entries 122154427Speterof the following form (where @samp{@{} and @samp{@}} 122254427Spetermeans the text between the braces can be repeated zero 122354427Speteror more times): 122454427Speter 122554427Speter@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} 122654427Speter @{; @var{attrname} = @var{attrval}@} <linefeed> 122754427Speter 122854427Speter@var{ent-type} is @samp{F} for a file, in which case the entry specifies the 122954427Speterattributes for that file. 123054427Speter 123154427Speter@var{ent-type} is @samp{D}, 123254427Speterand @var{filename} empty, to specify default attributes 123354427Speterto be used for newly added files. 123454427Speter 123581404SpeterOther @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older 123654427Speterwill delete them any time it writes file attributes. 123781404Speter@sc{cvs} 1.10 and later will preserve them. 123854427Speter 123954427SpeterNote that the order of the lines is not significant; 124054427Spetera program writing the fileattr file may 124154427Speterrearrange them at its convenience. 124254427Speter 1243130303SpeterThere is currently no way of quoting tabs or line feeds in the 124454427Speterfilename, @samp{=} in @var{attrname}, 124554427Speter@samp{;} in @var{attrval}, etc. Note: some implementations also 124654427Speterdon't handle a NUL character in any of the fields, but 124754427Speterimplementations are encouraged to allow it. 124854427Speter 124954427SpeterBy convention, @var{attrname} starting with @samp{_} is for an attribute given 125081404Speterspecial meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes 125154427Speter(or will be, once implementations start supporting user-defined attributes). 125254427Speter 1253130303SpeterBuilt-in attributes: 125454427Speter 125554427Speter@table @code 125654427Speter@item _watched 125754427SpeterPresent means the file is watched and should be checked out 125854427Speterread-only. 125954427Speter 126054427Speter@item _watchers 126154427SpeterUsers with watches for this file. Value is 126254427Speter@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} 126354427Speterwhere @var{watcher} is a username, and @var{type} 126454427Speteris zero or more of edit,unedit,commit separated by 126554427Speter@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). 126654427Speter 126754427Speter@item _editors 126854427SpeterUsers editing this file. Value is 126954427Speter@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} 127054427Speterwhere @var{editor} is a username, and @var{val} is 127154427Speter@var{time}+@var{hostname}+@var{pathname}, where 127254427Speter@var{time} is when the @code{cvs edit} command (or 127354427Speterequivalent) happened, 127454427Speterand @var{hostname} and @var{pathname} are for the working directory. 127554427Speter@end table 127654427Speter 127754427SpeterExample: 127854427Speter 127954427Speter@c FIXME: sanity.sh should contain a similar test case 128054427Speter@c so we can compare this example from something from 128154427Speter@c Real Life(TM). See cvsclient.texi (under Notify) for more 128254427Speter@c discussion of the date format of _editors. 128354427Speter@example 128454427SpeterFfile1 _watched=;_watchers=joe>edit,mary>commit 128554427SpeterFfile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs 128654427SpeterD _watched= 128754427Speter@end example 128854427Speter 1289102840Speter@noindent 129054427Spetermeans that the file @file{file1} should be checked out 129154427Speterread-only. Furthermore, joe is watching for edits and 129254427Spetermary is watching for commits. The file @file{file2} 129354427Spetershould be checked out read-only; sue started editing it 129454427Speteron 8 Jan 1975 in the directory @file{/home/sue/cvs} on 129554427Speterthe machine @code{workstn1}. Future files which are 129654427Speteradded should be checked out read-only. To represent 129754427Speterthis example here, we have shown a space after 129854427Speter@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact 129954427Speterthere must be a single tab character there and no spaces. 130054427Speter 130132785Speter@node Locks 130232785Speter@subsection CVS locks in the repository 130332785Speter 130444852Speter@cindex #cvs.rfl, technical details 130544852Speter@cindex #cvs.wfl, technical details 130644852Speter@cindex #cvs.lock, technical details 130766525Speter@cindex Locks, cvs, technical details 130881404SpeterFor an introduction to @sc{cvs} locks focusing on 130932785Speteruser-visible behavior, see @ref{Concurrency}. The 131032785Speterfollowing section is aimed at people who are writing 131181404Spetertools which want to access a @sc{cvs} repository without 1312130303Speterinterfering with other tools accessing the same 131332785Speterrepository. If you find yourself confused by concepts 131432785Speterdescribed here, like @dfn{read lock}, @dfn{write lock}, 131532785Speterand @dfn{deadlock}, you might consult the literature on 131632785Speteroperating systems or databases. 131732785Speter 131844852Speter@cindex #cvs.tfl 131932785SpeterAny file in the repository with a name starting 132054427Speterwith @file{#cvs.rfl.} is a read lock. Any file in 132132785Speterthe repository with a name starting with 132281404Speter@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} 132381404Speter(before @sc{cvs} 1.5) also created files with names starting 132432785Speterwith @file{#cvs.tfl}, but they are not discussed here. 132532785SpeterThe directory @file{#cvs.lock} serves as a master 132632785Speterlock. That is, one must obtain this lock first before 132732785Spetercreating any of the other locks. 132832785Speter 1329130303SpeterTo obtain a read lock, first create the @file{#cvs.lock} 133032785Speterdirectory. This operation must be atomic (which should 133132785Speterbe true for creating a directory under most operating 133232785Spetersystems). If it fails because the directory already 133332785Speterexisted, wait for a while and try again. After 133432785Speterobtaining the @file{#cvs.lock} lock, create a file 133554427Speterwhose name is @file{#cvs.rfl.} followed by information 133632785Speterof your choice (for example, hostname and process 133732785Speteridentification number). Then remove the 133832785Speter@file{#cvs.lock} directory to release the master lock. 133932785SpeterThen proceed with reading the repository. When you are 134032785Speterdone, remove the @file{#cvs.rfl} file to release the 134132785Speterread lock. 134232785Speter 1343130303SpeterTo obtain a write lock, first create the 1344130303Speter@file{#cvs.lock} directory, as with read locks. Then 134532785Spetercheck that there are no files whose names start with 134654427Speter@file{#cvs.rfl.}. If there are, remove 134732785Speter@file{#cvs.lock}, wait for a while, and try again. If 134832785Speterthere are no readers, then create a file whose name is 134932785Speter@file{#cvs.wfl} followed by information of your choice 135032785Speter(for example, hostname and process identification 135132785Speternumber). Hang on to the @file{#cvs.lock} lock. Proceed 135232785Speterwith writing the repository. When you are done, first 135332785Speterremove the @file{#cvs.wfl} file and then the 135432785Speter@file{#cvs.lock} directory. Note that unlike the 135532785Speter@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just 135632785Speterinformational; it has no effect on the locking operation 135732785Speterbeyond what is provided by holding on to the 135832785Speter@file{#cvs.lock} lock itself. 135932785Speter 1360130303SpeterNote that each lock (write lock or read lock) only locks 136132785Spetera single directory in the repository, including 136232785Speter@file{Attic} and @file{CVS} but not including 136332785Spetersubdirectories which represent other directories under 136432785Speterversion control. To lock an entire tree, you need to 136532785Speterlock each directory (note that if you fail to obtain 136632785Speterany lock you need, you must release the whole tree 136732785Speterbefore waiting and trying again, to avoid deadlocks). 136832785Speter 1369130303SpeterNote also that @sc{cvs} expects write locks to control 137032785Speteraccess to individual @file{foo,v} files. @sc{rcs} has 137132785Spetera scheme where the @file{,foo,} file serves as a lock, 137232785Speterbut @sc{cvs} does not implement it and so taking out a 1373130303Speter@sc{cvs} write lock is recommended. See the comments at 137432785Speterrcs_internal_lockfile in the @sc{cvs} source code for 137532785Speterfurther discussion/rationale. 137632785Speter 137732785Speter@node CVSROOT storage 137832785Speter@subsection How files are stored in the CVSROOT directory 137932785Speter@cindex CVSROOT, storage of files 138032785Speter 138132785SpeterThe @file{$CVSROOT/CVSROOT} directory contains the 138232785Spetervarious administrative files. In some ways this 138332785Speterdirectory is just like any other directory in the 138432785Speterrepository; it contains @sc{rcs} files whose names end 138532785Speterin @samp{,v}, and many of the @sc{cvs} commands operate 138632785Speteron it the same way. However, there are a few 138732785Speterdifferences. 138832785Speter 138932785SpeterFor each administrative file, in addition to the 139032785Speter@sc{rcs} file, there is also a checked out copy of the 139132785Speterfile. For example, there is an @sc{rcs} file 139244852Speter@file{loginfo,v} and a file @file{loginfo} which 139332785Spetercontains the latest revision contained in 139432785Speter@file{loginfo,v}. When you check in an administrative 139544852Speterfile, @sc{cvs} should print 139632785Speter 139732785Speter@example 139832785Spetercvs commit: Rebuilding administrative file database 139932785Speter@end example 140032785Speter 140132785Speter@noindent 140232785Speterand update the checked out copy in 140332785Speter@file{$CVSROOT/CVSROOT}. If it does not, there is 140432785Spetersomething wrong (@pxref{BUGS}). To add your own files 140532785Speterto the files to be updated in this fashion, you can add 140654427Speterthem to the @file{checkoutlist} administrative file 140754427Speter(@pxref{checkoutlist}). 140832785Speter 140932785Speter@cindex modules.db 141032785Speter@cindex modules.pag 141132785Speter@cindex modules.dir 141232785SpeterBy default, the @file{modules} file behaves as 141332785Speterdescribed above. If the modules file is very large, 141432785Speterstoring it as a flat text file may make looking up 141532785Spetermodules slow (I'm not sure whether this is as much of a 141632785Speterconcern now as when @sc{cvs} first evolved this 141732785Speterfeature; I haven't seen benchmarks). Therefore, by 141832785Spetermaking appropriate edits to the @sc{cvs} source code 141932785Speterone can store the modules file in a database which 142032785Speterimplements the @code{ndbm} interface, such as Berkeley 142132785Speterdb or GDBM. If this option is in use, then the modules 142232785Speterdatabase will be stored in the files @file{modules.db}, 142332785Speter@file{modules.pag}, and/or @file{modules.dir}. 142432785Speter@c I think fileattr also will use the database stuff. 142532785Speter@c Anything else? 142632785Speter 142732785SpeterFor information on the meaning of the various 142832785Speteradministrative files, see @ref{Administrative files}. 142932785Speter 143025839Speter@node Working directory storage 143125839Speter@section How data is stored in the working directory 143225839Speter 143326801Speter@c FIXME: Somewhere we should discuss timestamps (test 143426801Speter@c case "stamps" in sanity.sh). But not here. Maybe 143526801Speter@c in some kind of "working directory" chapter which 143626801Speter@c would encompass the "Builds" one? But I'm not sure 143726801Speter@c whether that is a good organization (is it based on 143826801Speter@c what the user wants to do?). 143926801Speter 144032785Speter@cindex CVS directory, in working directory 144125839SpeterWhile we are discussing @sc{cvs} internals which may 144225839Speterbecome visible from time to time, we might as well talk 144325839Speterabout what @sc{cvs} puts in the @file{CVS} directories 144425839Speterin the working directories. As with the repository, 144525839Speter@sc{cvs} handles this information and one can usually 144625839Speteraccess it via @sc{cvs} commands. But in some cases it 144725839Spetermay be useful to look at it, and other programs, such 144825839Speteras the @code{jCVS} graphical user interface or the 144925839Speter@code{VC} package for emacs, may need to look at it. 145025839SpeterSuch programs should follow the recommendations in this 145125839Spetersection if they hope to be able to work with other 145225839Speterprograms which use those files, including future 145325839Speterversions of the programs just mentioned and the 145425839Spetercommand-line @sc{cvs} client. 145525839Speter 145625839SpeterThe @file{CVS} directory contains several files. 145725839SpeterPrograms which are reading this directory should 145825839Spetersilently ignore files which are in the directory but 145925839Speterwhich are not documented here, to allow for future 146025839Speterexpansion. 146125839Speter 146254427SpeterThe files are stored according to the text file 146354427Speterconvention for the system in question. This means that 146454427Speterworking directories are not portable between systems 146554427Speterwith differing conventions for storing text files. 146654427SpeterThis is intentional, on the theory that the files being 146781404Spetermanaged by @sc{cvs} probably will not be portable between 146854427Spetersuch systems either. 146954427Speter 147025839Speter@table @file 147125839Speter@item Root 147225839SpeterThis file contains the current @sc{cvs} root, as 147325839Speterdescribed in @ref{Specifying a repository}. 147425839Speter 147525839Speter@cindex Repository file, in CVS directory 147625839Speter@cindex CVS/Repository file 147725839Speter@item Repository 147825839SpeterThis file contains the directory within the repository 147932785Speterwhich the current directory corresponds with. It can 148032785Speterbe either an absolute pathname or a relative pathname; 148132785Speter@sc{cvs} has had the ability to read either format 148232785Spetersince at least version 1.3 or so. The relative 148332785Speterpathname is relative to the root, and is the more 148432785Spetersensible approach, but the absolute pathname is quite 148532785Spetercommon and implementations should accept either. For 148632785Speterexample, after the command 148725839Speter 148825839Speter@example 148925839Spetercvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc 149025839Speter@end example 149125839Speter 1492102840Speter@noindent 149325839Speter@file{Root} will contain 149425839Speter 149525839Speter@example 149625839Speter:local:/usr/local/cvsroot 149725839Speter@end example 149825839Speter 1499102840Speter@noindent 150032785Speterand @file{Repository} will contain either 150125839Speter 150225839Speter@example 150332785Speter/usr/local/cvsroot/yoyodyne/tc 150425839Speter@end example 150525839Speter 150632785Speter@noindent 150732785Speteror 150832785Speter 150932785Speter@example 151032785Speteryoyodyne/tc 151132785Speter@end example 151232785Speter 151354427SpeterIf the particular working directory does not correspond 151454427Speterto a directory in the repository, then @file{Repository} 151554427Spetershould contain @file{CVSROOT/Emptydir}. 1516102840Speter@cindex Emptydir, in CVSROOT directory 1517102840Speter@cindex CVSROOT/Emptydir directory 151854427Speter 151925839Speter@cindex Entries file, in CVS directory 152025839Speter@cindex CVS/Entries file 152125839Speter@item Entries 152225839SpeterThis file lists the files and directories in the 152354427Speterworking directory. 152425839SpeterThe first character of each line indicates what sort of 152525839Speterline it is. If the character is unrecognized, programs 152625839Speterreading the file should silently skip that line, to 152725839Speterallow for future expansion. 152825839Speter 152925839SpeterIf the first character is @samp{/}, then the format is: 153025839Speter 153125839Speter@example 153225839Speter/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate} 153325839Speter@end example 153425839Speter 1535102840Speter@noindent 153625839Speterwhere @samp{[} and @samp{]} are not part of the entry, 153725839Speterbut instead indicate that the @samp{+} and conflict 153825839Spetermarker are optional. @var{name} is the name of the 153925839Speterfile within the directory. @var{revision} is the 154025839Speterrevision that the file in the working derives from, or 154125839Speter@samp{0} for an added file, or @samp{-} followed by a 154225839Speterrevision for a removed file. @var{timestamp} is the 154325839Spetertimestamp of the file at the time that @sc{cvs} created 154425839Speterit; if the timestamp differs with the actual 154525839Spetermodification time of the file it means the file has 154654427Speterbeen modified. It is stored in 154725839Speterthe format used by the ISO C asctime() function (for 154825839Speterexample, @samp{Sun Apr 7 01:29:26 1996}). One may 154925839Speterwrite a string which is not in that format, for 155025839Speterexample, @samp{Result of merge}, to indicate that the 155125839Speterfile should always be considered to be modified. This 155225839Speteris not a special case; to see whether a file is 155325839Spetermodified a program should take the timestamp of the file 155425839Speterand simply do a string compare with @var{timestamp}. 155554427SpeterIf there was a conflict, @var{conflict} can be set to 155654427Speterthe modification time of the file after the file has been 155754427Speterwritten with conflict markers (@pxref{Conflicts example}). 155854427SpeterThus if @var{conflict} is subsequently the same as the actual 155925839Spetermodification time of the file it means that the user 156025839Speterhas obviously not resolved the conflict. @var{options} 156125839Spetercontains sticky options (for example @samp{-kb} for a 156225839Speterbinary file). @var{tagdate} contains @samp{T} followed 156325839Speterby a tag name, or @samp{D} for a date, followed by a 156425839Spetersticky tag or date. Note that if @var{timestamp} 156525839Spetercontains a pair of timestamps separated by a space, 156625839Speterrather than a single timestamp, you are dealing with a 156725839Speterversion of @sc{cvs} earlier than @sc{cvs} 1.5 (not 156825839Speterdocumented here). 156925839Speter 157054427SpeterThe timezone on the timestamp in CVS/Entries (local or 157154427Speteruniversal) should be the same as the operating system 157254427Speterstores for the timestamp of the file itself. For 157354427Speterexample, on Unix the file's timestamp is in universal 157454427Spetertime (UT), so the timestamp in CVS/Entries should be 157554427Spetertoo. On @sc{vms}, the file's timestamp is in local 157654427Spetertime, so @sc{cvs} on @sc{vms} should use local time. 157754427SpeterThis rule is so that files do not appear to be modified 157854427Spetermerely because the timezone changed (for example, to or 157954427Speterfrom summer time). 158054427Speter@c See comments and calls to gmtime() and friends in 158154427Speter@c src/vers_ts.c (function time_stamp). 158254427Speter 158325839SpeterIf the first character of a line in @file{Entries} is 158425839Speter@samp{D}, then it indicates a subdirectory. @samp{D} 158525839Speteron a line all by itself indicates that the program 158625839Speterwhich wrote the @file{Entries} file does record 158725839Spetersubdirectories (therefore, if there is such a line and 158825839Speterno other lines beginning with @samp{D}, one knows there 158925839Speterare no subdirectories). Otherwise, the line looks 159025839Speterlike: 159125839Speter 159225839Speter@example 159325839SpeterD/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} 159425839Speter@end example 159525839Speter 1596102840Speter@noindent 159725839Speterwhere @var{name} is the name of the subdirectory, and 159825839Speterall the @var{filler} fields should be silently ignored, 159925839Speterfor future expansion. Programs which modify 160025839Speter@code{Entries} files should preserve these fields. 160125839Speter 160254427SpeterThe lines in the @file{Entries} file can be in any order. 160354427Speter 160425839Speter@cindex Entries.Log file, in CVS directory 160525839Speter@cindex CVS/Entries.Log file 160625839Speter@item Entries.Log 160725839SpeterThis file does not record any information beyond that 160825839Speterin @file{Entries}, but it does provide a way to update 160925839Speterthe information without having to rewrite the entire 161025839Speter@file{Entries} file, including the ability to preserve 161125839Speterthe information even if the program writing 161225839Speter@file{Entries} and @file{Entries.Log} abruptly aborts. 161325839SpeterPrograms which are reading the @file{Entries} file 161425839Spetershould also check for @file{Entries.Log}. If the latter 161525839Speterexists, they should read @file{Entries} and then apply 161625839Speterthe changes mentioned in @file{Entries.Log}. After 161725839Speterapplying the changes, the recommended practice is to 161825839Speterrewrite @file{Entries} and then delete @file{Entries.Log}. 161925839SpeterThe format of a line in @file{Entries.Log} is a single 162025839Spetercharacter command followed by a space followed by a 162125839Speterline in the format specified for a line in 162225839Speter@file{Entries}. The single character command is 162325839Speter@samp{A} to indicate that the entry is being added, 162425839Speter@samp{R} to indicate that the entry is being removed, 162525839Speteror any other character to indicate that the entire line 162625839Speterin @file{Entries.Log} should be silently ignored (for 162725839Speterfuture expansion). If the second character of the line 162825839Speterin @file{Entries.Log} is not a space, then it was 162925839Speterwritten by an older version of @sc{cvs} (not documented 163025839Speterhere). 163125839Speter 163254427SpeterPrograms which are writing rather than reading can 163354427Spetersafely ignore @file{Entries.Log} if they so choose. 163454427Speter 163525839Speter@cindex Entries.Backup file, in CVS directory 163625839Speter@cindex CVS/Entries.Backup file 163725839Speter@item Entries.Backup 163825839SpeterThis is a temporary file. Recommended usage is to 163925839Speterwrite a new entries file to @file{Entries.Backup}, and 164025839Speterthen to rename it (atomically, where possible) to @file{Entries}. 164125839Speter 164225839Speter@cindex Entries.Static file, in CVS directory 164325839Speter@cindex CVS/Entries.Static file 164425839Speter@item Entries.Static 164525839SpeterThe only relevant thing about this file is whether it 164625839Speterexists or not. If it exists, then it means that only 164725839Speterpart of a directory was gotten and @sc{cvs} will 164825839Speternot create additional files in that directory. To 164925839Speterclear it, use the @code{update} command with the 165025839Speter@samp{-d} option, which will get the additional files 165125839Speterand remove @file{Entries.Static}. 165232785Speter@c FIXME: This needs to be better documented, in places 165332785Speter@c other than Working Directory Storage. 165432785Speter@c FIXCVS: The fact that this setting exists needs to 165532785Speter@c be more visible to the user. For example "cvs 165632785Speter@c status foo", in the case where the file would be 165732785Speter@c gotten except for Entries.Static, might say 165832785Speter@c something to distinguish this from other cases. 165932785Speter@c One thing that periodically gets suggested is to 166032785Speter@c have "cvs update" print something when it skips 166132785Speter@c files due to Entries.Static, but IMHO that kind of 166232785Speter@c noise pretty much makes the Entries.Static feature 166332785Speter@c useless. 166425839Speter 166525839Speter@cindex Tag file, in CVS directory 166625839Speter@cindex CVS/Tag file 166725839Speter@cindex Sticky tags/dates, per-directory 166825839Speter@cindex Per-directory sticky tags/dates 166925839Speter@item Tag 167025839SpeterThis file contains per-directory sticky tags or dates. 167125839SpeterThe first character is @samp{T} for a branch tag, 167225839Speter@samp{N} for a non-branch tag, or @samp{D} for a date, 167325839Speteror another character to mean the file should be 167425839Spetersilently ignored, for future expansion. This character 167525839Speteris followed by the tag or date. Note that 167625839Speterper-directory sticky tags or dates are used for things 167725839Speterlike applying to files which are newly added; they 167825839Spetermight not be the same as the sticky tags or dates on 167925839Speterindividual files. For general information on sticky 168025839Spetertags and dates, see @ref{Sticky tags}. 168125839Speter@c FIXME: This needs to be much better documented, 168225839Speter@c preferably not in the context of "working directory 168325839Speter@c storage". 168425839Speter@c FIXME: The Sticky tags node needs to discuss, or xref to 168525839Speter@c someplace which discusses, per-directory sticky 168625839Speter@c tags and the distinction with per-file sticky tags. 168725839Speter 168825839Speter@cindex Notify file, in CVS directory 168925839Speter@cindex CVS/Notify file 169025839Speter@item Notify 169125839SpeterThis file stores notifications (for example, for 169225839Speter@code{edit} or @code{unedit}) which have not yet been 169325839Spetersent to the server. Its format is not yet documented 169425839Speterhere. 169525839Speter 169625839Speter@cindex Notify.tmp file, in CVS directory 169725839Speter@cindex CVS/Notify.tmp file 169825839Speter@item Notify.tmp 169925839SpeterThis file is to @file{Notify} as @file{Entries.Backup} 170025839Speteris to @file{Entries}. That is, to write @file{Notify}, 170125839Speterfirst write the new contents to @file{Notify.tmp} and 170225839Speterthen (atomically where possible), rename it to 170325839Speter@file{Notify}. 170425839Speter 170525839Speter@cindex Base directory, in CVS directory 170625839Speter@cindex CVS/Base directory 170725839Speter@item Base 170825839SpeterIf watches are in use, then an @code{edit} command 170925839Speterstores the original copy of the file in the @file{Base} 171025839Speterdirectory. This allows the @code{unedit} command to 171125839Speteroperate even if it is unable to communicate with the 171225839Speterserver. 171325839Speter 171432785Speter@cindex Baserev file, in CVS directory 171532785Speter@cindex CVS/Baserev file 171632785Speter@item Baserev 171732785SpeterThe file lists the revision for each of the files in 171832785Speterthe @file{Base} directory. The format is: 171932785Speter 172032785Speter@example 172132785SpeterB@var{name}/@var{rev}/@var{expansion} 172232785Speter@end example 172332785Speter 1724102840Speter@noindent 172532785Speterwhere @var{expansion} should be ignored, to allow for 172632785Speterfuture expansion. 172732785Speter 172832785Speter@cindex Baserev.tmp file, in CVS directory 172932785Speter@cindex CVS/Baserev.tmp file 173032785Speter@item Baserev.tmp 173132785SpeterThis file is to @file{Baserev} as @file{Entries.Backup} 173232785Speteris to @file{Entries}. That is, to write @file{Baserev}, 173332785Speterfirst write the new contents to @file{Baserev.tmp} and 173432785Speterthen (atomically where possible), rename it to 173532785Speter@file{Baserev}. 173632785Speter 173725839Speter@cindex Template file, in CVS directory 173825839Speter@cindex CVS/Template file 173925839Speter@item Template 174025839SpeterThis file contains the template specified by the 174125839Speter@file{rcsinfo} file (@pxref{rcsinfo}). It is only used 174225839Speterby the client; the non-client/server @sc{cvs} consults 174325839Speter@file{rcsinfo} directly. 174425839Speter@end table 174525839Speter 174617721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 174717721Speter@node Intro administrative files 174817721Speter@section The administrative files 174917721Speter@cindex Administrative files (intro) 175017721Speter@cindex Modules file 175117721Speter@cindex CVSROOT, module name 175217721Speter@cindex Defining modules (intro) 175317721Speter 175425839Speter@c FIXME: this node should be reorganized into "general 175525839Speter@c information about admin files" and put the "editing 175625839Speter@c admin files" stuff up front rather than jumping into 175725839Speter@c the details of modules right away. Then the 175825839Speter@c Administrative files node can go away, the information 175925839Speter@c on each admin file distributed to a place appropriate 176025839Speter@c to its function, and this node can contain a table 176125839Speter@c listing each file and a @ref to its detailed description. 176225839Speter 176317721SpeterThe directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative 176417721Speterfiles}. @xref{Administrative files}, for a complete description. 176517721SpeterYou can use @sc{cvs} without any of these files, but 176617721Spetersome commands work better when at least the 176717721Speter@file{modules} file is properly set up. 176817721Speter 176917721SpeterThe most important of these files is the @file{modules} 177017721Speterfile. It defines all modules in the repository. This 177117721Speteris a sample @file{modules} file. 177217721Speter 177317721Speter@c FIXME: The CVSROOT line is a goofy example now that 177417721Speter@c mkmodules doesn't exist. 177517721Speter@example 177617721SpeterCVSROOT CVSROOT 177717721Spetermodules CVSROOT modules 177817721Spetercvs gnu/cvs 177917721Speterrcs gnu/rcs 178017721Speterdiff gnu/diff 178117721Spetertc yoyodyne/tc 178217721Speter@end example 178317721Speter 178425839SpeterThe @file{modules} file is line oriented. In its 178525839Spetersimplest form each line contains the name of the 178625839Spetermodule, whitespace, and the directory where the module 178725839Speterresides. The directory is a path relative to 178825839Speter@code{$CVSROOT}. The last four lines in the example 178917721Speterabove are examples of such lines. 179017721Speter 179117721Speter@c FIXME: might want to introduce the concept of options in modules file 179217721Speter@c (the old example which was here, -i mkmodules, is obsolete). 179317721Speter 179417721SpeterThe line that defines the module called @samp{modules} 179517721Speteruses features that are not explained here. 179617721Speter@xref{modules}, for a full explanation of all the 179717721Speteravailable features. 179817721Speter 179925839Speter@c FIXME: subsection without node is bogus 180017721Speter@subsection Editing administrative files 180117721Speter@cindex Editing administrative files 180217721Speter@cindex Administrative files, editing them 180317721Speter 180417721SpeterYou edit the administrative files in the same way that you would edit 180517721Speterany other module. Use @samp{cvs checkout CVSROOT} to get a working 180617721Spetercopy, edit it, and commit your changes in the normal way. 180717721Speter 180817721SpeterIt is possible to commit an erroneous administrative 180917721Speterfile. You can often fix the error and check in a new 181017721Speterrevision, but sometimes a particularly bad error in the 181117721Speteradministrative file makes it impossible to commit new 1812175261Sobrienrevisions. If and when this happens, you can correct 1813175261Sobrienthe problem by temporarily copying a corrected administrative file 1814175261Sobriendirectly into the @code{$CVSROOT/CVSROOT} repository directory, 1815175261Sobrienthen committing the same correction via a checkout of the @file{CVSROOT} 1816175261Sobrienmodule. It is important that the correction also be made via the 1817175261Sobrienchecked out copy, or the next checkout and commit to the 1818175261Sobrien<code>CVSROOT</code> module will overwrite the correction that was 1819175261Sobriencopied directly into the repository, possibly breaking things in such 1820175261Sobriena way as to prevent commits again. 182117721Speter@c @xref{Bad administrative files} for a hint 182217721Speter@c about how to solve such situations. 182317721Speter@c -- administrative file checking-- 182417721Speter 182517721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 182617721Speter@node Multiple repositories 182717721Speter@section Multiple repositories 182817721Speter@cindex Multiple repositories 182917721Speter@cindex Repositories, multiple 183017721Speter@cindex Many repositories 183117721Speter@cindex Parallel repositories 183217721Speter@cindex Disjoint repositories 183317721Speter@cindex CVSROOT, multiple repositories 183417721Speter 183517721SpeterIn some situations it is a good idea to have more than 183617721Speterone repository, for instance if you have two 183717721Speterdevelopment groups that work on separate projects 183817721Speterwithout sharing any code. All you have to do to have 183917721Speterseveral repositories is to specify the appropriate 184017721Speterrepository, using the @code{CVSROOT} environment 184117721Spetervariable, the @samp{-d} option to @sc{cvs}, or (once 184225839Speteryou have checked out a working directory) by simply 184325839Speterallowing @sc{cvs} to use the repository that was used 184425839Speterto check out the working directory 184525839Speter(@pxref{Specifying a repository}). 184617721Speter 184725839SpeterThe big advantage of having multiple repositories is 184854427Speterthat they can reside on different servers. With @sc{cvs} 184954427Speterversion 1.10, a single command cannot recurse into 185054427Speterdirectories from different repositories. With development 185154427Speterversions of @sc{cvs}, you can check out code from multiple 185254427Speterservers into your working directory. @sc{cvs} will 185354427Speterrecurse and handle all the details of making 185454427Speterconnections to as many server machines as necessary to 185554427Speterperform the requested command. Here is an example of 185654427Speterhow to set up a working directory: 185754427Speter 185854427Speter@example 185954427Spetercvs -d server1:/cvs co dir1 186054427Spetercd dir1 186154427Spetercvs -d server2:/root co sdir 186254427Spetercvs update 186354427Speter@end example 186454427Speter 186554427SpeterThe @code{cvs co} commands set up the working 186654427Speterdirectory, and then the @code{cvs update} command will 186754427Spetercontact server2, to update the dir1/sdir subdirectory, 186854427Speterand server1, to update everything else. 186954427Speter 187025839Speter@c FIXME: Does the FAQ have more about this? I have a 187125839Speter@c dim recollection, but I'm too lazy to check right now. 187217721Speter 187317721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 187417721Speter@node Creating a repository 187517721Speter@section Creating a repository 187617721Speter 187725839Speter@cindex Repository, setting up 187825839Speter@cindex Creating a repository 187925839Speter@cindex Setting up a repository 188017721Speter 1881175261SobrienThis section describes how to set up a @sc{cvs} repository for any 1882175261Sobriensort of access method. After completing the setup described in this 1883175261Sobriensection, you should be able to access your @sc{cvs} repository immediately 1884175261Sobrienvia the local access method and several remote access methods. For 1885175261Sobrienmore information on setting up remote access to the repository you create 1886175261Sobrienin this section, please read the section on @xref{Remote repositories}. 1887175261Sobrien 188825839SpeterTo set up a @sc{cvs} repository, first choose the 188925839Spetermachine and disk on which you want to store the 189025839Speterrevision history of the source files. CPU and memory 189132785Speterrequirements are modest, so most machines should be 189232785Speteradequate. For details see @ref{Server requirements}. 189332785Speter@c Possible that we should be providing a quick rule of 189432785Speter@c thumb, like the 32M memory for the server. That 189532785Speter@c might increase the number of people who are happy 189632785Speter@c with the answer, without following the xref. 189732785Speter 189832785SpeterTo estimate disk space 189925839Speterrequirements, if you are importing RCS files from 190025839Speteranother system, the size of those files is the 190125839Speterapproximate initial size of your repository, or if you 190225839Speterare starting without any version history, a rule of 190325839Speterthumb is to allow for the server approximately three 190481404Spetertimes the size of the code to be under @sc{cvs} for the 190525839Speterrepository (you will eventually outgrow this, but not 190625839Speterfor a while). On the machines on which the developers 190725839Speterwill be working, you'll want disk space for 190825839Speterapproximately one working directory for each developer 190925839Speter(either the entire tree or a portion of it, depending 191032785Speteron what each developer uses). 191125839Speter 191254427SpeterThe repository should be accessible 191325839Speter(directly or via a networked file system) from all 191425839Spetermachines which want to use @sc{cvs} in server or local 191525839Spetermode; the client machines need not have any access to 191625839Speterit other than via the @sc{cvs} protocol. It is not 191725839Speterpossible to use @sc{cvs} to read from a repository 191825839Speterwhich one only has read access to; @sc{cvs} needs to be 191925839Speterable to create lock files (@pxref{Concurrency}). 192025839Speter 192125839Speter@cindex init (subcommand) 192225839SpeterTo create a repository, run the @code{cvs init} 192325839Spetercommand. It will set up an empty repository in the 192425839Speter@sc{cvs} root specified in the usual way 192525839Speter(@pxref{Repository}). For example, 192625839Speter 192725839Speter@example 192825839Spetercvs -d /usr/local/cvsroot init 192925839Speter@end example 193025839Speter 193125839Speter@code{cvs init} is careful to never overwrite any 193225839Speterexisting files in the repository, so no harm is done if 193325839Speteryou run @code{cvs init} on an already set-up 193425839Speterrepository. 193525839Speter 193625839Speter@code{cvs init} will enable history logging; if you 193725839Speterdon't want that, remove the history file after running 193825839Speter@code{cvs init}. @xref{history file}. 193925839Speter 194025839Speter@node Backing up 194125839Speter@section Backing up a repository 194225839Speter@cindex Repository, backing up 194325839Speter@cindex Backing up, repository 194425839Speter 194525839SpeterThere is nothing particularly magical about the files 194625839Speterin the repository; for the most part it is possible to 194725839Speterback them up just like any other files. However, there 194825839Speterare a few issues to consider. 194925839Speter 195066525Speter@cindex Locks, cvs, and backups 195144852Speter@cindex #cvs.rfl, and backups 195225839SpeterThe first is that to be paranoid, one should either not 195325839Speteruse @sc{cvs} during the backup, or have the backup 195425839Speterprogram lock @sc{cvs} while doing the backup. To not 195525839Speteruse @sc{cvs}, you might forbid logins to machines which 195625839Spetercan access the repository, turn off your @sc{cvs} 195725839Speterserver, or similar mechanisms. The details would 195825839Speterdepend on your operating system and how you have 195925839Speter@sc{cvs} set up. To lock @sc{cvs}, you would create 196025839Speter@file{#cvs.rfl} locks in each repository directory. 196125839SpeterSee @ref{Concurrency}, for more on @sc{cvs} locks. 196225839SpeterHaving said all this, if you just back up without any 196325839Speterof these precautions, the results are unlikely to be 196425839Speterparticularly dire. Restoring from backup, the 196525839Speterrepository might be in an inconsistent state, but this 196625839Speterwould not be particularly hard to fix manually. 196725839Speter 196825839SpeterWhen you restore a repository from backup, assuming 196925839Speterthat changes in the repository were made after the time 197025839Speterof the backup, working directories which were not 197125839Speteraffected by the failure may refer to revisions which no 197225839Speterlonger exist in the repository. Trying to run @sc{cvs} 197325839Speterin such directories will typically produce an error 197425839Spetermessage. One way to get those changes back into the 197525839Speterrepository is as follows: 197625839Speter 197725839Speter@itemize @bullet 197825839Speter@item 197925839SpeterGet a new working directory. 198025839Speter 198125839Speter@item 198225839SpeterCopy the files from the working directory from before 198325839Speterthe failure over to the new working directory (do not 198425839Spetercopy the contents of the @file{CVS} directories, of 198525839Spetercourse). 198625839Speter 198725839Speter@item 198825839SpeterWorking in the new working directory, use commands such 198925839Speteras @code{cvs update} and @code{cvs diff} to figure out 199025839Speterwhat has changed, and then when you are ready, commit 199125839Speterthe changes into the repository. 199225839Speter@end itemize 199325839Speter 199426801Speter@node Moving a repository 199526801Speter@section Moving a repository 199666525Speter@cindex Repository, moving 199766525Speter@cindex Moving a repository 199866525Speter@cindex Copying a repository 199926801Speter 200026801SpeterJust as backing up the files in the repository is 200126801Speterpretty much like backing up any other files, if you 200226801Speterneed to move a repository from one place to another it 200326801Speteris also pretty much like just moving any other 200426801Spetercollection of files. 200526801Speter 200626801SpeterThe main thing to consider is that working directories 200726801Speterpoint to the repository. The simplest way to deal with 200826801Spetera moved repository is to just get a fresh working 200926801Speterdirectory after the move. Of course, you'll want to 201026801Spetermake sure that the old working directory had been 201126801Speterchecked in before the move, or you figured out some 201226801Speterother way to make sure that you don't lose any 201326801Speterchanges. If you really do want to reuse the existing 201426801Speterworking directory, it should be possible with manual 201526801Spetersurgery on the @file{CVS/Repository} files. You can 201626801Spetersee @ref{Working directory storage}, for information on 201726801Speterthe @file{CVS/Repository} and @file{CVS/Root} files, but 201826801Speterunless you are sure you want to bother, it probably 201926801Speterisn't worth it. 202054427Speter@c FIXME: Surgery on CVS/Repository should be avoided 202154427Speter@c by making RELATIVE_REPOS the default. 202254427Speter@c FIXME-maybe: might want some documented way to 202354427Speter@c change the CVS/Root files in some particular tree. 202454427Speter@c But then again, I don't know, maybe just having 202554427Speter@c people do this in perl/shell/&c isn't so bad... 202626801Speter 202717721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 202817721Speter@node Remote repositories 202917721Speter@section Remote repositories 203017721Speter@cindex Repositories, remote 203117721Speter@cindex Remote repositories 203217721Speter@cindex Client/Server Operation 203366525Speter@cindex Server, CVS 203481404Speter@cindex Remote repositories, port specification 203581404Speter@cindex Repositories, remote, port specification 203681404Speter@cindex Client/Server Operation, port specification 203781404Speter@cindex pserver (client/server connection method), port specification 203881404Speter@cindex kserver (client/server connection method), port specification 203981404Speter@cindex gserver (client/server connection method), port specification 204081404Speter@cindex port, specifying for remote repositories 204117721Speter 204217721Speter Your working copy of the sources can be on a 204325839Speterdifferent machine than the repository. Using @sc{cvs} 204425839Speterin this manner is known as @dfn{client/server} 204525839Speteroperation. You run @sc{cvs} on a machine which can 204625839Spetermount your working directory, known as the 204725839Speter@dfn{client}, and tell it to communicate to a machine 204825839Speterwhich can mount the repository, known as the 204925839Speter@dfn{server}. Generally, using a remote 205025839Speterrepository is just like using a local one, except that 205125839Speterthe format of the repository name is: 205217721Speter 205317721Speter@example 2054128266Speter[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 205517721Speter@end example 205617721Speter 205781404SpeterSpecifying a password in the repository name is not recommended during 205881404Spetercheckout, since this will cause @sc{cvs} to store a cleartext copy of the 205981404Speterpassword in each created directory. @code{cvs login} first instead 206081404Speter(@pxref{Password authentication client}). 206181404Speter 206217721SpeterThe details of exactly what needs to be set up depend 206317721Speteron how you are connecting to the server. 206417721Speter 206525839SpeterIf @var{method} is not specified, and the repository 206625839Spetername contains @samp{:}, then the default is @code{ext} 206725839Speteror @code{server}, depending on your platform; both are 206825839Speterdescribed in @ref{Connecting via rsh}. 206925839Speter@c Should we try to explain which platforms are which? 207025839Speter@c Platforms like unix and VMS, which only allow 207125839Speter@c privileged programs to bind to sockets <1024 lose on 207225839Speter@c :server: 207325839Speter@c Platforms like Mac and VMS, whose rsh program is 207425839Speter@c unusable or nonexistent, lose on :ext: 207525839Speter@c Platforms like OS/2 and NT probably could plausibly 207625839Speter@c default either way (modulo -b troubles). 207725839Speter 207825839Speter@c FIXME: We need to have a better way of explaining 207925839Speter@c what method to use. This presentation totally 208025839Speter@c obscures the fact that :ext: and CVS_RSH is the way to 208125839Speter@c use SSH, for example. Plus it incorrectly implies 208225839Speter@c that you need an @code{rsh} binary on the client to use 208325839Speter@c :server:. 208432785Speter@c Also note that rsh not pserver is the right choice if you want 208532785Speter@c users to be able to create their own repositories 208632785Speter@c (because of the --allow-root related issues). 208717721Speter@menu 208825839Speter* Server requirements:: Memory and other resources for servers 208917721Speter* Connecting via rsh:: Using the @code{rsh} program to connect 209017721Speter* Password authenticated:: Direct connections using passwords 209132785Speter* GSSAPI authenticated:: Direct connections using GSSAPI 2092130303Speter* Kerberos authenticated:: Direct connections with Kerberos 209354427Speter* Connecting via fork:: Using a forked @code{cvs server} to connect 209417721Speter@end menu 209517721Speter 209625839Speter@node Server requirements 209725839Speter@subsection Server requirements 209825839Speter 209925839SpeterThe quick answer to what sort of machine is suitable as 210025839Spetera server is that requirements are modest---a server 210125839Speterwith 32M of memory or even less can handle a fairly 210225839Speterlarge source tree with a fair amount of activity. 210325839Speter@c Say something about CPU speed too? I'm even less sure 210425839Speter@c what to say on that subject... 210525839Speter 210632785SpeterThe real answer, of course, is more complicated. 210732785SpeterEstimating the known areas of large memory consumption 210832785Spetershould be sufficient to estimate memory requirements. 210932785SpeterThere are two such areas documented here; other memory 211032785Speterconsumption should be small by comparison (if you find 211132785Speterthat is not the case, let us know, as described in 211232785Speter@ref{BUGS}, so we can update this documentation). 211332785Speter 211432785SpeterThe first area of big memory consumption is large 211532785Spetercheckouts, when using the @sc{cvs} server. The server 211632785Speterconsists of two processes for each client that it is 211732785Speterserving. Memory consumption on the child process 211832785Spetershould remain fairly small. Memory consumption on the 211932785Speterparent process, particularly if the network connection 212032785Speterto the client is slow, can be expected to grow to 212132785Speterslightly more than the size of the sources in a single 212232785Speterdirectory, or two megabytes, whichever is larger. 212325839Speter@c "two megabytes" of course is SERVER_HI_WATER. But 212425839Speter@c we don't mention that here because we are 212525839Speter@c documenting the default configuration of CVS. If it 212625839Speter@c is a "standard" thing to change that value, it 212725839Speter@c should be some kind of run-time configuration. 212844852Speter@c 212925839Speter@c See cvsclient.texi for more on the design decision 213025839Speter@c to not have locks in place while waiting for the 213125839Speter@c client, which is what results in memory consumption 213225839Speter@c as high as this. 213325839Speter 213425839SpeterMultiplying the size of each @sc{cvs} server by the 213525839Speternumber of servers which you expect to have active at 213625839Speterone time should give an idea of memory requirements for 213725839Speterthe server. For the most part, the memory consumed by 213825839Speterthe parent process probably can be swap space rather 213925839Speterthan physical memory. 214025839Speter@c Has anyone verified that notion about swap space? 214125839Speter@c I say it based pretty much on guessing that the 214225839Speter@c ->text of the struct buffer_data only gets accessed 214325839Speter@c in a first in, first out fashion, but I haven't 214425839Speter@c looked very closely. 214525839Speter 214632785Speter@c What about disk usage in /tmp on the server? I think that 214732785Speter@c it can be substantial, but I haven't looked at this 214832785Speter@c again and tried to figure it out ("cvs import" is 214932785Speter@c probably the worst case...). 215032785Speter 215132785SpeterThe second area of large memory consumption is 215232785Speter@code{diff}, when checking in large files. This is 215332785Speterrequired even for binary files. The rule of thumb is 215432785Speterto allow about ten times the size of the largest file 215532785Speteryou will want to check in, although five times may be 215632785Speteradequate. For example, if you want to check in a file 215732785Speterwhich is 10 megabytes, you should have 100 megabytes of 215832785Spetermemory on the machine doing the checkin (the server 215932785Spetermachine for client/server, or the machine running 216032785Speter@sc{cvs} for non-client/server). This can be swap 216132785Speterspace rather than physical memory. Because the memory 216232785Speteris only required briefly, there is no particular need 216332785Speterto allow memory for more than one such checkin at a 216432785Spetertime. 216532785Speter@c The 5-10 times rule of thumb is from Paul Eggert for 216632785Speter@c GNU diff. I don't think it is in the GNU diff 216732785Speter@c manual or anyplace like that. 216832785Speter@c 216932785Speter@c Probably we could be saying more about 217032785Speter@c non-client/server CVS. 217125839Speter@c I would guess for non-client/server CVS in an NFS 217232785Speter@c environment the biggest issues are the network and 217325839Speter@c the NFS server. 217425839Speter 217532785SpeterResource consumption for the client is even more 217632785Spetermodest---any machine with enough capacity to run the 217732785Speteroperating system in question should have little 217832785Spetertrouble. 217932785Speter@c Is that true? I think the client still wants to 218032785Speter@c (bogusly) store entire files in memory at times. 218132785Speter 218232785SpeterFor information on disk space requirements, see 218332785Speter@ref{Creating a repository}. 218432785Speter 218517721Speter@node Connecting via rsh 2186177391Sobrien@subsection Connecting with rsh or ssh 218717721Speter 2188177391Sobrien@cindex ssh 2189177391Sobrien@sc{cvs} may use the @samp{ssh} protocol to perform 2190177391Sobrienthese operations, so the remote user host needs to have 2191177391Sobriena either an agent like @code{ssh-agent} to hold 2192177391Sobriencredentials or a @file{.shosts} file which grants 2193177391Sobrienaccess to the local user. Note that the program that 2194177391Sobrien@sc{cvs} uses for this purpose may be specified using 2195177391Sobrienthe @file{--with-ssh} flag to configure. 2196177391Sobrien 219717721Speter@cindex rsh 2198102840Speter@sc{cvs} uses the @samp{rsh} protocol to perform these 219917721Speteroperations, so the remote user host needs to have a 220017721Speter@file{.rhosts} file which grants access to the local 2201177391Sobrienuser. Note that the program that @sc{cvs} uses for this 2202177391Sobrienpurpose may be specified using the @file{--with-rsh} 2203177391Sobrienflag to configure. 220417721Speter 2205102840SpeterFor example, suppose you are the user @samp{mozart} on 2206102840Speterthe local machine @samp{toe.example.com}, and the 2207102840Speterserver machine is @samp{faun.example.org}. On 220854427Speterfaun, put the following line into the file 2209102840Speter@file{.rhosts} in @samp{bach}'s home directory: 221017721Speter 221117721Speter@example 221254427Spetertoe.example.com mozart 221317721Speter@end example 221417721Speter 2215102840Speter@noindent 2216102840SpeterThen test that @samp{rsh} is working with 221717721Speter 221817721Speter@example 221954427Speterrsh -l bach faun.example.org 'echo $PATH' 222017721Speter@end example 222117721Speter 2222177391Sobrien@noindent 2223177391SobrienTo test that @samp{ssh} is working use 2224177391Sobrien 2225177391Sobrien@example 2226177391Sobrienssh -l bach faun.example.org 'echo $PATH' 2227177391Sobrien@end example 2228177391Sobrien 222932785Speter@cindex CVS_SERVER, environment variable 223017721SpeterNext you have to make sure that @code{rsh} will be able 223117721Speterto find the server. Make sure that the path which 223217721Speter@code{rsh} printed in the above example includes the 223317721Speterdirectory containing a program named @code{cvs} which 223417721Speteris the server. You need to set the path in 223517721Speter@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 223617721Speteror @file{.profile}. Alternately, you can set the 223717721Speterenvironment variable @code{CVS_SERVER} on the client 223817721Spetermachine to the filename of the server you want to use, 223917721Speterfor example @file{/usr/local/bin/cvs-1.6}. 224025839Speter@c FIXME: there should be a way to specify the 224125839Speter@c program in CVSROOT, not CVS_SERVER, so that one can use 224225839Speter@c different ones for different roots. e.g. ":server;cvs=cvs-1.6:" 224325839Speter@c instead of ":server:". 224417721Speter 224566525SpeterThere is no need to edit @file{inetd.conf} or start a 224617721Speter@sc{cvs} server daemon. 224717721Speter 224834461Speter@cindex :server:, setting up 224934461Speter@cindex :ext:, setting up 2250177391Sobrien@cindex :extssh:, setting up 225154427Speter@cindex Kerberos, using kerberized rsh 225254427Speter@cindex SSH (rsh replacement) 225354427Speter@cindex rsh replacements (Kerberized, SSH, &c) 2254177391SobrienThere are three access methods that you use in @code{CVSROOT} 2255177391Sobrienfor rsh or ssh. @code{:server:} specifies an internal rsh 225681404Speterclient, which is supported only by some @sc{cvs} ports. 2257177391Sobrien@code{:extssh:} specifies an external ssh program. By 2258177391Sobriendefault this is @code{ssh} (unless otherwise specified 2259177391Sobrienby the @file{--with-ssh} flag to configure) but you may set the 2260177391Sobrien@code{CVS_SSH} environment variable to invoke another 2261177391Sobrienprogram or wrapper script. 226225839Speter@code{:ext:} specifies an external rsh program. By 2263177391Sobriendefault this is @code{rsh} (unless otherwise specified 2264177391Sobrienby the @file{--with-rsh} flag to configure) but you may set the 226525839Speter@code{CVS_RSH} environment variable to invoke another 226625839Speterprogram which can access the remote server (for 226725839Speterexample, @code{remsh} on HP-UX 9 because @code{rsh} is 226825839Spetersomething different). It must be a program which can 226925839Spetertransmit data to and from the server without modifying 227025839Speterit; for example the Windows NT @code{rsh} is not 227125839Spetersuitable since it by default translates between CRLF 227281404Speterand LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 227325839Speterto @code{rsh} to get around this, but since this could 227425839Speterpotentially cause problems for programs other than the 227525839Speterstandard @code{rsh}, it may change in the future. If 227625839Speteryou set @code{CVS_RSH} to @code{SSH} or some other rsh 227725839Speterreplacement, the instructions in the rest of this 227825839Spetersection concerning @file{.rhosts} and so on are likely 227925839Speterto be inapplicable; consult the documentation for your rsh 228025839Speterreplacement. 228125839Speter@c FIXME: there should be a way to specify the 228225839Speter@c program in CVSROOT, not CVS_RSH, so that one can use 2283177391Sobrien@c different ones for different roots. e.g. 2284177391Sobrien@c ":ext;CVS_RSH=remsh:" instead of ":ext:". 228525839Speter@c See also the comment in src/client.c for rationale 228625839Speter@c concerning "rsh" being the default and never 228725839Speter@c "remsh". 228825839Speter 228917721SpeterContinuing our example, supposing you want to access 229017721Speterthe module @file{foo} in the repository 229117721Speter@file{/usr/local/cvsroot/}, on machine 229254427Speter@file{faun.example.org}, you are ready to go: 229317721Speter 229417721Speter@example 2295102840Spetercvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 229617721Speter@end example 229717721Speter 2298102840Speter@noindent 229917721Speter(The @file{bach@@} can be omitted if the username is 230017721Speterthe same on both the local and remote hosts.) 230117721Speter 230225839Speter@c Should we mention "rsh host echo hi" and "rsh host 230325839Speter@c cat" (the latter followed by typing text and ^D) 230425839Speter@c as troubleshooting techniques? Probably yes 230525839Speter@c (people tend to have trouble setting this up), 230625839Speter@c but this kind of thing can be hard to spell out. 230725839Speter 230817721Speter@node Password authenticated 230917721Speter@subsection Direct connection with password authentication 231017721Speter 231117721SpeterThe @sc{cvs} client can also connect to the server 231217721Speterusing a password protocol. This is particularly useful 231317721Speterif using @code{rsh} is not feasible (for example, 231417721Speterthe server is behind a firewall), and Kerberos also is 231517721Speternot available. 231617721Speter 231717721Speter To use this method, it is necessary to make 231817721Spetersome adjustments on both the server and client sides. 231917721Speter 232017721Speter@menu 232117721Speter* Password authentication server:: Setting up the server 232217721Speter* Password authentication client:: Using the client 232317721Speter* Password authentication security:: What this method does and does not do 232417721Speter@end menu 232517721Speter 232617721Speter@node Password authentication server 232717721Speter@subsubsection Setting up the server for password authentication 232817721Speter 232932785SpeterFirst of all, you probably want to tighten the 233032785Speterpermissions on the @file{$CVSROOT} and 233132785Speter@file{$CVSROOT/CVSROOT} directories. See @ref{Password 233232785Speterauthentication security}, for more details. 233332785Speter 233466525Speter@cindex pserver (subcommand) 233581404Speter@cindex Remote repositories, port specification 233681404Speter@cindex Repositories, remote, port specification 233781404Speter@cindex Client/Server Operation, port specification 233881404Speter@cindex pserver (client/server connection method), port specification 233981404Speter@cindex kserver (client/server connection method), port specification 234081404Speter@cindex gserver (client/server connection method), port specification 234181404Speter@cindex port, specifying for remote repositories 234266525Speter@cindex Password server, setting up 234366525Speter@cindex Authenticating server, setting up 2344102840Speter@cindex inetd, configuring for pserver 2345102840Speter@cindex xinetd, configuring for pserver 234625839Speter@c FIXME: this isn't quite right regarding port 234725839Speter@c numbers; CVS looks up "cvspserver" in 234825839Speter@c /etc/services (on unix, but what about non-unix?). 234917721SpeterOn the server side, the file @file{/etc/inetd.conf} 235017721Speterneeds to be edited so @code{inetd} knows to run the 235117721Spetercommand @code{cvs pserver} when it receives a 235217721Speterconnection on the right port. By default, the port 235317721Speternumber is 2401; it would be different if your client 235417721Speterwere compiled with @code{CVS_AUTH_PORT} defined to 2355107484Spetersomething else, though. This can also be specified in the CVSROOT variable 235681404Speter(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 235781404Speterenvironment variable (@pxref{Environment variables}). 235817721Speter 235917721Speter If your @code{inetd} allows raw port numbers in 236017721Speter@file{/etc/inetd.conf}, then the following (all on a 236117721Spetersingle line in @file{inetd.conf}) should be sufficient: 236217721Speter 236317721Speter@example 236417721Speter2401 stream tcp nowait root /usr/local/bin/cvs 236566525Spetercvs -f --allow-root=/usr/cvsroot pserver 236617721Speter@end example 236717721Speter 2368102840Speter@noindent 2369102840Speter(You could also use the 2370102840Speter@samp{-T} option to specify a temporary directory.) 237117721Speter 237226801SpeterThe @samp{--allow-root} option specifies the allowable 237326801Speter@sc{cvsroot} directory. Clients which attempt to use a 237426801Speterdifferent @sc{cvsroot} directory will not be allowed to 237526801Speterconnect. If there is more than one @sc{cvsroot} 237626801Speterdirectory which you want to allow, repeat the option. 237754427Speter(Unfortunately, many versions of @code{inetd} have very small 237854427Speterlimits on the number of arguments and/or the total length 237954427Speterof the command. The usual solution to this problem is 238054427Speterto have @code{inetd} run a shell script which then invokes 238154427Speter@sc{cvs} with the necessary arguments.) 238226801Speter 238317721Speter If your @code{inetd} wants a symbolic service 238417721Spetername instead of a raw port number, then put this in 238517721Speter@file{/etc/services}: 238617721Speter 238717721Speter@example 238817721Spetercvspserver 2401/tcp 238917721Speter@end example 239017721Speter 2391102840Speter@noindent 2392102840Speterand put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 239317721Speter 2394102840SpeterIf your system uses @code{xinetd} instead of @code{inetd}, 2395102840Speterthe procedure is slightly different. 2396102840SpeterCreate a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2397102840Speter 2398102840Speter@example 2399102840Speterservice cvspserver 2400102840Speter@{ 2401102840Speter port = 2401 2402102840Speter socket_type = stream 2403102840Speter protocol = tcp 2404102840Speter wait = no 2405102840Speter user = root 2406102840Speter passenv = PATH 2407102840Speter server = /usr/local/bin/cvs 2408102840Speter server_args = -f --allow-root=/usr/cvsroot pserver 2409102840Speter@} 2410102840Speter@end example 2411102840Speter 2412102840Speter@noindent 2413102840Speter(If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2414102840Speterthe @code{port} line.) 2415102840Speter 241617721Speter Once the above is taken care of, restart your 241717721Speter@code{inetd}, or do whatever is necessary to force it 241817721Speterto reread its initialization files. 241917721Speter 242054427SpeterIf you are having trouble setting this up, see 242154427Speter@ref{Connection}. 242225839Speter 242317721Speter@cindex CVS passwd file 242425839Speter@cindex passwd (admin file) 242517721SpeterBecause the client stores and transmits passwords in 242617721Spetercleartext (almost---see @ref{Password authentication 242725839Spetersecurity}, for details), a separate @sc{cvs} password 242866525Speterfile is generally used, so people don't compromise 242966525Spetertheir regular passwords when they access the 243066525Speterrepository. This file is 243166525Speter@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 243266525Speteradministrative files}). It uses a colon-separated 243366525Speterformat, similar to @file{/etc/passwd} on Unix systems, 243466525Speterexcept that it has fewer fields: @sc{cvs} username, 243566525Speteroptional password, and an optional system username for 243666525Speter@sc{cvs} to run as if authentication succeeds. Here is 243766525Speteran example @file{passwd} file with five entries: 243817721Speter 243917721Speter@example 244066525Speteranonymous: 244117721Speterbach:ULtgRLXo7NRxs 244266525Speterspwang:1sOp854gDF3DY 244366525Spetermelissa:tGX1fS8sun6rY:pubcvs 244466525Speterqproj:XR4EZcEs0szik:pubcvs 244517721Speter@end example 244617721Speter 2447102840Speter@noindent 244866525Speter(The passwords are encrypted according to the standard 244917721SpeterUnix @code{crypt()} function, so it is possible to 245017721Speterpaste in passwords directly from regular Unix 245166525Speter@file{/etc/passwd} files.) 245217721Speter 245366525SpeterThe first line in the example will grant access to any 245466525Speter@sc{cvs} client attempting to authenticate as user 245566525Speter@code{anonymous}, no matter what password they use, 245666525Speterincluding an empty password. (This is typical for 245766525Spetersites granting anonymous read-only access; for 245866525Speterinformation on how to do the "read-only" part, see 245981404Speter@ref{Read-only access}.) 246017721Speter 246166525SpeterThe second and third lines will grant access to 246266525Speter@code{bach} and @code{spwang} if they supply their 246366525Speterrespective plaintext passwords. 246425839Speter 246566525Speter@cindex User aliases 246666525SpeterThe fourth line will grant access to @code{melissa}, if 246766525Spetershe supplies the correct password, but her @sc{cvs} 246866525Speteroperations will actually run on the server side under 246966525Speterthe system user @code{pubcvs}. Thus, there need not be 247066525Speterany system user named @code{melissa}, but there 247166525Speter@emph{must} be one named @code{pubcvs}. 247225839Speter 247366525SpeterThe fifth line shows that system user identities can be 247466525Spetershared: any client who successfully authenticates as 247566525Speter@code{qproj} will actually run as @code{pubcvs}, just 247666525Speteras @code{melissa} does. That way you could create a 247766525Spetersingle, shared system user for each project in your 247866525Speterrepository, and give each developer their own line in 247966525Speterthe @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 248066525Speterusername on each line would be different, but the 248166525Spetersystem username would be the same. The reason to have 248281404Speterdifferent @sc{cvs} usernames is that @sc{cvs} will log their 248366525Speteractions under those names: when @code{melissa} commits 248466525Spetera change to a project, the checkin is recorded in the 248566525Speterproject's history under the name @code{melissa}, not 248666525Speter@code{pubcvs}. And the reason to have them share a 248766525Spetersystem username is so that you can arrange permissions 248866525Speterin the relevant area of the repository such that only 248966525Speterthat account has write-permission there. 249025839Speter 249166525SpeterIf the system-user field is present, all 249266525Speterpassword-authenticated @sc{cvs} commands run as that 249366525Speteruser; if no system user is specified, @sc{cvs} simply 249466525Spetertakes the @sc{cvs} username as the system username and 249566525Speterruns commands as that user. In either case, if there 249666525Speteris no such user on the system, then the @sc{cvs} 249766525Speteroperation will fail (regardless of whether the client 249866525Spetersupplied a valid password). 249966525Speter 250066525SpeterThe password and system-user fields can both be omitted 250166525Speter(and if the system-user field is omitted, then also 250266525Speteromit the colon that would have separated it from the 250366525Speterencrypted password). For example, this would be a 250466525Spetervalid @file{$CVSROOT/CVSROOT/passwd} file: 250566525Speter 250625839Speter@example 250766525Speteranonymous::pubcvs 250866525Speterfish:rKa5jzULzmhOo:kfogel 250966525Spetersussman:1sOp854gDF3DY 251025839Speter@end example 251125839Speter 2512102840Speter@noindent 251366525SpeterWhen the password field is omitted or empty, then the 251466525Speterclient's authentication attempt will succeed with any 251566525Speterpassword, including the empty string. However, the 251666525Spetercolon after the @sc{cvs} username is always necessary, 251766525Spetereven if the password is empty. 251825839Speter 251981404Speter@sc{cvs} can also fall back to use system authentication. 252066525SpeterWhen authenticating a password, the server first checks 252166525Speterfor the user in the @file{$CVSROOT/CVSROOT/passwd} 252266525Speterfile. If it finds the user, it will use that entry for 252366525Speterauthentication as described above. But if it does not 252466525Speterfind the user, or if the @sc{cvs} @file{passwd} file 252566525Speterdoes not exist, then the server can try to authenticate 252666525Speterthe username and password using the operating system's 252766525Speteruser-lookup routines (this "fallback" behavior can be 252866525Speterdisabled by setting @code{SystemAuth=no} in the 252966525Speter@sc{cvs} @file{config} file, @pxref{config}). Be 253066525Speteraware, however, that falling back to system 253166525Speterauthentication might be a security risk: @sc{cvs} 253266525Speteroperations would then be authenticated with that user's 253366525Speterregular login password, and the password flies across 253466525Speterthe network in plaintext. See @ref{Password 253566525Speterauthentication security} for more on this. 253625839Speter 253717721SpeterRight now, the only way to put a password in the 253817721Speter@sc{cvs} @file{passwd} file is to paste it there from 253917721Spetersomewhere else. Someday, there may be a @code{cvs 254017721Speterpasswd} command. 254166525Speter 254266525SpeterUnlike many of the files in @file{$CVSROOT/CVSROOT}, it 254366525Speteris normal to edit the @file{passwd} file in-place, 254466525Speterrather than via @sc{cvs}. This is because of the 254566525Speterpossible security risks of having the @file{passwd} 254666525Speterfile checked out to people's working copies. If you do 254766525Speterwant to include the @file{passwd} file in checkouts of 254881404Speter@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 254966525Speter 255025839Speter@c We might also suggest using the @code{htpasswd} command 255125839Speter@c from freely available web servers as well, but that 255225839Speter@c would open up a can of worms in that the users next 255325839Speter@c questions are likely to be "where do I get it?" and 255425839Speter@c "how do I use it?" 255526801Speter@c Also note that htpasswd, at least the version I had, 255626801Speter@c likes to clobber the third field. 255717721Speter 255817721Speter@node Password authentication client 255917721Speter@subsubsection Using the client with password authentication 256017721Speter@cindex Login (subcommand) 256166525Speter@cindex Password client, using 256266525Speter@cindex Authenticated client, using 256334461Speter@cindex :pserver:, setting up 256466525SpeterTo run a @sc{cvs} command on a remote repository via 256566525Speterthe password-authenticating server, one specifies the 256681404Speter@code{pserver} protocol, optional username, repository host, an 256781404Speteroptional port number, and path to the repository. For example: 256817721Speter 256966525Speter@example 257081404Spetercvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 257166525Speter@end example 257217721Speter 2573102840Speter@noindent 257466525Speteror 257566525Speter 257617721Speter@example 257781404SpeterCVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 257866525Spetercvs checkout someproj 257966525Speter@end example 258066525Speter 258166525SpeterHowever, unless you're connecting to a public-access 258266525Speterrepository (i.e., one where that username doesn't 258381404Speterrequire a password), you'll need to supply a password or @dfn{log in} first. 258481404SpeterLogging in verifies your password with the repository and stores it in a file. 258566525SpeterIt's done with the @code{login} command, which will 258681404Speterprompt you interactively for the password if you didn't supply one as part of 258781404Speter@var{$CVSROOT}: 258866525Speter 258966525Speter@example 259054427Spetercvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 259144852SpeterCVS password: 259217721Speter@end example 259317721Speter 2594102840Speter@noindent 259581404Speteror 259681404Speter 259781404Speter@example 259881404Spetercvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 259981404Speter@end example 260081404Speter 260166525SpeterAfter you enter the password, @sc{cvs} verifies it with 260266525Speterthe server. If the verification succeeds, then that 260366525Spetercombination of username, host, repository, and password 260466525Speteris permanently recorded, so future transactions with 260566525Speterthat repository won't require you to run @code{cvs 260666525Speterlogin}. (If verification fails, @sc{cvs} will exit 260766525Spetercomplaining that the password was incorrect, and 260866525Speternothing will be recorded.) 260917721Speter 261066525SpeterThe records are stored, by default, in the file 261166525Speter@file{$HOME/.cvspass}. That file's format is 261266525Speterhuman-readable, and to a degree human-editable, but 261366525Speternote that the passwords are not stored in 261466525Spetercleartext---they are trivially encoded to protect them 261566525Speterfrom "innocent" compromise (i.e., inadvertent viewing 261666525Speterby a system administrator or other non-malicious 261766525Speterperson). 261817721Speter 261966525Speter@cindex CVS_PASSFILE, environment variable 262066525SpeterYou can change the default location of this file by 262166525Spetersetting the @code{CVS_PASSFILE} environment variable. 262266525SpeterIf you use this variable, make sure you set it 262366525Speter@emph{before} @code{cvs login} is run. If you were to 262466525Speterset it after running @code{cvs login}, then later 262566525Speter@sc{cvs} commands would be unable to look up the 262666525Speterpassword for transmission to the server. 262766525Speter 262866525SpeterOnce you have logged in, all @sc{cvs} commands using 262966525Speterthat remote repository and username will authenticate 263066525Speterwith the stored password. So, for example 263166525Speter 263217721Speter@example 263354427Spetercvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 263417721Speter@end example 263517721Speter 2636102840Speter@noindent 263766525Spetershould just work (unless the password changes on the 263866525Speterserver side, in which case you'll have to re-run 263966525Speter@code{cvs login}). 264017721Speter 264166525SpeterNote that if the @samp{:pserver:} were not present in 264266525Speterthe repository specification, @sc{cvs} would assume it 264366525Spetershould use @code{rsh} to connect with the server 264466525Speterinstead (@pxref{Connecting via rsh}). 264517721Speter 264666525SpeterOf course, once you have a working copy checked out and 264766525Speterare running @sc{cvs} commands from within it, there is 264866525Speterno longer any need to specify the repository 264966525Speterexplicitly, because @sc{cvs} can deduce the repository 265066525Speterfrom the working copy's @file{CVS} subdirectory. 265166525Speter 265225839Speter@c FIXME: seems to me this needs somewhat more 265325839Speter@c explanation. 265425839Speter@cindex Logout (subcommand) 265566525SpeterThe password for a given remote repository can be 265666525Speterremoved from the @code{CVS_PASSFILE} by using the 265725839Speter@code{cvs logout} command. 265825839Speter 265917721Speter@node Password authentication security 266017721Speter@subsubsection Security considerations with password authentication 266117721Speter 266266525Speter@cindex Security, of pserver 266317721SpeterThe passwords are stored on the client side in a 266417721Spetertrivial encoding of the cleartext, and transmitted in 266517721Speterthe same encoding. The encoding is done only to 266617721Speterprevent inadvertent password compromises (i.e., a 266717721Spetersystem administrator accidentally looking at the file), 266817721Speterand will not prevent even a naive attacker from gaining 266917721Speterthe password. 267017721Speter 267125839Speter@c FIXME: The bit about "access to the repository 267225839Speter@c implies general access to the system is *not* specific 267325839Speter@c to pserver; it applies to kerberos and SSH and 267425839Speter@c everything else too. Should reorganize the 267525839Speter@c documentation to make this clear. 267617721SpeterThe separate @sc{cvs} password file (@pxref{Password 267717721Speterauthentication server}) allows people 267817721Speterto use a different password for repository access than 267917721Speterfor login access. On the other hand, once a user has 268032785Speternon-read-only 268117721Speteraccess to the repository, she can execute programs on 268217721Speterthe server system through a variety of means. Thus, repository 268317721Speteraccess implies fairly broad system access as well. It 268417721Spetermight be possible to modify @sc{cvs} to prevent that, 268517721Speterbut no one has done so as of this writing. 268625839Speter@c OpenBSD uses chroot() and copies the repository to 268725839Speter@c provide anonymous read-only access (for details see 268825839Speter@c http://www.openbsd.org/anoncvs.shar). While this 268925839Speter@c closes the most obvious holes, I'm not sure it 269025839Speter@c closes enough holes to recommend it (plus it is 269125839Speter@c *very* easy to accidentally screw up a setup of this 269225839Speter@c type). 269317721Speter 269432785SpeterNote that because the @file{$CVSROOT/CVSROOT} directory 269532785Spetercontains @file{passwd} and other files which are used 269632785Speterto check security, you must control the permissions on 269732785Speterthis directory as tightly as the permissions on 269832785Speter@file{/etc}. The same applies to the @file{$CVSROOT} 269932785Speterdirectory itself and any directory 270032785Speterabove it in the tree. Anyone who has write access to 270132785Spetersuch a directory will have the ability to become any 270232785Speteruser on the system. Note that these permissions are 270332785Spetertypically tighter than you would use if you are not 270432785Speterusing pserver. 270532785Speter@c TODO: Would be really nice to document/implement a 270632785Speter@c scheme where the CVS server can run as some non-root 270732785Speter@c user, e.g. "cvs". CVSROOT/passwd would contain a 270832785Speter@c bunch of entries of the form foo:xxx:cvs (or the "cvs" 270932785Speter@c would be implicit). This would greatly reduce 271032785Speter@c security risks such as those hinted at in the 271132785Speter@c previous paragraph. I think minor changes to CVS 271232785Speter@c might be required but mostly this would just need 271332785Speter@c someone who wants to play with it, document it, &c. 271432785Speter 271517721SpeterIn summary, anyone who gets the password gets 271654427Speterrepository access (which may imply some measure of general system 271754427Speteraccess as well). The password is available to anyone 271817721Speterwho can sniff network packets or read a protected 271917721Speter(i.e., user read-only) file. If you want real 272017721Spetersecurity, get Kerberos. 272117721Speter 272232785Speter@node GSSAPI authenticated 272332785Speter@subsection Direct connection with GSSAPI 272432785Speter 272532785Speter@cindex GSSAPI 272666525Speter@cindex Security, GSSAPI 272734461Speter@cindex :gserver:, setting up 272854427Speter@cindex Kerberos, using :gserver: 272932785SpeterGSSAPI is a generic interface to network security 273032785Spetersystems such as Kerberos 5. 273132785SpeterIf you have a working GSSAPI library, you can have 273232785Speter@sc{cvs} connect via a direct @sc{tcp} connection, 273332785Speterauthenticating with GSSAPI. 273432785Speter 273532785SpeterTo do this, @sc{cvs} needs to be compiled with GSSAPI 273632785Spetersupport; when configuring @sc{cvs} it tries to detect 2737130303Speterwhether GSSAPI libraries using Kerberos version 5 are 273832785Speterpresent. You can also use the @file{--with-gssapi} 273932785Speterflag to configure. 274032785Speter 274132785SpeterThe connection is authenticated using GSSAPI, but the 274232785Spetermessage stream is @emph{not} authenticated by default. 274332785SpeterYou must use the @code{-a} global option to request 274432785Speterstream authentication. 274532785Speter 274632785SpeterThe data transmitted is @emph{not} encrypted by 274732785Speterdefault. Encryption support must be compiled into both 274832785Speterthe client and the server; use the 274932785Speter@file{--enable-encrypt} configure option to turn it on. 275032785SpeterYou must then use the @code{-x} global option to 275132785Speterrequest encryption. 275232785Speter 275332785SpeterGSSAPI connections are handled on the server side by 275432785Speterthe same server which handles the password 275532785Speterauthentication server; see @ref{Password authentication 275632785Speterserver}. If you are using a GSSAPI mechanism such as 275732785SpeterKerberos which provides for strong authentication, you 275832785Speterwill probably want to disable the ability to 275932785Speterauthenticate via cleartext passwords. To do so, create 276032785Speteran empty @file{CVSROOT/passwd} password file, and set 276132785Speter@code{SystemAuth=no} in the config file 276232785Speter(@pxref{config}). 276332785Speter 276432785SpeterThe GSSAPI server uses a principal name of 276532785Spetercvs/@var{hostname}, where @var{hostname} is the 276632785Spetercanonical name of the server host. You will have to 276732785Speterset this up as required by your GSSAPI mechanism. 276832785Speter 2769130303SpeterTo connect using GSSAPI, use the @samp{:gserver:} method. For 277032785Speterexample, 277132785Speter 277232785Speter@example 277354427Spetercvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 277432785Speter@end example 277532785Speter 277617721Speter@node Kerberos authenticated 2777130303Speter@subsection Direct connection with Kerberos 277817721Speter 277954427Speter@cindex Kerberos, using :kserver: 2780130303Speter@cindex Security, Kerberos 278134461Speter@cindex :kserver:, setting up 2782130303SpeterThe easiest way to use Kerberos is to use the Kerberos 278332785Speter@code{rsh}, as described in @ref{Connecting via rsh}. 278417721SpeterThe main disadvantage of using rsh is that all the data 278517721Speterneeds to pass through additional programs, so it may be 2786130303Speterslower. So if you have Kerberos installed you can 278717721Speterconnect via a direct @sc{tcp} connection, 2788130303Speterauthenticating with Kerberos. 278917721Speter 2790130303SpeterThis section concerns the Kerberos network security 279132785Spetersystem, version 4. Kerberos version 5 is supported via 279232785Speterthe GSSAPI generic network security interface, as 279332785Speterdescribed in the previous section. 279432785Speter 2795130303SpeterTo do this, @sc{cvs} needs to be compiled with Kerberos 279617721Spetersupport; when configuring @sc{cvs} it tries to detect 2797130303Speterwhether Kerberos is present or you can use the 279817721Speter@file{--with-krb4} flag to configure. 279917721Speter 280025839SpeterThe data transmitted is @emph{not} encrypted by 280125839Speterdefault. Encryption support must be compiled into both 280225839Speterthe client and server; use the 280325839Speter@file{--enable-encryption} configure option to turn it 280425839Speteron. You must then use the @code{-x} global option to 280525839Speterrequest encryption. 280625839Speter 280717721Speter@cindex CVS_CLIENT_PORT 280866525SpeterYou need to edit @file{inetd.conf} on the server 280917721Spetermachine to run @code{cvs kserver}. The client uses 281017721Speterport 1999 by default; if you want to use another port 281181404Speterspecify it in the @code{CVSROOT} (@pxref{Remote repositories}) 2812128266Speteror the @code{CVS_CLIENT_PORT} environment variable 2813128266Speter(@pxref{Environment variables}) on the client. 281417721Speter 281517721Speter@cindex kinit 281617721SpeterWhen you want to use @sc{cvs}, get a ticket in the 281717721Speterusual way (generally @code{kinit}); it must be a ticket 281817721Speterwhich allows you to log into the server machine. Then 281917721Speteryou are ready to go: 282017721Speter 282117721Speter@example 282254427Spetercvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 282317721Speter@end example 282417721Speter 282525839SpeterPrevious versions of @sc{cvs} would fall back to a 282625839Speterconnection via rsh; this version will not do so. 282717721Speter 282854427Speter@node Connecting via fork 282954427Speter@subsection Connecting with fork 283054427Speter 283154427Speter@cindex fork, access method 283254427Speter@cindex :fork:, setting up 283354427SpeterThis access method allows you to connect to a 283454427Speterrepository on your local disk via the remote protocol. 283554427SpeterIn other words it does pretty much the same thing as 283654427Speter@code{:local:}, but various quirks, bugs and the like are 283754427Speterthose of the remote @sc{cvs} rather than the local 283854427Speter@sc{cvs}. 283954427Speter 284054427SpeterFor day-to-day operations you might prefer either 284154427Speter@code{:local:} or @code{:fork:}, depending on your 284254427Speterpreferences. Of course @code{:fork:} comes in 284354427Speterparticularly handy in testing or 284454427Speterdebugging @code{cvs} and the remote protocol. 284554427SpeterSpecifically, we avoid all of the network-related 284654427Spetersetup/configuration, timeouts, and authentication 284754427Speterinherent in the other remote access methods but still 284854427Spetercreate a connection which uses the remote protocol. 284954427Speter 285054427SpeterTo connect using the @code{fork} method, use 285154427Speter@samp{:fork:} and the pathname to your local 285254427Speterrepository. For example: 285354427Speter 285454427Speter@example 285554427Spetercvs -d :fork:/usr/local/cvsroot checkout foo 285654427Speter@end example 285754427Speter 285854427Speter@cindex CVS_SERVER, and :fork: 285954427SpeterAs with @code{:ext:}, the server is called @samp{cvs} 286054427Speterby default, or the value of the @code{CVS_SERVER} 286154427Speterenvironment variable. 286254427Speter 286317721Speter@c --------------------------------------------------------------------- 286425839Speter@node Read-only access 286525839Speter@section Read-only repository access 286666525Speter@cindex Read-only repository access 286725839Speter@cindex readers (admin file) 286825839Speter@cindex writers (admin file) 286925839Speter 287025839Speter It is possible to grant read-only repository 287125839Speteraccess to people using the password-authenticated 287225839Speterserver (@pxref{Password authenticated}). (The 287325839Speterother access methods do not have explicit support for 287425839Speterread-only users because those methods all assume login 287525839Speteraccess to the repository machine anyway, and therefore 287625839Speterthe user can do whatever local file permissions allow 287744852Speterher to do.) 287825839Speter 287925839Speter A user who has read-only access can do only 288025839Speterthose @sc{cvs} operations which do not modify the 288125839Speterrepository, except for certain ``administrative'' files 288225839Speter(such as lock files and the history file). It may be 288325839Speterdesirable to use this feature in conjunction with 288425839Speteruser-aliasing (@pxref{Password authentication server}). 288525839Speter 288632785SpeterUnlike with previous versions of @sc{cvs}, read-only 288732785Speterusers should be able merely to read the repository, and 288832785Speternot to execute programs on the server or otherwise gain 288932785Speterunexpected levels of access. Or to be more accurate, 289032785Speterthe @emph{known} holes have been plugged. Because this 289132785Speterfeature is new and has not received a comprehensive 289232785Spetersecurity audit, you should use whatever level of 289332785Spetercaution seems warranted given your attitude concerning 289432785Spetersecurity. 289532785Speter 289625839Speter There are two ways to specify read-only access 289725839Speterfor a user: by inclusion, and by exclusion. 289825839Speter 289925839Speter "Inclusion" means listing that user 290025839Speterspecifically in the @file{$CVSROOT/CVSROOT/readers} 290125839Speterfile, which is simply a newline-separated list of 290225839Speterusers. Here is a sample @file{readers} file: 290325839Speter 290425839Speter@example 290525839Spetermelissa 290625839Spetersplotnik 290725839Speterjrandom 290825839Speter@end example 290925839Speter 2910102840Speter@noindent 291125839Speter (Don't forget the newline after the last user.) 291225839Speter 291325839Speter "Exclusion" means explicitly listing everyone 291425839Speterwho has @emph{write} access---if the file 291525839Speter 291625839Speter@example 291725839Speter$CVSROOT/CVSROOT/writers 291825839Speter@end example 291925839Speter 292025839Speter@noindent 292125839Speterexists, then only 292225839Speterthose users listed in it have write access, and 292325839Spetereveryone else has read-only access (of course, even the 292425839Speterread-only users still need to be listed in the 292525839Speter@sc{cvs} @file{passwd} file). The 292625839Speter@file{writers} file has the same format as the 292725839Speter@file{readers} file. 292825839Speter 292925839Speter Note: if your @sc{cvs} @file{passwd} 293025839Speterfile maps cvs users onto system users (@pxref{Password 293125839Speterauthentication server}), make sure you deny or grant 293225839Speterread-only access using the @emph{cvs} usernames, not 293325839Speterthe system usernames. That is, the @file{readers} and 293425839Speter@file{writers} files contain cvs usernames, which may 293525839Speteror may not be the same as system usernames. 293625839Speter 293725839Speter Here is a complete description of the server's 293825839Speterbehavior in deciding whether to grant read-only or 293925839Speterread-write access: 294025839Speter 294125839Speter If @file{readers} exists, and this user is 294225839Speterlisted in it, then she gets read-only access. Or if 294325839Speter@file{writers} exists, and this user is NOT listed in 294425839Speterit, then she also gets read-only access (this is true 294525839Spetereven if @file{readers} exists but she is not listed 294625839Speterthere). Otherwise, she gets full read-write access. 294725839Speter 294825839Speter Of course there is a conflict if the user is 294925839Speterlisted in both files. This is resolved in the more 295025839Speterconservative way, it being better to protect the 295125839Speterrepository too much than too little: such a user gets 295225839Speterread-only access. 295325839Speter 295425839Speter@node Server temporary directory 295525839Speter@section Temporary directories for the server 295666525Speter@cindex Temporary directories, and server 295766525Speter@cindex Server, temporary directories 295825839Speter 295925839SpeterWhile running, the @sc{cvs} server creates temporary 296044852Speterdirectories. They are named 296125839Speter 296225839Speter@example 296325839Spetercvs-serv@var{pid} 296425839Speter@end example 296525839Speter 296625839Speter@noindent 296725839Speterwhere @var{pid} is the process identification number of 2968128266Speterthe server. 2969128266SpeterThey are located in the directory specified by 2970128266Speterthe @samp{-T} global option (@pxref{Global options}), 2971128266Speterthe @code{TMPDIR} environment variable (@pxref{Environment variables}), 2972128266Speteror, failing that, @file{/tmp}. 297325839Speter 297425839SpeterIn most cases the server will remove the temporary 297525839Speterdirectory when it is done, whether it finishes normally 297625839Speteror abnormally. However, there are a few cases in which 297725839Speterthe server does not or cannot remove the temporary 297825839Speterdirectory, for example: 297925839Speter 298025839Speter@itemize @bullet 298125839Speter@item 298225839SpeterIf the server aborts due to an internal server error, 298325839Speterit may preserve the directory to aid in debugging 298425839Speter 298525839Speter@item 298625839SpeterIf the server is killed in a way that it has no way of 298725839Spetercleaning up (most notably, @samp{kill -KILL} on unix). 298825839Speter 298925839Speter@item 299025839SpeterIf the system shuts down without an orderly shutdown, 299125839Speterwhich tells the server to clean up. 299225839Speter@end itemize 299325839Speter 299425839SpeterIn cases such as this, you will need to manually remove 299525839Speterthe @file{cvs-serv@var{pid}} directories. As long as 299625839Speterthere is no server running with process identification 299725839Speternumber @var{pid}, it is safe to do so. 299825839Speter 299925839Speter@c --------------------------------------------------------------------- 300017721Speter@node Starting a new project 300117721Speter@chapter Starting a project with CVS 300217721Speter@cindex Starting a project with CVS 300317721Speter@cindex Creating a project 300417721Speter 300517721Speter@comment --moduledb-- 300625839SpeterBecause renaming files and moving them between 300725839Speterdirectories is somewhat inconvenient, the first thing 300825839Speteryou do when you start a new project should be to think 300925839Speterthrough your file organization. It is not impossible 301025839Speterto rename or move files, but it does increase the 301125839Speterpotential for confusion and @sc{cvs} does have some 301225839Speterquirks particularly in the area of renaming 301325839Speterdirectories. @xref{Moving files}. 301417721Speter 301517721SpeterWhat to do next depends on the situation at hand. 301617721Speter 301717721Speter@menu 301817721Speter* Setting up the files:: Getting the files into the repository 301917721Speter* Defining the module:: How to make a module of the files 302017721Speter@end menu 302117721Speter@c -- File permissions! 302217721Speter 302317721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 302417721Speter@node Setting up the files 302517721Speter@section Setting up the files 302617721Speter 302717721SpeterThe first step is to create the files inside the repository. This can 302817721Speterbe done in a couple of different ways. 302917721Speter 303017721Speter@c -- The contributed scripts 303117721Speter@menu 303217721Speter* From files:: This method is useful with old projects 303317721Speter where files already exists. 303417721Speter* From other version control systems:: Old projects where you want to 303517721Speter preserve history from another system. 303625839Speter* From scratch:: Creating a directory tree from scratch. 303717721Speter@end menu 303817721Speter 303917721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304017721Speter@node From files 304125839Speter@subsection Creating a directory tree from a number of files 304217721Speter@cindex Importing files 304317721Speter 304417721SpeterWhen you begin using @sc{cvs}, you will probably already have several 304517721Speterprojects that can be 304617721Speterput under @sc{cvs} control. In these cases the easiest way is to use the 304717721Speter@code{import} command. An example is probably the easiest way to 304817721Speterexplain how to use it. If the files you want to install in 304925839Speter@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 305025839Speterrepository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 305117721Speter 305217721Speter@example 305325839Speter$ cd @var{wdir} 305425839Speter$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 305517721Speter@end example 305617721Speter 305717721SpeterUnless you supply a log message with the @samp{-m} 305817721Speterflag, @sc{cvs} starts an editor and prompts for a 305917721Spetermessage. The string @samp{yoyo} is a @dfn{vendor tag}, 306017721Speterand @samp{start} is a @dfn{release tag}. They may fill 306117721Speterno purpose in this context, but since @sc{cvs} requires 306217721Speterthem they must be present. @xref{Tracking sources}, for 306317721Spetermore information about them. 306417721Speter 306517721SpeterYou can now verify that it worked, and remove your 306617721Speteroriginal source directory. 306725839Speter@c FIXME: Need to say more about "verify that it 306825839Speter@c worked". What should the user look for in the output 306925839Speter@c from "diff -r"? 307017721Speter 307117721Speter@example 307217721Speter$ cd .. 307366525Speter$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 307466525Speter$ diff -r @var{wdir} yoyodyne/@var{rdir} 307566525Speter$ rm -r @var{wdir} 307617721Speter@end example 307717721Speter 307817721Speter@noindent 307917721SpeterErasing the original sources is a good idea, to make sure that you do 308066525Speternot accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 308117721SpeterOf course, it would be wise to make sure that you have 308217721Spetera backup of the sources before you remove them. 308317721Speter 308417721SpeterThe @code{checkout} command can either take a module 308517721Spetername as argument (as it has done in all previous 308617721Speterexamples) or a path name relative to @code{$CVSROOT}, 308717721Speteras it did in the example above. 308817721Speter 308917721SpeterIt is a good idea to check that the permissions 309066525Speter@sc{cvs} sets on the directories inside @code{$CVSROOT} 309117721Speterare reasonable, and that they belong to the proper 309217721Spetergroups. @xref{File permissions}. 309317721Speter 309425839SpeterIf some of the files you want to import are binary, you 309525839Spetermay want to use the wrappers features to specify which 309625839Speterfiles are binary and which are not. @xref{Wrappers}. 309725839Speter 309817721Speter@c The node name is too long, but I am having trouble 309917721Speter@c thinking of something more concise. 310017721Speter@node From other version control systems 310117721Speter@subsection Creating Files From Other Version Control Systems 310226065Speter@cindex Importing files, from other version control systems 310317721Speter 310417721SpeterIf you have a project which you are maintaining with 310517721Speteranother version control system, such as @sc{rcs}, you 310617721Spetermay wish to put the files from that project into 310717721Speter@sc{cvs}, and preserve the revision history of the 310817721Speterfiles. 310917721Speter 311017721Speter@table @asis 311117721Speter@cindex RCS, importing files from 311217721Speter@item From RCS 311317721SpeterIf you have been using @sc{rcs}, find the @sc{rcs} 311417721Speterfiles---usually a file named @file{foo.c} will have its 311517721Speter@sc{rcs} file in @file{RCS/foo.c,v} (but it could be 311617721Speterother places; consult the @sc{rcs} documentation for 311717721Speterdetails). Then create the appropriate directories in 311817721Speter@sc{cvs} if they do not already exist. Then copy the 311917721Speterfiles into the appropriate directories in the @sc{cvs} 312017721Speterrepository (the name in the repository must be the name 312117721Speterof the source file with @samp{,v} added; the files go 312254427Speterdirectly in the appropriate directory of the repository, 312317721Speternot in an @file{RCS} subdirectory). This is one of the 312417721Speterfew times when it is a good idea to access the @sc{cvs} 312517721Speterrepository directly, rather than using @sc{cvs} 312617721Spetercommands. Then you are ready to check out a new 312717721Speterworking directory. 312817721Speter@c Someday there probably should be a "cvs import -t 312917721Speter@c rcs" or some such. It could even create magic 313017721Speter@c branches. It could also do something about the case 313117721Speter@c where the RCS file had a (non-magic) "0" branch. 313217721Speter 313325839SpeterThe @sc{rcs} file should not be locked when you move it 313425839Speterinto @sc{cvs}; if it is, @sc{cvs} will have trouble 313525839Speterletting you operate on it. 313625839Speter@c What is the easiest way to unlock your files if you 313725839Speter@c have them locked? Especially if you have a lot of them? 313825839Speter@c This is a CVS bug/misfeature; importing RCS files 313925839Speter@c should ignore whether they are locked and leave them in 314025839Speter@c an unlocked state. Yet another reason for a separate 314125839Speter@c "import RCS file" command. 314225839Speter 314317721Speter@c How many is "many"? Or do they just import RCS files? 314417721Speter@item From another version control system 314517721SpeterMany version control systems have the ability to export 314617721Speter@sc{rcs} files in the standard format. If yours does, 314717721Speterexport the @sc{rcs} files and then follow the above 314817721Speterinstructions. 314917721Speter 315032785SpeterFailing that, probably your best bet is to write a 315132785Speterscript that will check out the files one revision at a 315232785Spetertime using the command line interface to the other 315332785Spetersystem, and then check the revisions into @sc{cvs}. 315432785SpeterThe @file{sccs2rcs} script mentioned below may be a 315532785Speteruseful example to follow. 315632785Speter 315717721Speter@cindex SCCS, importing files from 315817721Speter@item From SCCS 315917721SpeterThere is a script in the @file{contrib} directory of 316017721Speterthe @sc{cvs} source distribution called @file{sccs2rcs} 316117721Speterwhich converts @sc{sccs} files to @sc{rcs} files. 316217721SpeterNote: you must run it on a machine which has both 316317721Speter@sc{sccs} and @sc{rcs} installed, and like everything 316417721Speterelse in contrib it is unsupported (your mileage may 316517721Spetervary). 316632785Speter 316732785Speter@cindex PVCS, importing files from 316832785Speter@item From PVCS 316932785SpeterThere is a script in the @file{contrib} directory of 317032785Speterthe @sc{cvs} source distribution called @file{pvcs_to_rcs} 317132785Speterwhich converts @sc{pvcs} archives to @sc{rcs} files. 317232785SpeterYou must run it on a machine which has both 317332785Speter@sc{pvcs} and @sc{rcs} installed, and like everything 317432785Speterelse in contrib it is unsupported (your mileage may 317532785Spetervary). See the comments in the script for details. 317617721Speter@end table 317725839Speter@c CMZ and/or PATCHY were systems that were used in the 317825839Speter@c high energy physics community (especially for 317925839Speter@c CERNLIB). CERN has replaced them with CVS, but the 318025839Speter@c CAR format seems to live on as a way to submit 318125839Speter@c changes. There is a program car2cvs which converts 318225839Speter@c but I'm not sure where one gets a copy. 318325839Speter@c Not sure it is worth mentioning here, since it would 318425839Speter@c appear to affect only one particular community. 318525839Speter@c Best page for more information is: 318625839Speter@c http://wwwcn1.cern.ch/asd/cvs/index.html 318725839Speter@c See also: 318825839Speter@c http://ecponion.cern.ch/ecpsa/cernlib.html 318917721Speter 319017721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319117721Speter@node From scratch 319225839Speter@subsection Creating a directory tree from scratch 319317721Speter 319444852Speter@c Also/instead should be documenting 319525839Speter@c $ cvs co -l . 319625839Speter@c $ mkdir tc 319725839Speter@c $ cvs add tc 319825839Speter@c $ cd tc 319925839Speter@c $ mkdir man 320025839Speter@c $ cvs add man 320125839Speter@c etc. 320225839Speter@c Using import to create the directories only is 320325839Speter@c probably a somewhat confusing concept. 320417721SpeterFor a new project, the easiest thing to do is probably 320517721Speterto create an empty directory structure, like this: 320617721Speter 320717721Speter@example 320817721Speter$ mkdir tc 320917721Speter$ mkdir tc/man 321017721Speter$ mkdir tc/testing 321117721Speter@end example 321217721Speter 321317721SpeterAfter that, you use the @code{import} command to create 321417721Speterthe corresponding (empty) directory structure inside 321517721Speterthe repository: 321617721Speter 321717721Speter@example 321817721Speter$ cd tc 321917721Speter$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 322017721Speter@end example 322117721Speter 3222130303SpeterThis will add yoyodyne/@var{dir} as a directory under 3223130303Speter@code{$CVSROOT}. 3224130303Speter 3225175261SobrienUse @code{checkout} to get the new project. Then, use @code{add} 3226175261Sobriento add files (and new directories) as needed. 322717721Speter 3228175261Sobrien@example 3229175261Sobrien$ cd .. 3230175261Sobrien$ cvs co yoyodyne/@var{dir} 3231175261Sobrien@end example 3232175261Sobrien 323317721SpeterCheck that the permissions @sc{cvs} sets on the 323466525Speterdirectories inside @code{$CVSROOT} are reasonable. 323517721Speter 323617721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 323717721Speter@node Defining the module 323817721Speter@section Defining the module 323917721Speter@cindex Defining a module 324017721Speter@cindex Editing the modules file 324117721Speter@cindex Module, defining 324217721Speter@cindex Modules file, changing 324317721Speter 324417721SpeterThe next step is to define the module in the 324517721Speter@file{modules} file. This is not strictly necessary, 324617721Speterbut modules can be convenient in grouping together 324717721Speterrelated files and directories. 324817721Speter 324917721SpeterIn simple cases these steps are sufficient to define a module. 325017721Speter 325117721Speter@enumerate 325217721Speter@item 325317721SpeterGet a working copy of the modules file. 325417721Speter 325517721Speter@example 325625839Speter$ cvs checkout CVSROOT/modules 325725839Speter$ cd CVSROOT 325817721Speter@end example 325917721Speter 326017721Speter@item 326117721SpeterEdit the file and insert a line that defines the module. @xref{Intro 326217721Speteradministrative files}, for an introduction. @xref{modules}, for a full 326317721Speterdescription of the modules file. You can use the 326417721Speterfollowing line to define the module @samp{tc}: 326517721Speter 326617721Speter@example 326717721Spetertc yoyodyne/tc 326817721Speter@end example 326917721Speter 327017721Speter@item 327117721SpeterCommit your changes to the modules file. 327217721Speter 327317721Speter@example 327417721Speter$ cvs commit -m "Added the tc module." modules 327517721Speter@end example 327617721Speter 327717721Speter@item 327817721SpeterRelease the modules module. 327917721Speter 328017721Speter@example 328117721Speter$ cd .. 328225839Speter$ cvs release -d CVSROOT 328317721Speter@end example 328417721Speter@end enumerate 328517721Speter 328617721Speter@c --------------------------------------------------------------------- 328732785Speter@node Revisions 328832785Speter@chapter Revisions 328917721Speter 329025839SpeterFor many uses of @sc{cvs}, one doesn't need to worry 329125839Spetertoo much about revision numbers; @sc{cvs} assigns 329225839Speternumbers such as @code{1.1}, @code{1.2}, and so on, and 329325839Speterthat is all one needs to know. However, some people 329425839Speterprefer to have more knowledge and control concerning 329525839Speterhow @sc{cvs} assigns revision numbers. 329617721Speter 329725839SpeterIf one wants to keep track of a set of revisions 329825839Speterinvolving more than one file, such as which revisions 329925839Speterwent into a particular release, one uses a @dfn{tag}, 330025839Speterwhich is a symbolic revision which can be assigned to a 330125839Speternumeric revision in each file. 330225839Speter 330317721Speter@menu 330425839Speter* Revision numbers:: The meaning of a revision number 330525839Speter* Versions revisions releases:: Terminology used in this manual 330625839Speter* Assigning revisions:: Assigning revisions 330717721Speter* Tags:: Tags--Symbolic revisions 330854427Speter* Tagging the working directory:: The cvs tag command 330954427Speter* Tagging by date/tag:: The cvs rtag command 331054427Speter* Modifying tags:: Adding, renaming, and deleting tags 331154427Speter* Tagging add/remove:: Tags with adding and removing files 331232785Speter* Sticky tags:: Certain tags are persistent 331317721Speter@end menu 331417721Speter 331517721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 331625839Speter@node Revision numbers 331725839Speter@section Revision numbers 331825839Speter@cindex Revision numbers 331925839Speter@cindex Revision tree 332025839Speter@cindex Linear development 332125839Speter@cindex Number, revision- 332225839Speter@cindex Decimal revision number 332325839Speter@cindex Branch number 332425839Speter@cindex Number, branch 332525839Speter 332625839SpeterEach version of a file has a unique @dfn{revision 332725839Speternumber}. Revision numbers look like @samp{1.1}, 332825839Speter@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 332925839SpeterA revision number always has an even number of 333025839Speterperiod-separated decimal integers. By default revision 333125839Speter1.1 is the first revision of a file. Each successive 333225839Speterrevision is given a new number by increasing the 333325839Speterrightmost number by one. The following figure displays 333425839Spetera few revisions, with newer revisions to the right. 333525839Speter 333625839Speter@example 333725839Speter +-----+ +-----+ +-----+ +-----+ +-----+ 333825839Speter ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 333925839Speter +-----+ +-----+ +-----+ +-----+ +-----+ 334025839Speter@end example 334125839Speter 334232785SpeterIt is also possible to end up with numbers containing 334332785Spetermore than one period, for example @samp{1.3.2.2}. Such 334432785Speterrevisions represent revisions on branches 334532785Speter(@pxref{Branching and merging}); such revision numbers 334632785Speterare explained in detail in @ref{Branches and 334732785Speterrevisions}. 334825839Speter 334925839Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 335025839Speter@node Versions revisions releases 335125839Speter@section Versions, revisions and releases 335225839Speter@cindex Revisions, versions and releases 335325839Speter@cindex Versions, revisions and releases 335425839Speter@cindex Releases, revisions and versions 335525839Speter 335625839SpeterA file can have several versions, as described above. 335725839SpeterLikewise, a software product can have several versions. 335825839SpeterA software product is often given a version number such 335925839Speteras @samp{4.1.1}. 336025839Speter 336125839SpeterVersions in the first sense are called @dfn{revisions} 336225839Speterin this document, and versions in the second sense are 336325839Spetercalled @dfn{releases}. To avoid confusion, the word 336425839Speter@dfn{version} is almost never used in this document. 336525839Speter 336625839Speter@node Assigning revisions 336725839Speter@section Assigning revisions 336825839Speter 336925839Speter@c We avoid the "major revision" terminology. It seems 337025839Speter@c like jargon. Hopefully "first number" is clear enough. 337125839SpeterBy default, @sc{cvs} will assign numeric revisions by 337225839Speterleaving the first number the same and incrementing the 337325839Spetersecond number. For example, @code{1.1}, @code{1.2}, 337425839Speter@code{1.3}, etc. 337525839Speter 337625839SpeterWhen adding a new file, the second number will always 337725839Speterbe one and the first number will equal the highest 337825839Speterfirst number of any file in that directory. For 337925839Speterexample, the current directory contains files whose 338025839Speterhighest numbered revisions are @code{1.7}, @code{3.1}, 338125839Speterand @code{4.12}, then an added file will be given the 338225839Speternumeric revision @code{4.1}. 3383128266Speter(When using client/server @sc{cvs}, 3384128266Speteronly files that are actually sent to the server are considered.) 338525839Speter 338625839Speter@c This is sort of redundant with something we said a 338725839Speter@c while ago. Somewhere we need a better way of 338825839Speter@c introducing how the first number can be anything 338925839Speter@c except "1", perhaps. Also I don't think this 339025839Speter@c presentation is clear on why we are discussing releases 339125839Speter@c and first numbers of numeric revisions in the same 339225839Speter@c breath. 339325839SpeterNormally there is no reason to care 339425839Speterabout the revision numbers---it is easier to treat them 339525839Speteras internal numbers that @sc{cvs} maintains, and tags 339625839Speterprovide a better way to distinguish between things like 339725839Speterrelease 1 versus release 2 of your product 339825839Speter(@pxref{Tags}). However, if you want to set the 339925839Speternumeric revisions, the @samp{-r} option to @code{cvs 340025839Spetercommit} can do that. The @samp{-r} option implies the 340125839Speter@samp{-f} option, in the sense that it causes the 340225839Speterfiles to be committed even if they are not modified. 340325839Speter 340425839SpeterFor example, to bring all your files up to 340525839Speterrevision 3.0 (including those that haven't changed), 340625839Speteryou might invoke: 340725839Speter 340825839Speter@example 340925839Speter$ cvs commit -r 3.0 341025839Speter@end example 341125839Speter 341225839SpeterNote that the number you specify with @samp{-r} must be 341325839Speterlarger than any existing revision number. That is, if 341425839Speterrevision 3.0 exists, you cannot @samp{cvs commit 341525839Speter-r 1.3}. If you want to maintain several releases in 341632785Speterparallel, you need to use a branch (@pxref{Branching and merging}). 341725839Speter 341825839Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 341917721Speter@node Tags 342017721Speter@section Tags--Symbolic revisions 342117721Speter@cindex Tags 342217721Speter 342317721SpeterThe revision numbers live a life of their own. They 342417721Speterneed not have anything at all to do with the release 342517721Speternumbers of your software product. Depending 342617721Speteron how you use @sc{cvs} the revision numbers might change several times 342717721Speterbetween two releases. As an example, some of the 342817721Spetersource files that make up @sc{rcs} 5.6 have the following 342917721Speterrevision numbers: 343017721Speter@cindex RCS revision numbers 343117721Speter 343217721Speter@example 343317721Speterci.c 5.21 343417721Speterco.c 5.9 343517721Speterident.c 5.3 343617721Speterrcs.c 5.12 343717721Speterrcsbase.h 5.11 343817721Speterrcsdiff.c 5.10 343917721Speterrcsedit.c 5.11 344017721Speterrcsfcmp.c 5.9 344117721Speterrcsgen.c 5.10 344217721Speterrcslex.c 5.11 344317721Speterrcsmap.c 5.2 344417721Speterrcsutil.c 5.10 344517721Speter@end example 344617721Speter 344717721Speter@cindex tag, command, introduction 344817721Speter@cindex Tag, symbolic name 344917721Speter@cindex Symbolic name (tag) 345017721Speter@cindex Name, symbolic (tag) 345132785Speter@cindex HEAD, as reserved tag name 345232785Speter@cindex BASE, as reserved tag name 345317721SpeterYou can use the @code{tag} command to give a symbolic name to a 345417721Spetercertain revision of a file. You can use the @samp{-v} flag to the 345517721Speter@code{status} command to see all tags that a file has, and 345625839Speterwhich revision numbers they represent. Tag names must 345725839Speterstart with an uppercase or lowercase letter and can 345817721Spetercontain uppercase and lowercase letters, digits, 345917721Speter@samp{-}, and @samp{_}. The two tag names @code{BASE} 346017721Speterand @code{HEAD} are reserved for use by @sc{cvs}. It 346117721Speteris expected that future names which are special to 346225839Speter@sc{cvs} will be specially named, for example by 346325839Speterstarting with @samp{.}, rather than being named analogously to 346417721Speter@code{BASE} and @code{HEAD}, to avoid conflicts with 346517721Speteractual tag names. 346644852Speter@c Including a character such as % or = has also been 346725839Speter@c suggested as the naming convention for future 346825839Speter@c special tag names. Starting with . is nice because 346925839Speter@c that is not a legal tag name as far as RCS is concerned. 347025839Speter@c FIXME: CVS actually accepts quite a few characters 347125839Speter@c in tag names, not just the ones documented above 347225839Speter@c (see RCS_check_tag). RCS 347325839Speter@c defines legitimate tag names by listing illegal 347425839Speter@c characters rather than legal ones. CVS is said to lose its 347525839Speter@c mind if you try to use "/" (try making such a tag sticky 347625839Speter@c and using "cvs status" client/server--see remote 347725839Speter@c protocol format for entries line for probable cause). 347825839Speter@c TODO: The testsuite 347925839Speter@c should test for whatever are documented above as 348025839Speter@c officially-OK tag names, and CVS should at least reject 348125839Speter@c characters that won't work, like "/". 348217721Speter 348325839SpeterYou'll want to choose some convention for naming tags, 348425839Speterbased on information such as the name of the program 348525839Speterand the version number of the release. For example, 348625839Speterone might take the name of the program, immediately 348725839Speterfollowed by the version number with @samp{.} changed to 348881404Speter@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 348925839Speter@code{cvs1-9}. If you choose a consistent convention, 349025839Speterthen you won't constantly be guessing whether a tag is 349125839Speter@code{cvs-1-9} or @code{cvs1_9} or what. You might 349225839Spetereven want to consider enforcing your convention in the 3493128266Speter@file{taginfo} file (@pxref{taginfo}). 349425839Speter@c Might be nice to say more about using taginfo this 349525839Speter@c way, like giving an example, or pointing out any particular 349625839Speter@c issues which arise. 349725839Speter 349817721Speter@cindex Adding a tag 349966525Speter@cindex Tag, example 350017721SpeterThe following example shows how you can add a tag to a 350117721Speterfile. The commands must be issued inside your working 350254427Speterdirectory. That is, you should issue the 350317721Spetercommand in the directory where @file{backend.c} 350417721Speterresides. 350517721Speter 350617721Speter@example 350744852Speter$ cvs tag rel-0-4 backend.c 350817721SpeterT backend.c 350917721Speter$ cvs status -v backend.c 351017721Speter=================================================================== 351117721SpeterFile: backend.c Status: Up-to-date 351217721Speter 351317721Speter Version: 1.4 Tue Dec 1 14:39:01 1992 351425839Speter RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 351517721Speter Sticky Tag: (none) 351617721Speter Sticky Date: (none) 351717721Speter Sticky Options: (none) 351817721Speter 351917721Speter Existing Tags: 352044852Speter rel-0-4 (revision: 1.4) 352117721Speter 352217721Speter@end example 352317721Speter 352454427SpeterFor a complete summary of the syntax of @code{cvs tag}, 352554427Speterincluding the various options, see @ref{Invoking CVS}. 352654427Speter 352717721SpeterThere is seldom reason to tag a file in isolation. A more common use is 352817721Speterto tag all the files that constitute a module with the same tag at 352917721Speterstrategic points in the development life-cycle, such as when a release 353017721Speteris made. 353117721Speter 353217721Speter@example 353344852Speter$ cvs tag rel-1-0 . 353417721Spetercvs tag: Tagging . 353517721SpeterT Makefile 353617721SpeterT backend.c 353717721SpeterT driver.c 353817721SpeterT frontend.c 353917721SpeterT parser.c 354017721Speter@end example 354117721Speter 3542102840Speter@noindent 354317721Speter(When you give @sc{cvs} a directory as argument, it generally applies the 354417721Speteroperation to all the files in that directory, and (recursively), to any 354517721Spetersubdirectories that it may contain. @xref{Recursive behavior}.) 354617721Speter 354717721Speter@cindex Retrieving an old revision using tags 354817721Speter@cindex Tag, retrieving old revisions 354917721SpeterThe @code{checkout} command has a flag, @samp{-r}, that lets you check out 355017721Spetera certain revision of a module. This flag makes it easy to 355117721Speterretrieve the sources that make up release 1.0 of the module @samp{tc} at 355217721Speterany time in the future: 355317721Speter 355417721Speter@example 355544852Speter$ cvs checkout -r rel-1-0 tc 355617721Speter@end example 355717721Speter 355817721Speter@noindent 355917721SpeterThis is useful, for instance, if someone claims that there is a bug in 356017721Speterthat release, but you cannot find the bug in the current working copy. 356117721Speter 356217721SpeterYou can also check out a module as it was at any given date. 356354427Speter@xref{checkout options}. When specifying @samp{-r} to 356454427Speterany of these commands, you will need beware of sticky 356554427Spetertags; see @ref{Sticky tags}. 356617721Speter 356717721SpeterWhen you tag more than one file with the same tag you 356817721Spetercan think about the tag as "a curve drawn through a 3569177391Sobrienmatrix of filename vs.@: revision number." Say we have 5 357017721Speterfiles with the following revisions: 357117721Speter 357217721Speter@example 357317721Speter@group 357417721Speter file1 file2 file3 file4 file5 357517721Speter 357617721Speter 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 357717721Speter 1.2*- 1.2 1.2 -1.2*- 357817721Speter 1.3 \- 1.3*- 1.3 / 1.3 357917721Speter 1.4 \ 1.4 / 1.4 358017721Speter \-1.5*- 1.5 358117721Speter 1.6 358217721Speter@end group 358317721Speter@end example 358417721Speter 358517721SpeterAt some time in the past, the @code{*} versions were tagged. 358617721SpeterYou can think of the tag as a handle attached to the curve 358717721Speterdrawn through the tagged revisions. When you pull on 358817721Speterthe handle, you get all the tagged revisions. Another 358917721Speterway to look at it is that you "sight" through a set of 359017721Speterrevisions that is "flat" along the tagged revisions, 359117721Speterlike this: 359217721Speter 359317721Speter@example 359417721Speter@group 359517721Speter file1 file2 file3 file4 file5 359617721Speter 359717721Speter 1.1 359817721Speter 1.2 359917721Speter 1.1 1.3 _ 360017721Speter 1.1 1.2 1.4 1.1 / 360117721Speter 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here 360217721Speter 1.3 1.6 1.3 \_ 360317721Speter 1.4 1.4 360417721Speter 1.5 360517721Speter@end group 360617721Speter@end example 360717721Speter 360854427Speter@node Tagging the working directory 360954427Speter@section Specifying what to tag from the working directory 361054427Speter 361166525Speter@cindex tag (subcommand) 361254427SpeterThe example in the previous section demonstrates one of 361354427Speterthe most common ways to choose which revisions to tag. 361454427SpeterNamely, running the @code{cvs tag} command without 361554427Speterarguments causes @sc{cvs} to select the revisions which 361654427Speterare checked out in the current working directory. For 361754427Speterexample, if the copy of @file{backend.c} in working 361854427Speterdirectory was checked out from revision 1.4, then 361954427Speter@sc{cvs} will tag revision 1.4. Note that the tag is 362054427Speterapplied immediately to revision 1.4 in the repository; 362154427Spetertagging is not like modifying a file, or other 362254427Speteroperations in which one first modifies the working 362354427Speterdirectory and then runs @code{cvs commit} to transfer 362454427Speterthat modification to the repository. 362554427Speter 362654427SpeterOne potentially surprising aspect of the fact that 362754427Speter@code{cvs tag} operates on the repository is that you 362854427Speterare tagging the checked-in revisions, which may differ 362954427Speterfrom locally modified files in your working directory. 363054427SpeterIf you want to avoid doing this by mistake, specify the 363154427Speter@samp{-c} option to @code{cvs tag}. If there are any 363254427Speterlocally modified files, @sc{cvs} will abort with an 363354427Spetererror before it tags any files: 363454427Speter 363554427Speter@example 363654427Speter$ cvs tag -c rel-0-4 363754427Spetercvs tag: backend.c is locally modified 363854427Spetercvs [tag aborted]: correct the above errors first! 363954427Speter@end example 364054427Speter 364154427Speter@node Tagging by date/tag 364254427Speter@section Specifying what to tag by date or revision 364366525Speter@cindex rtag (subcommand) 364454427Speter 364554427SpeterThe @code{cvs rtag} command tags the repository as of a 364654427Spetercertain date or time (or can be used to tag the latest 364754427Speterrevision). @code{rtag} works directly on the 364854427Speterrepository contents (it requires no prior checkout and 364954427Speterdoes not look for a working directory). 365054427Speter 365154427SpeterThe following options specify which date or revision to 365254427Spetertag. See @ref{Common options}, for a complete 365354427Speterdescription of them. 365454427Speter 365554427Speter@table @code 365654427Speter@item -D @var{date} 365754427SpeterTag the most recent revision no later than @var{date}. 365854427Speter 365954427Speter@item -f 366054427SpeterOnly useful with the @samp{-D @var{date}} or @samp{-r @var{tag}} 366154427Speterflags. If no matching revision is found, use the most 366254427Speterrecent revision (instead of ignoring the file). 366354427Speter 366454427Speter@item -r @var{tag} 366554427SpeterOnly tag those files that contain existing tag @var{tag}. 366654427Speter@end table 366754427Speter 366854427SpeterThe @code{cvs tag} command also allows one to specify 366954427Speterfiles by revision or date, using the same @samp{-r}, 367054427Speter@samp{-D}, and @samp{-f} options. However, this 367154427Speterfeature is probably not what you want. The reason is 367254427Speterthat @code{cvs tag} chooses which files to tag based on 367354427Speterthe files that exist in the working directory, rather 367454427Speterthan the files which existed as of the given tag/date. 367554427SpeterTherefore, you are generally better off using @code{cvs 367654427Speterrtag}. The exceptions might be cases like: 367754427Speter 367854427Speter@example 367954427Spetercvs tag -r 1.4 backend.c 368054427Speter@end example 368154427Speter 368254427Speter@node Modifying tags 368354427Speter@section Deleting, moving, and renaming tags 368454427Speter 368554427Speter@c Also see: 368654427Speter@c "How do I move or rename a magic branch tag?" 368754427Speter@c in the FAQ (I think the issues it talks about still 368854427Speter@c apply, but this could use some sanity.sh work). 368954427Speter 369054427SpeterNormally one does not modify tags. They exist in order 369154427Speterto record the history of the repository and so deleting 369254427Speterthem or changing their meaning would, generally, not be 369354427Speterwhat you want. 369454427Speter 369554427SpeterHowever, there might be cases in which one uses a tag 369654427Spetertemporarily or accidentally puts one in the wrong 369754427Speterplace. Therefore, one might delete, move, or rename a 3698102840Spetertag. 3699102840Speter 3700102840Speter@noindent 3701177391Sobrien@strong{WARNING: The commands in this section are 370254427Speterdangerous; they permanently discard historical 3703102840Speterinformation and it can be difficult or impossible to 370454427Speterrecover from errors. If you are a @sc{cvs} 370554427Speteradministrator, you may consider restricting these 3706128266Spetercommands with the @file{taginfo} file (@pxref{taginfo}).} 370754427Speter 370866525Speter@cindex Deleting tags 3709102840Speter@cindex Deleting branch tags 371066525Speter@cindex Removing tags 3711102840Speter@cindex Removing branch tags 371266525Speter@cindex Tags, deleting 3713102840Speter@cindex Branch tags, deleting 371454427SpeterTo delete a tag, specify the @samp{-d} option to either 371554427Speter@code{cvs tag} or @code{cvs rtag}. For example: 371654427Speter 371754427Speter@example 371854427Spetercvs rtag -d rel-0-4 tc 371954427Speter@end example 372054427Speter 3721102840Speter@noindent 3722102840Speterdeletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 3723102840SpeterIn the event that branch tags are encountered within the repository 3724102840Speterwith the given name, a warning message will be issued and the branch 3725102840Spetertag will not be deleted. If you are absolutely certain you know what 3726102840Speteryou are doing, the @code{-B} option may be specified to allow deletion 3727102840Speterof branch tags. In that case, any non-branch tags encountered will 3728102840Spetertrigger warnings and will not be deleted. 372954427Speter 3730102840Speter@noindent 3731177391Sobrien@strong{WARNING: Moving branch tags is very dangerous! If you think 3732128266Speteryou need the @code{-B} option, think again and ask your @sc{cvs} 3733128266Speteradministrator about it (if that isn't you). There is almost certainly 3734128266Speteranother way to accomplish what you want to accomplish.} 3735102840Speter 373666525Speter@cindex Moving tags 3737102840Speter@cindex Moving branch tags 373866525Speter@cindex Tags, moving 3739102840Speter@cindex Branch tags, moving 374054427SpeterWhen we say @dfn{move} a tag, we mean to make the same 374154427Spetername point to different revisions. For example, the 374254427Speter@code{stable} tag may currently point to revision 1.4 374354427Speterof @file{backend.c} and perhaps we want to make it 3744102840Speterpoint to revision 1.6. To move a non-branch tag, specify the 374554427Speter@samp{-F} option to either @code{cvs tag} or @code{cvs 374654427Speterrtag}. For example, the task just mentioned might be 374754427Speteraccomplished as: 374854427Speter 374954427Speter@example 375054427Spetercvs tag -r 1.6 -F stable backend.c 375154427Speter@end example 375254427Speter 3753102840Speter@noindent 3754102840SpeterIf any branch tags are encountered in the repository 3755102840Speterwith the given name, a warning is issued and the branch 3756102840Spetertag is not disturbed. If you are absolutely certain you 3757102840Speterwish to move the branch tag, the @code{-B} option may be specified. 3758102840SpeterIn that case, non-branch tags encountered with the given 3759102840Spetername are ignored with a warning message. 3760102840Speter 3761102840Speter@noindent 3762177391Sobrien@strong{WARNING: Moving branch tags is very dangerous! If you think you 3763128266Speterneed the @code{-B} option, think again and ask your @sc{cvs} 3764128266Speteradministrator about it (if that isn't you). There is almost certainly 3765128266Speteranother way to accomplish what you want to accomplish.} 3766102840Speter 376766525Speter@cindex Renaming tags 376866525Speter@cindex Tags, renaming 376954427SpeterWhen we say @dfn{rename} a tag, we mean to make a 377054427Speterdifferent name point to the same revisions as the old 377154427Spetertag. For example, one may have misspelled the tag name 377254427Speterand want to correct it (hopefully before others are 377354427Speterrelying on the old spelling). To rename a tag, first 377454427Spetercreate a new tag using the @samp{-r} option to 3775102840Speter@code{cvs rtag}, and then delete the old name. (Caution: 3776102840Speterthis method will not work with branch tags.) 3777102840SpeterThis leaves the new tag on exactly the 3778102840Spetersame files as the old tag. For example: 377954427Speter 378054427Speter@example 378154427Spetercvs rtag -r old-name-0-4 rel-0-4 tc 378254427Spetercvs rtag -d old-name-0-4 tc 378354427Speter@end example 378454427Speter 378554427Speter@node Tagging add/remove 378654427Speter@section Tagging and adding and removing files 378754427Speter 378854427SpeterThe subject of exactly how tagging interacts with 378954427Speteradding and removing files is somewhat obscure; for the 379054427Spetermost part @sc{cvs} will keep track of whether files 379154427Speterexist or not without too much fussing. By default, 379254427Spetertags are applied to only files which have a revision 379354427Spetercorresponding to what is being tagged. Files which did 379454427Speternot exist yet, or which were already removed, simply 379554427Speteromit the tag, and @sc{cvs} knows to treat the absence 379654427Speterof a tag as meaning that the file didn't exist as of 379754427Speterthat tag. 379854427Speter 379954427SpeterHowever, this can lose a small amount of information. 380054427SpeterFor example, suppose a file was added and then removed. 380154427SpeterThen, if the tag is missing for that file, there is no 380254427Speterway to know whether the tag refers to the time before 380354427Speterthe file was added, or the time after it was removed. 380454427SpeterIf you specify the @samp{-r} option to @code{cvs rtag}, 380554427Speterthen @sc{cvs} tags the files which have been removed, 380654427Speterand thereby avoids this problem. For example, one 380754427Spetermight specify @code{-r HEAD} to tag the head. 380854427Speter 380954427SpeterOn the subject of adding and removing files, the 381054427Speter@code{cvs rtag} command has a @samp{-a} option which 381154427Spetermeans to clear the tag from removed files that would 381254427Speternot otherwise be tagged. For example, one might 381354427Speterspecify this option in conjunction with @samp{-F} when 381454427Spetermoving a tag. If one moved a tag without @samp{-a}, 381554427Speterthen the tag in the removed files might still refer to 381654427Speterthe old revision, rather than reflecting the fact that 381754427Speterthe file had been removed. I don't think this is 381854427Speternecessary if @samp{-r} is specified, as noted above. 381954427Speter 382017721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 382132785Speter@node Sticky tags 382232785Speter@section Sticky tags 382332785Speter@cindex Sticky tags 382432785Speter@cindex Tags, sticky 382532785Speter 382632785Speter@c A somewhat related issue is per-directory sticky 382732785Speter@c tags (see comment at CVS/Tag in node Working 382832785Speter@c directory storage); we probably want to say 382932785Speter@c something like "you can set a sticky tag for only 383032785Speter@c some files, but you don't want to" or some such. 383132785Speter 383232785SpeterSometimes a working copy's revision has extra data 383332785Speterassociated with it, for example it might be on a branch 383432785Speter(@pxref{Branching and merging}), or restricted to 383532785Speterversions prior to a certain date by @samp{checkout -D} 383632785Speteror @samp{update -D}. Because this data persists -- 383732785Speterthat is, it applies to subsequent commands in the 383832785Speterworking copy -- we refer to it as @dfn{sticky}. 383932785Speter 384032785SpeterMost of the time, stickiness is an obscure aspect of 384132785Speter@sc{cvs} that you don't need to think about. However, 384232785Spetereven if you don't want to use the feature, you may need 384332785Speterto know @emph{something} about sticky tags (for 384432785Speterexample, how to avoid them!). 384532785Speter 384632785SpeterYou can use the @code{status} command to see if any 384732785Spetersticky tags or dates are set: 384832785Speter 384932785Speter@example 385032785Speter$ cvs status driver.c 385132785Speter=================================================================== 385232785SpeterFile: driver.c Status: Up-to-date 385332785Speter 385432785Speter Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 385532785Speter RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 385644852Speter Sticky Tag: rel-1-0-patches (branch: 1.7.2) 385732785Speter Sticky Date: (none) 385832785Speter Sticky Options: (none) 385932785Speter 386032785Speter@end example 386132785Speter 386232785Speter@cindex Resetting sticky tags 386332785Speter@cindex Sticky tags, resetting 386432785Speter@cindex Deleting sticky tags 386532785SpeterThe sticky tags will remain on your working files until 386632785Speteryou delete them with @samp{cvs update -A}. The 3867130303Speter@samp{-A} option merges local changes into the version of the 3868130303Speterfile from the head of the trunk, removing any sticky tags, 3869175261Sobriendates, or options (other than sticky @samp{-k} options on locally 3870175261Sobrienmodified files). See @ref{update} for more on the operation 3871128266Speterof @code{cvs update}. 387232785Speter 387366525Speter@cindex Sticky date 387432785SpeterThe most common use of sticky tags is to identify which 387532785Speterbranch one is working on, as described in 387632785Speter@ref{Accessing branches}. However, non-branch 387732785Spetersticky tags have uses as well. For example, 387832785Spetersuppose that you want to avoid updating your working 387932785Speterdirectory, to isolate yourself from possibly 388032785Speterdestabilizing changes other people are making. You 388132785Spetercan, of course, just refrain from running @code{cvs 388232785Speterupdate}. But if you want to avoid updating only a 388332785Speterportion of a larger tree, then sticky tags can help. 388432785SpeterIf you check out a certain revision (such as 1.4) it 388532785Speterwill become sticky. Subsequent @code{cvs update} 388632785Spetercommands will 388732785Speternot retrieve the latest revision until you reset the 388832785Spetertag with @code{cvs update -A}. Likewise, use of the 388932785Speter@samp{-D} option to @code{update} or @code{checkout} 389032785Spetersets a @dfn{sticky date}, which, similarly, causes that 389132785Speterdate to be used for future retrievals. 389232785Speter 389354427SpeterPeople often want to retrieve an old version of 389454427Spetera file without setting a sticky tag. This can 389554427Speterbe done with the @samp{-p} option to @code{checkout} or 389632785Speter@code{update}, which sends the contents of the file to 389754427Speterstandard output. For example: 389832785Speter@example 389932785Speter$ cvs update -p -r 1.1 file1 >file1 390032785Speter=================================================================== 390132785SpeterChecking out file1 390232785SpeterRCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 390332785SpeterVERS: 1.1 390432785Speter*************** 390544852Speter$ 390632785Speter@end example 390732785Speter 390854427SpeterHowever, this isn't the easiest way, if you are asking 390954427Speterhow to undo a previous checkin (in this example, put 391054427Speter@file{file1} back to the way it was as of revision 391154427Speter1.1). In that case you are better off using the 391254427Speter@samp{-j} option to @code{update}; for further 391354427Speterdiscussion see @ref{Merging two revisions}. 391454427Speter 391532785Speter@c --------------------------------------------------------------------- 391632785Speter@node Branching and merging 391732785Speter@chapter Branching and merging 391832785Speter@cindex Branching 391932785Speter@cindex Merging 392032785Speter@cindex Copying changes 392132785Speter@cindex Main trunk and branches 392232785Speter@cindex Revision tree, making branches 392332785Speter@cindex Branches, copying changes between 392432785Speter@cindex Changes, copying between branches 392532785Speter@cindex Modifications, copying between branches 392632785Speter 392781404Speter@sc{cvs} allows you to isolate changes onto a separate 392832785Speterline of development, known as a @dfn{branch}. When you 392932785Speterchange files on a branch, those changes do not appear 393032785Speteron the main trunk or other branches. 393132785Speter 393232785SpeterLater you can move changes from one branch to another 393332785Speterbranch (or the main trunk) by @dfn{merging}. Merging 393432785Speterinvolves first running @code{cvs update -j}, to merge 393532785Speterthe changes into the working directory. 393632785SpeterYou can then commit that revision, and thus effectively 393732785Spetercopy the changes onto another branch. 393832785Speter 393932785Speter@menu 394032785Speter* Branches motivation:: What branches are good for 394132785Speter* Creating a branch:: Creating a branch 394232785Speter* Accessing branches:: Checking out and updating branches 394332785Speter* Branches and revisions:: Branches are reflected in revision numbers 394432785Speter* Magic branch numbers:: Magic branch numbers 394532785Speter* Merging a branch:: Merging an entire branch 394632785Speter* Merging more than once:: Merging from a branch several times 394732785Speter* Merging two revisions:: Merging differences between two revisions 394832785Speter* Merging adds and removals:: What if files are added or removed? 394954427Speter* Merging and keywords:: Avoiding conflicts due to keyword substitution 395032785Speter@end menu 395132785Speter 395232785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 395317721Speter@node Branches motivation 395417721Speter@section What branches are good for 395517721Speter@cindex Branches motivation 395617721Speter@cindex What branches are good for 395717721Speter@cindex Motivation for branches 395817721Speter 395932785Speter@c FIXME: this node mentions one way to use branches, 396032785Speter@c but it is by no means the only way. For example, 396132785Speter@c the technique of committing a new feature on a branch, 396232785Speter@c until it is ready for the main trunk. The whole 396332785Speter@c thing is generally speaking more akin to the 396432785Speter@c "Revision management" node although it isn't clear to 396532785Speter@c me whether policy matters should be centralized or 396632785Speter@c distributed throughout the relevant sections. 396717721SpeterSuppose that release 1.0 of tc has been made. You are continuing to 396817721Speterdevelop tc, planning to create release 1.1 in a couple of months. After a 396917721Speterwhile your customers start to complain about a fatal bug. You check 397017721Speterout release 1.0 (@pxref{Tags}) and find the bug 397117721Speter(which turns out to have a trivial fix). However, the current revision 397217721Speterof the sources are in a state of flux and are not expected to be stable 397317721Speterfor at least another month. There is no way to make a 3974130303Speterbug fix release based on the newest sources. 397517721Speter 397617721SpeterThe thing to do in a situation like this is to create a @dfn{branch} on 397717721Speterthe revision trees for all the files that make up 397817721Speterrelease 1.0 of tc. You can then make 397917721Spetermodifications to the branch without disturbing the main trunk. When the 398032785Spetermodifications are finished you can elect to either incorporate them on 398117721Speterthe main trunk, or leave them on the branch. 398217721Speter 398317721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 398417721Speter@node Creating a branch 398517721Speter@section Creating a branch 398617721Speter@cindex Creating a branch 398717721Speter@cindex Branch, creating a 398832785Speter@cindex tag, creating a branch using 398917721Speter@cindex rtag, creating a branch using 399017721Speter 399132785SpeterYou can create a branch with @code{tag -b}; for 399232785Speterexample, assuming you're in a working copy: 399317721Speter 399417721Speter@example 399544852Speter$ cvs tag -b rel-1-0-patches 399632785Speter@end example 399732785Speter 399832785Speter@c FIXME: we should be more explicit about the value of 399932785Speter@c having a tag on the branchpoint. For example 400044852Speter@c "cvs tag rel-1-0-patches-branchpoint" before 400132785Speter@c the "cvs tag -b". This points out that 400244852Speter@c rel-1-0-patches is a pretty awkward name for 400332785Speter@c this example (more so than for the rtag example 400432785Speter@c below). 400532785Speter 400632785SpeterThis splits off a branch based on the current revisions 400732785Speterin the working copy, assigning that branch the name 400844852Speter@samp{rel-1-0-patches}. 400932785Speter 401032785SpeterIt is important to understand that branches get created 401132785Speterin the repository, not in the working copy. Creating a 401232785Speterbranch based on current revisions, as the above example 401332785Speterdoes, will @emph{not} automatically switch the working 401432785Spetercopy to be on the new branch. For information on how 401532785Speterto do that, see @ref{Accessing branches}. 401632785Speter 401732785SpeterYou can also create a branch without reference to any 401832785Speterworking copy, by using @code{rtag}: 401932785Speter 402032785Speter@example 402144852Speter$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 402217721Speter@end example 402317721Speter 402444852Speter@samp{-r rel-1-0} says that this branch should be 402532785Speterrooted at the revision that 402644852Spetercorresponds to the tag @samp{rel-1-0}. It need not 402732785Speterbe the most recent revision -- it's often useful to 402832785Spetersplit a branch off an old revision (for example, when 402932785Speterfixing a bug in a past release otherwise known to be 403032785Speterstable). 403117721Speter 403232785SpeterAs with @samp{tag}, the @samp{-b} flag tells 403332785Speter@code{rtag} to create a branch (rather than just a 403432785Spetersymbolic revision name). Note that the numeric 403544852Speterrevision number that matches @samp{rel-1-0} will 403632785Speterprobably be different from file to file. 403717721Speter 403832785SpeterSo, the full effect of the command is to create a new 403944852Speterbranch -- named @samp{rel-1-0-patches} -- in module 404032785Speter@samp{tc}, rooted in the revision tree at the point tagged 404144852Speterby @samp{rel-1-0}. 404232785Speter 404332785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 404432785Speter@node Accessing branches 404532785Speter@section Accessing branches 404632785Speter@cindex Check out a branch 404732785Speter@cindex Retrieve a branch 404832785Speter@cindex Access a branch 404932785Speter@cindex Identifying a branch 405032785Speter@cindex Branch, check out 405132785Speter@cindex Branch, retrieving 405232785Speter@cindex Branch, accessing 405332785Speter@cindex Branch, identifying 405432785Speter 405532785SpeterYou can retrieve a branch in one of two ways: by 405632785Speterchecking it out fresh from the repository, or by 405732785Speterswitching an existing working copy over to the branch. 405832785Speter 405932785SpeterTo check out a branch from the repository, invoke 406032785Speter@samp{checkout} with the @samp{-r} flag, followed by 406132785Speterthe tag name of the branch (@pxref{Creating a branch}): 406232785Speter 406317721Speter@example 406444852Speter$ cvs checkout -r rel-1-0-patches tc 406532785Speter@end example 406632785Speter 406732785SpeterOr, if you already have a working copy, you can switch 406832785Speterit to a given branch with @samp{update -r}: 406932785Speter 407032785Speter@example 407144852Speter$ cvs update -r rel-1-0-patches tc 407232785Speter@end example 407332785Speter 4074102840Speter@noindent 407532785Speteror equivalently: 407632785Speter 407732785Speter@example 407832785Speter$ cd tc 407944852Speter$ cvs update -r rel-1-0-patches 408032785Speter@end example 408132785Speter 408232785SpeterIt does not matter if the working copy was originally 408332785Speteron the main trunk or on some other branch -- the above 408432785Spetercommand will switch it to the named branch. And 408532785Spetersimilarly to a regular @samp{update} command, 408632785Speter@samp{update -r} merges any changes you have made, 408732785Speternotifying you of conflicts where they occur. 408832785Speter 408932785SpeterOnce you have a working copy tied to a particular 409032785Speterbranch, it remains there until you tell it otherwise. 409132785SpeterThis means that changes checked in from the working 409232785Spetercopy will add new revisions on that branch, while 409332785Speterleaving the main trunk and other branches unaffected. 409432785Speter 409532785Speter@cindex Branches, sticky 409632785SpeterTo find out what branch a working copy is on, you can 409732785Speteruse the @samp{status} command. In its output, look for 409832785Speterthe field named @samp{Sticky tag} (@pxref{Sticky tags}) 409932785Speter-- that's @sc{cvs}'s way of telling you the branch, if 410032785Speterany, of the current working files: 410132785Speter 410232785Speter@example 410317721Speter$ cvs status -v driver.c backend.c 410417721Speter=================================================================== 410517721SpeterFile: driver.c Status: Up-to-date 410617721Speter 410717721Speter Version: 1.7 Sat Dec 5 18:25:54 1992 410825839Speter RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 410944852Speter Sticky Tag: rel-1-0-patches (branch: 1.7.2) 411017721Speter Sticky Date: (none) 411117721Speter Sticky Options: (none) 411217721Speter 411317721Speter Existing Tags: 411444852Speter rel-1-0-patches (branch: 1.7.2) 411544852Speter rel-1-0 (revision: 1.7) 411617721Speter 411717721Speter=================================================================== 411817721SpeterFile: backend.c Status: Up-to-date 411917721Speter 412017721Speter Version: 1.4 Tue Dec 1 14:39:01 1992 412125839Speter RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 412244852Speter Sticky Tag: rel-1-0-patches (branch: 1.4.2) 412317721Speter Sticky Date: (none) 412417721Speter Sticky Options: (none) 412517721Speter 412617721Speter Existing Tags: 412744852Speter rel-1-0-patches (branch: 1.4.2) 412844852Speter rel-1-0 (revision: 1.4) 412944852Speter rel-0-4 (revision: 1.4) 413017721Speter 413117721Speter@end example 413217721Speter 413332785SpeterDon't be confused by the fact that the branch numbers 413432785Speterfor each file are different (@samp{1.7.2} and 413532785Speter@samp{1.4.2} respectively). The branch tag is the 413644852Spetersame, @samp{rel-1-0-patches}, and the files are 413732785Speterindeed on the same branch. The numbers simply reflect 413832785Speterthe point in each file's revision history at which the 413932785Speterbranch was made. In the above example, one can deduce 414032785Speterthat @samp{driver.c} had been through more changes than 414132785Speter@samp{backend.c} before this branch was created. 414217721Speter 414332785SpeterSee @ref{Branches and revisions} for details about how 414432785Speterbranch numbers are constructed. 414532785Speter 414617721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 414732785Speter@node Branches and revisions 414832785Speter@section Branches and revisions 414932785Speter@cindex Branch number 415032785Speter@cindex Number, branch 415132785Speter@cindex Revision numbers (branches) 415217721Speter 415332785SpeterOrdinarily, a file's revision history is a linear 415432785Speterseries of increments (@pxref{Revision numbers}): 415517721Speter 415617721Speter@example 415732785Speter +-----+ +-----+ +-----+ +-----+ +-----+ 415832785Speter ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 415932785Speter +-----+ +-----+ +-----+ +-----+ +-----+ 416032785Speter@end example 416117721Speter 416232785SpeterHowever, @sc{cvs} is not limited to linear development. The 416332785Speter@dfn{revision tree} can be split into @dfn{branches}, 416432785Speterwhere each branch is a self-maintained line of 416532785Speterdevelopment. Changes made on one branch can easily be 416644852Spetermoved back to the main trunk. 416717721Speter 416832785SpeterEach branch has a @dfn{branch number}, consisting of an 416932785Speterodd number of period-separated decimal integers. The 417032785Speterbranch number is created by appending an integer to the 417132785Speterrevision number where the corresponding branch forked 417232785Speteroff. Having branch numbers allows more than one branch 417332785Speterto be forked off from a certain revision. 417417721Speter 417532785Speter@need 3500 417632785SpeterAll revisions on a branch have revision numbers formed 417732785Speterby appending an ordinal number to the branch number. 417832785SpeterThe following figure illustrates branching with an 417932785Speterexample. 418032785Speter 418132785Speter@example 418254427Speter@c This example used to have a 1.2.2.4 revision, which 418354427Speter@c might help clarify that development can continue on 418454427Speter@c 1.2.2. Might be worth reinstating if it can be done 418554427Speter@c without overfull hboxes. 418632785Speter@group 418754427Speter +-------------+ 418854427Speter Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 418954427Speter / +-------------+ 419054427Speter / 419154427Speter / 419232785Speter +---------+ +---------+ +---------+ 419332785SpeterBranch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 419432785Speter / +---------+ +---------+ +---------+ 419532785Speter / 419632785Speter / 419732785Speter+-----+ +-----+ +-----+ +-----+ +-----+ 419832785Speter! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 419932785Speter+-----+ +-----+ +-----+ +-----+ +-----+ 420032785Speter ! 420132785Speter ! 420232785Speter ! +---------+ +---------+ +---------+ 420332785SpeterBranch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 420432785Speter +---------+ +---------+ +---------+ 420532785Speter 420632785Speter@end group 420717721Speter@end example 420817721Speter 420932785Speter@c -- However, at least for me the figure is not enough. I suggest more 421032785Speter@c -- text to accompany it. "A picture is worth a thousand words", so you 421132785Speter@c -- have to make sure the reader notices the couple of hundred words 421232785Speter@c -- *you* had in mind more than the others! 421317721Speter 421432785Speter@c -- Why an even number of segments? This section implies that this is 421532785Speter@c -- how the main trunk is distinguished from branch roots, but you never 421632785Speter@c -- explicitly say that this is the purpose of the [by itself rather 421732785Speter@c -- surprising] restriction to an even number of segments. 421817721Speter 421932785SpeterThe exact details of how the branch number is 422032785Speterconstructed is not something you normally need to be 422132785Speterconcerned about, but here is how it works: When 422232785Speter@sc{cvs} creates a branch number it picks the first 422332785Speterunused even integer, starting with 2. So when you want 422432785Speterto create a branch from revision 6.4 it will be 422532785Speternumbered 6.4.2. All branch numbers ending in a zero 422632785Speter(such as 6.4.0) are used internally by @sc{cvs} 422732785Speter(@pxref{Magic branch numbers}). The branch 1.1.1 has a 422832785Speterspecial meaning. @xref{Tracking sources}. 422917721Speter 423025839Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 423125839Speter@node Magic branch numbers 423225839Speter@section Magic branch numbers 423325839Speter 423432785Speter@c Want xref to here from "log"? 423525839Speter 423625839SpeterThis section describes a @sc{cvs} feature called 423725839Speter@dfn{magic branches}. For most purposes, you need not 423825839Speterworry about magic branches; @sc{cvs} handles them for 423925839Speteryou. However, they are visible to you in certain 424025839Spetercircumstances, so it may be useful to have some idea of 424125839Speterhow it works. 424225839Speter 424325839SpeterExternally, branch numbers consist of an odd number of 424425839Speterdot-separated decimal integers. @xref{Revision 424525839Speternumbers}. That is not the whole truth, however. For 424625839Speterefficiency reasons @sc{cvs} sometimes inserts an extra 0 424732785Speterin the second rightmost position (1.2.4 becomes 424832785Speter1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 424925839Speteron). 425025839Speter 425125839Speter@sc{cvs} does a pretty good job at hiding these so 425225839Spetercalled magic branches, but in a few places the hiding 425325839Speteris incomplete: 425425839Speter 425525839Speter@itemize @bullet 425625839Speter@ignore 425725839Speter@c This is in ignore as I'm taking their word for it, 425825839Speter@c that this was fixed 425925839Speter@c a long time ago. But before deleting this 426025839Speter@c entirely, I'd rather verify it (and add a test 426125839Speter@c case to the testsuite). 426225839Speter@item 426325839SpeterThe magic branch can appear in the output from 426425839Speter@code{cvs status} in vanilla @sc{cvs} 1.3. This is 426525839Speterfixed in @sc{cvs} 1.3-s2. 426625839Speter 426725839Speter@end ignore 426825839Speter@item 426925839SpeterThe magic branch number appears in the output from 427025839Speter@code{cvs log}. 427125839Speter@c What output should appear instead? 427225839Speter 427325839Speter@item 427425839SpeterYou cannot specify a symbolic branch name to @code{cvs 427525839Speteradmin}. 427625839Speter 427725839Speter@end itemize 427825839Speter 427925839Speter@c Can CVS do this automatically the first time 428025839Speter@c you check something in to that branch? Should 428125839Speter@c it? 428225839SpeterYou can use the @code{admin} command to reassign a 428325839Spetersymbolic name to a branch the way @sc{rcs} expects it 428425839Speterto be. If @code{R4patches} is assigned to the branch 428525839Speter1.4.2 (magic branch number 1.4.0.2) in file 428625839Speter@file{numbers.c} you can do this: 428725839Speter 428825839Speter@example 428925839Speter$ cvs admin -NR4patches:1.4.2 numbers.c 429025839Speter@end example 429125839Speter 429225839SpeterIt only works if at least one revision is already 429325839Spetercommitted on the branch. Be very careful so that you 429425839Speterdo not assign the tag to the wrong number. (There is 429525839Speterno way to see how the tag was assigned yesterday). 429625839Speter 429717721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 429817721Speter@node Merging a branch 429917721Speter@section Merging an entire branch 430017721Speter@cindex Merging a branch 430117721Speter@cindex -j (merging branches) 430217721Speter 430317721SpeterYou can merge changes made on a branch into your working copy by giving 430481404Speterthe @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 430581404Speter@samp{-j @var{branchname}} option it merges the changes made between the 4306128266Spetergreatest common ancestor (GCA) of the branch and the destination revision (in 4307128266Speterthe simple case below the GCA is the point where the branch forked) and the 4308128266Speternewest revision on that branch into your working copy. 430917721Speter 431017721Speter@cindex Join 431117721SpeterThe @samp{-j} stands for ``join''. 431217721Speter 431317721Speter@cindex Branch merge example 431417721Speter@cindex Example, branch merge 431517721Speter@cindex Merge, branch example 431617721SpeterConsider this revision tree: 431717721Speter 431817721Speter@example 431917721Speter+-----+ +-----+ +-----+ +-----+ 432017721Speter! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 432117721Speter+-----+ +-----+ +-----+ +-----+ 432217721Speter ! 432317721Speter ! 432417721Speter ! +---------+ +---------+ 432517721SpeterBranch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 432617721Speter +---------+ +---------+ 432717721Speter@end example 432817721Speter 432917721Speter@noindent 433017721SpeterThe branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 433117721Speterfollowing example assumes that the module @samp{mod} contains only one 433217721Speterfile, @file{m.c}. 433317721Speter 433417721Speter@example 433517721Speter$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 433617721Speter 433717721Speter$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 433817721Speter # @r{i.e. the changes between revision 1.2} 433917721Speter # @r{and 1.2.2.2, into your working copy} 434017721Speter # @r{of the file.} 434117721Speter 434217721Speter$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 434317721Speter@end example 434417721Speter 434517721SpeterA conflict can result from a merge operation. If that 434617721Speterhappens, you should resolve it before committing the 434717721Speternew revision. @xref{Conflicts example}. 434817721Speter 434954427SpeterIf your source files contain keywords (@pxref{Keyword substitution}), 435054427Speteryou might be getting more conflicts than strictly necessary. See 435154427Speter@ref{Merging and keywords}, for information on how to avoid this. 435254427Speter 435381404SpeterThe @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 435417721Spetersame effect as above could be achieved with this: 435517721Speter 435617721Speter@example 435717721Speter$ cvs checkout -j R1fix mod 435817721Speter$ cvs commit -m "Included R1fix" 435917721Speter@end example 436017721Speter 436181404SpeterIt should be noted that @code{update -j @var{tagname}} will also work but may 436281404Speternot produce the desired result. @xref{Merging adds and removals}, for more. 436381404Speter 436417721Speter@node Merging more than once 436517721Speter@section Merging from a branch several times 436617721Speter 436717721SpeterContinuing our example, the revision tree now looks 436817721Speterlike this: 436917721Speter 437017721Speter@example 437117721Speter+-----+ +-----+ +-----+ +-----+ +-----+ 437225839Speter! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 437317721Speter+-----+ +-----+ +-----+ +-----+ +-----+ 437417721Speter ! * 437517721Speter ! * 437617721Speter ! +---------+ +---------+ 437717721SpeterBranch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 437817721Speter +---------+ +---------+ 437917721Speter@end example 438017721Speter 4381102840Speter@noindent 438217721Speterwhere the starred line represents the merge from the 438317721Speter@samp{R1fix} branch to the main trunk, as just 438417721Speterdiscussed. 438517721Speter 438617721SpeterNow suppose that development continues on the 438717721Speter@samp{R1fix} branch: 438817721Speter 438917721Speter@example 439017721Speter+-----+ +-----+ +-----+ +-----+ +-----+ 439125839Speter! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 439217721Speter+-----+ +-----+ +-----+ +-----+ +-----+ 439317721Speter ! * 439417721Speter ! * 439517721Speter ! +---------+ +---------+ +---------+ 439617721SpeterBranch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 439717721Speter +---------+ +---------+ +---------+ 439817721Speter@end example 439917721Speter 4400102840Speter@noindent 440117721Speterand then you want to merge those new changes onto the 440217721Spetermain trunk. If you just use the @code{cvs update -j 440317721SpeterR1fix m.c} command again, @sc{cvs} will attempt to 440417721Spetermerge again the changes which you have already merged, 440517721Speterwhich can have undesirable side effects. 440617721Speter 440717721SpeterSo instead you need to specify that you only want to 440817721Spetermerge the changes on the branch which have not yet been 440917721Spetermerged into the trunk. To do that you specify two 441017721Speter@samp{-j} options, and @sc{cvs} merges the changes from 441117721Speterthe first revision to the second revision. For 441217721Speterexample, in this case the simplest way would be 441317721Speter 441417721Speter@example 441517721Spetercvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 441617721Speter # @r{head of the R1fix branch} 441717721Speter@end example 441817721Speter 441917721SpeterThe problem with this is that you need to specify the 442017721Speter1.2.2.2 revision manually. A slightly better approach 442117721Spetermight be to use the date the last merge was done: 442217721Speter 442317721Speter@example 442417721Spetercvs update -j R1fix:yesterday -j R1fix m.c 442517721Speter@end example 442617721Speter 442717721SpeterBetter yet, tag the R1fix branch after every merge into 442817721Speterthe trunk, and then use that tag for subsequent merges: 442917721Speter 443017721Speter@example 443117721Spetercvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 443217721Speter@end example 443317721Speter 443417721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 443517721Speter@node Merging two revisions 443617721Speter@section Merging differences between any two revisions 443717721Speter@cindex Merging two revisions 443817721Speter@cindex Revisions, merging differences between 443917721Speter@cindex Differences, merging 444017721Speter 444117721SpeterWith two @samp{-j @var{revision}} flags, the @code{update} 444217721Speter(and @code{checkout}) command can merge the differences 444317721Speterbetween any two revisions into your working file. 444417721Speter 444517721Speter@cindex Undoing a change 444617721Speter@cindex Removing a change 444717721Speter@example 444817721Speter$ cvs update -j 1.5 -j 1.3 backend.c 444917721Speter@end example 445017721Speter 445117721Speter@noindent 445254427Speterwill undo all changes made between revision 445317721Speter1.3 and 1.5. Note the order of the revisions! 445417721Speter 445517721SpeterIf you try to use this option when operating on 445617721Spetermultiple files, remember that the numeric revisions will 445754427Speterprobably be very different between the various files. 445854427SpeterYou almost always use symbolic 445917721Spetertags rather than revision numbers when operating on 446017721Spetermultiple files. 446117721Speter 446254427Speter@cindex Restoring old version of removed file 446354427Speter@cindex Resurrecting old version of dead file 446454427SpeterSpecifying two @samp{-j} options can also undo file 446554427Speterremovals or additions. For example, suppose you have 446654427Spetera file 446754427Speternamed @file{file1} which existed as revision 1.1, and 446854427Speteryou then removed it (thus adding a dead revision 1.2). 446954427SpeterNow suppose you want to add it again, with the same 447054427Spetercontents it had previously. Here is how to do it: 447154427Speter 447254427Speter@example 447354427Speter$ cvs update -j 1.2 -j 1.1 file1 447454427SpeterU file1 447554427Speter$ cvs commit -m test 447654427SpeterChecking in file1; 447754427Speter/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 447854427Speternew revision: 1.3; previous revision: 1.2 447954427Speterdone 448054427Speter$ 448154427Speter@end example 448254427Speter 448325839Speter@node Merging adds and removals 448425839Speter@section Merging can add or remove files 448525839Speter 448625839SpeterIf the changes which you are merging involve removing 448725839Speteror adding some files, @code{update -j} will reflect 448825839Spetersuch additions or removals. 448925839Speter 449025839Speter@c FIXME: This example needs a lot more explanation. 449125839Speter@c We also need other examples for some of the other 449225839Speter@c cases (not all--there are too many--as long as we present a 449325839Speter@c coherent general principle). 449425839SpeterFor example: 449525839Speter@example 449625839Spetercvs update -A 449725839Spetertouch a b c 449825839Spetercvs add a b c ; cvs ci -m "added" a b c 449925839Spetercvs tag -b branchtag 450025839Spetercvs update -r branchtag 450125839Spetertouch d ; cvs add d 450225839Speterrm a ; cvs rm a 450325839Spetercvs ci -m "added d, removed a" 450425839Spetercvs update -A 450525839Spetercvs update -jbranchtag 450625839Speter@end example 450725839Speter 450832785SpeterAfter these commands are executed and a @samp{cvs commit} is done, 450932785Speterfile @file{a} will be removed and file @file{d} added in the main branch. 451032785Speter@c (which was determined by trying it) 451132785Speter 451281404SpeterNote that using a single static tag (@samp{-j @var{tagname}}) 451381404Speterrather than a dynamic tag (@samp{-j @var{branchname}}) to merge 451481404Speterchanges from a branch will usually not remove files which were removed on the 451581404Speterbranch since @sc{cvs} does not automatically add static tags to dead revisions. 451681404SpeterThe exception to this rule occurs when 451781404Spetera static tag has been attached to a dead revision manually. Use the branch tag 451881404Speterto merge all changes from the branch or use two static tags as merge endpoints 4519130303Speterto be sure that all intended changes are propagated in the merge. 452081404Speter 452154427Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 452254427Speter@node Merging and keywords 452354427Speter@section Merging and keywords 452454427Speter@cindex Merging, and keyword substitution 452554427Speter@cindex Keyword substitution, and merging 452654427Speter@cindex -j (merging branches), and keyword substitution 452754427Speter@cindex -kk, to avoid conflicts during a merge 452854427Speter 452954427SpeterIf you merge files containing keywords (@pxref{Keyword 453054427Spetersubstitution}), you will normally get numerous 453154427Speterconflicts during the merge, because the keywords are 453254427Speterexpanded differently in the revisions which you are 453354427Spetermerging. 453454427Speter 453554427SpeterTherefore, you will often want to specify the 453654427Speter@samp{-kk} (@pxref{Substitution modes}) switch to the 453754427Spetermerge command line. By substituting just the name of 453854427Speterthe keyword, not the expanded value of that keyword, 453954427Speterthis option ensures that the revisions which you are 454054427Spetermerging will be the same as each other, and avoid 454154427Speterspurious conflicts. 454254427Speter 454354427SpeterFor example, suppose you have a file like this: 454454427Speter 454554427Speter@example 454654427Speter +---------+ 454754427Speter _! 1.1.2.1 ! <- br1 454854427Speter / +---------+ 454954427Speter / 455054427Speter / 455154427Speter+-----+ +-----+ 455254427Speter! 1.1 !----! 1.2 ! 455354427Speter+-----+ +-----+ 455454427Speter@end example 455554427Speter 4556102840Speter@noindent 455754427Speterand your working directory is currently on the trunk 455854427Speter(revision 1.2). Then you might get the following 455954427Speterresults from a merge: 456054427Speter 456154427Speter@example 456254427Speter$ cat file1 4563130303Speterkey $@splitrcskeyword{Revision}: 1.2 $ 456454427Speter. . . 456554427Speter$ cvs update -j br1 456654427SpeterU file1 456754427SpeterRCS file: /cvsroot/first-dir/file1,v 456854427Speterretrieving revision 1.1 456954427Speterretrieving revision 1.1.2.1 457054427SpeterMerging differences between 1.1 and 1.1.2.1 into file1 457154427Speterrcsmerge: warning: conflicts during merge 457254427Speter$ cat file1 457354427Speter@asis{}<<<<<<< file1 4574130303Speterkey $@splitrcskeyword{Revision}: 1.2 $ 457554427Speter@asis{}======= 4576130303Speterkey $@splitrcskeyword{Revision}: 1.1.2.1 $ 457754427Speter@asis{}>>>>>>> 1.1.2.1 457854427Speter. . . 457954427Speter@end example 458054427Speter 458154427SpeterWhat happened was that the merge tried to merge the 458254427Speterdifferences between 1.1 and 1.1.2.1 into your working 458354427Speterdirectory. So, since the keyword changed from 458454427Speter@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 458554427Speter@sc{cvs} tried to merge that change into your working 458654427Speterdirectory, which conflicted with the fact that your 458754427Speterworking directory had contained @code{Revision: 1.2}. 458854427Speter 458954427SpeterHere is what happens if you had used @samp{-kk}: 459054427Speter 459154427Speter@example 459254427Speter$ cat file1 4593130303Speterkey $@splitrcskeyword{Revision}: 1.2 $ 459454427Speter. . . 459554427Speter$ cvs update -kk -j br1 459654427SpeterU file1 459754427SpeterRCS file: /cvsroot/first-dir/file1,v 459854427Speterretrieving revision 1.1 459954427Speterretrieving revision 1.1.2.1 460054427SpeterMerging differences between 1.1 and 1.1.2.1 into file1 460154427Speter$ cat file1 4602130303Speterkey $@splitrcskeyword{Revision}$ 460354427Speter. . . 460454427Speter@end example 460554427Speter 460654427SpeterWhat is going on here is that revision 1.1 and 1.1.2.1 460754427Speterboth expand as plain @code{Revision}, and therefore 460854427Spetermerging the changes between them into the working 460954427Speterdirectory need not change anything. Therefore, there 461054427Speteris no conflict. 461154427Speter 461254427SpeterThere is, however, one major caveat with using 461354427Speter@samp{-kk} on merges. Namely, it overrides whatever 461454427Speterkeyword expansion mode @sc{cvs} would normally have 461554427Speterused. In particular, this is a problem if the mode had 461654427Speterbeen @samp{-kb} for a binary file. Therefore, if your 461754427Speterrepository contains binary files, you will need to deal 461854427Speterwith the conflicts rather than using @samp{-kk}. 461954427Speter 462054427Speter@ignore 462154427SpeterThe following seems rather confusing, possibly buggy, 462254427Speterand in general, in need of much more thought before it 462354427Speteris a recommended technique. For one thing, does it 462454427Speterapply on Windows as well as on Unix? 462554427Speter 462654427SpeterUnchanged binary files will undergo the same keyword substitution 462754427Speterbut will not be checked in on a subsequent 462854427Speter@code{cvs commit}. Be aware that binary files containing keyword 462954427Speterstrings which are present in or below the working directory 463054427Speterwill most likely remain corrupt until repaired, however. A simple 463154427Speter@code{cvs update -A} is sufficient to fix these otherwise unaltered binary files 463254427Speterif the merge is being done to the main branch but 463354427Speterthis must be done after the merge has been committed or the merge itself 463454427Speterwill be lost. 463554427Speter 463654427SpeterFor Example: 463754427Speter@example 463854427Spetercvs update -Akk -jbranchtag 463954427Spetercvs commit 464054427Spetercvs update -A 464154427Speter@end example 464254427Speter 464354427Speter@noindent 464454427Speterwill update the current directory from the main trunk of the 464554427Speterrepository, substituting the base keyword strings for keywords, 464654427Speterand merge changes made on the branch @samp{branchtag} into the new 464754427Speterwork files, performing the same keyword substitution on that file set before 464854427Spetercomparing the two sets. The final @code{cvs update -A} will restore any 464954427Spetercorrupted binary files as well as resetting the sticky @samp{-kk} tags which 465054427Speterwere present on the files in and below the working directory. 465154427SpeterUnfortunately, this doesn't work as well with an arbitrary branch tag, as the 465254427Speter@samp{-r @var{branchtag}} switch does not reset the sticky @samp{-kk} 465354427Speterswitches attached to the working files as @samp{-A} does. The workaround 465454427Speterfor this is to release the working directory after the merge has been 465554427Spetercommitted and check it out again. 465654427Speter@end ignore 465754427Speter 4658175261SobrienAs a result of using @samp{-kk} during the merge, each file examined by the 4659175261Sobrienupdate will have @samp{-kk} set as sticky options. Running @code{update -A} 4660175261Sobrienwill clear the sticky options on unmodified files, but it will not clear 4661175261Sobrienthe sticky options on modified files. To get back to the default keyword 4662175261Sobriensubstitution for modified files, you must commit the results of the merge 4663175261Sobrienand then run @code{update -A}. 4664175261Sobrien 466517721Speter@c --------------------------------------------------------------------- 466617721Speter@node Recursive behavior 466717721Speter@chapter Recursive behavior 466817721Speter@cindex Recursive (directory descending) 466917721Speter@cindex Directory, descending 467017721Speter@cindex Descending directories 467117721Speter@cindex Subdirectories 467217721Speter 467317721SpeterAlmost all of the subcommands of @sc{cvs} work 467417721Speterrecursively when you specify a directory as an 467517721Speterargument. For instance, consider this directory 467617721Speterstructure: 467717721Speter 467817721Speter@example 467917721Speter @code{$HOME} 468017721Speter | 468117721Speter +--@t{tc} 468217721Speter | | 468317721Speter +--@t{CVS} 468417721Speter | (internal @sc{cvs} files) 468517721Speter +--@t{Makefile} 468617721Speter +--@t{backend.c} 468717721Speter +--@t{driver.c} 468817721Speter +--@t{frontend.c} 468917721Speter +--@t{parser.c} 469017721Speter +--@t{man} 469117721Speter | | 469217721Speter | +--@t{CVS} 469317721Speter | | (internal @sc{cvs} files) 469417721Speter | +--@t{tc.1} 469544852Speter | 469617721Speter +--@t{testing} 469717721Speter | 469817721Speter +--@t{CVS} 469917721Speter | (internal @sc{cvs} files) 470017721Speter +--@t{testpgm.t} 470117721Speter +--@t{test2.t} 470217721Speter@end example 470317721Speter 470417721Speter@noindent 470517721SpeterIf @file{tc} is the current working directory, the 470617721Speterfollowing is true: 470717721Speter 470817721Speter@itemize @bullet 470917721Speter@item 471025839Speter@samp{cvs update testing} is equivalent to 471117721Speter 471225839Speter@example 471325839Spetercvs update testing/testpgm.t testing/test2.t 471425839Speter@end example 471525839Speter 471617721Speter@item 471717721Speter@samp{cvs update testing man} updates all files in the 471844852Spetersubdirectories 471917721Speter 472017721Speter@item 472117721Speter@samp{cvs update .} or just @samp{cvs update} updates 472254427Speterall files in the @code{tc} directory 472317721Speter@end itemize 472417721Speter 472517721SpeterIf no arguments are given to @code{update} it will 472617721Speterupdate all files in the current working directory and 472717721Speterall its subdirectories. In other words, @file{.} is a 472817721Speterdefault argument to @code{update}. This is also true 472917721Speterfor most of the @sc{cvs} subcommands, not only the 473017721Speter@code{update} command. 473117721Speter 473217721SpeterThe recursive behavior of the @sc{cvs} subcommands can be 473317721Speterturned off with the @samp{-l} option. 473425839SpeterConversely, the @samp{-R} option can be used to force recursion if 473525839Speter@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 473617721Speter 473717721Speter@example 473817721Speter$ cvs update -l # @r{Don't update files in subdirectories} 473917721Speter@end example 474017721Speter 474117721Speter@c --------------------------------------------------------------------- 474232785Speter@node Adding and removing 474332785Speter@chapter Adding, removing, and renaming files and directories 474432785Speter 474532785SpeterIn the course of a project, one will often add new 474632785Speterfiles. Likewise with removing or renaming, or with 474732785Speterdirectories. The general concept to keep in mind in 474832785Speterall these cases is that instead of making an 474932785Speterirreversible change you want @sc{cvs} to record the 475032785Speterfact that a change has taken place, just as with 475132785Spetermodifying an existing file. The exact mechanisms to do 475232785Speterthis in @sc{cvs} vary depending on the situation. 475332785Speter 475432785Speter@menu 475532785Speter* Adding files:: Adding files 475632785Speter* Removing files:: Removing files 475732785Speter* Removing directories:: Removing directories 475832785Speter* Moving files:: Moving and renaming files 475932785Speter* Moving directories:: Moving and renaming directories 476032785Speter@end menu 476132785Speter 476217721Speter@node Adding files 476332785Speter@section Adding files to a directory 476417721Speter@cindex Adding files 476517721Speter 476625839SpeterTo add a new file to a directory, follow these steps. 476717721Speter 476817721Speter@itemize @bullet 476917721Speter@item 477025839SpeterYou must have a working copy of the directory. 477117721Speter@xref{Getting the source}. 477217721Speter 477317721Speter@item 477425839SpeterCreate the new file inside your working copy of the directory. 477517721Speter 477617721Speter@item 477717721SpeterUse @samp{cvs add @var{filename}} to tell @sc{cvs} that you 477825839Speterwant to version control the file. If the file contains 477925839Speterbinary data, specify @samp{-kb} (@pxref{Binary files}). 478017721Speter 478117721Speter@item 478217721SpeterUse @samp{cvs commit @var{filename}} to actually check 478317721Speterin the file into the repository. Other developers 478417721Spetercannot see the file until you perform this step. 478517721Speter@end itemize 478617721Speter 478717721SpeterYou can also use the @code{add} command to add a new 478825839Speterdirectory. 478925839Speter@c FIXCVS and/or FIXME: Adding a directory doesn't 479025839Speter@c require the commit step. This probably can be 479125839Speter@c considered a CVS bug, but it is possible we should 479225839Speter@c warn people since this behavior probably won't be 479325839Speter@c changing right away. 479417721Speter 479517721SpeterUnlike most other commands, the @code{add} command is 4796177391Sobriennot recursive. You have to explicitly name files and 4797130303Speterdirectories that you wish to add to the repository. 4798130303SpeterHowever, each directory will need to be added 4799130303Speterseparately before you will be able to add new files 4800130303Speterto those directories. 480117721Speter 480217721Speter@example 4803130303Speter$ mkdir -p foo/bar 4804130303Speter$ cp ~/myfile foo/bar/myfile 4805130303Speter$ cvs add foo foo/bar 4806130303Speter$ cvs add foo/bar/myfile 480717721Speter@end example 480817721Speter 480925839Speter@cindex add (subcommand) 481025839Speter@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 481117721Speter 481225839SpeterSchedule @var{files} to be added to the repository. 481325839SpeterThe files or directories specified with @code{add} must 481425839Speteralready exist in the current directory. To add a whole 481525839Speternew directory hierarchy to the source repository (for 481625839Speterexample, files received from a third-party vendor), use 481725839Speterthe @code{import} command instead. @xref{import}. 481825839Speter 481925839SpeterThe added files are not placed in the source repository 482025839Speteruntil you use @code{commit} to make the change 482125839Speterpermanent. Doing an @code{add} on a file that was 482225839Speterremoved with the @code{remove} command will undo the 482325839Spetereffect of the @code{remove}, unless a @code{commit} 482425839Spetercommand intervened. @xref{Removing files}, for an 482525839Speterexample. 482625839Speter 482725839SpeterThe @samp{-k} option specifies the default way that 482825839Speterthis file will be checked out; for more information see 482925839Speter@ref{Substitution modes}. 483025839Speter 483125839Speter@c As noted in BUGS, -m is broken client/server (Nov 483225839Speter@c 96). Also see testsuite log2-* tests. 483325839SpeterThe @samp{-m} option specifies a description for the 483425839Speterfile. This description appears in the history log (if 483525839Speterit is enabled, @pxref{history file}). It will also be 483625839Spetersaved in the version history inside the repository when 483725839Speterthe file is committed. The @code{log} command displays 483825839Speterthis description. The description can be changed using 483925839Speter@samp{admin -t}. @xref{admin}. If you omit the 484025839Speter@samp{-m @var{description}} flag, an empty string will 484125839Speterbe used. You will not be prompted for a description. 484225839Speter@end deffn 484325839Speter 484425839SpeterFor example, the following commands add the file 484525839Speter@file{backend.c} to the repository: 484625839Speter 484725839Speter@c This example used to specify 484844852Speter@c -m "Optimizer and code generation passes." 484925839Speter@c to the cvs add command, but that doesn't work 485025839Speter@c client/server (see log2 in sanity.sh). Should fix CVS, 485125839Speter@c but also seems strange to document things which 485225839Speter@c don't work... 485325839Speter@example 485425839Speter$ cvs add backend.c 485525839Speter$ cvs commit -m "Early version. Not yet compilable." backend.c 485625839Speter@end example 485725839Speter 485825839SpeterWhen you add a file it is added only on the branch 485932785Speterwhich you are working on (@pxref{Branching and merging}). You can 486025839Speterlater merge the additions to another branch if you want 486125839Speter(@pxref{Merging adds and removals}). 486225839Speter@c Should we mention that earlier versions of CVS 486325839Speter@c lacked this feature (1.3) or implemented it in a buggy 486425839Speter@c way (well, 1.8 had many bugs in cvs update -j)? 486525839Speter@c Should we mention the bug/limitation regarding a 486625839Speter@c file being a regular file on one branch and a directory 486725839Speter@c on another? 486825839Speter@c FIXME: This needs an example, or several, here or 486925839Speter@c elsewhere, for it to make much sense. 487025839Speter@c Somewhere we need to discuss the aspects of death 487125839Speter@c support which don't involve branching, I guess. 487225839Speter@c Like the ability to re-create a release from a tag. 487325839Speter 487417721Speter@c --------------------------------------------------------------------- 487517721Speter@node Removing files 487632785Speter@section Removing files 487717721Speter@cindex Removing files 487817721Speter@cindex Deleting files 487917721Speter 488025839Speter@c FIXME: this node wants to be split into several 488132785Speter@c smaller nodes. Could make these children of 488232785Speter@c "Adding and removing", probably (death support could 488325839Speter@c be its own section, for example, as could the 488425839Speter@c various bits about undoing mistakes in adding and 488525839Speter@c removing). 488654427SpeterDirectories change. New files are added, and old files 488717721Speterdisappear. Still, you want to be able to retrieve an 488825839Speterexact copy of old releases. 488917721Speter 489025839SpeterHere is what you can do to remove a file, 489117721Speterbut remain able to retrieve old revisions: 489217721Speter 489317721Speter@itemize @bullet 489425839Speter@c FIXME: should probably be saying something about 489525839Speter@c having a working directory in the first place. 489617721Speter@item 489717721SpeterMake sure that you have not made any uncommitted 489817721Spetermodifications to the file. @xref{Viewing differences}, 489917721Speterfor one way to do that. You can also use the 490017721Speter@code{status} or @code{update} command. If you remove 490117721Speterthe file without committing your changes, you will of 490217721Spetercourse not be able to retrieve the file as it was 490317721Speterimmediately before you deleted it. 490417721Speter 490517721Speter@item 490625839SpeterRemove the file from your working copy of the directory. 490717721SpeterYou can for instance use @code{rm}. 490817721Speter 490917721Speter@item 491017721SpeterUse @samp{cvs remove @var{filename}} to tell @sc{cvs} that 491117721Speteryou really want to delete the file. 491217721Speter 491317721Speter@item 491417721SpeterUse @samp{cvs commit @var{filename}} to actually 491517721Speterperform the removal of the file from the repository. 491617721Speter@end itemize 491717721Speter 491825839Speter@c FIXME: Somehow this should be linked in with a more 491925839Speter@c general discussion of death support. I don't know 492025839Speter@c whether we want to use the term "death support" or 492125839Speter@c not (we can perhaps get by without it), but we do 492225839Speter@c need to discuss the "dead" state in "cvs log" and 492325839Speter@c related subjects. The current discussion is 492425839Speter@c scattered around, and not xref'd to each other. 492525839Speter@c FIXME: I think this paragraph wants to be moved 492625839Speter@c later down, at least after the first example. 492717721SpeterWhen you commit the removal of the file, @sc{cvs} 492817721Speterrecords the fact that the file no longer exists. It is 492917721Speterpossible for a file to exist on only some branches and 493017721Speternot on others, or to re-add another file with the same 493181404Spetername later. @sc{cvs} will correctly create or not create 493217721Speterthe file, based on the @samp{-r} and @samp{-D} options 493317721Speterspecified to @code{checkout} or @code{update}. 493417721Speter 493525839Speter@c FIXME: This style seems to clash with how we 493625839Speter@c document things in general. 493717721Speter@cindex Remove (subcommand) 493825839Speter@deffn Command {cvs remove} [options] files @dots{} 493917721Speter 494017721SpeterSchedule file(s) to be removed from the repository 494117721Speter(files which have not already been removed from the 494217721Speterworking directory are not processed). This command 494317721Speterdoes not actually remove the file from the repository 494425839Speteruntil you commit the removal. For a full list of 494525839Speteroptions, see @ref{Invoking CVS}. 494617721Speter@end deffn 494717721Speter 494817721SpeterHere is an example of removing several files: 494917721Speter 495017721Speter@example 495117721Speter$ cd test 495225839Speter$ rm *.c 495317721Speter$ cvs remove 495417721Spetercvs remove: Removing . 495517721Spetercvs remove: scheduling a.c for removal 495617721Spetercvs remove: scheduling b.c for removal 495717721Spetercvs remove: use 'cvs commit' to remove these files permanently 495817721Speter$ cvs ci -m "Removed unneeded files" 495917721Spetercvs commit: Examining . 496017721Spetercvs commit: Committing . 496117721Speter@end example 496217721Speter 496325839SpeterAs a convenience you can remove the file and @code{cvs 496425839Speterremove} it in one step, by specifying the @samp{-f} 496525839Speteroption. For example, the above example could also be 496625839Speterdone like this: 496717721Speter 496817721Speter@example 496925839Speter$ cd test 497025839Speter$ cvs remove -f *.c 497125839Spetercvs remove: scheduling a.c for removal 497225839Spetercvs remove: scheduling b.c for removal 497325839Spetercvs remove: use 'cvs commit' to remove these files permanently 497425839Speter$ cvs ci -m "Removed unneeded files" 497525839Spetercvs commit: Examining . 497625839Spetercvs commit: Committing . 497725839Speter@end example 497825839Speter 497925839SpeterIf you execute @code{remove} for a file, and then 498025839Speterchange your mind before you commit, you can undo the 498125839Speter@code{remove} with an @code{add} command. 498225839Speter@ignore 498325839Speter@c is this worth saying or not? Somehow it seems 498425839Speter@c confusing to me. 498525839SpeterOf course, 498625839Spetersince you have removed your copy of file in the working 498725839Speterdirectory, @sc{cvs} does not necessarily bring back the 498825839Spetercontents of the file from right before you executed 498925839Speter@code{remove}; instead it gets the file from the 499025839Speterrepository again. 499125839Speter@end ignore 499225839Speter 499325839Speter@c FIXME: what if you change your mind after you commit 499425839Speter@c it? (answer is also "cvs add" but we don't say that...). 499525839Speter@c We need some index entries for thinks like "undoing 499625839Speter@c removal" too. 499725839Speter 499825839Speter@example 499917721Speter$ ls 500017721SpeterCVS ja.h oj.c 500117721Speter$ rm oj.c 500217721Speter$ cvs remove oj.c 500317721Spetercvs remove: scheduling oj.c for removal 500417721Spetercvs remove: use 'cvs commit' to remove this file permanently 500517721Speter$ cvs add oj.c 500617721SpeterU oj.c 500717721Spetercvs add: oj.c, version 1.1.1.1, resurrected 500817721Speter@end example 500917721Speter 501017721SpeterIf you realize your mistake before you run the 501117721Speter@code{remove} command you can use @code{update} to 501217721Speterresurrect the file: 501317721Speter 501417721Speter@example 501517721Speter$ rm oj.c 501617721Speter$ cvs update oj.c 501717721Spetercvs update: warning: oj.c was lost 501817721SpeterU oj.c 501917721Speter@end example 502017721Speter 502125839SpeterWhen you remove a file it is removed only on the branch 502232785Speterwhich you are working on (@pxref{Branching and merging}). You can 502325839Speterlater merge the removals to another branch if you want 502425839Speter(@pxref{Merging adds and removals}). 502525839Speter 502625839Speter@node Removing directories 502732785Speter@section Removing directories 502866525Speter@cindex Removing directories 502966525Speter@cindex Directories, removing 503025839Speter 5031175261SobrienIn concept, removing directories is somewhat similar to 503225839Speterremoving files---you want the directory to not exist in 503325839Speteryour current working directories, but you also want to 503425839Speterbe able to retrieve old releases in which the directory 503525839Speterexisted. 503625839Speter 503725839SpeterThe way that you remove a directory is to remove all 503832785Speterthe files in it. You don't remove the directory 503932785Speteritself; there is no way to do that. 504032785SpeterInstead you specify the @samp{-P} option to 504166525Speter@code{cvs update} or @code{cvs checkout}, 504266525Speterwhich will cause @sc{cvs} to remove empty 504366525Speterdirectories from working directories. 504466525Speter(Note that @code{cvs export} always removes empty directories.) 504566525SpeterProbably the 504625839Speterbest way to do this is to always specify @samp{-P}; if 504725839Speteryou want an empty directory then put a dummy file (for 504825839Speterexample @file{.keepme}) in it to prevent @samp{-P} from 504925839Speterremoving it. 505025839Speter 505125839Speter@c I'd try to give a rationale for this, but I'm not 505225839Speter@c sure there is a particularly convincing one. What 505325839Speter@c we would _like_ is for CVS to do a better job of version 505425839Speter@c controlling whether directories exist, to eliminate the 505525839Speter@c need for -P and so that a file can be a directory in 505625839Speter@c one revision and a regular file in another. 505725839SpeterNote that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5058175261Sobrienoptions of @code{checkout}. This way, 505925839Speter@sc{cvs} will be able to correctly create the directory 506025839Speteror not depending on whether the particular version you 506125839Speterare checking out contains any files in that directory. 506225839Speter 506317721Speter@c --------------------------------------------------------------------- 506417721Speter@node Moving files 506532785Speter@section Moving and renaming files 506617721Speter@cindex Moving files 506717721Speter@cindex Renaming files 506817721Speter@cindex Files, moving 506917721Speter 507017721SpeterMoving files to a different directory or renaming them 507117721Speteris not difficult, but some of the ways in which this 507217721Speterworks may be non-obvious. (Moving or renaming a 507325839Speterdirectory is even harder. @xref{Moving directories}.). 507417721Speter 507517721SpeterThe examples below assume that the file @var{old} is renamed to 507617721Speter@var{new}. 507717721Speter 507817721Speter@menu 507917721Speter* Outside:: The normal way to Rename 508017721Speter* Inside:: A tricky, alternative way 508117721Speter* Rename by copying:: Another tricky, alternative way 508217721Speter@end menu 508317721Speter 508417721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 508517721Speter@node Outside 508632785Speter@subsection The Normal way to Rename 508717721Speter 508825839Speter@c More rename issues. Not sure whether these are 508925839Speter@c worth documenting; I'm putting them here because 509025839Speter@c it seems to be as good a place as any to try to 509125839Speter@c set down the issues. 509225839Speter@c * "cvs annotate" will annotate either the new 509325839Speter@c file or the old file; it cannot annotate _each 509425839Speter@c line_ based on whether it was last changed in the 509525839Speter@c new or old file. Unlike "cvs log", where the 509625839Speter@c consequences of having to select either the new 509725839Speter@c or old name seem fairly benign, this may be a 509825839Speter@c real advantage to having CVS know about renames 509925839Speter@c other than as a deletion and an addition. 510025839Speter 510117721SpeterThe normal way to move a file is to copy @var{old} to 510217721Speter@var{new}, and then issue the normal @sc{cvs} commands 510317721Speterto remove @var{old} from the repository, and add 510425839Speter@var{new} to it. 510525839Speter@c The following sentence is not true: one must cd into 510625839Speter@c the directory to run "cvs add". 510725839Speter@c (Both @var{old} and @var{new} could 510825839Speter@c contain relative paths, for example @file{foo/bar.c}). 510917721Speter 511017721Speter@example 511117721Speter$ mv @var{old} @var{new} 511217721Speter$ cvs remove @var{old} 511344852Speter$ cvs add @var{new} 511417721Speter$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 511517721Speter@end example 511617721Speter 511717721SpeterThis is the simplest way to move a file, it is not 511817721Spetererror-prone, and it preserves the history of what was 511917721Speterdone. Note that to access the history of the file you 512017721Spetermust specify the old or the new name, depending on what 512117721Speterportion of the history you are accessing. For example, 512217721Speter@code{cvs log @var{old}} will give the log up until the 512317721Spetertime of the rename. 512417721Speter 512517721SpeterWhen @var{new} is committed its revision numbers will 512625839Speterstart again, usually at 1.1, so if that bothers you, 512725839Speteruse the @samp{-r rev} option to commit. For more 512825839Speterinformation see @ref{Assigning revisions}. 512917721Speter 513017721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 513117721Speter@node Inside 513232785Speter@subsection Moving the history file 513317721Speter 513417721SpeterThis method is more dangerous, since it involves moving 513517721Speterfiles inside the repository. Read this entire section 513617721Speterbefore trying it out! 513717721Speter 513817721Speter@example 513954427Speter$ cd $CVSROOT/@var{dir} 514017721Speter$ mv @var{old},v @var{new},v 514117721Speter@end example 514217721Speter 514317721Speter@noindent 514417721SpeterAdvantages: 514517721Speter 514617721Speter@itemize @bullet 514717721Speter@item 514817721SpeterThe log of changes is maintained intact. 514917721Speter 515017721Speter@item 515117721SpeterThe revision numbers are not affected. 515217721Speter@end itemize 515317721Speter 515417721Speter@noindent 515517721SpeterDisadvantages: 515617721Speter 515717721Speter@itemize @bullet 515817721Speter@item 515954427SpeterOld releases cannot easily be fetched from the 516017721Speterrepository. (The file will show up as @var{new} even 516117721Speterin revisions from the time before it was renamed). 516217721Speter 516317721Speter@item 516417721SpeterThere is no log information of when the file was renamed. 516517721Speter 516617721Speter@item 516717721SpeterNasty things might happen if someone accesses the history file 516817721Speterwhile you are moving it. Make sure no one else runs any of the @sc{cvs} 516917721Spetercommands while you move it. 517017721Speter@end itemize 517117721Speter 517217721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 517317721Speter@node Rename by copying 517432785Speter@subsection Copying the history file 517517721Speter 517617721SpeterThis way also involves direct modifications to the 517717721Speterrepository. It is safe, but not without drawbacks. 517817721Speter 517917721Speter@example 518017721Speter# @r{Copy the @sc{rcs} file inside the repository} 518154427Speter$ cd $CVSROOT/@var{dir} 518217721Speter$ cp @var{old},v @var{new},v 518317721Speter# @r{Remove the old file} 518454427Speter$ cd ~/@var{dir} 518517721Speter$ rm @var{old} 518617721Speter$ cvs remove @var{old} 518717721Speter$ cvs commit @var{old} 518817721Speter# @r{Remove all tags from @var{new}} 518917721Speter$ cvs update @var{new} 519025839Speter$ cvs log @var{new} # @r{Remember the non-branch tag names} 519125839Speter$ cvs tag -d @var{tag1} @var{new} 519225839Speter$ cvs tag -d @var{tag2} @var{new} 519317721Speter@dots{} 519417721Speter@end example 519517721Speter 519617721SpeterBy removing the tags you will be able to check out old 519754427Speterrevisions. 519817721Speter 519917721Speter@noindent 520017721SpeterAdvantages: 520117721Speter 520217721Speter@itemize @bullet 520317721Speter@item 520417721Speter@c FIXME: Is this true about -D now that we have death 520517721Speter@c support? See 5B.3 in the FAQ. 520617721SpeterChecking out old revisions works correctly, as long as 520717721Speteryou use @samp{-r@var{tag}} and not @samp{-D@var{date}} 520817721Speterto retrieve the revisions. 520917721Speter 521017721Speter@item 521117721SpeterThe log of changes is maintained intact. 521217721Speter 521317721Speter@item 521417721SpeterThe revision numbers are not affected. 521517721Speter@end itemize 521617721Speter 521717721Speter@noindent 521817721SpeterDisadvantages: 521917721Speter 522017721Speter@itemize @bullet 522117721Speter@item 522217721SpeterYou cannot easily see the history of the file across the rename. 522317721Speter 522425839Speter@ignore 522525839Speter@c Is this true? I don't see how the revision numbers 522625839Speter@c _could_ start over, when new,v is just old,v with 522725839Speter@c the tags deleted. 522825839Speter@c If there is some need to reinstate this text, 522925839Speter@c it is "usually 1.1", not "1.0" and it needs an 523025839Speter@c xref to Assigning revisions 523117721Speter@item 523217721SpeterUnless you use the @samp{-r rev} (@pxref{commit 523317721Speteroptions}) flag when @var{new} is committed its revision 523417721Speternumbers will start at 1.0 again. 523525839Speter@end ignore 523617721Speter@end itemize 523717721Speter 523817721Speter@c --------------------------------------------------------------------- 523917721Speter@node Moving directories 524032785Speter@section Moving and renaming directories 524117721Speter@cindex Moving directories 524217721Speter@cindex Renaming directories 524317721Speter@cindex Directories, moving 524417721Speter 524525839SpeterThe normal way to rename or move a directory is to 524625839Speterrename or move each file within it as described in 524725839Speter@ref{Outside}. Then check out with the @samp{-P} 524825839Speteroption, as described in @ref{Removing directories}. 524917721Speter 525025839SpeterIf you really want to hack the repository to rename or 525125839Speterdelete a directory in the repository, you can do it 525225839Speterlike this: 525317721Speter 525417721Speter@enumerate 525517721Speter@item 525654427SpeterInform everyone who has a checked out copy of the directory that the 5257175261Sobriendirectory will be renamed. They should commit all their changes in all their 5258175261Sobriencopies of the project containing the directory to be removed, and remove 5259175261Sobrienall their working copies of said project, before you take the steps below. 526017721Speter 526117721Speter@item 526217721SpeterRename the directory inside the repository. 526317721Speter 526417721Speter@example 526554427Speter$ cd $CVSROOT/@var{parent-dir} 526617721Speter$ mv @var{old-dir} @var{new-dir} 526717721Speter@end example 526817721Speter 526917721Speter@item 527017721SpeterFix the @sc{cvs} administrative files, if necessary (for 527117721Speterinstance if you renamed an entire module). 527217721Speter 527317721Speter@item 527454427SpeterTell everyone that they can check out again and continue 527517721Speterworking. 527617721Speter 527717721Speter@end enumerate 527817721Speter 527954427SpeterIf someone had a working copy the @sc{cvs} commands will 528017721Spetercease to work for him, until he removes the directory 528117721Speterthat disappeared inside the repository. 528217721Speter 528317721SpeterIt is almost always better to move the files in the 528417721Speterdirectory instead of moving the directory. If you move the 528517721Speterdirectory you are unlikely to be able to retrieve old 528617721Speterreleases correctly, since they probably depend on the 528717721Spetername of the directories. 528817721Speter 528917721Speter@c --------------------------------------------------------------------- 529017721Speter@node History browsing 529117721Speter@chapter History browsing 529217721Speter@cindex History browsing 529317721Speter@cindex Traceability 529417721Speter@cindex Isolation 529517721Speter 529617721Speter@ignore 529717721Speter@c This is too long for an introduction (goal is 529817721Speter@c one 20x80 character screen), and also mixes up a 529917721Speter@c variety of issues (parallel development, history, 530017721Speter@c maybe even touches on process control). 530117721Speter 530217721Speter@c -- @quote{To lose ones history is to lose ones soul.} 530317721Speter@c -- /// 530417721Speter@c -- ///Those who cannot remember the past are condemned to repeat it. 530517721Speter@c -- /// -- George Santayana 530617721Speter@c -- /// 530717721Speter 530817721Speter@sc{cvs} tries to make it easy for a group of people to work 530917721Spetertogether. This is done in two ways: 531017721Speter 531117721Speter@itemize @bullet 531217721Speter@item 531317721SpeterIsolation---You have your own working copy of the 531417721Spetersource. You are not affected by modifications made by 531517721Speterothers until you decide to incorporate those changes 531617721Speter(via the @code{update} command---@pxref{update}). 531717721Speter 531844852Speter@item 531917721SpeterTraceability---When something has changed, you can 532017721Speteralways see @emph{exactly} what changed. 532117721Speter@end itemize 532217721Speter 532317721SpeterThere are several features of @sc{cvs} that together lead 532417721Speterto traceability: 532517721Speter 532617721Speter@itemize @bullet 532717721Speter@item 532817721SpeterEach revision of a file has an accompanying log 532917721Spetermessage. 533017721Speter 533117721Speter@item 533217721SpeterAll commits are optionally logged to a central history 533317721Speterdatabase. 533417721Speter 533517721Speter@item 533617721SpeterLogging information can be sent to a user-defined 533717721Speterprogram (@pxref{loginfo}). 533817721Speter@end itemize 533917721Speter 534017721Speter@c -- More text here. 534117721Speter 534217721SpeterThis chapter should talk about the history file, the 534317721Speter@code{log} command, the usefulness of ChangeLogs 534417721Spetereven when you run @sc{cvs}, and things like that. 534517721Speter 534617721Speter@end ignore 534717721Speter 534817721Speter@c kind of lame, in a lot of ways the above text inside 534917721Speter@c the @ignore motivates this chapter better 535017721SpeterOnce you have used @sc{cvs} to store a version control 535117721Speterhistory---what files have changed when, how, and by 535217721Speterwhom, there are a variety of mechanisms for looking 535317721Speterthrough the history. 535417721Speter 535525839Speter@c FIXME: should also be talking about how you look at 535625839Speter@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 535717721Speter@menu 535817721Speter* log messages:: Log messages 535917721Speter* history database:: The history database 536017721Speter* user-defined logging:: User-defined logging 536117721Speter@end menu 536217721Speter 536317721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 536417721Speter@node log messages 536517721Speter@section Log messages 536617721Speter 536717721Speter@c FIXME: @xref to place where we talk about how to 536817721Speter@c specify message to commit. 536917721SpeterWhenever you commit a file you specify a log message. 537017721Speter 537117721Speter@c FIXME: bring the information here, and get rid of or 537217721Speter@c greatly shrink the "log" node. 537317721SpeterTo look through the log messages which have been 537417721Speterspecified for every revision which has been committed, 537517721Speteruse the @code{cvs log} command (@pxref{log}). 537617721Speter 537717721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 537817721Speter@node history database 537917721Speter@section The history database 538017721Speter 538117721Speter@c FIXME: bring the information from the history file 538217721Speter@c and history nodes here. Rewrite it to be motivated 538317721Speter@c better (start out by clearly explaining what gets 538417721Speter@c logged in history, for example). 538517721SpeterYou can use the history file (@pxref{history file}) to 538617721Speterlog various @sc{cvs} actions. To retrieve the 538717721Speterinformation from the history file, use the @code{cvs 538817721Speterhistory} command (@pxref{history}). 538966525Speter 539066525SpeterNote: you can control what is logged to this file by using the 539166525Speter@samp{LogHistory} keyword in the @file{CVSROOT/config} file 539266525Speter(@pxref{config}). 539366525Speter 539425839Speter@c 539525839Speter@c The history database has many problems: 539625839Speter@c * It is very unclear what field means what. This 539725839Speter@c could be improved greatly by better documentation, 539825839Speter@c but there are still non-orthogonalities (for 539925839Speter@c example, tag does not record the "repository" 540025839Speter@c field but most records do). 540125839Speter@c * Confusion about files, directories, and modules. 540225839Speter@c Some commands record one, some record others. 540325839Speter@c * File removal is not logged. There is an 'R' 540425839Speter@c record type documented, but CVS never uses it. 540525839Speter@c * Tags are only logged for the "cvs rtag" command, 540625839Speter@c not "cvs tag". The fix for this is not completely 540725839Speter@c clear (see above about modules vs. files). 540825839Speter@c * Are there other cases of operations that are not 540925839Speter@c logged? One would hope for all changes to the 541025839Speter@c repository to be logged somehow (particularly 541125839Speter@c operations like tagging, "cvs admin -k", and other 541225839Speter@c operations which do not record a history that one 541325839Speter@c can get with "cvs log"). Operations on the working 541425839Speter@c directory, like export, get, and release, are a 541525839Speter@c second category also covered by the current "cvs 541625839Speter@c history". 541725839Speter@c * The history file does not record the options given 541825839Speter@c to a command. The most serious manifestation of 541925839Speter@c this is perhaps that it doesn't record whether a command 542025839Speter@c was recursive. It is not clear to me whether one 542125839Speter@c wants to log at a level very close to the command 542225839Speter@c line, as a sort of way of logging each command 542325839Speter@c (more or less), or whether one wants 542425839Speter@c to log more at the level of what was changed (or 542525839Speter@c something in between), but either way the current 542625839Speter@c information has pretty big gaps. 542725839Speter@c * Further details about a tag--like whether it is a 542825839Speter@c branch tag or, if a non-branch tag, which branch it 542925839Speter@c is on. One can find out this information about the 543025839Speter@c tag as it exists _now_, but if the tag has been 543125839Speter@c moved, one doesn't know what it was like at the time 543225839Speter@c the history record was written. 543325839Speter@c * Whether operating on a particular tag, date, or 543425839Speter@c options was implicit (sticky) or explicit. 543525839Speter@c 543625839Speter@c Another item, only somewhat related to the above, is a 543725839Speter@c way to control what is logged in the history file. 543825839Speter@c This is probably the only good way to handle 543925839Speter@c different people having different ideas about 544025839Speter@c information/space tradeoffs. 544125839Speter@c 544225839Speter@c It isn't really clear that it makes sense to try to 544325839Speter@c patch up the history file format as it exists now to 544425839Speter@c include all that stuff. It might be better to 544525839Speter@c design a whole new CVSROOT/nhistory file and "cvs 544625839Speter@c nhistory" command, or some such, or in some other 544725839Speter@c way trying to come up with a clean break from the 544825839Speter@c past, which can address the above concerns. Another 544925839Speter@c open question is how/whether this relates to 545025839Speter@c taginfo/loginfo/etc. 545117721Speter 545217721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 545317721Speter@node user-defined logging 545417721Speter@section User-defined logging 545517721Speter 545617721Speter@c FIXME: probably should centralize this information 545717721Speter@c here, at least to some extent. Maybe by moving the 545817721Speter@c loginfo, etc., nodes here and replacing 545917721Speter@c the "user-defined logging" node with one node for 546017721Speter@c each method. 546117721SpeterYou can customize @sc{cvs} to log various kinds of 546217721Speteractions, in whatever manner you choose. These 546317721Spetermechanisms operate by executing a script at various 546417721Spetertimes. The script might append a message to a file 546517721Speterlisting the information and the programmer who created 546617721Speterit, or send mail to a group of developers, or, perhaps, 546717721Speterpost a message to a particular newsgroup. To log 546817721Spetercommits, use the @file{loginfo} file (@pxref{loginfo}). 5469128266SpeterTo log tags, use the @file{taginfo} file (@pxref{taginfo}). 547017721Speter@c FIXME: What is difference between doing it in the 547117721Speter@c modules file and using loginfo/taginfo? Why should 547217721Speter@c user use one or the other? 5473177391SobrienTo log checkouts, exports, and tags, 5474177391Sobrienrespectively, you can also use the 547517721Speter@samp{-o}, @samp{-e}, and @samp{-t} options in the 547617721Spetermodules file. For a more flexible way of giving 547717721Speternotifications to various users, which requires less in 547817721Speterthe way of keeping centralized scripts up to date, use 547917721Speterthe @code{cvs watch add} command (@pxref{Getting 548017721SpeterNotified}); this command is useful even if you are not 548117721Speterusing @code{cvs watch on}. 548217721Speter 548317721Speter@c --------------------------------------------------------------------- 548432785Speter@node Binary files 548532785Speter@chapter Handling binary files 548632785Speter@cindex Binary files 548732785Speter 548832785SpeterThe most common use for @sc{cvs} is to store text 548932785Speterfiles. With text files, @sc{cvs} can merge revisions, 549032785Speterdisplay the differences between revisions in a 549132785Speterhuman-visible fashion, and other such operations. 549232785SpeterHowever, if you are willing to give up a few of these 549332785Speterabilities, @sc{cvs} can store binary files. For 549432785Speterexample, one might store a web site in @sc{cvs} 549532785Speterincluding both text files and binary images. 549632785Speter 549732785Speter@menu 549832785Speter* Binary why:: More details on issues with binary files 549932785Speter* Binary howto:: How to store them 550032785Speter@end menu 550132785Speter 550232785Speter@node Binary why 550332785Speter@section The issues with binary files 550432785Speter 550532785SpeterWhile the need to manage binary files may seem obvious 550632785Speterif the files that you customarily work with are binary, 550732785Speterputting them into version control does present some 550832785Speteradditional issues. 550932785Speter 551032785SpeterOne basic function of version control is to show the 551132785Speterdifferences between two revisions. For example, if 551232785Spetersomeone else checked in a new version of a file, you 551332785Spetermay wish to look at what they changed and determine 551432785Speterwhether their changes are good. For text files, 551532785Speter@sc{cvs} provides this functionality via the @code{cvs 551632785Speterdiff} command. For binary files, it may be possible to 551732785Speterextract the two revisions and then compare them with a 551832785Spetertool external to @sc{cvs} (for example, word processing 551932785Spetersoftware often has such a feature). If there is no 552032785Spetersuch tool, one must track changes via other mechanisms, 552132785Spetersuch as urging people to write good log messages, and 552232785Speterhoping that the changes they actually made were the 552332785Speterchanges that they intended to make. 552432785Speter 552532785SpeterAnother ability of a version control system is the 552632785Speterability to merge two revisions. For @sc{cvs} this 552732785Speterhappens in two contexts. The first is when users make 552832785Speterchanges in separate working directories 552932785Speter(@pxref{Multiple developers}). The second is when one 553032785Spetermerges explicitly with the @samp{update -j} command 553132785Speter(@pxref{Branching and merging}). 553232785Speter 553332785SpeterIn the case of text 553432785Speterfiles, @sc{cvs} can merge changes made independently, 553532785Speterand signal a conflict if the changes conflict. With 553632785Speterbinary files, the best that @sc{cvs} can do is present 553732785Speterthe two different copies of the file, and leave it to 553832785Speterthe user to resolve the conflict. The user may choose 553932785Speterone copy or the other, or may run an external merge 554032785Spetertool which knows about that particular file format, if 554132785Speterone exists. 554232785SpeterNote that having the user merge relies primarily on the 554332785Speteruser to not accidentally omit some changes, and thus is 554432785Speterpotentially error prone. 554532785Speter 554632785SpeterIf this process is thought to be undesirable, the best 554732785Speterchoice may be to avoid merging. To avoid the merges 554832785Speterthat result from separate working directories, see the 554932785Speterdiscussion of reserved checkouts (file locking) in 555032785Speter@ref{Multiple developers}. To avoid the merges 555132785Speterresulting from branches, restrict use of branches. 555232785Speter 555332785Speter@node Binary howto 555432785Speter@section How to store binary files 555532785Speter 555632785SpeterThere are two issues with using @sc{cvs} to store 555732785Speterbinary files. The first is that @sc{cvs} by default 555832785Speterconverts line endings between the canonical form in 555932785Speterwhich they are stored in the repository (linefeed 556032785Speteronly), and the form appropriate to the operating system 556132785Speterin use on the client (for example, carriage return 556232785Speterfollowed by line feed for Windows NT). 556332785Speter 556432785SpeterThe second is that a binary file might happen to 556532785Spetercontain data which looks like a keyword (@pxref{Keyword 556632785Spetersubstitution}), so keyword expansion must be turned 556732785Speteroff. 556832785Speter 556932785Speter@c FIXME: the third is that one can't do merges with 557032785Speter@c binary files. xref to Multiple Developers and the 557132785Speter@c reserved checkout issues. 557232785Speter 557332785SpeterThe @samp{-kb} option available with some @sc{cvs} 557432785Spetercommands insures that neither line ending conversion 557532785Speternor keyword expansion will be done. 557632785Speter 557732785SpeterHere is an example of how you can create a new file 557832785Speterusing the @samp{-kb} flag: 557932785Speter 558032785Speter@example 5581130303Speter$ echo '$@splitrcskeyword{Id}$' > kotest 558232785Speter$ cvs add -kb -m"A test file" kotest 558332785Speter$ cvs ci -m"First checkin; contains a keyword" kotest 558432785Speter@end example 558532785Speter 558632785SpeterIf a file accidentally gets added without @samp{-kb}, 558732785Speterone can use the @code{cvs admin} command to recover. 558832785SpeterFor example: 558932785Speter 559032785Speter@example 5591130303Speter$ echo '$@splitrcskeyword{Id}$' > kotest 559232785Speter$ cvs add -m"A test file" kotest 559332785Speter$ cvs ci -m"First checkin; contains a keyword" kotest 559432785Speter$ cvs admin -kb kotest 559532785Speter$ cvs update -A kotest 559632785Speter# @r{For non-unix systems:} 559732785Speter# @r{Copy in a good copy of the file from outside CVS} 559832785Speter$ cvs commit -m "make it binary" kotest 559932785Speter@end example 560032785Speter 560132785Speter@c Trying to describe this for both unix and non-unix 560232785Speter@c in the same description is very confusing. Might 560332785Speter@c want to split the two, or just ditch the unix "shortcut" 560432785Speter@c (unixheads don't do much with binary files, anyway). 560532785Speter@c This used to say "(Try the above example, and do a 560632785Speter@c @code{cat kotest} after every command)". But that 560732785Speter@c only really makes sense for the unix case. 560832785SpeterWhen you check in the file @file{kotest} the file is 560932785Speternot preserved as a binary file, because you did not 561032785Spetercheck it in as a binary file. The @code{cvs 561132785Speteradmin -kb} command sets the default keyword 561232785Spetersubstitution method for this file, but it does not 561332785Speteralter the working copy of the file that you have. If you need to 561444852Spetercope with line endings (that is, you are using 561532785Speter@sc{cvs} on a non-unix system), then you need to 561632785Spetercheck in a new copy of the file, as shown by the 561732785Speter@code{cvs commit} command above. 561832785SpeterOn unix, the @code{cvs update -A} command suffices. 561932785Speter@c FIXME: should also describe what the *other users* 562032785Speter@c need to do, if they have checked out copies which 562132785Speter@c have been corrupted by lack of -kb. I think maybe 562232785Speter@c "cvs update -kb" or "cvs 562332785Speter@c update -A" would suffice, although the user who 562432785Speter@c reported this suggested removing the file, manually 562532785Speter@c removing it from CVS/Entries, and then "cvs update" 5626128266Speter(Note that you can use @code{cvs log} to determine the default keyword 5627128266Spetersubstitution method for a file and @code{cvs status} to determine 5628128266Speterthe keyword substitution method for a working copy.) 562932785Speter 563032785SpeterHowever, in using @code{cvs admin -k} to change the 563132785Speterkeyword expansion, be aware that the keyword expansion 563232785Spetermode is not version controlled. This means that, for 563332785Speterexample, that if you have a text file in old releases, 563432785Speterand a binary file with the same name in new releases, 563532785Speter@sc{cvs} provides no way to check out the file in text 563632785Speteror binary mode depending on what version you are 563732785Speterchecking out. There is no good workaround for this 563832785Speterproblem. 563932785Speter 564032785SpeterYou can also set a default for whether @code{cvs add} 564132785Speterand @code{cvs import} treat a file as binary based on 564232785Speterits name; for example you could say that files who 564332785Speternames end in @samp{.exe} are binary. @xref{Wrappers}. 564432785SpeterThere is currently no way to have @sc{cvs} detect 564532785Speterwhether a file is binary based on its contents. The 564632785Spetermain difficulty with designing such a feature is that 564732785Speterit is not clear how to distinguish between binary and 564832785Speternon-binary files, and the rules to apply would vary 564932785Speterconsiderably with the operating system. 565032785Speter@c For example, it would be good on MS-DOS-family OSes 565132785Speter@c for anything containing ^Z to be binary. Having 565232785Speter@c characters with the 8th bit set imply binary is almost 565332785Speter@c surely a bad idea in the context of ISO-8859-* and 565432785Speter@c other such character sets. On VMS or the Mac, we 565532785Speter@c could use the OS's file typing. This is a 565632785Speter@c commonly-desired feature, and something of this sort 565732785Speter@c may make sense. But there are a lot of pitfalls here. 565832785Speter@c 565932785Speter@c Another, probably better, way to tell is to read the 566032785Speter@c file in text mode, write it to a temp file in text 566144852Speter@c mode, and then do a binary mode compare of the two 566232785Speter@c files. If they differ, it is a binary file. This 566332785Speter@c might have problems on VMS (or some other system 566432785Speter@c with several different text modes), but in general 566532785Speter@c should be relatively portable. The only other 566632785Speter@c downside I can think of is that it would be fairly 566732785Speter@c slow, but that is perhaps a small price to pay for 566832785Speter@c not having your files corrupted. Another issue is 566932785Speter@c what happens if you import a text file with bare 567032785Speter@c linefeeds on Windows. Such files will show up on 567132785Speter@c Windows sometimes (I think some native windows 567232785Speter@c programs even write them, on occasion). Perhaps it 567332785Speter@c is reasonable to treat such files as binary; after 567432785Speter@c all it is something of a presumption to assume that 567532785Speter@c the user would want the linefeeds converted to CRLF. 567632785Speter 567732785Speter@c --------------------------------------------------------------------- 567832785Speter@node Multiple developers 567932785Speter@chapter Multiple developers 568032785Speter@cindex Multiple developers 568132785Speter@cindex Team of developers 568232785Speter@cindex File locking 568332785Speter@cindex Locking files 568432785Speter@cindex Working copy 568566525Speter@cindex Reserved checkouts 568666525Speter@cindex Unreserved checkouts 568732785Speter@cindex RCS-style locking 568832785Speter 568932785SpeterWhen more than one person works on a software project 569032785Speterthings often get complicated. Often, two people try to 569132785Speteredit the same file simultaneously. One solution, known 569232785Speteras @dfn{file locking} or @dfn{reserved checkouts}, is 569332785Speterto allow only one person to edit each file at a time. 569432785SpeterThis is the only solution with some version control 569532785Spetersystems, including @sc{rcs} and @sc{sccs}. Currently 569632785Speterthe usual way to get reserved checkouts with @sc{cvs} 569732785Speteris the @code{cvs admin -l} command (@pxref{admin 569832785Speteroptions}). This is not as nicely integrated into 569932785Speter@sc{cvs} as the watch features, described below, but it 570032785Speterseems that most people with a need for reserved 570132785Spetercheckouts find it adequate. 570232785Speter@c Or "find it better than worrying about implementing 570332785Speter@c nicely integrated reserved checkouts" or ...? 570432785SpeterIt also may be possible to use the watches 570532785Speterfeatures described below, together with suitable 570632785Speterprocedures (not enforced by software), to avoid having 570732785Spetertwo people edit at the same time. 570832785Speter 570932785Speter@c Our unreserved checkout model might not 571032785Speter@c be quite the same as others. For example, I 571132785Speter@c think that some systems will tend to create a branch 571232785Speter@c in the case where CVS prints "up-to-date check failed". 571332785Speter@c It isn't clear to me whether we should try to 571432785Speter@c explore these subtleties; it could easily just 571532785Speter@c confuse people. 571632785SpeterThe default model with @sc{cvs} is known as 571732785Speter@dfn{unreserved checkouts}. In this model, developers 571832785Spetercan edit their own @dfn{working copy} of a file 571932785Spetersimultaneously. The first person that commits his 572032785Speterchanges has no automatic way of knowing that another 572132785Speterhas started to edit it. Others will get an error 572232785Spetermessage when they try to commit the file. They must 572332785Speterthen use @sc{cvs} commands to bring their working copy 572432785Speterup to date with the repository revision. This process 572532785Speteris almost automatic. 572632785Speter 572732785Speter@c FIXME? should probably use the word "watch" here, to 572832785Speter@c tie this into the text below and above. 572966525Speter@sc{cvs} also supports mechanisms which facilitate 573054427Spetervarious kinds of communication, without actually 573132785Speterenforcing rules like reserved checkouts do. 573232785Speter 573332785SpeterThe rest of this chapter describes how these various 573432785Spetermodels work, and some of the issues involved in 573532785Speterchoosing between them. 573632785Speter 573732785Speter@ignore 573832785SpeterHere is a draft reserved checkout design or discussion 573932785Speterof the issues. This seems like as good a place as any 574032785Speterfor this. 574132785Speter 574232785SpeterMight want a cvs lock/cvs unlock--in which the names 574332785Speterdiffer from edit/unedit because the network must be up 574432785Speterfor these to work. unedit gives an error if there is a 574532785Speterreserved checkout in place (so that people don't 574632785Speteraccidentally leave locks around); unlock gives an error 574732785Speterif one is not in place (this is more arguable; perhaps 574832785Speterit should act like unedit in that case). 574932785Speter 575032785SpeterOn the other hand, might want it so that emacs, 575132785Speterscripts, etc., can get ready to edit a file without 575232785Speterhaving to know which model is in use. In that case we 575332785Speterwould have a "cvs watch lock" (or .cvsrc?) (that is, 575432785Speterthree settings, "on", "off", and "lock"). Having cvs 575532785Speterwatch lock set would cause a get to record in the CVS 575632785Speterdirectory which model is in use, and cause "cvs edit" 575732785Speterto change behaviors. We'd want a way to query which 575832785Spetersetting is in effect (this would be handy even if it is 575932785Speteronly "on" or "off" as presently). If lock is in 576032785Spetereffect, then commit would require a lock before 576132785Speterallowing a checkin; chmod wouldn't suffice (might be 576232785Speterdebatable--see chmod comment below, in watches--but it 576332785Speteris the way people expect RCS to work and I can't think 576432785Speterof any significant downside. On the other hand, maybe 576532785Speterit isn't worth bothering, because people who are used 576632785Speterto RCS wouldn't think to use chmod anyway). 576732785Speter 576832785SpeterImplementation: use file attributes or use RCS 576932785Speterlocking. The former avoids more dependence on RCS 5770130303Speterbehaviors we will need to re-implement as we librarify 577132785SpeterRCS, and makes it easier to import/export RCS files (in 577232785Speterthat context, want to ignore the locker field). But 577332785Speternote that RCS locks are per-branch, which is the 577432785Spetercorrect behavior (this is also an issue for the "watch 577532785Speteron" features; they should be per-branch too). 577632785Speter 577732785SpeterHere are a few more random notes about implementation 577832785Speterdetails, assuming "cvs watch lock" and 577932785Speter 578032785SpeterCVS/Watched file? Or try to fit this into CVS/Entries somehow? 578132785SpeterCases: (1) file is checked out (unreserved or with watch on) by old 578281404Speterversion of @sc{cvs}, now we do something with new one, (2) file is checked 578332785Speterout by new version, now we do something with old one. 578432785Speter 578532785SpeterRemote protocol would have a "Watched" analogous to "Mode". Of course 578632785Speterit would apply to all Updated-like requests. How do we keep this 578732785Spetersetting up to date? I guess that there wants to be a Watched request, 578832785Speterand the server would send a new one if it isn't up to date? (Ugh--hard 578932785Speterto implement and slows down "cvs -q update"--is there an easier way?) 579032785Speter 579132785Speter"cvs edit"--checks CVS/Watched, and if watch lock, then sends 579232785Speter"edit-lock" request. Which comes back with a Checked-in with 579332785Speterappropriate Watched (off, on, lock, locked, or some such?), or error 579432785Spetermessage if already locked. 579532785Speter 579632785Speter"cvs commit"--only will commit if off/on/locked. lock is not OK. 579732785Speter 579832785SpeterDoc: 579932785Speternote that "cvs edit" must be connected to network if watch lock is in 580032785Spetereffect. 580132785Speter 580232785SpeterTalk about what to do if someone has locked a file and you want to 580332785Speteredit that file. (breaking locks, or lack thereof). 580432785Speter 580532785Speter 580632785SpeterOne other idea (which could work along with the 580732785Speterexisting "cvs admin -l" reserved checkouts, as well as 580832785Speterthe above): 580932785Speter 581032785Speter"cvs editors" could show who has the file locked, if 581132785Spetersomeone does. 581232785Speter 581332785Speter@end ignore 581432785Speter 581532785Speter@menu 581632785Speter* File status:: A file can be in several states 581732785Speter* Updating a file:: Bringing a file up-to-date 581832785Speter* Conflicts example:: An informative example 581932785Speter* Informing others:: To cooperate you must inform 582032785Speter* Concurrency:: Simultaneous repository access 582132785Speter* Watches:: Mechanisms to track who is editing files 582232785Speter* Choosing a model:: Reserved or unreserved checkouts? 582332785Speter@end menu 582432785Speter 582532785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 582632785Speter@node File status 582732785Speter@section File status 582832785Speter@cindex File status 582932785Speter@cindex Status of a file 583032785Speter 583132785Speter@c Shouldn't this start with an example or something, 583232785Speter@c introducing the unreserved checkout model? Before we 583332785Speter@c dive into listing states? 583432785SpeterBased on what operations you have performed on a 583532785Speterchecked out file, and what operations others have 583632785Speterperformed to that file in the repository, one can 583732785Speterclassify a file in a number of states. The states, as 583832785Speterreported by the @code{status} command, are: 583932785Speter 584032785Speter@c The order of items is chosen to group logically 584132785Speter@c similar outputs together. 584232785Speter@c People who want alphabetical can use the index... 584332785Speter@table @asis 584432785Speter@cindex Up-to-date 584532785Speter@item Up-to-date 584632785SpeterThe file is identical with the latest revision in the 584732785Speterrepository for the branch in use. 584832785Speter@c FIXME: should we clarify "in use"? The answer is 584932785Speter@c sticky tags, and trying to distinguish branch sticky 585032785Speter@c tags from non-branch sticky tags seems rather awkward 585132785Speter@c here. 585232785Speter@c FIXME: What happens with non-branch sticky tags? Is 585332785Speter@c a stuck file "Up-to-date" or "Needs checkout" or what? 585432785Speter 585532785Speter@item Locally Modified 585632785Speter@cindex Locally Modified 585732785SpeterYou have edited the file, and not yet committed your changes. 585832785Speter 585932785Speter@item Locally Added 586032785Speter@cindex Locally Added 586132785SpeterYou have added the file with @code{add}, and not yet 586232785Spetercommitted your changes. 586332785Speter@c There are many cases involving the file being 586432785Speter@c added/removed/modified in the working directory, and 586532785Speter@c added/removed/modified in the repository, which we 586632785Speter@c don't try to describe here. I'm not sure that "cvs 586732785Speter@c status" produces a non-confusing output in most of 586832785Speter@c those cases. 586932785Speter 587032785Speter@item Locally Removed 587132785Speter@cindex Locally Removed 587232785SpeterYou have removed the file with @code{remove}, and not yet 587332785Spetercommitted your changes. 587432785Speter 587532785Speter@item Needs Checkout 587632785Speter@cindex Needs Checkout 587732785SpeterSomeone else has committed a newer revision to the 587832785Speterrepository. The name is slightly misleading; you will 587932785Speterordinarily use @code{update} rather than 588032785Speter@code{checkout} to get that newer revision. 588132785Speter 588232785Speter@item Needs Patch 588332785Speter@cindex Needs Patch 588432785Speter@c See also newb-123j0 in sanity.sh (although that case 588532785Speter@c should probably be changed rather than documented). 588632785SpeterLike Needs Checkout, but the @sc{cvs} server will send 588732785Spetera patch rather than the entire file. Sending a patch or 588832785Spetersending an entire file accomplishes the same thing. 588932785Speter 589032785Speter@item Needs Merge 589132785Speter@cindex Needs Merge 589232785SpeterSomeone else has committed a newer revision to the repository, and you 589332785Speterhave also made modifications to the file. 589432785Speter 5895128266Speter@item Unresolved Conflict 5896128266Speter@cindex Unresolved Conflict 5897128266Speter@c FIXCVS - This file status needs to be changed to some more informative 5898128266Speter@c text that distinguishes it more clearly from each of the Locally Added, 5899128266Speter@c File had conflicts on merge, and Unknown status types, but an exact and 5900128266Speter@c succinct wording escapes me at the moment. 5901128266SpeterA file with the same name as this new file has been added to the repository 5902128266Speterfrom a second workspace. This file will need to be moved out of the way 5903128266Speterto allow an @code{update} to complete. 5904128266Speter 590532785Speter@item File had conflicts on merge 590632785Speter@cindex File had conflicts on merge 590732785Speter@c is it worth saying that this message was "Unresolved 590832785Speter@c Conflict" in CVS 1.9 and earlier? I'm inclined to 590932785Speter@c think that is unnecessarily confusing to new users. 591032785SpeterThis is like Locally Modified, except that a previous 591132785Speter@code{update} command gave a conflict. If you have not 591232785Speteralready done so, you need to 591332785Speterresolve the conflict as described in @ref{Conflicts example}. 591432785Speter 591532785Speter@item Unknown 591632785Speter@cindex Unknown 591766525Speter@sc{cvs} doesn't know anything about this file. For 591832785Speterexample, you have created a new file and have not run 591932785Speter@code{add}. 592044852Speter@c 592132785Speter@c "Entry Invalid" and "Classify Error" are also in the 592232785Speter@c status.c. The latter definitely indicates a CVS bug 592332785Speter@c (should it be worded more like "internal error" so 592432785Speter@c people submit bug reports if they see it?). The former 592532785Speter@c I'm not as sure; I haven't tracked down whether/when it 592632785Speter@c appears in "cvs status" output. 592732785Speter 592832785Speter@end table 592932785Speter 593032785SpeterTo help clarify the file status, @code{status} also 593132785Speterreports the @code{Working revision} which is the 593232785Speterrevision that the file in the working directory derives 593332785Speterfrom, and the @code{Repository revision} which is the 593432785Speterlatest revision in the repository for the branch in 593532785Speteruse. 593632785Speter@c FIXME: should we clarify "in use"? The answer is 593732785Speter@c sticky tags, and trying to distinguish branch sticky 593832785Speter@c tags from non-branch sticky tags seems rather awkward 593932785Speter@c here. 594032785Speter@c FIXME: What happens with non-branch sticky tags? 594132785Speter@c What is the Repository Revision there? See the 594232785Speter@c comment at vn_rcs in cvs.h, which is kind of 594332785Speter@c confused--we really need to document better what this 594432785Speter@c field contains. 594532785Speter@c Q: Should we document "New file!" and other such 594632785Speter@c outputs or are they self-explanatory? 594732785Speter@c FIXME: what about the date to the right of "Working 594832785Speter@c revision"? It doesn't appear with client/server and 594932785Speter@c seems unnecessary (redundant with "ls -l") so 595032785Speter@c perhaps it should be removed for non-client/server too? 595132785Speter@c FIXME: Need some examples. 595232785Speter@c FIXME: Working revision can also be something like 595332785Speter@c "-1.3" for a locally removed file. Not at all 595432785Speter@c self-explanatory (and it is possible that CVS should 595532785Speter@c be changed rather than documenting this). 595632785Speter 595732785Speter@c Would be nice to have an @example showing output 595832785Speter@c from cvs status, with comments showing the xref 595932785Speter@c where each part of the output is described. This 596032785Speter@c might fit in nicely if it is desirable to split this 596132785Speter@c node in two; one to introduce "cvs status" and one 596232785Speter@c to list each of the states. 596332785SpeterThe options to @code{status} are listed in 596432785Speter@ref{Invoking CVS}. For information on its @code{Sticky tag} 596532785Speterand @code{Sticky date} output, see @ref{Sticky tags}. 596632785SpeterFor information on its @code{Sticky options} output, 596732785Spetersee the @samp{-k} option in @ref{update options}. 596832785Speter 596932785SpeterYou can think of the @code{status} and @code{update} 597032785Spetercommands as somewhat complementary. You use 597132785Speter@code{update} to bring your files up to date, and you 597232785Spetercan use @code{status} to give you some idea of what an 597332785Speter@code{update} would do (of course, the state of the 597432785Speterrepository might change before you actually run 597532785Speter@code{update}). In fact, if you want a command to 597632785Speterdisplay file status in a more brief format than is 597732785Speterdisplayed by the @code{status} command, you can invoke 597832785Speter 597932785Speter@cindex update, to display file status 598032785Speter@example 598132785Speter$ cvs -n -q update 598232785Speter@end example 598332785Speter 598432785SpeterThe @samp{-n} option means to not actually do the 598532785Speterupdate, but merely to display statuses; the @samp{-q} 598632785Speteroption avoids printing the name of each directory. For 598732785Spetermore information on the @code{update} command, and 598832785Speterthese options, see @ref{Invoking CVS}. 598932785Speter 599032785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 599132785Speter@node Updating a file 599232785Speter@section Bringing a file up to date 599332785Speter@cindex Bringing a file up to date 599432785Speter@cindex Updating a file 599532785Speter@cindex Merging a file 599666525Speter@cindex Update, introduction 599732785Speter 5998175261SobrienWhen you want to update or merge a file, use the @code{cvs update -d} 599932785Spetercommand. For files that are not up to date this is roughly equivalent 600032785Speterto a @code{checkout} command: the newest revision of the file is 6001175261Sobrienextracted from the repository and put in your working directory. The 6002175261Sobrien@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} 6003175261Sobrienthat you wish it to create directories added by other developers. 600432785Speter 600532785SpeterYour modifications to a file are never lost when you 600632785Speteruse @code{update}. If no newer revision exists, 600732785Speterrunning @code{update} has no effect. If you have 600832785Speteredited the file, and a newer revision is available, 600932785Speter@sc{cvs} will merge all changes into your working copy. 601032785Speter 601132785SpeterFor instance, imagine that you checked out revision 1.4 and started 601232785Speterediting it. In the meantime someone else committed revision 1.5, and 601332785Spetershortly after that revision 1.6. If you run @code{update} on the file 601432785Speternow, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 601532785Speteryour file. 601632785Speter 601732785Speter@cindex Overlap 601832785SpeterIf any of the changes between 1.4 and 1.6 were made too 601932785Speterclose to any of the changes you have made, an 602032785Speter@dfn{overlap} occurs. In such cases a warning is 602132785Speterprinted, and the resulting file includes both 602232785Speterversions of the lines that overlap, delimited by 602332785Speterspecial markers. 602432785Speter@xref{update}, for a complete description of the 602532785Speter@code{update} command. 602632785Speter 602732785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 602832785Speter@node Conflicts example 602932785Speter@section Conflicts example 603032785Speter@cindex Merge, an example 603132785Speter@cindex Example of merge 603232785Speter@cindex driver.c (merge example) 603332785Speter 603432785SpeterSuppose revision 1.4 of @file{driver.c} contains this: 603532785Speter 603632785Speter@example 603732785Speter#include <stdio.h> 603832785Speter 603932785Spetervoid main() 604032785Speter@{ 604132785Speter parse(); 604232785Speter if (nerr == 0) 604332785Speter gencode(); 604432785Speter else 604532785Speter fprintf(stderr, "No code generated.\n"); 604632785Speter exit(nerr == 0 ? 0 : 1); 604732785Speter@} 604832785Speter@end example 604932785Speter 605032785Speter@noindent 605132785SpeterRevision 1.6 of @file{driver.c} contains this: 605232785Speter 605332785Speter@example 605432785Speter#include <stdio.h> 605532785Speter 605632785Speterint main(int argc, 605732785Speter char **argv) 605832785Speter@{ 605932785Speter parse(); 606032785Speter if (argc != 1) 606132785Speter @{ 606232785Speter fprintf(stderr, "tc: No args expected.\n"); 606332785Speter exit(1); 606432785Speter @} 606532785Speter if (nerr == 0) 606632785Speter gencode(); 606732785Speter else 606832785Speter fprintf(stderr, "No code generated.\n"); 606932785Speter exit(!!nerr); 607032785Speter@} 607132785Speter@end example 607232785Speter 607332785Speter@noindent 607432785SpeterYour working copy of @file{driver.c}, based on revision 607532785Speter1.4, contains this before you run @samp{cvs update}: 607632785Speter@c -- Really include "cvs"? 607732785Speter 607832785Speter@example 607932785Speter#include <stdlib.h> 608032785Speter#include <stdio.h> 608132785Speter 608232785Spetervoid main() 608332785Speter@{ 608432785Speter init_scanner(); 608532785Speter parse(); 608632785Speter if (nerr == 0) 608732785Speter gencode(); 608832785Speter else 608932785Speter fprintf(stderr, "No code generated.\n"); 609032785Speter exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 609132785Speter@} 609232785Speter@end example 609332785Speter 609432785Speter@noindent 609532785SpeterYou run @samp{cvs update}: 609632785Speter@c -- Really include "cvs"? 609732785Speter 609832785Speter@example 609932785Speter$ cvs update driver.c 610032785SpeterRCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 610132785Speterretrieving revision 1.4 610232785Speterretrieving revision 1.6 610332785SpeterMerging differences between 1.4 and 1.6 into driver.c 610432785Speterrcsmerge warning: overlaps during merge 610532785Spetercvs update: conflicts found in driver.c 610632785SpeterC driver.c 610732785Speter@end example 610832785Speter 610932785Speter@noindent 611032785Speter@cindex Conflicts (merge example) 611132785Speter@sc{cvs} tells you that there were some conflicts. 611232785SpeterYour original working file is saved unmodified in 611332785Speter@file{.#driver.c.1.4}. The new version of 611432785Speter@file{driver.c} contains this: 611532785Speter 611632785Speter@example 611732785Speter#include <stdlib.h> 611832785Speter#include <stdio.h> 611932785Speter 612032785Speterint main(int argc, 612132785Speter char **argv) 612232785Speter@{ 612332785Speter init_scanner(); 612432785Speter parse(); 612532785Speter if (argc != 1) 612632785Speter @{ 612732785Speter fprintf(stderr, "tc: No args expected.\n"); 612832785Speter exit(1); 612932785Speter @} 613032785Speter if (nerr == 0) 613132785Speter gencode(); 613232785Speter else 613332785Speter fprintf(stderr, "No code generated.\n"); 613432785Speter@asis{}<<<<<<< driver.c 613532785Speter exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 613632785Speter@asis{}======= 613732785Speter exit(!!nerr); 613832785Speter@asis{}>>>>>>> 1.6 613932785Speter@} 614032785Speter@end example 614132785Speter 614232785Speter@noindent 614332785Speter@cindex Markers, conflict 614432785Speter@cindex Conflict markers 614532785Speter@cindex <<<<<<< 614632785Speter@cindex >>>>>>> 614732785Speter@cindex ======= 614832785Speter 614932785SpeterNote how all non-overlapping modifications are incorporated in your working 615032785Spetercopy, and that the overlapping section is clearly marked with 615132785Speter@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 615232785Speter 615332785Speter@cindex Resolving a conflict 615432785Speter@cindex Conflict resolution 615532785SpeterYou resolve the conflict by editing the file, removing the markers and 615632785Speterthe erroneous line. Suppose you end up with this file: 615732785Speter@c -- Add xref to the pcl-cvs manual when it talks 615832785Speter@c -- about this. 615932785Speter@example 616032785Speter#include <stdlib.h> 616132785Speter#include <stdio.h> 616232785Speter 616332785Speterint main(int argc, 616432785Speter char **argv) 616532785Speter@{ 616632785Speter init_scanner(); 616732785Speter parse(); 616832785Speter if (argc != 1) 616932785Speter @{ 617032785Speter fprintf(stderr, "tc: No args expected.\n"); 617132785Speter exit(1); 617232785Speter @} 617332785Speter if (nerr == 0) 617432785Speter gencode(); 617532785Speter else 617632785Speter fprintf(stderr, "No code generated.\n"); 617732785Speter exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 617832785Speter@} 617932785Speter@end example 618032785Speter 618132785Speter@noindent 618232785SpeterYou can now go ahead and commit this as revision 1.7. 618332785Speter 618432785Speter@example 618532785Speter$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 618632785SpeterChecking in driver.c; 618732785Speter/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 618832785Speternew revision: 1.7; previous revision: 1.6 618932785Speterdone 619032785Speter@end example 619132785Speter 619232785SpeterFor your protection, @sc{cvs} will refuse to check in a 619332785Speterfile if a conflict occurred and you have not resolved 619432785Speterthe conflict. Currently to resolve a conflict, you 619532785Spetermust change the timestamp on the file. In previous 619632785Speterversions of @sc{cvs}, you also needed to 619732785Speterinsure that the file contains no conflict markers. 619832785SpeterBecause 619932785Speteryour file may legitimately contain conflict markers (that 620032785Speteris, occurrences of @samp{>>>>>>> } at the start of a 620132785Speterline that don't mark a conflict), the current 620232785Speterversion of @sc{cvs} will print a warning and proceed to 620332785Spetercheck in the file. 620432785Speter@c The old behavior was really icky; the only way out 620532785Speter@c was to start hacking on 620632785Speter@c the @code{CVS/Entries} file or other such workarounds. 620744852Speter@c 620832785Speter@c If the timestamp thing isn't considered nice enough, 620932785Speter@c maybe there should be a "cvs resolved" command 621032785Speter@c which clears the conflict indication. For a nice user 621132785Speter@c interface, this should be invoked by an interactive 621232785Speter@c merge tool like emerge rather than by the user 621332785Speter@c directly--such a tool can verify that the user has 621432785Speter@c really dealt with each conflict. 621532785Speter 621632785Speter@cindex emerge 621732785SpeterIf you use release 1.04 or later of pcl-cvs (a @sc{gnu} 621832785SpeterEmacs front-end for @sc{cvs}) you can use an Emacs 621932785Speterpackage called emerge to help you resolve conflicts. 622032785SpeterSee the documentation for pcl-cvs. 622132785Speter 622232785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 622332785Speter@node Informing others 622432785Speter@section Informing others about commits 622532785Speter@cindex Informing others 622632785Speter@cindex Spreading information 622732785Speter@cindex Mail, automatic mail on commit 622832785Speter 622932785SpeterIt is often useful to inform others when you commit a 6230177391Sobriennew revision of a file. The @file{loginfo} file can be 6231177391Sobrienused to automate this process. 623232785Speter@xref{loginfo}. You can use these features of @sc{cvs} 623332785Speterto, for instance, instruct @sc{cvs} to mail a 623432785Spetermessage to all developers, or post a message to a local 623532785Speternewsgroup. 623632785Speter@c -- More text would be nice here. 623732785Speter 623832785Speter@node Concurrency 623932785Speter@section Several developers simultaneously attempting to run CVS 624032785Speter 624166525Speter@cindex Locks, cvs, introduction 624232785Speter@c For a discussion of *why* CVS creates locks, see 624332785Speter@c the comment at the start of src/lock.c 624432785SpeterIf several developers try to run @sc{cvs} at the same 624532785Spetertime, one may get the following message: 624632785Speter 624732785Speter@example 624832785Speter[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 624932785Speter@end example 625032785Speter 625144852Speter@cindex #cvs.rfl, removing 625244852Speter@cindex #cvs.wfl, removing 625344852Speter@cindex #cvs.lock, removing 625432785Speter@sc{cvs} will try again every 30 seconds, and either 625532785Spetercontinue with the operation or print the message again, 625632785Speterif it still needs to wait. If a lock seems to stick 625732785Speteraround for an undue amount of time, find the person 625832785Speterholding the lock and ask them about the cvs command 625932785Speterthey are running. If they aren't running a cvs 626032785Spetercommand, look in the repository directory mentioned in 626132785Speterthe message and remove files which they own whose names 626244852Speterstart with @file{#cvs.rfl}, 626344852Speter@file{#cvs.wfl}, or @file{#cvs.lock}. 626432785Speter 626532785SpeterNote that these locks are to protect @sc{cvs}'s 626632785Speterinternal data structures and have no relationship to 626732785Speterthe word @dfn{lock} in the sense used by 626832785Speter@sc{rcs}---which refers to reserved checkouts 626932785Speter(@pxref{Multiple developers}). 627032785Speter 627132785SpeterAny number of people can be reading from a given 627232785Speterrepository at a time; only when someone is writing do 627332785Speterthe locks prevent other people from reading or writing. 627432785Speter 627532785Speter@cindex Atomic transactions, lack of 627632785Speter@cindex Transactions, atomic, lack of 627732785Speter@c the following talks about what one might call commit/update 627832785Speter@c atomicity. 627932785Speter@c Probably also should say something about 628032785Speter@c commit/commit atomicity, that is, "An update will 628132785Speter@c not get partial versions of more than one commit". 628232785Speter@c CVS currently has this property and I guess we can 628332785Speter@c make it a documented feature. 628432785Speter@c For example one person commits 628532785Speter@c a/one.c and b/four.c and another commits a/two.c and 628632785Speter@c b/three.c. Then an update cannot get the new a/one.c 628732785Speter@c and a/two.c and the old b/four.c and b/three.c. 6288102840SpeterOne might hope for the following property: 628932785Speter 6290102840Speter@quotation 629132785SpeterIf someone commits some changes in one cvs command, 629232785Speterthen an update by someone else will either get all the 629332785Speterchanges, or none of them. 6294102840Speter@end quotation 629532785Speter 6296102840Speter@noindent 629732785Speterbut @sc{cvs} does @emph{not} have this property. For 629832785Speterexample, given the files 629932785Speter 630032785Speter@example 630132785Spetera/one.c 630232785Spetera/two.c 630332785Speterb/three.c 630432785Speterb/four.c 630532785Speter@end example 630632785Speter 6307102840Speter@noindent 630832785Speterif someone runs 630932785Speter 631032785Speter@example 631132785Spetercvs ci a/two.c b/three.c 631232785Speter@end example 631332785Speter 6314102840Speter@noindent 631532785Speterand someone else runs @code{cvs update} at the same 631632785Spetertime, the person running @code{update} might get only 631732785Speterthe change to @file{b/three.c} and not the change to 631832785Speter@file{a/two.c}. 631932785Speter 632032785Speter@node Watches 632132785Speter@section Mechanisms to track who is editing files 632232785Speter@cindex Watches 632332785Speter 632432785SpeterFor many groups, use of @sc{cvs} in its default mode is 632532785Speterperfectly satisfactory. Users may sometimes go to 632632785Spetercheck in a modification only to find that another 632732785Spetermodification has intervened, but they deal with it and 632832785Speterproceed with their check in. Other groups prefer to be 632932785Speterable to know who is editing what files, so that if two 633032785Speterpeople try to edit the same file they can choose to 633132785Spetertalk about who is doing what when rather than be 633232785Spetersurprised at check in time. The features in this 633332785Spetersection allow such coordination, while retaining the 633432785Speterability of two developers to edit the same file at the 633532785Spetersame time. 633632785Speter 633732785Speter@c Some people might ask why CVS does not enforce the 633832785Speter@c rule on chmod, by requiring a cvs edit before a cvs 633932785Speter@c commit. The main reason is that it could always be 634032785Speter@c circumvented--one could edit the file, and 634132785Speter@c then when ready to check it in, do the cvs edit and put 634232785Speter@c in the new contents and do the cvs commit. One 634332785Speter@c implementation note: if we _do_ want to have cvs commit 634432785Speter@c require a cvs edit, we should store the state on 634532785Speter@c whether the cvs edit has occurred in the working 634632785Speter@c directory, rather than having the server try to keep 634732785Speter@c track of what working directories exist. 634832785Speter@c FIXME: should the above discussion be part of the 634932785Speter@c manual proper, somewhere, not just in a comment? 635032785SpeterFor maximum benefit developers should use @code{cvs 635132785Speteredit} (not @code{chmod}) to make files read-write to 635232785Speteredit them, and @code{cvs release} (not @code{rm}) to 635332785Speterdiscard a working directory which is no longer in use, 635432785Speterbut @sc{cvs} is not able to enforce this behavior. 635532785Speter 635632785Speter@c I'm a little dissatisfied with this presentation, 635732785Speter@c because "watch on"/"edit"/"editors" are one set of 635832785Speter@c functionality, and "watch add"/"watchers" is another 635932785Speter@c which is somewhat orthogonal even though they interact in 636032785Speter@c various ways. But I think it might be 636132785Speter@c confusing to describe them separately (e.g. "watch 636232785Speter@c add" with loginfo). I don't know. 636332785Speter 636432785Speter@menu 636532785Speter* Setting a watch:: Telling CVS to watch certain files 636632785Speter* Getting Notified:: Telling CVS to notify you 636732785Speter* Editing files:: How to edit a file which is being watched 636832785Speter* Watch information:: Information about who is watching and editing 636932785Speter* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 637032785Speter@end menu 637132785Speter 637232785Speter@node Setting a watch 637332785Speter@subsection Telling CVS to watch certain files 637432785Speter 637532785SpeterTo enable the watch features, you first specify that 637632785Spetercertain files are to be watched. 637732785Speter 637832785Speter@cindex watch on (subcommand) 6379128266Speter@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 638032785Speter 638166525Speter@cindex Read-only files, and watches 638232785SpeterSpecify that developers should run @code{cvs edit} 638381404Speterbefore editing @var{files}. @sc{cvs} will create working 638432785Spetercopies of @var{files} read-only, to remind developers 638532785Speterto run the @code{cvs edit} command before working on 638632785Speterthem. 638732785Speter 638881404SpeterIf @var{files} includes the name of a directory, @sc{cvs} 638932785Speterarranges to watch all files added to the corresponding 639032785Speterrepository directory, and sets a default for files 639132785Speteradded in the future; this allows the user to set 639232785Speternotification policies on a per-directory basis. The 639332785Spetercontents of the directory are processed recursively, 639432785Speterunless the @code{-l} option is given. 639532785SpeterThe @code{-R} option can be used to force recursion if the @code{-l} 639632785Speteroption is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 639732785Speter 639832785SpeterIf @var{files} is omitted, it defaults to the current directory. 639932785Speter 640032785Speter@cindex watch off (subcommand) 640132785Speter@end deffn 640232785Speter 6403128266Speter@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 640432785Speter 640566525SpeterDo not create @var{files} read-only on checkout; thus, 640666525Speterdevelopers will not be reminded to use @code{cvs edit} 640766525Speterand @code{cvs unedit}. 640866525Speter@ignore 640981404Speter@sc{cvs} will check out @var{files} 641066525Speterread-write as usual, unless other permissions override 641166525Speterdue to the @code{PreservePermissions} option being 641266525Speterenabled in the @file{config} administrative file 641366525Speter(@pxref{Special Files}, @pxref{config}) 641466525Speter@end ignore 641532785Speter 641632785SpeterThe @var{files} and options are processed as for @code{cvs 641732785Speterwatch on}. 641832785Speter 641932785Speter@end deffn 642032785Speter 642132785Speter@node Getting Notified 642232785Speter@subsection Telling CVS to notify you 642332785Speter 642432785SpeterYou can tell @sc{cvs} that you want to receive 642532785Speternotifications about various actions taken on a file. 642632785SpeterYou can do this without using @code{cvs watch on} for 642732785Speterthe file, but generally you will want to use @code{cvs 6428102840Speterwatch on}, to remind developers to use the @code{cvs edit} 642932785Spetercommand. 643032785Speter 643132785Speter@cindex watch add (subcommand) 6432128266Speter@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 643332785Speter 643432785SpeterAdd the current user to the list of people to receive notification of 643532785Speterwork done on @var{files}. 643632785Speter 643781404SpeterThe @code{-a} option specifies what kinds of events @sc{cvs} should notify 643832785Speterthe user about. @var{action} is one of the following: 643932785Speter 644032785Speter@table @code 644132785Speter 644232785Speter@item edit 644332785SpeterAnother user has applied the @code{cvs edit} command (described 6444102840Speterbelow) to a watched file. 644532785Speter 6446102840Speter@item commit 6447102840SpeterAnother user has committed changes to one of the named @var{files}. 6448102840Speter 644932785Speter@item unedit 6450102840SpeterAnother user has abandoned editing a file (other than by committing changes). 6451102840SpeterThey can do this in several ways, by: 645232785Speter 6453102840Speter@itemize @bullet 645432785Speter 6455102840Speter@item 6456102840Speterapplying the @code{cvs unedit} command (described below) to the file 6457102840Speter 6458102840Speter@item 6459102840Speterapplying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6460102840Speter(or recursively to a directory more than one level up) 6461102840Speter 6462102840Speter@item 6463102840Speterdeleting the file and allowing @code{cvs update} to recreate it 6464102840Speter 6465102840Speter@end itemize 6466102840Speter 646732785Speter@item all 646832785SpeterAll of the above. 646932785Speter 647032785Speter@item none 647132785SpeterNone of the above. (This is useful with @code{cvs edit}, 647232785Speterdescribed below.) 647332785Speter 647432785Speter@end table 647532785Speter 647632785SpeterThe @code{-a} option may appear more than once, or not at all. If 647732785Speteromitted, the action defaults to @code{all}. 647832785Speter 6479102840SpeterThe @var{files} and options are processed as for 6480102840Speter@code{cvs watch on}. 648132785Speter 648232785Speter@end deffn 648332785Speter 648432785Speter 648532785Speter@cindex watch remove (subcommand) 6486128266Speter@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 648732785Speter 648832785SpeterRemove a notification request established using @code{cvs watch add}; 648932785Speterthe arguments are the same. If the @code{-a} option is present, only 649032785Speterwatches for the specified actions are removed. 649132785Speter 649232785Speter@end deffn 649332785Speter 649432785Speter@cindex notify (admin file) 649532785SpeterWhen the conditions exist for notification, @sc{cvs} 649632785Spetercalls the @file{notify} administrative file. Edit 649732785Speter@file{notify} as one edits the other administrative 649832785Speterfiles (@pxref{Intro administrative files}). This 649932785Speterfile follows the usual conventions for administrative 650032785Speterfiles (@pxref{syntax}), where each line is a regular 650132785Speterexpression followed by a command to execute. The 650254427Spetercommand should contain a single occurrence of @samp{%s} 650332785Speterwhich will be replaced by the user to notify; the rest 650432785Speterof the information regarding the notification will be 650532785Spetersupplied to the command on standard input. The 650632785Speterstandard thing to put in the @code{notify} file is the 650732785Spetersingle line: 650832785Speter 650932785Speter@example 651066525SpeterALL mail %s -s "CVS notification" 651132785Speter@end example 651232785Speter 6513102840Speter@noindent 651432785SpeterThis causes users to be notified by electronic mail. 651532785Speter@c FIXME: should it be this hard to set up this 651632785Speter@c behavior (and the result when one fails to do so, 651732785Speter@c silent failure to notify, so non-obvious)? Should 651832785Speter@c CVS give a warning if no line in notify matches (and 651932785Speter@c document the use of "DEFAULT :" for the case where 652032785Speter@c skipping the notification is indeed desired)? 652132785Speter 652232785Speter@cindex users (admin file) 652332785SpeterNote that if you set this up in the straightforward 652432785Speterway, users receive notifications on the server machine. 652532785SpeterOne could of course write a @file{notify} script which 652632785Speterdirected notifications elsewhere, but to make this 652732785Spetereasy, @sc{cvs} allows you to associate a notification 652832785Speteraddress for each user. To do so create a file 652932785Speter@file{users} in @file{CVSROOT} with a line for each 653032785Speteruser in the format @var{user}:@var{value}. Then 653132785Speterinstead of passing the name of the user to be notified 653232785Speterto @file{notify}, @sc{cvs} will pass the @var{value} 653332785Speter(normally an email address on some other machine). 653432785Speter 653566525Speter@sc{cvs} does not notify you for your own changes. 653632785SpeterCurrently this check is done based on whether the user 653732785Spetername of the person taking the action which triggers 653832785Speternotification matches the user name of the person 653932785Spetergetting notification. In fact, in general, the watches 654032785Speterfeatures only track one edit by each user. It probably 654132785Speterwould be more useful if watches tracked each working 654232785Speterdirectory separately, so this behavior might be worth 654332785Speterchanging. 654432785Speter@c "behavior might be worth changing" is an effort to 654532785Speter@c point to future directions while also not promising 654632785Speter@c that "they" (as in "why don't they fix CVS to....") 654732785Speter@c will do this. 654832785Speter@c one implementation issue is identifying whether a 654932785Speter@c working directory is same or different. Comparing 655032785Speter@c pathnames/hostnames is hopeless, but having the server 655132785Speter@c supply a serial number which the client stores in the 655232785Speter@c CVS directory as a magic cookie should work. 655332785Speter 655432785Speter@node Editing files 655532785Speter@subsection How to edit a file which is being watched 655632785Speter 655766525Speter@cindex Checkout, as term for getting ready to edit 655832785SpeterSince a file which is being watched is checked out 655932785Speterread-only, you cannot simply edit it. To make it 656032785Speterread-write, and inform others that you are planning to 656132785Speteredit it, use the @code{cvs edit} command. Some systems 656232785Spetercall this a @dfn{checkout}, but @sc{cvs} uses that term 656332785Speterfor obtaining a copy of the sources (@pxref{Getting the 656432785Spetersource}), an operation which those systems call a 656532785Speter@dfn{get} or a @dfn{fetch}. 656632785Speter@c Issue to think about: should we transition CVS 656732785Speter@c towards the "get" terminology? "cvs get" is already a 656832785Speter@c synonym for "cvs checkout" and that section of the 656932785Speter@c manual refers to "Getting the source". If this is 657032785Speter@c done, needs to be done gingerly (for example, we should 657132785Speter@c still accept "checkout" in .cvsrc files indefinitely 657232785Speter@c even if the CVS's messages are changed from "cvs checkout: " 657332785Speter@c to "cvs get: "). 657432785Speter@c There is a concern about whether "get" is not as 657532785Speter@c good for novices because it is a more general term 657632785Speter@c than "checkout" (and thus arguably harder to assign 657732785Speter@c a technical meaning for). 657832785Speter 657932785Speter@cindex edit (subcommand) 6580128266Speter@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 658132785Speter 658281404SpeterPrepare to edit the working files @var{files}. @sc{cvs} makes the 658332785Speter@var{files} read-write, and notifies users who have requested 658432785Speter@code{edit} notification for any of @var{files}. 658532785Speter 6586128266SpeterThe @code{cvs edit} command accepts the same options as the 658732785Speter@code{cvs watch add} command, and establishes a temporary watch for the 658881404Speteruser on @var{files}; @sc{cvs} will remove the watch when @var{files} are 658932785Speter@code{unedit}ed or @code{commit}ted. If the user does not wish to 659032785Speterreceive notifications, she should specify @code{-a none}. 659132785Speter 6592128266SpeterThe @var{files} and the options are processed as for the @code{cvs 659332785Speterwatch} commands. 659432785Speter 659566525Speter@ignore 6596128266Speter@strong{Caution: If the @code{PreservePermissions} 659734461Speteroption is enabled in the repository (@pxref{config}), 659881404Speter@sc{cvs} will not change the permissions on any of the 659934461Speter@var{files}. The reason for this change is to ensure 660034461Speterthat using @samp{cvs edit} does not interfere with the 660181404Speterability to store file permissions in the @sc{cvs} 6602128266Speterrepository.} 660366525Speter@end ignore 660434461Speter 660532785Speter@end deffn 660632785Speter 660732785SpeterNormally when you are done with a set of changes, you 660832785Speteruse the @code{cvs commit} command, which checks in your 660932785Speterchanges and returns the watched files to their usual 661032785Speterread-only state. But if you instead decide to abandon 661132785Speteryour changes, or not to make any changes, you can use 661232785Speterthe @code{cvs unedit} command. 661332785Speter 661432785Speter@cindex unedit (subcommand) 661566525Speter@cindex Abandoning work 661666525Speter@cindex Reverting to repository version 6617128266Speter@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 661832785Speter 661932785SpeterAbandon work on the working files @var{files}, and revert them to the 662081404Speterrepository versions on which they are based. @sc{cvs} makes those 662132785Speter@var{files} read-only for which users have requested notification using 662281404Speter@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 662332785Speternotification for any of @var{files}. 662432785Speter 662532785SpeterThe @var{files} and options are processed as for the 662632785Speter@code{cvs watch} commands. 662732785Speter 662832785SpeterIf watches are not in use, the @code{unedit} command 662932785Speterprobably does not work, and the way to revert to the 6630102840Speterrepository version is with the command @code{cvs update -C file} 6631102840Speter(@pxref{update}). 6632102840SpeterThe meaning is 6633102840Speternot precisely the same; the latter may also 663432785Speterbring in some changes which have been made in the 663532785Speterrepository since the last time you updated. 663632785Speter@c It would be a useful enhancement to CVS to make 663732785Speter@c unedit work in the non-watch case as well. 663832785Speter@end deffn 663932785Speter 664032785SpeterWhen using client/server @sc{cvs}, you can use the 664132785Speter@code{cvs edit} and @code{cvs unedit} commands even if 664254427Speter@sc{cvs} is unable to successfully communicate with the 664332785Speterserver; the notifications will be sent upon the next 664432785Spetersuccessful @sc{cvs} command. 664532785Speter 664632785Speter@node Watch information 664732785Speter@subsection Information about who is watching and editing 664832785Speter 664932785Speter@cindex watchers (subcommand) 6650128266Speter@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 665132785Speter 665232785SpeterList the users currently watching changes to @var{files}. The report 665332785Speterincludes the files being watched, and the mail address of each watcher. 665432785Speter 665532785SpeterThe @var{files} and options are processed as for the 665632785Speter@code{cvs watch} commands. 665732785Speter 665832785Speter@end deffn 665932785Speter 666032785Speter 666132785Speter@cindex editors (subcommand) 6662128266Speter@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 666332785Speter 666432785SpeterList the users currently working on @var{files}. The report 666532785Speterincludes the mail address of each user, the time when the user began 666632785Speterworking with the file, and the host and path of the working directory 666732785Spetercontaining the file. 666832785Speter 666932785SpeterThe @var{files} and options are processed as for the 667032785Speter@code{cvs watch} commands. 667132785Speter 667232785Speter@end deffn 667332785Speter 667432785Speter@node Watches Compatibility 667532785Speter@subsection Using watches with old versions of CVS 667632785Speter 667732785Speter@cindex CVS 1.6, and watches 667832785SpeterIf you use the watch features on a repository, it 667932785Spetercreates @file{CVS} directories in the repository and 668032785Speterstores the information about watches in that directory. 668132785SpeterIf you attempt to use @sc{cvs} 1.6 or earlier with the 668232785Speterrepository, you get an error message such as the 668332785Speterfollowing (all on one line): 668432785Speter 668532785Speter@example 668632785Spetercvs update: cannot open CVS/Entries for reading: 668732785SpeterNo such file or directory 668832785Speter@end example 668932785Speter 6690102840Speter@noindent 669132785Speterand your operation will likely be aborted. To use the 669232785Speterwatch features, you must upgrade all copies of @sc{cvs} 669332785Speterwhich use that repository in local or server mode. If 669432785Speteryou cannot upgrade, use the @code{watch off} and 669532785Speter@code{watch remove} commands to remove all watches, and 669632785Speterthat will restore the repository to a state which 669732785Speter@sc{cvs} 1.6 can cope with. 669832785Speter 669932785Speter@node Choosing a model 670032785Speter@section Choosing between reserved or unreserved checkouts 670166525Speter@cindex Choosing, reserved or unreserved checkouts 670232785Speter 670332785SpeterReserved and unreserved checkouts each have pros and 670432785Spetercons. Let it be said that a lot of this is a matter of 670532785Speteropinion or what works given different groups' working 670632785Speterstyles, but here is a brief description of some of the 670732785Speterissues. There are many ways to organize a team of 670832785Speterdevelopers. @sc{cvs} does not try to enforce a certain 670932785Speterorganization. It is a tool that can be used in several 671032785Speterways. 671132785Speter 671232785SpeterReserved checkouts can be very counter-productive. If 671332785Spetertwo persons want to edit different parts of a file, 671432785Speterthere may be no reason to prevent either of them from 671532785Speterdoing so. Also, it is common for someone to take out a 671632785Speterlock on a file, because they are planning to edit it, 671732785Speterbut then forget to release the lock. 671832785Speter 671932785Speter@c "many groups"? specifics? cites to papers on this? 672032785Speter@c some way to weasel-word it a bit more so we don't 672132785Speter@c need facts :-)? 672232785SpeterPeople, especially people who are familiar with 672332785Speterreserved checkouts, often wonder how often conflicts 672432785Speteroccur if unreserved checkouts are used, and how 672532785Speterdifficult they are to resolve. The experience with 672632785Spetermany groups is that they occur rarely and usually are 672732785Speterrelatively straightforward to resolve. 672832785Speter 672932785SpeterThe rarity of serious conflicts may be surprising, until one realizes 673032785Speterthat they occur only when two developers disagree on the proper design 673132785Speterfor a given section of code; such a disagreement suggests that the 673232785Speterteam has not been communicating properly in the first place. In order 673332785Speterto collaborate under @emph{any} source management regimen, developers 673432785Spetermust agree on the general design of the system; given this agreement, 673532785Speteroverlapping changes are usually straightforward to merge. 673632785Speter 673732785SpeterIn some cases unreserved checkouts are clearly 673832785Speterinappropriate. If no merge tool exists for the kind of 673932785Speterfile you are managing (for example word processor files 674032785Speteror files edited by Computer Aided Design programs), and 674132785Speterit is not desirable to change to a program which uses a 674232785Spetermergeable data format, then resolving conflicts is 674332785Spetergoing to be unpleasant enough that you generally will 674432785Speterbe better off to simply avoid the conflicts instead, by 674532785Speterusing reserved checkouts. 674632785Speter 674732785SpeterThe watches features described above in @ref{Watches} 674832785Spetercan be considered to be an intermediate model between 674932785Speterreserved checkouts and unreserved checkouts. When you 675032785Spetergo to edit a file, it is possible to find out who else 675132785Speteris editing it. And rather than having the system 675232785Spetersimply forbid both people editing the file, it can tell 675332785Speteryou what the situation is and let you figure out 675432785Speterwhether it is a problem in that particular case or not. 675532785SpeterTherefore, for some groups it can be considered the 675632785Speterbest of both the reserved checkout and unreserved 675732785Spetercheckout worlds. 675832785Speter 675932785Speter@c --------------------------------------------------------------------- 676032785Speter@node Revision management 676132785Speter@chapter Revision management 676232785Speter@cindex Revision management 676332785Speter 676432785Speter@c -- This chapter could be expanded a lot. 676532785Speter@c -- Experiences are very welcome! 676632785Speter 676732785SpeterIf you have read this far, you probably have a pretty 676832785Spetergood grasp on what @sc{cvs} can do for you. This 676932785Speterchapter talks a little about things that you still have 677032785Speterto decide. 677132785Speter 677232785SpeterIf you are doing development on your own using @sc{cvs} 677332785Speteryou could probably skip this chapter. The questions 677432785Speterthis chapter takes up become more important when more 677532785Speterthan one person is working in a repository. 677632785Speter 677732785Speter@menu 677832785Speter* When to commit:: Some discussion on the subject 677932785Speter@end menu 678032785Speter 678132785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 678232785Speter@node When to commit 678332785Speter@section When to commit? 678432785Speter@cindex When to commit 6785107484Speter@cindex Committing, when to 678632785Speter@cindex Policy 678732785Speter 678832785SpeterYour group should decide which policy to use regarding 678932785Spetercommits. Several policies are possible, and as your 679032785Speterexperience with @sc{cvs} grows you will probably find 679132785Speterout what works for you. 679232785Speter 679332785SpeterIf you commit files too quickly you might commit files 679432785Speterthat do not even compile. If your partner updates his 679532785Speterworking sources to include your buggy file, he will be 679632785Speterunable to compile the code. On the other hand, other 679732785Speterpersons will not be able to benefit from the 679832785Speterimprovements you make to the code if you commit very 679932785Speterseldom, and conflicts will probably be more common. 680032785Speter 680132785SpeterIt is common to only commit files after making sure 680232785Speterthat they can be compiled. Some sites require that the 680332785Speterfiles pass a test suite. Policies like this can be 680432785Speterenforced using the commitinfo file 680532785Speter(@pxref{commitinfo}), but you should think twice before 680632785Speteryou enforce such a convention. By making the 680732785Speterdevelopment environment too controlled it might become 680832785Spetertoo regimented and thus counter-productive to the real 680932785Spetergoal, which is to get software written. 681032785Speter 681132785Speter@c --------------------------------------------------------------------- 681217721Speter@node Keyword substitution 681317721Speter@chapter Keyword substitution 681417721Speter@cindex Keyword substitution 681517721Speter@cindex Keyword expansion 681617721Speter@cindex Identifying files 681717721Speter 681817721Speter@comment Be careful when editing this chapter. 681917721Speter@comment Remember that this file is kept under 682017721Speter@comment version control, so we must not accidentally 682117721Speter@comment include a valid keyword in the running text. 682217721Speter 682354427SpeterAs long as you edit source files inside a working 682454427Speterdirectory you can always find out the state of 682517721Speteryour files via @samp{cvs status} and @samp{cvs log}. 682617721SpeterBut as soon as you export the files from your 682717721Speterdevelopment environment it becomes harder to identify 682817721Speterwhich revisions they are. 682917721Speter 683081404Speter@sc{cvs} can use a mechanism known as @dfn{keyword 683117721Spetersubstitution} (or @dfn{keyword expansion}) to help 683217721Speteridentifying the files. Embedded strings of the form 683317721Speter@code{$@var{keyword}$} and 683417721Speter@code{$@var{keyword}:@dots{}$} in a file are replaced 683517721Speterwith strings of the form 683617721Speter@code{$@var{keyword}:@var{value}$} whenever you obtain 683717721Spetera new revision of the file. 683817721Speter 683917721Speter@menu 684026065Speter* Keyword list:: Keywords 684117721Speter* Using keywords:: Using keywords 684217721Speter* Avoiding substitution:: Avoiding substitution 684317721Speter* Substitution modes:: Substitution modes 6844130303Speter* Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. 684517721Speter@end menu 684617721Speter 684717721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 684817721Speter@node Keyword list 684932785Speter@section Keyword List 685032785Speter@cindex Keyword List 685117721Speter 685244852Speter@c FIXME: need some kind of example here I think, 685326065Speter@c perhaps in a 685426065Speter@c "Keyword intro" node. The intro in the "Keyword 685526065Speter@c substitution" node itself seems OK, but to launch 685626065Speter@c into a list of the keywords somehow seems too abrupt. 685717721Speter 685826065SpeterThis is a list of the keywords: 685926065Speter 686017721Speter@table @code 686117721Speter@cindex Author keyword 6862128266Speter@item $@splitrcskeyword{Author}$ 686317721SpeterThe login name of the user who checked in the revision. 686417721Speter 686517721Speter@cindex Date keyword 6866128266Speter@item $@splitrcskeyword{Date}$ 686717721SpeterThe date and time (UTC) the revision was checked in. 686817721Speter 686917721Speter@cindex Header keyword 6870128266Speter@item $@splitrcskeyword{Header}$ 687117721SpeterA standard header containing the full pathname of the 687217721Speter@sc{rcs} file, the revision number, the date (UTC), the 687317721Speterauthor, the state, and the locker (if locked). Files 687417721Speterwill normally never be locked when you use @sc{cvs}. 687517721Speter 687617721Speter@cindex Id keyword 6877128266Speter@item $@splitrcskeyword{Id}$ 6878128266SpeterSame as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} 687917721Speterfilename is without a path. 688017721Speter 688125839Speter@cindex Name keyword 6882128266Speter@item $@splitrcskeyword{Name}$ 688354427SpeterTag name used to check out this file. The keyword is 688454427Speterexpanded only if one checks out with an explicit tag 688554427Spetername. For example, when running the command @code{cvs 688654427Speterco -r first}, the keyword expands to @samp{Name: first}. 688725839Speter 688817721Speter@cindex Locker keyword 6889128266Speter@item $@splitrcskeyword{Locker}$ 689017721SpeterThe login name of the user who locked the revision 689154427Speter(empty if not locked, which is the normal case unless 689254427Speter@code{cvs admin -l} is in use). 689317721Speter 689417721Speter@cindex Log keyword 6895128266Speter@item $@splitrcskeyword{Log}$ 689617721SpeterThe log message supplied during commit, preceded by a 689717721Speterheader containing the @sc{rcs} filename, the revision 689817721Speternumber, the author, and the date (UTC). Existing log 689917721Spetermessages are @emph{not} replaced. Instead, the new log 6900130303Spetermessage is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}. 690132785SpeterEach new line is prefixed with the same string which 690232785Speterprecedes the @code{$Log} keyword. For example, if the 6903102840Speterfile contains: 690432785Speter 690532785Speter@example 690632785Speter /* Here is what people have been up to: 690732785Speter * 6908130303Speter * $@splitrcskeyword{Log}: frob.c,v $ 690932785Speter * Revision 1.1 1997/01/03 14:23:51 joe 691032785Speter * Add the superfrobnicate option 691144852Speter * 691232785Speter */ 691332785Speter@end example 691432785Speter 691532785Speter@noindent 691632785Speterthen additional lines which are added when expanding 691732785Speterthe @code{$Log} keyword will be preceded by @samp{ * }. 691832785SpeterUnlike previous versions of @sc{cvs} and @sc{rcs}, the 691932785Speter@dfn{comment leader} from the @sc{rcs} file is not used. 692032785SpeterThe @code{$Log} keyword is useful for 692117721Speteraccumulating a complete change log in a source file, 692217721Speterbut for several reasons it can be problematic. 692317721Speter@xref{Log keyword}. 692417721Speter 692517721Speter@cindex RCSfile keyword 6926128266Speter@item $@splitrcskeyword{RCSfile}$ 692717721SpeterThe name of the RCS file without a path. 692817721Speter 692917721Speter@cindex Revision keyword 6930128266Speter@item $@splitrcskeyword{Revision}$ 693117721SpeterThe revision number assigned to the revision. 693217721Speter 693317721Speter@cindex Source keyword 6934128266Speter@item $@splitrcskeyword{Source}$ 693517721SpeterThe full pathname of the RCS file. 693617721Speter 693717721Speter@cindex State keyword 6938128266Speter@item $@splitrcskeyword{State}$ 693917721SpeterThe state assigned to the revision. States can be 694032785Speterassigned with @code{cvs admin -s}---see @ref{admin options}. 694117721Speter 694217721Speter@end table 694317721Speter 694417721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 694517721Speter@node Using keywords 694617721Speter@section Using keywords 694717721Speter 694817721SpeterTo include a keyword string you simply include the 6949128266Speterrelevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the 6950130303Speterfile, and commit the file. @sc{cvs} will automatically (Or, 6951130303Spetermore accurately, as part of the update run that 6952130303Speterautomatically happens after a commit.) 695317721Speterexpand the string as part of the commit operation. 695417721Speter 6955130303SpeterIt is common to embed the @code{$@splitrcskeyword{Id}$} string in 695644852Speterthe source files so that it gets passed through to 695744852Spetergenerated files. For example, if you are managing 695844852Spetercomputer program source code, you might include a 695944852Spetervariable which is initialized to contain that string. 696044852SpeterOr some C compilers may provide a @code{#pragma ident} 696144852Speterdirective. Or a document management system might 696244852Speterprovide a way to pass a string through to generated 696344852Speterfiles. 696417721Speter 696544852Speter@c Would be nice to give an example, but doing this in 696644852Speter@c portable C is not possible and the problem with 696744852Speter@c picking any one language (VMS HELP files, Ada, 696844852Speter@c troff, whatever) is that people use CVS for all 696944852Speter@c kinds of files. 697017721Speter 697117721Speter@cindex Ident (shell command) 697217721SpeterThe @code{ident} command (which is part of the @sc{rcs} 697317721Speterpackage) can be used to extract keywords and their 697417721Spetervalues from a file. This can be handy for text files, 697517721Speterbut it is even more useful for extracting keywords from 697617721Speterbinary files. 697717721Speter 697817721Speter@example 697917721Speter$ ident samp.c 698017721Spetersamp.c: 6981130303Speter $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 698217721Speter$ gcc samp.c 698317721Speter$ ident a.out 698417721Spetera.out: 6985130303Speter $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 698617721Speter@end example 698717721Speter 698817721Speter@cindex What (shell command) 698917721SpeterS@sc{ccs} is another popular revision control system. 699017721SpeterIt has a command, @code{what}, which is very similar to 699117721Speter@code{ident} and used for the same purpose. Many sites 699217721Speterwithout @sc{rcs} have @sc{sccs}. Since @code{what} 699317721Speterlooks for the character sequence @code{@@(#)} it is 699417721Spetereasy to include keywords that are detected by either 699554427Spetercommand. Simply prefix the keyword with the 699617721Spetermagic @sc{sccs} phrase, like this: 699717721Speter 699817721Speter@example 6999130303Speterstatic char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 700017721Speter@end example 700117721Speter 700217721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 700317721Speter@node Avoiding substitution 700417721Speter@section Avoiding substitution 700517721Speter 700617721SpeterKeyword substitution has its disadvantages. Sometimes 700717721Speteryou might want the literal text string 7008130303Speter@samp{$@splitrcskeyword{Author}$} to appear inside a file without 700932785Speter@sc{cvs} interpreting it as a keyword and expanding it 7010130303Speterinto something like @samp{$@splitrcskeyword{Author}: ceder $}. 701117721Speter 701217721SpeterThere is unfortunately no way to selectively turn off 701317721Speterkeyword substitution. You can use @samp{-ko} 701417721Speter(@pxref{Substitution modes}) to turn off keyword 701517721Spetersubstitution entirely. 701617721Speter 701726065SpeterIn many cases you can avoid using keywords in 701817721Speterthe source, even though they appear in the final 701917721Speterproduct. For example, the source for this manual 702017721Spetercontains @samp{$@@asis@{@}Author$} whenever the text 7021130303Speter@samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff} 702217721Speterand @code{troff} you can embed the null-character 702317721Speter@code{\&} inside the keyword for a similar effect. 702417721Speter 702517721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 702617721Speter@node Substitution modes 702717721Speter@section Substitution modes 702854427Speter@cindex Keyword substitution, changing modes 702926065Speter@cindex -k (keyword substitution) 703017721Speter@cindex Kflag 703117721Speter 703217721Speter@c FIXME: This could be made more coherent, by expanding it 703317721Speter@c with more examples or something. 703417721SpeterEach file has a stored default substitution mode, and 703517721Spetereach working directory copy of a file also has a 703617721Spetersubstitution mode. The former is set by the @samp{-k} 703717721Speteroption to @code{cvs add} and @code{cvs admin}; the 703832785Speterlatter is set by the @samp{-k} or @samp{-A} options to @code{cvs 7039175261Sobriencheckout} or @code{cvs update}. 7040175261Sobrien@code{cvs diff} and @code{cvs rdiff} also 7041175261Sobrienhave @samp{-k} options. 7042175261SobrienFor some examples, 704354427Spetersee @ref{Binary files}, and @ref{Merging and keywords}. 704432785Speter@c The fact that -A is overloaded to mean both reset 704532785Speter@c sticky options and reset sticky tags/dates is 704632785Speter@c somewhat questionable. Perhaps there should be 704732785Speter@c separate options to reset sticky options (e.g. -k 704832785Speter@c A") and tags/dates (someone suggested -r HEAD could 704932785Speter@c do this instead of setting a sticky tag of "HEAD" 705032785Speter@c as in the status quo but I haven't thought much 705132785Speter@c about that idea. Of course -r .reset or something 705232785Speter@c could be coined if this needs to be a new option). 705332785Speter@c On the other hand, having -A mean "get things back 705432785Speter@c into the state after a fresh checkout" has a certain 705532785Speter@c appeal, and maybe there is no sufficient reason for 705632785Speter@c creeping featurism in this area. 705717721Speter 705817721SpeterThe modes available are: 705917721Speter 706017721Speter@table @samp 706117721Speter@item -kkv 706217721SpeterGenerate keyword strings using the default form, e.g. 7063130303Speter@code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision} 706417721Speterkeyword. 706517721Speter 706617721Speter@item -kkvl 706717721SpeterLike @samp{-kkv}, except that a locker's name is always 706817721Speterinserted if the given revision is currently locked. 706954427SpeterThe locker's name is only relevant if @code{cvs admin 707054427Speter-l} is in use. 707117721Speter 707217721Speter@item -kk 707317721SpeterGenerate only keyword names in keyword strings; omit 707417721Spetertheir values. For example, for the @code{Revision} 7075130303Speterkeyword, generate the string @code{$@splitrcskeyword{Revision}$} 7076130303Speterinstead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option 707717721Speteris useful to ignore differences due to keyword 707817721Spetersubstitution when comparing different revisions of a 707954427Speterfile (@pxref{Merging and keywords}). 708017721Speter 708117721Speter@item -ko 708217721SpeterGenerate the old keyword string, present in the working 708317721Speterfile just before it was checked in. For example, for 708417721Speterthe @code{Revision} keyword, generate the string 7085130303Speter@code{$@splitrcskeyword{Revision}: 1.1 $} instead of 7086130303Speter@code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the 708717721Speterstring appeared when the file was checked in. 708817721Speter 708917721Speter@item -kb 709017721SpeterLike @samp{-ko}, but also inhibit conversion of line 709117721Speterendings between the canonical form in which they are 709217721Speterstored in the repository (linefeed only), and the form 709317721Speterappropriate to the operating system in use on the 709417721Speterclient. For systems, like unix, which use linefeed 709517721Speteronly to terminate lines, this is the same as 709617721Speter@samp{-ko}. For more information on binary files, see 709717721Speter@ref{Binary files}. 709817721Speter 709917721Speter@item -kv 710017721SpeterGenerate only keyword values for keyword strings. For 710117721Speterexample, for the @code{Revision} keyword, generate the string 7102130303Speter@code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. 710317721SpeterThis can help generate files in programming languages 710417721Speterwhere it is hard to strip keyword delimiters like 7105130303Speter@code{$@splitrcskeyword{Revision}: $} from a string. However, 710617721Speterfurther keyword substitution cannot be performed once 710717721Speterthe keyword names are removed, so this option should be 710817721Speterused with care. 710917721Speter 711017721SpeterOne often would like to use @samp{-kv} with @code{cvs 711117721Speterexport}---@pxref{export}. But be aware that doesn't 711217721Speterhandle an export containing binary files correctly. 711317721Speter 711417721Speter@end table 711517721Speter 711617721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 711717721Speter@node Log keyword 7118130303Speter@section Problems with the $@splitrcskeyword{Log}$ keyword. 711917721Speter 7120130303SpeterThe @code{$@splitrcskeyword{Log}$} keyword is somewhat 712117721Spetercontroversial. As long as you are working on your 712217721Speterdevelopment system the information is easily accessible 7123130303Spetereven if you do not use the @code{$@splitrcskeyword{Log}$} 712417721Speterkeyword---just do a @code{cvs log}. Once you export 712517721Speterthe file the history information might be useless 712617721Speteranyhow. 712717721Speter 712826065SpeterA more serious concern is that @sc{cvs} is not good at 7129130303Speterhandling @code{$@splitrcskeyword{Log}$} entries when a branch is 713017721Spetermerged onto the main trunk. Conflicts often result 713117721Speterfrom the merging operation. 713232785Speter@c Might want to check whether the CVS implementation 713332785Speter@c of RCS_merge has this problem the same way rcsmerge 713432785Speter@c does. I would assume so.... 713517721Speter 713617721SpeterPeople also tend to "fix" the log entries in the file 713717721Speter(correcting spelling mistakes and maybe even factual 713817721Spetererrors). If that is done the information from 713917721Speter@code{cvs log} will not be consistent with the 714017721Speterinformation inside the file. This may or may not be a 714117721Speterproblem in real life. 714217721Speter 7143130303SpeterIt has been suggested that the @code{$@splitrcskeyword{Log}$} 714417721Speterkeyword should be inserted @emph{last} in the file, and 714517721Speternot in the files header, if it is to be used at all. 714617721SpeterThat way the long list of change messages will not 714717721Speterinterfere with everyday source file browsing. 714817721Speter 714917721Speter@c --------------------------------------------------------------------- 715032785Speter@node Tracking sources 715132785Speter@chapter Tracking third-party sources 715232785Speter@cindex Third-party sources 715332785Speter@cindex Tracking sources 715417721Speter 715532785Speter@c FIXME: Need discussion of added and removed files. 715632785Speter@c FIXME: This doesn't really adequately introduce the 715732785Speter@c concepts of "vendor" and "you". They don't *have* 715832785Speter@c to be separate organizations or separate people. 715932785Speter@c We want a description which is somewhat more based on 716032785Speter@c the technical issues of which sources go where, but 716132785Speter@c also with enough examples of how this relates to 716232785Speter@c relationships like customer-supplier, developer-QA, 716332785Speter@c maintainer-contributor, or whatever, to make it 716432785Speter@c seem concrete. 716532785SpeterIf you modify a program to better fit your site, you 716632785Speterprobably want to include your modifications when the next 716732785Speterrelease of the program arrives. @sc{cvs} can help you with 716832785Speterthis task. 716917721Speter 717032785Speter@cindex Vendor 717132785Speter@cindex Vendor branch 717232785Speter@cindex Branch, vendor- 717332785SpeterIn the terminology used in @sc{cvs}, the supplier of the 717432785Speterprogram is called a @dfn{vendor}. The unmodified 717532785Speterdistribution from the vendor is checked in on its own 717632785Speterbranch, the @dfn{vendor branch}. @sc{cvs} reserves branch 717732785Speter1.1.1 for this use. 717817721Speter 717932785SpeterWhen you modify the source and commit it, your revision 718032785Speterwill end up on the main trunk. When a new release is 718132785Spetermade by the vendor, you commit it on the vendor branch 718232785Speterand copy the modifications onto the main trunk. 718325839Speter 718432785SpeterUse the @code{import} command to create and update 718544852Speterthe vendor branch. When you import a new file, 718632785Speterthe vendor branch is made the `head' revision, so 718732785Speteranyone that checks out a copy of the file gets that 718832785Speterrevision. When a local modification is committed it is 718932785Speterplaced on the main trunk, and made the `head' 719032785Speterrevision. 719117721Speter 719232785Speter@menu 719354427Speter* First import:: Importing for the first time 719454427Speter* Update imports:: Updating with the import command 719554427Speter* Reverting local changes:: Reverting to the latest vendor release 719632785Speter* Binary files in imports:: Binary files require special handling 719732785Speter* Keywords in imports:: Keyword substitution might be undesirable 719832785Speter* Multiple vendor branches:: What if you get sources from several places? 719932785Speter@end menu 720017721Speter 720132785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 720232785Speter@node First import 720354427Speter@section Importing for the first time 720432785Speter@cindex Importing modules 720532785Speter 720632785Speter@c Should mention naming conventions for vendor tags, 720732785Speter@c release tags, and perhaps directory names. 720832785SpeterUse the @code{import} command to check in the sources 720932785Speterfor the first time. When you use the @code{import} 721032785Spetercommand to track third-party sources, the @dfn{vendor 721132785Spetertag} and @dfn{release tags} are useful. The 721232785Speter@dfn{vendor tag} is a symbolic name for the branch 721332785Speter(which is always 1.1.1, unless you use the @samp{-b 721481404Speter@var{branch}} flag---see @ref{Multiple vendor branches}.). The 721532785Speter@dfn{release tags} are symbolic names for a particular 721632785Speterrelease, such as @samp{FSF_0_04}. 721732785Speter 721832785Speter@c I'm not completely sure this belongs here. But 721932785Speter@c we need to say it _somewhere_ reasonably obvious; it 722032785Speter@c is a common misconception among people first learning CVS 722132785SpeterNote that @code{import} does @emph{not} change the 722232785Speterdirectory in which you invoke it. In particular, it 722332785Speterdoes not set up that directory as a @sc{cvs} working 722432785Speterdirectory; if you want to work with the sources import 722532785Speterthem first and then check them out into a different 722632785Speterdirectory (@pxref{Getting the source}). 722732785Speter 722866525Speter@cindex wdiff (import example) 722932785SpeterSuppose you have the sources to a program called 723032785Speter@code{wdiff} in a directory @file{wdiff-0.04}, 723132785Speterand are going to make private modifications that you 723232785Speterwant to be able to use even when new releases are made 723332785Speterin the future. You start by importing the source to 723432785Speteryour repository: 723532785Speter 723617721Speter@example 723732785Speter$ cd wdiff-0.04 723832785Speter$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 723917721Speter@end example 724017721Speter 724132785SpeterThe vendor tag is named @samp{FSF_DIST} in the above 724232785Speterexample, and the only release tag assigned is 724332785Speter@samp{WDIFF_0_04}. 724432785Speter@c FIXME: Need to say where fsf/wdiff comes from. 724517721Speter 724632785Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 724732785Speter@node Update imports 724854427Speter@section Updating with the import command 724932785Speter 725032785SpeterWhen a new release of the source arrives, you import it into the 725132785Speterrepository with the same @code{import} command that you used to set up 725232785Speterthe repository in the first place. The only difference is that you 7253102840Speterspecify a different release tag this time: 725432785Speter 725517721Speter@example 725632785Speter$ tar xfz wdiff-0.05.tar.gz 725732785Speter$ cd wdiff-0.05 725832785Speter$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 725917721Speter@end example 726017721Speter 7261177391Sobrien@strong{WARNING: If you use a release tag that already exists in one of the 7262175261Sobrienrepository archives, files removed by an import may not be detected.} 7263175261Sobrien 726432785SpeterFor files that have not been modified locally, the newly created 726532785Speterrevision becomes the head revision. If you have made local 726632785Speterchanges, @code{import} will warn you that you must merge the changes 7267102840Speterinto the main trunk, and tell you to use @samp{checkout -j} to do so: 726817721Speter 726932785Speter@c FIXME: why "wdiff" here and "fsf/wdiff" in the 727032785Speter@c "import"? I think the assumption is that one has 727132785Speter@c "wdiff fsf/wdiff" or some such in modules, but it 727232785Speter@c would be better to not use modules in this example. 727332785Speter@example 727432785Speter$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 727532785Speter@end example 727625839Speter 727732785Speter@noindent 727832785SpeterThe above command will check out the latest revision of 727932785Speter@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 728032785Spetersince yesterday into the working copy. If any conflicts arise during 728132785Speterthe merge they should be resolved in the normal way (@pxref{Conflicts 728232785Speterexample}). Then, the modified files may be committed. 728325839Speter 7284102840SpeterHowever, it is much better to use the two release tags rather than using 7285102840Spetera date on the branch as suggested above: 728632785Speter 728732785Speter@example 728832785Speter$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 728932785Speter@end example 729032785Speter 729132785Speter@noindent 7292102840SpeterThe reason this is better is that 7293102840Speterusing a date, as suggested above, assumes that you do 7294102840Speternot import more than one release of a product per day. 7295102840SpeterMore importantly, using the release tags allows @sc{cvs} to detect files 7296102840Speterthat were removed between the two vendor releases and mark them for 7297102840Speterremoval. Since @code{import} has no way to detect removed files, you 7298102840Spetershould do a merge like this even if @code{import} doesn't tell you to. 729932785Speter 730032785Speter@node Reverting local changes 730132785Speter@section Reverting to the latest vendor release 730232785Speter 730332785SpeterYou can also revert local changes completely and return 730432785Speterto the latest vendor release by changing the `head' 730532785Speterrevision back to the vendor branch on all files. For 730632785Speterexample, if you have a checked-out copy of the sources 730732785Speterin @file{~/work.d/wdiff}, and you want to revert to the 730832785Spetervendor's version for all the files in that directory, 730932785Speteryou would type: 731032785Speter 731132785Speter@example 731232785Speter$ cd ~/work.d/wdiff 7313128266Speter$ cvs admin -bFSF_DIST . 731432785Speter@end example 731532785Speter 731632785Speter@noindent 7317128266SpeterYou must specify the @samp{-bFSF_DIST} without any space 731832785Speterafter the @samp{-b}. @xref{admin options}. 731932785Speter 732032785Speter@node Binary files in imports 732132785Speter@section How to handle binary files with cvs import 732232785Speter 732332785SpeterUse the @samp{-k} wrapper option to tell import which 732432785Speterfiles are binary. @xref{Wrappers}. 732532785Speter 732632785Speter@node Keywords in imports 732732785Speter@section How to handle keyword substitution with cvs import 732832785Speter 732932785SpeterThe sources which you are importing may contain 733032785Speterkeywords (@pxref{Keyword substitution}). For example, 733132785Speterthe vendor may use @sc{cvs} or some other system 733232785Speterwhich uses similar keyword expansion syntax. If you 733332785Speterjust import the files in the default fashion, then 733432785Speterthe keyword expansions supplied by the vendor will 733532785Speterbe replaced by keyword expansions supplied by your 733632785Speterown copy of @sc{cvs}. It may be more convenient to 733732785Spetermaintain the expansions supplied by the vendor, so 733832785Speterthat this information can supply information about 733932785Speterthe sources that you imported from the vendor. 734032785Speter 734132785SpeterTo maintain the keyword expansions supplied by the 734232785Spetervendor, supply the @samp{-ko} option to @code{cvs 734332785Speterimport} the first time you import the file. 734432785SpeterThis will turn off keyword expansion 734532785Speterfor that file entirely, so if you want to be more 734632785Speterselective you'll have to think about what you want 734732785Speterand use the @samp{-k} option to @code{cvs update} or 734832785Speter@code{cvs admin} as appropriate. 734932785Speter@c Supplying -ko to import if the file already existed 735032785Speter@c has no effect. Not clear to me whether it should 735132785Speter@c or not. 735232785Speter 735332785Speter@node Multiple vendor branches 735432785Speter@section Multiple vendor branches 735532785Speter 735632785SpeterAll the examples so far assume that there is only one 735732785Spetervendor from which you are getting sources. In some 735832785Spetersituations you might get sources from a variety of 735932785Speterplaces. For example, suppose that you are dealing with 736032785Spetera project where many different people and teams are 736132785Spetermodifying the software. There are a variety of ways to 736232785Speterhandle this, but in some cases you have a bunch of 736332785Spetersource trees lying around and what you want to do more 736481404Speterthan anything else is just to all put them in @sc{cvs} so 736532785Speterthat you at least have them in one place. 736632785Speter 736732785SpeterFor handling situations in which there may be more than 736832785Speterone vendor, you may specify the @samp{-b} option to 736932785Speter@code{cvs import}. It takes as an argument the vendor 737032785Speterbranch to import to. The default is @samp{-b 1.1.1}. 737132785Speter 737232785SpeterFor example, suppose that there are two teams, the red 737332785Speterteam and the blue team, that are sending you sources. 737432785SpeterYou want to import the red team's efforts to branch 737532785Speter1.1.1 and use the vendor tag RED. You want to import 737632785Speterthe blue team's efforts to branch 1.1.3 and use the 737732785Spetervendor tag BLUE. So the commands you might use are: 737832785Speter 737932785Speter@example 738032785Speter$ cvs import dir RED RED_1-0 738132785Speter$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 738232785Speter@end example 738332785Speter 738432785SpeterNote that if your vendor tag does not match your 738581404Speter@samp{-b} option, @sc{cvs} will not detect this case! For 738632785Speterexample, 738732785Speter 738832785Speter@example 738932785Speter$ cvs import -b 1.1.3 dir RED RED_1-0 739032785Speter@end example 739132785Speter 739232785Speter@noindent 739332785SpeterBe careful; this kind of mismatch is sure to sow 739432785Speterconfusion or worse. I can't think of a useful purpose 739532785Speterfor the ability to specify a mismatch here, but if you 739681404Speterdiscover such a use, don't. @sc{cvs} is likely to make this 739732785Speteran error in some future release. 739832785Speter 739932785Speter@c Probably should say more about the semantics of 740032785Speter@c multiple branches. What about the default branch? 740132785Speter@c What about joining (perhaps not as useful with 740232785Speter@c multiple branches, or perhaps it is. Either way 740332785Speter@c should be mentioned). 740432785Speter 740525839Speter@c I'm not sure about the best location for this. In 740625839Speter@c one sense, it might belong right after we've introduced 740725839Speter@c CVS's basic version control model, because people need 740825839Speter@c to figure out builds right away. The current location 740925839Speter@c is based on the theory that it kind of akin to the 741025839Speter@c "Revision management" section. 741125839Speter@node Builds 741225839Speter@chapter How your build system interacts with CVS 741366525Speter@cindex Builds 741425839Speter@cindex make 741525839Speter 741625839SpeterAs mentioned in the introduction, @sc{cvs} does not 741725839Spetercontain software for building your software from source 741825839Spetercode. This section describes how various aspects of 741925839Speteryour build system might interact with @sc{cvs}. 742025839Speter 742125839Speter@c Is there a way to discuss this without reference to 742225839Speter@c tools other than CVS? I'm not sure there is; I 742325839Speter@c wouldn't think that people who learn CVS first would 742425839Speter@c even have this concern. 742525839SpeterOne common question, especially from people who are 742625839Speteraccustomed to @sc{rcs}, is how to make their build get 742725839Speteran up to date copy of the sources. The answer to this 742825839Speterwith @sc{cvs} is two-fold. First of all, since 742925839Speter@sc{cvs} itself can recurse through directories, there 743025839Speteris no need to modify your @file{Makefile} (or whatever 743125839Speterconfiguration file your build tool uses) to make sure 743225839Spetereach file is up to date. Instead, just use two 743325839Spetercommands, first @code{cvs -q update} and then 743425839Speter@code{make} or whatever the command is to invoke your 743525839Speterbuild tool. Secondly, you do not necessarily 743625839Speter@emph{want} to get a copy of a change someone else made 743725839Speteruntil you have finished your own work. One suggested 743825839Speterapproach is to first update your sources, then 743925839Speterimplement, build and 744025839Spetertest the change you were thinking of, and then commit 744125839Speteryour sources (updating first if necessary). By 744225839Speterperiodically (in between changes, using the approach 744325839Speterjust described) updating your entire tree, you ensure 744425839Speterthat your sources are sufficiently up to date. 744525839Speter 744666525Speter@cindex Bill of materials 744725839SpeterOne common need is to record which versions of which 744825839Spetersource files went into a particular build. This kind 744925839Speterof functionality is sometimes called @dfn{bill of 745025839Spetermaterials} or something similar. The best way to do 745125839Speterthis with @sc{cvs} is to use the @code{tag} command to 745225839Speterrecord which versions went into a given build 745325839Speter(@pxref{Tags}). 745425839Speter 745525839SpeterUsing @sc{cvs} in the most straightforward manner 745625839Speterpossible, each developer will have a copy of the entire 745725839Spetersource tree which is used in a particular build. If 745825839Speterthe source tree is small, or if developers are 745925839Spetergeographically dispersed, this is the preferred 746025839Spetersolution. In fact one approach for larger projects is 746125839Speterto break a project down into smaller 746225839Speter@c I say subsystem instead of module because they may or 746325839Speter@c may not use the modules file. 746425839Speterseparately-compiled subsystems, and arrange a way of 746525839Speterreleasing them internally so that each developer need 7466130303Spetercheck out only those subsystems which they are 746725839Speteractively working on. 746825839Speter 746925839SpeterAnother approach is to set up a structure which allows 747025839Speterdevelopers to have their own copies of some files, and 747125839Speterfor other files to access source files from a central 747225839Speterlocation. Many people have come up with some such a 747325839Speter@c two such people are paul@sander.cupertino.ca.us (for 747425839Speter@c a previous employer) 7475175261Sobrien@c and gunnar.tornblom@se.abb.com (spicm and related tools), 747625839Speter@c but as far as I know 747732785Speter@c no one has nicely packaged or released such a system (or 747825839Speter@c instructions for constructing one). 747925839Spetersystem using features such as the symbolic link feature 748025839Speterfound in many operating systems, or the @code{VPATH} 748125839Speterfeature found in many versions of @code{make}. One build 748225839Spetertool which is designed to help with this kind of thing 748325839Speteris Odin (see 748425839Speter@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 748525839Speter@c Should we be saying more about Odin? Or how you use 748625839Speter@c it with CVS? Also, the Prime Time Freeware for Unix 748725839Speter@c disk (see http://www.ptf.com/) has Odin (with a nice 748825839Speter@c paragraph summarizing it on the web), so that might be a 748925839Speter@c semi-"official" place to point people. 749025839Speter@c 749125839Speter@c Of course, many non-CVS systems have this kind of 749225839Speter@c functionality, for example OSF's ODE 749325839Speter@c (http://www.osf.org/ode/) or mk 749426801Speter@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 749526801Speter@c He has changed providers in the past; a search engine search 749626801Speter@c for "Peter Ziobrzynski" probably won't get too many 749726801Speter@c spurious hits :-). A more stable URL might be 749826801Speter@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 749925839Speter@c there is any point in mentioning them here unless they 750025839Speter@c can work with CVS. 750125839Speter 750217721Speter@c --------------------------------------------------------------------- 750334461Speter@node Special Files 750434461Speter@chapter Special Files 750534461Speter 750666525Speter@cindex Special files 750766525Speter@cindex Device nodes 750866525Speter@cindex Ownership, saving in CVS 750966525Speter@cindex Permissions, saving in CVS 751066525Speter@cindex Hard links 751166525Speter@cindex Symbolic links 751244852Speter 751381404SpeterIn normal circumstances, @sc{cvs} works only with regular 751434461Speterfiles. Every file in a project is assumed to be 751534461Speterpersistent; it must be possible to open, read and close 751681404Speterthem; and so on. @sc{cvs} also ignores file permissions and 751734461Speterownerships, leaving such issues to be resolved by the 751834461Speterdeveloper at installation time. In other words, it is 751934461Speternot possible to "check in" a device into a repository; 752081404Speterif the device file cannot be opened, @sc{cvs} will refuse to 752134461Speterhandle it. Files also lose their ownerships and 752234461Speterpermissions during repository transactions. 752334461Speter 752466525Speter@ignore 752544852SpeterIf the configuration variable @code{PreservePermissions} 752681404Speter(@pxref{config}) is set in the repository, @sc{cvs} will 752744852Spetersave the following file characteristics in the 752844852Speterrepository: 752934461Speter 753044852Speter@itemize @bullet 753144852Speter@item user and group ownership 753244852Speter@item permissions 753344852Speter@item major and minor device numbers 753444852Speter@item symbolic links 753544852Speter@item hard link structure 753644852Speter@end itemize 753734461Speter 753844852SpeterUsing the @code{PreservePermissions} option affects the 753981404Speterbehavior of @sc{cvs} in several ways. First, some of the 754081404Speternew operations supported by @sc{cvs} are not accessible to 754144852Speterall users. In particular, file ownership and special 754244852Speterfile characteristics may only be changed by the 754344852Spetersuperuser. When the @code{PreservePermissions} 754444852Speterconfiguration variable is set, therefore, users will 754581404Speterhave to be `root' in order to perform @sc{cvs} operations. 754644852Speter 754781404SpeterWhen @code{PreservePermissions} is in use, some @sc{cvs} 754844852Speteroperations (such as @samp{cvs status}) will not 754944852Speterrecognize a file's hard link structure, and so will 755044852Speteremit spurious warnings about mismatching hard links. 755181404SpeterThe reason is that @sc{cvs}'s internal structure does not 755244852Spetermake it easy for these operations to collect all the 755344852Speternecessary data about hard links, so they check for file 755444852Speterconflicts with inaccurate data. 755544852Speter 755681404SpeterA more subtle difference is that @sc{cvs} considers a file 755734461Speterto have changed only if its contents have changed 755834461Speter(specifically, if the modification time of the working 755934461Speterfile does not match that of the repository's file). 756044852SpeterTherefore, if only the permissions, ownership or hard 756144852Speterlinkage have changed, or if a device's major or minor 756281404Speternumbers have changed, @sc{cvs} will not notice. In order to 756344852Spetercommit such a change to the repository, you must force 756444852Speterthe commit with @samp{cvs commit -f}. This also means 756544852Speterthat if a file's permissions have changed and the 756644852Speterrepository file is newer than the working copy, 756744852Speterperforming @samp{cvs update} will silently change the 756844852Speterpermissions on the working copy. 756934461Speter 757081404SpeterChanging hard links in a @sc{cvs} repository is particularly 757144852Speterdelicate. Suppose that file @file{foo} is linked to 757244852Speterfile @file{old}, but is later relinked to file 757344852Speter@file{new}. You can wind up in the unusual situation 757444852Speterwhere, although @file{foo}, @file{old} and @file{new} 757544852Speterhave all had their underlying link patterns changed, 757644852Speteronly @file{foo} and @file{new} have been modified, so 757744852Speter@file{old} is not considered a candidate for checking 757844852Speterin. It can be very easy to produce inconsistent 757944852Speterresults this way. Therefore, we recommend that when it 758044852Speteris important to save hard links in a repository, the 758144852Speterprudent course of action is to @code{touch} any file 758244852Speterwhose linkage or status has changed since the last 758344852Spetercheckin. Indeed, it may be wise to @code{touch *} 758444852Speterbefore each commit in a directory with complex hard 758544852Speterlink structures. 758644852Speter 758734461SpeterIt is worth noting that only regular files may 758834461Speterbe merged, for reasons that hopefully are obvious. If 758934461Speter@samp{cvs update} or @samp{cvs checkout -j} attempts to 759034461Spetermerge a symbolic link with a regular file, or two 759181404Speterdevice files for different kinds of devices, @sc{cvs} will 759234461Speterreport a conflict and refuse to perform the merge. At 759334461Speterthe same time, @samp{cvs diff} will not report any 759434461Speterdifferences between these files, since no meaningful 759534461Spetertextual comparisons can be made on files which contain 759634461Speterno text. 759734461Speter 759844852SpeterThe @code{PreservePermissions} features do not work 759944852Speterwith client/server @sc{cvs}. Another limitation is 760044852Speterthat hard links must be to other files within the same 760134461Speterdirectory; hard links across directories are not 760234461Spetersupported. 760366525Speter@end ignore 760434461Speter 760534461Speter@c --------------------------------------------------------------------- 7606130303Speter@c ----- START MAN 1 ----- 760725839Speter@node CVS commands 760825839Speter@appendix Guide to CVS commands 760917721Speter 761025839SpeterThis appendix describes the overall structure of 761125839Speter@sc{cvs} commands, and describes some commands in 761225839Speterdetail (others are described elsewhere; for a quick 761325839Speterreference to @sc{cvs} commands, @pxref{Invoking CVS}). 761425839Speter@c The idea is that we want to move the commands which 761525839Speter@c are described here into the main body of the manual, 761625839Speter@c in the process reorganizing the manual to be 761725839Speter@c organized around what the user wants to do, not 761825839Speter@c organized around CVS commands. 761954427Speter@c 762054427Speter@c Note that many users do expect a manual which is 762154427Speter@c organized by command. At least some users do. 762254427Speter@c One good addition to the "organized by command" 762354427Speter@c section (if any) would be "see also" links. 762454427Speter@c The awk manual might be a good example; it has a 762554427Speter@c reference manual which is more verbose than Invoking 762654427Speter@c CVS but probably somewhat less verbose than CVS 762754427Speter@c Commands. 762817721Speter 762917721Speter@menu 763017721Speter* Structure:: Overall structure of CVS commands 763126065Speter* Exit status:: Indicating CVS's success or failure 7632128266Speter* ~/.cvsrc:: Default options with the ~/.cvsrc file 763317721Speter* Global options:: Options you give to the left of cvs_command 763417721Speter* Common options:: Options you give to the right of cvs_command 7635177391Sobrien* add:: Add files and directories to the repository 763632785Speter* admin:: Administration 7637130303Speter* annotate:: What revision modified each line of a file? 763817721Speter* checkout:: Checkout sources for editing 763917721Speter* commit:: Check files into the repository 764025839Speter* diff:: Show differences between revisions 764117721Speter* export:: Export sources from CVS, similar to checkout 764217721Speter* history:: Show status of files and users 764317721Speter* import:: Import sources into CVS, using vendor branches 764425839Speter* log:: Show log messages for files 764517721Speter* rdiff:: 'patch' format diffs between releases 764654427Speter* release:: Indicate that a directory is no longer in use 7647177391Sobrien* remove:: Remove files from active development 764817721Speter* update:: Bring work tree in sync with repository 764917721Speter@end menu 765017721Speter 765117721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 765217721Speter@node Structure 765317721Speter@appendixsec Overall structure of CVS commands 765417721Speter@cindex Structure 765517721Speter@cindex CVS command structure 765617721Speter@cindex Command structure 765717721Speter@cindex Format of CVS commands 765817721Speter 765925839SpeterThe overall format of all @sc{cvs} commands is: 766017721Speter 766117721Speter@example 766217721Spetercvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 766317721Speter@end example 766417721Speter 766517721Speter@table @code 766617721Speter@item cvs 766725839SpeterThe name of the @sc{cvs} program. 766817721Speter 766917721Speter@item cvs_options 767017721SpeterSome options that affect all sub-commands of @sc{cvs}. These are 767117721Speterdescribed below. 767217721Speter 767317721Speter@item cvs_command 767417721SpeterOne of several different sub-commands. Some of the commands have 767517721Speteraliases that can be used instead; those aliases are noted in the 767617721Speterreference manual for that command. There are only two situations 767717721Speterwhere you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 767817721Speterlist of available commands, and @samp{cvs -v} displays version 767917721Speterinformation on @sc{cvs} itself. 768017721Speter 768117721Speter@item command_options 768217721SpeterOptions that are specific for the command. 768317721Speter 768417721Speter@item command_args 768517721SpeterArguments to the commands. 768617721Speter@end table 768717721Speter 768817721SpeterThere is unfortunately some confusion between 768917721Speter@code{cvs_options} and @code{command_options}. 7690130303SpeterWhen given as a @code{cvs_option}, some options only 7691130303Speteraffect some of the commands. When given as a 7692130303Speter@code{command_option} it may have a different meaning, and 7693130303Speterbe accepted by more commands. In other words, do not 769417721Spetertake the above categorization too seriously. Look at 769517721Speterthe documentation instead. 769617721Speter 769726065Speter@node Exit status 769826065Speter@appendixsec CVS's exit status 769966525Speter@cindex Exit status, of CVS 770026065Speter 770181404Speter@sc{cvs} can indicate to the calling environment whether it 770226065Spetersucceeded or failed by setting its @dfn{exit status}. 770326065SpeterThe exact way of testing the exit status will vary from 770426065Speterone operating system to another. For example in a unix 770526065Spetershell script the @samp{$?} variable will be 0 if the 770626065Speterlast command returned a successful exit status, or 770726065Spetergreater than 0 if the exit status indicated failure. 770826065Speter 770981404SpeterIf @sc{cvs} is successful, it returns a successful status; 771026065Speterif there is an error, it prints an error message and 771126065Speterreturns a failure status. The one exception to this is 771226065Speterthe @code{cvs diff} command. It will return a 771326065Spetersuccessful status if it found no differences, or a 771426065Speterfailure status if there were differences or if there 771526065Speterwas an error. Because this behavior provides no good 771626065Speterway to detect errors, in the future it is possible that 771726065Speter@code{cvs diff} will be changed to behave like the 771826065Speterother @sc{cvs} commands. 771926065Speter@c It might seem like checking whether cvs -q diff 772026065Speter@c produces empty or non-empty output can tell whether 772126065Speter@c there were differences or not. But it seems like 772226065Speter@c there are cases with output but no differences 772326065Speter@c (testsuite basica-8b). It is not clear to me how 772426065Speter@c useful it is for a script to be able to check 772526065Speter@c whether there were differences. 772626065Speter@c FIXCVS? In previous versions of CVS, cvs diff 772726065Speter@c returned 0 for no differences, 1 for differences, or 772826065Speter@c 2 for errors. Is this behavior worth trying to 772926065Speter@c bring back (but what does it mean for VMS?)? 773026065Speter 773117721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 773217721Speter@node ~/.cvsrc 773317721Speter@appendixsec Default options and the ~/.cvsrc file 773417721Speter@cindex .cvsrc file 773566525Speter@cindex Option defaults 773617721Speter 773717721SpeterThere are some @code{command_options} that are used so 773817721Speteroften that you might have set up an alias or some other 773917721Spetermeans to make sure you always specify that option. One 774017721Speterexample (the one that drove the implementation of the 774132785Speter@file{.cvsrc} support, actually) is that many people find the 774217721Speterdefault output of the @samp{diff} command to be very 774317721Speterhard to read, and that either context diffs or unidiffs 774417721Speterare much easier to understand. 774517721Speter 774617721SpeterThe @file{~/.cvsrc} file is a way that you can add 774717721Speterdefault options to @code{cvs_commands} within cvs, 774817721Speterinstead of relying on aliases or other shell scripts. 774917721Speter 775017721SpeterThe format of the @file{~/.cvsrc} file is simple. The 775117721Speterfile is searched for a line that begins with the same 775217721Spetername as the @code{cvs_command} being executed. If a 775317721Spetermatch is found, then the remainder of the line is split 775417721Speterup (at whitespace characters) into separate options and 775517721Speteradded to the command arguments @emph{before} any 775617721Speteroptions from the command line. 775717721Speter 775817721SpeterIf a command has two names (e.g., @code{checkout} and 775917721Speter@code{co}), the official name, not necessarily the one 776017721Speterused on the command line, will be used to match against 776117721Speterthe file. So if this is the contents of the user's 776217721Speter@file{~/.cvsrc} file: 776317721Speter 776417721Speter@example 776517721Speterlog -N 7766102840Speterdiff -uN 7767102840Speterrdiff -u 7768102840Speterupdate -Pd 776944852Spetercheckout -P 7770102840Speterrelease -d 777117721Speter@end example 777217721Speter 777317721Speter@noindent 777417721Speterthe command @samp{cvs checkout foo} would have the 777517721Speter@samp{-P} option added to the arguments, as well as 777617721Speter@samp{cvs co foo}. 777717721Speter 777817721SpeterWith the example file above, the output from @samp{cvs 777917721Speterdiff foobar} will be in unidiff format. @samp{cvs diff 778017721Speter-c foobar} will provide context diffs, as usual. 778117721SpeterGetting "old" format diffs would be slightly more 778217721Spetercomplicated, because @code{diff} doesn't have an option 778317721Speterto specify use of the "old" format, so you would need 778417721Speter@samp{cvs -f diff foobar}. 778517721Speter 778617721SpeterIn place of the command name you can use @code{cvs} to 778717721Speterspecify global options (@pxref{Global options}). For 778817721Speterexample the following line in @file{.cvsrc} 778917721Speter 779017721Speter@example 779117721Spetercvs -z6 779217721Speter@end example 779317721Speter 7794102840Speter@noindent 779532785Spetercauses @sc{cvs} to use compression level 6. 779617721Speter 779717721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 779817721Speter@node Global options 779917721Speter@appendixsec Global options 780017721Speter@cindex Options, global 780117721Speter@cindex Global options 780217721Speter@cindex Left-hand options 780317721Speter 780417721SpeterThe available @samp{cvs_options} (that are given to the 780517721Speterleft of @samp{cvs_command}) are: 780617721Speter 780717721Speter@table @code 780826801Speter@item --allow-root=@var{rootdir} 780926801SpeterSpecify legal @sc{cvsroot} directory. See 781026801Speter@ref{Password authentication server}. 781126801Speter 781266525Speter@cindex Authentication, stream 781366525Speter@cindex Stream authentication 781432785Speter@item -a 781532785SpeterAuthenticate all communication between the client and 781632785Speterthe server. Only has an effect on the @sc{cvs} client. 781732785SpeterAs of this writing, this is only implemented when using 781832785Spetera GSSAPI connection (@pxref{GSSAPI authenticated}). 781932785SpeterAuthentication prevents certain sorts of attacks 782032785Speterinvolving hijacking the active @sc{tcp} connection. 782132785SpeterEnabling authentication does not enable encryption. 782232785Speter 782317721Speter@cindex RCSBIN, overriding 782417721Speter@cindex Overriding RCSBIN 782517721Speter@item -b @var{bindir} 782632785SpeterIn @sc{cvs} 1.9.18 and older, this specified that 782732785Speter@sc{rcs} programs are in the @var{bindir} directory. 782832785SpeterCurrent versions of @sc{cvs} do not run @sc{rcs} 782932785Speterprograms; for compatibility this option is accepted, 783032785Speterbut it does nothing. 783117721Speter 783225839Speter@cindex TMPDIR, overriding 783325839Speter@cindex Overriding TMPDIR 783425839Speter@item -T @var{tempdir} 783525839SpeterUse @var{tempdir} as the directory where temporary files are 783625839Speterlocated. Overrides the setting of the @code{$TMPDIR} environment 783725839Spetervariable and any precompiled directory. This parameter should be 783825839Speterspecified as an absolute pathname. 7839102840Speter(When running client/server, @samp{-T} affects only the local process; 7840102840Speterspecifying @samp{-T} for the client has no effect on the server and 7841102840Spetervice versa.) 784225839Speter 784317721Speter@cindex CVSROOT, overriding 784417721Speter@cindex Overriding CVSROOT 784517721Speter@item -d @var{cvs_root_directory} 784617721SpeterUse @var{cvs_root_directory} as the root directory 784717721Speterpathname of the repository. Overrides the setting of 7848177391Sobrienthe @code{$CVSROOT} environment variable. See @ref{Repository}. 784917721Speter 785017721Speter@cindex EDITOR, overriding 785117721Speter@cindex Overriding EDITOR 785217721Speter@item -e @var{editor} 785317721SpeterUse @var{editor} to enter revision log information. Overrides the 785425839Spetersetting of the @code{$CVSEDITOR} and @code{$EDITOR} 785525839Speterenvironment variables. For more information, see 785625839Speter@ref{Committing your changes}. 785717721Speter 785817721Speter@item -f 785917721SpeterDo not read the @file{~/.cvsrc} file. This 786017721Speteroption is most often used because of the 786117721Speternon-orthogonality of the @sc{cvs} option set. For 786217721Speterexample, the @samp{cvs log} option @samp{-N} (turn off 786317721Speterdisplay of tag names) does not have a corresponding 786417721Speteroption to turn the display on. So if you have 786525839Speter@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 786617721Speteryou may need to use @samp{-f} to show the tag names. 786717721Speter 786817721Speter@item -H 786925839Speter@itemx --help 787017721SpeterDisplay usage information about the specified @samp{cvs_command} 787117721Speter(but do not actually execute the command). If you don't specify 787225839Spetera command name, @samp{cvs -H} displays overall help for 787325839Speter@sc{cvs}, including a list of other help options. 787425839Speter@c It seems to me it is better to document it this way 787525839Speter@c rather than trying to update this documentation 787625839Speter@c every time that we add a --help-foo option. But 787725839Speter@c perhaps that is confusing... 787817721Speter 787917721Speter@cindex Read-only mode 788017721Speter@item -n 788117721SpeterDo not change any files. Attempt to execute the 788217721Speter@samp{cvs_command}, but only to issue reports; do not remove, 788317721Speterupdate, or merge any existing files, or create any new files. 788417721Speter 788526801SpeterNote that @sc{cvs} will not necessarily produce exactly 788626801Speterthe same output as without @samp{-n}. In some cases 788726801Speterthe output will be the same, but in other cases 788826801Speter@sc{cvs} will skip some of the processing that would 788926801Speterhave been required to produce the exact same output. 789026801Speter 789117721Speter@item -Q 789217721SpeterCause the command to be really quiet; the command will only 789317721Spetergenerate output for serious problems. 789417721Speter 789517721Speter@item -q 789617721SpeterCause the command to be somewhat quiet; informational messages, 789717721Spetersuch as reports of recursion through subdirectories, are 789817721Spetersuppressed. 789917721Speter 790066525Speter@cindex Read-only files, and -r 790117721Speter@item -r 790244852SpeterMake new working files read-only. Same effect 790317721Speteras if the @code{$CVSREAD} environment variable is set 790417721Speter(@pxref{Environment variables}). The default is to 790517721Spetermake working files writable, unless watches are on 790617721Speter(@pxref{Watches}). 790717721Speter 790817721Speter@item -s @var{variable}=@var{value} 790917721SpeterSet a user variable (@pxref{Variables}). 791017721Speter 791117721Speter@cindex Trace 791217721Speter@item -t 791317721SpeterTrace program execution; display messages showing the steps of 791417721Speter@sc{cvs} activity. Particularly useful with @samp{-n} to explore the 791517721Speterpotential impact of an unfamiliar command. 791617721Speter 791717721Speter@item -v 791825839Speter@item --version 791917721SpeterDisplay version and copyright information for @sc{cvs}. 792017721Speter 792117721Speter@cindex CVSREAD, overriding 792217721Speter@cindex Overriding CVSREAD 792317721Speter@item -w 792417721SpeterMake new working files read-write. Overrides the 792517721Spetersetting of the @code{$CVSREAD} environment variable. 792617721SpeterFiles are created read-write by default, unless @code{$CVSREAD} is 792717721Speterset or @samp{-r} is given. 792832785Speter@c Note that -w only overrides -r and CVSREAD; it has 792932785Speter@c no effect on files which are readonly because of 793032785Speter@c "cvs watch on". My guess is that is the way it 793132785Speter@c should be (or should "cvs -w get" on a watched file 793232785Speter@c be the same as a get and a cvs edit?), but I'm not 793332785Speter@c completely sure whether to document it this way. 793417721Speter 793525839Speter@item -x 793666525Speter@cindex Encryption 793725839SpeterEncrypt all communication between the client and the 793825839Speterserver. Only has an effect on the @sc{cvs} client. As 793925839Speterof this writing, this is only implemented when using a 794032785SpeterGSSAPI connection (@pxref{GSSAPI authenticated}) or a 794125839SpeterKerberos connection (@pxref{Kerberos authenticated}). 794232785SpeterEnabling encryption implies that message traffic is 794332785Speteralso authenticated. Encryption support is not 794432785Speteravailable by default; it must be enabled using a 794532785Speterspecial configure option, @file{--enable-encryption}, 794632785Speterwhen you build @sc{cvs}. 794725839Speter 794817721Speter@item -z @var{gzip-level} 794966525Speter@cindex Compression 795066525Speter@cindex Gzip 795166525SpeterSet the compression level. 795266525SpeterValid levels are 1 (high speed, low compression) to 795366525Speter9 (low speed, high compression), or 0 to disable 795466525Spetercompression (the default). 795566525SpeterOnly has an effect on the @sc{cvs} client. 795617721Speter 795717721Speter@end table 795817721Speter 795917721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 796017721Speter@node Common options 796117721Speter@appendixsec Common command options 796217721Speter@cindex Common options 796317721Speter@cindex Right-hand options 796417721Speter 796517721SpeterThis section describes the @samp{command_options} that 796617721Speterare available across several @sc{cvs} commands. These 796717721Speteroptions are always given to the right of 796817721Speter@samp{cvs_command}. Not all 796917721Spetercommands support all of these options; each option is 797017721Speteronly supported for commands where it makes sense. 797117721SpeterHowever, when a command has one of these options you 797217721Spetercan almost always count on the same behavior of the 797317721Speteroption as in other commands. (Other command options, 797417721Speterwhich are listed with the individual commands, may have 797517721Speterdifferent behavior from one @sc{cvs} command to the other). 797617721Speter 7977175261Sobrien@strong{The @samp{history} command is an exception; it supports 7978128266Spetermany options that conflict even with these standard options.} 797917721Speter 798017721Speter@table @code 798117721Speter@cindex Dates 798217721Speter@cindex Time 798317721Speter@cindex Specifying dates 798417721Speter@item -D @var{date_spec} 798517721SpeterUse the most recent revision no later than @var{date_spec}. 798617721Speter@var{date_spec} is a single argument, a date description 798717721Speterspecifying a date in the past. 798817721Speter 798917721SpeterThe specification is @dfn{sticky} when you use it to make a 799017721Speterprivate copy of a source file; that is, when you get a working 799117721Speterfile using @samp{-D}, @sc{cvs} records the date you specified, so that 799217721Speterfurther updates in the same directory will use the same date 799317721Speter(for more information on sticky tags/dates, @pxref{Sticky tags}). 799417721Speter 7995102840Speter@samp{-D} is available with the @code{annotate}, @code{checkout}, 799617721Speter@code{diff}, @code{export}, @code{history}, 799717721Speter@code{rdiff}, @code{rtag}, and @code{update} commands. 799817721Speter(The @code{history} command uses this option in a 799944852Speterslightly different way; @pxref{history options}). 800017721Speter 800125839Speter@c What other formats should we accept? I don't want 800225839Speter@c to start accepting a whole mess of non-standard 800325839Speter@c new formats (there are a lot which are in wide use in 800425839Speter@c one context or another), but practicality does 800525839Speter@c dictate some level of flexibility. 800625839Speter@c * POSIX.2 (e.g. touch, ls output, date) and other 800725839Speter@c POSIX and/or de facto unix standards (e.g. at). The 800825839Speter@c practice here is too inconsistent to be of any use. 800925839Speter@c * VMS dates. This is not a formal standard, but 801025839Speter@c there is a published specification (see SYS$ASCTIM 801125839Speter@c and SYS$BINTIM in the _VMS System Services Reference 801225839Speter@c Manual_), it is implemented consistently in VMS 801325839Speter@c utilities, and VMS users will expect CVS running on 801425839Speter@c VMS to support this format (and if we're going to do 801525839Speter@c that, better to make CVS support it on all 801625839Speter@c platforms. Maybe). 801744852Speter@c 801825839Speter@c NOTE: The tar manual has some documentation for 801925839Speter@c getdate.y (just for our info; we don't want to 802025839Speter@c attempt to document all the formats accepted by 802125839Speter@c getdate.y). 802244852Speter@c 802325839Speter@c One more note: In output, CVS should consistently 802425839Speter@c use one date format, and that format should be one that 802525839Speter@c it accepts in input as well. The former isn't 802625839Speter@c really true (see survey below), and I'm not 802725839Speter@c sure that either of those formats is accepted in 802844852Speter@c input. 802944852Speter@c 803025839Speter@c cvs log 803125839Speter@c current 1996/01/02 13:45:31 803225839Speter@c Internet 02 Jan 1996 13:45:31 UT 803325839Speter@c ISO 1996-01-02 13:45:31 803425839Speter@c cvs ann 803525839Speter@c current 02-Jan-96 803625839Speter@c Internet-like 02 Jan 96 803725839Speter@c ISO 96-01-02 803825839Speter@c cvs status 803925839Speter@c current Tue Jun 11 02:54:53 1996 804025839Speter@c Internet [Tue,] 11 Jun 1996 02:54:53 804125839Speter@c ISO 1996-06-11 02:54:53 804225839Speter@c note: date possibly should be omitted entirely for 804325839Speter@c other reasons. 804425839Speter@c cvs editors 804525839Speter@c current Tue Jun 11 02:54:53 1996 GMT 804625839Speter@c cvs history 804725839Speter@c current 06/11 02:54 +0000 804825839Speter@c any others? 804925839Speter@c There is a good chance the proper solution has to 805025839Speter@c involve at least some level of letting the user 805125839Speter@c decide which format (with the default being the 805225839Speter@c formats CVS has always used; changing these might be 805325839Speter@c _very_ disruptive since scripts may very well be 805425839Speter@c parsing them). 805525839Speter@c 805625839Speter@c Another random bit of prior art concerning dates is 805725839Speter@c the strptime function which takes templates such as 805825839Speter@c "%m/%d/%y", and apparent a variant of getdate() 805925839Speter@c which also honors them. See 806025839Speter@c X/Open CAE Specification, System Interfaces and 806125839Speter@c Headers Issue 4, Version 2 (September 1994), in the 806225839Speter@c entry for getdate() on page 231 806325839Speter 806466525Speter@cindex Timezone, in input 806566525Speter@cindex Zone, time, in input 806625839SpeterA wide variety of date formats are supported by 806725839Speter@sc{cvs}. The most standard ones are ISO8601 (from the 806825839SpeterInternational Standards Organization) and the Internet 806925839Spetere-mail standard (specified in RFC822 as amended by 807025839SpeterRFC1123). 807125839Speter 807225839Speter@c Probably should be doing more to spell out just what 807325839Speter@c the rules are, rather than just giving examples. 807425839Speter@c But I want to keep this simple too. 807525839Speter@c So I don't know.... 807625839Speter@c A few specific issues: (1) Maybe should reassure 807725839Speter@c people that years after 2000 807844852Speter@c work (they are in the testsuite, so they do indeed 807925839Speter@c work). (2) What do two digit years 808025839Speter@c mean? Where do we accept them? (3) Local times can 808125839Speter@c be ambiguous or nonexistent if they fall during the 808225839Speter@c hour when daylight savings time goes into or out of 808325839Speter@c effect. Pretty obscure, so I'm not at all sure we 808425839Speter@c should be documenting the behavior in that case. 808525839SpeterISO8601 dates have many variants but a few examples 808625839Speterare: 808725839Speter 808825839Speter@example 808925839Speter1972-09-24 809025839Speter1972-09-24 20:05 809125839Speter@end example 809225839Speter@c I doubt we really accept all ISO8601 format dates 809325839Speter@c (for example, decimal hours like 1972-09-24 20,2) 809425839Speter@c I'm not sure we should, many of them are pretty 809525839Speter@c bizarre and it has lots of gratuitous multiple ways 809625839Speter@c to specify the same thing. 809725839Speter 809881404SpeterThere are a lot more ISO8601 date formats, and @sc{cvs} 809954427Speteraccepts many of them, but you probably don't want to 810054427Speterhear the @emph{whole} long story :-). 810125839Speter 810254427Speter@c Citing a URL here is kind of problematic given how 810354427Speter@c much they change and people who have old versions of 810454427Speter@c this manual, but in case we want to reinstate an 810554427Speter@c ISO8601 URL, a few are: 810625839Speter@c http://www.saqqara.demon.co.uk/datefmt.htm 810754427Speter@c http://www.cl.cam.ac.uk/~mgk25/iso-time.html 810854427Speter@c Citing some other ISO8601 source is probably even 810954427Speter@c worse :-). 811025839Speter 811125839SpeterIn addition to the dates allowed in Internet e-mail 811225839Speteritself, @sc{cvs} also allows some of the fields to be 811325839Speteromitted. For example: 811425839Speter@c FIXME: Need to figure out better, and document, 811525839Speter@c what we want to allow the user to omit. 811625839Speter@c NOTE: "omit" does not imply "reorder". 811725839Speter@c FIXME: Need to cite a web page describing how to get 811825839Speter@c RFC's. 811925839Speter 812025839Speter@example 812125839Speter24 Sep 1972 20:05 812225839Speter24 Sep 812325839Speter@end example 812425839Speter 812525839SpeterThe date is interpreted as being in the 812625839Speterlocal timezone, unless a specific timezone is 812725839Speterspecified. 812825839Speter 812925839SpeterThese two date formats are preferred. However, 813025839Speter@sc{cvs} currently accepts a wide variety of other date 813125839Speterformats. They are intentionally not documented here in 813225839Speterany detail, and future versions of @sc{cvs} might not 813325839Speteraccept all of them. 813432785Speter@c We should document and testsuite "now" and 813532785Speter@c "yesterday". "now" is mentioned in the FAQ and 813632785Speter@c "yesterday" is mentioned in this document (and the 813732785Speter@c message from "cvs import" suggesting a merge 813832785Speter@c command). What else? Probably some/all of the "3 813932785Speter@c weeks ago" family. 814044852Speter@c 814125839Speter@c Maybe at 814225839Speter@c some point have CVS start give warnings on "unofficial" 814325839Speter@c formats (many of which might be typos or user 814425839Speter@c misunderstandings, and/or formats people never/rarely 814525839Speter@c use to specify dates)? 814625839Speter 814725839SpeterOne such format is 814825839Speter@code{@var{month}/@var{day}/@var{year}}. This may 814925839Speterconfuse people who are accustomed to having the month 815025839Speterand day in the other order; @samp{1/4/96} is January 4, 815125839Speternot April 1. 815225839Speter 815317721SpeterRemember to quote the argument to the @samp{-D} 815417721Speterflag so that your shell doesn't interpret spaces as 815517721Speterargument separators. A command using the @samp{-D} 815617721Speterflag can look like this: 815717721Speter 815817721Speter@example 815917721Speter$ cvs diff -D "1 hour ago" cvs.texinfo 816017721Speter@end example 816117721Speter 816217721Speter@cindex Forcing a tag match 816317721Speter@item -f 816417721SpeterWhen you specify a particular date or tag to @sc{cvs} commands, they 816517721Speternormally ignore files that do not contain the tag (or did not 816617721Speterexist prior to the date) that you specified. Use the @samp{-f} option 816717721Speterif you want files retrieved even when there is no match for the 816817721Spetertag or date. (The most recent revision of the file 816944852Speterwill be used). 817017721Speter 817154427SpeterNote that even with @samp{-f}, a tag that you specify 817254427Spetermust exist (that is, in some file, not necessary in 817354427Speterevery file). This is so that @sc{cvs} will continue to 817454427Spetergive an error if you mistype a tag name. 817554427Speter 817617721Speter@need 800 817725839Speter@samp{-f} is available with these commands: 817825839Speter@code{annotate}, @code{checkout}, @code{export}, 817925839Speter@code{rdiff}, @code{rtag}, and @code{update}. 818017721Speter 8181128266Speter@strong{WARNING: The @code{commit} and @code{remove} 818232785Spetercommands also have a 818317721Speter@samp{-f} option, but it has a different behavior for 818432785Speterthose commands. See @ref{commit options}, and 8185128266Speter@ref{Removing files}.} 818617721Speter 818717721Speter@item -k @var{kflag} 818832785SpeterAlter the default processing of keywords. 8189177391SobrienSee @ref{Keyword substitution}, for the meaning of 819017721Speter@var{kflag}. Your @var{kflag} specification is 819117721Speter@dfn{sticky} when you use it to create a private copy 819217721Speterof a source file; that is, when you use this option 819317721Speterwith the @code{checkout} or @code{update} commands, 819417721Speter@sc{cvs} associates your selected @var{kflag} with the 819517721Speterfile, and continues to use it with future update 819617721Spetercommands on the same file until you specify otherwise. 819717721Speter 819817721SpeterThe @samp{-k} option is available with the @code{add}, 8199175261Sobrien@code{checkout}, @code{diff}, @code{rdiff}, @code{import} and 820017721Speter@code{update} commands. 820117721Speter 820217721Speter@item -l 820317721SpeterLocal; run only in current working directory, rather than 820444852Speterrecursing through subdirectories. 820517721Speter 820625839SpeterAvailable with the following commands: @code{annotate}, @code{checkout}, 820725839Speter@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 820825839Speter@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, 820925839Speter@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 821025839Speterand @code{watchers}. 821117721Speter 821217721Speter@cindex Editor, avoiding invocation of 821317721Speter@cindex Avoiding editor invocation 821417721Speter@item -m @var{message} 821517721SpeterUse @var{message} as log information, instead of 821617721Speterinvoking an editor. 821717721Speter 821817721SpeterAvailable with the following commands: @code{add}, 821917721Speter@code{commit} and @code{import}. 822017721Speter 822117721Speter@item -n 8222128266SpeterDo not run any tag program. (A program can be 8223128266Speterspecified to run in the modules 822444852Speterdatabase (@pxref{modules}); this option bypasses it). 822517721Speter 8226175261Sobrien@strong{This is not the same as the @samp{cvs -n} 8227128266Speterprogram option, which you can specify to the left of a cvs command!} 822817721Speter 8229175261SobrienAvailable with the @code{checkout}, @code{export}, 823017721Speterand @code{rtag} commands. 823117721Speter 823217721Speter@item -P 823332785SpeterPrune empty directories. See @ref{Removing directories}. 823417721Speter 823517721Speter@item -p 823617721SpeterPipe the files retrieved from the repository to standard output, 823717721Speterrather than writing them in the current directory. Available 823817721Speterwith the @code{checkout} and @code{update} commands. 823917721Speter 824025839Speter@item -R 824125839SpeterProcess directories recursively. This is on by default. 824217721Speter 824325839SpeterAvailable with the following commands: @code{annotate}, @code{checkout}, 824425839Speter@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 824525839Speter@code{rdiff}, @code{remove}, @code{rtag}, 824625839Speter@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 824725839Speterand @code{watchers}. 824825839Speter 824917721Speter@item -r @var{tag} 825032785Speter@cindex HEAD, special tag 825132785Speter@cindex BASE, special tag 825217721SpeterUse the revision specified by the @var{tag} argument instead of the 825317721Speterdefault @dfn{head} revision. As well as arbitrary tags defined 825417721Speterwith the @code{tag} or @code{rtag} command, two special tags are 825517721Speteralways available: @samp{HEAD} refers to the most recent version 825617721Speteravailable in the repository, and @samp{BASE} refers to the 825717721Speterrevision you last checked out into the current working directory. 825817721Speter 825925839Speter@c FIXME: What does HEAD really mean? I believe that 826025839Speter@c the current answer is the head of the default branch 826125839Speter@c for all cvs commands except diff. For diff, it 826225839Speter@c seems to be (a) the head of the trunk (or the default 826325839Speter@c branch?) if there is no sticky tag, (b) the head of the 826444852Speter@c branch for the sticky tag, if there is a sticky tag. 826544852Speter@c (b) is ugly as it differs 826625839Speter@c from what HEAD means for other commands, but people 826732785Speter@c and/or scripts are quite possibly used to it. 826832785Speter@c See "head" tests in sanity.sh. 826932785Speter@c Probably the best fix is to introduce two new 827032785Speter@c special tags, ".thead" for the head of the trunk, 827132785Speter@c and ".bhead" for the head of the current branch. 827232785Speter@c Then deprecate HEAD. This has the advantage of 827354427Speter@c not surprising people with a change to HEAD, and a 827432785Speter@c side benefit of also phasing out the poorly-named 827532785Speter@c HEAD (see discussion of reserved tag names in node 827632785Speter@c "Tags"). Of course, .thead and .bhead should be 827732785Speter@c carefully implemented (with the implementation the 827832785Speter@c same for "diff" as for everyone else), test cases 827932785Speter@c written (similar to the ones in "head"), new tests 828032785Speter@c cases written for things like default branches, &c. 828125839Speter 828225839SpeterThe tag specification is sticky when you use this 828325839Speter@c option 828417721Speterwith @code{checkout} or @code{update} to make your own 828517721Spetercopy of a file: @sc{cvs} remembers the tag and continues to use it on 828617721Speterfuture update commands, until you specify otherwise (for more information 828754427Speteron sticky tags/dates, @pxref{Sticky tags}). 828817721Speter 828954427SpeterThe tag can be either a symbolic or numeric tag, as 829054427Speterdescribed in @ref{Tags}, or the name of a branch, as 829154427Speterdescribed in @ref{Branching and merging}. 8292175261SobrienWhen a command expects a specific revision, 8293175261Sobrienthe name of a branch is interpreted as the most recent 8294175261Sobrienrevision on that branch. 829554427Speter 829617721SpeterSpecifying the @samp{-q} global option along with the 829717721Speter@samp{-r} command option is often useful, to suppress 829832785Speterthe warning messages when the @sc{rcs} file 829917721Speterdoes not contain the specified tag. 830017721Speter 8301175261Sobrien@strong{This is not the same as the overall @samp{cvs -r} option, 8302128266Speterwhich you can specify to the left of a @sc{cvs} command!} 830317721Speter 8304175261Sobrien@samp{-r} is available with the @code{annotate}, @code{checkout}, 8305175261Sobrien@code{commit}, @code{diff}, @code{history}, @code{export}, @code{rdiff}, 830617721Speter@code{rtag}, and @code{update} commands. 830717721Speter 830825839Speter@item -W 830925839SpeterSpecify file names that should be filtered. You can 831025839Speteruse this option repeatedly. The spec can be a file 831125839Spetername pattern of the same type that you can specify in 831225839Speterthe @file{.cvswrappers} file. 831332785SpeterAvailable with the following commands: @code{import}, 831425839Speterand @code{update}. 831517721Speter 831617721Speter@end table 831717721Speter 831817721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8319177391Sobrien@node add 8320177391Sobrien@appendixsec add---Add files and directories to the repository 8321177391Sobrien@cindex add (subcommand) 8322177391Sobrien 8323177391Sobrien@itemize @bullet 8324177391Sobrien@item 8325177391SobrienSynopsis: add [-k rcs-kflag] [-m message] files... 8326177391Sobrien@item 8327177391SobrienRequires: repository, working directory. 8328177391Sobrien@item 8329177391SobrienChanges: repository, working directory. 8330177391Sobrien@end itemize 8331177391Sobrien 8332177391SobrienThe @code{add} command is used to present new files 8333177391Sobrienand directories for addition into the @sc{cvs} 8334177391Sobrienrepository. When @code{add} is used on a directory, 8335177391Sobriena new directory is created in the repository 8336177391Sobrienimmediately. When used on a file, only the working 8337177391Sobriendirectory is updated. Changes to the repository are 8338177391Sobriennot made until the @code{commit} command is used on 8339177391Sobrienthe newly added file. 8340177391Sobrien 8341177391SobrienThe @code{add} command also resurrects files that 8342177391Sobrienhave been previously removed. This can be done 8343177391Sobrienbefore or after the @code{commit} command is used 8344177391Sobriento finalize the removal of files. Resurrected files 8345177391Sobrienare restored into the working directory at the time 8346177391Sobrienthe @code{add} command is executed. 8347177391Sobrien 8348177391Sobrien@menu 8349177391Sobrien* add options:: add options 8350177391Sobrien* add examples:: add examples 8351177391Sobrien@end menu 8352177391Sobrien 8353177391Sobrien@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8354177391Sobrien@node add options 8355177391Sobrien@appendixsubsec add options 8356177391Sobrien 8357177391SobrienThese standard options are supported by @code{add} 8358177391Sobrien(@pxref{Common options}, for a complete description of 8359177391Sobrienthem): 8360177391Sobrien 8361177391Sobrien@table @code 8362177391Sobrien@item -k @var{kflag} 8363177391SobrienProcess keywords according to @var{kflag}. See 8364177391Sobrien@ref{Keyword substitution}. 8365177391SobrienThis option is sticky; future updates of 8366177391Sobrienthis file in this working directory will use the same 8367177391Sobrien@var{kflag}. The @code{status} command can be viewed 8368177391Sobriento see the sticky options. For more information on 8369177391Sobrienthe @code{status} command, @xref{Invoking CVS}. 8370177391Sobrien 8371177391Sobrien@item -m @var{message} 8372177391SobrienUse @var{message} as the log message, instead of 8373177391Sobrieninvoking an editor. 8374177391Sobrien@end table 8375177391Sobrien 8376177391Sobrien@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8377177391Sobrien@node add examples 8378177391Sobrien@appendixsubsec add examples 8379177391Sobrien 8380177391Sobrien@appendixsubsubsec Adding a directory 8381177391Sobrien 8382177391Sobrien@example 8383177391Sobrien$ mkdir doc 8384177391Sobrien$ cvs add doc 8385177391SobrienDirectory /path/to/repository/doc added to the repository 8386177391Sobrien@end example 8387177391Sobrien 8388177391Sobrien@appendixsubsubsec Adding a file 8389177391Sobrien 8390177391Sobrien@example 8391177391Sobrien 8392177391Sobrien$ >TODO 8393177391Sobrien$ cvs add TODO 8394177391Sobriencvs add: scheduling file `TODO' for addition 8395177391Sobriencvs add: use 'cvs commit' to add this file permanently 8396177391Sobrien@end example 8397177391Sobrien 8398177391Sobrien@appendixsubsubsec Undoing a @code{remove} command 8399177391Sobrien 8400177391Sobrien@example 8401177391Sobrien$ rm -f makefile 8402177391Sobrien$ cvs remove makefile 8403177391Sobriencvs remove: scheduling `makefile' for removal 8404177391Sobriencvs remove: use 'cvs commit' to remove this file permanently 8405177391Sobrien$ cvs add makefile 8406177391SobrienU makefile 8407177391Sobriencvs add: makefile, version 1.2, resurrected 8408177391Sobrien@end example 8409177391Sobrien 8410177391Sobrien@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 841117721Speter@node admin 841232785Speter@appendixsec admin---Administration 841317721Speter@cindex Admin (subcommand) 841417721Speter 841517721Speter@itemize @bullet 841617721Speter@item 841717721SpeterRequires: repository, working directory. 841817721Speter@item 841917721SpeterChanges: repository. 842017721Speter@item 842117721SpeterSynonym: rcs 842217721Speter@end itemize 842317721Speter 842432785SpeterThis is the @sc{cvs} interface to assorted 842532785Speteradministrative facilities. Some of them have 842632785Speterquestionable usefulness for @sc{cvs} but exist for 842732785Speterhistorical purposes. Some of the questionable options 842832785Speterare likely to disappear in the future. This command 842932785Speter@emph{does} work recursively, so extreme care should be 843032785Speterused. 843117721Speter 843254427Speter@cindex cvsadmin 843332785SpeterOn unix, if there is a group named @code{cvsadmin}, 843454427Speteronly members of that group can run @code{cvs admin} 843554427Speter(except for the @code{cvs admin -k} command, which can 843654427Speterbe run by anybody). This group should exist on the 843754427Speterserver, or any system running the non-client/server 843854427Speter@sc{cvs}. To disallow @code{cvs admin} for all users, 843954427Spetercreate a group with no users in it. On NT, the 844054427Speter@code{cvsadmin} feature does not exist and all users 844154427Spetercan run @code{cvs admin}. 844217721Speter 844317721Speter@menu 844417721Speter* admin options:: admin options 844517721Speter@end menu 844617721Speter 844717721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844817721Speter@node admin options 844917721Speter@appendixsubsec admin options 845017721Speter 845132785SpeterSome of these options have questionable usefulness for 845232785Speter@sc{cvs} but exist for historical purposes. Some even 845332785Spetermake it impossible to use @sc{cvs} until you undo the 845432785Spetereffect! 845517721Speter 845617721Speter@table @code 845717721Speter@item -A@var{oldfile} 845817721SpeterMight not work together with @sc{cvs}. Append the 845917721Speteraccess list of @var{oldfile} to the access list of the 846017721Speter@sc{rcs} file. 846117721Speter 846217721Speter@item -a@var{logins} 846317721SpeterMight not work together with @sc{cvs}. Append the 846417721Speterlogin names appearing in the comma-separated list 846517721Speter@var{logins} to the access list of the @sc{rcs} file. 846617721Speter 846717721Speter@item -b[@var{rev}] 846832785SpeterSet the default branch to @var{rev}. In @sc{cvs}, you 846932785Speternormally do not manipulate default branches; sticky 847032785Spetertags (@pxref{Sticky tags}) are a better way to decide 847132785Speterwhich branch you want to work on. There is one reason 847232785Speterto run @code{cvs admin -b}: to revert to the vendor's 847325839Speterversion when using vendor branches (@pxref{Reverting 847425839Speterlocal changes}). 847532785SpeterThere can be no space between @samp{-b} and its argument. 847632785Speter@c Hmm, we don't document the usage where rev is 847732785Speter@c omitted. Maybe that usage can/should be deprecated 847832785Speter@c (and replaced with -bHEAD or something?) (so we can toss 847932785Speter@c the optional argument). Note that -bHEAD does not 848032785Speter@c work, as of 17 Sep 1997, but probably will once "cvs 848132785Speter@c admin" is internal to CVS. 848217721Speter 848366525Speter@cindex Comment leader 848417721Speter@item -c@var{string} 848532785SpeterSets the comment leader to @var{string}. The comment 848632785Speterleader is not used by current versions of @sc{cvs} or 848732785Speter@sc{rcs} 5.7. Therefore, you can almost surely not 8488177391Sobrienworry about it. See @ref{Keyword substitution}. 848917721Speter 849017721Speter@item -e[@var{logins}] 849117721SpeterMight not work together with @sc{cvs}. Erase the login 849217721Speternames appearing in the comma-separated list 849317721Speter@var{logins} from the access list of the RCS file. If 849417721Speter@var{logins} is omitted, erase the entire access list. 849554427SpeterThere can be no space between @samp{-e} and its argument. 849617721Speter 849717721Speter@item -I 849817721SpeterRun interactively, even if the standard input is not a 849932785Speterterminal. This option does not work with the 850032785Speterclient/server @sc{cvs} and is likely to disappear in 850132785Spetera future release of @sc{cvs}. 850217721Speter 850317721Speter@item -i 850432785SpeterUseless with @sc{cvs}. This creates and initializes a 850532785Speternew @sc{rcs} file, without depositing a revision. With 850632785Speter@sc{cvs}, add files with the @code{cvs add} command 850732785Speter(@pxref{Adding files}). 850817721Speter 850917721Speter@item -k@var{subst} 851032785SpeterSet the default keyword 8511177391Sobriensubstitution to @var{subst}. See @ref{Keyword 851217721Spetersubstitution}. Giving an explicit @samp{-k} option to 851317721Speter@code{cvs update}, @code{cvs export}, or @code{cvs 851417721Spetercheckout} overrides this default. 851517721Speter 851617721Speter@item -l[@var{rev}] 851717721SpeterLock the revision with number @var{rev}. If a branch 851817721Speteris given, lock the latest revision on that branch. If 851917721Speter@var{rev} is omitted, lock the latest revision on the 852032785Speterdefault branch. There can be no space between 852132785Speter@samp{-l} and its argument. 852217721Speter 852317721SpeterThis can be used in conjunction with the 852417721Speter@file{rcslock.pl} script in the @file{contrib} 852517721Speterdirectory of the @sc{cvs} source distribution to 852617721Speterprovide reserved checkouts (where only one user can be 852717721Speterediting a given file at a time). See the comments in 852817721Speterthat file for details (and see the @file{README} file 852917721Speterin that directory for disclaimers about the unsupported 853017721Speternature of contrib). According to comments in that 853117721Speterfile, locking must set to strict (which is the default). 853217721Speter 853317721Speter@item -L 853417721SpeterSet locking to strict. Strict locking means that the 853517721Speterowner of an RCS file is not exempt from locking for 853617721Spetercheckin. For use with @sc{cvs}, strict locking must be 853717721Speterset; see the discussion under the @samp{-l} option above. 853817721Speter 853917721Speter@cindex Changing a log message 854017721Speter@cindex Replacing a log message 854117721Speter@cindex Correcting a log message 854217721Speter@cindex Fixing a log message 854317721Speter@cindex Log message, correcting 854417721Speter@item -m@var{rev}:@var{msg} 854517721SpeterReplace the log message of revision @var{rev} with 854617721Speter@var{msg}. 854717721Speter 854832785Speter@c The rcs -M option, to suppress sending mail, has never been 854932785Speter@c documented as a cvs admin option. 855032785Speter 855117721Speter@item -N@var{name}[:[@var{rev}]] 855217721SpeterAct like @samp{-n}, except override any previous 855332785Speterassignment of @var{name}. For use with magic branches, 855432785Spetersee @ref{Magic branch numbers}. 855517721Speter 855617721Speter@item -n@var{name}[:[@var{rev}]] 855717721SpeterAssociate the symbolic name @var{name} with the branch 855817721Speteror revision @var{rev}. It is normally better to use 855917721Speter@samp{cvs tag} or @samp{cvs rtag} instead. Delete the 856017721Spetersymbolic name if both @samp{:} and @var{rev} are 856117721Speteromitted; otherwise, print an error message if 856217721Speter@var{name} is already associated with another number. 856317721SpeterIf @var{rev} is symbolic, it is expanded before 856417721Speterassociation. A @var{rev} consisting of a branch number 856517721Speterfollowed by a @samp{.} stands for the current latest 856617721Speterrevision in the branch. A @samp{:} with an empty 856717721Speter@var{rev} stands for the current latest revision on the 856817721Speterdefault branch, normally the trunk. For example, 856932785Speter@samp{cvs admin -n@var{name}:} associates @var{name} with the 857032785Spetercurrent latest revision of all the RCS files; 857132785Speterthis contrasts with @samp{cvs admin -n@var{name}:$} which 857217721Speterassociates @var{name} with the revision numbers 857317721Speterextracted from keyword strings in the corresponding 857417721Speterworking files. 857517721Speter 857617721Speter@cindex Deleting revisions 857717721Speter@cindex Outdating revisions 857817721Speter@cindex Saving space 857917721Speter@item -o@var{range} 858017721SpeterDeletes (@dfn{outdates}) the revisions given by 858132785Speter@var{range}. 858232785Speter 858332785SpeterNote that this command can be quite dangerous unless 858432785Speteryou know @emph{exactly} what you are doing (for example 858532785Spetersee the warnings below about how the 858632785Speter@var{rev1}:@var{rev2} syntax is confusing). 858732785Speter 858832785SpeterIf you are short on disc this option might help you. 858932785SpeterBut think twice before using it---there is no way short 859032785Speterof restoring the latest backup to undo this command! 859132785SpeterIf you delete different revisions than you planned, 859281404Spetereither due to carelessness or (heaven forbid) a @sc{cvs} 859332785Speterbug, there is no opportunity to correct the error 859432785Speterbefore the revisions are deleted. It probably would be 859532785Spetera good idea to experiment on a copy of the repository 859632785Speterfirst. 859732785Speter 859832785SpeterSpecify @var{range} in one of the following ways: 859932785Speter 860032785Speter@table @code 860132785Speter@item @var{rev1}::@var{rev2} 860232785SpeterCollapse all revisions between rev1 and rev2, so that 860381404Speter@sc{cvs} only stores the differences associated with going 860432785Speterfrom rev1 to rev2, not intermediate steps. For 860532785Speterexample, after @samp{-o 1.3::1.5} one can retrieve 860632785Speterrevision 1.3, revision 1.5, or the differences to get 860732785Speterfrom 1.3 to 1.5, but not the revision 1.4, or the 860832785Speterdifferences between 1.3 and 1.4. Other examples: 860932785Speter@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 861032785Spetereffect, because there are no intermediate revisions to 861132785Speterremove. 861232785Speter 861332785Speter@item ::@var{rev} 861432785SpeterCollapse revisions between the beginning of the branch 861532785Spetercontaining @var{rev} and @var{rev} itself. The 861632785Speterbranchpoint and @var{rev} are left intact. For 861732785Speterexample, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 861832785Speterrevision 1.3.2.5, and everything in between, but leaves 861932785Speter1.3 and 1.3.2.6 intact. 862032785Speter 862132785Speter@item @var{rev}:: 862232785SpeterCollapse revisions between @var{rev} and the end of the 862332785Speterbranch containing @var{rev}. Revision @var{rev} is 862432785Speterleft intact but the head revision is deleted. 862532785Speter 862632785Speter@item @var{rev} 862732785SpeterDelete the revision @var{rev}. For example, @samp{-o 862832785Speter1.3} is equivalent to @samp{-o 1.2::1.4}. 862932785Speter 863032785Speter@item @var{rev1}:@var{rev2} 863132785SpeterDelete the revisions from @var{rev1} to @var{rev2}, 863232785Speterinclusive, on the same branch. One will not be able to 863332785Speterretrieve @var{rev1} or @var{rev2} or any of the 863432785Speterrevisions in between. For example, the command 863532785Speter@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 863632785SpeterIt means to delete revisions up to, and including, the 863732785Spetertag R_1_02. But beware! If there are files that have not 863832785Speterchanged between R_1_02 and R_1_03 the file will have 863932785Speter@emph{the same} numerical revision number assigned to 864032785Speterthe tags R_1_02 and R_1_03. So not only will it be 864132785Speterimpossible to retrieve R_1_02; R_1_03 will also have to 864232785Speterbe restored from the tapes! In most cases you want to 864332785Speterspecify @var{rev1}::@var{rev2} instead. 864432785Speter 864532785Speter@item :@var{rev} 864632785SpeterDelete revisions from the beginning of the 864717721Speterbranch containing @var{rev} up to and including 864832785Speter@var{rev}. 864932785Speter 865032785Speter@item @var{rev}: 865132785SpeterDelete revisions from revision @var{rev}, including 865232785Speter@var{rev} itself, to the end of the branch containing 865332785Speter@var{rev}. 865432785Speter@end table 865532785Speter 865632785SpeterNone of the revisions to be deleted may have 865717721Speterbranches or locks. 865817721Speter 865932785SpeterIf any of the revisions to be deleted have symbolic 866032785Speternames, and one specifies one of the @samp{::} syntaxes, 866132785Speterthen @sc{cvs} will give an error and not delete any 866232785Speterrevisions. If you really want to delete both the 866332785Spetersymbolic names and the revisions, first delete the 866432785Spetersymbolic names with @code{cvs tag -d}, then run 866532785Speter@code{cvs admin -o}. If one specifies the 866632785Speternon-@samp{::} syntaxes, then @sc{cvs} will delete the 866732785Speterrevisions but leave the symbolic names pointing to 866832785Speternonexistent revisions. This behavior is preserved for 866932785Spetercompatibility with previous versions of @sc{cvs}, but 867032785Speterbecause it isn't very useful, in the future it may 867132785Speterchange to be like the @samp{::} case. 867232785Speter 867317721SpeterDue to the way @sc{cvs} handles branches @var{rev} 867417721Spetercannot be specified symbolically if it is a branch. 8675177391SobrienSee @ref{Magic branch numbers} for an explanation. 867632785Speter@c FIXME: is this still true? I suspect not. 867717721Speter 867817721SpeterMake sure that no-one has checked out a copy of the 867917721Speterrevision you outdate. Strange things will happen if he 868017721Speterstarts to edit it and tries to check it back in. For 868117721Speterthis reason, this option is not a good way to take back 868217721Spetera bogus commit; commit a new revision undoing the bogus 868317721Speterchange instead (@pxref{Merging two revisions}). 868417721Speter 868517721Speter@item -q 868617721SpeterRun quietly; do not print diagnostics. 868717721Speter 868817721Speter@item -s@var{state}[:@var{rev}] 868917721SpeterUseful with @sc{cvs}. Set the state attribute of the 869017721Speterrevision @var{rev} to @var{state}. If @var{rev} is a 869117721Speterbranch number, assume the latest revision on that 869217721Speterbranch. If @var{rev} is omitted, assume the latest 869317721Speterrevision on the default branch. Any identifier is 869417721Speteracceptable for @var{state}. A useful set of states is 869517721Speter@samp{Exp} (for experimental), @samp{Stab} (for 869617721Speterstable), and @samp{Rel} (for released). By default, 869717721Speterthe state of a new revision is set to @samp{Exp} when 869817721Speterit is created. The state is visible in the output from 869917721Speter@var{cvs log} (@pxref{log}), and in the 8700130303Speter@samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords 870117721Speter(@pxref{Keyword substitution}). Note that @sc{cvs} 8702175261Sobrienuses the @code{dead} state for its own purposes (@pxref{Attic}); to 870317721Spetertake a file to or from the @code{dead} state use 8704175261Sobriencommands like @code{cvs remove} and @code{cvs add} 8705175261Sobrien(@pxref{Adding and removing}), not @code{cvs admin -s}. 870617721Speter 870717721Speter@item -t[@var{file}] 870817721SpeterUseful with @sc{cvs}. Write descriptive text from the 870917721Spetercontents of the named @var{file} into the RCS file, 871017721Speterdeleting the existing text. The @var{file} pathname 871132785Spetermay not begin with @samp{-}. The descriptive text can be seen in the 871232785Speteroutput from @samp{cvs log} (@pxref{log}). 871332785SpeterThere can be no space between @samp{-t} and its argument. 871432785Speter 871532785SpeterIf @var{file} is omitted, 871617721Speterobtain the text from standard input, terminated by 871717721Speterend-of-file or by a line containing @samp{.} by itself. 871817721SpeterPrompt for the text if interaction is possible; see 871966525Speter@samp{-I}. 872017721Speter 872117721Speter@item -t-@var{string} 872217721SpeterSimilar to @samp{-t@var{file}}. Write descriptive text 872317721Speterfrom the @var{string} into the @sc{rcs} file, deleting 872417721Speterthe existing text. 872532785SpeterThere can be no space between @samp{-t} and its argument. 872617721Speter 872732785Speter@c The rcs -T option, do not update last-mod time for 872832785Speter@c minor changes, has never been documented as a 872932785Speter@c cvs admin option. 873032785Speter 873117721Speter@item -U 873217721SpeterSet locking to non-strict. Non-strict locking means 873317721Speterthat the owner of a file need not lock a revision for 873417721Spetercheckin. For use with @sc{cvs}, strict locking must be 873517721Speterset; see the discussion under the @samp{-l} option 873617721Speterabove. 873717721Speter 873817721Speter@item -u[@var{rev}] 873917721SpeterSee the option @samp{-l} above, for a discussion of 874017721Speterusing this option with @sc{cvs}. Unlock the revision 874117721Speterwith number @var{rev}. If a branch is given, unlock 874217721Speterthe latest revision on that branch. If @var{rev} is 874317721Speteromitted, remove the latest lock held by the caller. 874481404SpeterNormally, only the locker of a revision may unlock it; 874581404Spetersomebody else unlocking a revision breaks the lock. 874681404SpeterThis causes the original locker to be sent a @code{commit} 874781404Speternotification (@pxref{Getting Notified}). 874832785SpeterThere can be no space between @samp{-u} and its argument. 874917721Speter 875017721Speter@item -V@var{n} 875132785SpeterIn previous versions of @sc{cvs}, this option meant to 875232785Speterwrite an @sc{rcs} file which would be acceptable to 875332785Speter@sc{rcs} version @var{n}, but it is now obsolete and 875432785Speterspecifying it will produce an error. 875532785Speter@c Note that -V without an argument has never been 875632785Speter@c documented as a cvs admin option. 875717721Speter 875817721Speter@item -x@var{suffixes} 875932785SpeterIn previous versions of @sc{cvs}, this was documented 876032785Speteras a way of specifying the names of the @sc{rcs} 876132785Speterfiles. However, @sc{cvs} has always required that the 876232785Speter@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 876332785Speterthis option has never done anything useful. 876432785Speter 876532785Speter@c The rcs -z option, to specify the timezone, has 876632785Speter@c never been documented as a cvs admin option. 876717721Speter@end table 876817721Speter 876917721Speter 877017721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8771130303Speter@node annotate 8772130303Speter@appendixsec annotate---What revision modified each line of a file? 8773130303Speter@cindex annotate (subcommand) 8774130303Speter 8775130303Speter@itemize @bullet 8776130303Speter@item 8777130303SpeterSynopsis: annotate [options] files@dots{} 8778130303Speter@item 8779130303SpeterRequires: repository. 8780130303Speter@item 8781177391SobrienSynonym: blame 8782177391Sobrien@item 8783130303SpeterChanges: nothing. 8784130303Speter@end itemize 8785130303Speter 8786130303SpeterFor each file in @var{files}, print the head revision 8787130303Speterof the trunk, together with information on the last 8788130303Spetermodification for each line. 8789130303Speter 8790130303Speter@menu 8791130303Speter* annotate options:: annotate options 8792130303Speter* annotate example:: annotate example 8793130303Speter@end menu 8794130303Speter 8795130303Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8796130303Speter@node annotate options 8797130303Speter@appendixsubsec annotate options 8798130303Speter 8799130303SpeterThese standard options are supported by @code{annotate} 8800177391Sobrien(@pxref{Common options} for a complete description of 8801130303Speterthem): 8802130303Speter 8803130303Speter@table @code 8804130303Speter@item -l 8805130303SpeterLocal directory only, no recursion. 8806130303Speter 8807130303Speter@item -R 8808130303SpeterProcess directories recursively. 8809130303Speter 8810130303Speter@item -f 8811130303SpeterUse head revision if tag/date not found. 8812130303Speter 8813130303Speter@item -F 8814130303SpeterAnnotate binary files. 8815130303Speter 8816130303Speter@item -r @var{revision} 8817130303SpeterAnnotate file as of specified revision/tag. 8818130303Speter 8819130303Speter@item -D @var{date} 8820130303SpeterAnnotate file as of specified date. 8821130303Speter@end table 8822130303Speter 8823130303Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8824130303Speter@node annotate example 8825130303Speter@appendixsubsec annotate example 8826130303Speter 8827130303SpeterFor example: 8828130303Speter 8829130303Speter@example 8830130303Speter$ cvs annotate ssfile 8831130303SpeterAnnotations for ssfile 8832130303Speter*************** 8833130303Speter1.1 (mary 27-Mar-96): ssfile line 1 8834130303Speter1.2 (joe 28-Mar-96): ssfile line 2 8835130303Speter@end example 8836130303Speter 8837130303SpeterThe file @file{ssfile} currently contains two lines. 8838130303SpeterThe @code{ssfile line 1} line was checked in by 8839130303Speter@code{mary} on March 27. Then, on March 28, @code{joe} 8840130303Speteradded a line @code{ssfile line 2}, without modifying 8841130303Speterthe @code{ssfile line 1} line. This report doesn't 8842130303Spetertell you anything about lines which have been deleted 8843130303Speteror replaced; you need to use @code{cvs diff} for that 8844130303Speter(@pxref{diff}). 8845130303Speter 8846130303SpeterThe options to @code{cvs annotate} are listed in 8847130303Speter@ref{Invoking CVS}, and can be used to select the files 8848130303Speterand revisions to annotate. The options are described 8849130303Speterin more detail there and in @ref{Common options}. 8850130303Speter 8851130303Speter@c FIXME: maybe an example using the options? Just 8852130303Speter@c what it means to select a revision might be worth a 8853130303Speter@c few words of explanation ("you want to see who 8854130303Speter@c changed this line *before* 1.4"...). 8855130303Speter 8856130303Speter 8857130303Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 885817721Speter@node checkout 885917721Speter@appendixsec checkout---Check out sources for editing 886066525Speter@cindex checkout (subcommand) 886166525Speter@cindex co (subcommand) 886217721Speter 886317721Speter@itemize @bullet 886417721Speter@item 886517721SpeterSynopsis: checkout [options] modules@dots{} 886617721Speter@item 886717721SpeterRequires: repository. 886817721Speter@item 886917721SpeterChanges: working directory. 887017721Speter@item 887117721SpeterSynonyms: co, get 887217721Speter@end itemize 887317721Speter 887432785SpeterCreate or update a working directory containing copies of the 887517721Spetersource files specified by @var{modules}. You must execute 887617721Speter@code{checkout} before using most of the other @sc{cvs} 887717721Spetercommands, since most of them operate on your working 887817721Speterdirectory. 887917721Speter 888032785SpeterThe @var{modules} are either 888117721Spetersymbolic names for some 888217721Spetercollection of source directories and files, or paths to 888317721Speterdirectories or files in the repository. The symbolic 888417721Speternames are defined in the @samp{modules} file. 8885177391SobrienSee @ref{modules}. 888625839Speter@c Needs an example, particularly of the non-"modules" 888725839Speter@c case but probably of both. 888817721Speter 888932785Speter@c FIXME: this seems like a very odd place to introduce 889032785Speter@c people to how CVS works. The bit about unreserved 889132785Speter@c checkouts is also misleading as it depends on how 889232785Speter@c things are set up. 889317721SpeterDepending on the modules you specify, @code{checkout} may 889417721Speterrecursively create directories and populate them with 889517721Speterthe appropriate source files. You can then edit these 889617721Spetersource files at any time (regardless of whether other 889717721Spetersoftware developers are editing their own copies of the 889817721Spetersources); update them to include new changes applied by 889917721Speterothers to the source repository; or commit your work as 890017721Spetera permanent change to the source repository. 890117721Speter 890217721SpeterNote that @code{checkout} is used to create 890317721Speterdirectories. The top-level directory created is always 890417721Speteradded to the directory where @code{checkout} is 890517721Speterinvoked, and usually has the same name as the specified 890617721Spetermodule. In the case of a module alias, the created 890717721Spetersub-directory may have a different name, but you can be 890817721Spetersure that it will be a sub-directory, and that 890917721Speter@code{checkout} will show the relative path leading to 891017721Spetereach file as it is extracted into your private work 891117721Speterarea (unless you specify the @samp{-Q} global option). 891217721Speter 891317721SpeterThe files created by @code{checkout} are created 891417721Speterread-write, unless the @samp{-r} option to @sc{cvs} 891517721Speter(@pxref{Global options}) is specified, the 891617721Speter@code{CVSREAD} environment variable is specified 891717721Speter(@pxref{Environment variables}), or a watch is in 891817721Spetereffect for that file (@pxref{Watches}). 891917721Speter 892032785SpeterNote that running @code{checkout} on a directory that was already 892132785Speterbuilt by a prior @code{checkout} is also permitted. 892232785SpeterThis is similar to specifying the @samp{-d} option 892332785Speterto the @code{update} command in the sense that new 892417721Speterdirectories that have been created in the repository 892532785Speterwill appear in your work area. 892632785SpeterHowever, @code{checkout} takes a module name whereas 892732785Speter@code{update} takes a directory name. Also 892832785Speterto use @code{checkout} this way it must be run from the 892932785Spetertop level directory (where you originally ran 893032785Speter@code{checkout} from), so before you run 893132785Speter@code{checkout} to update an existing directory, don't 893232785Speterforget to change your directory to the top level 893332785Speterdirectory. 893417721Speter 8935177391SobrienFor the output produced by the @code{checkout} command, 8936177391Sobrien@xref{update output}. 893725839Speter 893817721Speter@menu 893917721Speter* checkout options:: checkout options 894017721Speter* checkout examples:: checkout examples 894117721Speter@end menu 894217721Speter 894317721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894417721Speter@node checkout options 894517721Speter@appendixsubsec checkout options 894617721Speter 894717721SpeterThese standard options are supported by @code{checkout} 8948177391Sobrien(@pxref{Common options} for a complete description of 894917721Speterthem): 895017721Speter 895117721Speter@table @code 895217721Speter@item -D @var{date} 895317721SpeterUse the most recent revision no later than @var{date}. 895417721SpeterThis option is sticky, and implies @samp{-P}. See 8955177391Sobrien@ref{Sticky tags} for more information on sticky tags/dates. 895617721Speter 895717721Speter@item -f 895817721SpeterOnly useful with the @samp{-D @var{date}} or @samp{-r 895917721Speter@var{tag}} flags. If no matching revision is found, 896017721Speterretrieve the most recent revision (instead of ignoring 896117721Speterthe file). 896217721Speter 896317721Speter@item -k @var{kflag} 896432785SpeterProcess keywords according to @var{kflag}. See 896532785Speter@ref{Keyword substitution}. 896632785SpeterThis option is sticky; future updates of 896717721Speterthis file in this working directory will use the same 896817721Speter@var{kflag}. The @code{status} command can be viewed 8969177391Sobriento see the sticky options. See @ref{Invoking CVS} for 897025839Spetermore information on the @code{status} command. 897117721Speter 897217721Speter@item -l 897317721SpeterLocal; run only in current working directory. 897417721Speter 897517721Speter@item -n 897617721SpeterDo not run any checkout program (as specified 897717721Speterwith the @samp{-o} option in the modules file; 897817721Speter@pxref{modules}). 897917721Speter 898017721Speter@item -P 898125839SpeterPrune empty directories. See @ref{Moving directories}. 898217721Speter 898317721Speter@item -p 898417721SpeterPipe files to the standard output. 898517721Speter 898625839Speter@item -R 898725839SpeterCheckout directories recursively. This option is on by default. 898825839Speter 898917721Speter@item -r @var{tag} 899017721SpeterUse revision @var{tag}. This option is sticky, and implies @samp{-P}. 899117721SpeterSee @ref{Sticky tags}, for more information on sticky tags/dates. 899217721Speter@end table 899317721Speter 899417721SpeterIn addition to those, you can use these special command 899517721Speteroptions with @code{checkout}: 899617721Speter 899717721Speter@table @code 899817721Speter@item -A 899917721SpeterReset any sticky tags, dates, or @samp{-k} options. 9000175261SobrienDoes not reset sticky @samp{-k} options on modified files. 9001177391SobrienSee @ref{Sticky tags} for more information on sticky tags/dates. 900217721Speter 900317721Speter@item -c 900417721SpeterCopy the module file, sorted, to the standard output, 900517721Speterinstead of creating or modifying any files or 900617721Speterdirectories in your working directory. 900717721Speter 900817721Speter@item -d @var{dir} 900917721SpeterCreate a directory called @var{dir} for the working 901032785Speterfiles, instead of using the module name. In general, 901132785Speterusing this flag is equivalent to using @samp{mkdir 901232785Speter@var{dir}; cd @var{dir}} followed by the checkout 901332785Spetercommand without the @samp{-d} flag. 901417721Speter 901532785SpeterThere is an important exception, however. It is very 901632785Speterconvenient when checking out a single item to have the 901732785Speteroutput appear in a directory that doesn't contain empty 901832785Speterintermediate directories. In this case @emph{only}, 901981404Speter@sc{cvs} tries to ``shorten'' pathnames to avoid those empty 902032785Speterdirectories. 902132785Speter 902232785SpeterFor example, given a module @samp{foo} that contains 902332785Speterthe file @samp{bar.c}, the command @samp{cvs co -d dir 902432785Speterfoo} will create directory @samp{dir} and place 902532785Speter@samp{bar.c} inside. Similarly, given a module 902632785Speter@samp{bar} which has subdirectory @samp{baz} wherein 9027102840Speterthere is a file @samp{quux.c}, the command @samp{cvs co 9028102840Speter-d dir bar/baz} will create directory @samp{dir} and 902932785Speterplace @samp{quux.c} inside. 903032785Speter 903132785SpeterUsing the @samp{-N} flag will defeat this behavior. 903232785SpeterGiven the same module definitions above, @samp{cvs co 903332785Speter-N -d dir foo} will create directories @samp{dir/foo} 903432785Speterand place @samp{bar.c} inside, while @samp{cvs co -N -d 903532785Speterdir bar/baz} will create directories @samp{dir/bar/baz} 903632785Speterand place @samp{quux.c} inside. 903732785Speter 903817721Speter@item -j @var{tag} 903917721SpeterWith two @samp{-j} options, merge changes from the 904017721Speterrevision specified with the first @samp{-j} option to 904117721Speterthe revision specified with the second @samp{j} option, 904217721Speterinto the working directory. 904317721Speter 904417721SpeterWith one @samp{-j} option, merge changes from the 904517721Speterancestor revision to the revision specified with the 904617721Speter@samp{-j} option, into the working directory. The 904717721Speterancestor revision is the common ancestor of the 904817721Speterrevision which the working directory is based on, and 904917721Speterthe revision specified in the @samp{-j} option. 905017721Speter 905117721SpeterIn addition, each -j option can contain an optional 905217721Speterdate specification which, when used with branches, can 905317721Speterlimit the chosen revision to one within a specific 905417721Speterdate. An optional date is specified by adding a colon 905517721Speter(:) to the tag: 905617721Speter@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 905717721Speter 9058177391SobrienSee @ref{Branching and merging}. 905917721Speter 906017721Speter@item -N 906132785SpeterOnly useful together with @samp{-d @var{dir}}. With 906232785Speterthis option, @sc{cvs} will not ``shorten'' module paths 906332785Speterin your working directory when you check out a single 906432785Spetermodule. See the @samp{-d} flag for examples and a 906532785Speterdiscussion. 906617721Speter 906717721Speter@item -s 906817721SpeterLike @samp{-c}, but include the status of all modules, 9069177391Sobrienand sort it by the status string. See @ref{modules}, for 907017721Speterinfo about the @samp{-s} option that is used inside the 907117721Spetermodules file to set the module status. 907217721Speter@end table 907317721Speter 907417721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907517721Speter@node checkout examples 907617721Speter@appendixsubsec checkout examples 907717721Speter 907817721SpeterGet a copy of the module @samp{tc}: 907917721Speter 908017721Speter@example 908117721Speter$ cvs checkout tc 908217721Speter@end example 908317721Speter 908417721SpeterGet a copy of the module @samp{tc} as it looked one day 908517721Speterago: 908617721Speter 908717721Speter@example 908817721Speter$ cvs checkout -D yesterday tc 908917721Speter@end example 909017721Speter 909117721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 909217721Speter@node commit 909317721Speter@appendixsec commit---Check files into the repository 909466525Speter@cindex commit (subcommand) 909517721Speter 909617721Speter@itemize @bullet 909717721Speter@item 9098175261SobrienSynopsis: commit [-lRf] [-m 'log_message' | 909917721Speter-F file] [-r revision] [files@dots{}] 910017721Speter@item 910117721SpeterRequires: working directory, repository. 910217721Speter@item 910317721SpeterChanges: repository. 910417721Speter@item 910517721SpeterSynonym: ci 910617721Speter@end itemize 910717721Speter 910817721SpeterUse @code{commit} when you want to incorporate changes 910917721Speterfrom your working source files into the source 911017721Speterrepository. 911117721Speter 911217721SpeterIf you don't specify particular files to commit, all of 911317721Speterthe files in your working current directory are 911417721Speterexamined. @code{commit} is careful to change in the 911517721Speterrepository only those files that you have really 911617721Speterchanged. By default (or if you explicitly specify the 911717721Speter@samp{-R} option), files in subdirectories are also 911817721Speterexamined and committed if they have changed; you can 911917721Speteruse the @samp{-l} option to limit @code{commit} to the 912017721Spetercurrent directory only. 912117721Speter 912217721Speter@code{commit} verifies that the selected files are up 912317721Speterto date with the current revisions in the source 912417721Speterrepository; it will notify you, and exit without 912517721Spetercommitting, if any of the specified files must be made 912617721Spetercurrent first with @code{update} (@pxref{update}). 912717721Speter@code{commit} does not call the @code{update} command 912817721Speterfor you, but rather leaves that for you to do when the 912917721Spetertime is right. 913017721Speter 913117721SpeterWhen all is well, an editor is invoked to allow you to 913217721Speterenter a log message that will be written to one or more 913317721Speterlogging programs (@pxref{modules}, and @pxref{loginfo}) 913432785Speterand placed in the @sc{rcs} file inside the 913517721Speterrepository. This log message can be retrieved with the 9136177391Sobrien@code{log} command; @xref{log}. You can specify the 913717721Speterlog message on the command line with the @samp{-m 913817721Speter@var{message}} option, and thus avoid the editor invocation, 913925839Speteror use the @samp{-F @var{file}} option to specify 914017721Speterthat the argument file contains the log message. 914117721Speter 914217721Speter@menu 914317721Speter* commit options:: commit options 914417721Speter* commit examples:: commit examples 914517721Speter@end menu 914617721Speter 914717721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914817721Speter@node commit options 914917721Speter@appendixsubsec commit options 915017721Speter 915117721SpeterThese standard options are supported by @code{commit} 9152177391Sobrien(@pxref{Common options} for a complete description of 915317721Speterthem): 915417721Speter 915517721Speter@table @code 915617721Speter@item -l 915717721SpeterLocal; run only in current working directory. 915817721Speter 915917721Speter@item -R 916017721SpeterCommit directories recursively. This is on by default. 916117721Speter 916217721Speter@item -r @var{revision} 916317721SpeterCommit to @var{revision}. @var{revision} must be 916417721Spetereither a branch, or a revision on the main trunk that 916525839Speteris higher than any existing revision number 916625839Speter(@pxref{Assigning revisions}). You 916717721Spetercannot commit to a specific revision on a branch. 916825839Speter@c FIXME: Need xref for branch case. 916917721Speter@end table 917017721Speter 917117721Speter@code{commit} also supports these options: 917217721Speter 917317721Speter@table @code 917417721Speter@item -F @var{file} 917525839SpeterRead the log message from @var{file}, instead 917617721Speterof invoking an editor. 917717721Speter 917817721Speter@item -f 917925839SpeterNote that this is not the standard behavior of 918032785Speterthe @samp{-f} option as defined in @ref{Common options}. 918117721Speter 918217721SpeterForce @sc{cvs} to commit a new revision even if you haven't 918317721Spetermade any changes to the file. If the current revision 918417721Speterof @var{file} is 1.7, then the following two commands 918517721Speterare equivalent: 918617721Speter 918717721Speter@example 918817721Speter$ cvs commit -f @var{file} 918917721Speter$ cvs commit -r 1.8 @var{file} 919017721Speter@end example 919117721Speter 919225839Speter@c This is odd, but it's how CVS has worked for some 919325839Speter@c time. 919425839SpeterThe @samp{-f} option disables recursion (i.e., it 919525839Speterimplies @samp{-l}). To force @sc{cvs} to commit a new 919625839Speterrevision for all files in all subdirectories, you must 919725839Speteruse @samp{-f -R}. 919817721Speter 919917721Speter@item -m @var{message} 920017721SpeterUse @var{message} as the log message, instead of 920117721Speterinvoking an editor. 920217721Speter@end table 920317721Speter 920417721Speter@need 2000 920517721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920617721Speter@node commit examples 920717721Speter@appendixsubsec commit examples 920817721Speter 920954427Speter@c FIXME: this material wants to be somewhere 921054427Speter@c in "Branching and merging". 921154427Speter 921217721Speter@appendixsubsubsec Committing to a branch 921317721Speter 921417721SpeterYou can commit to a branch revision (one that has an 921517721Spetereven number of dots) with the @samp{-r} option. To 921617721Spetercreate a branch revision, use the @samp{-b} option 921754427Speterof the @code{rtag} or @code{tag} commands 921854427Speter(@pxref{Branching and merging}). Then, either @code{checkout} or 921917721Speter@code{update} can be used to base your sources on the 922017721Speternewly created branch. From that point on, all 922117721Speter@code{commit} changes made within these working sources 922217721Speterwill be automatically added to a branch revision, 922317721Speterthereby not disturbing main-line development in any 922417721Speterway. For example, if you had to create a patch to the 922517721Speter1.2 version of the product, even though the 2.0 version 922617721Speteris already under development, you might do: 922717721Speter 922817721Speter@example 922917721Speter$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 923017721Speter$ cvs checkout -r FCS1_2_Patch product_module 923117721Speter$ cd product_module 923217721Speter[[ hack away ]] 923317721Speter$ cvs commit 923417721Speter@end example 923517721Speter 923617721Speter@noindent 923717721SpeterThis works automatically since the @samp{-r} option is 923817721Spetersticky. 923917721Speter 924017721Speter@appendixsubsubsec Creating the branch after editing 924117721Speter 924217721SpeterSay you have been working on some extremely 924317721Speterexperimental software, based on whatever revision you 924417721Speterhappened to checkout last week. If others in your 924517721Spetergroup would like to work on this software with you, but 924617721Speterwithout disturbing main-line development, you could 924717721Spetercommit your change to a new branch. Others can then 924817721Spetercheckout your experimental stuff and utilize the full 924917721Speterbenefit of @sc{cvs} conflict resolution. The scenario might 925017721Speterlook like: 925117721Speter 925217721Speter@c FIXME: Should we be recommending tagging the branchpoint? 925317721Speter@example 925417721Speter[[ hacked sources are present ]] 925517721Speter$ cvs tag -b EXPR1 925617721Speter$ cvs update -r EXPR1 925717721Speter$ cvs commit 925817721Speter@end example 925917721Speter 926017721SpeterThe @code{update} command will make the @samp{-r 926117721SpeterEXPR1} option sticky on all files. Note that your 926217721Speterchanges to the files will never be removed by the 926317721Speter@code{update} command. The @code{commit} will 926417721Speterautomatically commit to the correct branch, because the 926517721Speter@samp{-r} is sticky. You could also do like this: 926617721Speter 926717721Speter@c FIXME: Should we be recommending tagging the branchpoint? 926817721Speter@example 926917721Speter[[ hacked sources are present ]] 927017721Speter$ cvs tag -b EXPR1 927117721Speter$ cvs commit -r EXPR1 927217721Speter@end example 927317721Speter 927417721Speter@noindent 927517721Speterbut then, only those files that were changed by you 927617721Speterwill have the @samp{-r EXPR1} sticky flag. If you hack 927717721Speteraway, and commit without specifying the @samp{-r EXPR1} 927817721Speterflag, some files may accidentally end up on the main 927917721Spetertrunk. 928017721Speter 928117721SpeterTo work with you on the experimental change, others 928217721Speterwould simply do 928317721Speter 928417721Speter@example 928517721Speter$ cvs checkout -r EXPR1 whatever_module 928617721Speter@end example 928717721Speter 928817721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 928917721Speter@node diff 929025839Speter@appendixsec diff---Show differences between revisions 929166525Speter@cindex diff (subcommand) 929217721Speter 929317721Speter@itemize @bullet 929417721Speter@item 9295102840SpeterSynopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}] 929617721Speter@item 929717721SpeterRequires: working directory, repository. 929817721Speter@item 929917721SpeterChanges: nothing. 930017721Speter@end itemize 930117721Speter 930217721SpeterThe @code{diff} command is used to compare different 930317721Speterrevisions of files. The default action is to compare 930417721Speteryour working files with the revisions they were based 930517721Speteron, and report any differences that are found. 930617721Speter 930717721SpeterIf any file names are given, only those files are 930817721Spetercompared. If any directories are given, all files 930917721Speterunder them will be compared. 931017721Speter 931126065SpeterThe exit status for diff is different than for other 9312177391Sobrien@sc{cvs} commands; for details @xref{Exit status}. 931317721Speter 931417721Speter@menu 931517721Speter* diff options:: diff options 931617721Speter* diff examples:: diff examples 931717721Speter@end menu 931817721Speter 931917721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932017721Speter@node diff options 932117721Speter@appendixsubsec diff options 932217721Speter 932317721SpeterThese standard options are supported by @code{diff} 9324177391Sobrien(@pxref{Common options} for a complete description of 932517721Speterthem): 932617721Speter 932717721Speter@table @code 932817721Speter@item -D @var{date} 932917721SpeterUse the most recent revision no later than @var{date}. 933017721SpeterSee @samp{-r} for how this affects the comparison. 933117721Speter 933217721Speter@item -k @var{kflag} 933332785SpeterProcess keywords according to @var{kflag}. See 933432785Speter@ref{Keyword substitution}. 933517721Speter 933617721Speter@item -l 933717721SpeterLocal; run only in current working directory. 933817721Speter 933917721Speter@item -R 934017721SpeterExamine directories recursively. This option is on by 934117721Speterdefault. 934217721Speter 934317721Speter@item -r @var{tag} 934417721SpeterCompare with revision @var{tag}. Zero, one or two 934517721Speter@samp{-r} options can be present. With no @samp{-r} 934617721Speteroption, the working file will be compared with the 934717721Speterrevision it was based on. With one @samp{-r}, that 934817721Speterrevision will be compared to your current working file. 934917721SpeterWith two @samp{-r} options those two revisions will be 935017721Spetercompared (and your working file will not affect the 935117721Speteroutcome in any way). 935232785Speter@c We should be a lot more explicit, with examples, 935332785Speter@c about the difference between "cvs diff" and "cvs 935432785Speter@c diff -r HEAD". This often confuses new users. 935517721Speter 935617721SpeterOne or both @samp{-r} options can be replaced by a 935717721Speter@samp{-D @var{date}} option, described above. 935817721Speter@end table 935917721Speter 936032785Speter@c Conceptually, this is a disaster. There are 3 936132785Speter@c zillion diff formats that we support via the diff 936232785Speter@c library. It is not obvious to me that we should 936332785Speter@c document them all. Maybe just the most common ones 936432785Speter@c like -c and -u, and think about phasing out the 936532785Speter@c obscure ones. 936632785Speter@c FIXCVS: also should be a way to specify an external 936732785Speter@c diff program (which can be different for different 936832785Speter@c file types) and pass through 936925839Speter@c arbitrary options, so that the user can do 937025839Speter@c "--pass=-Z --pass=foo" or something even if CVS 937132785Speter@c doesn't know about the "-Z foo" option to diff. 937232785Speter@c This would fit nicely with deprecating/eliminating 937332785Speter@c the obscure options of the diff library, because it 937432785Speter@c would let people specify an external GNU diff if 937532785Speter@c they are into that sort of thing. 937632785SpeterThe following options specify the format of the 937732785Speteroutput. They have the same meaning as in GNU diff. 9378102840SpeterMost options have two equivalent names, one of which is a single letter 9379102840Speterpreceded by @samp{-}, and the other of which is a long name preceded by 9380102840Speter@samp{--}. 938117721Speter 9382102840Speter@table @samp 9383102840Speter@item -@var{lines} 9384102840SpeterShow @var{lines} (an integer) lines of context. This option does not 9385102840Speterspecify an output format by itself; it has no effect unless it is 9386102840Spetercombined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9387102840Speteroperation, @code{patch} typically needs at least two lines of context. 9388102840Speter 9389102840Speter@item -a 9390102840SpeterTreat all files as text and compare them line-by-line, even if they 9391102840Speterdo not seem to be text. 9392102840Speter 9393102840Speter@item -b 9394102840SpeterIgnore trailing white space and consider all other sequences of one or 9395102840Spetermore white space characters to be equivalent. 9396102840Speter 9397102840Speter@item -B 9398102840SpeterIgnore changes that just insert or delete blank lines. 9399102840Speter 9400102840Speter@item --binary 9401102840SpeterRead and write data in binary mode. 9402102840Speter 9403102840Speter@item --brief 9404102840SpeterReport only whether the files differ, not the details of the 9405102840Speterdifferences. 9406102840Speter 9407102840Speter@item -c 9408102840SpeterUse the context output format. 9409102840Speter 9410102840Speter@item -C @var{lines} 9411102840Speter@itemx --context@r{[}=@var{lines}@r{]} 9412102840SpeterUse the context output format, showing @var{lines} (an integer) lines of 9413102840Spetercontext, or three if @var{lines} is not given. 9414102840SpeterFor proper operation, @code{patch} typically needs at least two lines of 9415102840Spetercontext. 9416102840Speter 9417102840Speter@item --changed-group-format=@var{format} 9418102840SpeterUse @var{format} to output a line group containing differing lines from 9419177391Sobrienboth files in if-then-else format. See @ref{Line group formats}. 9420102840Speter 9421102840Speter@item -d 9422102840SpeterChange the algorithm to perhaps find a smaller set of changes. This makes 9423102840Speter@code{diff} slower (sometimes much slower). 9424102840Speter 9425102840Speter@item -e 9426102840Speter@itemx --ed 9427102840SpeterMake output that is a valid @code{ed} script. 9428102840Speter 9429102840Speter@item --expand-tabs 9430102840SpeterExpand tabs to spaces in the output, to preserve the alignment of tabs 9431102840Speterin the input files. 9432102840Speter 9433102840Speter@item -f 9434102840SpeterMake output that looks vaguely like an @code{ed} script but has changes 9435102840Speterin the order they appear in the file. 9436102840Speter 9437102840Speter@item -F @var{regexp} 9438102840SpeterIn context and unified format, for each hunk of differences, show some 9439102840Speterof the last preceding line that matches @var{regexp}. 9440102840Speter 9441102840Speter@item --forward-ed 9442102840SpeterMake output that looks vaguely like an @code{ed} script but has changes 9443102840Speterin the order they appear in the file. 9444102840Speter 9445102840Speter@item -H 9446102840SpeterUse heuristics to speed handling of large files that have numerous 9447102840Speterscattered small changes. 9448102840Speter 9449102840Speter@item --horizon-lines=@var{lines} 9450102840SpeterDo not discard the last @var{lines} lines of the common prefix 9451102840Speterand the first @var{lines} lines of the common suffix. 9452102840Speter 9453102840Speter@item -i 9454102840SpeterIgnore changes in case; consider upper- and lower-case letters 9455102840Speterequivalent. 9456102840Speter 9457102840Speter@item -I @var{regexp} 9458102840SpeterIgnore changes that just insert or delete lines that match @var{regexp}. 9459102840Speter 9460102840Speter@item --ifdef=@var{name} 9461102840SpeterMake merged if-then-else output using @var{name}. 9462102840Speter 9463102840Speter@item --ignore-all-space 9464102840SpeterIgnore white space when comparing lines. 9465102840Speter 9466102840Speter@item --ignore-blank-lines 9467102840SpeterIgnore changes that just insert or delete blank lines. 9468102840Speter 9469102840Speter@item --ignore-case 9470102840SpeterIgnore changes in case; consider upper- and lower-case to be the same. 9471102840Speter 9472102840Speter@item --ignore-matching-lines=@var{regexp} 9473102840SpeterIgnore changes that just insert or delete lines that match @var{regexp}. 9474102840Speter 9475102840Speter@item --ignore-space-change 9476102840SpeterIgnore trailing white space and consider all other sequences of one or 9477102840Spetermore white space characters to be equivalent. 9478102840Speter 9479102840Speter@item --initial-tab 9480102840SpeterOutput a tab rather than a space before the text of a line in normal or 9481102840Spetercontext format. This causes the alignment of tabs in the line to look 9482102840Speternormal. 9483102840Speter 9484102840Speter@item -L @var{label} 9485102840SpeterUse @var{label} instead of the file name in the context format 9486102840Speterand unified format headers. 9487102840Speter 9488102840Speter@item --label=@var{label} 9489102840SpeterUse @var{label} instead of the file name in the context format 9490102840Speterand unified format headers. 9491102840Speter 9492102840Speter@item --left-column 9493102840SpeterPrint only the left column of two common lines in side by side format. 9494102840Speter 9495102840Speter@item --line-format=@var{format} 9496102840SpeterUse @var{format} to output all input lines in if-then-else format. 9497177391SobrienSee @ref{Line formats}. 9498102840Speter 9499102840Speter@item --minimal 9500102840SpeterChange the algorithm to perhaps find a smaller set of changes. This 9501102840Spetermakes @code{diff} slower (sometimes much slower). 9502102840Speter 9503102840Speter@item -n 9504102840SpeterOutput RCS-format diffs; like @samp{-f} except that each command 9505102840Speterspecifies the number of lines affected. 9506102840Speter 9507102840Speter@item -N 9508102840Speter@itemx --new-file 9509102840SpeterIn directory comparison, if a file is found in only one directory, 9510102840Spetertreat it as present but empty in the other directory. 9511102840Speter 9512102840Speter@item --new-group-format=@var{format} 9513102840SpeterUse @var{format} to output a group of lines taken from just the second 9514177391Sobrienfile in if-then-else format. See @ref{Line group formats}. 9515102840Speter 9516102840Speter@item --new-line-format=@var{format} 9517102840SpeterUse @var{format} to output a line taken from just the second file in 9518177391Sobrienif-then-else format. See @ref{Line formats}. 9519102840Speter 9520102840Speter@item --old-group-format=@var{format} 9521102840SpeterUse @var{format} to output a group of lines taken from just the first 9522177391Sobrienfile in if-then-else format. See @ref{Line group formats}. 9523102840Speter 9524102840Speter@item --old-line-format=@var{format} 9525102840SpeterUse @var{format} to output a line taken from just the first file in 9526177391Sobrienif-then-else format. See @ref{Line formats}. 9527102840Speter 9528102840Speter@item -p 9529102840SpeterShow which C function each change is in. 9530102840Speter 9531102840Speter@item --rcs 9532102840SpeterOutput RCS-format diffs; like @samp{-f} except that each command 9533102840Speterspecifies the number of lines affected. 9534102840Speter 9535102840Speter@item --report-identical-files 9536102840Speter@itemx -s 9537102840SpeterReport when two files are the same. 9538102840Speter 9539102840Speter@item --show-c-function 9540102840SpeterShow which C function each change is in. 9541102840Speter 9542102840Speter@item --show-function-line=@var{regexp} 9543102840SpeterIn context and unified format, for each hunk of differences, show some 9544102840Speterof the last preceding line that matches @var{regexp}. 9545102840Speter 9546102840Speter@item --side-by-side 9547102840SpeterUse the side by side output format. 9548102840Speter 9549102840Speter@item --speed-large-files 9550102840SpeterUse heuristics to speed handling of large files that have numerous 9551102840Speterscattered small changes. 9552102840Speter 9553102840Speter@item --suppress-common-lines 9554102840SpeterDo not print common lines in side by side format. 9555102840Speter 9556102840Speter@item -t 9557102840SpeterExpand tabs to spaces in the output, to preserve the alignment of tabs 9558102840Speterin the input files. 9559102840Speter 9560102840Speter@item -T 9561102840SpeterOutput a tab rather than a space before the text of a line in normal or 9562102840Spetercontext format. This causes the alignment of tabs in the line to look 9563102840Speternormal. 9564102840Speter 9565102840Speter@item --text 9566102840SpeterTreat all files as text and compare them line-by-line, even if they 9567102840Speterdo not appear to be text. 9568102840Speter 9569102840Speter@item -u 9570102840SpeterUse the unified output format. 9571102840Speter 9572102840Speter@item --unchanged-group-format=@var{format} 9573102840SpeterUse @var{format} to output a group of common lines taken from both files 9574102840Speterin if-then-else format. @xref{Line group formats}. 9575102840Speter 9576102840Speter@item --unchanged-line-format=@var{format} 9577102840SpeterUse @var{format} to output a line common to both files in if-then-else 9578102840Speterformat. @xref{Line formats}. 9579102840Speter 9580102840Speter@item -U @var{lines} 9581102840Speter@itemx --unified@r{[}=@var{lines}@r{]} 9582102840SpeterUse the unified output format, showing @var{lines} (an integer) lines of 9583102840Spetercontext, or three if @var{lines} is not given. 9584102840SpeterFor proper operation, @code{patch} typically needs at least two lines of 9585102840Spetercontext. 9586102840Speter 9587102840Speter@item -w 9588102840SpeterIgnore white space when comparing lines. 9589102840Speter 9590102840Speter@item -W @var{columns} 9591102840Speter@itemx --width=@var{columns} 9592102840SpeterUse an output width of @var{columns} in side by side format. 9593102840Speter 9594102840Speter@item -y 9595102840SpeterUse the side by side output format. 9596102840Speter@end table 9597102840Speter 9598102840Speter@menu 9599102840Speter* Line group formats:: Line group formats 9600102840Speter* Line formats:: Line formats 9601102840Speter@end menu 9602102840Speter 9603102840Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9604102840Speter@node Line group formats 9605102840Speter@appendixsubsubsec Line group formats 9606102840Speter 9607102840SpeterLine group formats let you specify formats suitable for many 9608102840Speterapplications that allow if-then-else input, including programming 9609102840Speterlanguages and text formatting languages. A line group format specifies 9610102840Speterthe output format for a contiguous group of similar lines. 9611102840Speter 9612102840SpeterFor example, the following command compares the TeX file @file{myfile} 9613102840Speterwith the original version from the repository, 9614102840Speterand outputs a merged file in which old regions are 9615102840Spetersurrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 9616102840Speterregions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 9617102840Speter 961844852Speter@example 9619102840Spetercvs diff \ 9620102840Speter --old-group-format='\begin@{em@} 9621102840Speter%<\end@{em@} 9622102840Speter' \ 9623102840Speter --new-group-format='\begin@{bf@} 9624102840Speter%>\end@{bf@} 9625102840Speter' \ 9626102840Speter myfile 962744852Speter@end example 962825839Speter 9629102840SpeterThe following command is equivalent to the above example, but it is a 9630102840Speterlittle more verbose, because it spells out the default line group formats. 9631102840Speter 9632102840Speter@example 9633102840Spetercvs diff \ 9634102840Speter --old-group-format='\begin@{em@} 9635102840Speter%<\end@{em@} 9636102840Speter' \ 9637102840Speter --new-group-format='\begin@{bf@} 9638102840Speter%>\end@{bf@} 9639102840Speter' \ 9640102840Speter --unchanged-group-format='%=' \ 9641102840Speter --changed-group-format='\begin@{em@} 9642102840Speter%<\end@{em@} 9643102840Speter\begin@{bf@} 9644102840Speter%>\end@{bf@} 9645102840Speter' \ 9646102840Speter myfile 9647102840Speter@end example 9648102840Speter 9649102840SpeterHere is a more advanced example, which outputs a diff listing with 9650102840Speterheaders containing line numbers in a ``plain English'' style. 9651102840Speter 9652102840Speter@example 9653102840Spetercvs diff \ 9654102840Speter --unchanged-group-format='' \ 9655102840Speter --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 9656102840Speter%<' \ 9657102840Speter --new-group-format='-------- %dN line%(N=1?:s) added after %de: 9658102840Speter%>' \ 9659102840Speter --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 9660102840Speter%<-------- to: 9661102840Speter%>' \ 9662102840Speter myfile 9663102840Speter@end example 9664102840Speter 9665102840SpeterTo specify a line group format, use one of the options 9666102840Speterlisted below. You can specify up to four line group formats, one for 9667102840Spetereach kind of line group. You should quote @var{format}, because it 9668102840Spetertypically contains shell metacharacters. 9669102840Speter 9670102840Speter@table @samp 9671102840Speter@item --old-group-format=@var{format} 9672102840SpeterThese line groups are hunks containing only lines from the first file. 9673102840SpeterThe default old group format is the same as the changed group format if 9674102840Speterit is specified; otherwise it is a format that outputs the line group as-is. 9675102840Speter 9676102840Speter@item --new-group-format=@var{format} 9677102840SpeterThese line groups are hunks containing only lines from the second 9678130303Speterfile. The default new group format is same as the changed group 9679102840Speterformat if it is specified; otherwise it is a format that outputs the 9680102840Speterline group as-is. 9681102840Speter 9682102840Speter@item --changed-group-format=@var{format} 9683102840SpeterThese line groups are hunks containing lines from both files. The 9684102840Speterdefault changed group format is the concatenation of the old and new 9685102840Spetergroup formats. 9686102840Speter 9687102840Speter@item --unchanged-group-format=@var{format} 9688102840SpeterThese line groups contain lines common to both files. The default 9689102840Speterunchanged group format is a format that outputs the line group as-is. 9690102840Speter@end table 9691102840Speter 9692102840SpeterIn a line group format, ordinary characters represent themselves; 9693102840Speterconversion specifications start with @samp{%} and have one of the 9694102840Speterfollowing forms. 9695102840Speter 9696102840Speter@table @samp 9697102840Speter@item %< 9698102840Speterstands for the lines from the first file, including the trailing newline. 9699102840SpeterEach line is formatted according to the old line format (@pxref{Line formats}). 9700102840Speter 9701102840Speter@item %> 9702102840Speterstands for the lines from the second file, including the trailing newline. 9703102840SpeterEach line is formatted according to the new line format. 9704102840Speter 9705102840Speter@item %= 9706102840Speterstands for the lines common to both files, including the trailing newline. 9707102840SpeterEach line is formatted according to the unchanged line format. 9708102840Speter 9709102840Speter@item %% 9710102840Speterstands for @samp{%}. 9711102840Speter 9712102840Speter@item %c'@var{C}' 9713102840Speterwhere @var{C} is a single character, stands for @var{C}. 9714102840Speter@var{C} may not be a backslash or an apostrophe. 9715102840SpeterFor example, @samp{%c':'} stands for a colon, even inside 9716102840Speterthe then-part of an if-then-else format, which a colon would 9717102840Speternormally terminate. 9718102840Speter 9719102840Speter@item %c'\@var{O}' 9720102840Speterwhere @var{O} is a string of 1, 2, or 3 octal digits, 9721102840Speterstands for the character with octal code @var{O}. 9722102840SpeterFor example, @samp{%c'\0'} stands for a null character. 9723102840Speter 9724102840Speter@item @var{F}@var{n} 9725102840Speterwhere @var{F} is a @code{printf} conversion specification and @var{n} is one 9726102840Speterof the following letters, stands for @var{n}'s value formatted with @var{F}. 9727102840Speter 9728102840Speter@table @samp 9729102840Speter@item e 9730102840SpeterThe line number of the line just before the group in the old file. 9731102840Speter 9732102840Speter@item f 9733102840SpeterThe line number of the first line in the group in the old file; 9734102840Speterequals @var{e} + 1. 9735102840Speter 9736102840Speter@item l 9737102840SpeterThe line number of the last line in the group in the old file. 9738102840Speter 9739102840Speter@item m 9740102840SpeterThe line number of the line just after the group in the old file; 9741102840Speterequals @var{l} + 1. 9742102840Speter 9743102840Speter@item n 9744102840SpeterThe number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 9745102840Speter 9746102840Speter@item E, F, L, M, N 9747102840SpeterLikewise, for lines in the new file. 9748102840Speter 9749102840Speter@end table 9750102840Speter 9751102840SpeterThe @code{printf} conversion specification can be @samp{%d}, 9752102840Speter@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 9753102840Speterlower case hexadecimal, or upper case hexadecimal output 9754102840Speterrespectively. After the @samp{%} the following options can appear in 9755102840Spetersequence: a @samp{-} specifying left-justification; an integer 9756102840Speterspecifying the minimum field width; and a period followed by an 9757102840Speteroptional integer specifying the minimum number of digits. 9758102840SpeterFor example, @samp{%5dN} prints the number of new lines in the group 9759102840Speterin a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 9760102840Speter 9761102840Speter@item (@var{A}=@var{B}?@var{T}:@var{E}) 9762102840SpeterIf @var{A} equals @var{B} then @var{T} else @var{E}. 9763102840Speter@var{A} and @var{B} are each either a decimal constant 9764102840Speteror a single letter interpreted as above. 9765102840SpeterThis format spec is equivalent to @var{T} if 9766102840Speter@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 9767102840Speter 9768102840SpeterFor example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 9769130303Speter@samp{no lines} if @var{N} (the number of lines in the group in the 9770102840Speternew file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 9771102840Speterotherwise. 9772102840Speter@end table 9773102840Speter 977417721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9775102840Speter@node Line formats 9776102840Speter@appendixsubsubsec Line formats 9777102840Speter 9778102840SpeterLine formats control how each line taken from an input file is 9779102840Speteroutput as part of a line group in if-then-else format. 9780102840Speter 9781102840SpeterFor example, the following command outputs text with a one-column 9782102840Speterchange indicator to the left of the text. The first column of output 9783102840Speteris @samp{-} for deleted lines, @samp{|} for added lines, and a space 9784102840Speterfor unchanged lines. The formats contain newline characters where 9785102840Speternewlines are desired on output. 9786102840Speter 9787102840Speter@example 9788102840Spetercvs diff \ 9789102840Speter --old-line-format='-%l 9790102840Speter' \ 9791102840Speter --new-line-format='|%l 9792102840Speter' \ 9793102840Speter --unchanged-line-format=' %l 9794102840Speter' \ 9795102840Speter myfile 9796102840Speter@end example 9797102840Speter 9798102840SpeterTo specify a line format, use one of the following options. You should 9799102840Speterquote @var{format}, since it often contains shell metacharacters. 9800102840Speter 9801102840Speter@table @samp 9802102840Speter@item --old-line-format=@var{format} 9803102840Speterformats lines just from the first file. 9804102840Speter 9805102840Speter@item --new-line-format=@var{format} 9806102840Speterformats lines just from the second file. 9807102840Speter 9808102840Speter@item --unchanged-line-format=@var{format} 9809102840Speterformats lines common to both files. 9810102840Speter 9811102840Speter@item --line-format=@var{format} 9812102840Speterformats all lines; in effect, it sets all three above options simultaneously. 9813102840Speter@end table 9814102840Speter 9815102840SpeterIn a line format, ordinary characters represent themselves; 9816102840Speterconversion specifications start with @samp{%} and have one of the 9817102840Speterfollowing forms. 9818102840Speter 9819102840Speter@table @samp 9820102840Speter@item %l 9821130303Speterstands for the contents of the line, not counting its trailing 9822102840Speternewline (if any). This format ignores whether the line is incomplete. 9823102840Speter 9824102840Speter@item %L 9825130303Speterstands for the contents of the line, including its trailing newline 9826102840Speter(if any). If a line is incomplete, this format preserves its 9827102840Speterincompleteness. 9828102840Speter 9829102840Speter@item %% 9830102840Speterstands for @samp{%}. 9831102840Speter 9832102840Speter@item %c'@var{C}' 9833102840Speterwhere @var{C} is a single character, stands for @var{C}. 9834102840Speter@var{C} may not be a backslash or an apostrophe. 9835102840SpeterFor example, @samp{%c':'} stands for a colon. 9836102840Speter 9837102840Speter@item %c'\@var{O}' 9838102840Speterwhere @var{O} is a string of 1, 2, or 3 octal digits, 9839102840Speterstands for the character with octal code @var{O}. 9840102840SpeterFor example, @samp{%c'\0'} stands for a null character. 9841102840Speter 9842102840Speter@item @var{F}n 9843102840Speterwhere @var{F} is a @code{printf} conversion specification, 9844102840Speterstands for the line number formatted with @var{F}. 9845102840SpeterFor example, @samp{%.5dn} prints the line number using the 9846102840Speter@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 9847102840Spetermore about printf conversion specifications. 9848102840Speter 9849102840Speter@end table 9850102840Speter 9851102840SpeterThe default line format is @samp{%l} followed by a newline character. 9852102840Speter 9853102840SpeterIf the input contains tab characters and it is important that they line 9854102840Speterup on output, you should ensure that @samp{%l} or @samp{%L} in a line 9855102840Speterformat is just after a tab stop (e.g.@: by preceding @samp{%l} or 9856102840Speter@samp{%L} with a tab character), or you should use the @samp{-t} or 9857102840Speter@samp{--expand-tabs} option. 9858102840Speter 9859102840SpeterTaken together, the line and line group formats let you specify many 9860102840Speterdifferent formats. For example, the following command uses a format 9861102840Spetersimilar to @code{diff}'s normal format. You can tailor this command 9862102840Speterto get fine control over @code{diff}'s output. 9863102840Speter 9864102840Speter@example 9865102840Spetercvs diff \ 9866102840Speter --old-line-format='< %l 9867102840Speter' \ 9868102840Speter --new-line-format='> %l 9869102840Speter' \ 9870102840Speter --old-group-format='%df%(f=l?:,%dl)d%dE 9871102840Speter%<' \ 9872102840Speter --new-group-format='%dea%dF%(F=L?:,%dL) 9873102840Speter%>' \ 9874102840Speter --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 9875102840Speter%<--- 9876102840Speter%>' \ 9877102840Speter --unchanged-group-format='' \ 9878102840Speter myfile 9879102840Speter@end example 9880102840Speter 9881102840Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988217721Speter@node diff examples 988317721Speter@appendixsubsec diff examples 988417721Speter 988517721SpeterThe following line produces a Unidiff (@samp{-u} flag) 988617721Speterbetween revision 1.14 and 1.19 of 988717721Speter@file{backend.c}. Due to the @samp{-kk} flag no 988817721Speterkeywords are substituted, so differences that only depend 988917721Speteron keyword substitution are ignored. 989017721Speter 989117721Speter@example 989217721Speter$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 989317721Speter@end example 989417721Speter 989517721SpeterSuppose the experimental branch EXPR1 was based on a 989617721Speterset of files tagged RELEASE_1_0. To see what has 989717721Speterhappened on that branch, the following can be used: 989817721Speter 989917721Speter@example 990017721Speter$ cvs diff -r RELEASE_1_0 -r EXPR1 990117721Speter@end example 990217721Speter 990317721SpeterA command like this can be used to produce a context 990417721Speterdiff between two releases: 990517721Speter 990617721Speter@example 990717721Speter$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 990817721Speter@end example 990917721Speter 991017721SpeterIf you are maintaining ChangeLogs, a command like the following 991117721Speterjust before you commit your changes may help you write 991217721Speterthe ChangeLog entry. All local modifications that have 991317721Speternot yet been committed will be printed. 991417721Speter 991517721Speter@example 991617721Speter$ cvs diff -u | less 991717721Speter@end example 991817721Speter 991917721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 992017721Speter@node export 992117721Speter@appendixsec export---Export sources from CVS, similar to checkout 992266525Speter@cindex export (subcommand) 992317721Speter 992417721Speter@itemize @bullet 992517721Speter@item 992625839SpeterSynopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{} 992717721Speter@item 992817721SpeterRequires: repository. 992917721Speter@item 993017721SpeterChanges: current directory. 993117721Speter@end itemize 993217721Speter 993317721SpeterThis command is a variant of @code{checkout}; use it 993417721Speterwhen you want a copy of the source for module without 993517721Speterthe @sc{cvs} administrative directories. For example, you 993617721Spetermight use @code{export} to prepare source for shipment 993717721Speteroff-site. This command requires that you specify a 993817721Speterdate or tag (with @samp{-D} or @samp{-r}), so that you 993966525Spetercan count on reproducing the source you ship to others 994066525Speter(and thus it always prunes empty directories). 994117721Speter 994217721SpeterOne often would like to use @samp{-kv} with @code{cvs 994332785Speterexport}. This causes any keywords to be 994417721Speterexpanded such that an import done at some other site 994517721Speterwill not lose the keyword revision information. But be 994617721Speteraware that doesn't handle an export containing binary 994717721Speterfiles correctly. Also be aware that after having used 994817721Speter@samp{-kv}, one can no longer use the @code{ident} 994917721Spetercommand (which is part of the @sc{rcs} suite---see 995032785Speterident(1)) which looks for keyword strings. If 995117721Speteryou want to be able to use @code{ident} you must not 995217721Speteruse @samp{-kv}. 995317721Speter 995417721Speter@menu 995517721Speter* export options:: export options 995617721Speter@end menu 995717721Speter 995817721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995917721Speter@node export options 996017721Speter@appendixsubsec export options 996117721Speter 996217721SpeterThese standard options are supported by @code{export} 996317721Speter(@pxref{Common options}, for a complete description of 996417721Speterthem): 996517721Speter 996617721Speter@table @code 996717721Speter@item -D @var{date} 996817721SpeterUse the most recent revision no later than @var{date}. 996917721Speter 997017721Speter@item -f 997117721SpeterIf no matching revision is found, retrieve the most 997217721Speterrecent revision (instead of ignoring the file). 997317721Speter 997417721Speter@item -l 997517721SpeterLocal; run only in current working directory. 997617721Speter 997717721Speter@item -n 997817721SpeterDo not run any checkout program. 997917721Speter 998017721Speter@item -R 998117721SpeterExport directories recursively. This is on by default. 998217721Speter 998317721Speter@item -r @var{tag} 998417721SpeterUse revision @var{tag}. 998517721Speter@end table 998617721Speter 998717721SpeterIn addition, these options (that are common to 998817721Speter@code{checkout} and @code{export}) are also supported: 998917721Speter 999017721Speter@table @code 999117721Speter@item -d @var{dir} 999217721SpeterCreate a directory called @var{dir} for the working 999332785Speterfiles, instead of using the module name. 9994177391SobrienSee @ref{checkout options} for complete details on how 999532785Speter@sc{cvs} handles this flag. 999617721Speter 999717721Speter@item -k @var{subst} 999817721SpeterSet keyword expansion mode (@pxref{Substitution modes}). 999917721Speter 1000017721Speter@item -N 1000132785SpeterOnly useful together with @samp{-d @var{dir}}. 10002177391SobrienSee @ref{checkout options} for complete details on how 1000332785Speter@sc{cvs} handles this flag. 1000417721Speter@end table 1000517721Speter 1000617721Speter@ignore 1000717721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000817721Speter@c @node export examples 1000917721Speter@appendixsubsec export examples 1001017721Speter 1001117721SpeterContributed examples are gratefully accepted. 1001217721Speter@c -- Examples here!! 1001317721Speter@end ignore 1001417721Speter 1001517721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1001617721Speter@node history 1001717721Speter@appendixsec history---Show status of files and users 1001866525Speter@cindex history (subcommand) 1001917721Speter 1002017721Speter@itemize @bullet 1002117721Speter@item 1002217721SpeterSynopsis: history [-report] [-flags] [-options args] [files@dots{}] 1002317721Speter@item 1002417721SpeterRequires: the file @file{$CVSROOT/CVSROOT/history} 1002517721Speter@item 1002617721SpeterChanges: nothing. 1002717721Speter@end itemize 1002817721Speter 1002917721Speter@sc{cvs} can keep a history file that tracks each use of the 1003017721Speter@code{checkout}, @code{commit}, @code{rtag}, 1003117721Speter@code{update}, and @code{release} commands. You can 1003217721Speteruse @code{history} to display this information in 1003317721Spetervarious formats. 1003417721Speter 1003517721SpeterLogging must be enabled by creating the file 1003617721Speter@file{$CVSROOT/CVSROOT/history}. 1003717721Speter 10038175261Sobrien@strong{@code{history} uses @samp{-f}, @samp{-l}, 1003917721Speter@samp{-n}, and @samp{-p} in ways that conflict with the 10040128266Speternormal use inside @sc{cvs} (@pxref{Common options}).} 1004117721Speter 1004217721Speter@menu 1004317721Speter* history options:: history options 1004417721Speter@end menu 1004517721Speter 1004617721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004717721Speter@node history options 1004817721Speter@appendixsubsec history options 1004917721Speter 1005017721SpeterSeveral options (shown above as @samp{-report}) control what 1005117721Speterkind of report is generated: 1005217721Speter 1005317721Speter@table @code 1005417721Speter@item -c 1005517721SpeterReport on each time commit was used (i.e., each time 1005617721Speterthe repository was modified). 1005717721Speter 1005844852Speter@item -e 1005932785SpeterEverything (all record types). Equivalent to 1006032785Speterspecifying @samp{-x} with all record types. Of course, 1006132785Speter@samp{-e} will also include record types which are 1006232785Speteradded in a future version of @sc{cvs}; if you are 1006332785Speterwriting a script which can only handle certain record 1006432785Spetertypes, you'll want to specify @samp{-x}. 1006517721Speter 1006617721Speter@item -m @var{module} 1006717721SpeterReport on a particular module. (You can meaningfully 1006817721Speteruse @samp{-m} more than once on the command line.) 1006917721Speter 1007017721Speter@item -o 1007166525SpeterReport on checked-out modules. This is the default report type. 1007217721Speter 1007317721Speter@item -T 1007417721SpeterReport on all tags. 1007517721Speter 1007617721Speter@item -x @var{type} 1007717721SpeterExtract a particular set of record types @var{type} from the @sc{cvs} 1007817721Speterhistory. The types are indicated by single letters, 1007944852Speterwhich you may specify in combination. 1008017721Speter 1008144852SpeterCertain commands have a single record type: 1008217721Speter 1008317721Speter@table @code 1008417721Speter@item F 1008517721Speterrelease 1008617721Speter@item O 1008717721Spetercheckout 1008825839Speter@item E 1008925839Speterexport 1009017721Speter@item T 1009117721Speterrtag 1009217721Speter@end table 1009317721Speter 1009417721Speter@noindent 10095128266SpeterOne of five record types may result from an update: 1009617721Speter 1009717721Speter@table @code 1009817721Speter@item C 1009917721SpeterA merge was necessary but collisions were 1010044852Speterdetected (requiring manual merging). 1010117721Speter@item G 1010217721SpeterA merge was necessary and it succeeded. 1010317721Speter@item U 1010417721SpeterA working file was copied from the repository. 10105128266Speter@item P 10106128266SpeterA working file was patched to match the repository. 1010717721Speter@item W 1010817721SpeterThe working copy of a file was deleted during 1010917721Speterupdate (because it was gone from the repository). 1011017721Speter@end table 1011117721Speter 1011217721Speter@noindent 1011317721SpeterOne of three record types results from commit: 1011417721Speter 1011517721Speter@table @code 1011617721Speter@item A 1011717721SpeterA file was added for the first time. 1011817721Speter@item M 1011917721SpeterA file was modified. 1012017721Speter@item R 1012117721SpeterA file was removed. 1012217721Speter@end table 1012317721Speter@end table 1012417721Speter 1012517721SpeterThe options shown as @samp{-flags} constrain or expand 1012617721Speterthe report without requiring option arguments: 1012717721Speter 1012817721Speter@table @code 1012917721Speter@item -a 1013017721SpeterShow data for all users (the default is to show data 1013117721Speteronly for the user executing @code{history}). 1013217721Speter 1013317721Speter@item -l 1013417721SpeterShow last modification only. 1013517721Speter 1013617721Speter@item -w 1013717721SpeterShow only the records for modifications done from the 1013817721Spetersame working directory where @code{history} is 1013917721Speterexecuting. 1014017721Speter@end table 1014117721Speter 1014217721SpeterThe options shown as @samp{-options @var{args}} constrain the report 1014317721Speterbased on an argument: 1014417721Speter 1014517721Speter@table @code 1014617721Speter@item -b @var{str} 1014717721SpeterShow data back to a record containing the string 1014817721Speter@var{str} in either the module name, the file name, or 1014917721Speterthe repository path. 1015017721Speter 1015117721Speter@item -D @var{date} 1015217721SpeterShow data since @var{date}. This is slightly different 1015317721Speterfrom the normal use of @samp{-D @var{date}}, which 1015417721Speterselects the newest revision older than @var{date}. 1015517721Speter 1015666525Speter@item -f @var{file} 1015766525SpeterShow data for a particular file 1015866525Speter(you can specify several @samp{-f} options on the same command line). 1015966525SpeterThis is equivalent to specifying the file on the command line. 1016066525Speter 1016166525Speter@item -n @var{module} 1016266525SpeterShow data for a particular module 1016366525Speter(you can specify several @samp{-n} options on the same command line). 1016466525Speter 1016517721Speter@item -p @var{repository} 1016617721SpeterShow data for a particular source repository (you 1016717721Spetercan specify several @samp{-p} options on the same command 1016817721Speterline). 1016917721Speter 1017017721Speter@item -r @var{rev} 1017117721SpeterShow records referring to revisions since the revision 1017217721Speteror tag named @var{rev} appears in individual @sc{rcs} 1017317721Speterfiles. Each @sc{rcs} file is searched for the revision or 1017417721Spetertag. 1017517721Speter 1017617721Speter@item -t @var{tag} 1017732785SpeterShow records since tag @var{tag} was last added to the 1017817721Speterhistory file. This differs from the @samp{-r} flag 1017917721Speterabove in that it reads only the history file, not the 1018017721Speter@sc{rcs} files, and is much faster. 1018117721Speter 1018217721Speter@item -u @var{name} 1018317721SpeterShow records for user @var{name}. 1018466525Speter 1018566525Speter@item -z @var{timezone} 1018666525SpeterShow times in the selected records using the specified 1018766525Spetertime zone instead of UTC. 1018817721Speter@end table 1018917721Speter 1019017721Speter@ignore 1019117721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019217721Speter@c @node history examples 1019317721Speter@appendixsubsec history examples 1019417721Speter 1019517721SpeterContributed examples will gratefully be accepted. 1019617721Speter@c -- Examples here! 1019717721Speter@end ignore 1019817721Speter 1019917721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1020017721Speter@node import 1020117721Speter@appendixsec import---Import sources into CVS, using vendor branches 1020266525Speter@cindex import (subcommand) 1020317721Speter 1020425839Speter@c FIXME: This node is way too long for one which has subnodes. 1020525839Speter 1020617721Speter@itemize @bullet 1020717721Speter@item 1020817721SpeterSynopsis: import [-options] repository vendortag releasetag@dots{} 1020917721Speter@item 1021017721SpeterRequires: Repository, source distribution directory. 1021117721Speter@item 1021217721SpeterChanges: repository. 1021317721Speter@end itemize 1021417721Speter 1021517721SpeterUse @code{import} to incorporate an entire source 1021617721Speterdistribution from an outside source (e.g., a source 1021717721Spetervendor) into your source repository directory. You can 1021817721Speteruse this command both for initial creation of a 1021917721Speterrepository, and for wholesale updates to the module 10220177391Sobrienfrom the outside source. See @ref{Tracking sources} for 1022117721Spetera discussion on this subject. 1022217721Speter 1022317721SpeterThe @var{repository} argument gives a directory name 1022417721Speter(or a path to a directory) under the @sc{cvs} root directory 1022517721Speterfor repositories; if the directory did not exist, 1022617721Speterimport creates it. 1022717721Speter 1022817721SpeterWhen you use import for updates to source that has been 1022917721Spetermodified in your source repository (since a prior 1023017721Speterimport), it will notify you of any files that conflict 1023117721Speterin the two branches of development; use @samp{checkout 1023217721Speter-j} to reconcile the differences, as import instructs 1023317721Speteryou to do. 1023417721Speter 1023517721SpeterIf @sc{cvs} decides a file should be ignored 1023617721Speter(@pxref{cvsignore}), it does not import it and prints 10237177391Sobrien@samp{I } followed by the filename (@pxref{import output} for a 1023825839Spetercomplete description of the output). 1023917721Speter 1024017721SpeterIf the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 1024117721Speterany file whose names match the specifications in that 1024217721Speterfile will be treated as packages and the appropriate 1024317721Speterfiltering will be performed on the file/directory 10244177391Sobrienbefore being imported. See @ref{Wrappers}. 1024517721Speter 1024632785SpeterThe outside source is saved in a first-level 1024717721Speterbranch, by default 1.1.1. Updates are leaves of this 1024817721Speterbranch; for example, files from the first imported 1024917721Spetercollection of source will be revision 1.1.1.1, then 1025017721Speterfiles from the first imported update will be revision 1025117721Speter1.1.1.2, and so on. 1025217721Speter 1025317721SpeterAt least three arguments are required. 1025417721Speter@var{repository} is needed to identify the collection 1025517721Speterof source. @var{vendortag} is a tag for the entire 1025617721Speterbranch (e.g., for 1.1.1). You must also specify at 10257175261Sobrienleast one @var{releasetag} to uniquely identify the files at 10258175261Sobrienthe leaves created each time you execute @code{import}. The 10259175261Sobrien@var{releasetag} should be new, not previously existing in the 10260175261Sobrienrepository file, and uniquely identify the imported release, 1026117721Speter 1026225839Speter@c I'm not completely sure this belongs here. But 1026325839Speter@c we need to say it _somewhere_ reasonably obvious; it 1026425839Speter@c is a common misconception among people first learning CVS 1026525839SpeterNote that @code{import} does @emph{not} change the 1026625839Speterdirectory in which you invoke it. In particular, it 1026725839Speterdoes not set up that directory as a @sc{cvs} working 1026825839Speterdirectory; if you want to work with the sources import 1026925839Speterthem first and then check them out into a different 1027025839Speterdirectory (@pxref{Getting the source}). 1027125839Speter 1027217721Speter@menu 1027317721Speter* import options:: import options 1027425839Speter* import output:: import output 1027517721Speter* import examples:: import examples 1027617721Speter@end menu 1027717721Speter 1027817721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027917721Speter@node import options 1028017721Speter@appendixsubsec import options 1028117721Speter 1028217721SpeterThis standard option is supported by @code{import} 10283177391Sobrien(@pxref{Common options} for a complete description): 1028417721Speter 1028517721Speter@table @code 1028617721Speter@item -m @var{message} 1028717721SpeterUse @var{message} as log information, instead of 1028817721Speterinvoking an editor. 1028917721Speter@end table 1029017721Speter 1029132785SpeterThere are the following additional special options. 1029217721Speter 1029317721Speter@table @code 1029417721Speter@item -b @var{branch} 1029526801SpeterSee @ref{Multiple vendor branches}. 1029617721Speter 1029717721Speter@item -k @var{subst} 1029832785SpeterIndicate the keyword expansion mode desired. This 1029917721Spetersetting will apply to all files created during the 1030017721Speterimport, but not to any files that previously existed in 10301177391Sobrienthe repository. See @ref{Substitution modes} for a 1030217721Speterlist of valid @samp{-k} settings. 1030317721Speter 1030417721Speter@item -I @var{name} 1030517721SpeterSpecify file names that should be ignored during 1030617721Speterimport. You can use this option repeatedly. To avoid 1030717721Speterignoring any files at all (even those ignored by 1030817721Speterdefault), specify `-I !'. 1030917721Speter 1031017721Speter@var{name} can be a file name pattern of the same type 1031117721Speterthat you can specify in the @file{.cvsignore} file. 10312177391SobrienSee @ref{cvsignore}. 1031317721Speter@c -- Is this really true? 1031417721Speter 1031517721Speter@item -W @var{spec} 1031617721SpeterSpecify file names that should be filtered during 1031717721Speterimport. You can use this option repeatedly. 1031817721Speter 1031917721Speter@var{spec} can be a file name pattern of the same type 1032017721Speterthat you can specify in the @file{.cvswrappers} 1032117721Speterfile. @xref{Wrappers}. 1032217721Speter@end table 1032317721Speter 1032417721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032525839Speter@node import output 1032625839Speter@appendixsubsec import output 1032725839Speter 1032825839Speter@code{import} keeps you informed of its progress by printing a line 1032925839Speterfor each file, preceded by one character indicating the status of the file: 1033025839Speter 1033125839Speter@table @code 1033225839Speter@item U @var{file} 1033325839SpeterThe file already exists in the repository and has not been locally 1033425839Spetermodified; a new revision has been created (if necessary). 1033525839Speter 1033625839Speter@item N @var{file} 1033725839SpeterThe file is a new file which has been added to the repository. 1033825839Speter 1033925839Speter@item C @var{file} 1034025839SpeterThe file already exists in the repository but has been locally modified; 1034125839Speteryou will have to merge the changes. 1034225839Speter 1034325839Speter@item I @var{file} 1034425839SpeterThe file is being ignored (@pxref{cvsignore}). 1034525839Speter 1034666525Speter@cindex Symbolic link, importing 1034766525Speter@cindex Link, symbolic, importing 1034825839Speter@c FIXME: also (somewhere else) probably 1034925839Speter@c should be documenting what happens if you "cvs add" 1035025839Speter@c a symbolic link. Also maybe what happens if 1035125839Speter@c you manually create symbolic links within the 1035225839Speter@c repository (? - not sure why we'd want to suggest 1035325839Speter@c doing that). 1035425839Speter@item L @var{file} 1035525839SpeterThe file is a symbolic link; @code{cvs import} ignores symbolic links. 1035625839SpeterPeople periodically suggest that this behavior should 1035725839Speterbe changed, but if there is a consensus on what it 1035825839Spetershould be changed to, it doesn't seem to be apparent. 1035925839Speter(Various options in the @file{modules} file can be used 1036025839Speterto recreate symbolic links on checkout, update, etc.; 1036144852Speter@pxref{modules}.) 1036225839Speter@end table 1036325839Speter 1036425839Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036517721Speter@node import examples 1036617721Speter@appendixsubsec import examples 1036717721Speter 1036832785SpeterSee @ref{Tracking sources}, and @ref{From files}. 1036917721Speter 1037017721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1037117721Speter@node log 1037225839Speter@appendixsec log---Print out log information for files 1037366525Speter@cindex log (subcommand) 1037417721Speter 1037517721Speter@itemize @bullet 1037617721Speter@item 1037725839SpeterSynopsis: log [options] [files@dots{}] 1037817721Speter@item 1037917721SpeterRequires: repository, working directory. 1038017721Speter@item 1038117721SpeterChanges: nothing. 1038217721Speter@end itemize 1038317721Speter 1038425839SpeterDisplay log information for files. @code{log} used to 1038525839Spetercall the @sc{rcs} utility @code{rlog}. Although this 1038625839Speteris no longer true in the current sources, this history 1038725839Speterdetermines the format of the output and the options, 1038825839Speterwhich are not quite in the style of the other @sc{cvs} 1038925839Spetercommands. 1039017721Speter 1039166525Speter@cindex Timezone, in output 1039266525Speter@cindex Zone, time, in output 1039325839Speter@c Kind of a funny place to document the timezone used 1039425839Speter@c in output from commands other than @code{log}. 1039525839Speter@c There is also more we need to say about this, 1039625839Speter@c including what happens in a client/server environment. 1039725839SpeterThe output includes the location of the @sc{rcs} file, 1039825839Speterthe @dfn{head} revision (the latest revision on the 1039925839Spetertrunk), all symbolic names (tags) and some other 1040025839Speterthings. For each revision, the revision number, the 1040125839Speterauthor, the number of lines added/deleted and the log 1040225839Spetermessage are printed. All times are displayed in 1040325839SpeterCoordinated Universal Time (UTC). (Other parts of 1040425839Speter@sc{cvs} print times in the local timezone). 1040525839Speter@c FIXCVS: need a better way to control the timezone 1040625839Speter@c used in output. Previous/current versions of CVS did/do 1040725839Speter@c sometimes support -z in RCSINIT, and/or an 1040825839Speter@c undocumented (except by reference to 'rlog') -z option 1040925839Speter@c to cvs log, but this has not been a consistent, 1041025839Speter@c documented feature. Perhaps a new global option, 1041125839Speter@c where LT means the client's timezone, which the 1041225839Speter@c client then communicates to the server, is the 1041325839Speter@c right solution. 1041425839Speter 10415175261Sobrien@strong{@code{log} uses @samp{-R} in a way that conflicts 10416128266Speterwith the normal use inside @sc{cvs} (@pxref{Common options}).} 1041725839Speter 1041817721Speter@menu 1041917721Speter* log options:: log options 1042017721Speter* log examples:: log examples 1042117721Speter@end menu 1042217721Speter 1042317721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042417721Speter@node log options 1042517721Speter@appendixsubsec log options 1042617721Speter 1042725839SpeterBy default, @code{log} prints all information that is 10428175261Sobrienavailable. All other options restrict the output. Note that the revision 10429177391Sobrienselection options (@code{-b}, @code{-d}, @code{-r}, @code{-s}, and @code{-w}) 10430177391Sobrienhave no 10431175261Sobrieneffect, other than possibly causing a search for files in Attic directories, 10432175261Sobrienwhen used in conjunction with the options that restrict the output to only 10433177391Sobrien@code{log} header fields (@code{-h}, @code{-R}, and @code{-t}) 10434175261Sobrienunless the @code{-S} option is also specified. 1043517721Speter 1043617721Speter@table @code 1043717721Speter@item -b 1043817721SpeterPrint information about the revisions on the default 1043917721Speterbranch, normally the highest branch on the trunk. 1044017721Speter 1044125839Speter@item -d @var{dates} 1044217721SpeterPrint information about revisions with a checkin 1044317721Speterdate/time in the range given by the 1044425839Spetersemicolon-separated list of dates. The date formats 1044525839Speteraccepted are those accepted by the @samp{-D} option to 1044625839Spetermany other @sc{cvs} commands (@pxref{Common options}). 1044725839SpeterDates can be combined into ranges as follows: 1044817721Speter 1044925839Speter@c Should we be thinking about accepting ISO8601 1045025839Speter@c ranges? For example "1972-09-10/1972-09-12". 1045117721Speter@table @code 1045217721Speter@item @var{d1}<@var{d2} 1045317721Speter@itemx @var{d2}>@var{d1} 1045417721SpeterSelect the revisions that were deposited between 1045525839Speter@var{d1} and @var{d2}. 1045617721Speter 1045717721Speter@item <@var{d} 1045817721Speter@itemx @var{d}> 1045917721SpeterSelect all revisions dated @var{d} or earlier. 1046017721Speter 1046117721Speter@item @var{d}< 1046217721Speter@itemx >@var{d} 1046317721SpeterSelect all revisions dated @var{d} or later. 1046417721Speter 1046517721Speter@item @var{d} 1046617721SpeterSelect the single, latest revision dated @var{d} or 1046717721Speterearlier. 1046817721Speter@end table 1046917721Speter 1047025839SpeterThe @samp{>} or @samp{<} characters may be followed by 1047125839Speter@samp{=} to indicate an inclusive range rather than an 1047225839Speterexclusive one. 1047317721Speter 1047425839SpeterNote that the separator is a semicolon (;). 1047525839Speter 1047617721Speter@item -h 1047732785SpeterPrint only the name of the @sc{rcs} file, name 1047832785Speterof the file in the working directory, head, 1047917721Speterdefault branch, access list, locks, symbolic names, and 1048017721Spetersuffix. 1048117721Speter 1048225839Speter@item -l 1048325839SpeterLocal; run only in current working directory. (Default 1048425839Speteris to run recursively). 1048525839Speter 1048617721Speter@item -N 1048717721SpeterDo not print the list of tags for this file. This 1048817721Speteroption can be very useful when your site uses a lot of 1048917721Spetertags, so rather than "more"'ing over 3 pages of tag 1049017721Speterinformation, the log information is presented without 1049144852Spetertags at all. 1049217721Speter 10493177391Sobrien@item -n 10494177391SobrienPrint the list of tags for this file. This option can 10495177391Sobrienbe very useful when your @file{.cvsrc} file has a 10496177391Sobrien@samp{log -N} entry as a way to get a full list of all 10497177391Sobrienof the tags. 10498177391Sobrien 1049917721Speter@item -R 1050032785SpeterPrint only the name of the @sc{rcs} file. 1050117721Speter 1050232785Speter@c Note that using a bare revision (in addition to not 1050332785Speter@c being explicitly documented here) is potentially 1050432785Speter@c confusing; it shows the log message to get from the 1050532785Speter@c previous revision to that revision. "-r1.3 -r1.6" 1050644852Speter@c (equivalent to "-r1.3,1.6") is even worse; it 1050732785Speter@c prints the messages to get from 1.2 to 1.3 and 1.5 1050832785Speter@c to 1.6. By analogy with "cvs diff", users might 1050932785Speter@c expect that it is more like specifying a range. 1051032785Speter@c It is not 100% clear to me how much of this should 1051132785Speter@c be documented (for example, multiple -r options 1051232785Speter@c perhaps could/should be deprecated given the false 1051332785Speter@c analogy with "cvs diff"). 1051432785Speter@c In general, this section should be rewritten to talk 1051532785Speter@c about messages to get from revision rev1 to rev2, 1051632785Speter@c rather than messages for revision rev2 (that is, the 1051732785Speter@c messages are associated with a change not a static 1051832785Speter@c revision and failing to make this distinction causes 1051932785Speter@c much confusion). 1052017721Speter@item -r@var{revisions} 1052117721SpeterPrint information about revisions given in the 1052217721Spetercomma-separated list @var{revisions} of revisions and 1052317721Speterranges. The following table explains the available 1052417721Speterrange formats: 1052517721Speter 1052617721Speter@table @code 1052717721Speter@item @var{rev1}:@var{rev2} 1052817721SpeterRevisions @var{rev1} to @var{rev2} (which must be on 1052917721Speterthe same branch). 1053017721Speter 1053181404Speter@item @var{rev1}::@var{rev2} 10532102840SpeterThe same, but excluding @var{rev1}. 1053381404Speter 1053417721Speter@item :@var{rev} 10535102840Speter@itemx ::@var{rev} 1053617721SpeterRevisions from the beginning of the branch up to 1053717721Speterand including @var{rev}. 1053817721Speter 1053944852Speter@item @var{rev}: 1054017721SpeterRevisions starting with @var{rev} to the end of the 1054117721Speterbranch containing @var{rev}. 1054217721Speter 10543102840Speter@item @var{rev}:: 1054481404SpeterRevisions starting just after @var{rev} to the end of the 1054581404Speterbranch containing @var{rev}. 1054681404Speter 1054717721Speter@item @var{branch} 1054817721SpeterAn argument that is a branch means all revisions on 1054925839Speterthat branch. 1055017721Speter 1055117721Speter@item @var{branch1}:@var{branch2} 1055281404Speter@itemx @var{branch1}::@var{branch2} 1055317721SpeterA range of branches means all revisions 1055417721Speteron the branches in that range. 1055517721Speter 1055617721Speter@item @var{branch}. 1055717721SpeterThe latest revision in @var{branch}. 1055817721Speter@end table 1055917721Speter 1056017721SpeterA bare @samp{-r} with no revisions means the latest 1056117721Speterrevision on the default branch, normally the trunk. 1056225839SpeterThere can be no space between the @samp{-r} option and 1056325839Speterits argument. 1056417721Speter 10565102840Speter@item -S 10566102840SpeterSuppress the header if no revisions are selected. 10567102840Speter 1056825839Speter@item -s @var{states} 1056917721SpeterPrint information about revisions whose state 1057017721Speterattributes match one of the states given in the 10571175261Sobriencomma-separated list @var{states}. Individual states may 10572175261Sobrienbe any text string, though @sc{cvs} commonly only uses two 10573175261Sobrienstates, @samp{Exp} and @samp{dead}. See @ref{admin options} 10574175261Sobrienfor more information. 1057517721Speter 1057617721Speter@item -t 1057717721SpeterPrint the same as @samp{-h}, plus the descriptive text. 1057817721Speter 1057917721Speter@item -w@var{logins} 1058017721SpeterPrint information about revisions checked in by users 1058117721Speterwith login names appearing in the comma-separated list 1058217721Speter@var{logins}. If @var{logins} is omitted, the user's 1058325839Speterlogin is assumed. There can be no space between the 1058425839Speter@samp{-w} option and its argument. 1058517721Speter@end table 1058617721Speter 1058725839Speter@code{log} prints the intersection of the revisions 1058825839Speterselected with the options @samp{-d}, @samp{-s}, and 1058925839Speter@samp{-w}, intersected with the union of the revisions 1059025839Speterselected by @samp{-b} and @samp{-r}. 1059117721Speter 1059217721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059317721Speter@node log examples 1059417721Speter@appendixsubsec log examples 1059517721Speter 1059617721SpeterContributed examples are gratefully accepted. 1059717721Speter 1059817721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1059917721Speter@node rdiff 1060017721Speter@appendixsec rdiff---'patch' format diffs between releases 1060166525Speter@cindex rdiff (subcommand) 1060217721Speter 1060317721Speter@itemize @bullet 1060417721Speter@item 1060517721Speterrdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{} 1060617721Speter@item 1060717721SpeterRequires: repository. 1060817721Speter@item 1060917721SpeterChanges: nothing. 1061017721Speter@item 1061117721SpeterSynonym: patch 1061217721Speter@end itemize 1061317721Speter 1061417721SpeterBuilds a Larry Wall format patch(1) file between two 1061532785Speterreleases, that can be fed directly into the @code{patch} 1061617721Speterprogram to bring an old release up-to-date with the new 1061717721Speterrelease. (This is one of the few @sc{cvs} commands that 1061817721Speteroperates directly from the repository, and doesn't 1061917721Speterrequire a prior checkout.) The diff output is sent to 1062017721Speterthe standard output device. 1062117721Speter 1062217721SpeterYou can specify (using the standard @samp{-r} and 1062317721Speter@samp{-D} options) any combination of one or two 1062417721Speterrevisions or dates. If only one revision or date is 1062517721Speterspecified, the patch file reflects differences between 1062617721Speterthat revision or date and the current head revisions in 1062717721Speterthe @sc{rcs} file. 1062817721Speter 1062917721SpeterNote that if the software release affected is contained 1063017721Speterin more than one directory, then it may be necessary to 1063132785Speterspecify the @samp{-p} option to the @code{patch} command when 1063232785Speterpatching the old sources, so that @code{patch} is able to find 1063317721Speterthe files that are located in other directories. 1063417721Speter 1063517721Speter@menu 1063617721Speter* rdiff options:: rdiff options 1063717721Speter* rdiff examples:: rdiff examples 1063817721Speter@end menu 1063917721Speter 1064017721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064117721Speter@node rdiff options 1064217721Speter@appendixsubsec rdiff options 1064317721Speter 1064417721SpeterThese standard options are supported by @code{rdiff} 10645177391Sobrien(@pxref{Common options} for a complete description of 1064617721Speterthem): 1064717721Speter 1064817721Speter@table @code 1064917721Speter@item -D @var{date} 1065017721SpeterUse the most recent revision no later than @var{date}. 1065117721Speter 1065217721Speter@item -f 1065317721SpeterIf no matching revision is found, retrieve the most 1065417721Speterrecent revision (instead of ignoring the file). 1065517721Speter 10656175261Sobrien@item -k @var{kflag} 10657175261SobrienProcess keywords according to @var{kflag}. See 10658175261Sobrien@ref{Keyword substitution}. 10659175261Sobrien 1066017721Speter@item -l 1066117721SpeterLocal; don't descend subdirectories. 1066217721Speter 1066325839Speter@item -R 1066425839SpeterExamine directories recursively. This option is on by default. 1066525839Speter 1066617721Speter@item -r @var{tag} 1066717721SpeterUse revision @var{tag}. 1066817721Speter@end table 1066917721Speter 1067017721SpeterIn addition to the above, these options are available: 1067117721Speter 1067217721Speter@table @code 1067317721Speter@item -c 1067417721SpeterUse the context diff format. This is the default format. 1067517721Speter 1067617721Speter@item -s 1067717721SpeterCreate a summary change report instead of a patch. The 1067817721Spetersummary includes information about files that were 1067917721Speterchanged or added between the releases. It is sent to 1068017721Speterthe standard output device. This is useful for finding 1068117721Speterout, for example, which files have changed between two 1068217721Speterdates or revisions. 1068317721Speter 1068417721Speter@item -t 1068517721SpeterA diff of the top two revisions is sent to the standard 1068617721Speteroutput device. This is most useful for seeing what the 1068717721Speterlast change to a file was. 1068817721Speter 1068917721Speter@item -u 1069017721SpeterUse the unidiff format for the context diffs. 1069154427SpeterRemember that old versions 1069217721Speterof the @code{patch} program can't handle the unidiff 1069317721Speterformat, so if you plan to post this patch to the net 1069417721Speteryou should probably not use @samp{-u}. 1069517721Speter 1069617721Speter@item -V @var{vn} 1069732785SpeterExpand keywords according to the rules current in 1069817721Speter@sc{rcs} version @var{vn} (the expansion format changed with 1069934461Speter@sc{rcs} version 5). Note that this option is no 1070081404Speterlonger accepted. @sc{cvs} will always expand keywords the 1070134461Speterway that @sc{rcs} version 5 does. 1070217721Speter@end table 1070317721Speter 1070417721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070517721Speter@node rdiff examples 1070617721Speter@appendixsubsec rdiff examples 1070717721Speter 1070854427SpeterSuppose you receive mail from @t{foo@@example.net} asking for an 1070917721Speterupdate from release 1.2 to 1.4 of the tc compiler. You 1071017721Speterhave no such patches on hand, but with @sc{cvs} that can 1071117721Spetereasily be fixed with a command such as this: 1071217721Speter 1071317721Speter@example 1071417721Speter$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 10715177391Sobrien> Mail -s 'The patches you asked for' foo@@example.net 1071617721Speter@end example 1071717721Speter 1071817721SpeterSuppose you have made release 1.3, and forked a branch 10719130303Spetercalled @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1} 1072017721Spetercorresponds to release 1.3.1, which was made some time 1072117721Speterago. Now, you want to see how much development has been 1072217721Speterdone on the branch. This command can be used: 1072317721Speter 1072417721Speter@example 1072517721Speter$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 1072617721Spetercvs rdiff: Diffing module-name 1072717721SpeterFile ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 1072817721SpeterFile foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 1072917721SpeterFile bar.h,v changed from revision 1.29.2.1 to 1.2 1073017721Speter@end example 1073117721Speter 1073217721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1073317721Speter@node release 1073417721Speter@appendixsec release---Indicate that a Module is no longer in use 1073566525Speter@cindex release (subcommand) 1073617721Speter 1073717721Speter@itemize @bullet 1073817721Speter@item 1073917721Speterrelease [-d] directories@dots{} 1074017721Speter@item 1074117721SpeterRequires: Working directory. 1074217721Speter@item 1074317721SpeterChanges: Working directory, history log. 1074417721Speter@end itemize 1074517721Speter 1074617721SpeterThis command is meant to safely cancel the effect of 1074717721Speter@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it 1074817721Speterisn't strictly necessary to use this command. You can 1074917721Speteralways simply delete your working directory, if you 1075017721Speterlike; but you risk losing changes you may have 1075117721Speterforgotten, and you leave no trace in the @sc{cvs} history 1075217721Speterfile (@pxref{history file}) that you've abandoned your 1075317721Spetercheckout. 1075417721Speter 1075517721SpeterUse @samp{cvs release} to avoid these problems. This 1075617721Spetercommand checks that no uncommitted changes are 1075717721Speterpresent; that you are executing it from immediately 1075817721Speterabove a @sc{cvs} working directory; and that the repository 1075917721Speterrecorded for your files is the same as the repository 1076017721Speterdefined in the module database. 1076117721Speter 1076217721SpeterIf all these conditions are true, @samp{cvs release} 1076317721Speterleaves a record of its execution (attesting to your 1076417721Speterintentionally abandoning your checkout) in the @sc{cvs} 1076517721Speterhistory log. 1076617721Speter 1076717721Speter@menu 1076817721Speter* release options:: release options 1076925839Speter* release output:: release output 1077017721Speter* release examples:: release examples 1077117721Speter@end menu 1077217721Speter 1077317721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077417721Speter@node release options 1077517721Speter@appendixsubsec release options 1077617721Speter 1077717721SpeterThe @code{release} command supports one command option: 1077817721Speter 1077917721Speter@table @code 1078017721Speter@item -d 1078117721SpeterDelete your working copy of the file if the release 1078217721Spetersucceeds. If this flag is not given your files will 1078317721Speterremain in your working directory. 1078417721Speter 10785128266Speter@strong{WARNING: The @code{release} command deletes 1078625839Speterall directories and files recursively. This 1078717721Speterhas the very serious side-effect that any directory 10788177391Sobriencreated inside checked-out sources, and not added to 10789177391Sobrienthe repository (using the @code{add} command; 10790177391Sobrien@pxref{Adding files}) will be silently deleted---even 10791128266Speterif it is non-empty!} 1079217721Speter@end table 1079317721Speter 1079417721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079517721Speter@node release output 1079617721Speter@appendixsubsec release output 1079717721Speter 1079817721SpeterBefore @code{release} releases your sources it will 1079917721Speterprint a one-line message for any file that is not 1080044852Speterup-to-date. 1080117721Speter 1080217721Speter@table @code 1080317721Speter@item U @var{file} 1080425839Speter@itemx P @var{file} 1080517721SpeterThere exists a newer revision of this file in the 1080617721Speterrepository, and you have not modified your local copy 1080725839Speterof the file (@samp{U} and @samp{P} mean the same thing). 1080817721Speter 1080917721Speter@item A @var{file} 1081017721SpeterThe file has been added to your private copy of the 1081117721Spetersources, but has not yet been committed to the 1081217721Speterrepository. If you delete your copy of the sources 1081317721Speterthis file will be lost. 1081417721Speter 1081517721Speter@item R @var{file} 1081617721SpeterThe file has been removed from your private copy of the 1081717721Spetersources, but has not yet been removed from the 1081817721Speterrepository, since you have not yet committed the 10819177391Sobrienremoval. See @ref{commit}. 1082017721Speter 1082117721Speter@item M @var{file} 1082217721SpeterThe file is modified in your working directory. There 1082317721Spetermight also be a newer revision inside the repository. 1082417721Speter 1082517721Speter@item ? @var{file} 1082617721Speter@var{file} is in your working directory, but does not 1082717721Spetercorrespond to anything in the source repository, and is 1082817721Speternot in the list of files for @sc{cvs} to ignore (see the 1082917721Speterdescription of the @samp{-I} option, and 1083017721Speter@pxref{cvsignore}). If you remove your working 1083117721Spetersources, this file will be lost. 1083217721Speter@end table 1083317721Speter 1083417721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083517721Speter@node release examples 1083617721Speter@appendixsubsec release examples 1083717721Speter 1083854427SpeterRelease the @file{tc} directory, and delete your local working copy 1083917721Speterof the files. 1084017721Speter 1084117721Speter@example 1084217721Speter$ cd .. # @r{You must stand immediately above the} 1084317721Speter # @r{sources when you issue @samp{cvs release}.} 1084417721Speter$ cvs release -d tc 1084517721SpeterYou have [0] altered files in this repository. 1084654427SpeterAre you sure you want to release (and delete) directory `tc': y 1084717721Speter$ 1084817721Speter@end example 1084917721Speter 1085017721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10851177391Sobrien@node remove 10852177391Sobrien@appendixsec remove---Remove files from active use 10853177391Sobrien@cindex remove (subcommand) 10854177391Sobrien 10855177391Sobrien@itemize @bullet 10856177391Sobrien@item 10857177391SobrienSynopsis: remove [-flR] [files...] 10858177391Sobrien@item 10859177391SobrienRequires: repository, working directory. 10860177391Sobrien@item 10861177391SobrienChanges: working directory. 10862177391Sobrien@end itemize 10863177391Sobrien 10864177391SobrienThe @code{remove} command is used to remove unwanted 10865177391Sobrienfiles from active use. The user normally deletes the 10866177391Sobrienfiles from the working directory prior to invocation 10867177391Sobrienof the @code{remove} command. Only the working 10868177391Sobriendirectory is updated. Changes to the repository are 10869177391Sobriennot made until the @code{commit} command is run. 10870177391Sobrien 10871177391SobrienThe @code{remove} command does not delete files from 10872177391Sobrienfrom the repository. @sc{cvs} keeps all historical 10873177391Sobriendata in the repository so that it is possible to 10874177391Sobrienreconstruct previous states of the projects under 10875177391Sobrienrevision control. 10876177391Sobrien 10877177391SobrienTo undo @sc{cvs} @code{remove} or to resurrect files 10878177391Sobrienthat were previously removed, @xref{add}. 10879177391Sobrien 10880177391Sobrien@menu 10881177391Sobrien* remove options:: remove options 10882177391Sobrien* remove examples:: remove examples 10883177391Sobrien@end menu 10884177391Sobrien 10885177391Sobrien@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10886177391Sobrien@node remove options 10887177391Sobrien@appendixsubsec remove options 10888177391Sobrien 10889177391SobrienThese standard options are supported by @code{remove} 10890177391Sobrien(@pxref{Common options} for a complete description of 10891177391Sobrienthem): 10892177391Sobrien 10893177391Sobrien@table @code 10894177391Sobrien@item -l 10895177391SobrienLocal; run only in current working directory. See @ref{Recursive behavior}. 10896177391Sobrien 10897177391Sobrien@item -R 10898177391SobrienProcess directories recursively. See @ref{Recursive behavior}. 10899177391Sobrien 10900177391Sobrien@end table 10901177391Sobrien 10902177391SobrienIn addition, these options are also supported: 10903177391Sobrien 10904177391Sobrien@table @code 10905177391Sobrien@item -f 10906177391SobrienNote that this is not the standard behavior of 10907177391Sobrienthe @samp{-f} option as defined in @ref{Common options}. 10908177391Sobrien 10909177391SobrienDelete files before removing them. 10910177391Sobrien 10911177391SobrienEntire directory hierarchies are easily removed 10912177391Sobrienusing @samp{-f}, but take note that it is not as 10913177391Sobrieneasy to resurrect directory hierarchies as it is 10914177391Sobriento remove them. 10915177391Sobrien 10916177391Sobrien@end table 10917177391Sobrien 10918177391Sobrien@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10919177391Sobrien@node remove examples 10920177391Sobrien@appendixsubsec remove examples 10921177391Sobrien 10922177391Sobrien@appendixsubsubsec Removing a file 10923177391Sobrien 10924177391Sobrien@example 10925177391Sobrien$ cvs remove remove.me 10926177391Sobriencvs remove: file `remove.me' still in working directory 10927177391Sobriencvs remove: 1 file exists; remove it first 10928177391Sobrien$ rm -f remove.me 10929177391Sobrien$ cvs remove remove.me 10930177391Sobriencvs remove: scheduling `remove.me' for removal 10931177391Sobriencvs remove: use 'cvs commit' to remove this file permanently 10932177391Sobrien 10933177391Sobrien$ ls remove.it 10934177391Sobrienremove.it 10935177391Sobrien$ cvs remove -f remove.it 10936177391Sobriencvs remove: scheduling `remove.it' for removal 10937177391Sobriencvs remove: use 'cvs commit' to remove this file permanently 10938177391Sobrien@end example 10939177391Sobrien 10940177391Sobrien@appendixsubsubsec Removing entire directories 10941177391Sobrien@example 10942177391Sobrien$ tree -d a 10943177391Sobriena 10944177391Sobrien|-- CVS 10945177391Sobrien`-- b 10946177391Sobrien `-- CVS 10947177391Sobrien 10948177391Sobrien3 directories 10949177391Sobrien$ cvs remove -f a 10950177391Sobriencvs remove: Removing a 10951177391Sobriencvs remove: Removing a/b 10952177391Sobriencvs remove: scheduling `a/b/c' for removal 10953177391Sobriencvs remove: use 'cvs commit' to remove this file permanently 10954177391Sobrien@end example 10955177391Sobrien 10956177391Sobrien@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1095717721Speter@node update 1095817721Speter@appendixsec update---Bring work tree in sync with repository 1095966525Speter@cindex update (subcommand) 1096017721Speter 1096117721Speter@itemize @bullet 1096217721Speter@item 10963102840Speterupdate [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files@dots{} 1096417721Speter@item 1096517721SpeterRequires: repository, working directory. 1096617721Speter@item 1096717721SpeterChanges: working directory. 1096817721Speter@end itemize 1096917721Speter 1097017721SpeterAfter you've run checkout to create your private copy 1097117721Speterof source from the common repository, other developers 1097217721Speterwill continue changing the central source. From time 1097317721Speterto time, when it is convenient in your development 1097417721Speterprocess, you can use the @code{update} command from 1097517721Speterwithin your working directory to reconcile your work 1097617721Speterwith any revisions applied to the source repository 1097717721Spetersince your last checkout or update. 1097817721Speter 1097917721Speter@menu 1098017721Speter* update options:: update options 1098117721Speter* update output:: update output 1098217721Speter@end menu 1098317721Speter 1098417721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098517721Speter@node update options 1098617721Speter@appendixsubsec update options 1098717721Speter 1098817721SpeterThese standard options are available with @code{update} 10989177391Sobrien(@pxref{Common options} for a complete description of 1099017721Speterthem): 1099117721Speter 1099217721Speter@table @code 1099317721Speter@item -D date 1099417721SpeterUse the most recent revision no later than @var{date}. 1099517721SpeterThis option is sticky, and implies @samp{-P}. 10996177391SobrienSee @ref{Sticky tags} for more information on sticky tags/dates. 1099717721Speter 1099817721Speter@item -f 1099917721SpeterOnly useful with the @samp{-D @var{date}} or @samp{-r 1100017721Speter@var{tag}} flags. If no matching revision is found, 1100117721Speterretrieve the most recent revision (instead of ignoring 1100217721Speterthe file). 1100317721Speter 1100417721Speter@item -k @var{kflag} 1100532785SpeterProcess keywords according to @var{kflag}. See 1100632785Speter@ref{Keyword substitution}. 1100732785SpeterThis option is sticky; future updates of 1100817721Speterthis file in this working directory will use the same 1100917721Speter@var{kflag}. The @code{status} command can be viewed 11010177391Sobriento see the sticky options. See @ref{Invoking CVS} for 1101125839Spetermore information on the @code{status} command. 1101217721Speter 1101317721Speter@item -l 11014177391SobrienLocal; run only in current working directory. See @ref{Recursive behavior}. 1101517721Speter 1101617721Speter@item -P 1101725839SpeterPrune empty directories. See @ref{Moving directories}. 1101817721Speter 1101917721Speter@item -p 1102017721SpeterPipe files to the standard output. 1102117721Speter 1102217721Speter@item -R 11023177391SobrienUpdate directories recursively (default). See @ref{Recursive 1102425839Speterbehavior}. 1102517721Speter 1102632785Speter@item -r rev 1102732785SpeterRetrieve revision/tag @var{rev}. This option is sticky, 1102817721Speterand implies @samp{-P}. 1102917721SpeterSee @ref{Sticky tags}, for more information on sticky tags/dates. 1103017721Speter@end table 1103117721Speter 1103217721Speter@need 800 1103317721SpeterThese special options are also available with 1103417721Speter@code{update}. 1103517721Speter 1103617721Speter@table @code 1103717721Speter@item -A 1103817721SpeterReset any sticky tags, dates, or @samp{-k} options. 11039175261SobrienDoes not reset sticky @samp{-k} options on modified files. 11040177391SobrienSee @ref{Sticky tags} for more information on sticky tags/dates. 1104117721Speter 1104266525Speter@item -C 1104366525SpeterOverwrite locally modified files with clean copies from 1104466525Speterthe repository (the modified file is saved in 1104566525Speter@file{.#@var{file}.@var{revision}}, however). 1104666525Speter 1104717721Speter@item -d 1104817721SpeterCreate any directories that exist in the repository if 1104917721Speterthey're missing from the working directory. Normally, 1105017721Speter@code{update} acts only on directories and files that 1105144852Speterwere already enrolled in your working directory. 1105217721Speter 1105317721SpeterThis is useful for updating directories that were 1105417721Spetercreated in the repository since the initial checkout; 1105517721Speterbut it has an unfortunate side effect. If you 1105617721Speterdeliberately avoided certain directories in the 1105717721Speterrepository when you created your working directory 1105817721Speter(either through use of a module name or by listing 1105917721Speterexplicitly the files and directories you wanted on the 1106017721Spetercommand line), then updating with @samp{-d} will create 1106117721Speterthose directories, which may not be what you want. 1106217721Speter 1106317721Speter@item -I @var{name} 1106417721SpeterIgnore files whose names match @var{name} (in your 1106517721Speterworking directory) during the update. You can specify 1106617721Speter@samp{-I} more than once on the command line to specify 1106717721Speterseveral files to ignore. Use @samp{-I !} to avoid 11068177391Sobrienignoring any files at all. See @ref{cvsignore} for other 1106917721Speterways to make @sc{cvs} ignore some files. 1107017721Speter 1107117721Speter@item -W@var{spec} 1107217721SpeterSpecify file names that should be filtered during 1107317721Speterupdate. You can use this option repeatedly. 1107417721Speter 1107517721Speter@var{spec} can be a file name pattern of the same type 1107617721Speterthat you can specify in the @file{.cvswrappers} 11077177391Sobrienfile. See @ref{Wrappers}. 1107817721Speter 1107917721Speter@item -j@var{revision} 1108017721SpeterWith two @samp{-j} options, merge changes from the 1108117721Speterrevision specified with the first @samp{-j} option to 1108217721Speterthe revision specified with the second @samp{j} option, 1108317721Speterinto the working directory. 1108417721Speter 1108517721SpeterWith one @samp{-j} option, merge changes from the 1108617721Speterancestor revision to the revision specified with the 1108717721Speter@samp{-j} option, into the working directory. The 1108817721Speterancestor revision is the common ancestor of the 1108917721Speterrevision which the working directory is based on, and 1109017721Speterthe revision specified in the @samp{-j} option. 1109117721Speter 1109281404SpeterNote that using a single @samp{-j @var{tagname}} option rather than 1109381404Speter@samp{-j @var{branchname}} to merge changes from a branch will 1109481404Speteroften not remove files which were removed on the branch. 11095177391SobrienSee @ref{Merging adds and removals} for more information. 1109681404Speter 1109732785SpeterIn addition, each @samp{-j} option can contain an optional 1109817721Speterdate specification which, when used with branches, can 1109917721Speterlimit the chosen revision to one within a specific 1110017721Speterdate. An optional date is specified by adding a colon 1110117721Speter(:) to the tag: 1110217721Speter@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 1110317721Speter 11104177391SobrienSee @ref{Branching and merging}. 1110517721Speter 1110617721Speter@end table 1110717721Speter 1110817721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110917721Speter@node update output 1111017721Speter@appendixsubsec update output 1111117721Speter 1111225839Speter@code{update} and @code{checkout} keep you informed of 1111332785Spetertheir progress by printing a line for each file, preceded 1111425839Speterby one character indicating the status of the file: 1111517721Speter 1111617721Speter@table @code 1111717721Speter@item U @var{file} 1111817721SpeterThe file was brought up to date with respect to the 1111917721Speterrepository. This is done for any file that exists in 11120175261Sobrienthe repository but not in your working directory, and for files 1112117721Speterthat you haven't changed but are not the most recent 1112217721Speterversions available in the repository. 1112317721Speter 1112425839Speter@item P @var{file} 11125102840SpeterLike @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 11126102840Speterfile. This accomplishes the same thing as @samp{U} using less bandwidth. 1112725839Speter 1112817721Speter@item A @var{file} 1112917721SpeterThe file has been added to your private copy of the 1113017721Spetersources, and will be added to the source repository 1113117721Speterwhen you run @code{commit} on the file. This is a 1113217721Speterreminder to you that the file needs to be committed. 1113317721Speter 1113417721Speter@item R @var{file} 1113517721SpeterThe file has been removed from your private copy of the 1113617721Spetersources, and will be removed from the source repository 1113717721Speterwhen you run @code{commit} on the file. This is a 1113817721Speterreminder to you that the file needs to be committed. 1113917721Speter 1114017721Speter@item M @var{file} 1114117721SpeterThe file is modified in your working directory. 1114217721Speter 1114317721Speter@samp{M} can indicate one of two states for a file 1114417721Speteryou're working on: either there were no modifications 1114517721Speterto the same file in the repository, so that your file 1114617721Speterremains as you last saw it; or there were modifications 1114717721Speterin the repository as well as in your copy, but they 1114817721Speterwere merged successfully, without conflict, in your 1114917721Speterworking directory. 1115017721Speter 1115117721Speter@sc{cvs} will print some messages if it merges your work, 1115217721Speterand a backup copy of your working file (as it looked 1115317721Speterbefore you ran @code{update}) will be made. The exact 1115417721Spetername of that file is printed while @code{update} runs. 1115517721Speter 1115617721Speter@item C @var{file} 1115725839Speter@cindex .# files 1115825839Speter@cindex __ files (VMS) 1115917721SpeterA conflict was detected while trying to merge your 1116017721Speterchanges to @var{file} with changes from the source 1116117721Speterrepository. @var{file} (the copy in your working 1116232785Speterdirectory) is now the result of attempting to merge 1116332785Speterthe two revisions; an unmodified copy of your file 1116417721Speteris also in your working directory, with the name 1116517721Speter@file{.#@var{file}.@var{revision}} where @var{revision} 1116632785Speteris the revision that your modified file started 1116725839Speterfrom. Resolve the conflict as described in 1116832785Speter@ref{Conflicts example}. 1116925839Speter@c "some systems" as in out-of-the-box OSes? Not as 1117025839Speter@c far as I know. We need to advise sysadmins as well 1117125839Speter@c as users how to set up this kind of purge, if that is 1117225839Speter@c what they want. 1117325839Speter@c We also might want to think about cleaner solutions, 1117425839Speter@c like having CVS remove the .# file once the conflict 1117525839Speter@c has been resolved or something like that. 1117625839Speter(Note that some systems automatically purge 1117717721Speterfiles that begin with @file{.#} if they have not been 1117817721Speteraccessed for a few days. If you intend to keep a copy 1117917721Speterof your original file, it is a very good idea to rename 1118025839Speterit.) Under @sc{vms}, the file name starts with 1118125839Speter@file{__} rather than @file{.#}. 1118217721Speter 1118317721Speter@item ? @var{file} 1118417721Speter@var{file} is in your working directory, but does not 1118517721Spetercorrespond to anything in the source repository, and is 1118617721Speternot in the list of files for @sc{cvs} to ignore (see the 1118717721Speterdescription of the @samp{-I} option, and 1118817721Speter@pxref{cvsignore}). 1118925839Speter@end table 1119017721Speter 11191130303Speter@c ----- END MAN 1 ----- 11192130303Speter@c --------------------------------------------------------------------- 1119325839Speter@node Invoking CVS 1119425839Speter@appendix Quick reference to CVS commands 1119525839Speter@cindex Command reference 1119625839Speter@cindex Reference, commands 1119725839Speter@cindex Invoking CVS 1119825839Speter 1119925839SpeterThis appendix describes how to invoke @sc{cvs}, with 1120025839Speterreferences to where each command or feature is 1120134461Speterdescribed in detail. For other references run the 1120234461Speter@code{cvs --help} command, or see @ref{Index}. 1120325839Speter 1120434461SpeterA @sc{cvs} command looks like: 1120534461Speter 1120634461Speter@example 1120734461Spetercvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 1120834461Speter@end example 1120934461Speter 1121034461SpeterGlobal options: 1121134461Speter 1121234461Speter@table @code 1121334461Speter@item --allow-root=@var{rootdir} 1121434461SpeterSpecify legal @sc{cvsroot} directory (server only) (not 1121534461Speterin @sc{cvs} 1.9 and older). See @ref{Password 1121634461Speterauthentication server}. 1121734461Speter 1121834461Speter@item -a 1121934461SpeterAuthenticate all communication (client only) (not in @sc{cvs} 1122034461Speter1.9 and older). See @ref{Global options}. 1122134461Speter 1122234461Speter@item -b 1122334461SpeterSpecify RCS location (@sc{cvs} 1.9 and older). See 1122434461Speter@ref{Global options}. 1122534461Speter 1122634461Speter@item -d @var{root} 1122734461SpeterSpecify the @sc{cvsroot}. See @ref{Repository}. 1122834461Speter 1122934461Speter@item -e @var{editor} 1123034461SpeterEdit messages with @var{editor}. See @ref{Committing 1123134461Speteryour changes}. 1123234461Speter 1123334461Speter@item -f 1123434461SpeterDo not read the @file{~/.cvsrc} file. See @ref{Global 1123534461Speteroptions}. 1123634461Speter 1123734461Speter@item -H 1123834461Speter@itemx --help 1123934461SpeterPrint a help message. See @ref{Global options}. 1124034461Speter 1124134461Speter@item -n 1124234461SpeterDo not change any files. See @ref{Global options}. 1124334461Speter 1124434461Speter@item -Q 1124544852SpeterBe really quiet. See @ref{Global options}. 1124634461Speter 1124734461Speter@item -q 1124844852SpeterBe somewhat quiet. See @ref{Global options}. 1124934461Speter 1125034461Speter@item -r 1125144852SpeterMake new working files read-only. See @ref{Global options}. 1125234461Speter 1125334461Speter@item -s @var{variable}=@var{value} 1125434461SpeterSet a user variable. See @ref{Variables}. 1125534461Speter 1125634461Speter@item -T @var{tempdir} 1125734461SpeterPut temporary files in @var{tempdir}. See @ref{Global 1125834461Speteroptions}. 1125934461Speter 1126034461Speter@item -t 1126134461SpeterTrace @sc{cvs} execution. See @ref{Global options}. 1126234461Speter 1126334461Speter@item -v 1126434461Speter@item --version 1126534461SpeterDisplay version and copyright information for @sc{cvs}. 1126634461Speter 1126734461Speter@item -w 1126834461SpeterMake new working files read-write. See @ref{Global 1126934461Speteroptions}. 1127034461Speter 1127134461Speter@item -x 1127266525SpeterEncrypt all communication (client only). 1127366525SpeterSee @ref{Global options}. 1127434461Speter 1127534461Speter@item -z @var{gzip-level} 1127666525Speter@cindex Compression 1127766525Speter@cindex Gzip 1127834461SpeterSet the compression level (client only). 1127966525SpeterSee @ref{Global options}. 1128034461Speter@end table 1128134461Speter 1128234461SpeterKeyword expansion modes (@pxref{Substitution modes}): 1128334461Speter 1128434461Speter@example 11285130303Speter-kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 11286130303Speter-kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11287130303Speter-kk $@splitrcskeyword{Id}$ 1128834461Speter-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 1128934461Speter-ko @i{no expansion} 1129034461Speter-kb @i{no expansion, file is binary} 1129134461Speter@end example 1129234461Speter 1129334461SpeterKeywords (@pxref{Keyword list}): 1129434461Speter 1129534461Speter@example 11296130303Speter$@splitrcskeyword{Author}: joe $ 11297130303Speter$@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ 11298130303Speter$@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11299130303Speter$@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11300130303Speter$@splitrcskeyword{Locker}: harry $ 11301130303Speter$@splitrcskeyword{Name}: snapshot_1_14 $ 11302130303Speter$@splitrcskeyword{RCSfile}: file1,v $ 11303130303Speter$@splitrcskeyword{Revision}: 1.1 $ 11304130303Speter$@splitrcskeyword{Source}: /home/files/file1,v $ 11305130303Speter$@splitrcskeyword{State}: Exp $ 11306130303Speter$@splitrcskeyword{Log}: file1,v $ 1130734461SpeterRevision 1.1 1993/12/09 03:30:17 joe 1130834461SpeterInitial revision 1130934461Speter 1131034461Speter@end example 1131134461Speter 1131225839Speter@c The idea behind this table is that we want each item 1131325839Speter@c to be a sentence or two at most. Preferably a 1131425839Speter@c single line. 1131544852Speter@c 1131625839Speter@c In some cases refs to "foo options" are just to get 1131725839Speter@c this thing written quickly, not because the "foo 1131825839Speter@c options" node is really the best place to point. 1131934461SpeterCommands, command options, and command arguments: 1132034461Speter 1132125839Speter@table @code 11322102840Speter@c ------------------------------------------------------------ 1132325839Speter@item add [@var{options}] [@var{files}@dots{}] 1132425839SpeterAdd a new file/directory. See @ref{Adding files}. 1132525839Speter 1132625839Speter@table @code 1132725839Speter@item -k @var{kflag} 1132825839SpeterSet keyword expansion. 1132925839Speter 1133025839Speter@item -m @var{msg} 1133125839SpeterSet file description. 1133217721Speter@end table 1133317721Speter 11334102840Speter@c ------------------------------------------------------------ 1133525839Speter@item admin [@var{options}] [@var{files}@dots{}] 1133625839SpeterAdministration of history files in the repository. See 1133725839Speter@ref{admin}. 1133825839Speter@c This list omits those options which are not 1133925839Speter@c documented as being useful with CVS. That might be 1134025839Speter@c a mistake... 1134117721Speter 1134225839Speter@table @code 1134325839Speter@item -b[@var{rev}] 1134434461SpeterSet default branch. See @ref{Reverting local changes}. 1134517721Speter 1134625839Speter@item -c@var{string} 1134725839SpeterSet comment leader. 1134817721Speter 1134925839Speter@item -k@var{subst} 1135025839SpeterSet keyword substitution. See @ref{Keyword 1135125839Spetersubstitution}. 1135225839Speter 1135325839Speter@item -l[@var{rev}] 1135425839SpeterLock revision @var{rev}, or latest revision. 1135525839Speter 1135625839Speter@item -m@var{rev}:@var{msg} 1135725839SpeterReplace the log message of revision @var{rev} with 1135825839Speter@var{msg}. 1135925839Speter 1136025839Speter@item -o@var{range} 1136132785SpeterDelete revisions from the repository. See 1136232785Speter@ref{admin options}. 1136325839Speter 1136425839Speter@item -q 1136525839SpeterRun quietly; do not print diagnostics. 1136625839Speter 1136725839Speter@item -s@var{state}[:@var{rev}] 11368175261SobrienSet the state. See @ref{admin options} for more information on possible 11369175261Sobrienstates. 1137025839Speter 1137125839Speter@c Does not work for client/server CVS 1137225839Speter@item -t 1137325839SpeterSet file description from standard input. 1137425839Speter 1137525839Speter@item -t@var{file} 1137625839SpeterSet file description from @var{file}. 1137725839Speter 1137825839Speter@item -t-@var{string} 1137925839SpeterSet file description to @var{string}. 1138025839Speter 1138125839Speter@item -u[@var{rev}] 1138225839SpeterUnlock revision @var{rev}, or latest revision. 1138325839Speter@end table 1138425839Speter 11385102840Speter@c ------------------------------------------------------------ 1138625839Speter@item annotate [@var{options}] [@var{files}@dots{}] 1138725839SpeterShow last revision where each line was modified. See 1138825839Speter@ref{annotate}. 1138925839Speter 1139025839Speter@table @code 1139125839Speter@item -D @var{date} 1139225839SpeterAnnotate the most recent revision no later than 1139325839Speter@var{date}. See @ref{Common options}. 1139425839Speter 11395102840Speter@item -F 11396102840SpeterForce annotation of binary files. (Without this option, 11397102840Speterbinary files are skipped with a message.) 11398102840Speter 1139925839Speter@item -f 1140025839SpeterUse head revision if tag/date not found. See 1140125839Speter@ref{Common options}. 1140225839Speter 1140325839Speter@item -l 1140425839SpeterLocal; run only in current working directory. @xref{Recursive behavior}. 1140525839Speter 1140625839Speter@item -R 1140725839SpeterOperate recursively (default). @xref{Recursive 1140825839Speterbehavior}. 1140925839Speter 1141025839Speter@item -r @var{tag} 1141125839SpeterAnnotate revision @var{tag}. See @ref{Common options}. 1141225839Speter@end table 1141325839Speter 11414102840Speter@c ------------------------------------------------------------ 1141525839Speter@item checkout [@var{options}] @var{modules}@dots{} 1141625839SpeterGet a copy of the sources. See @ref{checkout}. 1141725839Speter 1141825839Speter@table @code 1141925839Speter@item -A 1142025839SpeterReset any sticky tags/date/options. See @ref{Sticky 1142125839Spetertags} and @ref{Keyword substitution}. 1142225839Speter 1142325839Speter@item -c 1142425839SpeterOutput the module database. See @ref{checkout options}. 1142525839Speter 1142625839Speter@item -D @var{date} 1142725839SpeterCheck out revisions as of @var{date} (is sticky). See 1142825839Speter@ref{Common options}. 1142925839Speter 1143025839Speter@item -d @var{dir} 1143125839SpeterCheck out into @var{dir}. See @ref{checkout options}. 1143225839Speter 1143325839Speter@item -f 1143425839SpeterUse head revision if tag/date not found. See 1143525839Speter@ref{Common options}. 1143625839Speter 1143725839Speter@c Probably want to use rev1/rev2 style like for diff 1143825839Speter@c -r. Here and in on-line help. 1143925839Speter@item -j @var{rev} 1144025839SpeterMerge in changes. See @ref{checkout options}. 1144125839Speter 1144225839Speter@item -k @var{kflag} 1144325839SpeterUse @var{kflag} keyword expansion. See 1144425839Speter@ref{Substitution modes}. 1144525839Speter 1144625839Speter@item -l 1144725839SpeterLocal; run only in current working directory. @xref{Recursive behavior}. 1144825839Speter 1144925839Speter@item -N 1145032785SpeterDon't ``shorten'' module paths if -d specified. See 1145132785Speter@ref{checkout options}. 1145225839Speter 1145325839Speter@item -n 1145425839SpeterDo not run module program (if any). See @ref{checkout options}. 1145525839Speter 1145625839Speter@item -P 1145725839SpeterPrune empty directories. See @ref{Moving directories}. 1145825839Speter 1145925839Speter@item -p 1146025839SpeterCheck out files to standard output (avoids 1146125839Speterstickiness). See @ref{checkout options}. 1146225839Speter 1146325839Speter@item -R 1146425839SpeterOperate recursively (default). @xref{Recursive 1146525839Speterbehavior}. 1146625839Speter 1146725839Speter@item -r @var{tag} 1146825839SpeterCheckout revision @var{tag} (is sticky). See @ref{Common options}. 1146925839Speter 1147025839Speter@item -s 1147125839SpeterLike -c, but include module status. See @ref{checkout options}. 1147225839Speter@end table 1147325839Speter 11474102840Speter@c ------------------------------------------------------------ 1147525839Speter@item commit [@var{options}] [@var{files}@dots{}] 1147625839SpeterCheck changes into the repository. See @ref{commit}. 1147725839Speter 1147825839Speter@table @code 1147925839Speter@item -F @var{file} 1148025839SpeterRead log message from @var{file}. See @ref{commit options}. 1148125839Speter 1148225839Speter@item -f 1148325839Speter@c What is this "disables recursion"? It is from the 1148425839Speter@c on-line help; is it documented in this manual? 1148525839SpeterForce the file to be committed; disables recursion. 1148625839SpeterSee @ref{commit options}. 1148725839Speter 1148825839Speter@item -l 1148925839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1149025839Speter 1149125839Speter@item -m @var{msg} 1149225839SpeterUse @var{msg} as log message. See @ref{commit options}. 1149325839Speter 1149425839Speter@item -n 1149525839SpeterDo not run module program (if any). See @ref{commit options}. 1149625839Speter 1149725839Speter@item -R 1149825839SpeterOperate recursively (default). @xref{Recursive 1149925839Speterbehavior}. 1150025839Speter 1150125839Speter@item -r @var{rev} 1150225839SpeterCommit to @var{rev}. See @ref{commit options}. 1150325839Speter@c FIXME: should be dragging over text from 1150425839Speter@c commit options, especially if it can be cleaned up 1150525839Speter@c and made concise enough. 1150625839Speter@end table 1150725839Speter 11508102840Speter@c ------------------------------------------------------------ 1150925839Speter@item diff [@var{options}] [@var{files}@dots{}] 1151025839SpeterShow differences between revisions. See @ref{diff}. 1151125839SpeterIn addition to the options shown below, accepts a wide 1151225839Spetervariety of options to control output style, for example 1151325839Speter@samp{-c} for context diffs. 1151425839Speter 1151525839Speter@table @code 1151625839Speter@item -D @var{date1} 1151725839SpeterDiff revision for date against working file. See 1151825839Speter@ref{diff options}. 1151925839Speter 1152025839Speter@item -D @var{date2} 1152125839SpeterDiff @var{rev1}/@var{date1} against @var{date2}. See 1152225839Speter@ref{diff options}. 1152325839Speter 1152425839Speter@item -l 1152525839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1152625839Speter 1152725839Speter@item -N 1152825839SpeterInclude diffs for added and removed files. See 1152925839Speter@ref{diff options}. 1153025839Speter 1153125839Speter@item -R 1153225839SpeterOperate recursively (default). @xref{Recursive 1153325839Speterbehavior}. 1153425839Speter 1153525839Speter@item -r @var{rev1} 1153625839SpeterDiff revision for @var{rev1} against working file. See 1153725839Speter@ref{diff options}. 1153825839Speter 1153925839Speter@item -r @var{rev2} 1154044852SpeterDiff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}. 1154125839Speter@end table 1154225839Speter 11543102840Speter@c ------------------------------------------------------------ 1154425839Speter@item edit [@var{options}] [@var{files}@dots{}] 1154525839SpeterGet ready to edit a watched file. See @ref{Editing files}. 1154625839Speter 1154725839Speter@table @code 1154825839Speter@item -a @var{actions} 1154925839SpeterSpecify actions for temporary watch, where 1155025839Speter@var{actions} is @code{edit}, @code{unedit}, 1155125839Speter@code{commit}, @code{all}, or @code{none}. See 1155225839Speter@ref{Editing files}. 1155325839Speter 1155425839Speter@item -l 1155525839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1155625839Speter 1155725839Speter@item -R 1155825839SpeterOperate recursively (default). @xref{Recursive 1155925839Speterbehavior}. 1156025839Speter@end table 1156125839Speter 11562102840Speter@c ------------------------------------------------------------ 1156325839Speter@item editors [@var{options}] [@var{files}@dots{}] 1156425839SpeterSee who is editing a watched file. See @ref{Watch information}. 1156525839Speter 1156625839Speter@table @code 1156725839Speter@item -l 1156825839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1156925839Speter 1157025839Speter@item -R 1157125839SpeterOperate recursively (default). @xref{Recursive 1157225839Speterbehavior}. 1157325839Speter@end table 1157425839Speter 11575102840Speter@c ------------------------------------------------------------ 1157625839Speter@item export [@var{options}] @var{modules}@dots{} 1157781404SpeterExport files from @sc{cvs}. See @ref{export}. 1157825839Speter 1157925839Speter@table @code 1158025839Speter@item -D @var{date} 1158125839SpeterCheck out revisions as of @var{date}. See 1158225839Speter@ref{Common options}. 1158325839Speter 1158425839Speter@item -d @var{dir} 1158525839SpeterCheck out into @var{dir}. See @ref{export options}. 1158625839Speter 1158725839Speter@item -f 1158825839SpeterUse head revision if tag/date not found. See 1158925839Speter@ref{Common options}. 1159025839Speter 1159125839Speter@item -k @var{kflag} 1159225839SpeterUse @var{kflag} keyword expansion. See 1159325839Speter@ref{Substitution modes}. 1159425839Speter 1159525839Speter@item -l 1159625839SpeterLocal; run only in current working directory. @xref{Recursive behavior}. 1159725839Speter 1159825839Speter@item -N 1159932785SpeterDon't ``shorten'' module paths if -d specified. See 1160032785Speter@ref{export options}. 1160125839Speter 1160225839Speter@item -n 1160325839SpeterDo not run module program (if any). See @ref{export options}. 1160425839Speter 1160525839Speter@item -R 1160625839SpeterOperate recursively (default). @xref{Recursive 1160725839Speterbehavior}. 1160825839Speter 1160925839Speter@item -r @var{tag} 1161054427SpeterCheckout revision @var{tag}. See @ref{Common options}. 1161125839Speter@end table 1161225839Speter 11613102840Speter@c ------------------------------------------------------------ 1161425839Speter@item history [@var{options}] [@var{files}@dots{}] 1161525839SpeterShow repository access history. See @ref{history}. 1161625839Speter 1161725839Speter@table @code 1161825839Speter@item -a 1161925839SpeterAll users (default is self). See @ref{history options}. 1162025839Speter 1162125839Speter@item -b @var{str} 1162225839SpeterBack to record with @var{str} in module/file/repos 1162325839Speterfield. See @ref{history options}. 1162425839Speter 1162525839Speter@item -c 1162625839SpeterReport on committed (modified) files. See @ref{history options}. 1162725839Speter 1162825839Speter@item -D @var{date} 1162925839SpeterSince @var{date}. See @ref{history options}. 1163025839Speter 1163125839Speter@item -e 1163225839SpeterReport on all record types. See @ref{history options}. 1163325839Speter 1163425839Speter@item -l 1163525839SpeterLast modified (committed or modified report). See @ref{history options}. 1163625839Speter 1163725839Speter@item -m @var{module} 11638102840SpeterReport on @var{module} (repeatable). See @ref{history options}. 1163925839Speter 1164025839Speter@item -n @var{module} 1164125839SpeterIn @var{module}. See @ref{history options}. 1164225839Speter 1164325839Speter@item -o 1164425839SpeterReport on checked out modules. See @ref{history options}. 1164525839Speter 11646102840Speter@item -p @var{repository} 11647102840SpeterIn @var{repository}. See @ref{history options}. 11648102840Speter 1164925839Speter@item -r @var{rev} 1165025839SpeterSince revision @var{rev}. See @ref{history options}. 1165125839Speter 1165225839Speter@item -T 1165325839Speter@c What the @#$@# is a TAG? Same as a tag? This 1165425839Speter@c wording is also in the online-line help. 1165525839SpeterProduce report on all TAGs. See @ref{history options}. 1165625839Speter 1165725839Speter@item -t @var{tag} 1165825839SpeterSince tag record placed in history file (by anyone). 1165925839SpeterSee @ref{history options}. 1166025839Speter 1166125839Speter@item -u @var{user} 11662102840SpeterFor user @var{user} (repeatable). See @ref{history options}. 1166325839Speter 1166425839Speter@item -w 1166525839SpeterWorking directory must match. See @ref{history options}. 1166625839Speter 1166725839Speter@item -x @var{types} 1166825839SpeterReport on @var{types}, one or more of 11669128266Speter@code{TOEFWUPCGMAR}. See @ref{history options}. 1167025839Speter 1167125839Speter@item -z @var{zone} 11672102840SpeterOutput for time zone @var{zone}. See @ref{history options}. 1167325839Speter@end table 1167425839Speter 11675102840Speter@c ------------------------------------------------------------ 1167625839Speter@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 1167781404SpeterImport files into @sc{cvs}, using vendor branches. See 1167825839Speter@ref{import}. 1167925839Speter 1168025839Speter@table @code 1168125839Speter@item -b @var{bra} 1168225839SpeterImport to vendor branch @var{bra}. See 1168326801Speter@ref{Multiple vendor branches}. 1168425839Speter 1168525839Speter@item -d 1168625839SpeterUse the file's modification time as the time of 1168725839Speterimport. See @ref{import options}. 1168825839Speter 1168925839Speter@item -k @var{kflag} 1169032785SpeterSet default keyword substitution mode. See 1169125839Speter@ref{import options}. 1169225839Speter 1169325839Speter@item -m @var{msg} 1169425839SpeterUse @var{msg} for log message. See 1169525839Speter@ref{import options}. 1169625839Speter 1169725839Speter@item -I @var{ign} 1169825839SpeterMore files to ignore (! to reset). See 1169925839Speter@ref{import options}. 1170025839Speter 1170125839Speter@item -W @var{spec} 1170225839SpeterMore wrappers. See @ref{import options}. 1170325839Speter@end table 1170425839Speter 11705102840Speter@c ------------------------------------------------------------ 1170625839Speter@item init 1170781404SpeterCreate a @sc{cvs} repository if it doesn't exist. See 1170825839Speter@ref{Creating a repository}. 1170925839Speter 11710102840Speter@c ------------------------------------------------------------ 11711102840Speter@item kserver 11712102840SpeterKerberos authenticated server. 11713102840SpeterSee @ref{Kerberos authenticated}. 11714102840Speter 11715102840Speter@c ------------------------------------------------------------ 1171625839Speter@item log [@var{options}] [@var{files}@dots{}] 1171725839SpeterPrint out history information for files. See @ref{log}. 1171825839Speter 1171925839Speter@table @code 1172025839Speter@item -b 1172125839SpeterOnly list revisions on the default branch. See @ref{log options}. 1172225839Speter 1172325839Speter@item -d @var{dates} 1172425839SpeterSpecify dates (@var{d1}<@var{d2} for range, @var{d} for 1172525839Speterlatest before). See @ref{log options}. 1172625839Speter 1172725839Speter@item -h 1172825839SpeterOnly print header. See @ref{log options}. 1172925839Speter 1173025839Speter@item -l 1173125839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1173225839Speter 1173325839Speter@item -N 1173425839SpeterDo not list tags. See @ref{log options}. 1173525839Speter 1173625839Speter@item -R 1173725839SpeterOnly print name of RCS file. See @ref{log options}. 1173825839Speter 1173944852Speter@item -r@var{revs} 1174025839SpeterOnly list revisions @var{revs}. See @ref{log options}. 1174125839Speter 1174225839Speter@item -s @var{states} 1174325839SpeterOnly list revisions with specified states. See @ref{log options}. 1174425839Speter 1174525839Speter@item -t 1174625839SpeterOnly print header and descriptive text. See @ref{log 1174725839Speteroptions}. 1174825839Speter 1174944852Speter@item -w@var{logins} 1175025839SpeterOnly list revisions checked in by specified logins. See @ref{log options}. 1175125839Speter@end table 1175225839Speter 11753102840Speter@c ------------------------------------------------------------ 1175425839Speter@item login 1175525839SpeterPrompt for password for authenticating server. See 1175625839Speter@ref{Password authentication client}. 1175725839Speter 11758102840Speter@c ------------------------------------------------------------ 1175925839Speter@item logout 1176025839SpeterRemove stored password for authenticating server. See 1176125839Speter@ref{Password authentication client}. 1176225839Speter 11763102840Speter@c ------------------------------------------------------------ 11764102840Speter@item pserver 11765102840SpeterPassword authenticated server. 11766102840SpeterSee @ref{Password authentication server}. 11767102840Speter 11768102840Speter@c ------------------------------------------------------------ 11769102840Speter@item rannotate [@var{options}] [@var{modules}@dots{}] 11770102840SpeterShow last revision where each line was modified. See 11771102840Speter@ref{annotate}. 11772102840Speter 11773102840Speter@table @code 11774102840Speter@item -D @var{date} 11775102840SpeterAnnotate the most recent revision no later than 11776102840Speter@var{date}. See @ref{Common options}. 11777102840Speter 11778102840Speter@item -F 11779102840SpeterForce annotation of binary files. (Without this option, 11780102840Speterbinary files are skipped with a message.) 11781102840Speter 11782102840Speter@item -f 11783102840SpeterUse head revision if tag/date not found. See 11784102840Speter@ref{Common options}. 11785102840Speter 11786102840Speter@item -l 11787102840SpeterLocal; run only in current working directory. @xref{Recursive behavior}. 11788102840Speter 11789102840Speter@item -R 11790102840SpeterOperate recursively (default). @xref{Recursive behavior}. 11791102840Speter 11792102840Speter@item -r @var{tag} 11793102840SpeterAnnotate revision @var{tag}. See @ref{Common options}. 11794102840Speter@end table 11795102840Speter 11796102840Speter@c ------------------------------------------------------------ 1179725839Speter@item rdiff [@var{options}] @var{modules}@dots{} 1179825839SpeterShow differences between releases. See @ref{rdiff}. 1179925839Speter 1180025839Speter@table @code 1180125839Speter@item -c 1180225839SpeterContext diff output format (default). See @ref{rdiff options}. 1180325839Speter 1180425839Speter@item -D @var{date} 1180525839SpeterSelect revisions based on @var{date}. See @ref{Common options}. 1180625839Speter 1180725839Speter@item -f 1180825839SpeterUse head revision if tag/date not found. See 1180925839Speter@ref{Common options}. 1181025839Speter 1181125839Speter@item -l 1181225839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1181325839Speter 1181425839Speter@item -R 1181525839SpeterOperate recursively (default). @xref{Recursive 1181625839Speterbehavior}. 1181725839Speter 1181825839Speter@item -r @var{rev} 1181925839SpeterSelect revisions based on @var{rev}. See @ref{Common options}. 1182025839Speter 1182125839Speter@item -s 1182225839SpeterShort patch - one liner per file. See @ref{rdiff options}. 1182325839Speter 1182425839Speter@item -t 1182525839SpeterTop two diffs - last change made to the file. See 1182625839Speter@ref{diff options}. 1182725839Speter 1182825839Speter@item -u 1182925839SpeterUnidiff output format. See @ref{rdiff options}. 1183025839Speter 1183125839Speter@item -V @var{vers} 1183234461SpeterUse RCS Version @var{vers} for keyword expansion (obsolete). See 1183325839Speter@ref{rdiff options}. 1183425839Speter@end table 1183525839Speter 11836102840Speter@c ------------------------------------------------------------ 1183725839Speter@item release [@var{options}] @var{directory} 1183825839SpeterIndicate that a directory is no longer in use. See 1183925839Speter@ref{release}. 1184025839Speter 1184125839Speter@table @code 1184225839Speter@item -d 1184325839SpeterDelete the given directory. See @ref{release options}. 1184425839Speter@end table 1184525839Speter 11846102840Speter@c ------------------------------------------------------------ 1184725839Speter@item remove [@var{options}] [@var{files}@dots{}] 1184825839SpeterRemove an entry from the repository. See @ref{Removing files}. 1184925839Speter 1185025839Speter@table @code 1185125839Speter@item -f 1185225839SpeterDelete the file before removing it. See @ref{Removing files}. 1185325839Speter 1185425839Speter@item -l 1185525839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1185625839Speter 1185725839Speter@item -R 1185825839SpeterOperate recursively (default). @xref{Recursive 1185925839Speterbehavior}. 1186025839Speter@end table 1186125839Speter 11862102840Speter@c ------------------------------------------------------------ 11863102840Speter@item rlog [@var{options}] [@var{files}@dots{}] 11864102840SpeterPrint out history information for modules. See @ref{log}. 11865102840Speter 11866102840Speter@table @code 11867102840Speter@item -b 11868102840SpeterOnly list revisions on the default branch. See @ref{log options}. 11869102840Speter 11870102840Speter@item -d @var{dates} 11871102840SpeterSpecify dates (@var{d1}<@var{d2} for range, @var{d} for 11872102840Speterlatest before). See @ref{log options}. 11873102840Speter 11874102840Speter@item -h 11875102840SpeterOnly print header. See @ref{log options}. 11876102840Speter 11877102840Speter@item -l 11878102840SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 11879102840Speter 11880102840Speter@item -N 11881102840SpeterDo not list tags. See @ref{log options}. 11882102840Speter 11883102840Speter@item -R 11884102840SpeterOnly print name of RCS file. See @ref{log options}. 11885102840Speter 11886102840Speter@item -r@var{revs} 11887102840SpeterOnly list revisions @var{revs}. See @ref{log options}. 11888102840Speter 11889102840Speter@item -s @var{states} 11890102840SpeterOnly list revisions with specified states. See @ref{log options}. 11891102840Speter 11892102840Speter@item -t 11893102840SpeterOnly print header and descriptive text. See @ref{log options}. 11894102840Speter 11895102840Speter@item -w@var{logins} 11896102840SpeterOnly list revisions checked in by specified logins. See @ref{log options}. 11897102840Speter@end table 11898102840Speter 11899102840Speter@c ------------------------------------------------------------ 1190025839Speter@item rtag [@var{options}] @var{tag} @var{modules}@dots{} 1190154427SpeterAdd a symbolic tag to a module. 1190254427SpeterSee @ref{Revisions} and @ref{Branching and merging}. 1190325839Speter 1190425839Speter@table @code 1190525839Speter@item -a 1190625839SpeterClear tag from removed files that would not otherwise 1190754427Speterbe tagged. See @ref{Tagging add/remove}. 1190825839Speter 1190925839Speter@item -b 1191054427SpeterCreate a branch named @var{tag}. See @ref{Branching and merging}. 1191125839Speter 11912102840Speter@item -B 11913130303SpeterUsed in conjunction with -F or -d, enables movement and deletion of 11914102840Speterbranch tags. Use with extreme caution. 11915102840Speter 1191625839Speter@item -D @var{date} 1191754427SpeterTag revisions as of @var{date}. See @ref{Tagging by date/tag}. 1191825839Speter 1191925839Speter@item -d 1192054427SpeterDelete @var{tag}. See @ref{Modifying tags}. 1192125839Speter 1192225839Speter@item -F 1192354427SpeterMove @var{tag} if it already exists. See @ref{Modifying tags}. 1192425839Speter 1192525839Speter@item -f 1192625839SpeterForce a head revision match if tag/date not found. 1192754427SpeterSee @ref{Tagging by date/tag}. 1192825839Speter 1192925839Speter@item -l 1193025839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1193125839Speter 1193225839Speter@item -n 1193354427SpeterNo execution of tag program. See @ref{Common options}. 1193425839Speter 1193525839Speter@item -R 1193625839SpeterOperate recursively (default). @xref{Recursive 1193725839Speterbehavior}. 1193825839Speter 1193954427Speter@item -r @var{rev} 1194054427SpeterTag existing tag @var{rev}. See @ref{Tagging by date/tag}. 1194125839Speter@end table 1194225839Speter 11943102840Speter@c ------------------------------------------------------------ 11944102840Speter@item server 11945102840SpeterRsh server. See @ref{Connecting via rsh}. 11946102840Speter 11947102840Speter@c ------------------------------------------------------------ 1194825839Speter@item status [@var{options}] @var{files}@dots{} 1194925839SpeterDisplay status information in a working directory. See 1195025839Speter@ref{File status}. 1195125839Speter 1195225839Speter@table @code 1195325839Speter@item -l 1195425839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1195525839Speter 1195625839Speter@item -R 1195725839SpeterOperate recursively (default). @xref{Recursive 1195825839Speterbehavior}. 1195925839Speter 1196025839Speter@item -v 1196125839SpeterInclude tag information for file. See @ref{Tags}. 1196225839Speter@end table 1196325839Speter 11964102840Speter@c ------------------------------------------------------------ 1196525839Speter@item tag [@var{options}] @var{tag} [@var{files}@dots{}] 1196625839SpeterAdd a symbolic tag to checked out version of files. 1196754427SpeterSee @ref{Revisions} and @ref{Branching and merging}. 1196825839Speter 1196925839Speter@table @code 1197025839Speter@item -b 1197154427SpeterCreate a branch named @var{tag}. See @ref{Branching and merging}. 1197225839Speter 1197354427Speter@item -c 1197454427SpeterCheck that working files are unmodified. See 1197554427Speter@ref{Tagging the working directory}. 1197654427Speter 1197725839Speter@item -D @var{date} 1197854427SpeterTag revisions as of @var{date}. See @ref{Tagging by date/tag}. 1197925839Speter 1198025839Speter@item -d 1198154427SpeterDelete @var{tag}. See @ref{Modifying tags}. 1198225839Speter 1198325839Speter@item -F 1198454427SpeterMove @var{tag} if it already exists. See @ref{Modifying tags}. 1198525839Speter 1198625839Speter@item -f 1198725839SpeterForce a head revision match if tag/date not found. 1198854427SpeterSee @ref{Tagging by date/tag}. 1198925839Speter 1199025839Speter@item -l 1199125839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1199225839Speter 1199325839Speter@item -R 1199425839SpeterOperate recursively (default). @xref{Recursive 1199525839Speterbehavior}. 1199625839Speter 1199754427Speter@item -r @var{rev} 1199854427SpeterTag existing tag @var{rev}. See @ref{Tagging by date/tag}. 1199925839Speter@end table 1200025839Speter 12001102840Speter@c ------------------------------------------------------------ 1200225839Speter@item unedit [@var{options}] [@var{files}@dots{}] 1200325839SpeterUndo an edit command. See @ref{Editing files}. 1200425839Speter 1200525839Speter@table @code 1200625839Speter@item -l 1200725839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1200825839Speter 1200925839Speter@item -R 12010102840SpeterOperate recursively (default). @xref{Recursive behavior}. 1201125839Speter@end table 1201225839Speter 12013102840Speter@c ------------------------------------------------------------ 1201425839Speter@item update [@var{options}] [@var{files}@dots{}] 1201525839SpeterBring work tree in sync with repository. See 1201625839Speter@ref{update}. 1201725839Speter 1201825839Speter@table @code 1201925839Speter@item -A 1202025839SpeterReset any sticky tags/date/options. See @ref{Sticky 1202125839Spetertags} and @ref{Keyword substitution}. 1202225839Speter 1202366525Speter@item -C 1202466525SpeterOverwrite locally modified files with clean copies from 1202566525Speterthe repository (the modified file is saved in 1202666525Speter@file{.#@var{file}.@var{revision}}, however). 1202766525Speter 1202825839Speter@item -D @var{date} 1202925839SpeterCheck out revisions as of @var{date} (is sticky). See 1203025839Speter@ref{Common options}. 1203125839Speter 1203225839Speter@item -d 1203325839SpeterCreate directories. See @ref{update options}. 1203425839Speter 1203525839Speter@item -f 1203625839SpeterUse head revision if tag/date not found. See 1203725839Speter@ref{Common options}. 1203825839Speter 1203925839Speter@item -I @var{ign} 1204025839SpeterMore files to ignore (! to reset). See 1204125839Speter@ref{import options}. 1204225839Speter 1204325839Speter@c Probably want to use rev1/rev2 style like for diff 1204425839Speter@c -r. Here and in on-line help. 1204525839Speter@item -j @var{rev} 1204625839SpeterMerge in changes. See @ref{update options}. 1204725839Speter 1204825839Speter@item -k @var{kflag} 1204925839SpeterUse @var{kflag} keyword expansion. See 1205025839Speter@ref{Substitution modes}. 1205125839Speter 1205225839Speter@item -l 1205325839SpeterLocal; run only in current working directory. @xref{Recursive behavior}. 1205425839Speter 1205525839Speter@item -P 1205625839SpeterPrune empty directories. See @ref{Moving directories}. 1205725839Speter 1205825839Speter@item -p 1205925839SpeterCheck out files to standard output (avoids 1206025839Speterstickiness). See @ref{update options}. 1206125839Speter 1206225839Speter@item -R 1206325839SpeterOperate recursively (default). @xref{Recursive 1206425839Speterbehavior}. 1206525839Speter 1206625839Speter@item -r @var{tag} 1206725839SpeterCheckout revision @var{tag} (is sticky). See @ref{Common options}. 1206825839Speter 1206925839Speter@item -W @var{spec} 1207025839SpeterMore wrappers. See @ref{import options}. 1207125839Speter@end table 1207225839Speter 12073102840Speter@c ------------------------------------------------------------ 1207466525Speter@item version 1207581404Speter@cindex version (subcommand) 1207666525Speter 1207766525SpeterDisplay the version of @sc{cvs} being used. If the repository 1207866525Speteris remote, display both the client and server versions. 1207966525Speter 12080102840Speter@c ------------------------------------------------------------ 1208125839Speter@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 1208225839Speter 1208325839Speteron/off: turn on/off read-only checkouts of files. See 1208425839Speter@ref{Setting a watch}. 1208525839Speter 1208625839Speteradd/remove: add or remove notification on actions. See 1208725839Speter@ref{Getting Notified}. 1208825839Speter 1208925839Speter@table @code 1209025839Speter@item -a @var{actions} 1209125839SpeterSpecify actions for temporary watch, where 1209225839Speter@var{actions} is @code{edit}, @code{unedit}, 1209325839Speter@code{commit}, @code{all}, or @code{none}. See 1209425839Speter@ref{Editing files}. 1209525839Speter 1209625839Speter@item -l 1209725839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1209825839Speter 1209925839Speter@item -R 1210025839SpeterOperate recursively (default). @xref{Recursive 1210125839Speterbehavior}. 1210225839Speter@end table 1210325839Speter 12104102840Speter@c ------------------------------------------------------------ 1210525839Speter@item watchers [@var{options}] [@var{files}@dots{}] 1210625839SpeterSee who is watching a file. See @ref{Watch information}. 1210725839Speter 1210825839Speter@table @code 1210925839Speter@item -l 1211025839SpeterLocal; run only in current working directory. See @ref{Recursive behavior}. 1211125839Speter 1211225839Speter@item -R 1211325839SpeterOperate recursively (default). @xref{Recursive 1211425839Speterbehavior}. 1211525839Speter@end table 1211625839Speter 1211725839Speter@end table 1211825839Speter 1211917721Speter@c --------------------------------------------------------------------- 1212017721Speter@node Administrative files 1212125839Speter@appendix Reference manual for Administrative files 1212217721Speter@cindex Administrative files (reference) 1212317721Speter@cindex Files, reference manual 1212417721Speter@cindex Reference manual (files) 1212517721Speter@cindex CVSROOT (file) 1212617721Speter 1212726065Speter@c FIXME? Somewhere there needs to be a more "how-to" 1212826065Speter@c guide to writing these. I think the triggers 1212926065Speter@c (commitinfo, loginfo, taginfo, &c) are perhaps a 1213026065Speter@c different case than files like modules. One 1213126065Speter@c particular issue that people sometimes are 1213226065Speter@c (unnecessarily?) worried about is performance, and 1213326065Speter@c the impact of writing in perl or sh or ____. 1213417721SpeterInside the repository, in the directory 1213517721Speter@file{$CVSROOT/CVSROOT}, there are a number of 1213617721Spetersupportive files for @sc{cvs}. You can use @sc{cvs} in a limited 1213717721Speterfashion without any of them, but if they are set up 1213825839Speterproperly they can help make life easier. For a 1213932785Speterdiscussion of how to edit them, see @ref{Intro 1214025839Speteradministrative files}. 1214117721Speter 1214217721SpeterThe most important of these files is the @file{modules} 1214317721Speterfile, which defines the modules inside the repository. 1214417721Speter 1214517721Speter@menu 1214617721Speter* modules:: Defining modules 1214754427Speter* Wrappers:: Specify binary-ness based on file name 12148175261Sobrien* Trigger Scripts:: Some notes on the commit support files and 12149175261Sobrien taginfo, referenced below. 12150102840Speter* commit files:: The commit support files (commitinfo, 12151102840Speter verifymsg, editinfo, loginfo) 12152128266Speter* taginfo:: Verifying/Logging tags 1215317721Speter* rcsinfo:: Templates for the log messages 1215417721Speter* cvsignore:: Ignoring files via cvsignore 1215554427Speter* checkoutlist:: Adding your own administrative files 1215617721Speter* history file:: History information 1215717721Speter* Variables:: Various variables are expanded 1215832785Speter* config:: Miscellaneous CVS configuration 1215917721Speter@end menu 1216017721Speter 1216117721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1216217721Speter@node modules 1216317721Speter@appendixsec The modules file 1216417721Speter@cindex Modules (admin file) 1216517721Speter@cindex Defining modules (reference manual) 1216617721Speter 1216717721SpeterThe @file{modules} file records your definitions of 1216817721Speternames for collections of source code. @sc{cvs} will 1216917721Speteruse these definitions if you use @sc{cvs} to update the 1217017721Spetermodules file (use normal commands like @code{add}, 1217117721Speter@code{commit}, etc). 1217217721Speter 1217317721SpeterThe @file{modules} file may contain blank lines and 1217417721Spetercomments (lines beginning with @samp{#}) as well as 1217517721Spetermodule definitions. Long lines can be continued on the 1217617721Speternext line by specifying a backslash (@samp{\}) as the 1217717721Speterlast character on the line. 1217817721Speter 1217932785SpeterThere are three basic types of modules: alias modules, 1218032785Speterregular modules, and ampersand modules. The difference 1218132785Speterbetween them is the way that they map files in the 1218232785Speterrepository to files in the working directory. In all 1218332785Speterof the following examples, the top-level repository 1218432785Spetercontains a directory called @file{first-dir}, which 1218532785Spetercontains two files, @file{file1} and @file{file2}, and a 1218632785Speterdirectory @file{sdir}. @file{first-dir/sdir} contains 1218732785Spetera file @file{sfile}. 1218817721Speter 1218932785Speter@c FIXME: should test all the examples in this section. 1219032785Speter 1219132785Speter@menu 1219232785Speter* Alias modules:: The simplest kind of module 1219332785Speter* Regular modules:: 1219432785Speter* Ampersand modules:: 1219532896Speter* Excluding directories:: Excluding directories from a module 1219632785Speter* Module options:: Regular and ampersand modules can take options 1219766525Speter* Module program options:: How the modules ``program options'' programs 1219866525Speter are run. 1219932785Speter@end menu 1220032785Speter 1220132785Speter@node Alias modules 1220232785Speter@appendixsubsec Alias modules 1220332785Speter@cindex Alias modules 1220432785Speter@cindex -a, in modules file 1220532785Speter 1220632785SpeterAlias modules are the simplest kind of module: 1220732785Speter 1220817721Speter@table @code 1220917721Speter@item @var{mname} -a @var{aliases}@dots{} 1221017721SpeterThis represents the simplest way of defining a module 1221117721Speter@var{mname}. The @samp{-a} flags the definition as a 1221217721Spetersimple alias: @sc{cvs} will treat any use of @var{mname} (as 1221317721Spetera command argument) as if the list of names 1221417721Speter@var{aliases} had been specified instead. 1221517721Speter@var{aliases} may contain either other module names or 1221617721Speterpaths. When you use paths in aliases, @code{checkout} 1221717721Spetercreates all intermediate directories in the working 1221817721Speterdirectory, just as if the path had been specified 1221917721Speterexplicitly in the @sc{cvs} arguments. 1222032785Speter@end table 1222117721Speter 1222232785SpeterFor example, if the modules file contains: 1222332785Speter 1222432785Speter@example 1222532785Speteramodule -a first-dir 1222632785Speter@end example 1222732785Speter 1222832785Speter@noindent 1222932785Speterthen the following two commands are equivalent: 1223032785Speter 1223132785Speter@example 1223232785Speter$ cvs co amodule 1223332785Speter$ cvs co first-dir 1223432785Speter@end example 1223532785Speter 1223632785Speter@noindent 1223732785Speterand they each would provide output such as: 1223832785Speter 1223932785Speter@example 1224032785Spetercvs checkout: Updating first-dir 1224132785SpeterU first-dir/file1 1224232785SpeterU first-dir/file2 1224332785Spetercvs checkout: Updating first-dir/sdir 1224432785SpeterU first-dir/sdir/sfile 1224532785Speter@end example 1224632785Speter 1224732785Speter@node Regular modules 1224832785Speter@appendixsubsec Regular modules 1224932785Speter@cindex Regular modules 1225032785Speter 1225132785Speter@table @code 1225232785Speter@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 1225317721SpeterIn the simplest case, this form of module definition 1225417721Speterreduces to @samp{@var{mname} @var{dir}}. This defines 1225517721Speterall the files in directory @var{dir} as module mname. 1225617721Speter@var{dir} is a relative path (from @code{$CVSROOT}) to a 1225717721Speterdirectory of source in the source repository. In this 1225817721Spetercase, on checkout, a single directory called 1225917721Speter@var{mname} is created as a working directory; no 1226017721Speterintermediate directory levels are used by default, even 1226117721Speterif @var{dir} was a path involving several directory 1226217721Speterlevels. 1226332785Speter@end table 1226417721Speter 1226532785SpeterFor example, if a module is defined by: 1226632785Speter 1226732785Speter@example 1226832785Speterregmodule first-dir 1226932785Speter@end example 1227032785Speter 1227132785Speter@noindent 1227232785Speterthen regmodule will contain the files from first-dir: 1227332785Speter 1227432785Speter@example 1227532785Speter$ cvs co regmodule 1227632785Spetercvs checkout: Updating regmodule 1227732785SpeterU regmodule/file1 1227832785SpeterU regmodule/file2 1227932785Spetercvs checkout: Updating regmodule/sdir 1228032785SpeterU regmodule/sdir/sfile 1228132785Speter$ 1228232785Speter@end example 1228332785Speter 1228417721SpeterBy explicitly specifying files in the module definition 1228517721Speterafter @var{dir}, you can select particular files from 1228632785Speterdirectory @var{dir}. Here is 1228732785Speteran example: 1228817721Speter 1228917721Speter@example 1229032785Speterregfiles first-dir/sdir sfile 1229117721Speter@end example 1229217721Speter 1229317721Speter@noindent 1229432785SpeterWith this definition, getting the regfiles module 1229532785Speterwill create a single working directory 1229632785Speter@file{regfiles} containing the file listed, which 1229732785Spetercomes from a directory deeper 1229832785Speterin the @sc{cvs} source repository: 1229917721Speter 1230032785Speter@example 1230132785Speter$ cvs co regfiles 1230232785SpeterU regfiles/sfile 1230332785Speter$ 1230432785Speter@end example 1230532785Speter 1230632785Speter@node Ampersand modules 1230732785Speter@appendixsubsec Ampersand modules 1230832785Speter@cindex Ampersand modules 1230932785Speter@cindex &, in modules file 1231032785Speter 1231117721SpeterA module definition can refer to other modules by 1231217721Speterincluding @samp{&@var{module}} in its definition. 1231332785Speter@example 1231432785Speter@var{mname} [ options ] @var{&module}@dots{} 1231532785Speter@end example 1231632785Speter 1231732785SpeterThen getting the module creates a subdirectory for each such 1231825839Spetermodule, in the directory containing the module. For 1231925839Speterexample, if modules contains 1232017721Speter 1232125839Speter@example 1232232785Speterampermod &first-dir 1232325839Speter@end example 1232425839Speter 12325102840Speter@noindent 1232632785Speterthen a checkout will create an @code{ampermod} directory 1232732785Speterwhich contains a directory called @code{first-dir}, 1232825839Speterwhich in turns contains all the directories and files 1232932785Speterwhich live there. For example, the command 1233032785Speter 1233132785Speter@example 1233232785Speter$ cvs co ampermod 1233332785Speter@end example 1233432785Speter 1233532785Speter@noindent 1233632785Speterwill create the following files: 1233732785Speter 1233832785Speter@example 1233932785Speterampermod/first-dir/file1 1234032785Speterampermod/first-dir/file2 1234132785Speterampermod/first-dir/sdir/sfile 1234232785Speter@end example 1234332785Speter 1234432785SpeterThere is one quirk/bug: the messages that @sc{cvs} 1234532785Speterprints omit the @file{ampermod}, and thus do not 1234632785Spetercorrectly display the location to which it is checking 1234732785Speterout the files: 1234832785Speter 1234932785Speter@example 1235032785Speter$ cvs co ampermod 1235132785Spetercvs checkout: Updating first-dir 1235232785SpeterU first-dir/file1 1235332785SpeterU first-dir/file2 1235432785Spetercvs checkout: Updating first-dir/sdir 1235532785SpeterU first-dir/sdir/sfile 1235632785Speter$ 1235732785Speter@end example 1235832785Speter 1235932785SpeterDo not rely on this buggy behavior; it may get fixed in 1236032785Spetera future release of @sc{cvs}. 1236132785Speter 1236225839Speter@c FIXCVS: What happens if regular and & modules are 1236325839Speter@c combined, as in "ampermodule first-dir &second-dir"? 1236425839Speter@c When I tried it, it seemed to just ignore the 1236525839Speter@c "first-dir". I think perhaps it should be an error 1236625839Speter@c (but this needs further investigation). 1236725839Speter@c In addition to discussing what each one does, we 1236825839Speter@c should put in a few words about why you would use one or 1236925839Speter@c the other in various situations. 1237025839Speter 1237132896Speter@node Excluding directories 1237232896Speter@appendixsubsec Excluding directories 1237366525Speter@cindex Excluding directories, in modules file 1237432896Speter@cindex !, in modules file 1237532896Speter 1237632896SpeterAn alias module may exclude particular directories from 1237732896Speterother modules by using an exclamation mark (@samp{!}) 1237832896Speterbefore the name of each directory to be excluded. 1237932896Speter 1238032896SpeterFor example, if the modules file contains: 1238132896Speter 1238232896Speter@example 1238344852Speterexmodule -a !first-dir/sdir first-dir 1238432896Speter@end example 1238532896Speter 12386102840Speter@noindent 1238732896Speterthen checking out the module @samp{exmodule} will check 1238832896Speterout everything in @samp{first-dir} except any files in 1238932896Speterthe subdirectory @samp{first-dir/sdir}. 1239044852Speter@c Note that the "!first-dir/sdir" sometimes must be listed 1239144852Speter@c before "first-dir". That seems like a probable bug, in which 1239244852Speter@c case perhaps it should be fixed (to allow either 1239344852Speter@c order) rather than documented. See modules4 in testsuite. 1239432896Speter 1239532785Speter@node Module options 1239632785Speter@appendixsubsec Module options 1239766525Speter@cindex Options, in modules file 1239832785Speter 1239932785SpeterEither regular modules or ampersand modules can contain 1240032785Speteroptions, which supply additional information concerning 1240132785Speterthe module. 1240232785Speter 1240317721Speter@table @code 1240432785Speter@cindex -d, in modules file 1240517721Speter@item -d @var{name} 1240617721SpeterName the working directory something other than the 1240717721Spetermodule name. 1240832785Speter@c FIXME: Needs a bunch of examples, analogous to the 1240932785Speter@c examples for alias, regular, and ampersand modules 1241032785Speter@c which show where the files go without -d. 1241117721Speter 1241217721Speter@cindex Export program 1241332785Speter@cindex -e, in modules file 1241417721Speter@item -e @var{prog} 1241517721SpeterSpecify a program @var{prog} to run whenever files in a 1241617721Spetermodule are exported. @var{prog} runs with a single 1241717721Speterargument, the module name. 1241825839Speter@c FIXME: Is it run on server? client? 1241917721Speter 1242017721Speter@cindex Checkout program 1242132785Speter@cindex -o, in modules file 1242217721Speter@item -o @var{prog} 1242317721SpeterSpecify a program @var{prog} to run whenever files in a 1242417721Spetermodule are checked out. @var{prog} runs with a single 12425128266Speterargument, the module name. See @ref{Module program options} for 12426128266Speterinformation on how @var{prog} is called. 1242725839Speter@c FIXME: Is it run on server? client? 1242817721Speter 1242917721Speter@cindex Status of a module 1243017721Speter@cindex Module status 1243132785Speter@cindex -s, in modules file 1243217721Speter@item -s @var{status} 1243317721SpeterAssign a status to the module. When the module file is 1243417721Speterprinted with @samp{cvs checkout -s} the modules are 1243517721Spetersorted according to primarily module status, and 1243617721Spetersecondarily according to the module name. This option 1243717721Speterhas no other meaning. You can use this option for 1243817721Speterseveral things besides status: for instance, list the 1243917721Speterperson that is responsible for this module. 1244017721Speter 1244117721Speter@cindex Tag program 1244232785Speter@cindex -t, in modules file 1244317721Speter@item -t @var{prog} 1244417721SpeterSpecify a program @var{prog} to run whenever files in a 1244517721Spetermodule are tagged with @code{rtag}. @var{prog} runs 1244617721Speterwith two arguments: the module name and the symbolic 1244732785Spetertag specified to @code{rtag}. It is not run 1244832785Speterwhen @code{tag} is executed. Generally you will find 12449128266Speterthat the @file{taginfo} file is a better solution (@pxref{taginfo}). 1245025839Speter@c FIXME: Is it run on server? client? 1245132785Speter@c Problems with -t include: 1245232785Speter@c * It is run after the tag not before 1245332785Speter@c * It doesn't get passed all the information that 1245432785Speter@c taginfo does ("mov", &c). 1245532785Speter@c * It only is run for rtag, not tag. 1245617721Speter@end table 1245717721Speter 1245866525SpeterYou should also see @pxref{Module program options} about how the 1245966525Speter``program options'' programs are run. 1246066525Speter 1246117721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1246266525Speter 1246366525Speter@node Module program options 1246466525Speter@appendixsubsec How the modules file ``program options'' programs are run 1246566525Speter@cindex Modules file program options 1246666525Speter@cindex -t, in modules file 1246766525Speter@cindex -o, in modules file 1246866525Speter@cindex -e, in modules file 1246966525Speter 1247066525Speter@noindent 1247166525SpeterFor checkout, rtag, and export, the program is server-based, and as such the 1247266525Speterfollowing applies:- 1247366525Speter 1247466525SpeterIf using remote access methods (pserver, ext, etc.), 1247581404Speter@sc{cvs} will execute this program on the server from a temporary 1247666525Speterdirectory. The path is searched for this program. 1247766525Speter 12478177391SobrienIf using ``local access'' (on a local or remote NFS file system, i.e., 1247966525Speterrepository set just to a path), 1248066525Speterthe program will be executed from the newly checked-out tree, if 1248166525Speterfound there, or alternatively searched for in the path if not. 1248266525Speter 1248366525SpeterThe programs are all run after the operation has effectively 1248466525Spetercompleted. 1248566525Speter 1248666525Speter 1248766525Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1248817721Speter@node Wrappers 1248917721Speter@appendixsec The cvswrappers file 1249017721Speter@cindex cvswrappers (admin file) 1249117721Speter@cindex CVSWRAPPERS, environment variable 1249217721Speter@cindex Wrappers 1249317721Speter 1249425839Speter@c FIXME: need some better way of separating this out 12495128266Speter@c by functionality. -m is 12496128266Speter@c one feature, and -k is a another. And this discussion 1249725839Speter@c should be better motivated (e.g. start with the 1249825839Speter@c problems, then explain how the feature solves it). 1249925839Speter 1250054427SpeterWrappers refers to a @sc{cvs} feature which lets you 1250154427Spetercontrol certain settings based on the name of the file 1250254427Speterwhich is being operated on. The settings are @samp{-k} 1250354427Speterfor binary files, and @samp{-m} for nonmergeable text 1250454427Speterfiles. 1250554427Speter 1250654427SpeterThe @samp{-m} option 1250754427Speterspecifies the merge methodology that should be used when 1250844852Spetera non-binary file is updated. @code{MERGE} means the usual 1250932785Speter@sc{cvs} behavior: try to merge the files. @code{COPY} 1251032785Spetermeans that @code{cvs update} will refuse to merge 1251132785Speterfiles, as it also does for files specified as binary 1251244852Speterwith @samp{-kb} (but if the file is specified as 1251344852Speterbinary, there is no need to specify @samp{-m 'COPY'}). 1251481404Speter@sc{cvs} will provide the user with the 1251532785Spetertwo versions of the files, and require the user using 1251617721Spetermechanisms outside @sc{cvs}, to insert any necessary 12517128266Speterchanges. 12518128266Speter 12519177391Sobrien@strong{WARNING: Do not use @code{COPY} with 12520128266Speter@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 1252132785Spetercopy one version of your file over the other, wiping 12522128266Speterout the previous contents.} 1252332785Speter@c Ordinarily we don't document the behavior of old 1252432785Speter@c versions. But this one is so dangerous, I think we 1252532785Speter@c must. I almost renamed it to -m 'NOMERGE' so we 1252632785Speter@c could say "never use -m 'COPY'". 1252717721SpeterThe @samp{-m} wrapper option only affects behavior when 1252817721Spetermerging is done on update; it does not affect how files 1252932785Speterare stored. See @ref{Binary files}, for more on 1253017721Speterbinary files. 1253117721Speter 1253217721SpeterThe basic format of the file @file{cvswrappers} is: 1253317721Speter 1253425839Speter@c FIXME: @example is all wrong for this. Use @deffn or 1253525839Speter@c something more sensible. 1253617721Speter@example 1253717721Speterwildcard [option value][option value]... 1253817721Speter 1253917721Speterwhere option is one of 1254017721Speter-m update methodology value: MERGE or COPY 1254125839Speter-k keyword expansion value: expansion mode 1254217721Speter 1254317721Speterand value is a single-quote delimited value. 1254417721Speter@end example 1254517721Speter 1254654427Speter@ignore 1254717721Speter@example 1254817721Speter*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' 1254917721Speter*.c -t 'indent %s %s' 1255017721Speter@end example 1255132785Speter@c When does the filter need to be an absolute pathname 1255232785Speter@c and when will something like the above work? I 1255332785Speter@c suspect it relates to the PATH of the server (which 1255432785Speter@c in turn depends on all kinds of stuff, e.g. inetd 1255532785Speter@c for pserver). I'm not sure whether/where to discuss 1255632785Speter@c this. 1255732785Speter@c FIXME: What do the %s's stand for? 1255817721Speter 1255917721Speter@noindent 1256017721SpeterThe above example of a @file{cvswrappers} file 1256117721Speterstates that all files/directories that end with a @code{.nib} 1256217721Spetershould be filtered with the @file{wrap} program before 1256317721Speterchecking the file into the repository. The file should 1256417721Speterbe filtered though the @file{unwrap} program when the 1256517721Speterfile is checked out of the repository. The 1256617721Speter@file{cvswrappers} file also states that a @code{COPY} 1256717721Spetermethodology should be used when updating the files in 1256832785Speterthe repository (that is, no merging should be performed). 1256917721Speter 1257025839Speter@c What pitfalls arise when using indent this way? Is 1257125839Speter@c it a winning thing to do? Would be nice to at least 1257225839Speter@c hint at those issues; we want our examples to tell 1257325839Speter@c how to solve problems, not just to say that cvs can 1257425839Speter@c do certain things. 1257517721SpeterThe last example line says that all files that end with 1257632785Speter@code{.c} should be filtered with @file{indent} 1257717721Speterbefore being checked into the repository. Unlike the previous 1257832785Speterexample, no filtering of the @code{.c} file is done when 1257917721Speterit is checked out of the repository. 1258017721Speter@noindent 1258117721SpeterThe @code{-t} filter is called with two arguments, 1258217721Speterthe first is the name of the file/directory to filter 1258317721Speterand the second is the pathname to where the resulting 1258417721Speterfiltered file should be placed. 1258517721Speter 1258617721Speter@noindent 1258717721SpeterThe @code{-f} filter is called with one argument, 1258817721Speterwhich is the name of the file to filter from. The end 1258917721Speterresult of this filter will be a file in the users directory 1259017721Speterthat they can work on as they normally would. 1259117721Speter 1259225839SpeterNote that the @samp{-t}/@samp{-f} features do not 1259381404Speterconveniently handle one portion of @sc{cvs}'s operation: 1259481404Speterdetermining when files are modified. @sc{cvs} will still 1259525839Speterwant a file (or directory) to exist, and it will use 1259625839Speterits modification time to determine whether a file is 1259781404Spetermodified. If @sc{cvs} erroneously thinks a file is 1259825839Speterunmodified (for example, a directory is unchanged but 1259925839Speterone of the files within it is changed), you can force 1260025839Speterit to check in the file anyway by specifying the 1260125839Speter@samp{-f} option to @code{cvs commit} (@pxref{commit 1260225839Speteroptions}). 1260325839Speter@c This is, of course, a serious design flaw in -t/-f. 1260425839Speter@c Probably the whole functionality needs to be 1260525839Speter@c redesigned (starting from requirements) to fix this. 1260654427Speter@end ignore 1260725839Speter 1260854427Speter@c FIXME: We don't document -W or point to where it is 1260954427Speter@c documented. Or .cvswrappers. 1261054427SpeterFor example, the following command imports a 1261125839Speterdirectory, treating files whose name ends in 1261225839Speter@samp{.exe} as binary: 1261325839Speter 1261425839Speter@example 1261525839Spetercvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 1261625839Speter@end example 1261725839Speter 1261825839Speter@c Another good example, would be storing files 1261925839Speter@c (e.g. binary files) compressed in the repository. 1262025839Speter@c :::::::::::::::::: 1262125839Speter@c cvswrappers 1262225839Speter@c :::::::::::::::::: 1262325839Speter@c *.t12 -m 'COPY' 1262425839Speter@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 1262544852Speter@c 1262625839Speter@c :::::::::::::::::: 1262725839Speter@c gunzipcp 1262825839Speter@c :::::::::::::::::: 1262925839Speter@c : 1263025839Speter@c [ -f $1 ] || exit 1 1263125839Speter@c zcat $1 > /tmp/.#$1.$$ 1263225839Speter@c mv /tmp/.#$1.$$ $1 1263325839Speter@c 1263425839Speter@c :::::::::::::::::: 1263525839Speter@c gzipcp 1263625839Speter@c :::::::::::::::::: 1263725839Speter@c : 1263825839Speter@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 1263925839Speter@c if [ ! -d $DIRNAME ] ; then 1264025839Speter@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 1264125839Speter@c fi 1264225839Speter@c gzip -c $DIRNAME > $2 1264325839Speter@c One catch--"cvs diff" will not invoke the wrappers 1264425839Speter@c (probably a CVS bug, although I haven't thought it out). 1264525839Speter 12646175261Sobrien@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12647175261Sobrien@node Trigger Scripts 12648175261Sobrien@appendixsec The Trigger Scripts 12649175261Sobrien@cindex Info files 12650175261Sobrien@cindex Trigger scripts 1265117721Speter 12652175261SobrienSeveral of the administrative files support triggers, or the launching external 12653175261Sobrienscripts or programs at specific times before or after particular events. The 12654175261Sobrienindividual files are discussed in the later sections, @ref{commit files} and 12655175261Sobrien@ref{taginfo}, but some of the common elements are discussed here. 1265617721Speter 12657175261SobrienAll the trigger scripts are launched in a copy of the user sandbox being 12658175261Sobriencommitted, on the server, in client-server mode. In local mode, the scripts 12659175261Sobrienare actually launched directly from the user sandbox directory being committed. 12660175261SobrienFor most intents and purposes, the same scripts can be run in both locations 12661175261Sobrienwithout alteration. 1266217721Speter 1266317721Speter@menu 12664175261Sobrien* syntax:: The common syntax 12665175261Sobrien* Trigger Script Security:: Trigger script security 1266617721Speter@end menu 1266717721Speter 1266817721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266917721Speter@node syntax 1267017721Speter@appendixsubsec The common syntax 1267117721Speter@cindex Info files (syntax) 1267217721Speter@cindex Syntax of info files 1267317721Speter@cindex Common syntax of info files 1267417721Speter 1267525839Speter@c FIXME: having this so totally separate from the 1267625839Speter@c Variables node is rather bogus. 1267717721Speter 1267825839SpeterThe administrative files such as @file{commitinfo}, 1267925839Speter@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 1268025839Speterall have a common format. The purpose of the files are 1268125839Speterdescribed later on. The common syntax is described 1268225839Speterhere. 1268325839Speter 1268466525Speter@cindex Regular expression syntax 1268517721SpeterEach line contains the following: 1268617721Speter@itemize @bullet 1268717721Speter@item 1268825839Speter@c Say anything about DEFAULT and ALL? Right now we 1268925839Speter@c leave that to the description of each file (and in fact 1269025839Speter@c the practice is inconsistent which is really annoying). 1269125839SpeterA regular expression. This is a basic regular 1269225839Speterexpression in the syntax used by GNU emacs. 1269325839Speter@c FIXME: What we probably should be saying is "POSIX Basic 1269425839Speter@c Regular Expression with the following extensions (`\(' 1269525839Speter@c `\|' '+' etc)" 1269625839Speter@c rather than define it with reference to emacs. 1269725839Speter@c The reference to emacs is not strictly speaking 1269825839Speter@c true, as we don't support \=, \s, or \S. Also it isn't 1269925839Speter@c clear we should document and/or promise to continue to 1270025839Speter@c support all the obscure emacs extensions like \<. 1270125839Speter@c Also need to better cite (or include) full 1270225839Speter@c documentation for the syntax. 1270332785Speter@c Also see comment in configure.in about what happens to the 1270432785Speter@c syntax if we pick up a system-supplied regexp matcher. 1270517721Speter 1270617721Speter@item 1270717721SpeterA whitespace separator---one or more spaces and/or tabs. 1270817721Speter 1270917721Speter@item 1271017721SpeterA file name or command-line template. 1271117721Speter@end itemize 1271217721Speter 1271317721Speter@noindent 1271417721SpeterBlank lines are ignored. Lines that start with the 1271517721Spetercharacter @samp{#} are treated as comments. Long lines 1271617721Speterunfortunately can @emph{not} be broken in two parts in 1271717721Speterany way. 1271817721Speter 1271917721SpeterThe first regular expression that matches the current 1272017721Speterdirectory name in the repository is used. The rest of the line 1272117721Speteris used as a file name or command-line as appropriate. 1272217721Speter 1272325839Speter@c FIXME: need an example. In particular, show what 1272425839Speter@c the regular expression is matched against (one 1272525839Speter@c ordinarily clueful person got confused about whether it 1272625839Speter@c includes the filename--"directory name" above should be 1272725839Speter@c unambiguous but there is nothing like an example to 1272825839Speter@c confirm people's understanding of this sort of thing). 1272925839Speter 12730175261Sobrien@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12731175261Sobrien@node Trigger Script Security 12732175261Sobrien@appendixsubsec Security and the Trigger Scripts 12733175261Sobrien@cindex Info files, security 12734175261Sobrien@cindex Trigger scripts, security 12735175261Sobrien 12736175261SobrienSecurity is a huge subject, and implementing a secure system is a non-trivial 12737175261Sobrientask. This section will barely touch on all the issues involved, but it is 12738175261Sobrienwell to note that, as with any script you will be allowing an untrusted 12739175261Sobrienuser to run on your server, there are measures you can take to help prevent 12740175261Sobrienyour trigger scripts from being abused. 12741175261Sobrien 12742175261SobrienFor instance, since the CVS trigger scripts all run in a copy of the user's 12743175261Sobriensandbox on the server, a naively coded Perl trigger script which attempts to 12744175261Sobrienuse a Perl module that is not installed on the system can be hijacked by any 12745175261Sobrienuser with commit access who is checking in a file with the correct name. Other 12746175261Sobrienscripting languages may be vulnerable to similar hacks. 12747175261Sobrien 12748175261SobrienOne way to make a script more secure, at least with Perl, is to use scripts 12749175261Sobrienwhich invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. 12750175261SobrienIn the most basic terms, this causes Perl to avoid running code that may have 12751175261Sobriencome from an external source. Please run the @code{perldoc perlsec} command 12752175261Sobrienfor more on Perl security. Again, other languages may implement other security 12753175261Sobrienverification hooks which look more or less like Perl's "taint-check" mechanism. 12754175261Sobrien 1275517721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12756175261Sobrien@node commit files 12757175261Sobrien@appendixsec The commit support files 12758175261Sobrien@cindex Committing, administrative support files 12759175261Sobrien 12760175261SobrienThere are three kinds of trigger scripts (@pxref{Trigger Scripts}) that can be 12761175261Sobrienrun at various times during a commit. They are specified in files in the 12762175261Sobrienrepository, as described below. The following table summarizes the 12763175261Sobrienfile names and the purpose of the corresponding programs. 12764175261Sobrien 12765175261Sobrien@table @file 12766175261Sobrien@item commitinfo 12767175261SobrienThe program is responsible for checking that the commit 12768175261Sobrienis allowed. If it exits with a non-zero exit status 12769175261Sobrienthe commit will be aborted. 12770175261Sobrien 12771175261Sobrien@item verifymsg 12772175261SobrienThe specified program is used to evaluate the log message, 12773175261Sobrienand possibly verify that it contains all required 12774175261Sobrienfields. This is most useful in combination with the 12775175261Sobrien@file{rcsinfo} file, which can hold a log message 12776175261Sobrientemplate (@pxref{rcsinfo}). 12777175261Sobrien 12778175261Sobrien@item editinfo 12779175261SobrienThe specified program is used to edit the log message, 12780175261Sobrienand possibly verify that it contains all required 12781175261Sobrienfields. This is most useful in combination with the 12782175261Sobrien@file{rcsinfo} file, which can hold a log message 12783175261Sobrientemplate (@pxref{rcsinfo}). (obsolete) 12784175261Sobrien 12785175261Sobrien@item loginfo 12786175261SobrienThe specified program is called when the commit is 12787175261Sobriencomplete. It receives the log message and some 12788175261Sobrienadditional information and can store the log message in 12789175261Sobriena file, or mail it to appropriate persons, or maybe 12790175261Sobrienpost it to a local newsgroup, or@dots{} Your 12791175261Sobrienimagination is the limit! 12792175261Sobrien@end table 12793175261Sobrien 12794175261Sobrien@menu 12795175261Sobrien* commitinfo:: Pre-commit checking 12796175261Sobrien* verifymsg:: How are log messages evaluated? 12797175261Sobrien* editinfo:: Specifying how log messages are created 12798175261Sobrien (obsolete) 12799175261Sobrien* loginfo:: Where should log messages be sent? 12800175261Sobrien@end menu 12801175261Sobrien 12802175261Sobrien@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1280317721Speter@node commitinfo 12804102840Speter@appendixsubsec Commitinfo 12805107484Speter@cindex @file{commitinfo} 12806107484Speter@cindex Commits, precommit verification of 1280717721Speter@cindex Precommit checking 1280817721Speter 1280917721SpeterThe @file{commitinfo} file defines programs to execute 1281017721Speterwhenever @samp{cvs commit} is about to execute. These 1281117721Speterprograms are used for pre-commit checking to verify 1281217721Speterthat the modified, added and removed files are really 1281317721Speterready to be committed. This could be used, for 1281417721Speterinstance, to verify that the changed files conform to 1281517721Speterto your site's standards for coding practice. 1281617721Speter 1281717721SpeterAs mentioned earlier, each line in the 1281817721Speter@file{commitinfo} file consists of a regular expression 1281917721Speterand a command-line template. The template can include 1282017721Spetera program name and any number of arguments you wish to 1282117721Spetersupply to it. The full path to the current source 1282217721Speterrepository is appended to the template, followed by the 1282317721Speterfile names of any files involved in the commit (added, 1282417721Speterremoved, and modified files). 1282517721Speter 1282666525Speter@cindex Exit status, of commitinfo 1282717721SpeterThe first line with a regular expression matching the 1282854427Speterdirectory within the repository will be used. If the 1282917721Spetercommand returns a non-zero exit status the commit will 1283017721Speterbe aborted. 1283154427Speter@c FIXME: need example(s) of what "directory within the 1283254427Speter@c repository" means. 1283317721Speter 1283417721Speter@cindex DEFAULT in commitinfo 1283517721SpeterIf the repository name does not match any of the 1283617721Speterregular expressions in this file, the @samp{DEFAULT} 1283717721Speterline is used, if it is specified. 1283817721Speter 1283917721Speter@cindex ALL in commitinfo 1284054427SpeterAll occurrences of the name @samp{ALL} appearing as a 1284117721Speterregular expression are used in addition to the first 1284217721Spetermatching regular expression or the name @samp{DEFAULT}. 1284317721Speter 12844107484Speter@cindex @file{commitinfo}, working directory 12845107484Speter@cindex @file{commitinfo}, command environment 12846107484SpeterThe command will be run in the root of the workspace 12847107484Spetercontaining the new versions of any files the user would like 12848107484Speterto modify (commit), @emph{or in a copy of the workspace on 12849107484Speterthe server (@pxref{Remote repositories})}. If a file is 12850107484Speterbeing removed, there will be no copy of the file under the 12851107484Spetercurrent directory. If a file is being added, there will be 12852107484Speterno corresponding archive file in the repository unless the 12853107484Speterfile is being resurrected. 1285417721Speter 12855107484SpeterNote that both the repository directory and the corresponding 12856107484SpeterAttic (@pxref{Attic}) directory may need to be checked to 12857107484Speterlocate the archive file corresponding to any given file being 12858107484Spetercommitted. Much of the information about the specific commit 12859107484Speterrequest being made, including the destination branch, commit 12860107484Spetermessage, and command line options specified, is not available 12861107484Speterto the command. 12862107484Speter 1286325839Speter@c FIXME: should discuss using commitinfo to control 1286425839Speter@c who has checkin access to what (e.g. Joe can check into 1286525839Speter@c directories a, b, and c, and Mary can check into 1286625839Speter@c directories b, c, and d--note this case cannot be 1286725839Speter@c conveniently handled with unix groups). Of course, 1286825839Speter@c adding a new set of features to CVS might be a more 1286925839Speter@c natural way to fix this problem than telling people to 1287025839Speter@c use commitinfo. 1287125839Speter@c FIXME: Should make some reference, especially in 1287225839Speter@c the context of controlling who has access, to the fact 1287325839Speter@c that commitinfo can be circumvented. Perhaps 1287425839Speter@c mention SETXID (but has it been carefully examined 1287525839Speter@c for holes?). This fits in with the discussion of 1287625839Speter@c general CVS security in "Password authentication 1287725839Speter@c security" (the bit which is not pserver-specific). 1287825839Speter 1287917721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1288025839Speter@node verifymsg 12881102840Speter@appendixsubsec Verifying log messages 12882102840Speter@cindex @file{verifymsg} (admin file) 1288366525Speter@cindex Log message, verifying 1288425839Speter 1288544852SpeterOnce you have entered a log message, you can evaluate 1288644852Speterthat message to check for specific content, such as 1288725839Spetera bug ID. Use the @file{verifymsg} file to 1288825839Speterspecify a program that is used to verify the log message. 1288925839SpeterThis program could be a simple script that checks 1289025839Speterthat the entered message contains the required fields. 1289125839Speter 1289225839SpeterThe @file{verifymsg} file is often most useful together 1289325839Speterwith the @file{rcsinfo} file, which can be used to 1289425839Speterspecify a log message template. 1289525839Speter 1289625839SpeterEach line in the @file{verifymsg} file consists of a 1289725839Speterregular expression and a command-line template. The 1289825839Spetertemplate must include a program name, and can include 1289925839Speterany number of arguments. The full path to the current 1290025839Speterlog message template file is appended to the template. 1290125839Speter 1290225839SpeterOne thing that should be noted is that the @samp{ALL} 1290325839Speterkeyword is not supported. If more than one matching 1290425839Speterline is found, the first one is used. This can be 1290525839Speteruseful for specifying a default verification script in a 1290654427Speterdirectory, and then overriding it in a subdirectory. 1290725839Speter 12908102840Speter@cindex DEFAULT in @file{verifymsg} 1290925839SpeterIf the repository name does not match any of the 1291025839Speterregular expressions in this file, the @samp{DEFAULT} 1291125839Speterline is used, if it is specified. 1291225839Speter 12913102840Speter@cindex Exit status, of @file{verifymsg} 1291425839SpeterIf the verification script exits with a non-zero exit status, 1291525839Speterthe commit is aborted. 1291625839Speter 12917102840Speter@cindex @file{verifymsg}, changing the log message 12918102840SpeterIn the default configuration, CVS allows the 12919102840Speterverification script to change the log message. This is 12920102840Spetercontrolled via the RereadLogAfterVerify CVSROOT/config 12921102840Speteroption. 1292225839Speter 12923102840SpeterWhen @samp{RereadLogAfterVerify=always} or 12924102840Speter@samp{RereadLogAfterVerify=stat}, the log message will 12925102840Spetereither always be reread after the verification script 12926102840Speteris run or reread only if the log message file status 12927102840Speterhas changed. 12928102840Speter 12929102840Speter@xref{config}, for more on CVSROOT/config options. 12930102840Speter 12931102840SpeterIt is NOT a good idea for a @file{verifymsg} script to 12932102840Speterinteract directly with the user in the various 12933102840Speterclient/server methods. For the @code{pserver} method, 12934102840Speterthere is no protocol support for communicating between 12935102840Speter@file{verifymsg} and the client on the remote end. For the 12936102840Speter@code{ext} and @code{server} methods, it is possible 12937102840Speterfor CVS to become confused by the characters going 12938102840Speteralong the same channel as the CVS protocol 12939102840Spetermessages. See @ref{Remote repositories}, for more 12940102840Speterinformation on client/server setups. In addition, at the time 12941102840Speterthe @file{verifymsg} script runs, the CVS 12942102840Speterserver has locks in place in the repository. If control is 12943102840Speterreturned to the user here then other users may be stuck waiting 12944102840Speterfor access to the repository. 12945102840Speter 12946102840SpeterThis option can be useful if you find yourself using an 12947102840Speterrcstemplate that needs to be modified to remove empty 12948102840Speterelements or to fill in default values. It can also be 12949102840Speteruseful if the rcstemplate has changed in the repository 12950102840Speterand the CVS/Template was not updated, but is able to be 12951102840Speteradapted to the new format by the verification script 12952102840Speterthat is run by @file{verifymsg}. 12953102840Speter 12954102840SpeterAn example of an update might be to change all 12955102840Speteroccurrences of 'BugId:' to be 'DefectId:' (which can be 12956102840Speteruseful if the rcstemplate has recently been changed and 12957102840Speterthere are still checked-out user trees with cached 12958102840Spetercopies in the CVS/Template file of the older version). 12959102840Speter 12960102840SpeterAnother example of an update might be to delete a line 12961102840Speterthat contains 'BugID: none' from the log message after 12962102840Spetervalidation of that value as being allowed is made. 12963102840Speter 1296425839SpeterThe following is a little silly example of a 1296525839Speter@file{verifymsg} file, together with the corresponding 1296625839Speter@file{rcsinfo} file, the log message template and an 1296725839Speterverification script. We begin with the log message template. 1296825839SpeterWe want to always record a bug-id number on the first 1296925839Speterline of the log message. The rest of log message is 1297025839Speterfree text. The following template is found in the file 1297125839Speter@file{/usr/cvssupport/tc.template}. 1297225839Speter 1297325839Speter@example 1297444852SpeterBugId: 1297525839Speter@end example 1297625839Speter 1297725839SpeterThe script @file{/usr/cvssupport/bugid.verify} is used to 1297825839Speterevaluate the log message. 1297925839Speter 1298025839Speter@example 1298125839Speter#!/bin/sh 1298225839Speter# 1298325839Speter# bugid.verify filename 1298425839Speter# 1298544852Speter# Verify that the log message contains a valid bugid 1298625839Speter# on the first line. 1298725839Speter# 12988128266Speterif sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 1298925839Speter exit 0 12990128266Speterelif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 12991102840Speter # It is okay to allow commits with 'BugId: none', 12992102840Speter # but do not put that text into the real log message. 12993102840Speter grep -v '^BugId:[ ]*none$' > $1.rewrite 12994102840Speter mv $1.rewrite $1 12995102840Speter exit 0 1299625839Speterelse 1299725839Speter echo "No BugId found." 1299825839Speter exit 1 1299925839Speterfi 1300025839Speter@end example 1300125839Speter 1300225839SpeterThe @file{verifymsg} file contains this line: 1300325839Speter 1300425839Speter@example 1300554427Speter^tc /usr/cvssupport/bugid.verify 1300625839Speter@end example 1300725839Speter 1300825839SpeterThe @file{rcsinfo} file contains this line: 1300925839Speter 1301025839Speter@example 1301125839Speter^tc /usr/cvssupport/tc.template 1301225839Speter@end example 1301325839Speter 13014102840SpeterThe @file{config} file contains this line: 1301525839Speter 13016102840Speter@example 13017102840SpeterRereadLogAfterVerify=always 13018102840Speter@end example 1301925839Speter 13020102840Speter 13021102840Speter 1302225839Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1302317721Speter@node editinfo 13024102840Speter@appendixsubsec Editinfo 1302525839Speter@cindex editinfo (admin file) 1302617721Speter@cindex Editor, specifying per module 1302717721Speter@cindex Per-module editor 1302817721Speter@cindex Log messages, editing 1302917721Speter 13030175261Sobrien@strong{The @file{editinfo} feature has been 1303125839Speterrendered obsolete. To set a default editor for log 13032128266Spetermessages use the @code{CVSEDITOR}, @code{EDITOR} environment variables 1303325839Speter(@pxref{Environment variables}) or the @samp{-e} global 1303425839Speteroption (@pxref{Global options}). See @ref{verifymsg}, 1303525839Speterfor information on the use of the @file{verifymsg} 13036128266Speterfeature for evaluating log messages.} 1303725839Speter 1303817721SpeterIf you want to make sure that all log messages look the 1303917721Spetersame way, you can use the @file{editinfo} file to 1304017721Speterspecify a program that is used to edit the log message. 1304117721SpeterThis program could be a custom-made editor that always 1304217721Speterenforces a certain style of the log message, or maybe a 1304317721Spetersimple shell script that calls an editor, and checks 1304417721Speterthat the entered message contains the required fields. 1304517721Speter 1304617721SpeterIf no matching line is found in the @file{editinfo} 1304717721Speterfile, the editor specified in the environment variable 1304817721Speter@code{$CVSEDITOR} is used instead. If that variable is 1304917721Speternot set, then the environment variable @code{$EDITOR} 1305017721Speteris used instead. If that variable is not 1305125839Speterset a default will be used. See @ref{Committing your changes}. 1305217721Speter 1305317721SpeterThe @file{editinfo} file is often most useful together 1305417721Speterwith the @file{rcsinfo} file, which can be used to 1305517721Speterspecify a log message template. 1305617721Speter 1305717721SpeterEach line in the @file{editinfo} file consists of a 1305817721Speterregular expression and a command-line template. The 1305917721Spetertemplate must include a program name, and can include 1306017721Speterany number of arguments. The full path to the current 1306117721Speterlog message template file is appended to the template. 1306217721Speter 1306317721SpeterOne thing that should be noted is that the @samp{ALL} 1306417721Speterkeyword is not supported. If more than one matching 1306517721Speterline is found, the first one is used. This can be 1306617721Speteruseful for specifying a default edit script in a 1306717721Spetermodule, and then overriding it in a subdirectory. 1306817721Speter 1306917721Speter@cindex DEFAULT in editinfo 1307017721SpeterIf the repository name does not match any of the 1307117721Speterregular expressions in this file, the @samp{DEFAULT} 1307217721Speterline is used, if it is specified. 1307317721Speter 1307417721SpeterIf the edit script exits with a non-zero exit status, 1307517721Speterthe commit is aborted. 1307617721Speter 1307766525SpeterNote: when @sc{cvs} is accessing a remote repository, 1307825839Speteror when the @samp{-m} or @samp{-F} options to @code{cvs 1307925839Spetercommit} are used, @file{editinfo} will not be consulted. 1308025839SpeterThere is no good workaround for this; use 1308125839Speter@file{verifymsg} instead. 1308217721Speter 1308317721Speter@menu 1308417721Speter* editinfo example:: Editinfo example 1308517721Speter@end menu 1308617721Speter 1308717721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308817721Speter@node editinfo example 13089102840Speter@appendixsubsubsec Editinfo example 1309017721Speter 1309117721SpeterThe following is a little silly example of a 1309217721Speter@file{editinfo} file, together with the corresponding 1309317721Speter@file{rcsinfo} file, the log message template and an 1309417721Spetereditor script. We begin with the log message template. 1309517721SpeterWe want to always record a bug-id number on the first 1309617721Speterline of the log message. The rest of log message is 1309717721Speterfree text. The following template is found in the file 1309817721Speter@file{/usr/cvssupport/tc.template}. 1309917721Speter 1310017721Speter@example 1310144852SpeterBugId: 1310217721Speter@end example 1310317721Speter 1310417721SpeterThe script @file{/usr/cvssupport/bugid.edit} is used to 1310517721Speteredit the log message. 1310617721Speter 1310717721Speter@example 1310817721Speter#!/bin/sh 1310917721Speter# 1311017721Speter# bugid.edit filename 1311117721Speter# 1311217721Speter# Call $EDITOR on FILENAME, and verify that the 1311317721Speter# resulting file contains a valid bugid on the first 1311417721Speter# line. 1311517721Speterif [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi 1311617721Speterif [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi 1311717721Speter$CVSEDITOR $1 1311817721Speteruntil head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1 1311917721Speterdo echo -n "No BugId found. Edit again? ([y]/n)" 1312017721Speter read ans 1312117721Speter case $@{ans@} in 1312217721Speter n*) exit 1;; 1312317721Speter esac 1312417721Speter $CVSEDITOR $1 1312517721Speterdone 1312617721Speter@end example 1312717721Speter 1312817721SpeterThe @file{editinfo} file contains this line: 1312917721Speter 1313017721Speter@example 1313117721Speter^tc /usr/cvssupport/bugid.edit 1313217721Speter@end example 1313317721Speter 1313417721SpeterThe @file{rcsinfo} file contains this line: 1313517721Speter 1313617721Speter@example 1313717721Speter^tc /usr/cvssupport/tc.template 1313817721Speter@end example 1313917721Speter 1314017721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1314117721Speter@node loginfo 13142102840Speter@appendixsubsec Loginfo 1314325839Speter@cindex loginfo (admin file) 1314417721Speter@cindex Storing log messages 1314517721Speter@cindex Mailing log messages 1314617721Speter@cindex Distributing log messages 1314717721Speter@cindex Log messages 1314817721Speter 1314932785Speter@c "cvs commit" is not quite right. What we 1315032785Speter@c mean is "when the repository gets changed" which 1315132785Speter@c also includes "cvs import" and "cvs add" on a directory. 1315217721SpeterThe @file{loginfo} file is used to control where 1315317721Speter@samp{cvs commit} log information is sent. The first 1315417721Speterentry on a line is a regular expression which is tested 1315517721Speteragainst the directory that the change is being made to, 1315617721Speterrelative to the @code{$CVSROOT}. If a match is found, then 1315717721Speterthe remainder of the line is a filter program that 1315817721Spetershould expect log information on its standard input. 13159128266SpeterNote that the filter program @strong{must} read @strong{all} 13160128266Speterof the log information or @sc{cvs} may fail with a broken pipe signal. 1316117721Speter 1316217721SpeterIf the repository name does not match any of the 1316317721Speterregular expressions in this file, the @samp{DEFAULT} 1316417721Speterline is used, if it is specified. 1316517721Speter 1316654427SpeterAll occurrences of the name @samp{ALL} appearing as a 1316717721Speterregular expression are used in addition to the first 1316817721Spetermatching regular expression or @samp{DEFAULT}. 1316917721Speter 1317017721SpeterThe first matching regular expression is used. 1317117721Speter 1317217721Speter@xref{commit files}, for a description of the syntax of 1317344852Speterthe @file{loginfo} file. 1317417721Speter 1317525839SpeterThe user may specify a format string as 1317625839Speterpart of the filter. The string is composed of a 1317725839Speter@samp{%} followed by a space, or followed by a single 1317825839Speterformat character, or followed by a set of format 1317925839Spetercharacters surrounded by @samp{@{} and @samp{@}} as 1318025839Speterseparators. The format characters are: 1318125839Speter 1318225839Speter@table @t 1318325839Speter@item s 1318425839Speterfile name 1318525839Speter@item V 1318625839Speterold version number (pre-checkin) 1318725839Speter@item v 1318825839Speternew version number (post-checkin) 1318925839Speter@end table 1319025839Speter 1319125839SpeterAll other characters that appear in a format string 1319225839Speterexpand to an empty field (commas separating fields are 1319325839Speterstill provided). 1319425839Speter 1319525839SpeterFor example, some valid format strings are @samp{%}, 1319625839Speter@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 1319725839Speter 13198102840SpeterThe output will be a space separated string of tokens enclosed in 13199102840Speterquotation marks (@t{"}). 13200102840SpeterAny embedded dollar signs (@t{$}), backticks (@t{`}), 13201102840Speterbackslashes (@t{\}), or quotation marks will be preceded 13202102840Speterby a backslash (this allows the shell to correctly parse it 13203102840Speteras a single string, reguardless of the characters it contains). 13204102840SpeterFor backwards compatibility, the first 1320566525Spetertoken will be the repository subdirectory. The rest of the 1320625839Spetertokens will be comma-delimited lists of the information 1320725839Speterrequested in the format string. For example, if 1320866525Speter@samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%@{sVv@}} 1320925839Speteris the format string, and three files (@t{ChangeLog}, 1321025839Speter@t{Makefile}, @t{foo.c}) were modified, the output 1321125839Spetermight be: 1321225839Speter 1321325839Speter@example 13214102840Speter"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13" 1321525839Speter@end example 1321625839Speter 1321725839SpeterAs another example, @samp{%@{@}} means that only the 1321825839Spetername of the repository will be generated. 1321925839Speter 1322066525SpeterNote: when @sc{cvs} is accessing a remote repository, 1322117721Speter@file{loginfo} will be run on the @emph{remote} 1322217721Speter(i.e., server) side, not the client side (@pxref{Remote 1322317721Speterrepositories}). 1322417721Speter 1322517721Speter@menu 1322617721Speter* loginfo example:: Loginfo example 1322725839Speter* Keeping a checked out copy:: Updating a tree on every checkin 1322817721Speter@end menu 1322917721Speter 1323017721Speter@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323117721Speter@node loginfo example 13232102840Speter@appendixsubsubsec Loginfo example 1323317721Speter 1323417721SpeterThe following @file{loginfo} file, together with the 1323544852Spetertiny shell-script below, appends all log messages 1323617721Speterto the file @file{$CVSROOT/CVSROOT/commitlog}, 1323717721Speterand any commits to the administrative files (inside 1323817721Speterthe @file{CVSROOT} directory) are also logged in 1323917721Speter@file{/usr/adm/cvsroot-log}. 1324044852SpeterCommits to the @file{prog1} directory are mailed to @t{ceder}. 1324117721Speter 1324217721Speter@c FIXME: is it a CVS feature or bug that only the 1324317721Speter@c first matching line is used? It is documented 1324444852Speter@c above, but is it useful? For example, if we wanted 1324544852Speter@c to run both "cvs-log" and "Mail" for the CVSROOT 1324644852Speter@c directory, it is kind of awkward if 1324717721Speter@c only the first matching line is used. 1324817721Speter@example 1324944852SpeterALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 1325017721Speter^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log 1325144852Speter^prog1 Mail -s %s ceder 1325217721Speter@end example 1325317721Speter 1325417721SpeterThe shell-script @file{/usr/local/bin/cvs-log} looks 1325517721Speterlike this: 1325617721Speter 1325717721Speter@example 1325817721Speter#!/bin/sh 1325925839Speter(echo "------------------------------------------------------"; 1326044852Speter echo -n $2" "; 1326117721Speter date; 1326217721Speter echo; 1326344852Speter cat) >> $1 1326417721Speter@end example 1326517721Speter 1326625839Speter@node Keeping a checked out copy 13267102840Speter@appendixsubsubsec Keeping a checked out copy 1326825839Speter 1326925839Speter@c What other index entries? It seems like 1327025839Speter@c people might want to use a lot of different 1327125839Speter@c words for this functionality. 1327266525Speter@cindex Keeping a checked out copy 1327366525Speter@cindex Checked out copy, keeping 1327466525Speter@cindex Web pages, maintaining with CVS 1327525839Speter 1327625839SpeterIt is often useful to maintain a directory tree which 1327725839Spetercontains files which correspond to the latest version 1327825839Speterin the repository. For example, other developers might 1327925839Speterwant to refer to the latest sources without having to 1328025839Spetercheck them out, or you might be maintaining a web site 1328125839Speterwith @sc{cvs} and want every checkin to cause the files 1328225839Speterused by the web server to be updated. 1328325839Speter@c Can we offer more details on the web example? Or 1328425839Speter@c point the user at how to figure it out? This text 1328525839Speter@c strikes me as sufficient for someone who already has 1328625839Speter@c some idea of what we mean but not enough for the naive 1328725839Speter@c user/sysadmin to understand it and set it up. 1328825839Speter 1328925839SpeterThe way to do this is by having loginfo invoke 1329025839Speter@code{cvs update}. Doing so in the naive way will 1329125839Spetercause a problem with locks, so the @code{cvs update} 1329225839Spetermust be run in the background. 1329325839Speter@c Should we try to describe the problem with locks? 1329425839Speter@c It seems like a digression for someone who just 1329525839Speter@c wants to know how to make it work. 1329625839Speter@c Another choice which might work for a single file 1329725839Speter@c is to use "cvs -n update -p" which doesn't take 1329825839Speter@c out locks (I think) but I don't see many advantages 1329925839Speter@c of that and we might as well document something which 1330025839Speter@c works for multiple files. 1330134461SpeterHere is an example for unix (this should all be on one line): 1330225839Speter 1330325839Speter@example 1330425839Speter^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs; 1330525839Speter cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 1330625839Speter@end example 1330725839Speter 1330825839SpeterThis will cause checkins to repository directories 1330925839Speterstarting with @code{cyclic-pages} to update the checked 1331025839Speterout tree in @file{/u/www/local-docs}. 1331125839Speter@c More info on some of the details? The "sleep 2" is 1331225839Speter@c so if we are lucky the lock will be gone by the time 1331325839Speter@c we start and we can wait 2 seconds instead of 30. 1331425839Speter 1331517721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1331617721Speter@node rcsinfo 1331717721Speter@appendixsec Rcsinfo 1331825839Speter@cindex rcsinfo (admin file) 1331917721Speter@cindex Form for log message 1332017721Speter@cindex Log message template 1332117721Speter@cindex Template for log message 1332217721Speter 1332317721SpeterThe @file{rcsinfo} file can be used to specify a form to 1332417721Speteredit when filling out the commit log. The 1332517721Speter@file{rcsinfo} file has a syntax similar to the 1332625839Speter@file{verifymsg}, @file{commitinfo} and @file{loginfo} 1332717721Speterfiles. @xref{syntax}. Unlike the other files the second 1332817721Speterpart is @emph{not} a command-line template. Instead, 1332917721Speterthe part after the regular expression should be a full pathname to 1333017721Spetera file containing the log message template. 1333117721Speter 1333217721SpeterIf the repository name does not match any of the 1333317721Speterregular expressions in this file, the @samp{DEFAULT} 1333417721Speterline is used, if it is specified. 1333517721Speter 1333654427SpeterAll occurrences of the name @samp{ALL} appearing as a 1333717721Speterregular expression are used in addition to the first 1333817721Spetermatching regular expression or @samp{DEFAULT}. 1333917721Speter 1334025839Speter@c FIXME: should be offering advice, somewhere around 1334125839Speter@c here, about where to put the template file. The 1334225839Speter@c verifymsg example uses /usr/cvssupport but doesn't 1334325839Speter@c say anything about what that directory is for or 1334425839Speter@c whether it is hardwired into CVS or who creates 1334525839Speter@c it or anything. In particular we should say 1334625839Speter@c how to version control the template file. A 1334754427Speter@c probably better answer than the /usr/cvssupport 1334832785Speter@c stuff is to use checkoutlist (with xref to the 1334932785Speter@c checkoutlist doc). 1335025839Speter@c Also I am starting to see a connection between 1335125839Speter@c this and the Keeping a checked out copy node. 1335225839Speter@c Probably want to say something about that. 1335317721SpeterThe log message template will be used as a default log 1335417721Spetermessage. If you specify a log message with @samp{cvs 1335517721Spetercommit -m @var{message}} or @samp{cvs commit -f 1335617721Speter@var{file}} that log message will override the 1335717721Spetertemplate. 1335817721Speter 1335925839Speter@xref{verifymsg}, for an example @file{rcsinfo} 1336017721Speterfile. 1336117721Speter 1336266525SpeterWhen @sc{cvs} is accessing a remote repository, 1336317721Speterthe contents of @file{rcsinfo} at the time a directory 1336417721Speteris first checked out will specify a template which does 1336517721Speternot then change. If you edit @file{rcsinfo} or its 1336617721Spetertemplates, you may need to check out a new working 1336717721Speterdirectory. 1336817721Speter@c Would be nice to fix CVS so this isn't needed. For 1336917721Speter@c example, a mechanism analogous to CVS/Entries, where 1337017721Speter@c the client keeps track of what version of the template 1337117721Speter@c it has. 1337217721Speter 1337317721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13374128266Speter@node taginfo 13375128266Speter@appendixsec Taginfo 13376128266Speter@cindex taginfo (admin file) 13377128266Speter@cindex Tags, logging 13378128266Speter@cindex Tags, verifying 13379128266SpeterThe @file{taginfo} file defines programs to execute 13380128266Speterwhen someone executes a @code{tag} or @code{rtag} 13381128266Spetercommand. The @file{taginfo} file has the standard form 13382175261Sobrienfor trigger scripts (@pxref{Trigger Scripts}), 13383128266Speterwhere each line is a regular expression 13384175261Sobrienfollowed by a command to execute (@pxref{syntax}). The arguments passed 13385128266Speterto the command are, in order, the @var{tagname}, 13386128266Speter@var{operation} (@code{add} for @code{tag}, 13387128266Speter@code{mov} for @code{tag -F}, and @code{del} for 13388128266Speter@code{tag -d}), @var{repository}, and any remaining are 13389128266Speterpairs of @var{filename} @var{revision}. A non-zero 13390128266Speterexit of the filter program will cause the tag to be 13391128266Speteraborted. 13392128266Speter 13393128266SpeterHere is an example of using the @file{taginfo} file 13394128266Speterto log @code{tag} and @code{rtag} 13395128266Spetercommands. In the @file{taginfo} file put: 13396128266Speter 13397128266Speter@example 13398128266SpeterALL /usr/local/cvsroot/CVSROOT/loggit 13399128266Speter@end example 13400128266Speter 13401128266Speter@noindent 13402128266SpeterWhere @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 13403128266Speterfollowing script: 13404128266Speter 13405128266Speter@example 13406128266Speter#!/bin/sh 13407128266Speterecho "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 13408128266Speter@end example 13409128266Speter 13410128266Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1341117721Speter@node cvsignore 1341217721Speter@appendixsec Ignoring files via cvsignore 1341325839Speter@cindex cvsignore (admin file), global 1341417721Speter@cindex Global cvsignore 1341517721Speter@cindex Ignoring files 1341617721Speter@c -- This chapter should maybe be moved to the 1341717721Speter@c tutorial part of the manual? 1341817721Speter 1341917721SpeterThere are certain file names that frequently occur 1342017721Speterinside your working copy, but that you don't want to 1342117721Speterput under @sc{cvs} control. Examples are all the object 1342217721Speterfiles that you get while you compile your sources. 1342317721SpeterNormally, when you run @samp{cvs update}, it prints a 1342417721Speterline for each file it encounters that it doesn't know 1342517721Speterabout (@pxref{update output}). 1342617721Speter 1342717721Speter@sc{cvs} has a list of files (or sh(1) file name patterns) 1342817721Speterthat it should ignore while running @code{update}, 1342917721Speter@code{import} and @code{release}. 1343017721Speter@c -- Are those the only three commands affected? 1343117721SpeterThis list is constructed in the following way. 1343217721Speter 1343317721Speter@itemize @bullet 1343417721Speter@item 1343517721SpeterThe list is initialized to include certain file name 1343617721Speterpatterns: names associated with @sc{cvs} 1343717721Speteradministration, or with other common source control 1343817721Spetersystems; common names for patch files, object files, 1343917721Speterarchive files, and editor backup files; and other names 1344017721Speterthat are usually artifacts of assorted utilities. 1344117721SpeterCurrently, the default list of ignored file name 1344217721Speterpatterns is: 1344317721Speter 1344417721Speter@cindex Ignored files 1344517721Speter@cindex Automatically ignored files 1344617721Speter@example 1344717721Speter RCS SCCS CVS CVS.adm 1344817721Speter RCSLOG cvslog.* 1344917721Speter tags TAGS 1345017721Speter .make.state .nse_depinfo 1345117721Speter *~ #* .#* ,* _$* *$ 1345217721Speter *.old *.bak *.BAK *.orig *.rej .del-* 1345317721Speter *.a *.olb *.o *.obj *.so *.exe 1345444852Speter *.Z *.elc *.ln 1345517721Speter core 1345617721Speter@end example 1345717721Speter 1345817721Speter@item 1345917721SpeterThe per-repository list in 1346017721Speter@file{$CVSROOT/CVSROOT/cvsignore} is appended to 1346117721Speterthe list, if that file exists. 1346217721Speter 1346317721Speter@item 1346417721SpeterThe per-user list in @file{.cvsignore} in your home 1346517721Speterdirectory is appended to the list, if it exists. 1346617721Speter 1346717721Speter@item 1346817721SpeterAny entries in the environment variable 1346917721Speter@code{$CVSIGNORE} is appended to the list. 1347017721Speter 1347117721Speter@item 1347217721SpeterAny @samp{-I} options given to @sc{cvs} is appended. 1347317721Speter 1347417721Speter@item 1347517721SpeterAs @sc{cvs} traverses through your directories, the contents 1347617721Speterof any @file{.cvsignore} will be appended to the list. 1347717721SpeterThe patterns found in @file{.cvsignore} are only valid 1347817721Speterfor the directory that contains them, not for 1347917721Speterany sub-directories. 1348017721Speter@end itemize 1348117721Speter 1348217721SpeterIn any of the 5 places listed above, a single 1348317721Speterexclamation mark (@samp{!}) clears the ignore list. 1348417721SpeterThis can be used if you want to store any file which 1348517721Speternormally is ignored by @sc{cvs}. 1348617721Speter 1348725839SpeterSpecifying @samp{-I !} to @code{cvs import} will import 1348825839Spetereverything, which is generally what you want to do if 1348925839Speteryou are importing files from a pristine distribution or 1349025839Speterany other source which is known to not contain any 1349125839Speterextraneous files. However, looking at the rules above 1349225839Speteryou will see there is a fly in the ointment; if the 1349325839Speterdistribution contains any @file{.cvsignore} files, then 1349425839Speterthe patterns from those files will be processed even if 1349525839Speter@samp{-I !} is specified. The only workaround is to 1349625839Speterremove the @file{.cvsignore} files in order to do the 1349725839Speterimport. Because this is awkward, in the future 1349825839Speter@samp{-I !} might be modified to override 1349925839Speter@file{.cvsignore} files in each directory. 1350025839Speter 1350132785SpeterNote that the syntax of the ignore files consists of a 1350232785Speterseries of lines, each of which contains a space 1350332785Speterseparated list of filenames. This offers no clean way 1350432785Speterto specify filenames which contain spaces, but you can 1350532785Speteruse a workaround like @file{foo?bar} to match a file 1350632785Speternamed @file{foo bar} (it also matches @file{fooxbar} 1350732785Speterand the like). Also note that there is currently no 1350832785Speterway to specify comments. 1350932785Speter@c FIXCVS? I don't _like_ this syntax at all, but 1351032785Speter@c changing it raises all the usual compatibility 1351132785Speter@c issues and I'm also not sure what to change it to. 1351232785Speter 1351354427Speter@node checkoutlist 1351454427Speter@appendixsec The checkoutlist file 1351554427Speter@cindex checkoutlist 1351654427Speter 1351754427SpeterIt may be helpful to use @sc{cvs} to maintain your own 1351854427Speterfiles in the @file{CVSROOT} directory. For example, 1351954427Spetersuppose that you have a script @file{logcommit.pl} 1352054427Speterwhich you run by including the following line in the 1352154427Speter@file{commitinfo} administrative file: 1352254427Speter 1352354427Speter@example 1352454427SpeterALL $CVSROOT/CVSROOT/logcommit.pl 1352554427Speter@end example 1352654427Speter 1352754427SpeterTo maintain @file{logcommit.pl} with @sc{cvs} you would 1352854427Speteradd the following line to the @file{checkoutlist} 1352954427Speteradministrative file: 1353054427Speter 1353154427Speter@example 1353254427Speterlogcommit.pl 1353354427Speter@end example 1353454427Speter 1353554427SpeterThe format of @file{checkoutlist} is one line for each 1353654427Speterfile that you want to maintain using @sc{cvs}, giving 13537128266Speterthe name of the file, followed optionally by more whitespace 13538128266Speterand any error message that should print if the file cannot be 13539128266Speterchecked out into CVSROOT after a commit: 1354054427Speter 13541128266Speter@example 13542128266Speterlogcommit.pl Could not update CVSROOT/logcommit.pl. 13543128266Speter@end example 13544128266Speter 1354554427SpeterAfter setting up @file{checkoutlist} in this fashion, 1354654427Speterthe files listed there will function just like 1354754427Speter@sc{cvs}'s built-in administrative files. For example, 1354854427Speterwhen checking in one of the files you should get a 1354954427Spetermessage such as: 1355054427Speter 1355154427Speter@example 1355254427Spetercvs commit: Rebuilding administrative file database 1355354427Speter@end example 1355454427Speter 13555102840Speter@noindent 1355654427Speterand the checked out copy in the @file{CVSROOT} 1355754427Speterdirectory should be updated. 1355854427Speter 1355954427SpeterNote that listing @file{passwd} (@pxref{Password 1356054427Speterauthentication server}) in @file{checkoutlist} is not 1356154427Speterrecommended for security reasons. 1356254427Speter 1356354427SpeterFor information about keeping a checkout out copy in a 1356454427Spetermore general context than the one provided by 1356554427Speter@file{checkoutlist}, see @ref{Keeping a checked out 1356654427Spetercopy}. 1356754427Speter 1356817721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1356917721Speter@node history file 1357017721Speter@appendixsec The history file 1357117721Speter@cindex History file 1357217721Speter@cindex Log information, saving 1357317721Speter 1357417721SpeterThe file @file{$CVSROOT/CVSROOT/history} is used 1357517721Speterto log information for the @code{history} command 1357617721Speter(@pxref{history}). This file must be created to turn 1357717721Speteron logging. This is done automatically if the 1357817721Speter@code{cvs init} command is used to set up the 1357925839Speterrepository (@pxref{Creating a repository}). 1358017721Speter 1358117721SpeterThe file format of the @file{history} file is 1358217721Speterdocumented only in comments in the @sc{cvs} source 1358317721Spetercode, but generally programs should use the @code{cvs 1358417721Speterhistory} command to access it anyway, in case the 1358517721Speterformat changes with future releases of @sc{cvs}. 1358617721Speter 1358717721Speter@node Variables 1358817721Speter@appendixsec Expansions in administrative files 1358966525Speter@cindex Internal variables 1359066525Speter@cindex Variables 1359117721Speter 1359217721SpeterSometimes in writing an administrative file, you might 1359317721Speterwant the file to be able to know various things based 1359417721Speteron environment @sc{cvs} is running in. There are 1359517721Speterseveral mechanisms to do that. 1359617721Speter 1359717721SpeterTo find the home directory of the user running @sc{cvs} 1359817721Speter(from the @code{HOME} environment variable), use 1359917721Speter@samp{~} followed by @samp{/} or the end of the line. 1360017721SpeterLikewise for the home directory of @var{user}, use 1360117721Speter@samp{~@var{user}}. These variables are expanded on 1360232785Speterthe server machine, and don't get any reasonable 1360317721Speterexpansion if pserver (@pxref{Password authenticated}) 1360432785Speteris in use; therefore user variables (see below) may be 1360517721Spetera better choice to customize behavior based on the user 1360617721Speterrunning @sc{cvs}. 1360717721Speter@c Based on these limitations, should we deprecate ~? 1360817721Speter@c What is it good for? Are people using it? 1360917721Speter 1361017721SpeterOne may want to know about various pieces of 1361117721Speterinformation internal to @sc{cvs}. A @sc{cvs} internal 1361217721Spetervariable has the syntax @code{$@{@var{variable}@}}, 1361317721Speterwhere @var{variable} starts with a letter and consists 1361454427Speterof alphanumeric characters and @samp{_}. If the 1361517721Spetercharacter following @var{variable} is a 1361617721Speternon-alphanumeric character other than @samp{_}, the 1361717721Speter@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 1361817721Speterinternal variables are: 1361917721Speter 1362017721Speter@table @code 1362117721Speter@item CVSROOT 1362266525Speter@cindex CVSROOT, internal variable 13623102840SpeterThis is the absolute path to the current @sc{cvs} root directory. 1362417721Speter@xref{Repository}, for a description of the various 13625102840Speterways to specify this, but note that the internal 13626102840Spetervariable contains just the directory and not any 13627102840Speterof the access method information. 1362817721Speter 1362917721Speter@item RCSBIN 1363066525Speter@cindex RCSBIN, internal variable 1363132785SpeterIn @sc{cvs} 1.9.18 and older, this specified the 1363232785Speterdirectory where @sc{cvs} was looking for @sc{rcs} 1363332785Speterprograms. Because @sc{cvs} no longer runs @sc{rcs} 1363432785Speterprograms, specifying this internal variable is now an 1363532785Spetererror. 1363617721Speter 1363717721Speter@item CVSEDITOR 1363866525Speter@cindex CVSEDITOR, internal variable 13639128266Speter@itemx EDITOR 13640128266Speter@cindex EDITOR, internal variable 1364117721Speter@itemx VISUAL 1364266525Speter@cindex VISUAL, internal variable 1364317721SpeterThese all expand to the same value, which is the editor 1364417721Speterthat @sc{cvs} is using. @xref{Global options}, for how 1364517721Speterto specify this. 1364617721Speter 1364717721Speter@item USER 1364866525Speter@cindex USER, internal variable 1364917721SpeterUsername of the user running @sc{cvs} (on the @sc{cvs} 1365017721Speterserver machine). 1365166525SpeterWhen using pserver, this is the user specified in the repository 1365266525Speterspecification which need not be the same as the username the 1365366525Speterserver is running as (@pxref{Password authentication server}). 13654102840SpeterDo not confuse this with the environment variable of the same name. 1365517721Speter@end table 1365617721Speter 1365717721SpeterIf you want to pass a value to the administrative files 1365832785Speterwhich the user who is running @sc{cvs} can specify, 1365966525Speteruse a user variable. 1366066525Speter@cindex User variables 1366166525SpeterTo expand a user variable, the 1366217721Speteradministrative file contains 1366317721Speter@code{$@{=@var{variable}@}}. To set a user variable, 1366417721Speterspecify the global option @samp{-s} to @sc{cvs}, with 1366517721Speterargument @code{@var{variable}=@var{value}}. It may be 1366617721Speterparticularly useful to specify this option via 1366717721Speter@file{.cvsrc} (@pxref{~/.cvsrc}). 1366817721Speter 1366917721SpeterFor example, if you want the administrative file to 1367017721Speterrefer to a test directory you might create a user 1367117721Spetervariable @code{TESTDIR}. Then if @sc{cvs} is invoked 1367225839Speteras 1367325839Speter 1367425839Speter@example 1367525839Spetercvs -s TESTDIR=/work/local/tests 1367625839Speter@end example 1367725839Speter 1367825839Speter@noindent 1367925839Speterand the 1368017721Speteradministrative file contains @code{sh 1368117721Speter$@{=TESTDIR@}/runtests}, then that string is expanded 1368217721Speterto @code{sh /work/local/tests/runtests}. 1368317721Speter 1368417721SpeterAll other strings containing @samp{$} are reserved; 1368517721Speterthere is no way to quote a @samp{$} character so that 1368617721Speter@samp{$} represents itself. 1368717721Speter 1368881404SpeterEnvironment variables passed to administrative files are: 1368981404Speter 1369081404Speter@table @code 1369181404Speter@cindex environment variables, passed to administrative files 1369281404Speter 1369381404Speter@item CVS_USER 13694102840Speter@cindex CVS_USER, environment variable 1369581404SpeterThe @sc{cvs}-specific username provided by the user, if it 1369681404Spetercan be provided (currently just for the pserver access 13697102840Spetermethod), and to the empty string otherwise. (@code{CVS_USER} 13698102840Speterand @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 13699102840Speteris used to map @sc{cvs} usernames to system usernames.) 13700102840Speter 13701102840Speter@item LOGNAME 13702102840Speter@cindex LOGNAME, environment variable 13703102840SpeterThe username of the system user. 13704102840Speter 13705102840Speter@item USER 13706102840Speter@cindex USER, environment variable 13707102840SpeterSame as @code{LOGNAME}. 13708102840SpeterDo not confuse this with the internal variable of the same name. 1370981404Speter@end table 1371081404Speter 1371132785Speter@node config 1371232785Speter@appendixsec The CVSROOT/config configuration file 1371332785Speter 1371432785Speter@cindex config, in CVSROOT 1371532785Speter@cindex CVSROOT/config 1371632785Speter 1371732785SpeterThe administrative file @file{config} contains various 1371832785Spetermiscellaneous settings which affect the behavior of 1371932785Speter@sc{cvs}. The syntax is slightly different from the 1372032785Speterother administrative files. Variables are not 1372132785Speterexpanded. Lines which start with @samp{#} are 1372232785Speterconsidered comments. 1372332785Speter@c FIXME: where do we define comments for the other 1372432785Speter@c administrative files. 1372532785SpeterOther lines consist of a keyword, @samp{=}, and a 1372632785Spetervalue. Note that this syntax is very strict. 1372732785SpeterExtraneous spaces or tabs are not permitted. 1372832785Speter@c See comments in parseinfo.c:parse_config for more 1372932785Speter@c discussion of this strictness. 1373032785Speter 1373132785SpeterCurrently defined keywords are: 1373232785Speter 1373332785Speter@table @code 1373432785Speter@cindex RCSBIN, in CVSROOT/config 1373532785Speter@item RCSBIN=@var{bindir} 1373632785SpeterFor @sc{cvs} 1.9.12 through 1.9.18, this setting told 1373732785Speter@sc{cvs} to look for @sc{rcs} programs in the 1373832785Speter@var{bindir} directory. Current versions of @sc{cvs} 1373932785Speterdo not run @sc{rcs} programs; for compatibility this 1374032785Spetersetting is accepted, but it does nothing. 1374132785Speter 1374232785Speter@cindex SystemAuth, in CVSROOT/config 1374332785Speter@item SystemAuth=@var{value} 1374432785SpeterIf @var{value} is @samp{yes}, then pserver should check 1374532785Speterfor users in the system's user database if not found in 1374632785Speter@file{CVSROOT/passwd}. If it is @samp{no}, then all 1374732785Speterpserver users must exist in @file{CVSROOT/passwd}. 1374832785SpeterThe default is @samp{yes}. For more on pserver, see 1374932785Speter@ref{Password authenticated}. 1375034461Speter 1375166525Speter@ignore 1375234461Speter@cindex PreservePermissions, in CVSROOT/config 1375334461Speter@item PreservePermissions=@var{value} 1375434461SpeterEnable support for saving special device files, 1375534461Spetersymbolic links, file permissions and ownerships in the 1375634461Speterrepository. The default value is @samp{no}. 1375754427Speter@xref{Special Files}, for the full implications of using 1375834461Speterthis keyword. 1375966525Speter@end ignore 1376044852Speter 1376144852Speter@cindex TopLevelAdmin, in CVSROOT/config 1376244852Speter@item TopLevelAdmin=@var{value} 1376344852SpeterModify the @samp{checkout} command to create a 1376444852Speter@samp{CVS} directory at the top level of the new 1376544852Speterworking directory, in addition to @samp{CVS} 1376644852Speterdirectories created within checked-out directories. 1376744852SpeterThe default value is @samp{no}. 1376844852Speter 1376944852SpeterThis option is useful if you find yourself performing 1377044852Spetermany commands at the top level of your working 1377144852Speterdirectory, rather than in one of the checked out 1377266525Spetersubdirectories. The @file{CVS} directory created there 1377366525Speterwill mean you don't have to specify @code{CVSROOT} for 1377444852Spetereach command. It also provides a place for the 1377566525Speter@file{CVS/Template} file (@pxref{Working directory 1377644852Speterstorage}). 1377744852Speter 1377854427Speter@cindex LockDir, in CVSROOT/config 1377954427Speter@item LockDir=@var{directory} 1378081404SpeterPut @sc{cvs} lock files in @var{directory} rather than 1378154427Speterdirectly in the repository. This is useful if you want 1378254427Speterto let users read from the repository while giving them 1378354427Speterwrite access only to @var{directory}, not to the 13784102840Speterrepository. 13785102840SpeterIt can also be used to put the locks on a very fast 13786102840Speterin-memory file system to speed up locking and unlocking 13787102840Speterthe repository. 13788102840SpeterYou need to create @var{directory}, but 1378981404Speter@sc{cvs} will create subdirectories of @var{directory} as it 1379081404Speterneeds them. For information on @sc{cvs} locks, see 1379154427Speter@ref{Concurrency}. 1379254427Speter 1379354427Speter@c Mention this in Compatibility section? 1379454427SpeterBefore enabling the LockDir option, make sure that you 1379581404Speterhave tracked down and removed any copies of @sc{cvs} 1.9 or 1379654427Speterolder. Such versions neither support LockDir, nor will 1379754427Spetergive an error indicating that they don't support it. 1379854427SpeterThe result, if this is allowed to happen, is that some 1379981404Speter@sc{cvs} users will put the locks one place, and others will 1380054427Speterput them another place, and therefore the repository 1380181404Spetercould become corrupted. @sc{cvs} 1.10 does not support 1380254427SpeterLockDir but it will print a warning if run on a 1380354427Speterrepository with LockDir enabled. 1380466525Speter 1380566525Speter@cindex LogHistory, in CVSROOT/config 1380666525Speter@item LogHistory=@var{value} 13807102840SpeterControl what is logged to the @file{CVSROOT/history} file (@pxref{history}). 13808128266SpeterDefault of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log 1380966525Speterall transactions. Any subset of the default is 1381066525Speterlegal. (For example, to only log transactions that modify the 1381166525Speter@file{*,v} files, use @samp{LogHistory=TMAR}.) 13812102840Speter 13813102840Speter@cindex RereadLogAfterVerify, in CVSROOT/config 13814102840Speter@cindex @file{verifymsg}, changing the log message 13815102840Speter@item RereadLogAfterVerify=@var{value} 13816102840SpeterModify the @samp{commit} command such that CVS will reread the 13817102840Speterlog message after running the program specified by @file{verifymsg}. 13818102840Speter@var{value} may be one of @samp{yes} or @samp{always}, indicating that 13819102840Speterthe log message should always be reread; @samp{no} 13820102840Speteror @samp{never}, indicating that it should never be 13821102840Speterreread; or @var{value} may be @samp{stat}, indicating 13822130303Speterthat the file should be checked with the file system 13823102840Speter@samp{stat()} function to see if it has changed (see warning below) 13824102840Speterbefore rereading. The default value is @samp{always}. 13825102840Speter 13826175261Sobrien@strong{The `stat' mode can cause CVS to pause for up to 13827102840Speterone extra second per directory committed. This can be less IO and 13828102840SpeterCPU intensive but is not recommended for use with large repositories} 13829102840Speter 13830102840Speter@xref{verifymsg}, for more information on how verifymsg 13831102840Spetermay be used. 13832177391Sobrien 13833177391Sobrien@cindex IgnoreUnknownConfigKeys, in CVSROOT/config 13834177391Sobrien@item IgnoreUnknownConfigKeys=@var{value} 13835177391SobrienIf @var{value} is @samp{yes}, then @sc{cvs} should 13836177391Sobrienignore any keywords in @file{CVSROOT/config} which it 13837177391Sobriendoes not recognize. This option is intended primarily 13838177391Sobrienfor transitions between versions of @sc{cvs} which 13839177391Sobriensupport more configuration options in an environment 13840177391Sobrienwhere a read-only mirror of the current @sc{cvs} server 13841177391Sobrienmay be maintained by someone else who is not yet ready 13842177391Sobriento upgrade to the same version. It is recommended that 13843177391Sobrienthis option be used only for a short time so that 13844177391Sobrienproblems with the @file{CVSROOT/config} file will be 13845177391Sobrienfound quickly. The default is @samp{no}. 1384632785Speter@end table 1384732785Speter 1384817721Speter@c --------------------------------------------------------------------- 1384917721Speter@node Environment variables 1385017721Speter@appendix All environment variables which affect CVS 1385117721Speter@cindex Environment variables 1385217721Speter@cindex Reference manual for variables 1385317721Speter 1385417721SpeterThis is a complete list of all environment variables 1385517721Speterthat affect @sc{cvs}. 1385617721Speter 1385717721Speter@table @code 1385832785Speter@cindex CVSIGNORE, environment variable 1385917721Speter@item $CVSIGNORE 1386017721SpeterA whitespace-separated list of file name patterns that 1386117721Speter@sc{cvs} should ignore. @xref{cvsignore}. 1386217721Speter 1386332785Speter@cindex CVSWRAPPERS, environment variable 1386417721Speter@item $CVSWRAPPERS 1386517721SpeterA whitespace-separated list of file name patterns that 1386617721Speter@sc{cvs} should treat as wrappers. @xref{Wrappers}. 1386717721Speter 1386832785Speter@cindex CVSREAD, environment variable 1386966525Speter@cindex Read-only files, and CVSREAD 1387017721Speter@item $CVSREAD 1387117721SpeterIf this is set, @code{checkout} and @code{update} will 1387217721Spetertry hard to make the files in your working directory 1387317721Speterread-only. When this is not set, the default behavior 1387417721Speteris to permit modification of your working files. 1387517721Speter 1387626801Speter@item $CVSUMASK 1387726801SpeterControls permissions of files in the repository. See 1387826801Speter@ref{File permissions}. 1387926801Speter 1388017721Speter@item $CVSROOT 1388117721SpeterShould contain the full pathname to the root of the @sc{cvs} 1388232785Spetersource repository (where the @sc{rcs} files are 1388317721Speterkept). This information must be available to @sc{cvs} for 1388417721Spetermost commands to execute; if @code{$CVSROOT} is not set, 1388517721Speteror if you wish to override it for one invocation, you 1388617721Spetercan supply it on the command line: @samp{cvs -d cvsroot 1388717721Spetercvs_command@dots{}} Once you have checked out a working 1388817721Speterdirectory, @sc{cvs} stores the appropriate root (in 1388917721Speterthe file @file{CVS/Root}), so normally you only need to 1389044852Speterworry about this when initially checking out a working 1389117721Speterdirectory. 1389217721Speter 13893128266Speter@item $CVSEDITOR 13894128266Speter@cindex CVSEDITOR, environment variable 13895128266Speter@itemx $EDITOR 13896128266Speter@cindex EDITOR, environment variable 1389754427Speter@itemx $VISUAL 13898128266Speter@cindex VISUAL, environment variable 1389917721SpeterSpecifies the program to use for recording log messages 1390025839Speterduring commit. @code{$CVSEDITOR} overrides 13901128266Speter@code{$EDITOR}, which overrides @code{$VISUAL}. 13902128266SpeterSee @ref{Committing your changes} for more or 13903128266Speter@ref{Global options} for alternative ways of specifying a 13904128266Speterlog editor. 1390517721Speter 1390632785Speter@cindex PATH, environment variable 1390717721Speter@item $PATH 1390817721SpeterIf @code{$RCSBIN} is not set, and no path is compiled 1390917721Speterinto @sc{cvs}, it will use @code{$PATH} to try to find all 1391017721Speterprograms it uses. 1391117721Speter 1391232785Speter@cindex HOME, environment variable 1391317721Speter@item $HOME 1391432785Speter@cindex HOMEPATH, environment variable 1391517721Speter@item $HOMEPATH 1391632785Speter@cindex HOMEDRIVE, environment variable 1391732785Speter@item $HOMEDRIVE 1391817721SpeterUsed to locate the directory where the @file{.cvsrc} 1391981404Speterfile, and other such files, are searched. On Unix, @sc{cvs} 1392066525Speterjust checks for @code{HOME}. On Windows NT, the system will 1392166525Speterset @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 1392232785Speterfor example to @file{\joe}. On Windows 95, you'll 1392366525Speterprobably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 1392432785Speter@c We are being vague about whether HOME works on 1392532785Speter@c Windows; see long comment in windows-NT/filesubr.c. 1392617721Speter 1392732785Speter@cindex CVS_RSH, environment variable 1392817721Speter@item $CVS_RSH 1392981404SpeterSpecifies the external program which @sc{cvs} connects with, 1393025839Speterwhen @code{:ext:} access method is specified. 1393125839Speter@pxref{Connecting via rsh}. 1393217721Speter 13933177391Sobrien@cindex CVS_SSH, environment variable 13934177391Sobrien@item $CVS_SSH 13935177391SobrienSpecifies the external program which @sc{cvs} connects with, 13936177391Sobrienwhen @code{:extssh:} access method is specified. 13937177391Sobrien@pxref{Connecting via rsh}. 13938177391Sobrien 1393917721Speter@item $CVS_SERVER 1394017721SpeterUsed in client-server mode when accessing a remote 1394117721Speterrepository using @sc{rsh}. It specifies the name of 13942102840Speterthe program to start on the server side (and any 13943102840Speternecessary arguments) when accessing a remote repository 13944102840Speterusing the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 13945102840SpeterThe default value for @code{:ext:} and @code{:server:} is @code{cvs}; 13946102840Speterthe default value for @code{:fork:} is the name used to run the client. 13947102840Speter@pxref{Connecting via rsh} 1394817721Speter 1394917721Speter@item $CVS_PASSFILE 1395017721SpeterUsed in client-server mode when accessing the @code{cvs 1395117721Speterlogin server}. Default value is @file{$HOME/.cvspass}. 1395217721Speter@pxref{Password authentication client} 1395317721Speter 1395417721Speter@item $CVS_CLIENT_PORT 13955128266SpeterUsed in client-server mode to set the port to use when accessing the server 13956128266Spetervia Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 13957128266Speterif the port is not specified in the CVSROOT. 1395881404Speter@pxref{Remote repositories} 1395917721Speter 1396032785Speter@cindex CVS_RCMD_PORT, environment variable 1396117721Speter@item $CVS_RCMD_PORT 1396217721SpeterUsed in client-server mode. If set, specifies the port 1396317721Speternumber to be used when accessing the @sc{rcmd} demon on 1396417721Speterthe server side. (Currently not used for Unix clients). 1396517721Speter 1396632785Speter@cindex CVS_CLIENT_LOG, environment variable 1396717721Speter@item $CVS_CLIENT_LOG 1396817721SpeterUsed for debugging only in client-server 1396966525Spetermode. If set, everything sent to the server is logged 1397017721Speterinto @file{@code{$CVS_CLIENT_LOG}.in} and everything 1397166525Spetersent from the server is logged into 1397217721Speter@file{@code{$CVS_CLIENT_LOG}.out}. 1397317721Speter 1397432785Speter@cindex CVS_SERVER_SLEEP, environment variable 1397517721Speter@item $CVS_SERVER_SLEEP 1397617721SpeterUsed only for debugging the server side in 1397717721Speterclient-server mode. If set, delays the start of the 1397832785Speterserver child process the specified amount of 1397917721Speterseconds so that you can attach to it with a debugger. 1398017721Speter 1398132785Speter@cindex CVS_IGNORE_REMOTE_ROOT, environment variable 1398217721Speter@item $CVS_IGNORE_REMOTE_ROOT 1398354427SpeterFor @sc{cvs} 1.10 and older, setting this variable 1398454427Speterprevents @sc{cvs} from overwriting the @file{CVS/Root} 1398554427Speterfile when the @samp{-d} global option is specified. 1398654427SpeterLater versions of @sc{cvs} do not rewrite 1398766525Speter@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 1398854427Spetereffect. 1398917721Speter 1399032785Speter@cindex COMSPEC, environment variable 1399117721Speter@item $COMSPEC 1399217721SpeterUsed under OS/2 only. It specifies the name of the 1399317721Spetercommand interpreter and defaults to @sc{cmd.exe}. 1399417721Speter 1399532785Speter@cindex TMPDIR, environment variable 1399625839Speter@item $TMPDIR 1399732785Speter@cindex TMP, environment variable 1399825839Speter@itemx $TMP 1399932785Speter@cindex TEMP, environment variable 1400025839Speter@itemx $TEMP 1400166525Speter@cindex Temporary files, location of 1400232785Speter@c This is quite nuts. We don't talk about tempnam 1400332785Speter@c or mkstemp which we sometimes use. The discussion 1400432785Speter@c of "Global options" is semi-incoherent. 1400532785Speter@c I'm not even sure those are the only inaccuracies. 1400632785Speter@c Furthermore, the conventions are 1400725839Speter@c pretty crazy and they should be simplified. 1400832785SpeterDirectory in which temporary files are located. 1400932785SpeterThe @sc{cvs} server uses 1401025839Speter@code{TMPDIR}. @xref{Global options}, for a 1401125839Speterdescription of how to specify this. 1401225839SpeterSome parts of @sc{cvs} will always use @file{/tmp} (via 1401325839Speterthe @code{tmpnam} function provided by the system). 1401417721Speter 1401525839SpeterOn Windows NT, @code{TMP} is used (via the @code{_tempnam} 1401625839Speterfunction provided by the system). 1401725839Speter 1401825839SpeterThe @code{patch} program which is used by the @sc{cvs} 1401925839Speterclient uses @code{TMPDIR}, and if it is not set, uses 1402032785Speter@file{/tmp} (at least with GNU patch 2.1). Note that 1402132785Speterif your server and client are both running @sc{cvs} 1402232785Speter1.9.10 or later, @sc{cvs} will not invoke an external 1402332785Speter@code{patch} program. 1402417721Speter@end table 1402517721Speter 1402632785Speter@node Compatibility 1402732785Speter@appendix Compatibility between CVS Versions 1402817721Speter 1402932785Speter@cindex CVS, versions of 1403066525Speter@cindex Versions, of CVS 1403166525Speter@cindex Compatibility, between CVS versions 1403232785Speter@c We don't mention versions older than CVS 1.3 1403332785Speter@c on the theory that it would clutter it up for the vast 1403432785Speter@c majority of people, who don't have anything that old. 1403532785Speter@c 1403632785SpeterThe repository format is compatible going back to 1403732785Speter@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 1403832785Speteryou have copies of @sc{cvs} 1.6 or older and you want 1403932785Speterto use the optional developer communication features. 1404032785Speter@c If you "cvs rm" and commit using 1.3, then you'll 1404132785Speter@c want to run "rcs -sdead <file,v>" on each of the 1404232785Speter@c files in the Attic if you then want 1.5 and 1404332785Speter@c later to recognize those files as dead (I think the 1404432785Speter@c symptom if this is not done is that files reappear 1404532785Speter@c in joins). (Wait: the above will work but really to 1404632785Speter@c be strictly correct we should suggest checking 1404732785Speter@c in a new revision rather than just changing the 1404832785Speter@c state of the head revision, shouldn't we?). 1404932785Speter@c The old convert.sh script was for this, but it never 1405032785Speter@c did get updated to reflect use of the RCS "dead" 1405132785Speter@c state. 1405232785Speter@c Note: this is tricky to document without confusing 1405332785Speter@c people--need to carefully say what CVS version we 1405444852Speter@c are talking about and keep in mind the distinction 1405532785Speter@c between a 1405632785Speter@c repository created with 1.3 and on which one now 1405732785Speter@c uses 1.5+, and a repository on which one wants to 1405832785Speter@c use both versions side by side (e.g. during a 1405932785Speter@c transition period). 1406032785Speter@c Wait, can't CVS just detect the case in which a file 1406132785Speter@c is in the Attic but the head revision is not dead? 1406232785Speter@c Not sure whether this should produce a warning or 1406332785Speter@c something, and probably needs further thought, but 1406432785Speter@c it would appear that the situation can be detected. 1406544852Speter@c 1406632785Speter@c We might want to separate out the 1.3 compatibility 1406732785Speter@c section (for repository & working directory) from the 1406832785Speter@c rest--that might help avoid confusing people who 1406932785Speter@c are upgrading (for example) from 1.6 to 1.8. 1407032785Speter@c 1407132785Speter@c A minor incompatibility is if a current version of CVS 1407232785Speter@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 1407332785Speter@c see this as if there is no tag. Seems to me this is 1407432785Speter@c too obscure to mention. 1407517721Speter 1407632785SpeterThe working directory format is compatible going back 1407732785Speterto @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 1407832785Speterand @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 1407932785Spetera working directory checked out with @sc{cvs} 1.3, 1408032785Speter@sc{cvs} will convert it, but to go back to @sc{cvs} 1408132785Speter1.3 you need to check out a new working directory with 1408232785Speter@sc{cvs} 1.3. 1408317721Speter 1408432785SpeterThe remote protocol is interoperable going back to @sc{cvs} 1.5, but no 1408532785Speterfurther (1.5 was the first official release with the remote protocol, 1408632785Speterbut some older versions might still be floating around). In many 1408732785Spetercases you need to upgrade both the client and the server to take 14088130303Speteradvantage of new features and bug fixes, however. 1408932785Speter 1409032785Speter@c Perhaps should be saying something here about the 1409132785Speter@c "D" lines in Entries (written by CVS 1.9; 1.8 and 1409232785Speter@c older don't use them). These are supposed to be 1409332785Speter@c compatible in both directions, but I'm not sure 1409432785Speter@c they quite are 100%. One common gripe is if you 1409532785Speter@c "rm -r" a directory and 1.9 gets confused, as it 1409632785Speter@c still sees it in Entries. That one is fixed in 1409732785Speter@c (say) 1.9.6. Someone else reported problems with 1409832785Speter@c starting with a directory which was checked out with 1409932785Speter@c an old version, and then using a new version, and 1410032785Speter@c some "D" lines appeared, but not for every 1410132785Speter@c directory, causing some directories to be skipped. 1410232785Speter@c They weren't sure how to reproduce this, though. 1410332785Speter 1410417721Speter@c --------------------------------------------------------------------- 1410517721Speter@node Troubleshooting 1410617721Speter@appendix Troubleshooting 1410717721Speter 1410826801SpeterIf you are having trouble with @sc{cvs}, this appendix 1410926801Spetermay help. If there is a particular error message which 1411026801Speteryou are seeing, then you can look up the message 1411126801Speteralphabetically. If not, you can look through the 1411226801Spetersection on other problems to see if your problem is 1411326801Spetermentioned there. 1411426801Speter 1411517721Speter@menu 1411625839Speter* Error messages:: Partial list of CVS errors 1411734461Speter* Connection:: Trouble making a connection to a CVS server 1411826801Speter* Other problems:: Problems not readily listed by error message 1411917721Speter@end menu 1412017721Speter 1412117721Speter@ignore 1412217721Speter@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1412317721Speter@c @node Bad administrative files 1412417721Speter@appendixsec Bad administrative files 1412517721Speter 1412617721Speter@c -- Give hints on how to fix them 1412717721Speter@end ignore 1412817721Speter 1412925839Speter@node Error messages 1413025839Speter@appendixsec Partial list of error messages 1413117721Speter 1413225839SpeterHere is a partial list of error messages that you may 1413325839Spetersee from @sc{cvs}. It is not a complete list---@sc{cvs} 1413425839Speteris capable of printing many, many error messages, often 1413525839Speterwith parts of them supplied by the operating system, 1413625839Speterbut the intention is to list the common and/or 1413725839Speterpotentially confusing error messages. 1413817721Speter 1413925839SpeterThe messages are alphabetical, but introductory text 1414025839Spetersuch as @samp{cvs update: } is not considered in 1414125839Speterordering them. 1414217721Speter 1414325839SpeterIn some cases the list includes messages printed by old 1414425839Speterversions of @sc{cvs} (partly because users may not be 1414525839Spetersure which version of @sc{cvs} they are using at any 1414625839Speterparticular moment). 1414732785Speter@c If we want to start retiring messages, perhaps we 1414832785Speter@c should pick a cutoff version (for example, no more 1414932785Speter@c messages which are specific to versions before 1.9) 1415032785Speter@c and then move the old messages to an "old messages" 1415132785Speter@c node rather than deleting them completely. 1415217721Speter 1415325839Speter@table @code 1415425839Speter@c FIXME: What is the correct way to format a multiline 1415525839Speter@c error message here? Maybe @table is the wrong 1415625839Speter@c choice? Texinfo gurus? 14157102840Speter@item @var{file}:@var{line}: Assertion '@var{text}' failed 14158102840SpeterThe exact format of this message may vary depending on 14159102840Speteryour system. It indicates a bug in @sc{cvs}, which can 14160102840Speterbe handled as described in @ref{BUGS}. 14161102840Speter 1416232785Speter@item cvs @var{command}: authorization failed: server @var{host} rejected access 1416332785SpeterThis is a generic response when trying to connect to a 1416432785Speterpserver server which chooses not to provide a 1416532785Speterspecific reason for denying authorization. Check that 1416632785Speterthe username and password specified are correct and 1416766525Speterthat the @code{CVSROOT} specified is allowed by @samp{--allow-root} 1416866525Speterin @file{inetd.conf}. See @ref{Password authenticated}. 1416932785Speter 1417044852Speter@item cvs @var{command}: conflict: removed @var{file} was modified by second party 1417144852SpeterThis message indicates that you removed a file, and 1417244852Spetersomeone else modified it. To resolve the conflict, 1417344852Speterfirst run @samp{cvs add @var{file}}. If desired, look 1417444852Speterat the other party's modification to decide whether you 1417544852Speterstill want to remove it. If you don't want to remove 1417644852Speterit, stop here. If you do want to remove it, proceed 1417744852Speterwith @samp{cvs remove @var{file}} and commit your 1417844852Speterremoval. 1417944852Speter@c Tests conflicts2-142b* in sanity.sh test for this. 1418044852Speter 1418125839Speter@item cannot change permissions on temporary directory 1418225839Speter@example 1418325839SpeterOperation not permitted 1418425839Speter@end example 1418525839SpeterThis message has been happening in a non-reproducible, 1418625839Speteroccasional way when we run the client/server testsuite, 1418725839Speterboth on Red Hat Linux 3.0.3 and 4.1. We haven't been 1418825839Speterable to figure out what causes it, nor is it known 14189130303Speterwhether it is specific to Linux (or even to this 1419025839Speterparticular machine!). If the problem does occur on 1419125839Speterother unices, @samp{Operation not permitted} would be 1419225839Speterlikely to read @samp{Not owner} or whatever the system 1419325839Speterin question uses for the unix @code{EPERM} error. If 1419425839Speteryou have any information to add, please let us know as 1419525839Speterdescribed in @ref{BUGS}. If you experience this error 1419625839Speterwhile using @sc{cvs}, retrying the operation which 1419725839Speterproduced it should work fine. 1419832785Speter@c This has been seen in a variety of tests, including 1419932785Speter@c multibranch-2, multibranch-5, and basic1-24-rm-rm, 1420032785Speter@c so it doesn't seem particularly specific to any one 1420132785Speter@c test. 1420217721Speter 1420354427Speter@item cvs [server aborted]: Cannot check out files into the repository itself 1420454427SpeterThe obvious cause for this message (especially for 1420554427Speternon-client/server @sc{cvs}) is that the @sc{cvs} root 1420654427Speteris, for example, @file{/usr/local/cvsroot} and you try 1420754427Speterto check out files when you are in a subdirectory, such 1420854427Speteras @file{/usr/local/cvsroot/test}. However, there is a 1420954427Spetermore subtle cause, which is that the temporary 1421054427Speterdirectory on the server is set to a subdirectory of the 1421154427Speterroot (which is also not allowed). If this is the 1421254427Speterproblem, set the temporary directory to somewhere else, 1421354427Speterfor example @file{/var/tmp}; see @code{TMPDIR} in 1421454427Speter@ref{Environment variables}, for how to set the 1421554427Spetertemporary directory. 1421654427Speter 14217102840Speter@item cannot commit files as 'root' 14218102840SpeterSee @samp{'root' is not allowed to commit files}. 14219102840Speter 1422025839Speter@c For one example see basica-1a10 in the testsuite 1422125839Speter@c For another example, "cvs co ." on NT; see comment 1422225839Speter@c at windows-NT/filesubr.c (expand_wild). 1422326065Speter@c For another example, "cvs co foo/bar" where foo exists. 1422425839Speter@item cannot open CVS/Entries for reading: No such file or directory 1422525839SpeterThis generally indicates a @sc{cvs} internal error, and 1422625839Spetercan be handled as with other @sc{cvs} bugs 1422725839Speter(@pxref{BUGS}). Usually there is a workaround---the 1422825839Speterexact nature of which would depend on the situation but 1422925839Speterwhich hopefully could be figured out. 1423017721Speter 1423132785Speter@c This is more obscure than it might sound; it only 1423232785Speter@c happens if you run "cvs init" from a directory which 1423332785Speter@c contains a CVS/Root file at the start. 1423432785Speter@item cvs [init aborted]: cannot open CVS/Root: No such file or directory 1423532785SpeterThis message is harmless. Provided it is not 1423632785Speteraccompanied by other errors, the operation has 1423732785Spetercompleted successfully. This message should not occur 1423832785Speterwith current versions of @sc{cvs}, but it is documented 1423932785Speterhere for the benefit of @sc{cvs} 1.9 and older. 1424032785Speter 14241102840Speter@item cvs server: cannot open /root/.cvsignore: Permission denied 14242102840Speter@itemx cvs [server aborted]: can't chdir(/root): Permission denied 14243102840SpeterSee @ref{Connection}. 14244102840Speter 1424526065Speter@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 1424626065SpeterThis message has been reported as intermittently 1424781404Speterhappening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 1424826065Speterunknown; if you know more about what causes it, let us 1424926065Speterknow as described in @ref{BUGS}. 1425026065Speter 1425132785Speter@item cvs [@var{command} aborted]: cannot start server via rcmd 1425232785SpeterThis, unfortunately, is a rather nonspecific error 1425332785Spetermessage which @sc{cvs} 1.9 will print if you are 1425432785Speterrunning the @sc{cvs} client and it is having trouble 1425532785Speterconnecting to the server. Current versions of @sc{cvs} 1425632785Spetershould print a much more specific error message. If 1425732785Speteryou get this message when you didn't mean to run the 1425832785Speterclient at all, you probably forgot to specify 1425932785Speter@code{:local:}, as described in @ref{Repository}. 1426032785Speter 1426132785Speter@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 1426281404Speter@sc{cvs} 1.9 and older will print this message 1426332785Speterwhen trying to check in a binary file if 1426432785Speter@sc{rcs} is not correctly installed. Re-read the 1426532785Speterinstructions that came with your @sc{rcs} distribution 1426632785Speterand the @sc{install} file in the @sc{cvs} 1426732785Speterdistribution. Alternately, upgrade to a current 1426832785Speterversion of @sc{cvs}, which checks in files itself 1426932785Speterrather than via @sc{rcs}. 1427032785Speter 1427132785Speter@item cvs checkout: could not check out @var{file} 1427281404SpeterWith @sc{cvs} 1.9, this can mean that the @code{co} program 1427332785Speter(part of @sc{rcs}) returned a failure. It should be 1427432785Speterpreceded by another error message, however it has been 1427532785Speterobserved without another error message and the cause is 1427681404Speternot well-understood. With the current version of @sc{cvs}, 1427732785Speterwhich does not run @code{co}, if this message occurs 1427881404Speterwithout another error message, it is definitely a @sc{cvs} 1427932785Speterbug (@pxref{BUGS}). 1428032785Speter@c My current suspicion is that the RCS in the rcs (not 1428132785Speter@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 1428232785Speter@c CD is bad (remains to be confirmed). 1428332785Speter@c There is also a report of something which looks 1428432785Speter@c very similar on SGI, Irix 5.2, so I dunno. 1428532785Speter 1428632785Speter@item cvs [login aborted]: could not find out home directory 1428732785SpeterThis means that you need to set the environment 1428881404Spetervariables that @sc{cvs} uses to locate your home directory. 1428966525SpeterSee the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 1429032785Speter@ref{Environment variables}. 1429132785Speter 1429232785Speter@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 1429381404Speter@sc{cvs} 1.9 and older will print this message if there was 1429432785Spetera problem finding the @code{rcsmerge} program. Make 1429532785Spetersure that it is in your @code{PATH}, or upgrade to a 1429681404Spetercurrent version of @sc{cvs}, which does not require 1429732785Speteran external @code{rcsmerge} program. 1429832785Speter 1429925839Speter@item cvs [update aborted]: could not patch @var{file}: No such file or directory 1430025839SpeterThis means that there was a problem finding the 1430125839Speter@code{patch} program. Make sure that it is in your 1430225839Speter@code{PATH}. Note that despite appearances the message 1430325839Speteris @emph{not} referring to whether it can find @var{file}. 1430432785SpeterIf both the client and the server are running a current 1430532785Speterversion of @sc{cvs}, then there is no need for an 1430632785Speterexternal patch program and you should not see this 1430732785Spetermessage. But if either client or server is running 1430832785Speter@sc{cvs} 1.9, then you need @code{patch}. 1430917721Speter 1431025839Speter@item cvs update: could not patch @var{file}; will refetch 1431125839SpeterThis means that for whatever reason the client was 1431225839Speterunable to apply a patch that the server sent. The 1431325839Spetermessage is nothing to be concerned about, because 1431425839Speterinability to apply the patch only slows things down and 1431525839Speterhas no effect on what @sc{cvs} does. 1431625839Speter@c xref to update output. Or File status? 1431725839Speter@c Or some place else that 1431825839Speter@c explains this whole "patch"/P/Needs Patch thing? 1431917721Speter 1432025839Speter@item dying gasps from @var{server} unexpected 1432132785SpeterThere is a known bug in the server for @sc{cvs} 1.9.18 1432232785Speterand older which can cause this. For me, this was 1432332785Speterreproducible if I used the @samp{-t} global option. It 1432432785Speterwas fixed by Andy Piper's 14 Nov 1997 change to 1432532785Spetersrc/filesubr.c, if anyone is curious. 1432632785SpeterIf you see the message, 1432725839Speteryou probably can just retry the operation which failed, 1432825839Speteror if you have discovered information concerning its 1432925839Spetercause, please let us know as described in @ref{BUGS}. 1433017721Speter 1433125839Speter@item end of file from server (consult above messages if any) 1433225839SpeterThe most common cause for this message is if you are 14333177391Sobrienusing an external @code{rsh} or @code{ssh} program and it exited with 1433425839Speteran error. In this case the @code{rsh} program should 1433525839Speterhave printed a message, which will appear before the 1433625839Speterabove message. For more information on setting up a 1433725839Speter@sc{cvs} client and server, see @ref{Remote repositories}. 1433825839Speter 1433954427Speter@item cvs [update aborted]: EOF in key in RCS file @var{file},v 1434054427Speter@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 1434154427SpeterThis means that there is a syntax error in the given 1434254427Speter@sc{rcs} file. Note that this might be true even if @sc{rcs} can 1434354427Speterread the file OK; @sc{cvs} does more error checking of 1434454427Spetererrors in the RCS file. That is why you may see this 1434554427Spetermessage when upgrading from @sc{cvs} 1.9 to @sc{cvs} 1434654427Speter1.10. The likely cause for the original corruption is 1434754427Speterhardware, the operating system, or the like. Of 1434854427Spetercourse, if you find a case in which @sc{cvs} seems to 1434954427Spetercorrupting the file, by all means report it, 1435054427Speter(@pxref{BUGS}). 1435154427SpeterThere are quite a few variations of this error message, 1435254427Speterdepending on exactly where in the @sc{rcs} file @sc{cvs} 1435354427Speterfinds the syntax error. 1435454427Speter 1435525839Speter@cindex mkmodules 1435625839Speter@item cvs commit: Executing 'mkmodules' 1435725839SpeterThis means that your repository is set up for a version 1435825839Speterof @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 1435925839Speter1.8 or later, the above message will be preceded by 1436025839Speter 1436117721Speter@example 1436225839Spetercvs commit: Rebuilding administrative file database 1436317721Speter@end example 1436417721Speter 1436525839SpeterIf you see both messages, the database is being rebuilt 1436625839Spetertwice, which is unnecessary but harmless. If you wish 1436725839Speterto avoid the duplication, and you have no versions of 1436825839Speter@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 1436925839Speterevery place it appears in your @code{modules} 1437025839Speterfile. For more information on the @code{modules} file, 1437125839Spetersee @ref{modules}. 1437217721Speter 1437354427Speter@c This message comes from "co", and I believe is 1437432785Speter@c possible only with older versions of CVS which call 1437532785Speter@c co. The problem with being able to create the bogus 1437632785Speter@c RCS file still exists, though (and I think maybe 1437732785Speter@c there is a different symptom(s) now). 1437832785Speter@c FIXME: Would be nice to have a more exact wording 1437932785Speter@c for this message. 1438032785Speter@item missing author 1438132785SpeterTypically this can happen if you created an RCS file 1438281404Speterwith your username set to empty. @sc{cvs} will, bogusly, 1438332785Spetercreate an illegal RCS file with no value for the author 1438432785Speterfield. The solution is to make sure your username is 1438532785Speterset to a non-empty value and re-create the RCS file. 1438632785Speter@c "make sure your username is set" is complicated in 1438732785Speter@c and of itself, as there are the environment 1438832785Speter@c variables the system login name, &c, and it depends 1438932785Speter@c on the version of CVS. 1439032785Speter 1439154427Speter@item cvs [checkout aborted]: no such tag @var{tag} 1439254427SpeterThis message means that @sc{cvs} isn't familiar with 1439354427Speterthe tag @var{tag}. Usually this means that you have 1439454427Spetermistyped a tag name; however there are (relatively 1439554427Speterobscure) cases in which @sc{cvs} will require you to 1439654427Speter@c Search sanity.sh for "no such tag" to see some of 1439754427Speter@c the relatively obscure cases. 1439854427Spetertry a few other @sc{cvs} commands involving that tag, 1439954427Speterbefore you find one which will cause @sc{cvs} to update 14400128266Speter@cindex CVSROOT/val-tags file, forcing tags into 14401128266Speter@cindex val-tags file, forcing tags into 1440254427Speterthe @file{val-tags} file; see discussion of val-tags in 1440354427Speter@ref{File permissions}. You only need to worry about 1440454427Speterthis once for a given tag; when a tag is listed in 1440554427Speter@file{val-tags}, it stays there. Note that using 1440654427Speter@samp{-f} to not require tag matches does not override 1440754427Speterthis check; see @ref{Common options}. 1440854427Speter 1440932785Speter@item *PANIC* administration files missing 1441032785SpeterThis typically means that there is a directory named 1441181404Speter@sc{cvs} but it does not contain the administrative files 1441281404Speterwhich @sc{cvs} puts in a CVS directory. If the problem is 1441332785Speterthat you created a CVS directory via some mechanism 1441481404Speterother than @sc{cvs}, then the answer is simple, use a name 1441581404Speterother than @sc{cvs}. If not, it indicates a @sc{cvs} bug 1441632785Speter(@pxref{BUGS}). 1441732785Speter 1441826801Speter@item rcs error: Unknown option: -x,v/ 1441926801SpeterThis message will be followed by a usage message for 1442026801Speter@sc{rcs}. It means that you have an old version of 1442126801Speter@sc{rcs} (probably supplied with your operating 1442266525Spetersystem), as well as an old version of @sc{cvs}. 1442366525Speter@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 1442466525Speterlater; current versions of @sc{cvs} do not run @sc{rcs} programs. 1442526801Speter@c For more information on installing @sc{cvs}, see 1442626801Speter@c (FIXME: where? it depends on whether you are 1442726801Speter@c getting binaries or sources or what). 1442832785Speter@c The message can also say "ci error" or something 1442932785Speter@c instead of "rcs error", I suspect. 1443026801Speter 1443125839Speter@item cvs [server aborted]: received broken pipe signal 14432128266SpeterThis message can be caused by a loginfo program that fails to 14433128266Speterread all of the log information from its standard input. 14434128266SpeterIf you find it happening in any other circumstances, 14435128266Speterplease let us know as described in @ref{BUGS}. 1443625839Speter 14437102840Speter@item 'root' is not allowed to commit files 14438102840SpeterWhen committing a permanent change, @sc{cvs} makes a log entry of 14439102840Speterwho committed the change. If you are committing the change logged 14440102840Speterin as "root" (not under "su" or other root-priv giving program), 14441102840Speter@sc{cvs} cannot determine who is actually making the change. 14442102840SpeterAs such, by default, @sc{cvs} disallows changes to be committed by users 14443107484Speterlogged in as "root". (You can disable this option by passing the 14444107484Speter@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 14445107484SpeterOn some systems this means editing the appropriate @file{config.h} file 14446107484Speterbefore building @sc{cvs}.) 14447102840Speter 14448175261Sobrien@item Terminated with fatal signal 11 14449175261SobrienThis message usually indicates that @sc{cvs} (the server, if you're 14450175261Sobrienusing client/server mode) has run out of (virtual) memory. 14451175261SobrienAlthough @sc{cvs} tries to catch the error and issue a more meaningful 14452175261Sobrienmessage, there are many circumstances where that is not possible. 14453175261SobrienIf you appear to have lots of memory available to the system, 14454175261Sobrienthe problem is most likely that you're running into a system-wide 14455175261Sobrienlimit on the amount of memory a single process can use or a 14456175261Sobriensimilar process-specific limit. 14457175261SobrienThe mechanisms for displaying and setting such limits vary from 14458175261Sobriensystem to system, so you'll have to consult an expert for your 14459175261Sobrienparticular system if you don't know how to do that. 14460175261Sobrien 1446132785Speter@item Too many arguments! 1446232785SpeterThis message is typically printed by the @file{log.pl} 1446332785Speterscript which is in the @file{contrib} directory in the 1446432785Speter@sc{cvs} source distribution. In some versions of 1446532785Speter@sc{cvs}, @file{log.pl} has been part of the default 1446632785Speter@sc{cvs} installation. The @file{log.pl} script gets 1446732785Spetercalled from the @file{loginfo} administrative file. 1446832785SpeterCheck that the arguments passed in @file{loginfo} match 1446932785Speterwhat your version of @file{log.pl} expects. In 1447032785Speterparticular, the @file{log.pl} from @sc{cvs} 1.3 and 14471130303Speterolder expects the log file as an argument whereas the 1447232785Speter@file{log.pl} from @sc{cvs} 1.5 and newer expects the 14473130303Speterlog file to be specified with a @samp{-f} option. Of 1447432785Spetercourse, if you don't need @file{log.pl} you can just 1447532785Spetercomment it out of @file{loginfo}. 1447632785Speter 1447754427Speter@item cvs [update aborted]: unexpected EOF reading @var{file},v 1447854427SpeterSee @samp{EOF in key in RCS file}. 1447954427Speter 1448054427Speter@item cvs [login aborted]: unrecognized auth response from @var{server} 1448154427SpeterThis message typically means that the server is not set 1448254427Speterup properly. For example, if @file{inetd.conf} points 1448354427Speterto a nonexistent cvs executable. To debug it further, 1448454427Speterfind the log file which inetd writes 1448554427Speter(@file{/var/log/messages} or whatever inetd uses on 1448654427Speteryour system). For details, see @ref{Connection}, and 1448754427Speter@ref{Password authentication server}. 1448854427Speter 1448925839Speter@item cvs commit: Up-to-date check failed for `@var{file}' 1449025839SpeterThis means that someone else has committed a change to 1449125839Speterthat file since the last time that you did a @code{cvs 1449225839Speterupdate}. So before proceeding with your @code{cvs 1449381404Spetercommit} you need to @code{cvs update}. @sc{cvs} will merge 1449425839Speterthe changes that you made and the changes that the 1449525839Speterother person made. If it does not detect any conflicts 1449666525Speterit will report @samp{M @var{file}} and you are ready 1449725839Speterto @code{cvs commit}. If it detects conflicts it will 1449866525Speterprint a message saying so, will report @samp{C @var{file}}, 1449925839Speterand you need to manually resolve the 1450025839Speterconflict. For more details on this process see 1450125839Speter@ref{Conflicts example}. 1450225839Speter 1450325839Speter@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 1450425839Speter@example 1450525839SpeterOnly one of [exEX3] allowed 1450625839Speter@end example 1450725839SpeterThis indicates a problem with the installation of 1450825839Speter@code{diff3} and @code{rcsmerge}. Specifically 1450925839Speter@code{rcsmerge} was compiled to look for GNU diff3, but 1451025839Speterit is finding unix diff3 instead. The exact text of 1451125839Speterthe message will vary depending on the system. The 1451232785Spetersimplest solution is to upgrade to a current version of 1451332785Speter@sc{cvs}, which does not rely on external 1451432785Speter@code{rcsmerge} or @code{diff3} programs. 1451525839Speter 1451632785Speter@item warning: unrecognized response `@var{text}' from cvs server 1451732785SpeterIf @var{text} contains a valid response (such as 1451832785Speter@samp{ok}) followed by an extra carriage return 1451932785Spetercharacter (on many systems this will cause the second 1452032785Speterpart of the message to overwrite the first part), then 1452132785Speterit probably means that you are using the @samp{:ext:} 1452232785Speteraccess method with a version of rsh, such as most 1452332785Speternon-unix rsh versions, which does not by default 1452432785Speterprovide a transparent data stream. In such cases you 1452532785Speterprobably want to try @samp{:server:} instead of 1452632785Speter@samp{:ext:}. If @var{text} is something else, this 1452781404Spetermay signify a problem with your @sc{cvs} server. 1452832785SpeterDouble-check your installation against the instructions 1452981404Speterfor setting up the @sc{cvs} server. 1453032785Speter@c FIXCVS: should be printing CR as \r or \015 or some 1453132785Speter@c such, probably. 1453232785Speter 1453354427Speter@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 1453454427SpeterThis is a normal message, not an error. See 1453554427Speter@ref{Concurrency}, for more details. 1453654427Speter 1453725839Speter@item cvs commit: warning: editor session failed 1453866525Speter@cindex Exit status, of editor 1453925839SpeterThis means that the editor which @sc{cvs} is using exits with a nonzero 1454025839Speterexit status. Some versions of vi will do this even when there was not 1454125839Spetera problem editing the file. If so, point the 1454266525Speter@code{CVSEDITOR} environment variable to a small script 1454325839Spetersuch as: 1454425839Speter 1454525839Speter@example 1454625839Speter#!/bin/sh 1454725839Spetervi $* 1454825839Speterexit 0 1454925839Speter@end example 1455025839Speter 14551175261Sobrien@item cvs update: warning: @var{file} was lost 14552175261SobrienThis means that the working copy of @var{file} has been deleted 14553175261Sobrienbut it has not been removed from @sc{cvs}. 14554175261SobrienThis is nothing to be concerned about, 14555175261Sobrienthe update will just recreate the local file from the repository. 14556175261Sobrien(This is a convenient way to discard local changes to a file: 14557175261Sobrienjust delete it and then run @code{cvs update}.) 14558175261Sobrien 14559175261Sobrien@item cvs update: warning: @var{file} is not (any longer) pertinent 14560175261SobrienThis means that the working copy of @var{file} has been deleted, 14561175261Sobrienit has not been removed from @sc{cvs} in the current working directory, 14562175261Sobrienbut it has been removed from @sc{cvs} in some other working directory. 14563175261SobrienThis is nothing to be concerned about, 14564175261Sobrienthe update would have removed the local file anyway. 14565175261Sobrien 1456625839Speter@end table 1456725839Speter 1456834461Speter@node Connection 1456934461Speter@appendixsec Trouble making a connection to a CVS server 1457034461Speter 1457134461SpeterThis section concerns what to do if you are having 1457234461Spetertrouble making a connection to a @sc{cvs} server. If 1457334461Speteryou are running the @sc{cvs} command line client 1457434461Speterrunning on Windows, first upgrade the client to 1457534461Speter@sc{cvs} 1.9.12 or later. The error reporting in 1457634461Speterearlier versions provided much less information about 1457734461Speterwhat the problem was. If the client is non-Windows, 1457834461Speter@sc{cvs} 1.9 should be fine. 1457934461Speter 1458034461SpeterIf the error messages are not sufficient to track down 1458134461Speterthe problem, the next steps depend largely on which 1458234461Speteraccess method you are using. 1458334461Speter 1458434461Speter@table @code 1458534461Speter@cindex :ext:, troubleshooting 1458634461Speter@item :ext: 1458734461SpeterTry running the rsh program from the command line. For 1458834461Speterexample: "rsh servername cvs -v" should print @sc{cvs} 1458934461Speterversion information. If this doesn't work, you need to 1459034461Speterfix it before you can worry about @sc{cvs} problems. 1459134461Speter 1459234461Speter@cindex :server:, troubleshooting 1459334461Speter@item :server: 1459434461SpeterYou don't need a command line rsh program to use this 1459534461Speteraccess method, but if you have an rsh program around, 1459634461Speterit may be useful as a debugging tool. Follow the 1459734461Speterdirections given for :ext:. 1459834461Speter 1459934461Speter@cindex :pserver:, troubleshooting 1460034461Speter@item :pserver: 1460181404SpeterErrors along the lines of "connection refused" typically indicate 1460281404Speterthat inetd isn't even listening for connections on port 2401 14603102840Speterwhereas errors like "connection reset by peer", 14604128266Speter"received broken pipe signal", "recv() from server: EOF", 14605128266Speteror "end of file from server" 14606102840Spetertypically indicate that inetd is listening for 1460781404Speterconnections but is unable to start @sc{cvs} (this is frequently 14608128266Spetercaused by having an incorrect path in @file{inetd.conf} 14609128266Speteror by firewall software rejecting the connection). 1461081404Speter"unrecognized auth response" errors are caused by a bad command 1461181404Speterline in @file{inetd.conf}, typically an invalid option or forgetting 1461281404Speterto put the @samp{pserver} command at the end of the line. 1461381404SpeterAnother less common problem is invisible control characters that 1461481404Speteryour editor "helpfully" added without you noticing. 1461581404Speter 1461634461SpeterOne good debugging tool is to "telnet servername 1461734461Speter2401". After connecting, send any text (for example 1461834461Speter"foo" followed by return). If @sc{cvs} is working 1461934461Spetercorrectly, it will respond with 1462034461Speter 1462134461Speter@example 1462234461Spetercvs [pserver aborted]: bad auth protocol start: foo 1462334461Speter@end example 1462434461Speter 1462581404SpeterIf instead you get: 1462681404Speter 1462781404Speter@example 1462881404SpeterUsage: cvs [cvs-options] command [command-options-and-arguments] 1462981404Speter... 1463081404Speter@end example 1463181404Speter 14632102840Speter@noindent 1463381404Speterthen you're missing the @samp{pserver} command at the end of the 1463481404Speterline in @file{inetd.conf}; check to make sure that the entire command 1463581404Speteris on one line and that it's complete. 1463681404Speter 1463781404SpeterLikewise, if you get something like: 1463881404Speter 1463981404Speter@example 1464081404SpeterUnknown command: `pserved' 1464181404Speter 1464281404SpeterCVS commands are: 1464381404Speter add Add a new file/directory to the repository 1464481404Speter... 1464581404Speter@end example 1464681404Speter 14647102840Speter@noindent 1464881404Speterthen you've misspelled @samp{pserver} in some way. If it isn't 1464981404Speterobvious, check for invisible control characters (particularly 1465081404Spetercarriage returns) in @file{inetd.conf}. 1465181404Speter 1465281404SpeterIf it fails to work at all, then make sure inetd is working 1465366525Speterright. Change the invocation in @file{inetd.conf} to run the 1465434461Speterecho program instead of cvs. For example: 1465534461Speter 1465634461Speter@example 1465734461Speter2401 stream tcp nowait root /bin/echo echo hello 1465834461Speter@end example 1465934461Speter 1466034461SpeterAfter making that change and instructing inetd to 1466134461Speterre-read its configuration file, "telnet servername 1466234461Speter2401" should show you the text hello and then the 1466334461Speterserver should close the connection. If this doesn't 1466434461Speterwork, you need to fix it before you can worry about 1466534461Speter@sc{cvs} problems. 1466634461Speter 1466734461SpeterOn AIX systems, the system will often have its own 1466834461Speterprogram trying to use port 2401. This is AIX's problem 1466934461Speterin the sense that port 2401 is registered for use with 1467034461Speter@sc{cvs}. I hear that there is an AIX patch available 1467134461Speterto address this problem. 1467254427Speter 1467354427SpeterAnother good debugging tool is the @samp{-d} 1467454427Speter(debugging) option to inetd. Consult your system 1467554427Speterdocumentation for more information. 1467666525Speter 1467766525SpeterIf you seem to be connecting but get errors like: 1467866525Speter 1467966525Speter@example 1468066525Spetercvs server: cannot open /root/.cvsignore: Permission denied 1468166525Spetercvs [server aborted]: can't chdir(/root): Permission denied 1468266525Speter@end example 1468366525Speter 14684102840Speter@noindent 1468581404Speterthen you probably haven't specified @samp{-f} in @file{inetd.conf}. 14686102840Speter(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 14687102840Speteryour system setting the @code{$HOME} environment variable 14688102840Speterfor programs being run by inetd. In this case, you can either 14689102840Speterhave inetd run a shell script that unsets @code{$HOME} and then runs 14690102840Speter@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 14691102840Speterenvironment.) 1469266525Speter 1469366525SpeterIf you can connect successfully for a while but then can't, 1469466525Speteryou've probably hit inetd's rate limit. 1469566525Speter(If inetd receives too many requests for the same service 1469666525Speterin a short period of time, it assumes that something is wrong 1469766525Speterand temporarily disables the service.) 1469866525SpeterCheck your inetd documentation to find out how to adjust the 1469966525Speterrate limit (some versions of inetd have a single rate limit, 1470066525Speterothers allow you to set the limit for each service separately.) 1470134461Speter@end table 1470234461Speter 1470326801Speter@node Other problems 1470426801Speter@appendixsec Other common problems 1470526801Speter 1470634461SpeterHere is a list of problems which do not fit into the 1470734461Speterabove categories. They are in no particular order. 1470826801Speter 1470926801Speter@itemize @bullet 1471026801Speter@item 1471154427SpeterOn Windows, if there is a 30 second or so delay when 1471254427Speteryou run a @sc{cvs} command, it may mean that you have 1471354427Speteryour home directory set to @file{C:/}, for example (see 1471454427Speter@code{HOMEDRIVE} and @code{HOMEPATH} in 1471581404Speter@ref{Environment variables}). @sc{cvs} expects the home 1471654427Speterdirectory to not end in a slash, for example @file{C:} 1471754427Speteror @file{C:\cvs}. 1471854427Speter@c FIXCVS: CVS should at least detect this and print an 1471954427Speter@c error, presumably. 1472054427Speter 1472154427Speter@item 1472232785SpeterIf you are running @sc{cvs} 1.9.18 or older, and 1472332785Speter@code{cvs update} finds a conflict and tries to 1472426801Spetermerge, as described in @ref{Conflicts example}, but 1472526801Speterdoesn't tell you there were conflicts, then you may 1472632785Speterhave an old version of @sc{rcs}. The easiest solution 1472732785Speterprobably is to upgrade to a current version of 1472832785Speter@sc{cvs}, which does not rely on external @sc{rcs} 1472932785Speterprograms. 1473026801Speter@end itemize 1473126801Speter 1473217721Speter@c --------------------------------------------------------------------- 1473332785Speter@node Credits 1473432785Speter@appendix Credits 1473532785Speter 1473632785Speter@cindex Contributors (manual) 1473732785Speter@cindex Credits (manual) 1473832785SpeterRoland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 1473932785Speterwrote the manual pages which were distributed with 1474032785Speter@sc{cvs} 1.3. Much of their text was copied into this 1474132785Spetermanual. He also read an early draft 1474232785Speterof this manual and contributed many ideas and 1474332785Spetercorrections. 1474432785Speter 1474532785SpeterThe mailing-list @code{info-cvs} is sometimes 1474632785Speterinformative. I have included information from postings 1474732785Spetermade by the following persons: 1474832785SpeterDavid G. Grubbs <@t{dgg@@think.com}>. 1474932785Speter 1475032785SpeterSome text has been extracted from the man pages for 1475132785Speter@sc{rcs}. 1475232785Speter 1475332785SpeterThe @sc{cvs} @sc{faq} by David G. Grubbs has provided 1475432785Speteruseful material. The @sc{faq} is no longer maintained, 1475532785Speterhowever, and this manual is about the closest thing there 1475632785Speteris to a successor (with respect to documenting how to 1475732785Speteruse @sc{cvs}, at least). 1475832785Speter 1475932785SpeterIn addition, the following persons have helped by 1476032785Spetertelling me about mistakes I've made: 1476132785Speter 1476232785Speter@display 1476332785SpeterRoxanne Brunskill <@t{rbrunski@@datap.ca}>, 1476432785SpeterKathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 1476532785SpeterKarl Pingle <@t{pingle@@acuson.com}>, 1476632785SpeterThomas A Peterson <@t{tap@@src.honeywell.com}>, 1476732785SpeterInge Wallin <@t{ingwa@@signum.se}>, 1476832785SpeterDirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 1476932785Speterand Michael Brown <@t{brown@@wi.extrel.com}>. 1477032785Speter@end display 1477132785Speter 1477232785SpeterThe list of contributors here is not comprehensive; for a more 1477332785Spetercomplete list of who has contributed to this manual see 1477432785Speterthe file @file{doc/ChangeLog} in the @sc{cvs} source 1477532785Speterdistribution. 1477632785Speter 1477732785Speter@c --------------------------------------------------------------------- 1477832785Speter@node BUGS 1477932785Speter@appendix Dealing with bugs in CVS or this manual 1478032785Speter 1478132785Speter@cindex Bugs in this manual or CVS 1478232785SpeterNeither @sc{cvs} nor this manual is perfect, and they 1478332785Speterprobably never will be. If you are having trouble 1478432785Speterusing @sc{cvs}, or think you have found a bug, there 1478532785Speterare a number of things you can do about it. Note that 1478632785Speterif the manual is unclear, that can be considered a bug 1478732785Speterin the manual, so these problems are often worth doing 1478832785Spetersomething about as well as problems with @sc{cvs} itself. 1478932785Speter 1479032785Speter@cindex Reporting bugs 1479132785Speter@cindex Bugs, reporting 1479232785Speter@cindex Errors, reporting 1479332785Speter@itemize @bullet 1479432785Speter@item 1479532785SpeterIf you want someone to help you and fix bugs that you 1479632785Speterreport, there are companies which will do that for a 1479781404Speterfee. One such company is: 1479832785Speter 14799128266Speter@cindex Ximbiot 1480032785Speter@cindex Support, getting CVS support 1480132785Speter@example 14802177391SobrienXimbiot LLC 14803177391SobrienSuite 230 14804177391Sobrien200 Diversion St. 14805177391SobrienRochester Hills, MI 48307-6636 14806128266SpeterUSA 14807128266SpeterEmail: info@@ximbiot.com 14808177391SobrienPhone: (248) 835-1260 14809177391SobrienFax: (248) 835-1263 14810128266Speter@url{http://ximbiot.com/} 1481132785Speter 1481232785Speter@end example 1481332785Speter 1481432785Speter@item 1481532785SpeterIf you got @sc{cvs} through a distributor, such as an 1481632785Speteroperating system vendor or a vendor of freeware 1481732785Speter@sc{cd-rom}s, you may wish to see whether the 1481832785Speterdistributor provides support. Often, they will provide 1481932785Speterno support or minimal support, but this may vary from 1482032785Speterdistributor to distributor. 1482132785Speter 1482232785Speter@item 1482332785SpeterIf you have the skills and time to do so, you may wish 1482432785Speterto fix the bug yourself. If you wish to submit your 1482532785Speterfix for inclusion in future releases of @sc{cvs}, see 1482632785Speterthe file @sc{hacking} in the @sc{cvs} source 1482732785Speterdistribution. It contains much more information on the 1482832785Speterprocess of submitting fixes. 1482932785Speter 1483032785Speter@item 14831175261SobrienThere may be resources on the net which can help. A 14832175261Sobriengood place to start is: 1483332785Speter 1483432785Speter@example 14835175261Sobrien@url{http://cvs.nongnu.org/} 1483632785Speter@end example 1483732785Speter 1483832785SpeterIf you are so inspired, increasing the information 1483932785Speteravailable on the net is likely to be appreciated. For 1484032785Speterexample, before the standard @sc{cvs} distribution 1484132785Speterworked on Windows 95, there was a web page with some 1484232785Speterexplanation and patches for running @sc{cvs} on Windows 1484332785Speter95, and various people helped out by mentioning this 1484432785Speterpage on mailing lists or newsgroups when the subject 1484532785Spetercame up. 1484632785Speter 1484732785Speter@item 14848175261SobrienIt is also possible to report bugs to @email{bug-cvs@@nongnu.org}. 1484932785SpeterNote that someone may or may not want to do anything 1485032785Speterwith your bug report---if you need a solution consider 1485132785Speterone of the options mentioned above. People probably do 1485232785Speterwant to hear about bugs which are particularly severe 1485332785Speterin consequences and/or easy to fix, however. You can 1485432785Speteralso increase your odds by being as clear as possible 1485532785Speterabout the exact nature of the bug and any other 1485632785Speterrelevant information. The way to report bugs is to 14857175261Sobriensend email to @email{bug-cvs@@nongnu.org}. Note 14858175261Sobrienthat submissions to @email{bug-cvs@@nongnu.org} may be distributed 1485932785Speterunder the terms of the @sc{gnu} Public License, so if 1486032785Speteryou don't like this, don't submit them. There is 1486132785Speterusually no justification for sending mail directly to 1486232785Speterone of the @sc{cvs} maintainers rather than to 14863175261Sobrien@email{bug-cvs@@nongnu.org}; those maintainers who want to hear 14864175261Sobrienabout such bug reports read @email{bug-cvs@@nongnu.org}. Also note 1486532785Speterthat sending a bug report to other mailing lists or 1486632785Speternewsgroups is @emph{not} a substitute for sending it to 14867175261Sobrien@email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on 1486832785Speterwhatever forum you prefer, but there are not 1486932785Speternecessarily any maintainers reading bug reports sent 14870175261Sobrienanywhere except @email{bug-cvs@@nongnu.org}. 1487132785Speter@end itemize 1487232785Speter 1487332785Speter@cindex Known bugs in this manual or CVS 1487432785SpeterPeople often ask if there is a list of known bugs or 1487532785Speterwhether a particular bug is a known one. The file 1487632785Speter@sc{bugs} in the @sc{cvs} source distribution is one 1487732785Speterlist of known bugs, but it doesn't necessarily try to 1487832785Speterbe comprehensive. Perhaps there will never be a 1487932785Spetercomprehensive, detailed list of known bugs. 1488032785Speter 1488132785Speter@c --------------------------------------------------------------------- 1488217721Speter@node Index 1488317721Speter@unnumbered Index 1488417721Speter@cindex Index 1488517721Speter 1488617721Speter@printindex cp 1488717721Speter 1488817721Speter@bye 1488917721Speter 1489017721SpeterLocal Variables: 1489117721Speterfill-column: 55 1489217721SpeterEnd: 14893