cvs.texinfo revision 1.7
1\input texinfo @c -*-texinfo-*- 2@comment Documentation for CVS. 3@setfilename cvs.info 4@macro copyleftnotice 5@noindent 6Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 7 2001, 2002, 2003, 2004, 2005, 2006 8 Free Software Foundation, Inc. 9 10@multitable @columnfractions .12 .88 11@item Portions 12@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 13 2006 Derek R. Price, 14@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006 15 Ximbiot @url{http://ximbiot.com}, 16@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 17@item @tab and Copyright @copyright{} others. 18@end multitable 19 20@ignore 21Permission is granted to process this file through Tex and print the 22results, provided the printed document carries copying permission 23notice identical to this one except for the removal of this paragraph 24(this paragraph not being relevant to the printed manual). 25 26@end ignore 27Permission is granted to make and distribute verbatim copies of 28this manual provided the copyright notice and this permission notice 29are preserved on all copies. 30 31Permission is granted to copy and distribute modified versions of this 32manual under the conditions for verbatim copying, provided also that the 33entire resulting derived work is distributed under the terms of a 34permission notice identical to this one. 35 36Permission is granted to copy and distribute translations of this manual 37into another language, under the above conditions for modified versions, 38except that this permission notice may be stated in a translation 39approved by the Free Software Foundation. 40@end macro 41 42@comment This file is part of the CVS distribution. 43 44@comment CVS is free software; you can redistribute it and/or modify 45@comment it under the terms of the GNU General Public License as published by 46@comment the Free Software Foundation; either version 2, or (at your option) 47@comment any later version. 48 49@comment CVS is distributed in the hope that it will be useful, 50@comment but WITHOUT ANY WARRANTY; without even the implied warranty of 51@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 52@comment GNU General Public License for more details. 53 54@c See ../README for A4 vs. US letter size. 55@c When we provided A4 postscript, and people tried to 56@c print it on US letter, the usual complaint was that the 57@c page numbers would get cut off. 58@c If one prints US letter on A4, reportedly there is 59@c some extra space at the top and/or bottom, and the side 60@c margins are a bit narrow, but no text is lost. 61@c 62@c See 63@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html 64@c for more on paper sizes. Insuring that margins are 65@c big enough to print on either A4 or US letter does 66@c indeed seem to be the usual approach (RFC2346). 67 68@c This document seems to get overfull hboxes with some 69@c frequency (probably because the tendency is to 70@c sanity-check it with "make info" and run TeX less 71@c often). The big ugly boxes just seem to add insult 72@c to injury, and I'm not aware of them helping to fix 73@c the overfull hboxes at all. 74@finalout 75 76@include version.texi 77@settitle CVS---Concurrent Versions System v@value{VERSION} 78@setchapternewpage odd 79 80@c -- TODO list: 81@c -- Fix all lines that match "^@c -- " 82@c -- Also places marked with FIXME should be manual 83@c problems (as opposed to FIXCVS for CVS problems). 84 85@c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by 86@c @asis when generating info and dvi, and by <i></i> in the generated html, 87@c such that keywords are not expanded in the generated html. 88@ifnothtml 89@macro splitrcskeyword {arg} 90@asis{}\arg\ 91@end macro 92@end ifnothtml 93 94@ifhtml 95@macro splitrcskeyword {arg} 96@i{}\arg\ 97@end macro 98@end ifhtml 99 100@dircategory GNU Packages 101@direntry 102* CVS: (cvs). Concurrent Versions System 103@end direntry 104@dircategory Individual utilities 105@direntry 106* cvs: (cvs)CVS commands. Concurrent Versions System 107@end direntry 108 109@comment The titlepage section does not appear in the Info file. 110@titlepage 111@sp 4 112@comment The title is printed in a large font. 113@center @titlefont{Version Management} 114@sp 115@center @titlefont{with} 116@sp 117@center @titlefont{CVS} 118@sp 2 119@center for @sc{cvs} @value{VERSION} 120@comment -release- 121@sp 3 122@center Per Cederqvist et al 123 124@comment The following two commands start the copyright page 125@comment for the printed manual. This will not appear in the Info file. 126@page 127@vskip 0pt plus 1filll 128@copyleftnotice 129@end titlepage 130 131@summarycontents 132 133@contents 134 135@comment ================================================================ 136@comment The real text starts here 137@comment ================================================================ 138 139@ifnottex 140@c --------------------------------------------------------------------- 141@node Top 142@top 143 144This info manual describes how to use and administer 145@sc{cvs} version @value{VERSION}. 146@end ifnottex 147 148@ifinfo 149@copyleftnotice 150@end ifinfo 151 152@c This menu is pretty long. Not sure how easily that 153@c can be fixed (no brilliant ideas right away)... 154@menu 155* Overview:: An introduction to CVS 156* Repository:: Where all your sources are stored 157* Starting a new project:: Starting a project with CVS 158* Revisions:: Numeric and symbolic names for revisions 159* Branching and merging:: Diverging/rejoining branches of development 160* Recursive behavior:: CVS descends directories 161* Adding and removing:: Adding/removing/renaming files/directories 162* History browsing:: Viewing the history of files in various ways 163 164CVS and the Real World. 165----------------------- 166* Binary files:: CVS can handle binary files 167* Multiple developers:: How CVS helps a group of developers 168* Revision management:: Policy questions for revision management 169* Keyword substitution:: CVS can include the revision inside the file 170* Tracking sources:: Tracking third-party sources 171* Builds:: Issues related to CVS and builds 172* Special Files:: Devices, links and other non-regular files 173 174References. 175----------- 176* CVS commands:: CVS commands share some things 177* Invoking CVS:: Quick reference to CVS commands 178* Administrative files:: Reference manual for the Administrative files 179* Environment variables:: All environment variables which affect CVS 180* Compatibility:: Upgrading CVS versions 181* Troubleshooting:: Some tips when nothing works 182* Credits:: Some of the contributors to this manual 183* BUGS:: Dealing with bugs in CVS or this manual 184* Index:: Index 185@end menu 186 187@c --------------------------------------------------------------------- 188@node Overview 189@chapter Overview 190@cindex Overview 191 192This chapter is for people who have never used 193@sc{cvs}, and perhaps have never used version control 194software before. 195 196If you are already familiar with @sc{cvs} and are just 197trying to learn a particular feature or remember a 198certain command, you can probably skip everything here. 199 200@menu 201* What is CVS?:: What you can do with @sc{cvs} 202* What is CVS not?:: Problems @sc{cvs} doesn't try to solve 203* A sample session:: A tour of basic @sc{cvs} usage 204@end menu 205 206@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 207@node What is CVS? 208@section What is CVS? 209@cindex What is CVS? 210@cindex Introduction to CVS 211@cindex CVS, introduction to 212 213@sc{cvs} is a version control system. Using it, you can 214record the history of your source files. 215 216@c -- /// 217@c -- ///Those who cannot remember the past are condemned to repeat it. 218@c -- /// -- George Santayana 219@c -- ////// 220 221@c -- Insert history quote here! 222For example, bugs sometimes creep in when 223software is modified, and you might not detect the bug 224until a long time after you make the modification. 225With @sc{cvs}, you can easily retrieve old versions to see 226exactly which change caused the bug. This can 227sometimes be a big help. 228 229You could of course save every version of every file 230you have ever created. This would 231however waste an enormous amount of disk space. @sc{cvs} 232stores all the versions of a file in a single file in a 233clever way that only stores the differences between 234versions. 235 236@sc{cvs} also helps you if you are part of a group of people working 237on the same project. It is all too easy to overwrite 238each others' changes unless you are extremely careful. 239Some editors, like @sc{gnu} Emacs, try to make sure that 240two people never modify the same file at the 241same time. Unfortunately, if someone is using another 242editor, that safeguard will not work. @sc{cvs} solves this problem 243by insulating the different developers from each other. Every 244developer works in his own directory, and @sc{cvs} merges 245the work when each developer is done. 246 247@cindex History of CVS 248@cindex CVS, history of 249@cindex Credits (CVS program) 250@cindex Contributors (CVS program) 251@sc{cvs} started out as a bunch of shell scripts written by 252Dick Grune, posted to the newsgroup 253@code{comp.sources.unix} in the volume 6 254release of July, 1986. While no actual code from 255these shell scripts is present in the current version 256of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms 257come from them. 258 259In April, 1989, Brian Berliner designed and coded @sc{cvs}. 260Jeff Polk later helped Brian with the design of the @sc{cvs} 261module and vendor branch support. 262 263@cindex Source, getting CVS source 264You can get @sc{cvs} in a variety of ways, including 265free download from the Internet. For more information 266on downloading @sc{cvs} and other @sc{cvs} topics, see: 267 268@example 269@url{http://cvs.nongnu.org/} 270@end example 271 272@cindex Mailing list 273@cindex List, mailing list 274@cindex Newsgroups 275There is a mailing list, known as @email{info-cvs@@nongnu.org}, 276devoted to @sc{cvs}. To subscribe or 277unsubscribe 278write to 279@email{info-cvs-request@@nongnu.org}. 280If you prefer a Usenet group, there is a one-way mirror (posts to the email 281list are usually sent to the news group, but not visa versa) of 282@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}. The right 283Usenet group for posts is @url{news:comp.software.config-mgmt} which is for 284@sc{cvs} discussions (along with other configuration 285management systems). In the future, it might be 286possible to create a 287@code{comp.software.config-mgmt.cvs}, but probably only 288if there is sufficient @sc{cvs} traffic on 289@url{news:comp.software.config-mgmt}. 290@c Other random data is that the tale was very 291@c skeptical of comp.software.config-mgmt.cvs when the 292@c subject came up around 1995 or so (for one 293@c thing, because creating it would be a "reorg" which 294@c would need to take a more comprehensive look at the 295@c whole comp.software.config-mgmt.* hierarchy). 296 297You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list, 298described in more detail in @ref{BUGS}. To subscribe 299send mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way 300Usenet mirror (posts to the Usenet group are usually sent to the email list and 301visa versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}. 302 303@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 304@node What is CVS not? 305@section What is CVS not? 306@cindex What is CVS not? 307 308@sc{cvs} can do a lot of things for you, but it does 309not try to be everything for everyone. 310 311@table @asis 312@item @sc{cvs} is not a build system. 313 314Though the structure of your repository and modules 315file interact with your build system 316(e.g. @file{Makefile}s), they are essentially 317independent. 318 319@sc{cvs} does not dictate how you build anything. It 320merely stores files for retrieval in a tree structure 321you devise. 322 323@sc{cvs} does not dictate how to use disk space in the 324checked out working directories. If you write your 325@file{Makefile}s or scripts in every directory so they 326have to know the relative positions of everything else, 327you wind up requiring the entire repository to be 328checked out. 329 330If you modularize your work, and construct a build 331system that will share files (via links, mounts, 332@code{VPATH} in @file{Makefile}s, etc.), you can 333arrange your disk usage however you like. 334 335But you have to remember that @emph{any} such system is 336a lot of work to construct and maintain. @sc{cvs} does 337not address the issues involved. 338 339Of course, you should place the tools created to 340support such a build system (scripts, @file{Makefile}s, 341etc) under @sc{cvs}. 342 343Figuring out what files need to be rebuilt when 344something changes is, again, something to be handled 345outside the scope of @sc{cvs}. One traditional 346approach is to use @code{make} for building, and use 347some automated tool for generating the dependencies which 348@code{make} uses. 349 350See @ref{Builds}, for more information on doing builds 351in conjunction with @sc{cvs}. 352 353@item @sc{cvs} is not a substitute for management. 354 355Your managers and project leaders are expected to talk 356to you frequently enough to make certain you are aware 357of schedules, merge points, branch names and release 358dates. If they don't, @sc{cvs} can't help. 359 360@sc{cvs} is an instrument for making sources dance to 361your tune. But you are the piper and the composer. No 362instrument plays itself or writes its own music. 363 364@item @sc{cvs} is not a substitute for developer communication. 365 366When faced with conflicts within a single file, most 367developers manage to resolve them without too much 368effort. But a more general definition of ``conflict'' 369includes problems too difficult to solve without 370communication between developers. 371 372@sc{cvs} cannot determine when simultaneous changes 373within a single file, or across a whole collection of 374files, will logically conflict with one another. Its 375concept of a @dfn{conflict} is purely textual, arising 376when two changes to the same base file are near enough 377to spook the merge (i.e. @code{diff3}) command. 378 379@sc{cvs} does not claim to help at all in figuring out 380non-textual or distributed conflicts in program logic. 381 382For example: Say you change the arguments to function 383@code{X} defined in file @file{A}. At the same time, 384someone edits file @file{B}, adding new calls to 385function @code{X} using the old arguments. You are 386outside the realm of @sc{cvs}'s competence. 387 388Acquire the habit of reading specs and talking to your 389peers. 390 391 392@item @sc{cvs} does not have change control 393 394Change control refers to a number of things. First of 395all it can mean @dfn{bug-tracking}, that is being able 396to keep a database of reported bugs and the status of 397each one (is it fixed? in what release? has the bug 398submitter agreed that it is fixed?). For interfacing 399@sc{cvs} to an external bug-tracking system, see the 400@file{rcsinfo} and @file{verifymsg} files 401(@pxref{Administrative files}). 402 403Another aspect of change control is keeping track of 404the fact that changes to several files were in fact 405changed together as one logical change. If you check 406in several files in a single @code{cvs commit} 407operation, @sc{cvs} then forgets that those files were 408checked in together, and the fact that they have the 409same log message is the only thing tying them 410together. Keeping a @sc{gnu} style @file{ChangeLog} 411can help somewhat. 412@c FIXME: should have an xref to a section which talks 413@c more about keeping ChangeLog's with CVS, but that 414@c section hasn't been written yet. 415 416Another aspect of change control, in some systems, is 417the ability to keep track of the status of each 418change. Some changes have been written by a developer, 419others have been reviewed by a second developer, and so 420on. Generally, the way to do this with @sc{cvs} is to 421generate a diff (using @code{cvs diff} or @code{diff}) 422and email it to someone who can then apply it using the 423@code{patch} utility. This is very flexible, but 424depends on mechanisms outside @sc{cvs} to make sure 425nothing falls through the cracks. 426 427@item @sc{cvs} is not an automated testing program 428 429It should be possible to enforce mandatory use of a 430test suite using the @code{commitinfo} file. I haven't 431heard a lot about projects trying to do that or whether 432there are subtle gotchas, however. 433 434@item @sc{cvs} does not have a built-in process model 435 436Some systems provide ways to ensure that changes or 437releases go through various steps, with various 438approvals as needed. Generally, one can accomplish 439this with @sc{cvs} but it might be a little more work. 440In some cases you'll want to use the @file{commitinfo}, 441@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} 442files, to require that certain steps be performed 443before cvs will allow a checkin. Also consider whether 444features such as branches and tags can be used to 445perform tasks such as doing work in a development tree 446and then merging certain changes over to a stable tree 447only once they have been proven. 448@end table 449 450@c --------------------------------------------------------------------- 451@node A sample session 452@section A sample session 453@cindex Example of a work-session 454@cindex Getting started 455@cindex Work-session, example of 456@cindex tc, Trivial Compiler (example) 457@cindex Trivial Compiler (example) 458 459@c I think an example is a pretty good way to start. But 460@c somewhere in here, maybe after the sample session, 461@c we need something which is kind of 462@c a "roadmap" which is more directed at sketching out 463@c the functionality of CVS and pointing people to 464@c various other parts of the manual. As it stands now 465@c people who read in order get dumped right into all 466@c manner of hair regarding remote repositories, 467@c creating a repository, etc. 468@c 469@c The following was in the old Basic concepts node. I don't 470@c know how good a job it does at introducing modules, 471@c or whether they need to be introduced so soon, but 472@c something of this sort might go into some 473@c introductory material somewhere. 474@ignore 475@cindex Modules (intro) 476The repository contains directories and files, in an 477arbitrary tree. The @dfn{modules} feature can be used 478to group together a set of directories or files into a 479single entity (@pxref{modules}). A typical usage is to 480define one module per project. 481@end ignore 482 483As a way of introducing @sc{cvs}, we'll go through a 484typical work-session using @sc{cvs}. The first thing 485to understand is that @sc{cvs} stores all files in a 486centralized @dfn{repository} (@pxref{Repository}); this 487section assumes that a repository is set up. 488@c I'm not sure that the sentence concerning the 489@c repository quite tells the user what they need to 490@c know at this point. Might need to expand on "centralized" 491@c slightly (maybe not here, maybe further down in the example?) 492 493Suppose you are working on a simple compiler. The source 494consists of a handful of C files and a @file{Makefile}. 495The compiler is called @samp{tc} (Trivial Compiler), 496and the repository is set up so that there is a module 497called @samp{tc}. 498 499@menu 500* Getting the source:: Creating a workspace 501* Committing your changes:: Making your work available to others 502* Cleaning up:: Cleaning up 503* Viewing differences:: Viewing differences 504@end menu 505 506@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 507@node Getting the source 508@subsection Getting the source 509@cindex Getting the source 510@cindex Checking out source 511@cindex Fetching source 512@cindex Source, getting from CVS 513@cindex Checkout, example 514 515The first thing you must do is to get your own working copy of the 516source for @samp{tc}. For this, you use the @code{checkout} command: 517 518@example 519$ cvs checkout tc 520@end example 521 522@noindent 523This will create a new directory called @file{tc} and populate it with 524the source files. 525 526@example 527$ cd tc 528$ ls 529CVS Makefile backend.c driver.c frontend.c parser.c 530@end example 531 532The @file{CVS} directory is used internally by 533@sc{cvs}. Normally, you should not modify or remove 534any of the files in it. 535 536You start your favorite editor, hack away at @file{backend.c}, and a couple 537of hours later you have added an optimization pass to the compiler. 538A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that 539you want to edit. @xref{Multiple developers}, for an explanation. 540 541@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 542@node Committing your changes 543@subsection Committing your changes 544@cindex Committing changes to files 545@cindex Log message entry 546 547When you have checked that the compiler is still compilable you decide 548to make a new version of @file{backend.c}. This will 549store your new @file{backend.c} in the repository and 550make it available to anyone else who is using that same 551repository. 552 553@example 554$ cvs commit backend.c 555@end example 556 557@noindent 558@sc{cvs} starts an editor, to allow you to enter a log 559message. You type in ``Added an optimization pass.'', 560save the temporary file, and exit the editor. 561 562@cindex CVSEDITOR, environment variable 563@cindex EDITOR, environment variable 564The environment variable @code{$CVSEDITOR} determines 565which editor is started. If @code{$CVSEDITOR} is not 566set, then if the environment variable @code{$EDITOR} is 567set, it will be used. If both @code{$CVSEDITOR} and 568@code{$EDITOR} are not set then there is a default 569which will vary with your operating system, for example 570@code{vi} for unix or @code{notepad} for Windows 571NT/95. 572 573@cindex VISUAL, environment variable 574In addition, @sc{cvs} checks the @code{$VISUAL} environment 575variable. Opinions vary on whether this behavior is desirable and 576whether future releases of @sc{cvs} should check @code{$VISUAL} or 577ignore it. You will be OK either way if you make sure that 578@code{$VISUAL} is either unset or set to the same thing as 579@code{$EDITOR}. 580 581@c This probably should go into some new node 582@c containing detailed info on the editor, rather than 583@c the intro. In fact, perhaps some of the stuff with 584@c CVSEDITOR and -m and so on should too. 585When @sc{cvs} starts the editor, it includes a list of 586files which are modified. For the @sc{cvs} client, 587this list is based on comparing the modification time 588of the file against the modification time that the file 589had when it was last gotten or updated. Therefore, if 590a file's modification time has changed but its contents 591have not, it will show up as modified. The simplest 592way to handle this is simply not to worry about it---if 593you proceed with the commit @sc{cvs} will detect that 594the contents are not modified and treat it as an 595unmodified file. The next @code{update} will clue 596@sc{cvs} in to the fact that the file is unmodified, 597and it will reset its stored timestamp so that the file 598will not show up in future editor sessions. 599@c FIXCVS: Might be nice if "commit" and other commands 600@c would reset that timestamp too, but currently commit 601@c doesn't. 602@c FIXME: Need to talk more about the process of 603@c prompting for the log message. Like show an example 604@c of what it pops up in the editor, for example. Also 605@c a discussion of how to get the "a)bort, c)ontinue, 606@c e)dit" prompt and what to do with it. Might also 607@c work in the suggestion that if you want a diff, you 608@c should make it before running commit (someone 609@c suggested that the diff pop up in the editor. I'm 610@c not sure that is better than telling people to run 611@c "cvs diff" first if that is what they want, but if 612@c we want to tell people that, the manual possibly 613@c should say it). 614 615If you want to avoid 616starting an editor you can specify the log message on 617the command line using the @samp{-m} flag instead, like 618this: 619 620@example 621$ cvs commit -m "Added an optimization pass" backend.c 622@end example 623 624@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 625@node Cleaning up 626@subsection Cleaning up 627@cindex Cleaning up 628@cindex Working copy, removing 629@cindex Removing your working copy 630@cindex Releasing your working copy 631 632Before you turn to other tasks you decide to remove your working copy of 633tc. One acceptable way to do that is of course 634 635@example 636$ cd .. 637$ rm -r tc 638@end example 639 640@noindent 641but a better way is to use the @code{release} command (@pxref{release}): 642 643@example 644$ cd .. 645$ cvs release -d tc 646M driver.c 647? tc 648You have [1] altered files in this repository. 649Are you sure you want to release (and delete) directory `tc': n 650** `release' aborted by user choice. 651@end example 652 653The @code{release} command checks that all your modifications have been 654committed. If history logging is enabled it also makes a note in the 655history file. @xref{history file}. 656 657When you use the @samp{-d} flag with @code{release}, it 658also removes your working copy. 659 660In the example above, the @code{release} command wrote a couple of lines 661of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. 662That is nothing to worry about: @file{tc} is the executable compiler, 663and it should not be stored in the repository. @xref{cvsignore}, 664for information about how to make that warning go away. 665@xref{release output}, for a complete explanation of 666all possible output from @code{release}. 667 668@samp{M driver.c} is more serious. It means that the 669file @file{driver.c} has been modified since it was 670checked out. 671 672The @code{release} command always finishes by telling 673you how many modified files you have in your working 674copy of the sources, and then asks you for confirmation 675before deleting any files or making any note in the 676history file. 677 678You decide to play it safe and answer @kbd{n @key{RET}} 679when @code{release} asks for confirmation. 680 681@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 682@node Viewing differences 683@subsection Viewing differences 684@cindex Viewing differences 685@cindex Diff 686 687You do not remember modifying @file{driver.c}, so you want to see what 688has happened to that file. 689 690@example 691$ cd tc 692$ cvs diff driver.c 693@end example 694 695This command runs @code{diff} to compare the version of @file{driver.c} 696that you checked out with your working copy. When you see the output 697you remember that you added a command line option that enabled the 698optimization pass. You check it in, and release the module. 699@c FIXME: we haven't yet defined the term "check in". 700 701@example 702$ cvs commit -m "Added an optimization pass" driver.c 703Checking in driver.c; 704/usr/local/cvsroot/tc/driver.c,v <-- driver.c 705new revision: 1.2; previous revision: 1.1 706done 707$ cd .. 708$ cvs release -d tc 709? tc 710You have [0] altered files in this repository. 711Are you sure you want to release (and delete) directory `tc': y 712@end example 713 714@c --------------------------------------------------------------------- 715@node Repository 716@chapter The Repository 717@cindex Repository (intro) 718@cindex Repository, example 719@cindex Layout of repository 720@cindex Typical repository 721@cindex /usr/local/cvsroot, as example repository 722@cindex cvsroot 723 724The @sc{cvs} @dfn{repository} stores a complete copy of 725all the files and directories which are under version 726control. 727 728Normally, you never access any of the files in the 729repository directly. Instead, you use @sc{cvs} 730commands to get your own copy of the files into a 731@dfn{working directory}, and then 732work on that copy. When you've finished a set of 733changes, you check (or @dfn{commit}) them back into the 734repository. The repository then contains the changes 735which you have made, as well as recording exactly what 736you changed, when you changed it, and other such 737information. Note that the repository is not a 738subdirectory of the working directory, or vice versa; 739they should be in separate locations. 740@c Need some example, e.g. repository 741@c /usr/local/cvsroot; working directory 742@c /home/joe/sources. But this node is too long 743@c as it is; need a little reorganization... 744 745@cindex :local:, setting up 746@sc{cvs} can access a repository by a variety of 747means. It might be on the local computer, or it might 748be on a computer across the room or across the world. 749To distinguish various ways to access a repository, the 750repository name can start with an @dfn{access method}. 751For example, the access method @code{:local:} means to 752access a repository directory, so the repository 753@code{:local:/usr/local/cvsroot} means that the 754repository is in @file{/usr/local/cvsroot} on the 755computer running @sc{cvs}. For information on other 756access methods, see @ref{Remote repositories}. 757 758@c Can se say this more concisely? Like by passing 759@c more of the buck to the Remote repositories node? 760If the access method is omitted, then if the repository 761starts with @samp{/}, then @code{:local:} is 762assumed. If it does not start with @samp{/} then either 763@code{:ext:} or @code{:server:} is assumed. For 764example, if you have a local repository in 765@file{/usr/local/cvsroot}, you can use 766@code{/usr/local/cvsroot} instead of 767@code{:local:/usr/local/cvsroot}. But if (under 768Windows NT, for example) your local repository is 769@file{c:\src\cvsroot}, then you must specify the access 770method, as in @code{:local:c:/src/cvsroot}. 771 772@c This might appear to go in Repository storage, but 773@c actually it is describing something which is quite 774@c user-visible, when you do a "cvs co CVSROOT". This 775@c isn't necessary the perfect place for that, though. 776The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains 777administrative files for @sc{cvs}. The other directories contain the actual 778user-defined modules. 779 780@menu 781* Specifying a repository:: Telling CVS where your repository is 782* Repository storage:: The structure of the repository 783* Working directory storage:: The structure of working directories 784* Intro administrative files:: Defining modules 785* Multiple repositories:: Multiple repositories 786* Creating a repository:: Creating a repository 787* Backing up:: Backing up a repository 788* Moving a repository:: Moving a repository 789* Remote repositories:: Accessing repositories on remote machines 790* Read-only access:: Granting read-only access to the repository 791* Server temporary directory:: The server creates temporary directories 792@end menu 793 794@node Specifying a repository 795@section Telling CVS where your repository is 796 797There are several ways to tell @sc{cvs} 798where to find the repository. You can name the 799repository on the command line explicitly, with the 800@code{-d} (for "directory") option: 801 802@example 803cvs -d /usr/local/cvsroot checkout yoyodyne/tc 804@end example 805 806@cindex .profile, setting CVSROOT in 807@cindex .cshrc, setting CVSROOT in 808@cindex .tcshrc, setting CVSROOT in 809@cindex .bashrc, setting CVSROOT in 810@cindex CVSROOT, environment variable 811 Or you can set the @code{$CVSROOT} environment 812variable to an absolute path to the root of the 813repository, @file{/usr/local/cvsroot} in this example. 814To set @code{$CVSROOT}, @code{csh} and @code{tcsh} 815users should have this line in their @file{.cshrc} or 816@file{.tcshrc} files: 817 818@example 819setenv CVSROOT /usr/local/cvsroot 820@end example 821 822@noindent 823@code{sh} and @code{bash} users should instead have these lines in their 824@file{.profile} or @file{.bashrc}: 825 826@example 827CVSROOT=/usr/local/cvsroot 828export CVSROOT 829@end example 830 831@cindex Root file, in CVS directory 832@cindex CVS/Root file 833 A repository specified with @code{-d} will 834override the @code{$CVSROOT} environment variable. 835Once you've checked a working copy out from the 836repository, it will remember where its repository is 837(the information is recorded in the 838@file{CVS/Root} file in the working copy). 839 840The @code{-d} option and the @file{CVS/Root} file both 841override the @code{$CVSROOT} environment variable. If 842@code{-d} option differs from @file{CVS/Root}, the 843former is used. Of course, for proper operation they 844should be two ways of referring to the same repository. 845 846@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 847@node Repository storage 848@section How data is stored in the repository 849@cindex Repository, how data is stored 850 851For most purposes it isn't important @emph{how} 852@sc{cvs} stores information in the repository. In 853fact, the format has changed in the past, and is likely 854to change in the future. Since in almost all cases one 855accesses the repository via @sc{cvs} commands, such 856changes need not be disruptive. 857 858However, in some cases it may be necessary to 859understand how @sc{cvs} stores data in the repository, 860for example you might need to track down @sc{cvs} locks 861(@pxref{Concurrency}) or you might need to deal with 862the file permissions appropriate for the repository. 863 864@menu 865* Repository files:: What files are stored in the repository 866* File permissions:: File permissions 867* Windows permissions:: Issues specific to Windows 868* Attic:: Some files are stored in the Attic 869* CVS in repository:: Additional information in CVS directory 870* Locks:: CVS locks control concurrent accesses 871* CVSROOT storage:: A few things about CVSROOT are different 872@end menu 873 874@node Repository files 875@subsection Where files are stored within the repository 876 877@c @cindex Filenames, legal 878@c @cindex Legal filenames 879@c Somewhere we need to say something about legitimate 880@c characters in filenames in working directory and 881@c repository. Not "/" (not even on non-unix). And 882@c here is a specific set of issues: 883@c Files starting with a - are handled inconsistently. They can not 884@c be added to a repository with an add command, because it they are 885@c interpreted as a switch. They can appear in a repository if they are 886@c part of a tree that is imported. They can not be removed from the tree 887@c once they are there. 888@c Note that "--" *is* supported (as a 889@c consequence of using GNU getopt). Should document 890@c this somewhere ("Common options"?). The other usual technique, 891@c "./-foo", isn't as effective, at least for "cvs add" 892@c which doesn't support pathnames containing "/". 893 894The overall structure of the repository is a directory 895tree corresponding to the directories in the working 896directory. For example, supposing the repository is in 897 898@example 899/usr/local/cvsroot 900@end example 901 902@noindent 903here is a possible directory tree (showing only the 904directories): 905 906@example 907@t{/usr} 908 | 909 +--@t{local} 910 | | 911 | +--@t{cvsroot} 912 | | | 913 | | +--@t{CVSROOT} 914 | (administrative files) 915 | 916 +--@t{gnu} 917 | | 918 | +--@t{diff} 919 | | (source code to @sc{gnu} diff) 920 | | 921 | +--@t{rcs} 922 | | (source code to @sc{rcs}) 923 | | 924 | +--@t{cvs} 925 | (source code to @sc{cvs}) 926 | 927 +--@t{yoyodyne} 928 | 929 +--@t{tc} 930 | | 931 | +--@t{man} 932 | | 933 | +--@t{testing} 934 | 935 +--(other Yoyodyne software) 936@end example 937 938With the directories are @dfn{history files} for each file 939under version control. The name of the history file is 940the name of the corresponding file with @samp{,v} 941appended to the end. Here is what the repository for 942the @file{yoyodyne/tc} directory might look like: 943@c FIXME: Should also mention CVS (CVSREP) 944@c FIXME? Should we introduce Attic with an xref to 945@c Attic? Not sure whether that is a good idea or not. 946@example 947 @code{$CVSROOT} 948 | 949 +--@t{yoyodyne} 950 | | 951 | +--@t{tc} 952 | | | 953 +--@t{Makefile,v} 954 +--@t{backend.c,v} 955 +--@t{driver.c,v} 956 +--@t{frontend.c,v} 957 +--@t{parser.c,v} 958 +--@t{man} 959 | | 960 | +--@t{tc.1,v} 961 | 962 +--@t{testing} 963 | 964 +--@t{testpgm.t,v} 965 +--@t{test2.t,v} 966@end example 967 968@cindex History files 969@cindex RCS history files 970@c The first sentence, about what history files 971@c contain, is kind of redundant with our intro to what the 972@c repository does in node Repository.... 973The history files contain, among other things, enough 974information to recreate any revision of the file, a log 975of all commit messages and the user-name of the person 976who committed the revision. The history files are 977known as @dfn{RCS files}, because the first program to 978store files in that format was a version control system 979known as @sc{rcs}. For a full 980description of the file format, see the @code{man} page 981@cite{rcsfile(5)}, distributed with @sc{rcs}, or the 982file @file{doc/RCSFILES} in the @sc{cvs} source 983distribution. This 984file format has become very common---many systems other 985than @sc{cvs} or @sc{rcs} can at least import history 986files in this format. 987@c FIXME: Think about including documentation for this 988@c rather than citing it? In the long run, getting 989@c this to be a standard (not sure if we can cope with 990@c a standards process as formal as IEEE/ANSI/ISO/etc, 991@c though...) is the way to go, so maybe citing is 992@c better. 993 994The @sc{rcs} files used in @sc{cvs} differ in a few 995ways from the standard format. The biggest difference 996is magic branches; for more information see @ref{Magic 997branch numbers}. Also in @sc{cvs} the valid tag names 998are a subset of what @sc{rcs} accepts; for @sc{cvs}'s 999rules see @ref{Tags}. 1000 1001@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002@node File permissions 1003@subsection File permissions 1004@c -- Move this to @node Creating a repository or similar 1005@cindex Security, file permissions in repository 1006@cindex File permissions, general 1007@cindex Permissions, general 1008@c FIXME: we need to somehow reflect "permissions in 1009@c repository" versus "permissions in working 1010@c directory" in the index entries. 1011@cindex Group, UNIX file permissions, in repository 1012@cindex Read-only files, in repository 1013All @samp{,v} files are created read-only, and you 1014should not change the permission of those files. The 1015directories inside the repository should be writable by 1016the persons that have permission to modify the files in 1017each directory. This normally means that you must 1018create a UNIX group (see group(5)) consisting of the 1019persons that are to edit the files in a project, and 1020set up the repository so that it is that group that 1021owns the directory. 1022(On some systems, you also need to set the set-group-ID-on-execution bit 1023on the repository directories (see chmod(1)) so that newly-created files 1024and directories get the group-ID of the parent directory rather than 1025that of the current process.) 1026 1027@c See also comment in commitinfo node regarding cases 1028@c which are really awkward with unix groups. 1029 1030This means that you can only control access to files on 1031a per-directory basis. 1032 1033Note that users must also have write access to check 1034out files, because @sc{cvs} needs to create lock files 1035(@pxref{Concurrency}). You can use LockDir in CVSROOT/config 1036to put the lock files somewhere other than in the repository 1037if you want to allow read-only access to some directories 1038(@pxref{config}). 1039 1040@c CVS seems to use CVSUMASK in picking permissions for 1041@c val-tags, but maybe we should say more about this. 1042@c Like val-tags gets created by someone who doesn't 1043@c have CVSUMASK set right? 1044@cindex CVSROOT/val-tags file, and read-only access to projects 1045@cindex val-tags file, and read-only access to projects 1046Also note that users must have write access to the 1047@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep 1048track of what tags are valid tag names (it is sometimes 1049updated when tags are used, as well as when they are 1050created). 1051 1052Each @sc{rcs} file will be owned by the user who last 1053checked it in. This has little significance; what 1054really matters is who owns the directories. 1055 1056@cindex CVSUMASK, environment variable 1057@cindex Umask, for repository files 1058@sc{cvs} tries to set up reasonable file permissions 1059for new directories that are added inside the tree, but 1060you must fix the permissions manually when a new 1061directory should have different permissions than its 1062parent directory. If you set the @code{CVSUMASK} 1063environment variable that will control the file 1064permissions which @sc{cvs} uses in creating directories 1065and/or files in the repository. @code{CVSUMASK} does 1066not affect the file permissions in the working 1067directory; such files have the permissions which are 1068typical for newly created files, except that sometimes 1069@sc{cvs} creates them read-only (see the sections on 1070watches, @ref{Setting a watch}; -r, @ref{Global 1071options}; or @code{CVSREAD}, @ref{Environment variables}). 1072@c FIXME: Need more discussion of which 1073@c group should own the file in the repository. 1074@c Include a somewhat detailed example of the usual 1075@c case where CVSUMASK is 007, the developers are all 1076@c in a group, and that group owns stuff in the 1077@c repository. Need to talk about group ownership of 1078@c newly-created directories/files (on some unices, 1079@c such as SunOS4, setting the setgid bit on the 1080@c directories will make files inherit the directory's 1081@c group. On other unices, your mileage may vary. I 1082@c can't remember what POSIX says about this, if 1083@c anything). 1084 1085Note that using the client/server @sc{cvs} 1086(@pxref{Remote repositories}), there is no good way to 1087set @code{CVSUMASK}; the setting on the client machine 1088has no effect. If you are connecting with @code{rsh}, you 1089can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as 1090described in the documentation for your operating 1091system. This behavior might change in future versions 1092of @sc{cvs}; do not rely on the setting of 1093@code{CVSUMASK} on the client having no effect. 1094@c FIXME: need to explain what a umask is or cite 1095@c someplace which does. 1096@c 1097@c There is also a larger (largely separate) issue 1098@c about the meaning of CVSUMASK in a non-unix context. 1099@c For example, whether there is 1100@c an equivalent which fits better into other 1101@c protection schemes like POSIX.6, VMS, &c. 1102@c 1103@c FIXME: Need one place which discusses this 1104@c read-only files thing. Why would one use -r or 1105@c CVSREAD? Why would one use watches? How do they 1106@c interact? 1107@c 1108@c FIXME: We need to state 1109@c whether using CVSUMASK removes the need for manually 1110@c fixing permissions (in fact, if we are going to mention 1111@c manually fixing permission, we better document a lot 1112@c better just what we mean by "fix"). 1113 1114Using pserver, you will generally need stricter 1115permissions on the @sc{cvsroot} directory and 1116directories above it in the tree; see @ref{Password 1117authentication security}. 1118 1119@cindex Setuid 1120@cindex Setgid 1121@cindex Security, setuid 1122@cindex Installed images (VMS) 1123Some operating systems have features which allow a 1124particular program to run with the ability to perform 1125operations which the caller of the program could not. 1126For example, the set user ID (setuid) or set group ID 1127(setgid) features of unix or the installed image 1128feature of VMS. @sc{cvs} was not written to use such 1129features and therefore attempting to install @sc{cvs} in 1130this fashion will provide protection against only 1131accidental lapses; anyone who is trying to circumvent 1132the measure will be able to do so, and depending on how 1133you have set it up may gain access to more than just 1134@sc{cvs}. You may wish to instead consider pserver. It 1135shares some of the same attributes, in terms of 1136possibly providing a false sense of security or opening 1137security holes wider than the ones you are trying to 1138fix, so read the documentation on pserver security 1139carefully if you are considering this option 1140(@ref{Password authentication security}). 1141 1142@node Windows permissions 1143@subsection File Permission issues specific to Windows 1144@cindex Windows, and permissions 1145@cindex File permissions, Windows-specific 1146@cindex Permissions, Windows-specific 1147 1148Some file permission issues are specific to Windows 1149operating systems (Windows 95, Windows NT, and 1150presumably future operating systems in this family. 1151Some of the following might apply to OS/2 but I'm not 1152sure). 1153 1154If you are using local @sc{cvs} and the repository is on a 1155networked file system which is served by the Samba SMB 1156server, some people have reported problems with 1157permissions. Enabling WRITE=YES in the samba 1158configuration is said to fix/workaround it. 1159Disclaimer: I haven't investigated enough to know the 1160implications of enabling that option, nor do I know 1161whether there is something which @sc{cvs} could be doing 1162differently in order to avoid the problem. If you find 1163something out, please let us know as described in 1164@ref{BUGS}. 1165 1166@node Attic 1167@subsection The attic 1168@cindex Attic 1169 1170You will notice that sometimes @sc{cvs} stores an 1171@sc{rcs} file in the @code{Attic}. For example, if the 1172@sc{cvsroot} is @file{/usr/local/cvsroot} and we are 1173talking about the file @file{backend.c} in the 1174directory @file{yoyodyne/tc}, then the file normally 1175would be in 1176 1177@example 1178/usr/local/cvsroot/yoyodyne/tc/backend.c,v 1179@end example 1180 1181@noindent 1182but if it goes in the attic, it would be in 1183 1184@example 1185/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v 1186@end example 1187 1188@noindent 1189@cindex Dead state 1190instead. It should not matter from a user point of 1191view whether a file is in the attic; @sc{cvs} keeps 1192track of this and looks in the attic when it needs to. 1193But in case you want to know, the rule is that the RCS 1194file is stored in the attic if and only if the head 1195revision on the trunk has state @code{dead}. A 1196@code{dead} state means that file has been removed, or 1197never added, for that revision. For example, if you 1198add a file on a branch, it will have a trunk revision 1199in @code{dead} state, and a branch revision in a 1200non-@code{dead} state. 1201@c Probably should have some more concrete examples 1202@c here, or somewhere (not sure exactly how we should 1203@c arrange the discussion of the dead state, versus 1204@c discussion of the attic). 1205 1206@node CVS in repository 1207@subsection The CVS directory in the repository 1208@cindex CVS directory, in repository 1209 1210The @file{CVS} directory in each repository directory 1211contains information such as file attributes (in a file 1212called @file{CVS/fileattr}. In the 1213future additional files may be added to this directory, 1214so implementations should silently ignore additional 1215files. 1216 1217This behavior is implemented only by @sc{cvs} 1.7 and 1218later; for details see @ref{Watches Compatibility}. 1219 1220The format of the @file{fileattr} file is a series of entries 1221of the following form (where @samp{@{} and @samp{@}} 1222means the text between the braces can be repeated zero 1223or more times): 1224 1225@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} 1226 @{; @var{attrname} = @var{attrval}@} <linefeed> 1227 1228@var{ent-type} is @samp{F} for a file, in which case the entry specifies the 1229attributes for that file. 1230 1231@var{ent-type} is @samp{D}, 1232and @var{filename} empty, to specify default attributes 1233to be used for newly added files. 1234 1235Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older 1236will delete them any time it writes file attributes. 1237@sc{cvs} 1.10 and later will preserve them. 1238 1239Note that the order of the lines is not significant; 1240a program writing the fileattr file may 1241rearrange them at its convenience. 1242 1243There is currently no way of quoting tabs or line feeds in the 1244filename, @samp{=} in @var{attrname}, 1245@samp{;} in @var{attrval}, etc. Note: some implementations also 1246don't handle a NUL character in any of the fields, but 1247implementations are encouraged to allow it. 1248 1249By convention, @var{attrname} starting with @samp{_} is for an attribute given 1250special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes 1251(or will be, once implementations start supporting user-defined attributes). 1252 1253Built-in attributes: 1254 1255@table @code 1256@item _watched 1257Present means the file is watched and should be checked out 1258read-only. 1259 1260@item _watchers 1261Users with watches for this file. Value is 1262@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} 1263where @var{watcher} is a username, and @var{type} 1264is zero or more of edit,unedit,commit separated by 1265@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). 1266 1267@item _editors 1268Users editing this file. Value is 1269@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} 1270where @var{editor} is a username, and @var{val} is 1271@var{time}+@var{hostname}+@var{pathname}, where 1272@var{time} is when the @code{cvs edit} command (or 1273equivalent) happened, 1274and @var{hostname} and @var{pathname} are for the working directory. 1275@end table 1276 1277Example: 1278 1279@c FIXME: sanity.sh should contain a similar test case 1280@c so we can compare this example from something from 1281@c Real Life(TM). See cvsclient.texi (under Notify) for more 1282@c discussion of the date format of _editors. 1283@example 1284Ffile1 _watched=;_watchers=joe>edit,mary>commit 1285Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs 1286D _watched= 1287@end example 1288 1289@noindent 1290means that the file @file{file1} should be checked out 1291read-only. Furthermore, joe is watching for edits and 1292mary is watching for commits. The file @file{file2} 1293should be checked out read-only; sue started editing it 1294on 8 Jan 1975 in the directory @file{/home/sue/cvs} on 1295the machine @code{workstn1}. Future files which are 1296added should be checked out read-only. To represent 1297this example here, we have shown a space after 1298@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact 1299there must be a single tab character there and no spaces. 1300 1301@node Locks 1302@subsection CVS locks in the repository 1303 1304@cindex #cvs.rfl, technical details 1305@cindex #cvs.pfl, technical details 1306@cindex #cvs.wfl, technical details 1307@cindex #cvs.lock, technical details 1308@cindex Locks, cvs, technical details 1309For an introduction to @sc{cvs} locks focusing on 1310user-visible behavior, see @ref{Concurrency}. The 1311following section is aimed at people who are writing 1312tools which want to access a @sc{cvs} repository without 1313interfering with other tools accessing the same 1314repository. If you find yourself confused by concepts 1315described here, like @dfn{read lock}, @dfn{write lock}, 1316and @dfn{deadlock}, you might consult the literature on 1317operating systems or databases. 1318 1319@cindex #cvs.tfl 1320Any file in the repository with a name starting 1321with @file{#cvs.rfl.} is a read lock. Any file in 1322the repository with a name starting with 1323@file{#cvs.pfl} is a promotable read lock. Any file in 1324the repository with a name starting with 1325@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} 1326(before @sc{cvs} 1.5) also created files with names starting 1327with @file{#cvs.tfl}, but they are not discussed here. 1328The directory @file{#cvs.lock} serves as a master 1329lock. That is, one must obtain this lock first before 1330creating any of the other locks. 1331 1332To obtain a read lock, first create the @file{#cvs.lock} 1333directory. This operation must be atomic (which should 1334be true for creating a directory under most operating 1335systems). If it fails because the directory already 1336existed, wait for a while and try again. After 1337obtaining the @file{#cvs.lock} lock, create a file 1338whose name is @file{#cvs.rfl.} followed by information 1339of your choice (for example, hostname and process 1340identification number). Then remove the 1341@file{#cvs.lock} directory to release the master lock. 1342Then proceed with reading the repository. When you are 1343done, remove the @file{#cvs.rfl} file to release the 1344read lock. 1345 1346Promotable read locks are a concept you may not find in other literature on 1347concurrency. They are used to allow a two (or more) pass process to only lock 1348a file for read on the first (read) pass(es), then upgrade its read locks to 1349write locks if necessary for a final pass, still assured that the files have 1350not changed since they were first read. @sc{cvs} uses promotable read locks, 1351for example, to prevent commit and tag verification passes from interfering 1352with other reading processes. It can then lock only a single directory at a 1353time for write during the write pass. 1354 1355To obtain a promotable read lock, first create the @file{#cvs.lock} directory, 1356as with a non-promotable read lock. Then check 1357that there are no files that start with 1358@file{#cvs.pfl}. If there are, remove the master @file{#cvs.lock} directory, 1359wait awhile (CVS waits 30 seconds between lock attempts), and try again. If 1360there are no other promotable locks, go ahead and create a file whose name is 1361@file{#cvs.pfl} followed by information of your choice (for example, CVS uses 1362its hostname and the process identification number of the CVS server process 1363creating the lock). If versions of @sc{cvs} older than version 1.12.4 access 1364your repository directly (not via a @sc{cvs} server of version 1.12.4 or 1365later), then you should also create a read lock since older versions of CVS 1366will ignore the promotable lock when attempting to create their own write lock. 1367Then remove the master @file{#cvs.lock} directory in order to allow other 1368processes to obtain read locks. 1369 1370To obtain a write lock, first create the 1371@file{#cvs.lock} directory, as with read locks. Then 1372check that there are no files whose names start with 1373@file{#cvs.rfl.} and no files whose names start with @file{#cvs.pfl} that are 1374not owned by the process attempting to get the write lock. If either exist, 1375remove @file{#cvs.lock}, wait for a while, and try again. If 1376there are no readers or promotable locks from other processes, then create a 1377file whose name is @file{#cvs.wfl} followed by information of your choice 1378(again, CVS uses the hostname and server process identification 1379number). Remove your @file{#cvs.pfl} file if present. Hang on to the 1380@file{#cvs.lock} lock. Proceed 1381with writing the repository. When you are done, first 1382remove the @file{#cvs.wfl} file and then the 1383@file{#cvs.lock} directory. Note that unlike the 1384@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just 1385informational; it has no effect on the locking operation 1386beyond what is provided by holding on to the 1387@file{#cvs.lock} lock itself. 1388 1389Note that each lock (write lock or read lock) only locks 1390a single directory in the repository, including 1391@file{Attic} and @file{CVS} but not including 1392subdirectories which represent other directories under 1393version control. To lock an entire tree, you need to 1394lock each directory (note that if you fail to obtain 1395any lock you need, you must release the whole tree 1396before waiting and trying again, to avoid deadlocks). 1397 1398Note also that @sc{cvs} expects write locks to control 1399access to individual @file{foo,v} files. @sc{rcs} has 1400a scheme where the @file{,foo,} file serves as a lock, 1401but @sc{cvs} does not implement it and so taking out a 1402@sc{cvs} write lock is recommended. See the comments at 1403rcs_internal_lockfile in the @sc{cvs} source code for 1404further discussion/rationale. 1405 1406@node CVSROOT storage 1407@subsection How files are stored in the CVSROOT directory 1408@cindex CVSROOT, storage of files 1409 1410The @file{$CVSROOT/CVSROOT} directory contains the 1411various administrative files. In some ways this 1412directory is just like any other directory in the 1413repository; it contains @sc{rcs} files whose names end 1414in @samp{,v}, and many of the @sc{cvs} commands operate 1415on it the same way. However, there are a few 1416differences. 1417 1418For each administrative file, in addition to the 1419@sc{rcs} file, there is also a checked out copy of the 1420file. For example, there is an @sc{rcs} file 1421@file{loginfo,v} and a file @file{loginfo} which 1422contains the latest revision contained in 1423@file{loginfo,v}. When you check in an administrative 1424file, @sc{cvs} should print 1425 1426@example 1427cvs commit: Rebuilding administrative file database 1428@end example 1429 1430@noindent 1431and update the checked out copy in 1432@file{$CVSROOT/CVSROOT}. If it does not, there is 1433something wrong (@pxref{BUGS}). To add your own files 1434to the files to be updated in this fashion, you can add 1435them to the @file{checkoutlist} administrative file 1436(@pxref{checkoutlist}). 1437 1438@cindex modules.db 1439@cindex modules.pag 1440@cindex modules.dir 1441By default, the @file{modules} file behaves as 1442described above. If the modules file is very large, 1443storing it as a flat text file may make looking up 1444modules slow (I'm not sure whether this is as much of a 1445concern now as when @sc{cvs} first evolved this 1446feature; I haven't seen benchmarks). Therefore, by 1447making appropriate edits to the @sc{cvs} source code 1448one can store the modules file in a database which 1449implements the @code{ndbm} interface, such as Berkeley 1450db or GDBM. If this option is in use, then the modules 1451database will be stored in the files @file{modules.db}, 1452@file{modules.pag}, and/or @file{modules.dir}. 1453@c I think fileattr also will use the database stuff. 1454@c Anything else? 1455 1456For information on the meaning of the various 1457administrative files, see @ref{Administrative files}. 1458 1459@node Working directory storage 1460@section How data is stored in the working directory 1461 1462@c FIXME: Somewhere we should discuss timestamps (test 1463@c case "stamps" in sanity.sh). But not here. Maybe 1464@c in some kind of "working directory" chapter which 1465@c would encompass the "Builds" one? But I'm not sure 1466@c whether that is a good organization (is it based on 1467@c what the user wants to do?). 1468 1469@cindex CVS directory, in working directory 1470While we are discussing @sc{cvs} internals which may 1471become visible from time to time, we might as well talk 1472about what @sc{cvs} puts in the @file{CVS} directories 1473in the working directories. As with the repository, 1474@sc{cvs} handles this information and one can usually 1475access it via @sc{cvs} commands. But in some cases it 1476may be useful to look at it, and other programs, such 1477as the @code{jCVS} graphical user interface or the 1478@code{VC} package for emacs, may need to look at it. 1479Such programs should follow the recommendations in this 1480section if they hope to be able to work with other 1481programs which use those files, including future 1482versions of the programs just mentioned and the 1483command-line @sc{cvs} client. 1484 1485The @file{CVS} directory contains several files. 1486Programs which are reading this directory should 1487silently ignore files which are in the directory but 1488which are not documented here, to allow for future 1489expansion. 1490 1491The files are stored according to the text file 1492convention for the system in question. This means that 1493working directories are not portable between systems 1494with differing conventions for storing text files. 1495This is intentional, on the theory that the files being 1496managed by @sc{cvs} probably will not be portable between 1497such systems either. 1498 1499@table @file 1500@item Root 1501This file contains the current @sc{cvs} root, as 1502described in @ref{Specifying a repository}. 1503 1504@cindex Repository file, in CVS directory 1505@cindex CVS/Repository file 1506@item Repository 1507This file contains the directory within the repository 1508which the current directory corresponds with. It can 1509be either an absolute pathname or a relative pathname; 1510@sc{cvs} has had the ability to read either format 1511since at least version 1.3 or so. The relative 1512pathname is relative to the root, and is the more 1513sensible approach, but the absolute pathname is quite 1514common and implementations should accept either. For 1515example, after the command 1516 1517@example 1518cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc 1519@end example 1520 1521@noindent 1522@file{Root} will contain 1523 1524@example 1525:local:/usr/local/cvsroot 1526@end example 1527 1528@noindent 1529and @file{Repository} will contain either 1530 1531@example 1532/usr/local/cvsroot/yoyodyne/tc 1533@end example 1534 1535@noindent 1536or 1537 1538@example 1539yoyodyne/tc 1540@end example 1541 1542If the particular working directory does not correspond 1543to a directory in the repository, then @file{Repository} 1544should contain @file{CVSROOT/Emptydir}. 1545@cindex Emptydir, in CVSROOT directory 1546@cindex CVSROOT/Emptydir directory 1547 1548@cindex Entries file, in CVS directory 1549@cindex CVS/Entries file 1550@item Entries 1551This file lists the files and directories in the 1552working directory. 1553The first character of each line indicates what sort of 1554line it is. If the character is unrecognized, programs 1555reading the file should silently skip that line, to 1556allow for future expansion. 1557 1558If the first character is @samp{/}, then the format is: 1559 1560@example 1561/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate} 1562@end example 1563 1564@noindent 1565where @samp{[} and @samp{]} are not part of the entry, 1566but instead indicate that the @samp{+} and conflict 1567marker are optional. @var{name} is the name of the 1568file within the directory. @var{revision} is the 1569revision that the file in the working derives from, or 1570@samp{0} for an added file, or @samp{-} followed by a 1571revision for a removed file. @var{timestamp} is the 1572timestamp of the file at the time that @sc{cvs} created 1573it; if the timestamp differs with the actual 1574modification time of the file it means the file has 1575been modified. It is stored in 1576the format used by the ISO C asctime() function (for 1577example, @samp{Sun Apr 7 01:29:26 1996}). One may 1578write a string which is not in that format, for 1579example, @samp{Result of merge}, to indicate that the 1580file should always be considered to be modified. This 1581is not a special case; to see whether a file is 1582modified a program should take the timestamp of the file 1583and simply do a string compare with @var{timestamp}. 1584If there was a conflict, @var{conflict} can be set to 1585the modification time of the file after the file has been 1586written with conflict markers (@pxref{Conflicts example}). 1587Thus if @var{conflict} is subsequently the same as the actual 1588modification time of the file it means that the user 1589has obviously not resolved the conflict. @var{options} 1590contains sticky options (for example @samp{-kb} for a 1591binary file). @var{tagdate} contains @samp{T} followed 1592by a tag name, or @samp{D} for a date, followed by a 1593sticky tag or date. Note that if @var{timestamp} 1594contains a pair of timestamps separated by a space, 1595rather than a single timestamp, you are dealing with a 1596version of @sc{cvs} earlier than @sc{cvs} 1.5 (not 1597documented here). 1598 1599The timezone on the timestamp in CVS/Entries (local or 1600universal) should be the same as the operating system 1601stores for the timestamp of the file itself. For 1602example, on Unix the file's timestamp is in universal 1603time (UT), so the timestamp in CVS/Entries should be 1604too. On @sc{vms}, the file's timestamp is in local 1605time, so @sc{cvs} on @sc{vms} should use local time. 1606This rule is so that files do not appear to be modified 1607merely because the timezone changed (for example, to or 1608from summer time). 1609@c See comments and calls to gmtime() and friends in 1610@c src/vers_ts.c (function time_stamp). 1611 1612If the first character of a line in @file{Entries} is 1613@samp{D}, then it indicates a subdirectory. @samp{D} 1614on a line all by itself indicates that the program 1615which wrote the @file{Entries} file does record 1616subdirectories (therefore, if there is such a line and 1617no other lines beginning with @samp{D}, one knows there 1618are no subdirectories). Otherwise, the line looks 1619like: 1620 1621@example 1622D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} 1623@end example 1624 1625@noindent 1626where @var{name} is the name of the subdirectory, and 1627all the @var{filler} fields should be silently ignored, 1628for future expansion. Programs which modify 1629@code{Entries} files should preserve these fields. 1630 1631The lines in the @file{Entries} file can be in any order. 1632 1633@cindex Entries.Log file, in CVS directory 1634@cindex CVS/Entries.Log file 1635@item Entries.Log 1636This file does not record any information beyond that 1637in @file{Entries}, but it does provide a way to update 1638the information without having to rewrite the entire 1639@file{Entries} file, including the ability to preserve 1640the information even if the program writing 1641@file{Entries} and @file{Entries.Log} abruptly aborts. 1642Programs which are reading the @file{Entries} file 1643should also check for @file{Entries.Log}. If the latter 1644exists, they should read @file{Entries} and then apply 1645the changes mentioned in @file{Entries.Log}. After 1646applying the changes, the recommended practice is to 1647rewrite @file{Entries} and then delete @file{Entries.Log}. 1648The format of a line in @file{Entries.Log} is a single 1649character command followed by a space followed by a 1650line in the format specified for a line in 1651@file{Entries}. The single character command is 1652@samp{A} to indicate that the entry is being added, 1653@samp{R} to indicate that the entry is being removed, 1654or any other character to indicate that the entire line 1655in @file{Entries.Log} should be silently ignored (for 1656future expansion). If the second character of the line 1657in @file{Entries.Log} is not a space, then it was 1658written by an older version of @sc{cvs} (not documented 1659here). 1660 1661Programs which are writing rather than reading can 1662safely ignore @file{Entries.Log} if they so choose. 1663 1664@cindex Entries.Backup file, in CVS directory 1665@cindex CVS/Entries.Backup file 1666@item Entries.Backup 1667This is a temporary file. Recommended usage is to 1668write a new entries file to @file{Entries.Backup}, and 1669then to rename it (atomically, where possible) to @file{Entries}. 1670 1671@cindex Entries.Static file, in CVS directory 1672@cindex CVS/Entries.Static file 1673@item Entries.Static 1674The only relevant thing about this file is whether it 1675exists or not. If it exists, then it means that only 1676part of a directory was gotten and @sc{cvs} will 1677not create additional files in that directory. To 1678clear it, use the @code{update} command with the 1679@samp{-d} option, which will get the additional files 1680and remove @file{Entries.Static}. 1681@c FIXME: This needs to be better documented, in places 1682@c other than Working Directory Storage. 1683@c FIXCVS: The fact that this setting exists needs to 1684@c be more visible to the user. For example "cvs 1685@c status foo", in the case where the file would be 1686@c gotten except for Entries.Static, might say 1687@c something to distinguish this from other cases. 1688@c One thing that periodically gets suggested is to 1689@c have "cvs update" print something when it skips 1690@c files due to Entries.Static, but IMHO that kind of 1691@c noise pretty much makes the Entries.Static feature 1692@c useless. 1693 1694@cindex Tag file, in CVS directory 1695@cindex CVS/Tag file 1696@cindex Sticky tags/dates, per-directory 1697@cindex Per-directory sticky tags/dates 1698@item Tag 1699This file contains per-directory sticky tags or dates. 1700The first character is @samp{T} for a branch tag, 1701@samp{N} for a non-branch tag, or @samp{D} for a date, 1702or another character to mean the file should be 1703silently ignored, for future expansion. This character 1704is followed by the tag or date. Note that 1705per-directory sticky tags or dates are used for things 1706like applying to files which are newly added; they 1707might not be the same as the sticky tags or dates on 1708individual files. For general information on sticky 1709tags and dates, see @ref{Sticky tags}. 1710@c FIXME: This needs to be much better documented, 1711@c preferably not in the context of "working directory 1712@c storage". 1713@c FIXME: The Sticky tags node needs to discuss, or xref to 1714@c someplace which discusses, per-directory sticky 1715@c tags and the distinction with per-file sticky tags. 1716 1717@cindex Notify file, in CVS directory 1718@cindex CVS/Notify file 1719@item Notify 1720This file stores notifications (for example, for 1721@code{edit} or @code{unedit}) which have not yet been 1722sent to the server. Its format is not yet documented 1723here. 1724 1725@cindex Notify.tmp file, in CVS directory 1726@cindex CVS/Notify.tmp file 1727@item Notify.tmp 1728This file is to @file{Notify} as @file{Entries.Backup} 1729is to @file{Entries}. That is, to write @file{Notify}, 1730first write the new contents to @file{Notify.tmp} and 1731then (atomically where possible), rename it to 1732@file{Notify}. 1733 1734@cindex Base directory, in CVS directory 1735@cindex CVS/Base directory 1736@item Base 1737If watches are in use, then an @code{edit} command 1738stores the original copy of the file in the @file{Base} 1739directory. This allows the @code{unedit} command to 1740operate even if it is unable to communicate with the 1741server. 1742 1743@cindex Baserev file, in CVS directory 1744@cindex CVS/Baserev file 1745@item Baserev 1746The file lists the revision for each of the files in 1747the @file{Base} directory. The format is: 1748 1749@example 1750B@var{name}/@var{rev}/@var{expansion} 1751@end example 1752 1753@noindent 1754where @var{expansion} should be ignored, to allow for 1755future expansion. 1756 1757@cindex Baserev.tmp file, in CVS directory 1758@cindex CVS/Baserev.tmp file 1759@item Baserev.tmp 1760This file is to @file{Baserev} as @file{Entries.Backup} 1761is to @file{Entries}. That is, to write @file{Baserev}, 1762first write the new contents to @file{Baserev.tmp} and 1763then (atomically where possible), rename it to 1764@file{Baserev}. 1765 1766@cindex Template file, in CVS directory 1767@cindex CVS/Template file 1768@item Template 1769This file contains the template specified by the 1770@file{rcsinfo} file (@pxref{rcsinfo}). It is only used 1771by the client; the non-client/server @sc{cvs} consults 1772@file{rcsinfo} directly. 1773@end table 1774 1775@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1776@node Intro administrative files 1777@section The administrative files 1778@cindex Administrative files (intro) 1779@cindex Modules file 1780@cindex CVSROOT, module name 1781@cindex Defining modules (intro) 1782 1783@c FIXME: this node should be reorganized into "general 1784@c information about admin files" and put the "editing 1785@c admin files" stuff up front rather than jumping into 1786@c the details of modules right away. Then the 1787@c Administrative files node can go away, the information 1788@c on each admin file distributed to a place appropriate 1789@c to its function, and this node can contain a table 1790@c listing each file and a @ref to its detailed description. 1791 1792The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative 1793files}. @xref{Administrative files}, for a complete description. 1794You can use @sc{cvs} without any of these files, but 1795some commands work better when at least the 1796@file{modules} file is properly set up. 1797 1798The most important of these files is the @file{modules} 1799file. It defines all modules in the repository. This 1800is a sample @file{modules} file. 1801 1802@c FIXME: The CVSROOT line is a goofy example now that 1803@c mkmodules doesn't exist. 1804@example 1805CVSROOT CVSROOT 1806modules CVSROOT modules 1807cvs gnu/cvs 1808rcs gnu/rcs 1809diff gnu/diff 1810tc yoyodyne/tc 1811@end example 1812 1813The @file{modules} file is line oriented. In its 1814simplest form each line contains the name of the 1815module, whitespace, and the directory where the module 1816resides. The directory is a path relative to 1817@code{$CVSROOT}. The last four lines in the example 1818above are examples of such lines. 1819 1820@c FIXME: might want to introduce the concept of options in modules file 1821@c (the old example which was here, -i mkmodules, is obsolete). 1822 1823The line that defines the module called @samp{modules} 1824uses features that are not explained here. 1825@xref{modules}, for a full explanation of all the 1826available features. 1827 1828@c FIXME: subsection without node is bogus 1829@subsection Editing administrative files 1830@cindex Editing administrative files 1831@cindex Administrative files, editing them 1832 1833You edit the administrative files in the same way that you would edit 1834any other module. Use @samp{cvs checkout CVSROOT} to get a working 1835copy, edit it, and commit your changes in the normal way. 1836 1837It is possible to commit an erroneous administrative 1838file. You can often fix the error and check in a new 1839revision, but sometimes a particularly bad error in the 1840administrative file makes it impossible to commit new 1841revisions. 1842@c @xref{Bad administrative files} for a hint 1843@c about how to solve such situations. 1844@c -- administrative file checking-- 1845 1846@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1847@node Multiple repositories 1848@section Multiple repositories 1849@cindex Multiple repositories 1850@cindex Repositories, multiple 1851@cindex Many repositories 1852@cindex Parallel repositories 1853@cindex Disjoint repositories 1854@cindex CVSROOT, multiple repositories 1855 1856In some situations it is a good idea to have more than 1857one repository, for instance if you have two 1858development groups that work on separate projects 1859without sharing any code. All you have to do to have 1860several repositories is to specify the appropriate 1861repository, using the @code{CVSROOT} environment 1862variable, the @samp{-d} option to @sc{cvs}, or (once 1863you have checked out a working directory) by simply 1864allowing @sc{cvs} to use the repository that was used 1865to check out the working directory 1866(@pxref{Specifying a repository}). 1867 1868The big advantage of having multiple repositories is 1869that they can reside on different servers. With @sc{cvs} 1870version 1.10, a single command cannot recurse into 1871directories from different repositories. With development 1872versions of @sc{cvs}, you can check out code from multiple 1873servers into your working directory. @sc{cvs} will 1874recurse and handle all the details of making 1875connections to as many server machines as necessary to 1876perform the requested command. Here is an example of 1877how to set up a working directory: 1878 1879@example 1880cvs -d server1:/cvs co dir1 1881cd dir1 1882cvs -d server2:/root co sdir 1883cvs update 1884@end example 1885 1886The @code{cvs co} commands set up the working 1887directory, and then the @code{cvs update} command will 1888contact server2, to update the dir1/sdir subdirectory, 1889and server1, to update everything else. 1890 1891@c FIXME: Does the FAQ have more about this? I have a 1892@c dim recollection, but I'm too lazy to check right now. 1893 1894@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1895@node Creating a repository 1896@section Creating a repository 1897 1898@cindex Repository, setting up 1899@cindex Creating a repository 1900@cindex Setting up a repository 1901 1902This section describes how to set up a @sc{cvs} repository for any 1903sort of access method. After completing the setup described in this 1904section, you should be able to access your @sc{cvs} repository immediately 1905via the local access method and several remote access methods. For 1906more information on setting up remote access to the repository you create 1907in this section, please read the section on @xref{Remote repositories}. 1908 1909To set up a @sc{cvs} repository, first choose the 1910machine and disk on which you want to store the 1911revision history of the source files. CPU and memory 1912requirements are modest, so most machines should be 1913adequate. For details see @ref{Server requirements}. 1914@c Possible that we should be providing a quick rule of 1915@c thumb, like the 32M memory for the server. That 1916@c might increase the number of people who are happy 1917@c with the answer, without following the xref. 1918 1919To estimate disk space 1920requirements, if you are importing RCS files from 1921another system, the size of those files is the 1922approximate initial size of your repository, or if you 1923are starting without any version history, a rule of 1924thumb is to allow for the server approximately three 1925times the size of the code to be under @sc{cvs} for the 1926repository (you will eventually outgrow this, but not 1927for a while). On the machines on which the developers 1928will be working, you'll want disk space for 1929approximately one working directory for each developer 1930(either the entire tree or a portion of it, depending 1931on what each developer uses). 1932 1933The repository should be accessible 1934(directly or via a networked file system) from all 1935machines which want to use @sc{cvs} in server or local 1936mode; the client machines need not have any access to 1937it other than via the @sc{cvs} protocol. It is not 1938possible to use @sc{cvs} to read from a repository 1939which one only has read access to; @sc{cvs} needs to be 1940able to create lock files (@pxref{Concurrency}). 1941 1942@node Backing up 1943@section Backing up a repository 1944@cindex Repository, backing up 1945@cindex Backing up, repository 1946 1947There is nothing particularly magical about the files 1948in the repository; for the most part it is possible to 1949back them up just like any other files. However, there 1950are a few issues to consider. 1951 1952@cindex Locks, cvs, and backups 1953@cindex #cvs.rfl, and backups 1954The first is that to be paranoid, one should either not 1955use @sc{cvs} during the backup, or have the backup 1956program lock @sc{cvs} while doing the backup. To not 1957use @sc{cvs}, you might forbid logins to machines which 1958can access the repository, turn off your @sc{cvs} 1959server, or similar mechanisms. The details would 1960depend on your operating system and how you have 1961@sc{cvs} set up. To lock @sc{cvs}, you would create 1962@file{#cvs.rfl} locks in each repository directory. 1963See @ref{Concurrency}, for more on @sc{cvs} locks. 1964Having said all this, if you just back up without any 1965of these precautions, the results are unlikely to be 1966particularly dire. Restoring from backup, the 1967repository might be in an inconsistent state, but this 1968would not be particularly hard to fix manually. 1969 1970When you restore a repository from backup, assuming 1971that changes in the repository were made after the time 1972of the backup, working directories which were not 1973affected by the failure may refer to revisions which no 1974longer exist in the repository. Trying to run @sc{cvs} 1975in such directories will typically produce an error 1976message. One way to get those changes back into the 1977repository is as follows: 1978 1979@itemize @bullet 1980@item 1981Get a new working directory. 1982 1983@item 1984Copy the files from the working directory from before 1985the failure over to the new working directory (do not 1986copy the contents of the @file{CVS} directories, of 1987course). 1988 1989@item 1990Working in the new working directory, use commands such 1991as @code{cvs update} and @code{cvs diff} to figure out 1992what has changed, and then when you are ready, commit 1993the changes into the repository. 1994@end itemize 1995 1996@node Moving a repository 1997@section Moving a repository 1998@cindex Repository, moving 1999@cindex Moving a repository 2000@cindex Copying a repository 2001 2002Just as backing up the files in the repository is 2003pretty much like backing up any other files, if you 2004need to move a repository from one place to another it 2005is also pretty much like just moving any other 2006collection of files. 2007 2008The main thing to consider is that working directories 2009point to the repository. The simplest way to deal with 2010a moved repository is to just get a fresh working 2011directory after the move. Of course, you'll want to 2012make sure that the old working directory had been 2013checked in before the move, or you figured out some 2014other way to make sure that you don't lose any 2015changes. If you really do want to reuse the existing 2016working directory, it should be possible with manual 2017surgery on the @file{CVS/Repository} files. You can 2018see @ref{Working directory storage}, for information on 2019the @file{CVS/Repository} and @file{CVS/Root} files, but 2020unless you are sure you want to bother, it probably 2021isn't worth it. 2022@c FIXME: Surgery on CVS/Repository should be avoided 2023@c by making RELATIVE_REPOS the default. 2024@c FIXME-maybe: might want some documented way to 2025@c change the CVS/Root files in some particular tree. 2026@c But then again, I don't know, maybe just having 2027@c people do this in perl/shell/&c isn't so bad... 2028 2029@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2030@node Remote repositories 2031@section Remote repositories 2032@cindex Repositories, remote 2033@cindex Remote repositories 2034@cindex Client/Server Operation 2035@cindex Server, CVS 2036@cindex Remote repositories, port specification 2037@cindex Repositories, remote, port specification 2038@cindex Client/Server Operation, port specification 2039@cindex pserver (client/server connection method), port specification 2040@cindex kserver (client/server connection method), port specification 2041@cindex gserver (client/server connection method), port specification 2042@cindex port, specifying for remote repositories 2043 2044 Your working copy of the sources can be on a 2045different machine than the repository. Using @sc{cvs} 2046in this manner is known as @dfn{client/server} 2047operation. You run @sc{cvs} on a machine which can 2048mount your working directory, known as the 2049@dfn{client}, and tell it to communicate to a machine 2050which can mount the repository, known as the 2051@dfn{server}. Generally, using a remote 2052repository is just like using a local one, except that 2053the format of the repository name is: 2054 2055@example 2056[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 2057@end example 2058 2059Specifying a password in the repository name is not recommended during 2060checkout, since this will cause @sc{cvs} to store a cleartext copy of the 2061password in each created directory. @code{cvs login} first instead 2062(@pxref{Password authentication client}). 2063 2064The details of exactly what needs to be set up depend 2065on how you are connecting to the server. 2066 2067@c Should we try to explain which platforms are which? 2068@c Platforms like unix and VMS, which only allow 2069@c privileged programs to bind to sockets <1024 lose on 2070@c :server: 2071@c Platforms like Mac and VMS, whose rsh program is 2072@c unusable or nonexistent, lose on :ext: 2073@c Platforms like OS/2 and NT probably could plausibly 2074@c default either way (modulo -b troubles). 2075 2076@menu 2077* Server requirements:: Memory and other resources for servers 2078* The connection method:: Connection methods and method options 2079* Connecting via rsh:: Using the @code{rsh} program to connect 2080* Password authenticated:: Direct connections using passwords 2081* GSSAPI authenticated:: Direct connections using GSSAPI 2082* Kerberos authenticated:: Direct connections with Kerberos 2083* Connecting via fork:: Using a forked @code{cvs server} to connect 2084* Write proxies:: Distributing load across several CVS servers 2085@end menu 2086 2087@node Server requirements 2088@subsection Server requirements 2089 2090The quick answer to what sort of machine is suitable as 2091a server is that requirements are modest---a server 2092with 32M of memory or even less can handle a fairly 2093large source tree with a fair amount of activity. 2094@c Say something about CPU speed too? I'm even less sure 2095@c what to say on that subject... 2096 2097The real answer, of course, is more complicated. 2098Estimating the known areas of large memory consumption 2099should be sufficient to estimate memory requirements. 2100There are two such areas documented here; other memory 2101consumption should be small by comparison (if you find 2102that is not the case, let us know, as described in 2103@ref{BUGS}, so we can update this documentation). 2104 2105The first area of big memory consumption is large 2106checkouts, when using the @sc{cvs} server. The server 2107consists of two processes for each client that it is 2108serving. Memory consumption on the child process 2109should remain fairly small. Memory consumption on the 2110parent process, particularly if the network connection 2111to the client is slow, can be expected to grow to 2112slightly more than the size of the sources in a single 2113directory, or two megabytes, whichever is larger. 2114@c "two megabytes" of course is SERVER_HI_WATER. But 2115@c we don't mention that here because we are 2116@c documenting the default configuration of CVS. If it 2117@c is a "standard" thing to change that value, it 2118@c should be some kind of run-time configuration. 2119@c 2120@c See cvsclient.texi for more on the design decision 2121@c to not have locks in place while waiting for the 2122@c client, which is what results in memory consumption 2123@c as high as this. 2124 2125Multiplying the size of each @sc{cvs} server by the 2126number of servers which you expect to have active at 2127one time should give an idea of memory requirements for 2128the server. For the most part, the memory consumed by 2129the parent process probably can be swap space rather 2130than physical memory. 2131@c Has anyone verified that notion about swap space? 2132@c I say it based pretty much on guessing that the 2133@c ->text of the struct buffer_data only gets accessed 2134@c in a first in, first out fashion, but I haven't 2135@c looked very closely. 2136 2137@c What about disk usage in /tmp on the server? I think that 2138@c it can be substantial, but I haven't looked at this 2139@c again and tried to figure it out ("cvs import" is 2140@c probably the worst case...). 2141 2142The second area of large memory consumption is 2143@code{diff}, when checking in large files. This is 2144required even for binary files. The rule of thumb is 2145to allow about ten times the size of the largest file 2146you will want to check in, although five times may be 2147adequate. For example, if you want to check in a file 2148which is 10 megabytes, you should have 100 megabytes of 2149memory on the machine doing the checkin (the server 2150machine for client/server, or the machine running 2151@sc{cvs} for non-client/server). This can be swap 2152space rather than physical memory. Because the memory 2153is only required briefly, there is no particular need 2154to allow memory for more than one such checkin at a 2155time. 2156@c The 5-10 times rule of thumb is from Paul Eggert for 2157@c GNU diff. I don't think it is in the GNU diff 2158@c manual or anyplace like that. 2159@c 2160@c Probably we could be saying more about 2161@c non-client/server CVS. 2162@c I would guess for non-client/server CVS in an NFS 2163@c environment the biggest issues are the network and 2164@c the NFS server. 2165 2166Resource consumption for the client is even more 2167modest---any machine with enough capacity to run the 2168operating system in question should have little 2169trouble. 2170@c Is that true? I think the client still wants to 2171@c (bogusly) store entire files in memory at times. 2172 2173For information on disk space requirements, see 2174@ref{Creating a repository}. 2175 2176@node The connection method 2177@subsection The connection method 2178 2179In its simplest form, the @var{method} portion of the repository string 2180(@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork}, 2181@samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some 2182platforms, @samp{server}. 2183 2184If @var{method} is not specified, and the repository 2185name starts with a @samp{/}, then the default is @code{local}. 2186If @var{method} is not specified, and the repository 2187name does not start with a @samp{/}, then the default is @code{ext} 2188or @code{server}, depending on your platform; both the @samp{ext} 2189and @samp{server} methods are described in @ref{Connecting via rsh}. 2190 2191@cindex connection method options 2192@cindex options, connection method 2193The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection 2194methods all accept optional method options, specified as part of the 2195@var{method} string, like so: 2196 2197@example 2198:@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data} 2199@end example 2200 2201@sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though 2202it may sometimes be sensitive to the case of @var{arg}. The possible method 2203options are as follows: 2204 2205@table @code 2206@cindex CVS_PROXY_PORT 2207@cindex proxy, method option 2208@cindex proxyport, method option 2209@cindex proxies, web, connecting via 2210@cindex web proxies, connecting via 2211@cindex proxies, HTTP, connecting via 2212@cindex HTTP proxies, connecting via 2213@item proxy=@var{hostname} 2214@itemx proxyport=@var{port} 2215These two method options can be used to connect via an HTTP tunnel style web 2216proxy. @var{hostname} should be the name of the HTTP proxy server to connect 2217through and @var{port} is the port number on the HTTP proxy server to connect 2218via. @var{port} defaults to 8080. 2219 2220@strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy 2221server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.} 2222 2223For example, to connect pserver via a web proxy listening on port 8000 of 2224www.myproxy.net, you would use a method of: 2225 2226@example 2227:pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string} 2228@end example 2229 2230@strong{NOTE: In the above example, @var{pserver_connection_string} is still 2231required to connect and authenticate to the CVS server, as noted in the 2232upcoming sections on password authentication, @code{gserver}, and 2233@code{kserver}. The example above only demonstrates a modification to the 2234@var{method} portion of the repository name.} 2235 2236These options first appeared in @sc{cvs} version 1.12.7 and are valid as 2237modifcations to the @code{gserver} and @code{pserver} connection methods. 2238 2239@cindex CVS_RSH method option 2240@item CVS_RSH=@var{path} 2241This method option can be used with the @code{ext} method to specify the path 2242the @sc{cvs} client will use to find the remote shell used to contact the 2243@sc{cvs} server and takes precedence over any path specified in the 2244@code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}). For 2245example, to connect to a @sc{cvs} server via the local 2246@file{/path/to/ssh/command} command, you could choose to specify the following 2247@var{path} via the @code{CVS_RSH} method option: 2248 2249@example 2250:ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string} 2251@end example 2252 2253This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2254as a modifcation to the @code{ext} connection method. 2255 2256@cindex CVS_SERVER method option 2257@item CVS_SERVER=@var{path} 2258This method option can be used with the @code{ext} and @code{fork} methods to 2259specify the path @sc{cvs} will use to find the @sc{cvs} executable on the 2260@sc{cvs} server and takes precedence over any path specified in the 2261@code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}). For 2262example, to select the remote @file{/path/to/cvs/command} executable as your 2263@sc{cvs} server application on the @sc{cvs} server machine, you could choose to 2264specify the following @var{path} via the @code{CVS_SERVER} method option: 2265 2266@example 2267:ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string} 2268@end example 2269 2270@noindent 2271or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your 2272@code{$PATH} on the @sc{cvs} server: 2273 2274@example 2275:ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string} 2276@end example 2277 2278This method option first appeared in @sc{cvs} version 1.12.11 and is valid 2279as a modifcation to both the @code{ext} and @code{fork} connection methods. 2280 2281@cindex Redirect, method option 2282@item Redirect=@var{boolean-state} 2283The @code{Redirect} method option determines whether the @sc{cvs} client will 2284allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually 2285for write requests, as in a write proxy setup. 2286 2287A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config} 2288file options is acceptable here (@pxref{config}). For example, @samp{on}, 2289@samp{off}, @samp{true}, and @samp{false} are all valid values for 2290@var{boolean-state}. @var{boolean-state} for the @code{Redirect} method option 2291defaults to @samp{on}. 2292 2293This option will have no effect when talking to any non-secondary @sc{cvs} 2294server. For more on write proxies and secondary servers, please see 2295@ref{Write proxies}. 2296 2297This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2298as a modifcation to the @code{ext} connection method. 2299@end table 2300 2301As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER} 2302options, a method specification like the following would work: 2303 2304@example 2305:ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command: 2306@end example 2307 2308This means that you would not need to have 2309the @code{CVS_SERVER} or @code{CVS_RSH} environment 2310variables set correctly. See @ref{Connecting via rsh}, for more details on 2311these environment variables. 2312 2313@node Connecting via rsh 2314@subsection Connecting with rsh 2315 2316@cindex rsh 2317@sc{cvs} uses the @samp{rsh} protocol to perform these 2318operations, so the remote user host needs to have a 2319@file{.rhosts} file which grants access to the local 2320user. Note that the program that @sc{cvs} uses for this 2321purpose may be specified using the @file{--with-rsh} 2322flag to configure. 2323 2324For example, suppose you are the user @samp{mozart} on 2325the local machine @samp{toe.example.com}, and the 2326server machine is @samp{faun.example.org}. On 2327faun, put the following line into the file 2328@file{.rhosts} in @samp{bach}'s home directory: 2329 2330@example 2331toe.example.com mozart 2332@end example 2333 2334@noindent 2335Then test that @samp{rsh} is working with 2336 2337@example 2338rsh -l bach faun.example.org 'echo $PATH' 2339@end example 2340 2341@cindex CVS_SERVER, environment variable 2342Next you have to make sure that @code{rsh} will be able 2343to find the server. Make sure that the path which 2344@code{rsh} printed in the above example includes the 2345directory containing a program named @code{cvs} which 2346is the server. You need to set the path in 2347@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 2348or @file{.profile}. Alternately, you can set the 2349environment variable @code{CVS_SERVER} on the client 2350machine to the filename of the server you want to use, 2351for example @file{/usr/local/bin/cvs-1.6}. 2352For the @code{ext} and @code{fork} methods, you may 2353also specify @var{CVS_SERVER} as an otpion in the 2354@var{CVSROOT} so that you may use different servers for 2355differnt roots. See @ref{Remote repositories} for more 2356details. 2357 2358There is no need to edit @file{inetd.conf} or start a 2359@sc{cvs} server daemon. 2360 2361@cindex :server:, setting up 2362@cindex :ext:, setting up 2363@cindex Kerberos, using kerberized rsh 2364@cindex SSH (rsh replacement) 2365@cindex rsh replacements (Kerberized, SSH, &c) 2366There are two access methods that you use in @code{CVSROOT} 2367for rsh. @code{:server:} specifies an internal rsh 2368client, which is supported only by some @sc{cvs} ports. 2369@code{:ext:} specifies an external rsh program. By 2370default this is @code{rsh} (unless otherwise specified 2371by the @file{--with-rsh} flag to configure) but you may set the 2372@code{CVS_RSH} environment variable to invoke another 2373program which can access the remote server (for 2374example, @code{remsh} on HP-UX 9 because @code{rsh} is 2375something different). It must be a program which can 2376transmit data to and from the server without modifying 2377it; for example the Windows NT @code{rsh} is not 2378suitable since it by default translates between CRLF 2379and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 2380to @code{rsh} to get around this, but since this could 2381potentially cause problems for programs other than the 2382standard @code{rsh}, it may change in the future. If 2383you set @code{CVS_RSH} to @code{SSH} or some other rsh 2384replacement, the instructions in the rest of this 2385section concerning @file{.rhosts} and so on are likely 2386to be inapplicable; consult the documentation for your rsh 2387replacement. 2388 2389You may choose to specify the @var{CVS_RSH} option as a method option 2390in the @var{CVSROOT} string to allow you to use different connection tools 2391for different roots (@pxref{The connection method}). For example, allowing 2392some roots to use @code{CVS_RSH=remsh} and some to use 2393@code{CVS_RSH=ssh} for the @code{ext} method. See also 2394the @ref{Remote repositories} for more details. 2395@c See also the comment in src/client.c for rationale 2396@c concerning "rsh" being the default and never 2397@c "remsh". 2398 2399Continuing our example, supposing you want to access 2400the module @file{foo} in the repository 2401@file{/usr/local/cvsroot/}, on machine 2402@file{faun.example.org}, you are ready to go: 2403 2404@example 2405cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2406@end example 2407 2408@noindent 2409(The @file{bach@@} can be omitted if the username is 2410the same on both the local and remote hosts.) 2411 2412@c Should we mention "rsh host echo hi" and "rsh host 2413@c cat" (the latter followed by typing text and ^D) 2414@c as troubleshooting techniques? Probably yes 2415@c (people tend to have trouble setting this up), 2416@c but this kind of thing can be hard to spell out. 2417 2418@node Password authenticated 2419@subsection Direct connection with password authentication 2420 2421The @sc{cvs} client can also connect to the server 2422using a password protocol. This is particularly useful 2423if using @code{rsh} is not feasible (for example, 2424the server is behind a firewall), and Kerberos also is 2425not available. 2426 2427 To use this method, it is necessary to make 2428some adjustments on both the server and client sides. 2429 2430@menu 2431* Password authentication server:: Setting up the server 2432* Password authentication client:: Using the client 2433* Password authentication security:: What this method does and does not do 2434@end menu 2435 2436@node Password authentication server 2437@subsubsection Setting up the server for password authentication 2438 2439First of all, you probably want to tighten the 2440permissions on the @file{$CVSROOT} and 2441@file{$CVSROOT/CVSROOT} directories. See @ref{Password 2442authentication security}, for more details. 2443 2444@cindex pserver (subcommand) 2445@cindex Remote repositories, port specification 2446@cindex Repositories, remote, port specification 2447@cindex Client/Server Operation, port specification 2448@cindex pserver (client/server connection method), port specification 2449@cindex kserver (client/server connection method), port specification 2450@cindex gserver (client/server connection method), port specification 2451@cindex port, specifying for remote repositories 2452@cindex Password server, setting up 2453@cindex Authenticating server, setting up 2454@cindex inetd, configuring for pserver 2455@cindex xinetd, configuring for pserver 2456@c FIXME: this isn't quite right regarding port 2457@c numbers; CVS looks up "cvspserver" in 2458@c /etc/services (on unix, but what about non-unix?). 2459On the server side, the file @file{/etc/inetd.conf} 2460needs to be edited so @code{inetd} knows to run the 2461command @code{cvs pserver} when it receives a 2462connection on the right port. By default, the port 2463number is 2401; it would be different if your client 2464were compiled with @code{CVS_AUTH_PORT} defined to 2465something else, though. This can also be specified in the CVSROOT variable 2466(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 2467environment variable (@pxref{Environment variables}). 2468 2469 If your @code{inetd} allows raw port numbers in 2470@file{/etc/inetd.conf}, then the following (all on a 2471single line in @file{inetd.conf}) should be sufficient: 2472 2473@example 24742401 stream tcp nowait root /usr/local/bin/cvs 2475cvs -f --allow-root=/usr/cvsroot pserver 2476@end example 2477 2478@noindent 2479(You could also use the 2480@samp{-T} option to specify a temporary directory.) 2481 2482The @samp{--allow-root} option specifies the allowable 2483@sc{cvsroot} directory. Clients which attempt to use a 2484different @sc{cvsroot} directory will not be allowed to 2485connect. If there is more than one @sc{cvsroot} 2486directory which you want to allow, repeat the option. 2487(Unfortunately, many versions of @code{inetd} have very small 2488limits on the number of arguments and/or the total length 2489of the command. The usual solution to this problem is 2490to have @code{inetd} run a shell script which then invokes 2491@sc{cvs} with the necessary arguments.) 2492 2493 If your @code{inetd} wants a symbolic service 2494name instead of a raw port number, then put this in 2495@file{/etc/services}: 2496 2497@example 2498cvspserver 2401/tcp 2499@end example 2500 2501@noindent 2502and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 2503 2504If your system uses @code{xinetd} instead of @code{inetd}, 2505the procedure is slightly different. 2506Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2507 2508@example 2509service cvspserver 2510@{ 2511 port = 2401 2512 socket_type = stream 2513 protocol = tcp 2514 wait = no 2515 user = root 2516 passenv = PATH 2517 server = /usr/local/bin/cvs 2518 server_args = -f --allow-root=/usr/cvsroot pserver 2519@} 2520@end example 2521 2522@noindent 2523(If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2524the @code{port} line.) 2525 2526 Once the above is taken care of, restart your 2527@code{inetd}, or do whatever is necessary to force it 2528to reread its initialization files. 2529 2530If you are having trouble setting this up, see 2531@ref{Connection}. 2532 2533@cindex CVS passwd file 2534@cindex passwd (admin file) 2535Because the client stores and transmits passwords in 2536cleartext (almost---see @ref{Password authentication 2537security}, for details), a separate @sc{cvs} password 2538file is generally used, so people don't compromise 2539their regular passwords when they access the 2540repository. This file is 2541@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 2542administrative files}). It uses a colon-separated 2543format, similar to @file{/etc/passwd} on Unix systems, 2544except that it has fewer fields: @sc{cvs} username, 2545optional password, and an optional system username for 2546@sc{cvs} to run as if authentication succeeds. Here is 2547an example @file{passwd} file with five entries: 2548 2549@example 2550anonymous: 2551bach:ULtgRLXo7NRxs 2552spwang:1sOp854gDF3DY 2553melissa:tGX1fS8sun6rY:pubcvs 2554qproj:XR4EZcEs0szik:pubcvs 2555@end example 2556 2557@noindent 2558(The passwords are encrypted according to the standard 2559Unix @code{crypt()} function, so it is possible to 2560paste in passwords directly from regular Unix 2561@file{/etc/passwd} files.) 2562 2563The first line in the example will grant access to any 2564@sc{cvs} client attempting to authenticate as user 2565@code{anonymous}, no matter what password they use, 2566including an empty password. (This is typical for 2567sites granting anonymous read-only access; for 2568information on how to do the "read-only" part, see 2569@ref{Read-only access}.) 2570 2571The second and third lines will grant access to 2572@code{bach} and @code{spwang} if they supply their 2573respective plaintext passwords. 2574 2575@cindex User aliases 2576The fourth line will grant access to @code{melissa}, if 2577she supplies the correct password, but her @sc{cvs} 2578operations will actually run on the server side under 2579the system user @code{pubcvs}. Thus, there need not be 2580any system user named @code{melissa}, but there 2581@emph{must} be one named @code{pubcvs}. 2582 2583The fifth line shows that system user identities can be 2584shared: any client who successfully authenticates as 2585@code{qproj} will actually run as @code{pubcvs}, just 2586as @code{melissa} does. That way you could create a 2587single, shared system user for each project in your 2588repository, and give each developer their own line in 2589the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 2590username on each line would be different, but the 2591system username would be the same. The reason to have 2592different @sc{cvs} usernames is that @sc{cvs} will log their 2593actions under those names: when @code{melissa} commits 2594a change to a project, the checkin is recorded in the 2595project's history under the name @code{melissa}, not 2596@code{pubcvs}. And the reason to have them share a 2597system username is so that you can arrange permissions 2598in the relevant area of the repository such that only 2599that account has write-permission there. 2600 2601If the system-user field is present, all 2602password-authenticated @sc{cvs} commands run as that 2603user; if no system user is specified, @sc{cvs} simply 2604takes the @sc{cvs} username as the system username and 2605runs commands as that user. In either case, if there 2606is no such user on the system, then the @sc{cvs} 2607operation will fail (regardless of whether the client 2608supplied a valid password). 2609 2610The password and system-user fields can both be omitted 2611(and if the system-user field is omitted, then also 2612omit the colon that would have separated it from the 2613encrypted password). For example, this would be a 2614valid @file{$CVSROOT/CVSROOT/passwd} file: 2615 2616@example 2617anonymous::pubcvs 2618fish:rKa5jzULzmhOo:kfogel 2619sussman:1sOp854gDF3DY 2620@end example 2621 2622@noindent 2623When the password field is omitted or empty, then the 2624client's authentication attempt will succeed with any 2625password, including the empty string. However, the 2626colon after the @sc{cvs} username is always necessary, 2627even if the password is empty. 2628 2629@sc{cvs} can also fall back to use system authentication. 2630When authenticating a password, the server first checks 2631for the user in the @file{$CVSROOT/CVSROOT/passwd} 2632file. If it finds the user, it will use that entry for 2633authentication as described above. But if it does not 2634find the user, or if the @sc{cvs} @file{passwd} file 2635does not exist, then the server can try to authenticate 2636the username and password using the operating system's 2637user-lookup routines (this "fallback" behavior can be 2638disabled by setting @code{SystemAuth=no} in the 2639@sc{cvs} @file{config} file, @pxref{config}). 2640 2641The default fallback behavior is to look in 2642@file{/etc/passwd} for this system user unless your 2643system has PAM (Pluggable Authentication Modules) 2644and your @sc{cvs} server executable was configured to 2645use it at compile time (using @code{./configure --enable-pam} - see the 2646INSTALL file for more). In this case, PAM will be consulted instead. 2647This means that @sc{cvs} can be configured to use any password 2648authentication source PAM can be configured to use (possibilities 2649include a simple UNIX password, NIS, LDAP, and others) in its 2650global configuration file (usually @file{/etc/pam.conf} 2651or possibly @file{/etc/pam.d/cvs}). See your PAM documentation 2652for more details on PAM configuration. 2653 2654Note that PAM is an experimental feature in @sc{cvs} and feedback is 2655encouraged. Please send a mail to one of the @sc{cvs} mailing lists 2656(@code{info-cvs@@nongnu.org} or @code{bug-cvs@@nongnu.org}) if you use the 2657@sc{cvs} PAM support. 2658 2659@strong{WARNING: Using PAM gives the system administrator much more 2660flexibility about how @sc{cvs} users are authenticated but 2661no more security than other methods. See below for more.} 2662 2663CVS needs an "auth", "account" and "session" module in the 2664PAM configuration file. A typical PAM configuration 2665would therefore have the following lines 2666in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 2667system @file{/etc/passwd} authentication: 2668 2669@example 2670cvs auth required pam_unix.so 2671cvs account required pam_unix.so 2672cvs session required pam_unix.so 2673@end example 2674 2675The the equivalent @file{/etc/pam.d/cvs} would contain 2676 2677@example 2678auth required pam_unix.so 2679account required pam_unix.so 2680session required pam_unix.so 2681@end example 2682 2683Some systems require a full path to the module so that 2684@file{pam_unix.so} (Linux) would become something like 2685@file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris). 2686See the @file{contrib/pam} subdirectory of the @sc{cvs} 2687source distribution for further example configurations. 2688 2689The PAM service name given above as "cvs" is just 2690the service name in the default configuration and can be 2691set using 2692@code{./configure --with-hardcoded-pam-service-name=<pam-service-name>} 2693before compiling. @sc{cvs} can also be configured to use whatever 2694name it is invoked as as its PAM service name using 2695@code{./configure --without-hardcoded-pam-service-name}, but this 2696feature should not be used if you may not have control of the name 2697@sc{cvs} will be invoked as. 2698 2699Be aware, also, that falling back to system 2700authentication might be a security risk: @sc{cvs} 2701operations would then be authenticated with that user's 2702regular login password, and the password flies across 2703the network in plaintext. See @ref{Password 2704authentication security} for more on this. 2705This may be more of a problem with PAM authentication 2706because it is likely that the source of the system 2707password is some central authentication service like 2708LDAP which is also used to authenticate other services. 2709 2710On the other hand, PAM makes it very easy to change your password 2711regularly. If they are given the option of a one-password system for 2712all of their activities, users are often more willing to change their 2713password on a regular basis. 2714 2715In the non-PAM configuration where the password is stored in the 2716@file{CVSROOT/passwd} file, it is difficult to change passwords on a 2717regular basis since only administrative users (or in some cases 2718processes that act as an administrative user) are typically given 2719access to modify this file. Either there needs to be some 2720hand-crafted web page or set-uid program to update the file, or the 2721update needs to be done by submitting a request to an administrator to 2722perform the duty by hand. In the first case, having to remember to 2723update a separate password on a periodic basis can be difficult. In 2724the second case, the manual nature of the change will typically mean 2725that the password will not be changed unless it is absolutely 2726necessary. 2727 2728Note that PAM administrators should probably avoid configuring 2729one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If 2730OTPs are desired, the administrator may wish to encourage the use of 2731one of the other Client/Server access methods. See the section on 2732@pxref{Remote repositories} for a list of other methods. 2733 2734Right now, the only way to put a password in the 2735@sc{cvs} @file{passwd} file is to paste it there from 2736somewhere else. Someday, there may be a @code{cvs 2737passwd} command. 2738 2739Unlike many of the files in @file{$CVSROOT/CVSROOT}, it 2740is normal to edit the @file{passwd} file in-place, 2741rather than via @sc{cvs}. This is because of the 2742possible security risks of having the @file{passwd} 2743file checked out to people's working copies. If you do 2744want to include the @file{passwd} file in checkouts of 2745@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 2746 2747@c We might also suggest using the @code{htpasswd} command 2748@c from freely available web servers as well, but that 2749@c would open up a can of worms in that the users next 2750@c questions are likely to be "where do I get it?" and 2751@c "how do I use it?" 2752@c Also note that htpasswd, at least the version I had, 2753@c likes to clobber the third field. 2754 2755@node Password authentication client 2756@subsubsection Using the client with password authentication 2757@cindex Login (subcommand) 2758@cindex Password client, using 2759@cindex Authenticated client, using 2760@cindex :pserver:, setting up 2761To run a @sc{cvs} command on a remote repository via 2762the password-authenticating server, one specifies the 2763@code{pserver} protocol, optional username, repository host, an 2764optional port number, and path to the repository. For example: 2765 2766@example 2767cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 2768@end example 2769 2770@noindent 2771or 2772 2773@example 2774CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 2775cvs checkout someproj 2776@end example 2777 2778However, unless you're connecting to a public-access 2779repository (i.e., one where that username doesn't 2780require a password), you'll need to supply a password or @dfn{log in} first. 2781Logging in verifies your password with the repository and stores it in a file. 2782It's done with the @code{login} command, which will 2783prompt you interactively for the password if you didn't supply one as part of 2784@var{$CVSROOT}: 2785 2786@example 2787cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 2788CVS password: 2789@end example 2790 2791@noindent 2792or 2793 2794@example 2795cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 2796@end example 2797 2798After you enter the password, @sc{cvs} verifies it with 2799the server. If the verification succeeds, then that 2800combination of username, host, repository, and password 2801is permanently recorded, so future transactions with 2802that repository won't require you to run @code{cvs 2803login}. (If verification fails, @sc{cvs} will exit 2804complaining that the password was incorrect, and 2805nothing will be recorded.) 2806 2807The records are stored, by default, in the file 2808@file{$HOME/.cvspass}. That file's format is 2809human-readable, and to a degree human-editable, but 2810note that the passwords are not stored in 2811cleartext---they are trivially encoded to protect them 2812from "innocent" compromise (i.e., inadvertent viewing 2813by a system administrator or other non-malicious 2814person). 2815 2816@cindex CVS_PASSFILE, environment variable 2817You can change the default location of this file by 2818setting the @code{CVS_PASSFILE} environment variable. 2819If you use this variable, make sure you set it 2820@emph{before} @code{cvs login} is run. If you were to 2821set it after running @code{cvs login}, then later 2822@sc{cvs} commands would be unable to look up the 2823password for transmission to the server. 2824 2825Once you have logged in, all @sc{cvs} commands using 2826that remote repository and username will authenticate 2827with the stored password. So, for example 2828 2829@example 2830cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2831@end example 2832 2833@noindent 2834should just work (unless the password changes on the 2835server side, in which case you'll have to re-run 2836@code{cvs login}). 2837 2838Note that if the @samp{:pserver:} were not present in 2839the repository specification, @sc{cvs} would assume it 2840should use @code{rsh} to connect with the server 2841instead (@pxref{Connecting via rsh}). 2842 2843Of course, once you have a working copy checked out and 2844are running @sc{cvs} commands from within it, there is 2845no longer any need to specify the repository 2846explicitly, because @sc{cvs} can deduce the repository 2847from the working copy's @file{CVS} subdirectory. 2848 2849@c FIXME: seems to me this needs somewhat more 2850@c explanation. 2851@cindex Logout (subcommand) 2852The password for a given remote repository can be 2853removed from the @code{CVS_PASSFILE} by using the 2854@code{cvs logout} command. 2855 2856@node Password authentication security 2857@subsubsection Security considerations with password authentication 2858 2859@cindex Security, of pserver 2860The passwords are stored on the client side in a 2861trivial encoding of the cleartext, and transmitted in 2862the same encoding. The encoding is done only to 2863prevent inadvertent password compromises (i.e., a 2864system administrator accidentally looking at the file), 2865and will not prevent even a naive attacker from gaining 2866the password. 2867 2868@c FIXME: The bit about "access to the repository 2869@c implies general access to the system is *not* specific 2870@c to pserver; it applies to kerberos and SSH and 2871@c everything else too. Should reorganize the 2872@c documentation to make this clear. 2873The separate @sc{cvs} password file (@pxref{Password 2874authentication server}) allows people 2875to use a different password for repository access than 2876for login access. On the other hand, once a user has 2877non-read-only 2878access to the repository, she can execute programs on 2879the server system through a variety of means. Thus, repository 2880access implies fairly broad system access as well. It 2881might be possible to modify @sc{cvs} to prevent that, 2882but no one has done so as of this writing. 2883@c OpenBSD uses chroot() and copies the repository to 2884@c provide anonymous read-only access (for details see 2885@c http://www.openbsd.org/anoncvs.shar). While this 2886@c closes the most obvious holes, I'm not sure it 2887@c closes enough holes to recommend it (plus it is 2888@c *very* easy to accidentally screw up a setup of this 2889@c type). 2890 2891Note that because the @file{$CVSROOT/CVSROOT} directory 2892contains @file{passwd} and other files which are used 2893to check security, you must control the permissions on 2894this directory as tightly as the permissions on 2895@file{/etc}. The same applies to the @file{$CVSROOT} 2896directory itself and any directory 2897above it in the tree. Anyone who has write access to 2898such a directory will have the ability to become any 2899user on the system. Note that these permissions are 2900typically tighter than you would use if you are not 2901using pserver. 2902@c TODO: Would be really nice to document/implement a 2903@c scheme where the CVS server can run as some non-root 2904@c user, e.g. "cvs". CVSROOT/passwd would contain a 2905@c bunch of entries of the form foo:xxx:cvs (or the "cvs" 2906@c would be implicit). This would greatly reduce 2907@c security risks such as those hinted at in the 2908@c previous paragraph. I think minor changes to CVS 2909@c might be required but mostly this would just need 2910@c someone who wants to play with it, document it, &c. 2911 2912In summary, anyone who gets the password gets 2913repository access (which may imply some measure of general system 2914access as well). The password is available to anyone 2915who can sniff network packets or read a protected 2916(i.e., user read-only) file. If you want real 2917security, get Kerberos. 2918 2919@node GSSAPI authenticated 2920@subsection Direct connection with GSSAPI 2921 2922@cindex GSSAPI 2923@cindex Security, GSSAPI 2924@cindex :gserver:, setting up 2925@cindex Kerberos, using :gserver: 2926GSSAPI is a generic interface to network security 2927systems such as Kerberos 5. 2928If you have a working GSSAPI library, you can have 2929@sc{cvs} connect via a direct @sc{tcp} connection, 2930authenticating with GSSAPI. 2931 2932To do this, @sc{cvs} needs to be compiled with GSSAPI 2933support; when configuring @sc{cvs} it tries to detect 2934whether GSSAPI libraries using Kerberos version 5 are 2935present. You can also use the @file{--with-gssapi} 2936flag to configure. 2937 2938The connection is authenticated using GSSAPI, but the 2939message stream is @emph{not} authenticated by default. 2940You must use the @code{-a} global option to request 2941stream authentication. 2942 2943The data transmitted is @emph{not} encrypted by 2944default. Encryption support must be compiled into both 2945the client and the server; use the 2946@file{--enable-encrypt} configure option to turn it on. 2947You must then use the @code{-x} global option to 2948request encryption. 2949 2950GSSAPI connections are handled on the server side by 2951the same server which handles the password 2952authentication server; see @ref{Password authentication 2953server}. If you are using a GSSAPI mechanism such as 2954Kerberos which provides for strong authentication, you 2955will probably want to disable the ability to 2956authenticate via cleartext passwords. To do so, create 2957an empty @file{CVSROOT/passwd} password file, and set 2958@code{SystemAuth=no} in the config file 2959(@pxref{config}). 2960 2961The GSSAPI server uses a principal name of 2962cvs/@var{hostname}, where @var{hostname} is the 2963canonical name of the server host. You will have to 2964set this up as required by your GSSAPI mechanism. 2965 2966To connect using GSSAPI, use the @samp{:gserver:} method. For 2967example, 2968 2969@example 2970cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 2971@end example 2972 2973@node Kerberos authenticated 2974@subsection Direct connection with Kerberos 2975 2976@cindex Kerberos, using :kserver: 2977@cindex Security, Kerberos 2978@cindex :kserver:, setting up 2979The easiest way to use Kerberos is to use the Kerberos 2980@code{rsh}, as described in @ref{Connecting via rsh}. 2981The main disadvantage of using rsh is that all the data 2982needs to pass through additional programs, so it may be 2983slower. So if you have Kerberos installed you can 2984connect via a direct @sc{tcp} connection, 2985authenticating with Kerberos. 2986 2987This section concerns the Kerberos network security 2988system, version 4. Kerberos version 5 is supported via 2989the GSSAPI generic network security interface, as 2990described in the previous section. 2991 2992To do this, @sc{cvs} needs to be compiled with Kerberos 2993support; when configuring @sc{cvs} it tries to detect 2994whether Kerberos is present or you can use the 2995@file{--with-krb4} flag to configure. 2996 2997The data transmitted is @emph{not} encrypted by 2998default. Encryption support must be compiled into both 2999the client and server; use the 3000@file{--enable-encryption} configure option to turn it 3001on. You must then use the @code{-x} global option to 3002request encryption. 3003 3004The CVS client will attempt to connect to port 1999 by default. 3005 3006@cindex kinit 3007When you want to use @sc{cvs}, get a ticket in the 3008usual way (generally @code{kinit}); it must be a ticket 3009which allows you to log into the server machine. Then 3010you are ready to go: 3011 3012@example 3013cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 3014@end example 3015 3016Previous versions of @sc{cvs} would fall back to a 3017connection via rsh; this version will not do so. 3018 3019@node Connecting via fork 3020@subsection Connecting with fork 3021 3022@cindex fork, access method 3023@cindex :fork:, setting up 3024This access method allows you to connect to a 3025repository on your local disk via the remote protocol. 3026In other words it does pretty much the same thing as 3027@code{:local:}, but various quirks, bugs and the like are 3028those of the remote @sc{cvs} rather than the local 3029@sc{cvs}. 3030 3031For day-to-day operations you might prefer either 3032@code{:local:} or @code{:fork:}, depending on your 3033preferences. Of course @code{:fork:} comes in 3034particularly handy in testing or 3035debugging @code{cvs} and the remote protocol. 3036Specifically, we avoid all of the network-related 3037setup/configuration, timeouts, and authentication 3038inherent in the other remote access methods but still 3039create a connection which uses the remote protocol. 3040 3041To connect using the @code{fork} method, use 3042@samp{:fork:} and the pathname to your local 3043repository. For example: 3044 3045@example 3046cvs -d :fork:/usr/local/cvsroot checkout foo 3047@end example 3048 3049@cindex CVS_SERVER, and :fork: 3050As with @code{:ext:}, the server is called @samp{cvs} 3051by default, or the value of the @code{CVS_SERVER} 3052environment variable. 3053 3054 3055@node Write proxies 3056@subsection Distributing load across several CVS servers 3057 3058@cindex PrimaryServer, in CVSROOT/config 3059@cindex Primary server 3060@cindex Secondary server 3061@cindex proxy, write 3062@cindex write proxy 3063@sc{cvs} can be configured to distribute usage across several @sc{cvs} 3064servers. This is accomplished by means of one or more @dfn{write proxies}, or 3065@dfn{secondary servers}, for a single @dfn{primary server}. 3066 3067When a @sc{cvs} client accesses a secondary server and only sends read 3068requests, then the secondary server handles the entire request. If the client 3069sends any write requests, however, the secondary server asks the client to 3070redirect its write request to the primary server, if the client supports 3071redirect requests, and otherwise becomes a transparent proxy for the primary 3072server, which actually handles the write request. 3073 3074In this manner, any number of read-only secondary servers may be configured as 3075write proxies for the primary server, effectively distributing the load from 3076all read operations between the secondary servers and restricting the load on 3077the primary server to write operations and pushing changes to the secondaries. 3078 3079Primary servers will not automatically push changes to secondaries. This must 3080be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, & 3081@file{postwatch} scripts (@pxref{Trigger Scripts}) like the following: 3082 3083@example 3084ALL rsync -gopr -essh ./ secondary:/cvsroot/%p & 3085@end example 3086 3087You would probably actually want to lock directories for write on the secondary 3088and for read on the primary before running the @samp{rsync} in the above 3089example, but describing such a setup is beyond the scope of this document. 3090 3091A secondary advantage of a write proxy setup is that users pointing at the 3092secondary server can still execute fast read operations while on a network that 3093connects to the primary over a slow link or even one where the link to the 3094primary is periodically broken. Only write operations will require the network 3095link to the primary. 3096 3097To configure write proxies, the primary must be specified with the 3098@samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}). For the 3099transparent proxy mode to work, all secondary servers must also be running the 3100same version of the @sc{cvs} server, or at least one that provides the same 3101list of supported requests to the client as the primary server. This is not 3102necessary for redirection. 3103 3104Once a primary server is configured, secondary servers may be configured by: 3105 3106@enumerate 3107@item 3108Duplicating the primary repository at the new location. 3109@item 3110Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and 3111@file{postwatch} files on the primary to propagate writes to the new secondary. 3112@item 3113Configure remote access to the secondary(ies) as you would configure access 3114to any other CVS server (@pxref{Remote repositories}). 3115@item 3116Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to 3117@strong{all} incovations of the secondary server if the path to the @sc{cvs} 3118repository directory is different on the two servers and you wish to support 3119clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier 3120clients do not handle the @samp{Redirect} response). 3121 3122Please note, again, that writethrough proxy suport requires 3123@code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all} 3124incovations of the secondary server, not just @samp{pserver} invocations. 3125This may require a wrapper script for the @sc{cvs} executable 3126on your server machine. 3127@end enumerate 3128 3129 3130@c --------------------------------------------------------------------- 3131@node Read-only access 3132@section Read-only repository access 3133@cindex Read-only repository access 3134@cindex readers (admin file) 3135@cindex writers (admin file) 3136 3137 It is possible to grant read-only repository 3138access to people using the password-authenticated 3139server (@pxref{Password authenticated}). (The 3140other access methods do not have explicit support for 3141read-only users because those methods all assume login 3142access to the repository machine anyway, and therefore 3143the user can do whatever local file permissions allow 3144her to do.) 3145 3146 A user who has read-only access can do only 3147those @sc{cvs} operations which do not modify the 3148repository, except for certain ``administrative'' files 3149(such as lock files and the history file). It may be 3150desirable to use this feature in conjunction with 3151user-aliasing (@pxref{Password authentication server}). 3152 3153Unlike with previous versions of @sc{cvs}, read-only 3154users should be able merely to read the repository, and 3155not to execute programs on the server or otherwise gain 3156unexpected levels of access. Or to be more accurate, 3157the @emph{known} holes have been plugged. Because this 3158feature is new and has not received a comprehensive 3159security audit, you should use whatever level of 3160caution seems warranted given your attitude concerning 3161security. 3162 3163 There are two ways to specify read-only access 3164for a user: by inclusion, and by exclusion. 3165 3166 "Inclusion" means listing that user 3167specifically in the @file{$CVSROOT/CVSROOT/readers} 3168file, which is simply a newline-separated list of 3169users. Here is a sample @file{readers} file: 3170 3171@example 3172melissa 3173splotnik 3174jrandom 3175@end example 3176 3177@noindent 3178 (Don't forget the newline after the last user.) 3179 3180 "Exclusion" means explicitly listing everyone 3181who has @emph{write} access---if the file 3182 3183@example 3184$CVSROOT/CVSROOT/writers 3185@end example 3186 3187@noindent 3188exists, then only 3189those users listed in it have write access, and 3190everyone else has read-only access (of course, even the 3191read-only users still need to be listed in the 3192@sc{cvs} @file{passwd} file). The 3193@file{writers} file has the same format as the 3194@file{readers} file. 3195 3196 Note: if your @sc{cvs} @file{passwd} 3197file maps cvs users onto system users (@pxref{Password 3198authentication server}), make sure you deny or grant 3199read-only access using the @emph{cvs} usernames, not 3200the system usernames. That is, the @file{readers} and 3201@file{writers} files contain cvs usernames, which may 3202or may not be the same as system usernames. 3203 3204 Here is a complete description of the server's 3205behavior in deciding whether to grant read-only or 3206read-write access: 3207 3208 If @file{readers} exists, and this user is 3209listed in it, then she gets read-only access. Or if 3210@file{writers} exists, and this user is NOT listed in 3211it, then she also gets read-only access (this is true 3212even if @file{readers} exists but she is not listed 3213there). Otherwise, she gets full read-write access. 3214 3215 Of course there is a conflict if the user is 3216listed in both files. This is resolved in the more 3217conservative way, it being better to protect the 3218repository too much than too little: such a user gets 3219read-only access. 3220 3221@node Server temporary directory 3222@section Temporary directories for the server 3223@cindex Temporary directories, and server 3224@cindex Server, temporary directories 3225 3226While running, the @sc{cvs} server creates temporary 3227directories. They are named 3228 3229@example 3230cvs-serv@var{pid} 3231@end example 3232 3233@noindent 3234where @var{pid} is the process identification number of 3235the server. 3236They are located in the directory specified by 3237the @samp{-T} global option (@pxref{Global options}), 3238the @code{TMPDIR} environment variable (@pxref{Environment variables}), 3239or, failing that, @file{/tmp}. 3240 3241In most cases the server will remove the temporary 3242directory when it is done, whether it finishes normally 3243or abnormally. However, there are a few cases in which 3244the server does not or cannot remove the temporary 3245directory, for example: 3246 3247@itemize @bullet 3248@item 3249If the server aborts due to an internal server error, 3250it may preserve the directory to aid in debugging 3251 3252@item 3253If the server is killed in a way that it has no way of 3254cleaning up (most notably, @samp{kill -KILL} on unix). 3255 3256@item 3257If the system shuts down without an orderly shutdown, 3258which tells the server to clean up. 3259@end itemize 3260 3261In cases such as this, you will need to manually remove 3262the @file{cvs-serv@var{pid}} directories. As long as 3263there is no server running with process identification 3264number @var{pid}, it is safe to do so. 3265 3266@c --------------------------------------------------------------------- 3267@node Starting a new project 3268@chapter Starting a project with CVS 3269@cindex Starting a project with CVS 3270@cindex Creating a project 3271 3272@comment --moduledb-- 3273Because renaming files and moving them between 3274directories is somewhat inconvenient, the first thing 3275you do when you start a new project should be to think 3276through your file organization. It is not impossible 3277to rename or move files, but it does increase the 3278potential for confusion and @sc{cvs} does have some 3279quirks particularly in the area of renaming 3280directories. @xref{Moving files}. 3281 3282What to do next depends on the situation at hand. 3283 3284@menu 3285* Setting up the files:: Getting the files into the repository 3286* Defining the module:: How to make a module of the files 3287@end menu 3288@c -- File permissions! 3289 3290@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3291@node Setting up the files 3292@section Setting up the files 3293 3294The first step is to create the files inside the repository. This can 3295be done in a couple of different ways. 3296 3297@c -- The contributed scripts 3298@menu 3299* From files:: This method is useful with old projects 3300 where files already exists. 3301* From other version control systems:: Old projects where you want to 3302 preserve history from another system. 3303* From scratch:: Creating a directory tree from scratch. 3304@end menu 3305 3306@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3307@node From files 3308@subsection Creating a directory tree from a number of files 3309@cindex Importing files 3310 3311When you begin using @sc{cvs}, you will probably already have several 3312projects that can be 3313put under @sc{cvs} control. In these cases the easiest way is to use the 3314@code{import} command. An example is probably the easiest way to 3315explain how to use it. If the files you want to install in 3316@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 3317repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 3318 3319@example 3320$ cd @var{wdir} 3321$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 3322@end example 3323 3324Unless you supply a log message with the @samp{-m} 3325flag, @sc{cvs} starts an editor and prompts for a 3326message. The string @samp{yoyo} is a @dfn{vendor tag}, 3327and @samp{start} is a @dfn{release tag}. They may fill 3328no purpose in this context, but since @sc{cvs} requires 3329them they must be present. @xref{Tracking sources}, for 3330more information about them. 3331 3332You can now verify that it worked, and remove your 3333original source directory. 3334@c FIXME: Need to say more about "verify that it 3335@c worked". What should the user look for in the output 3336@c from "diff -r"? 3337 3338@example 3339$ cd .. 3340$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 3341$ diff -r @var{wdir} yoyodyne/@var{rdir} 3342$ rm -r @var{wdir} 3343@end example 3344 3345@noindent 3346Erasing the original sources is a good idea, to make sure that you do 3347not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 3348Of course, it would be wise to make sure that you have 3349a backup of the sources before you remove them. 3350 3351The @code{checkout} command can either take a module 3352name as argument (as it has done in all previous 3353examples) or a path name relative to @code{$CVSROOT}, 3354as it did in the example above. 3355 3356It is a good idea to check that the permissions 3357@sc{cvs} sets on the directories inside @code{$CVSROOT} 3358are reasonable, and that they belong to the proper 3359groups. @xref{File permissions}. 3360 3361If some of the files you want to import are binary, you 3362may want to use the wrappers features to specify which 3363files are binary and which are not. @xref{Wrappers}. 3364 3365@c The node name is too long, but I am having trouble 3366@c thinking of something more concise. 3367@node From other version control systems 3368@subsection Creating Files From Other Version Control Systems 3369@cindex Importing files, from other version control systems 3370 3371If you have a project which you are maintaining with 3372another version control system, such as @sc{rcs}, you 3373may wish to put the files from that project into 3374@sc{cvs}, and preserve the revision history of the 3375files. 3376 3377@table @asis 3378@cindex RCS, importing files from 3379@item From RCS 3380If you have been using @sc{rcs}, find the @sc{rcs} 3381files---usually a file named @file{foo.c} will have its 3382@sc{rcs} file in @file{RCS/foo.c,v} (but it could be 3383other places; consult the @sc{rcs} documentation for 3384details). Then create the appropriate directories in 3385@sc{cvs} if they do not already exist. Then copy the 3386files into the appropriate directories in the @sc{cvs} 3387repository (the name in the repository must be the name 3388of the source file with @samp{,v} added; the files go 3389directly in the appropriate directory of the repository, 3390not in an @file{RCS} subdirectory). This is one of the 3391few times when it is a good idea to access the @sc{cvs} 3392repository directly, rather than using @sc{cvs} 3393commands. Then you are ready to check out a new 3394working directory. 3395@c Someday there probably should be a "cvs import -t 3396@c rcs" or some such. It could even create magic 3397@c branches. It could also do something about the case 3398@c where the RCS file had a (non-magic) "0" branch. 3399 3400The @sc{rcs} file should not be locked when you move it 3401into @sc{cvs}; if it is, @sc{cvs} will have trouble 3402letting you operate on it. 3403@c What is the easiest way to unlock your files if you 3404@c have them locked? Especially if you have a lot of them? 3405@c This is a CVS bug/misfeature; importing RCS files 3406@c should ignore whether they are locked and leave them in 3407@c an unlocked state. Yet another reason for a separate 3408@c "import RCS file" command. 3409 3410@c How many is "many"? Or do they just import RCS files? 3411@item From another version control system 3412Many version control systems have the ability to export 3413@sc{rcs} files in the standard format. If yours does, 3414export the @sc{rcs} files and then follow the above 3415instructions. 3416 3417Failing that, probably your best bet is to write a 3418script that will check out the files one revision at a 3419time using the command line interface to the other 3420system, and then check the revisions into @sc{cvs}. 3421The @file{sccs2rcs} script mentioned below may be a 3422useful example to follow. 3423 3424@cindex SCCS, importing files from 3425@item From SCCS 3426There is a script in the @file{contrib} directory of 3427the @sc{cvs} source distribution called @file{sccs2rcs} 3428which converts @sc{sccs} files to @sc{rcs} files. 3429Note: you must run it on a machine which has both 3430@sc{sccs} and @sc{rcs} installed, and like everything 3431else in contrib it is unsupported (your mileage may 3432vary). 3433 3434@cindex PVCS, importing files from 3435@item From PVCS 3436There is a script in the @file{contrib} directory of 3437the @sc{cvs} source distribution called @file{pvcs_to_rcs} 3438which converts @sc{pvcs} archives to @sc{rcs} files. 3439You must run it on a machine which has both 3440@sc{pvcs} and @sc{rcs} installed, and like everything 3441else in contrib it is unsupported (your mileage may 3442vary). See the comments in the script for details. 3443@end table 3444@c CMZ and/or PATCHY were systems that were used in the 3445@c high energy physics community (especially for 3446@c CERNLIB). CERN has replaced them with CVS, but the 3447@c CAR format seems to live on as a way to submit 3448@c changes. There is a program car2cvs which converts 3449@c but I'm not sure where one gets a copy. 3450@c Not sure it is worth mentioning here, since it would 3451@c appear to affect only one particular community. 3452@c Best page for more information is: 3453@c http://wwwcn1.cern.ch/asd/cvs/index.html 3454@c See also: 3455@c http://ecponion.cern.ch/ecpsa/cernlib.html 3456 3457@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3458@node From scratch 3459@subsection Creating a directory tree from scratch 3460 3461@c Also/instead should be documenting 3462@c $ cvs co -l . 3463@c $ mkdir tc 3464@c $ cvs add tc 3465@c $ cd tc 3466@c $ mkdir man 3467@c $ cvs add man 3468@c etc. 3469@c Using import to create the directories only is 3470@c probably a somewhat confusing concept. 3471For a new project, the easiest thing to do is probably 3472to create an empty directory structure, like this: 3473 3474@example 3475$ mkdir tc 3476$ mkdir tc/man 3477$ mkdir tc/testing 3478@end example 3479 3480After that, you use the @code{import} command to create 3481the corresponding (empty) directory structure inside 3482the repository: 3483 3484@example 3485$ cd tc 3486$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 3487@end example 3488 3489This will add yoyodyne/@var{dir} as a directory under 3490@code{$CVSROOT}. 3491 3492Use @code{checkout} to get the new project. Then, use @code{add} 3493to add files (and new directories) as needed. 3494 3495@example 3496$ cd .. 3497$ cvs co yoyodyne/@var{dir} 3498@end example 3499 3500Check that the permissions @sc{cvs} sets on the 3501directories inside @code{$CVSROOT} are reasonable. 3502 3503@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3504@node Defining the module 3505@section Defining the module 3506@cindex Defining a module 3507@cindex Editing the modules file 3508@cindex Module, defining 3509@cindex Modules file, changing 3510 3511The next step is to define the module in the 3512@file{modules} file. This is not strictly necessary, 3513but modules can be convenient in grouping together 3514related files and directories. 3515 3516In simple cases these steps are sufficient to define a module. 3517 3518@enumerate 3519@item 3520Get a working copy of the modules file. 3521 3522@example 3523$ cvs checkout CVSROOT/modules 3524$ cd CVSROOT 3525@end example 3526 3527@item 3528Edit the file and insert a line that defines the module. @xref{Intro 3529administrative files}, for an introduction. @xref{modules}, for a full 3530description of the modules file. You can use the 3531following line to define the module @samp{tc}: 3532 3533@example 3534tc yoyodyne/tc 3535@end example 3536 3537@item 3538Commit your changes to the modules file. 3539 3540@example 3541$ cvs commit -m "Added the tc module." modules 3542@end example 3543 3544@item 3545Release the modules module. 3546 3547@example 3548$ cd .. 3549$ cvs release -d CVSROOT 3550@end example 3551@end enumerate 3552 3553@c --------------------------------------------------------------------- 3554@node Revisions 3555@chapter Revisions 3556 3557For many uses of @sc{cvs}, one doesn't need to worry 3558too much about revision numbers; @sc{cvs} assigns 3559numbers such as @code{1.1}, @code{1.2}, and so on, and 3560that is all one needs to know. However, some people 3561prefer to have more knowledge and control concerning 3562how @sc{cvs} assigns revision numbers. 3563 3564If one wants to keep track of a set of revisions 3565involving more than one file, such as which revisions 3566went into a particular release, one uses a @dfn{tag}, 3567which is a symbolic revision which can be assigned to a 3568numeric revision in each file. 3569 3570@menu 3571* Revision numbers:: The meaning of a revision number 3572* Versions revisions releases:: Terminology used in this manual 3573* Assigning revisions:: Assigning revisions 3574* Tags:: Tags--Symbolic revisions 3575* Tagging the working directory:: The cvs tag command 3576* Tagging by date/tag:: The cvs rtag command 3577* Modifying tags:: Adding, renaming, and deleting tags 3578* Tagging add/remove:: Tags with adding and removing files 3579* Sticky tags:: Certain tags are persistent 3580@end menu 3581 3582@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3583@node Revision numbers 3584@section Revision numbers 3585@cindex Revision numbers 3586@cindex Revision tree 3587@cindex Linear development 3588@cindex Number, revision- 3589@cindex Decimal revision number 3590@cindex Branch number 3591@cindex Number, branch 3592 3593Each version of a file has a unique @dfn{revision 3594number}. Revision numbers look like @samp{1.1}, 3595@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 3596A revision number always has an even number of 3597period-separated decimal integers. By default revision 35981.1 is the first revision of a file. Each successive 3599revision is given a new number by increasing the 3600rightmost number by one. The following figure displays 3601a few revisions, with newer revisions to the right. 3602 3603@example 3604 +-----+ +-----+ +-----+ +-----+ +-----+ 3605 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 3606 +-----+ +-----+ +-----+ +-----+ +-----+ 3607@end example 3608 3609It is also possible to end up with numbers containing 3610more than one period, for example @samp{1.3.2.2}. Such 3611revisions represent revisions on branches 3612(@pxref{Branching and merging}); such revision numbers 3613are explained in detail in @ref{Branches and 3614revisions}. 3615 3616@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3617@node Versions revisions releases 3618@section Versions, revisions and releases 3619@cindex Revisions, versions and releases 3620@cindex Versions, revisions and releases 3621@cindex Releases, revisions and versions 3622 3623A file can have several versions, as described above. 3624Likewise, a software product can have several versions. 3625A software product is often given a version number such 3626as @samp{4.1.1}. 3627 3628Versions in the first sense are called @dfn{revisions} 3629in this document, and versions in the second sense are 3630called @dfn{releases}. To avoid confusion, the word 3631@dfn{version} is almost never used in this document. 3632 3633@node Assigning revisions 3634@section Assigning revisions 3635 3636@c We avoid the "major revision" terminology. It seems 3637@c like jargon. Hopefully "first number" is clear enough. 3638@c 3639@c Well, in the context of software release numbers, 3640@c "major" and "minor" release or version numbers are 3641@c documented in at least the GNU Coding Standards, but I'm 3642@c still not sure I find that a valid reason to apply the 3643@c terminology to RCS revision numbers. "First", "Second", 3644@c "subsequent", and so on is almost surely clearer, 3645@c especially to a novice reader. -DRP 3646By default, @sc{cvs} will assign numeric revisions by 3647leaving the first number the same and incrementing the 3648second number. For example, @code{1.1}, @code{1.2}, 3649@code{1.3}, etc. 3650 3651When adding a new file, the second number will always 3652be one and the first number will equal the highest 3653first number of any file in that directory. For 3654example, the current directory contains files whose 3655highest numbered revisions are @code{1.7}, @code{3.1}, 3656and @code{4.12}, then an added file will be given the 3657numeric revision @code{4.1}. 3658(When using client/server @sc{cvs}, 3659only files that are actually sent to the server are considered.) 3660 3661@c This is sort of redundant with something we said a 3662@c while ago. Somewhere we need a better way of 3663@c introducing how the first number can be anything 3664@c except "1", perhaps. Also I don't think this 3665@c presentation is clear on why we are discussing releases 3666@c and first numbers of numeric revisions in the same 3667@c breath. 3668Normally there is no reason to care 3669about the revision numbers---it is easier to treat them 3670as internal numbers that @sc{cvs} maintains, and tags 3671provide a better way to distinguish between things like 3672release 1 versus release 2 of your product 3673(@pxref{Tags}). However, if you want to set the 3674numeric revisions, the @samp{-r} option to @code{cvs 3675commit} can do that. The @samp{-r} option implies the 3676@samp{-f} option, in the sense that it causes the 3677files to be committed even if they are not modified. 3678 3679For example, to bring all your files up to 3680revision 3.0 (including those that haven't changed), 3681you might invoke: 3682 3683@example 3684$ cvs commit -r 3.0 3685@end example 3686 3687Note that the number you specify with @samp{-r} must be 3688larger than any existing revision number. That is, if 3689revision 3.0 exists, you cannot @samp{cvs commit 3690-r 1.3}. If you want to maintain several releases in 3691parallel, you need to use a branch (@pxref{Branching and merging}). 3692 3693@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3694@node Tags 3695@section Tags--Symbolic revisions 3696@cindex Tags 3697 3698The revision numbers live a life of their own. They 3699need not have anything at all to do with the release 3700numbers of your software product. Depending 3701on how you use @sc{cvs} the revision numbers might change several times 3702between two releases. As an example, some of the 3703source files that make up @sc{rcs} 5.6 have the following 3704revision numbers: 3705@cindex RCS revision numbers 3706 3707@example 3708ci.c 5.21 3709co.c 5.9 3710ident.c 5.3 3711rcs.c 5.12 3712rcsbase.h 5.11 3713rcsdiff.c 5.10 3714rcsedit.c 5.11 3715rcsfcmp.c 5.9 3716rcsgen.c 5.10 3717rcslex.c 5.11 3718rcsmap.c 5.2 3719rcsutil.c 5.10 3720@end example 3721 3722@cindex tag (subcommand), introduction 3723@cindex Tags, symbolic name 3724@cindex Symbolic name (tag) 3725@cindex Name, symbolic (tag) 3726@cindex HEAD, as reserved tag name 3727@cindex BASE, as reserved tag name 3728You can use the @code{tag} command to give a symbolic name to a 3729certain revision of a file. You can use the @samp{-v} flag to the 3730@code{status} command to see all tags that a file has, and 3731which revision numbers they represent. Tag names must 3732start with an uppercase or lowercase letter and can 3733contain uppercase and lowercase letters, digits, 3734@samp{-}, and @samp{_}. The two tag names @code{BASE} 3735and @code{HEAD} are reserved for use by @sc{cvs}. It 3736is expected that future names which are special to 3737@sc{cvs} will be specially named, for example by 3738starting with @samp{.}, rather than being named analogously to 3739@code{BASE} and @code{HEAD}, to avoid conflicts with 3740actual tag names. 3741@c Including a character such as % or = has also been 3742@c suggested as the naming convention for future 3743@c special tag names. Starting with . is nice because 3744@c that is not a legal tag name as far as RCS is concerned. 3745@c FIXME: CVS actually accepts quite a few characters 3746@c in tag names, not just the ones documented above 3747@c (see RCS_check_tag). RCS 3748@c defines legitimate tag names by listing illegal 3749@c characters rather than legal ones. CVS is said to lose its 3750@c mind if you try to use "/" (try making such a tag sticky 3751@c and using "cvs status" client/server--see remote 3752@c protocol format for entries line for probable cause). 3753@c TODO: The testsuite 3754@c should test for whatever are documented above as 3755@c officially-OK tag names, and CVS should at least reject 3756@c characters that won't work, like "/". 3757 3758You'll want to choose some convention for naming tags, 3759based on information such as the name of the program 3760and the version number of the release. For example, 3761one might take the name of the program, immediately 3762followed by the version number with @samp{.} changed to 3763@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 3764@code{cvs1-9}. If you choose a consistent convention, 3765then you won't constantly be guessing whether a tag is 3766@code{cvs-1-9} or @code{cvs1_9} or what. You might 3767even want to consider enforcing your convention in the 3768@file{taginfo} file (@pxref{taginfo}). 3769@c Might be nice to say more about using taginfo this 3770@c way, like giving an example, or pointing out any particular 3771@c issues which arise. 3772 3773@cindex Adding a tag 3774@cindex Tags, example 3775The following example shows how you can add a tag to a 3776file. The commands must be issued inside your working 3777directory. That is, you should issue the 3778command in the directory where @file{backend.c} 3779resides. 3780 3781@example 3782$ cvs tag rel-0-4 backend.c 3783T backend.c 3784$ cvs status -v backend.c 3785=================================================================== 3786File: backend.c Status: Up-to-date 3787 3788 Version: 1.4 Tue Dec 1 14:39:01 1992 3789 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 3790 Sticky Tag: (none) 3791 Sticky Date: (none) 3792 Sticky Options: (none) 3793 3794 Existing Tags: 3795 rel-0-4 (revision: 1.4) 3796 3797@end example 3798 3799For a complete summary of the syntax of @code{cvs tag}, 3800including the various options, see @ref{Invoking CVS}. 3801 3802There is seldom reason to tag a file in isolation. A more common use is 3803to tag all the files that constitute a module with the same tag at 3804strategic points in the development life-cycle, such as when a release 3805is made. 3806 3807@example 3808$ cvs tag rel-1-0 . 3809cvs tag: Tagging . 3810T Makefile 3811T backend.c 3812T driver.c 3813T frontend.c 3814T parser.c 3815@end example 3816 3817@noindent 3818(When you give @sc{cvs} a directory as argument, it generally applies the 3819operation to all the files in that directory, and (recursively), to any 3820subdirectories that it may contain. @xref{Recursive behavior}.) 3821 3822@cindex Retrieving an old revision using tags 3823@cindex Tags, retrieving old revisions 3824The @code{checkout} command has a flag, @samp{-r}, that lets you check out 3825a certain revision of a module. This flag makes it easy to 3826retrieve the sources that make up release 1.0 of the module @samp{tc} at 3827any time in the future: 3828 3829@example 3830$ cvs checkout -r rel-1-0 tc 3831@end example 3832 3833@noindent 3834This is useful, for instance, if someone claims that there is a bug in 3835that release, but you cannot find the bug in the current working copy. 3836 3837You can also check out a module as it was on any branch at any given date. 3838@xref{checkout options}. When specifying @samp{-r} or @samp{-D} to 3839any of these commands, you will need beware of sticky 3840tags; see @ref{Sticky tags}. 3841 3842When you tag more than one file with the same tag you 3843can think about the tag as "a curve drawn through a 3844matrix of filename vs. revision number." Say we have 5 3845files with the following revisions: 3846 3847@example 3848@group 3849 file1 file2 file3 file4 file5 3850 3851 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 3852 1.2*- 1.2 1.2 -1.2*- 3853 1.3 \- 1.3*- 1.3 / 1.3 3854 1.4 \ 1.4 / 1.4 3855 \-1.5*- 1.5 3856 1.6 3857@end group 3858@end example 3859 3860At some time in the past, the @code{*} versions were tagged. 3861You can think of the tag as a handle attached to the curve 3862drawn through the tagged revisions. When you pull on 3863the handle, you get all the tagged revisions. Another 3864way to look at it is that you "sight" through a set of 3865revisions that is "flat" along the tagged revisions, 3866like this: 3867 3868@example 3869@group 3870 file1 file2 file3 file4 file5 3871 3872 1.1 3873 1.2 3874 1.1 1.3 _ 3875 1.1 1.2 1.4 1.1 / 3876 1.2*----1.3*----1.5*----1.2*----1.1* (--- <--- Look here 3877 1.3 1.6 1.3 \_ 3878 1.4 1.4 3879 1.5 3880@end group 3881@end example 3882 3883@node Tagging the working directory 3884@section Specifying what to tag from the working directory 3885 3886@cindex tag (subcommand) 3887The example in the previous section demonstrates one of 3888the most common ways to choose which revisions to tag. 3889Namely, running the @code{cvs tag} command without 3890arguments causes @sc{cvs} to select the revisions which 3891are checked out in the current working directory. For 3892example, if the copy of @file{backend.c} in working 3893directory was checked out from revision 1.4, then 3894@sc{cvs} will tag revision 1.4. Note that the tag is 3895applied immediately to revision 1.4 in the repository; 3896tagging is not like modifying a file, or other 3897operations in which one first modifies the working 3898directory and then runs @code{cvs commit} to transfer 3899that modification to the repository. 3900 3901One potentially surprising aspect of the fact that 3902@code{cvs tag} operates on the repository is that you 3903are tagging the checked-in revisions, which may differ 3904from locally modified files in your working directory. 3905If you want to avoid doing this by mistake, specify the 3906@samp{-c} option to @code{cvs tag}. If there are any 3907locally modified files, @sc{cvs} will abort with an 3908error before it tags any files: 3909 3910@example 3911$ cvs tag -c rel-0-4 3912cvs tag: backend.c is locally modified 3913cvs [tag aborted]: correct the above errors first! 3914@end example 3915 3916@node Tagging by date/tag 3917@section Specifying what to tag by date or revision 3918@cindex rtag (subcommand) 3919 3920The @code{cvs rtag} command tags the repository as of a 3921certain date or time (or can be used to tag the latest 3922revision). @code{rtag} works directly on the 3923repository contents (it requires no prior checkout and 3924does not look for a working directory). 3925 3926The following options specify which date or revision to 3927tag. See @ref{Common options}, for a complete 3928description of them. 3929 3930@table @code 3931@item -D @var{date} 3932Tag the most recent revision no later than @var{date}. 3933 3934@item -f 3935Only useful with the @samp{-D} or @samp{-r} 3936flags. If no matching revision is found, use the most 3937recent revision (instead of ignoring the file). 3938 3939@item -r @var{tag}[:@var{date}] 3940Tag the revision already tagged with @var{tag} or, when @var{date} is specified 3941and @var{tag} is a branch tag, the version from the branch @var{tag} as it 3942existed on @var{date}. See @ref{Common options}. 3943@end table 3944 3945The @code{cvs tag} command also allows one to specify 3946files by revision or date, using the same @samp{-r}, 3947@samp{-D}, and @samp{-f} options. However, this 3948feature is probably not what you want. The reason is 3949that @code{cvs tag} chooses which files to tag based on 3950the files that exist in the working directory, rather 3951than the files which existed as of the given tag/date. 3952Therefore, you are generally better off using @code{cvs 3953rtag}. The exceptions might be cases like: 3954 3955@example 3956cvs tag -r 1.4 stable backend.c 3957@end example 3958 3959@node Modifying tags 3960@section Deleting, moving, and renaming tags 3961 3962@c Also see: 3963@c "How do I move or rename a magic branch tag?" 3964@c in the FAQ (I think the issues it talks about still 3965@c apply, but this could use some sanity.sh work). 3966 3967Normally one does not modify tags. They exist in order 3968to record the history of the repository and so deleting 3969them or changing their meaning would, generally, not be 3970what you want. 3971 3972However, there might be cases in which one uses a tag 3973temporarily or accidentally puts one in the wrong 3974place. Therefore, one might delete, move, or rename a 3975tag. 3976 3977@noindent 3978@strong{WARNING: the commands in this section are 3979dangerous; they permanently discard historical 3980information and it can be difficult or impossible to 3981recover from errors. If you are a @sc{cvs} 3982administrator, you may consider restricting these 3983commands with the @file{taginfo} file (@pxref{taginfo}).} 3984 3985@cindex Deleting tags 3986@cindex Deleting branch tags 3987@cindex Removing tags 3988@cindex Removing branch tags 3989@cindex Tags, deleting 3990@cindex Branch tags, deleting 3991To delete a tag, specify the @samp{-d} option to either 3992@code{cvs tag} or @code{cvs rtag}. For example: 3993 3994@example 3995cvs rtag -d rel-0-4 tc 3996@end example 3997 3998@noindent 3999deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 4000In the event that branch tags are encountered within the repository 4001with the given name, a warning message will be issued and the branch 4002tag will not be deleted. If you are absolutely certain you know what 4003you are doing, the @code{-B} option may be specified to allow deletion 4004of branch tags. In that case, any non-branch tags encountered will 4005trigger warnings and will not be deleted. 4006 4007@noindent 4008@strong{WARNING: Moving branch tags is very dangerous! If you think 4009you need the @code{-B} option, think again and ask your @sc{cvs} 4010administrator about it (if that isn't you). There is almost certainly 4011another way to accomplish what you want to accomplish.} 4012 4013@cindex Moving tags 4014@cindex Moving branch tags 4015@cindex Tags, moving 4016@cindex Branch tags, moving 4017When we say @dfn{move} a tag, we mean to make the same 4018name point to different revisions. For example, the 4019@code{stable} tag may currently point to revision 1.4 4020of @file{backend.c} and perhaps we want to make it 4021point to revision 1.6. To move a non-branch tag, specify the 4022@samp{-F} option to either @code{cvs tag} or @code{cvs 4023rtag}. For example, the task just mentioned might be 4024accomplished as: 4025 4026@example 4027cvs tag -r 1.6 -F stable backend.c 4028@end example 4029 4030@noindent 4031If any branch tags are encountered in the repository 4032with the given name, a warning is issued and the branch 4033tag is not disturbed. If you are absolutely certain you 4034wish to move the branch tag, the @code{-B} option may be specified. 4035In that case, non-branch tags encountered with the given 4036name are ignored with a warning message. 4037 4038@noindent 4039@strong{WARNING: Moving branch tags is very dangerous! If you think you 4040need the @code{-B} option, think again and ask your @sc{cvs} 4041administrator about it (if that isn't you). There is almost certainly 4042another way to accomplish what you want to accomplish.} 4043 4044@cindex Renaming tags 4045@cindex Tags, renaming 4046When we say @dfn{rename} a tag, we mean to make a 4047different name point to the same revisions as the old 4048tag. For example, one may have misspelled the tag name 4049and want to correct it (hopefully before others are 4050relying on the old spelling). To rename a tag, first 4051create a new tag using the @samp{-r} option to 4052@code{cvs rtag}, and then delete the old name. (Caution: 4053this method will not work with branch tags.) 4054This leaves the new tag on exactly the 4055same files as the old tag. For example: 4056 4057@example 4058cvs rtag -r old-name-0-4 rel-0-4 tc 4059cvs rtag -d old-name-0-4 tc 4060@end example 4061 4062@node Tagging add/remove 4063@section Tagging and adding and removing files 4064 4065The subject of exactly how tagging interacts with 4066adding and removing files is somewhat obscure; for the 4067most part @sc{cvs} will keep track of whether files 4068exist or not without too much fussing. By default, 4069tags are applied to only files which have a revision 4070corresponding to what is being tagged. Files which did 4071not exist yet, or which were already removed, simply 4072omit the tag, and @sc{cvs} knows to treat the absence 4073of a tag as meaning that the file didn't exist as of 4074that tag. 4075 4076However, this can lose a small amount of information. 4077For example, suppose a file was added and then removed. 4078Then, if the tag is missing for that file, there is no 4079way to know whether the tag refers to the time before 4080the file was added, or the time after it was removed. 4081If you specify the @samp{-r} option to @code{cvs rtag}, 4082then @sc{cvs} tags the files which have been removed, 4083and thereby avoids this problem. For example, one 4084might specify @code{-r HEAD} to tag the head. 4085 4086On the subject of adding and removing files, the 4087@code{cvs rtag} command has a @samp{-a} option which 4088means to clear the tag from removed files that would 4089not otherwise be tagged. For example, one might 4090specify this option in conjunction with @samp{-F} when 4091moving a tag. If one moved a tag without @samp{-a}, 4092then the tag in the removed files might still refer to 4093the old revision, rather than reflecting the fact that 4094the file had been removed. I don't think this is 4095necessary if @samp{-r} is specified, as noted above. 4096 4097@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4098@node Sticky tags 4099@section Sticky tags 4100@cindex Sticky tags 4101@cindex Tags, sticky 4102 4103@c A somewhat related issue is per-directory sticky 4104@c tags (see comment at CVS/Tag in node Working 4105@c directory storage); we probably want to say 4106@c something like "you can set a sticky tag for only 4107@c some files, but you don't want to" or some such. 4108 4109Sometimes a working copy's revision has extra data 4110associated with it, for example it might be on a branch 4111(@pxref{Branching and merging}), or restricted to 4112versions prior to a certain date by @samp{checkout -D} 4113or @samp{update -D}. Because this data persists -- 4114that is, it applies to subsequent commands in the 4115working copy -- we refer to it as @dfn{sticky}. 4116 4117Most of the time, stickiness is an obscure aspect of 4118@sc{cvs} that you don't need to think about. However, 4119even if you don't want to use the feature, you may need 4120to know @emph{something} about sticky tags (for 4121example, how to avoid them!). 4122 4123You can use the @code{status} command to see if any 4124sticky tags or dates are set: 4125 4126@example 4127$ cvs status driver.c 4128=================================================================== 4129File: driver.c Status: Up-to-date 4130 4131 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 4132 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 4133 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4134 Sticky Date: (none) 4135 Sticky Options: (none) 4136 4137@end example 4138 4139@cindex Resetting sticky tags 4140@cindex Sticky tags, resetting 4141@cindex Deleting sticky tags 4142The sticky tags will remain on your working files until 4143you delete them with @samp{cvs update -A}. The 4144@samp{-A} option merges local changes into the version of the 4145file from the head of the trunk, removing any sticky tags, 4146dates, or options. See @ref{update} for more on the operation 4147of @code{cvs update}. 4148 4149@cindex Sticky date 4150The most common use of sticky tags is to identify which 4151branch one is working on, as described in 4152@ref{Accessing branches}. However, non-branch 4153sticky tags have uses as well. For example, 4154suppose that you want to avoid updating your working 4155directory, to isolate yourself from possibly 4156destabilizing changes other people are making. You 4157can, of course, just refrain from running @code{cvs 4158update}. But if you want to avoid updating only a 4159portion of a larger tree, then sticky tags can help. 4160If you check out a certain revision (such as 1.4) it 4161will become sticky. Subsequent @code{cvs update} 4162commands will 4163not retrieve the latest revision until you reset the 4164tag with @code{cvs update -A}. Likewise, use of the 4165@samp{-D} option to @code{update} or @code{checkout} 4166sets a @dfn{sticky date}, which, similarly, causes that 4167date to be used for future retrievals. 4168 4169People often want to retrieve an old version of 4170a file without setting a sticky tag. This can 4171be done with the @samp{-p} option to @code{checkout} or 4172@code{update}, which sends the contents of the file to 4173standard output. For example: 4174@example 4175$ cvs update -p -r 1.1 file1 >file1 4176=================================================================== 4177Checking out file1 4178RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 4179VERS: 1.1 4180*************** 4181$ 4182@end example 4183 4184However, this isn't the easiest way, if you are asking 4185how to undo a previous checkin (in this example, put 4186@file{file1} back to the way it was as of revision 41871.1). In that case you are better off using the 4188@samp{-j} option to @code{update}; for further 4189discussion see @ref{Merging two revisions}. 4190 4191@c --------------------------------------------------------------------- 4192@node Branching and merging 4193@chapter Branching and merging 4194@cindex Branching 4195@cindex Merging 4196@cindex Copying changes 4197@cindex Main trunk and branches 4198@cindex Revision tree, making branches 4199@cindex Branches, copying changes between 4200@cindex Changes, copying between branches 4201@cindex Modifications, copying between branches 4202 4203@sc{cvs} allows you to isolate changes onto a separate 4204line of development, known as a @dfn{branch}. When you 4205change files on a branch, those changes do not appear 4206on the main trunk or other branches. 4207 4208Later you can move changes from one branch to another 4209branch (or the main trunk) by @dfn{merging}. Merging 4210involves first running @code{cvs update -j}, to merge 4211the changes into the working directory. 4212You can then commit that revision, and thus effectively 4213copy the changes onto another branch. 4214 4215@menu 4216* Branches motivation:: What branches are good for 4217* Creating a branch:: Creating a branch 4218* Accessing branches:: Checking out and updating branches 4219* Branches and revisions:: Branches are reflected in revision numbers 4220* Magic branch numbers:: Magic branch numbers 4221* Merging a branch:: Merging an entire branch 4222* Merging more than once:: Merging from a branch several times 4223* Merging two revisions:: Merging differences between two revisions 4224* Merging adds and removals:: What if files are added or removed? 4225* Merging and keywords:: Avoiding conflicts due to keyword substitution 4226@end menu 4227 4228@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4229@node Branches motivation 4230@section What branches are good for 4231@cindex Branches motivation 4232@cindex What branches are good for 4233@cindex Motivation for branches 4234 4235@c FIXME: this node mentions one way to use branches, 4236@c but it is by no means the only way. For example, 4237@c the technique of committing a new feature on a branch, 4238@c until it is ready for the main trunk. The whole 4239@c thing is generally speaking more akin to the 4240@c "Revision management" node although it isn't clear to 4241@c me whether policy matters should be centralized or 4242@c distributed throughout the relevant sections. 4243Suppose that release 1.0 of tc has been made. You are continuing to 4244develop tc, planning to create release 1.1 in a couple of months. After a 4245while your customers start to complain about a fatal bug. You check 4246out release 1.0 (@pxref{Tags}) and find the bug 4247(which turns out to have a trivial fix). However, the current revision 4248of the sources are in a state of flux and are not expected to be stable 4249for at least another month. There is no way to make a 4250bug fix release based on the newest sources. 4251 4252The thing to do in a situation like this is to create a @dfn{branch} on 4253the revision trees for all the files that make up 4254release 1.0 of tc. You can then make 4255modifications to the branch without disturbing the main trunk. When the 4256modifications are finished you can elect to either incorporate them on 4257the main trunk, or leave them on the branch. 4258 4259@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4260@node Creating a branch 4261@section Creating a branch 4262@cindex Creating a branch 4263@cindex Branch, creating a 4264@cindex tag (subcommand), creating a branch using 4265@cindex rtag (subcommand), creating a branch using 4266 4267You can create a branch with @code{tag -b}; for 4268example, assuming you're in a working copy: 4269 4270@example 4271$ cvs tag -b rel-1-0-patches 4272@end example 4273 4274@c FIXME: we should be more explicit about the value of 4275@c having a tag on the branchpoint. For example 4276@c "cvs tag rel-1-0-patches-branchpoint" before 4277@c the "cvs tag -b". This points out that 4278@c rel-1-0-patches is a pretty awkward name for 4279@c this example (more so than for the rtag example 4280@c below). 4281 4282This splits off a branch based on the current revisions 4283in the working copy, assigning that branch the name 4284@samp{rel-1-0-patches}. 4285 4286It is important to understand that branches get created 4287in the repository, not in the working copy. Creating a 4288branch based on current revisions, as the above example 4289does, will @emph{not} automatically switch the working 4290copy to be on the new branch. For information on how 4291to do that, see @ref{Accessing branches}. 4292 4293You can also create a branch without reference to any 4294working copy, by using @code{rtag}: 4295 4296@example 4297$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 4298@end example 4299 4300@samp{-r rel-1-0} says that this branch should be 4301rooted at the revision that 4302corresponds to the tag @samp{rel-1-0}. It need not 4303be the most recent revision -- it's often useful to 4304split a branch off an old revision (for example, when 4305fixing a bug in a past release otherwise known to be 4306stable). 4307 4308As with @samp{tag}, the @samp{-b} flag tells 4309@code{rtag} to create a branch (rather than just a 4310symbolic revision name). Note that the numeric 4311revision number that matches @samp{rel-1-0} will 4312probably be different from file to file. 4313 4314So, the full effect of the command is to create a new 4315branch -- named @samp{rel-1-0-patches} -- in module 4316@samp{tc}, rooted in the revision tree at the point tagged 4317by @samp{rel-1-0}. 4318 4319@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4320@node Accessing branches 4321@section Accessing branches 4322@cindex Check out a branch 4323@cindex Retrieve a branch 4324@cindex Access a branch 4325@cindex Identifying a branch 4326@cindex Branch, check out 4327@cindex Branch, retrieving 4328@cindex Branch, accessing 4329@cindex Branch, identifying 4330 4331You can retrieve a branch in one of two ways: by 4332checking it out fresh from the repository, or by 4333switching an existing working copy over to the branch. 4334 4335To check out a branch from the repository, invoke 4336@samp{checkout} with the @samp{-r} flag, followed by 4337the tag name of the branch (@pxref{Creating a branch}): 4338 4339@example 4340$ cvs checkout -r rel-1-0-patches tc 4341@end example 4342 4343Or, if you already have a working copy, you can switch 4344it to a given branch with @samp{update -r}: 4345 4346@example 4347$ cvs update -r rel-1-0-patches tc 4348@end example 4349 4350@noindent 4351or equivalently: 4352 4353@example 4354$ cd tc 4355$ cvs update -r rel-1-0-patches 4356@end example 4357 4358It does not matter if the working copy was originally 4359on the main trunk or on some other branch -- the above 4360command will switch it to the named branch. And 4361similarly to a regular @samp{update} command, 4362@samp{update -r} merges any changes you have made, 4363notifying you of conflicts where they occur. 4364 4365Once you have a working copy tied to a particular 4366branch, it remains there until you tell it otherwise. 4367This means that changes checked in from the working 4368copy will add new revisions on that branch, while 4369leaving the main trunk and other branches unaffected. 4370 4371@cindex Branches, sticky 4372To find out what branch a working copy is on, you can 4373use the @samp{status} command. In its output, look for 4374the field named @samp{Sticky tag} (@pxref{Sticky tags}) 4375-- that's @sc{cvs}'s way of telling you the branch, if 4376any, of the current working files: 4377 4378@example 4379$ cvs status -v driver.c backend.c 4380=================================================================== 4381File: driver.c Status: Up-to-date 4382 4383 Version: 1.7 Sat Dec 5 18:25:54 1992 4384 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 4385 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4386 Sticky Date: (none) 4387 Sticky Options: (none) 4388 4389 Existing Tags: 4390 rel-1-0-patches (branch: 1.7.2) 4391 rel-1-0 (revision: 1.7) 4392 4393=================================================================== 4394File: backend.c Status: Up-to-date 4395 4396 Version: 1.4 Tue Dec 1 14:39:01 1992 4397 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 4398 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 4399 Sticky Date: (none) 4400 Sticky Options: (none) 4401 4402 Existing Tags: 4403 rel-1-0-patches (branch: 1.4.2) 4404 rel-1-0 (revision: 1.4) 4405 rel-0-4 (revision: 1.4) 4406 4407@end example 4408 4409Don't be confused by the fact that the branch numbers 4410for each file are different (@samp{1.7.2} and 4411@samp{1.4.2} respectively). The branch tag is the 4412same, @samp{rel-1-0-patches}, and the files are 4413indeed on the same branch. The numbers simply reflect 4414the point in each file's revision history at which the 4415branch was made. In the above example, one can deduce 4416that @samp{driver.c} had been through more changes than 4417@samp{backend.c} before this branch was created. 4418 4419See @ref{Branches and revisions} for details about how 4420branch numbers are constructed. 4421 4422@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4423@node Branches and revisions 4424@section Branches and revisions 4425@cindex Branch number 4426@cindex Number, branch 4427@cindex Revision numbers (branches) 4428 4429Ordinarily, a file's revision history is a linear 4430series of increments (@pxref{Revision numbers}): 4431 4432@example 4433 +-----+ +-----+ +-----+ +-----+ +-----+ 4434 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 4435 +-----+ +-----+ +-----+ +-----+ +-----+ 4436@end example 4437 4438However, @sc{cvs} is not limited to linear development. The 4439@dfn{revision tree} can be split into @dfn{branches}, 4440where each branch is a self-maintained line of 4441development. Changes made on one branch can easily be 4442moved back to the main trunk. 4443 4444Each branch has a @dfn{branch number}, consisting of an 4445odd number of period-separated decimal integers. The 4446branch number is created by appending an integer to the 4447revision number where the corresponding branch forked 4448off. Having branch numbers allows more than one branch 4449to be forked off from a certain revision. 4450 4451@need 3500 4452All revisions on a branch have revision numbers formed 4453by appending an ordinal number to the branch number. 4454The following figure illustrates branching with an 4455example. 4456 4457@example 4458@c This example used to have a 1.2.2.4 revision, which 4459@c might help clarify that development can continue on 4460@c 1.2.2. Might be worth reinstating if it can be done 4461@c without overfull hboxes. 4462@group 4463 +-------------+ 4464 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 4465 / +-------------+ 4466 / 4467 / 4468 +---------+ +---------+ +---------+ 4469Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4470 / +---------+ +---------+ +---------+ 4471 / 4472 / 4473+-----+ +-----+ +-----+ +-----+ +-----+ 4474! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4475+-----+ +-----+ +-----+ +-----+ +-----+ 4476 ! 4477 ! 4478 ! +---------+ +---------+ +---------+ 4479Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 4480 +---------+ +---------+ +---------+ 4481 4482@end group 4483@end example 4484 4485@c -- However, at least for me the figure is not enough. I suggest more 4486@c -- text to accompany it. "A picture is worth a thousand words", so you 4487@c -- have to make sure the reader notices the couple of hundred words 4488@c -- *you* had in mind more than the others! 4489 4490@c -- Why an even number of segments? This section implies that this is 4491@c -- how the main trunk is distinguished from branch roots, but you never 4492@c -- explicitly say that this is the purpose of the [by itself rather 4493@c -- surprising] restriction to an even number of segments. 4494 4495The exact details of how the branch number is 4496constructed is not something you normally need to be 4497concerned about, but here is how it works: When 4498@sc{cvs} creates a branch number it picks the first 4499unused even integer, starting with 2. So when you want 4500to create a branch from revision 6.4 it will be 4501numbered 6.4.2. All branch numbers ending in a zero 4502(such as 6.4.0) are used internally by @sc{cvs} 4503(@pxref{Magic branch numbers}). The branch 1.1.1 has a 4504special meaning. @xref{Tracking sources}. 4505 4506@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4507@node Magic branch numbers 4508@section Magic branch numbers 4509 4510@c Want xref to here from "log"? 4511 4512This section describes a @sc{cvs} feature called 4513@dfn{magic branches}. For most purposes, you need not 4514worry about magic branches; @sc{cvs} handles them for 4515you. However, they are visible to you in certain 4516circumstances, so it may be useful to have some idea of 4517how it works. 4518 4519Externally, branch numbers consist of an odd number of 4520dot-separated decimal integers. @xref{Revision 4521numbers}. That is not the whole truth, however. For 4522efficiency reasons @sc{cvs} sometimes inserts an extra 0 4523in the second rightmost position (1.2.4 becomes 45241.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 4525on). 4526 4527@sc{cvs} does a pretty good job at hiding these so 4528called magic branches, but in a few places the hiding 4529is incomplete: 4530 4531@itemize @bullet 4532@ignore 4533@c This is in ignore as I'm taking their word for it, 4534@c that this was fixed 4535@c a long time ago. But before deleting this 4536@c entirely, I'd rather verify it (and add a test 4537@c case to the testsuite). 4538@item 4539The magic branch can appear in the output from 4540@code{cvs status} in vanilla @sc{cvs} 1.3. This is 4541fixed in @sc{cvs} 1.3-s2. 4542 4543@end ignore 4544@item 4545The magic branch number appears in the output from 4546@code{cvs log}. 4547@c What output should appear instead? 4548 4549@item 4550You cannot specify a symbolic branch name to @code{cvs 4551admin}. 4552 4553@end itemize 4554 4555@c Can CVS do this automatically the first time 4556@c you check something in to that branch? Should 4557@c it? 4558You can use the @code{admin} command to reassign a 4559symbolic name to a branch the way @sc{rcs} expects it 4560to be. If @code{R4patches} is assigned to the branch 45611.4.2 (magic branch number 1.4.0.2) in file 4562@file{numbers.c} you can do this: 4563 4564@example 4565$ cvs admin -NR4patches:1.4.2 numbers.c 4566@end example 4567 4568It only works if at least one revision is already 4569committed on the branch. Be very careful so that you 4570do not assign the tag to the wrong number. (There is 4571no way to see how the tag was assigned yesterday). 4572 4573@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4574@node Merging a branch 4575@section Merging an entire branch 4576@cindex Merging a branch 4577@cindex -j (merging branches) 4578 4579You can merge changes made on a branch into your working copy by giving 4580the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 4581@samp{-j @var{branchname}} option it merges the changes made between the 4582greatest common ancestor (GCA) of the branch and the destination revision (in 4583the simple case below the GCA is the point where the branch forked) and the 4584newest revision on that branch into your working copy. 4585 4586@cindex Join 4587The @samp{-j} stands for ``join''. 4588 4589@cindex Branch merge example 4590@cindex Example, branch merge 4591@cindex Merge, branch example 4592Consider this revision tree: 4593 4594@example 4595+-----+ +-----+ +-----+ +-----+ 4596! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 4597+-----+ +-----+ +-----+ +-----+ 4598 ! 4599 ! 4600 ! +---------+ +---------+ 4601Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4602 +---------+ +---------+ 4603@end example 4604 4605@noindent 4606The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 4607following example assumes that the module @samp{mod} contains only one 4608file, @file{m.c}. 4609 4610@example 4611$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 4612 4613$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 4614 # @r{i.e. the changes between revision 1.2} 4615 # @r{and 1.2.2.2, into your working copy} 4616 # @r{of the file.} 4617 4618$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 4619@end example 4620 4621A conflict can result from a merge operation. If that 4622happens, you should resolve it before committing the 4623new revision. @xref{Conflicts example}. 4624 4625If your source files contain keywords (@pxref{Keyword substitution}), 4626you might be getting more conflicts than strictly necessary. See 4627@ref{Merging and keywords}, for information on how to avoid this. 4628 4629The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 4630same effect as above could be achieved with this: 4631 4632@example 4633$ cvs checkout -j R1fix mod 4634$ cvs commit -m "Included R1fix" 4635@end example 4636 4637It should be noted that @code{update -j @var{tagname}} will also work but may 4638not produce the desired result. @xref{Merging adds and removals}, for more. 4639 4640@node Merging more than once 4641@section Merging from a branch several times 4642 4643Continuing our example, the revision tree now looks 4644like this: 4645 4646@example 4647+-----+ +-----+ +-----+ +-----+ +-----+ 4648! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4649+-----+ +-----+ +-----+ +-----+ +-----+ 4650 ! * 4651 ! * 4652 ! +---------+ +---------+ 4653Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4654 +---------+ +---------+ 4655@end example 4656 4657@noindent 4658where the starred line represents the merge from the 4659@samp{R1fix} branch to the main trunk, as just 4660discussed. 4661 4662Now suppose that development continues on the 4663@samp{R1fix} branch: 4664 4665@example 4666+-----+ +-----+ +-----+ +-----+ +-----+ 4667! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4668+-----+ +-----+ +-----+ +-----+ +-----+ 4669 ! * 4670 ! * 4671 ! +---------+ +---------+ +---------+ 4672Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4673 +---------+ +---------+ +---------+ 4674@end example 4675 4676@noindent 4677and then you want to merge those new changes onto the 4678main trunk. If you just use the @code{cvs update -j 4679R1fix m.c} command again, @sc{cvs} will attempt to 4680merge again the changes which you have already merged, 4681which can have undesirable side effects. 4682 4683So instead you need to specify that you only want to 4684merge the changes on the branch which have not yet been 4685merged into the trunk. To do that you specify two 4686@samp{-j} options, and @sc{cvs} merges the changes from 4687the first revision to the second revision. For 4688example, in this case the simplest way would be 4689 4690@example 4691cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 4692 # @r{head of the R1fix branch} 4693@end example 4694 4695The problem with this is that you need to specify the 46961.2.2.2 revision manually. A slightly better approach 4697might be to use the date the last merge was done: 4698 4699@example 4700cvs update -j R1fix:yesterday -j R1fix m.c 4701@end example 4702 4703Better yet, tag the R1fix branch after every merge into 4704the trunk, and then use that tag for subsequent merges: 4705 4706@example 4707cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 4708@end example 4709 4710@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4711@node Merging two revisions 4712@section Merging differences between any two revisions 4713@cindex Merging two revisions 4714@cindex Revisions, merging differences between 4715@cindex Differences, merging 4716 4717With two @samp{-j @var{revision}} flags, the @code{update} 4718(and @code{checkout}) command can merge the differences 4719between any two revisions into your working file. 4720 4721@cindex Undoing a change 4722@cindex Removing a change 4723@example 4724$ cvs update -j 1.5 -j 1.3 backend.c 4725@end example 4726 4727@noindent 4728will undo all changes made between revision 47291.3 and 1.5. Note the order of the revisions! 4730 4731If you try to use this option when operating on 4732multiple files, remember that the numeric revisions will 4733probably be very different between the various files. 4734You almost always use symbolic 4735tags rather than revision numbers when operating on 4736multiple files. 4737 4738@cindex Restoring old version of removed file 4739@cindex Resurrecting old version of dead file 4740Specifying two @samp{-j} options can also undo file 4741removals or additions. For example, suppose you have 4742a file 4743named @file{file1} which existed as revision 1.1, and 4744you then removed it (thus adding a dead revision 1.2). 4745Now suppose you want to add it again, with the same 4746contents it had previously. Here is how to do it: 4747 4748@example 4749$ cvs update -j 1.2 -j 1.1 file1 4750U file1 4751$ cvs commit -m test 4752Checking in file1; 4753/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 4754new revision: 1.3; previous revision: 1.2 4755done 4756$ 4757@end example 4758 4759@node Merging adds and removals 4760@section Merging can add or remove files 4761 4762If the changes which you are merging involve removing 4763or adding some files, @code{update -j} will reflect 4764such additions or removals. 4765 4766@c FIXME: This example needs a lot more explanation. 4767@c We also need other examples for some of the other 4768@c cases (not all--there are too many--as long as we present a 4769@c coherent general principle). 4770For example: 4771@example 4772cvs update -A 4773touch a b c 4774cvs add a b c ; cvs ci -m "added" a b c 4775cvs tag -b branchtag 4776cvs update -r branchtag 4777touch d ; cvs add d 4778rm a ; cvs rm a 4779cvs ci -m "added d, removed a" 4780cvs update -A 4781cvs update -jbranchtag 4782@end example 4783 4784After these commands are executed and a @samp{cvs commit} is done, 4785file @file{a} will be removed and file @file{d} added in the main branch. 4786@c (which was determined by trying it) 4787 4788Note that using a single static tag (@samp{-j @var{tagname}}) 4789rather than a dynamic tag (@samp{-j @var{branchname}}) to merge 4790changes from a branch will usually not remove files which were removed on the 4791branch since @sc{cvs} does not automatically add static tags to dead revisions. 4792The exception to this rule occurs when 4793a static tag has been attached to a dead revision manually. Use the branch tag 4794to merge all changes from the branch or use two static tags as merge endpoints 4795to be sure that all intended changes are propagated in the merge. 4796 4797@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4798@node Merging and keywords 4799@section Merging and keywords 4800@cindex Merging, and keyword substitution 4801@cindex Keyword substitution, and merging 4802@cindex -j (merging branches), and keyword substitution 4803@cindex -kk, to avoid conflicts during a merge 4804 4805If you merge files containing keywords (@pxref{Keyword 4806substitution}), you will normally get numerous 4807conflicts during the merge, because the keywords are 4808expanded differently in the revisions which you are 4809merging. 4810 4811Therefore, you will often want to specify the 4812@samp{-kk} (@pxref{Substitution modes}) switch to the 4813merge command line. By substituting just the name of 4814the keyword, not the expanded value of that keyword, 4815this option ensures that the revisions which you are 4816merging will be the same as each other, and avoid 4817spurious conflicts. 4818 4819For example, suppose you have a file like this: 4820 4821@example 4822 +---------+ 4823 _! 1.1.2.1 ! <- br1 4824 / +---------+ 4825 / 4826 / 4827+-----+ +-----+ 4828! 1.1 !----! 1.2 ! 4829+-----+ +-----+ 4830@end example 4831 4832@noindent 4833and your working directory is currently on the trunk 4834(revision 1.2). Then you might get the following 4835results from a merge: 4836 4837@example 4838$ cat file1 4839key $@splitrcskeyword{Revision}: 1.2 $ 4840. . . 4841$ cvs update -j br1 4842U file1 4843RCS file: /cvsroot/first-dir/file1,v 4844retrieving revision 1.1 4845retrieving revision 1.1.2.1 4846Merging differences between 1.1 and 1.1.2.1 into file1 4847rcsmerge: warning: conflicts during merge 4848$ cat file1 4849@asis{}<<<<<<< file1 4850key $@splitrcskeyword{Revision}: 1.2 $ 4851@asis{}======= 4852key $@splitrcskeyword{Revision}: 1.1.2.1 $ 4853@asis{}>>>>>>> 1.1.2.1 4854. . . 4855@end example 4856 4857What happened was that the merge tried to merge the 4858differences between 1.1 and 1.1.2.1 into your working 4859directory. So, since the keyword changed from 4860@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 4861@sc{cvs} tried to merge that change into your working 4862directory, which conflicted with the fact that your 4863working directory had contained @code{Revision: 1.2}. 4864 4865Here is what happens if you had used @samp{-kk}: 4866 4867@example 4868$ cat file1 4869key $@splitrcskeyword{Revision}: 1.2 $ 4870. . . 4871$ cvs update -kk -j br1 4872U file1 4873RCS file: /cvsroot/first-dir/file1,v 4874retrieving revision 1.1 4875retrieving revision 1.1.2.1 4876Merging differences between 1.1 and 1.1.2.1 into file1 4877$ cat file1 4878key $@splitrcskeyword{Revision}$ 4879. . . 4880@end example 4881 4882What is going on here is that revision 1.1 and 1.1.2.1 4883both expand as plain @code{Revision}, and therefore 4884merging the changes between them into the working 4885directory need not change anything. Therefore, there 4886is no conflict. 4887 4888@strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a 4889major problem with using @samp{-kk} on merges. Namely, @samp{-kk} 4890overrode any default keyword expansion mode set in the archive file in 4891the repository. This could, unfortunately for some users, cause data 4892corruption in binary files (with a default keyword expansion mode set 4893to @samp{-kb}). Therefore, when a repository contained binary files, 4894conflicts had to be dealt with manually rather than using @samp{-kk} in 4895a merge command.} 4896 4897In @sc{cvs} version 1.12.2 and later, the keyword expansion mode 4898provided on the command line to any @sc{cvs} command no longer 4899overrides the @samp{-kb} keyword expansion mode setting for binary 4900files, though it will still override other default keyword expansion 4901modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts 4902on lines containing RCS keywords, even when your repository contains 4903binary files. 4904 4905@c --------------------------------------------------------------------- 4906@node Recursive behavior 4907@chapter Recursive behavior 4908@cindex Recursive (directory descending) 4909@cindex Directory, descending 4910@cindex Descending directories 4911@cindex Subdirectories 4912 4913Almost all of the subcommands of @sc{cvs} work 4914recursively when you specify a directory as an 4915argument. For instance, consider this directory 4916structure: 4917 4918@example 4919 @code{$HOME} 4920 | 4921 +--@t{tc} 4922 | | 4923 +--@t{CVS} 4924 | (internal @sc{cvs} files) 4925 +--@t{Makefile} 4926 +--@t{backend.c} 4927 +--@t{driver.c} 4928 +--@t{frontend.c} 4929 +--@t{parser.c} 4930 +--@t{man} 4931 | | 4932 | +--@t{CVS} 4933 | | (internal @sc{cvs} files) 4934 | +--@t{tc.1} 4935 | 4936 +--@t{testing} 4937 | 4938 +--@t{CVS} 4939 | (internal @sc{cvs} files) 4940 +--@t{testpgm.t} 4941 +--@t{test2.t} 4942@end example 4943 4944@noindent 4945If @file{tc} is the current working directory, the 4946following is true: 4947 4948@itemize @bullet 4949@item 4950@samp{cvs update testing} is equivalent to 4951 4952@example 4953cvs update testing/testpgm.t testing/test2.t 4954@end example 4955 4956@item 4957@samp{cvs update testing man} updates all files in the 4958subdirectories 4959 4960@item 4961@samp{cvs update .} or just @samp{cvs update} updates 4962all files in the @code{tc} directory 4963@end itemize 4964 4965If no arguments are given to @code{update} it will 4966update all files in the current working directory and 4967all its subdirectories. In other words, @file{.} is a 4968default argument to @code{update}. This is also true 4969for most of the @sc{cvs} subcommands, not only the 4970@code{update} command. 4971 4972The recursive behavior of the @sc{cvs} subcommands can be 4973turned off with the @samp{-l} option. 4974Conversely, the @samp{-R} option can be used to force recursion if 4975@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 4976 4977@example 4978$ cvs update -l # @r{Don't update files in subdirectories} 4979@end example 4980 4981@c --------------------------------------------------------------------- 4982@node Adding and removing 4983@chapter Adding, removing, and renaming files and directories 4984 4985In the course of a project, one will often add new 4986files. Likewise with removing or renaming, or with 4987directories. The general concept to keep in mind in 4988all these cases is that instead of making an 4989irreversible change you want @sc{cvs} to record the 4990fact that a change has taken place, just as with 4991modifying an existing file. The exact mechanisms to do 4992this in @sc{cvs} vary depending on the situation. 4993 4994@menu 4995* Adding files:: Adding files 4996* Removing files:: Removing files 4997* Removing directories:: Removing directories 4998* Moving files:: Moving and renaming files 4999* Moving directories:: Moving and renaming directories 5000@end menu 5001 5002@node Adding files 5003@section Adding files to a directory 5004@cindex Adding files 5005 5006To add a new file to a directory, follow these steps. 5007 5008@itemize @bullet 5009@item 5010You must have a working copy of the directory. 5011@xref{Getting the source}. 5012 5013@item 5014Create the new file inside your working copy of the directory. 5015 5016@item 5017Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you 5018want to version control the file. If the file contains 5019binary data, specify @samp{-kb} (@pxref{Binary files}). 5020 5021@item 5022Use @samp{cvs commit @var{filename}} to actually check 5023in the file into the repository. Other developers 5024cannot see the file until you perform this step. 5025@end itemize 5026 5027You can also use the @code{add} command to add a new 5028directory. 5029@c FIXCVS and/or FIXME: Adding a directory doesn't 5030@c require the commit step. This probably can be 5031@c considered a CVS bug, but it is possible we should 5032@c warn people since this behavior probably won't be 5033@c changing right away. 5034 5035Unlike most other commands, the @code{add} command is 5036not recursive. You have to expcicitly name files and 5037directories that you wish to add to the repository. 5038However, each directory will need to be added 5039separately before you will be able to add new files 5040to those directories. 5041 5042@example 5043$ mkdir -p foo/bar 5044$ cp ~/myfile foo/bar/myfile 5045$ cvs add foo foo/bar 5046$ cvs add foo/bar/myfile 5047@end example 5048 5049@cindex add (subcommand) 5050@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 5051 5052Schedule @var{files} to be added to the repository. 5053The files or directories specified with @code{add} must 5054already exist in the current directory. To add a whole 5055new directory hierarchy to the source repository (for 5056example, files received from a third-party vendor), use 5057the @code{import} command instead. @xref{import}. 5058 5059The added files are not placed in the source repository 5060until you use @code{commit} to make the change 5061permanent. Doing an @code{add} on a file that was 5062removed with the @code{remove} command will undo the 5063effect of the @code{remove}, unless a @code{commit} 5064command intervened. @xref{Removing files}, for an 5065example. 5066 5067The @samp{-k} option specifies the default way that 5068this file will be checked out; for more information see 5069@ref{Substitution modes}. 5070 5071@c As noted in BUGS, -m is broken client/server (Nov 5072@c 96). Also see testsuite log2-* tests. 5073The @samp{-m} option specifies a description for the 5074file. This description appears in the history log (if 5075it is enabled, @pxref{history file}). It will also be 5076saved in the version history inside the repository when 5077the file is committed. The @code{log} command displays 5078this description. The description can be changed using 5079@samp{admin -t}. @xref{admin}. If you omit the 5080@samp{-m @var{description}} flag, an empty string will 5081be used. You will not be prompted for a description. 5082@end deffn 5083 5084For example, the following commands add the file 5085@file{backend.c} to the repository: 5086 5087@c This example used to specify 5088@c -m "Optimizer and code generation passes." 5089@c to the cvs add command, but that doesn't work 5090@c client/server (see log2 in sanity.sh). Should fix CVS, 5091@c but also seems strange to document things which 5092@c don't work... 5093@example 5094$ cvs add backend.c 5095$ cvs commit -m "Early version. Not yet compilable." backend.c 5096@end example 5097 5098When you add a file it is added only on the branch 5099which you are working on (@pxref{Branching and merging}). You can 5100later merge the additions to another branch if you want 5101(@pxref{Merging adds and removals}). 5102@c Should we mention that earlier versions of CVS 5103@c lacked this feature (1.3) or implemented it in a buggy 5104@c way (well, 1.8 had many bugs in cvs update -j)? 5105@c Should we mention the bug/limitation regarding a 5106@c file being a regular file on one branch and a directory 5107@c on another? 5108@c FIXME: This needs an example, or several, here or 5109@c elsewhere, for it to make much sense. 5110@c Somewhere we need to discuss the aspects of death 5111@c support which don't involve branching, I guess. 5112@c Like the ability to re-create a release from a tag. 5113 5114@c --------------------------------------------------------------------- 5115@node Removing files 5116@section Removing files 5117@cindex Removing files 5118@cindex Deleting files 5119 5120@c FIXME: this node wants to be split into several 5121@c smaller nodes. Could make these children of 5122@c "Adding and removing", probably (death support could 5123@c be its own section, for example, as could the 5124@c various bits about undoing mistakes in adding and 5125@c removing). 5126Directories change. New files are added, and old files 5127disappear. Still, you want to be able to retrieve an 5128exact copy of old releases. 5129 5130Here is what you can do to remove a file, 5131but remain able to retrieve old revisions: 5132 5133@itemize @bullet 5134@c FIXME: should probably be saying something about 5135@c having a working directory in the first place. 5136@item 5137Make sure that you have not made any uncommitted 5138modifications to the file. @xref{Viewing differences}, 5139for one way to do that. You can also use the 5140@code{status} or @code{update} command. If you remove 5141the file without committing your changes, you will of 5142course not be able to retrieve the file as it was 5143immediately before you deleted it. 5144 5145@item 5146Remove the file from your working copy of the directory. 5147You can for instance use @code{rm}. 5148 5149@item 5150Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that 5151you really want to delete the file. 5152 5153@item 5154Use @samp{cvs commit @var{filename}} to actually 5155perform the removal of the file from the repository. 5156@end itemize 5157 5158@c FIXME: Somehow this should be linked in with a more 5159@c general discussion of death support. I don't know 5160@c whether we want to use the term "death support" or 5161@c not (we can perhaps get by without it), but we do 5162@c need to discuss the "dead" state in "cvs log" and 5163@c related subjects. The current discussion is 5164@c scattered around, and not xref'd to each other. 5165@c FIXME: I think this paragraph wants to be moved 5166@c later down, at least after the first example. 5167When you commit the removal of the file, @sc{cvs} 5168records the fact that the file no longer exists. It is 5169possible for a file to exist on only some branches and 5170not on others, or to re-add another file with the same 5171name later. @sc{cvs} will correctly create or not create 5172the file, based on the @samp{-r} and @samp{-D} options 5173specified to @code{checkout} or @code{update}. 5174 5175@c FIXME: This style seems to clash with how we 5176@c document things in general. 5177@cindex Remove (subcommand) 5178@deffn Command {cvs remove} [options] files @dots{} 5179 5180Schedule file(s) to be removed from the repository 5181(files which have not already been removed from the 5182working directory are not processed). This command 5183does not actually remove the file from the repository 5184until you commit the removal. For a full list of 5185options, see @ref{Invoking CVS}. 5186@end deffn 5187 5188Here is an example of removing several files: 5189 5190@example 5191$ cd test 5192$ rm *.c 5193$ cvs remove 5194cvs remove: Removing . 5195cvs remove: scheduling a.c for removal 5196cvs remove: scheduling b.c for removal 5197cvs remove: use 'cvs commit' to remove these files permanently 5198$ cvs ci -m "Removed unneeded files" 5199cvs commit: Examining . 5200cvs commit: Committing . 5201@end example 5202 5203As a convenience you can remove the file and @code{cvs 5204remove} it in one step, by specifying the @samp{-f} 5205option. For example, the above example could also be 5206done like this: 5207 5208@example 5209$ cd test 5210$ cvs remove -f *.c 5211cvs remove: scheduling a.c for removal 5212cvs remove: scheduling b.c for removal 5213cvs remove: use 'cvs commit' to remove these files permanently 5214$ cvs ci -m "Removed unneeded files" 5215cvs commit: Examining . 5216cvs commit: Committing . 5217@end example 5218 5219If you execute @code{remove} for a file, and then 5220change your mind before you commit, you can undo the 5221@code{remove} with an @code{add} command. 5222@ignore 5223@c is this worth saying or not? Somehow it seems 5224@c confusing to me. 5225Of course, 5226since you have removed your copy of file in the working 5227directory, @sc{cvs} does not necessarily bring back the 5228contents of the file from right before you executed 5229@code{remove}; instead it gets the file from the 5230repository again. 5231@end ignore 5232 5233@c FIXME: what if you change your mind after you commit 5234@c it? (answer is also "cvs add" but we don't say that...). 5235@c We need some index entries for thinks like "undoing 5236@c removal" too. 5237 5238@example 5239$ ls 5240CVS ja.h oj.c 5241$ rm oj.c 5242$ cvs remove oj.c 5243cvs remove: scheduling oj.c for removal 5244cvs remove: use 'cvs commit' to remove this file permanently 5245$ cvs add oj.c 5246U oj.c 5247cvs add: oj.c, version 1.1.1.1, resurrected 5248@end example 5249 5250If you realize your mistake before you run the 5251@code{remove} command you can use @code{update} to 5252resurrect the file: 5253 5254@example 5255$ rm oj.c 5256$ cvs update oj.c 5257cvs update: warning: oj.c was lost 5258U oj.c 5259@end example 5260 5261When you remove a file it is removed only on the branch 5262which you are working on (@pxref{Branching and merging}). You can 5263later merge the removals to another branch if you want 5264(@pxref{Merging adds and removals}). 5265 5266@node Removing directories 5267@section Removing directories 5268@cindex Removing directories 5269@cindex Directories, removing 5270 5271In concept, removing directories is somewhat similar to 5272removing files---you want the directory to not exist in 5273your current working directories, but you also want to 5274be able to retrieve old releases in which the directory 5275existed. 5276 5277The way that you remove a directory is to remove all 5278the files in it. You don't remove the directory 5279itself; there is no way to do that. 5280Instead you specify the @samp{-P} option to 5281@code{cvs update} or @code{cvs checkout}, 5282which will cause @sc{cvs} to remove empty 5283directories from working directories. 5284(Note that @code{cvs export} always removes empty directories.) 5285Probably the 5286best way to do this is to always specify @samp{-P}; if 5287you want an empty directory then put a dummy file (for 5288example @file{.keepme}) in it to prevent @samp{-P} from 5289removing it. 5290 5291@c I'd try to give a rationale for this, but I'm not 5292@c sure there is a particularly convincing one. What 5293@c we would _like_ is for CVS to do a better job of version 5294@c controlling whether directories exist, to eliminate the 5295@c need for -P and so that a file can be a directory in 5296@c one revision and a regular file in another. 5297Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5298options of @code{checkout}. This way, 5299@sc{cvs} will be able to correctly create the directory 5300or not depending on whether the particular version you 5301are checking out contains any files in that directory. 5302 5303@c --------------------------------------------------------------------- 5304@node Moving files 5305@section Moving and renaming files 5306@cindex Moving files 5307@cindex Renaming files 5308@cindex Files, moving 5309 5310Moving files to a different directory or renaming them 5311is not difficult, but some of the ways in which this 5312works may be non-obvious. (Moving or renaming a 5313directory is even harder. @xref{Moving directories}.). 5314 5315The examples below assume that the file @var{old} is renamed to 5316@var{new}. 5317 5318@menu 5319* Outside:: The normal way to Rename 5320* Inside:: A tricky, alternative way 5321* Rename by copying:: Another tricky, alternative way 5322@end menu 5323 5324@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5325@node Outside 5326@subsection The Normal way to Rename 5327 5328@c More rename issues. Not sure whether these are 5329@c worth documenting; I'm putting them here because 5330@c it seems to be as good a place as any to try to 5331@c set down the issues. 5332@c * "cvs annotate" will annotate either the new 5333@c file or the old file; it cannot annotate _each 5334@c line_ based on whether it was last changed in the 5335@c new or old file. Unlike "cvs log", where the 5336@c consequences of having to select either the new 5337@c or old name seem fairly benign, this may be a 5338@c real advantage to having CVS know about renames 5339@c other than as a deletion and an addition. 5340 5341The normal way to move a file is to copy @var{old} to 5342@var{new}, and then issue the normal @sc{cvs} commands 5343to remove @var{old} from the repository, and add 5344@var{new} to it. 5345@c The following sentence is not true: one must cd into 5346@c the directory to run "cvs add". 5347@c (Both @var{old} and @var{new} could 5348@c contain relative paths, for example @file{foo/bar.c}). 5349 5350@example 5351$ mv @var{old} @var{new} 5352$ cvs remove @var{old} 5353$ cvs add @var{new} 5354$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 5355@end example 5356 5357This is the simplest way to move a file, it is not 5358error-prone, and it preserves the history of what was 5359done. Note that to access the history of the file you 5360must specify the old or the new name, depending on what 5361portion of the history you are accessing. For example, 5362@code{cvs log @var{old}} will give the log up until the 5363time of the rename. 5364 5365When @var{new} is committed its revision numbers will 5366start again, usually at 1.1, so if that bothers you, 5367use the @samp{-r @var{tag}} option to commit. For more 5368information see @ref{Assigning revisions}. 5369 5370@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5371@node Inside 5372@subsection Moving the history file 5373 5374This method is more dangerous, since it involves moving 5375files inside the repository. Read this entire section 5376before trying it out! 5377 5378@example 5379$ cd $CVSROOT/@var{dir} 5380$ mv @var{old},v @var{new},v 5381@end example 5382 5383@noindent 5384Advantages: 5385 5386@itemize @bullet 5387@item 5388The log of changes is maintained intact. 5389 5390@item 5391The revision numbers are not affected. 5392@end itemize 5393 5394@noindent 5395Disadvantages: 5396 5397@itemize @bullet 5398@item 5399Old releases cannot easily be fetched from the 5400repository. (The file will show up as @var{new} even 5401in revisions from the time before it was renamed). 5402 5403@item 5404There is no log information of when the file was renamed. 5405 5406@item 5407Nasty things might happen if someone accesses the history file 5408while you are moving it. Make sure no one else runs any of the @sc{cvs} 5409commands while you move it. 5410@end itemize 5411 5412@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5413@node Rename by copying 5414@subsection Copying the history file 5415 5416This way also involves direct modifications to the 5417repository. It is safe, but not without drawbacks. 5418 5419@example 5420# @r{Copy the @sc{rcs} file inside the repository} 5421$ cd $CVSROOT/@var{dir} 5422$ cp @var{old},v @var{new},v 5423# @r{Remove the old file} 5424$ cd ~/@var{dir} 5425$ rm @var{old} 5426$ cvs remove @var{old} 5427$ cvs commit @var{old} 5428# @r{Remove all tags from @var{new}} 5429$ cvs update @var{new} 5430$ cvs log @var{new} # @r{Remember the non-branch tag names} 5431$ cvs tag -d @var{tag1} @var{new} 5432$ cvs tag -d @var{tag2} @var{new} 5433@dots{} 5434@end example 5435 5436By removing the tags you will be able to check out old 5437revisions. 5438 5439@noindent 5440Advantages: 5441 5442@itemize @bullet 5443@item 5444@c FIXME: Is this true about -D now that we have death 5445@c support? See 5B.3 in the FAQ. 5446Checking out old revisions works correctly, as long as 5447you use @samp{-r @var{tag}} and not @samp{-D @var{date}} 5448to retrieve the revisions. 5449 5450@item 5451The log of changes is maintained intact. 5452 5453@item 5454The revision numbers are not affected. 5455@end itemize 5456 5457@noindent 5458Disadvantages: 5459 5460@itemize @bullet 5461@item 5462You cannot easily see the history of the file across the rename. 5463 5464@ignore 5465@c Is this true? I don't see how the revision numbers 5466@c _could_ start over, when new,v is just old,v with 5467@c the tags deleted. 5468@c If there is some need to reinstate this text, 5469@c it is "usually 1.1", not "1.0" and it needs an 5470@c xref to Assigning revisions 5471@item 5472Unless you use the @samp{-r @var{tag}} (@pxref{commit 5473options}) flag when @var{new} is committed its revision 5474numbers will start at 1.0 again. 5475@end ignore 5476@end itemize 5477 5478@c --------------------------------------------------------------------- 5479@node Moving directories 5480@section Moving and renaming directories 5481@cindex Moving directories 5482@cindex Renaming directories 5483@cindex Directories, moving 5484 5485The normal way to rename or move a directory is to 5486rename or move each file within it as described in 5487@ref{Outside}. Then check out with the @samp{-P} 5488option, as described in @ref{Removing directories}. 5489 5490If you really want to hack the repository to rename or 5491delete a directory in the repository, you can do it 5492like this: 5493 5494@enumerate 5495@item 5496Inform everyone who has a checked out copy of the directory that the 5497directory will be renamed. They should commit all their changes in all their 5498copies of the project containing the directory to be removed, and remove 5499all their working copies of said project, before you take the steps below. 5500 5501@item 5502Rename the directory inside the repository. 5503 5504@example 5505$ cd $CVSROOT/@var{parent-dir} 5506$ mv @var{old-dir} @var{new-dir} 5507@end example 5508 5509@item 5510Fix the @sc{cvs} administrative files, if necessary (for 5511instance if you renamed an entire module). 5512 5513@item 5514Tell everyone that they can check out again and continue 5515working. 5516 5517@end enumerate 5518 5519If someone had a working copy the @sc{cvs} commands will 5520cease to work for him, until he removes the directory 5521that disappeared inside the repository. 5522 5523It is almost always better to move the files in the 5524directory instead of moving the directory. If you move the 5525directory you are unlikely to be able to retrieve old 5526releases correctly, since they probably depend on the 5527name of the directories. 5528 5529@c --------------------------------------------------------------------- 5530@node History browsing 5531@chapter History browsing 5532@cindex History browsing 5533@cindex Traceability 5534@cindex Isolation 5535 5536@ignore 5537@c This is too long for an introduction (goal is 5538@c one 20x80 character screen), and also mixes up a 5539@c variety of issues (parallel development, history, 5540@c maybe even touches on process control). 5541 5542@c -- @quote{To lose ones history is to lose ones soul.} 5543@c -- /// 5544@c -- ///Those who cannot remember the past are condemned to repeat it. 5545@c -- /// -- George Santayana 5546@c -- /// 5547 5548@sc{cvs} tries to make it easy for a group of people to work 5549together. This is done in two ways: 5550 5551@itemize @bullet 5552@item 5553Isolation---You have your own working copy of the 5554source. You are not affected by modifications made by 5555others until you decide to incorporate those changes 5556(via the @code{update} command---@pxref{update}). 5557 5558@item 5559Traceability---When something has changed, you can 5560always see @emph{exactly} what changed. 5561@end itemize 5562 5563There are several features of @sc{cvs} that together lead 5564to traceability: 5565 5566@itemize @bullet 5567@item 5568Each revision of a file has an accompanying log 5569message. 5570 5571@item 5572All commits are optionally logged to a central history 5573database. 5574 5575@item 5576Logging information can be sent to a user-defined 5577program (@pxref{loginfo}). 5578@end itemize 5579 5580@c -- More text here. 5581 5582This chapter should talk about the history file, the 5583@code{log} command, the usefulness of ChangeLogs 5584even when you run @sc{cvs}, and things like that. 5585 5586@end ignore 5587 5588@c kind of lame, in a lot of ways the above text inside 5589@c the @ignore motivates this chapter better 5590Once you have used @sc{cvs} to store a version control 5591history---what files have changed when, how, and by 5592whom, there are a variety of mechanisms for looking 5593through the history. 5594 5595@c FIXME: should also be talking about how you look at 5596@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 5597@menu 5598* log messages:: Log messages 5599* history database:: The history database 5600* user-defined logging:: User-defined logging 5601@end menu 5602 5603@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5604@node log messages 5605@section Log messages 5606 5607@c FIXME: @xref to place where we talk about how to 5608@c specify message to commit. 5609Whenever you commit a file you specify a log message. 5610 5611@c FIXME: bring the information here, and get rid of or 5612@c greatly shrink the "log" node. 5613To look through the log messages which have been 5614specified for every revision which has been committed, 5615use the @code{cvs log} command (@pxref{log}). 5616 5617@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5618@node history database 5619@section The history database 5620 5621@c FIXME: bring the information from the history file 5622@c and history nodes here. Rewrite it to be motivated 5623@c better (start out by clearly explaining what gets 5624@c logged in history, for example). 5625You can use the history file (@pxref{history file}) to 5626log various @sc{cvs} actions. To retrieve the 5627information from the history file, use the @code{cvs 5628history} command (@pxref{history}). 5629 5630Note: you can control what is logged to this file by using the 5631@samp{LogHistory} keyword in the @file{CVSROOT/config} file 5632(@pxref{config}). 5633 5634@c 5635@c The history database has many problems: 5636@c * It is very unclear what field means what. This 5637@c could be improved greatly by better documentation, 5638@c but there are still non-orthogonalities (for 5639@c example, tag does not record the "repository" 5640@c field but most records do). 5641@c * Confusion about files, directories, and modules. 5642@c Some commands record one, some record others. 5643@c * File removal is not logged. There is an 'R' 5644@c record type documented, but CVS never uses it. 5645@c * Tags are only logged for the "cvs rtag" command, 5646@c not "cvs tag". The fix for this is not completely 5647@c clear (see above about modules vs. files). 5648@c * Are there other cases of operations that are not 5649@c logged? One would hope for all changes to the 5650@c repository to be logged somehow (particularly 5651@c operations like tagging, "cvs admin -k", and other 5652@c operations which do not record a history that one 5653@c can get with "cvs log"). Operations on the working 5654@c directory, like export, get, and release, are a 5655@c second category also covered by the current "cvs 5656@c history". 5657@c * The history file does not record the options given 5658@c to a command. The most serious manifestation of 5659@c this is perhaps that it doesn't record whether a command 5660@c was recursive. It is not clear to me whether one 5661@c wants to log at a level very close to the command 5662@c line, as a sort of way of logging each command 5663@c (more or less), or whether one wants 5664@c to log more at the level of what was changed (or 5665@c something in between), but either way the current 5666@c information has pretty big gaps. 5667@c * Further details about a tag--like whether it is a 5668@c branch tag or, if a non-branch tag, which branch it 5669@c is on. One can find out this information about the 5670@c tag as it exists _now_, but if the tag has been 5671@c moved, one doesn't know what it was like at the time 5672@c the history record was written. 5673@c * Whether operating on a particular tag, date, or 5674@c options was implicit (sticky) or explicit. 5675@c 5676@c Another item, only somewhat related to the above, is a 5677@c way to control what is logged in the history file. 5678@c This is probably the only good way to handle 5679@c different people having different ideas about 5680@c information/space tradeoffs. 5681@c 5682@c It isn't really clear that it makes sense to try to 5683@c patch up the history file format as it exists now to 5684@c include all that stuff. It might be better to 5685@c design a whole new CVSROOT/nhistory file and "cvs 5686@c nhistory" command, or some such, or in some other 5687@c way trying to come up with a clean break from the 5688@c past, which can address the above concerns. Another 5689@c open question is how/whether this relates to 5690@c taginfo/loginfo/etc. 5691 5692@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5693@node user-defined logging 5694@section User-defined logging 5695 5696@c FIXME: probably should centralize this information 5697@c here, at least to some extent. Maybe by moving the 5698@c loginfo, etc., nodes here and replacing 5699@c the "user-defined logging" node with one node for 5700@c each method. 5701You can customize @sc{cvs} to log various kinds of 5702actions, in whatever manner you choose. These 5703mechanisms operate by executing a script at various 5704times. The script might append a message to a file 5705listing the information and the programmer who created 5706it, or send mail to a group of developers, or, perhaps, 5707post a message to a particular newsgroup. To log 5708commits, use the @file{loginfo} file (@pxref{loginfo}), and 5709to log tagging operations, use the @file{taginfo} file 5710(@pxref{taginfo}). 5711 5712@c FIXME: What is difference between doing it in the 5713@c modules file and using loginfo/taginfo? Why should 5714@c user use one or the other? 5715To log commits, checkouts, exports, and tags, 5716respectively, you can also use the @samp{-i}, 5717@samp{-o}, @samp{-e}, and @samp{-t} options in the 5718modules file. For a more flexible way of giving 5719notifications to various users, which requires less in 5720the way of keeping centralized scripts up to date, use 5721the @code{cvs watch add} command (@pxref{Getting 5722Notified}); this command is useful even if you are not 5723using @code{cvs watch on}. 5724 5725@c --------------------------------------------------------------------- 5726@node Binary files 5727@chapter Handling binary files 5728@cindex Binary files 5729 5730The most common use for @sc{cvs} is to store text 5731files. With text files, @sc{cvs} can merge revisions, 5732display the differences between revisions in a 5733human-visible fashion, and other such operations. 5734However, if you are willing to give up a few of these 5735abilities, @sc{cvs} can store binary files. For 5736example, one might store a web site in @sc{cvs} 5737including both text files and binary images. 5738 5739@menu 5740* Binary why:: More details on issues with binary files 5741* Binary howto:: How to store them 5742@end menu 5743 5744@node Binary why 5745@section The issues with binary files 5746 5747While the need to manage binary files may seem obvious 5748if the files that you customarily work with are binary, 5749putting them into version control does present some 5750additional issues. 5751 5752One basic function of version control is to show the 5753differences between two revisions. For example, if 5754someone else checked in a new version of a file, you 5755may wish to look at what they changed and determine 5756whether their changes are good. For text files, 5757@sc{cvs} provides this functionality via the @code{cvs 5758diff} command. For binary files, it may be possible to 5759extract the two revisions and then compare them with a 5760tool external to @sc{cvs} (for example, word processing 5761software often has such a feature). If there is no 5762such tool, one must track changes via other mechanisms, 5763such as urging people to write good log messages, and 5764hoping that the changes they actually made were the 5765changes that they intended to make. 5766 5767Another ability of a version control system is the 5768ability to merge two revisions. For @sc{cvs} this 5769happens in two contexts. The first is when users make 5770changes in separate working directories 5771(@pxref{Multiple developers}). The second is when one 5772merges explicitly with the @samp{update -j} command 5773(@pxref{Branching and merging}). 5774 5775In the case of text 5776files, @sc{cvs} can merge changes made independently, 5777and signal a conflict if the changes conflict. With 5778binary files, the best that @sc{cvs} can do is present 5779the two different copies of the file, and leave it to 5780the user to resolve the conflict. The user may choose 5781one copy or the other, or may run an external merge 5782tool which knows about that particular file format, if 5783one exists. 5784Note that having the user merge relies primarily on the 5785user to not accidentally omit some changes, and thus is 5786potentially error prone. 5787 5788If this process is thought to be undesirable, the best 5789choice may be to avoid merging. To avoid the merges 5790that result from separate working directories, see the 5791discussion of reserved checkouts (file locking) in 5792@ref{Multiple developers}. To avoid the merges 5793resulting from branches, restrict use of branches. 5794 5795@node Binary howto 5796@section How to store binary files 5797 5798There are two issues with using @sc{cvs} to store 5799binary files. The first is that @sc{cvs} by default 5800converts line endings between the canonical form in 5801which they are stored in the repository (linefeed 5802only), and the form appropriate to the operating system 5803in use on the client (for example, carriage return 5804followed by line feed for Windows NT). 5805 5806The second is that a binary file might happen to 5807contain data which looks like a keyword (@pxref{Keyword 5808substitution}), so keyword expansion must be turned 5809off. 5810 5811@c FIXME: the third is that one can't do merges with 5812@c binary files. xref to Multiple Developers and the 5813@c reserved checkout issues. 5814 5815The @samp{-kb} option available with some @sc{cvs} 5816commands insures that neither line ending conversion 5817nor keyword expansion will be done. 5818 5819Here is an example of how you can create a new file 5820using the @samp{-kb} flag: 5821 5822@example 5823$ echo '$@splitrcskeyword{Id}$' > kotest 5824$ cvs add -kb -m"A test file" kotest 5825$ cvs ci -m"First checkin; contains a keyword" kotest 5826@end example 5827 5828If a file accidentally gets added without @samp{-kb}, 5829one can use the @code{cvs admin} command to recover. 5830For example: 5831 5832@example 5833$ echo '$@splitrcskeyword{Id}$' > kotest 5834$ cvs add -m"A test file" kotest 5835$ cvs ci -m"First checkin; contains a keyword" kotest 5836$ cvs admin -kb kotest 5837$ cvs update -A kotest 5838# @r{For non-unix systems:} 5839# @r{Copy in a good copy of the file from outside CVS} 5840$ cvs commit -m "make it binary" kotest 5841@end example 5842 5843@c Trying to describe this for both unix and non-unix 5844@c in the same description is very confusing. Might 5845@c want to split the two, or just ditch the unix "shortcut" 5846@c (unixheads don't do much with binary files, anyway). 5847@c This used to say "(Try the above example, and do a 5848@c @code{cat kotest} after every command)". But that 5849@c only really makes sense for the unix case. 5850When you check in the file @file{kotest} the file is 5851not preserved as a binary file, because you did not 5852check it in as a binary file. The @code{cvs 5853admin -kb} command sets the default keyword 5854substitution method for this file, but it does not 5855alter the working copy of the file that you have. If you need to 5856cope with line endings (that is, you are using 5857@sc{cvs} on a non-unix system), then you need to 5858check in a new copy of the file, as shown by the 5859@code{cvs commit} command above. 5860On unix, the @code{cvs update -A} command suffices. 5861@c FIXME: should also describe what the *other users* 5862@c need to do, if they have checked out copies which 5863@c have been corrupted by lack of -kb. I think maybe 5864@c "cvs update -kb" or "cvs 5865@c update -A" would suffice, although the user who 5866@c reported this suggested removing the file, manually 5867@c removing it from CVS/Entries, and then "cvs update" 5868(Note that you can use @code{cvs log} to determine the default keyword 5869substitution method for a file and @code{cvs status} to determine 5870the keyword substitution method for a working copy.) 5871 5872However, in using @code{cvs admin -k} to change the 5873keyword expansion, be aware that the keyword expansion 5874mode is not version controlled. This means that, for 5875example, that if you have a text file in old releases, 5876and a binary file with the same name in new releases, 5877@sc{cvs} provides no way to check out the file in text 5878or binary mode depending on what version you are 5879checking out. There is no good workaround for this 5880problem. 5881 5882You can also set a default for whether @code{cvs add} 5883and @code{cvs import} treat a file as binary based on 5884its name; for example you could say that files who 5885names end in @samp{.exe} are binary. @xref{Wrappers}. 5886There is currently no way to have @sc{cvs} detect 5887whether a file is binary based on its contents. The 5888main difficulty with designing such a feature is that 5889it is not clear how to distinguish between binary and 5890non-binary files, and the rules to apply would vary 5891considerably with the operating system. 5892@c For example, it would be good on MS-DOS-family OSes 5893@c for anything containing ^Z to be binary. Having 5894@c characters with the 8th bit set imply binary is almost 5895@c surely a bad idea in the context of ISO-8859-* and 5896@c other such character sets. On VMS or the Mac, we 5897@c could use the OS's file typing. This is a 5898@c commonly-desired feature, and something of this sort 5899@c may make sense. But there are a lot of pitfalls here. 5900@c 5901@c Another, probably better, way to tell is to read the 5902@c file in text mode, write it to a temp file in text 5903@c mode, and then do a binary mode compare of the two 5904@c files. If they differ, it is a binary file. This 5905@c might have problems on VMS (or some other system 5906@c with several different text modes), but in general 5907@c should be relatively portable. The only other 5908@c downside I can think of is that it would be fairly 5909@c slow, but that is perhaps a small price to pay for 5910@c not having your files corrupted. Another issue is 5911@c what happens if you import a text file with bare 5912@c linefeeds on Windows. Such files will show up on 5913@c Windows sometimes (I think some native windows 5914@c programs even write them, on occasion). Perhaps it 5915@c is reasonable to treat such files as binary; after 5916@c all it is something of a presumption to assume that 5917@c the user would want the linefeeds converted to CRLF. 5918 5919@c --------------------------------------------------------------------- 5920@node Multiple developers 5921@chapter Multiple developers 5922@cindex Multiple developers 5923@cindex Team of developers 5924@cindex File locking 5925@cindex Locking files 5926@cindex Working copy 5927@cindex Reserved checkouts 5928@cindex Unreserved checkouts 5929@cindex RCS-style locking 5930 5931When more than one person works on a software project 5932things often get complicated. Often, two people try to 5933edit the same file simultaneously. One solution, known 5934as @dfn{file locking} or @dfn{reserved checkouts}, is 5935to allow only one person to edit each file at a time. 5936This is the only solution with some version control 5937systems, including @sc{rcs} and @sc{sccs}. Currently 5938the usual way to get reserved checkouts with @sc{cvs} 5939is the @code{cvs admin -l} command (@pxref{admin 5940options}). This is not as nicely integrated into 5941@sc{cvs} as the watch features, described below, but it 5942seems that most people with a need for reserved 5943checkouts find it adequate. 5944@c Or "find it better than worrying about implementing 5945@c nicely integrated reserved checkouts" or ...? 5946 5947As of @sc{cvs} version 1.12.10, another technique for getting most of the 5948effect of reserved checkouts is to enable advisory locks. To enable advisory 5949locks, have all developers put "edit -c", "commit -c" in their 5950.cvsrc file, and turn on watches in the repository. This 5951prevents them from doing a @code{cvs edit} if anyone is 5952already editting the file. It also may 5953be possible to use plain watches together with suitable 5954procedures (not enforced by software), to avoid having 5955two people edit at the same time. 5956 5957@c Our unreserved checkout model might not 5958@c be quite the same as others. For example, I 5959@c think that some systems will tend to create a branch 5960@c in the case where CVS prints "up-to-date check failed". 5961@c It isn't clear to me whether we should try to 5962@c explore these subtleties; it could easily just 5963@c confuse people. 5964The default model with @sc{cvs} is known as 5965@dfn{unreserved checkouts}. In this model, developers 5966can edit their own @dfn{working copy} of a file 5967simultaneously. The first person that commits his 5968changes has no automatic way of knowing that another 5969has started to edit it. Others will get an error 5970message when they try to commit the file. They must 5971then use @sc{cvs} commands to bring their working copy 5972up to date with the repository revision. This process 5973is almost automatic. 5974 5975@c FIXME? should probably use the word "watch" here, to 5976@c tie this into the text below and above. 5977@sc{cvs} also supports mechanisms which facilitate 5978various kinds of communication, without actually 5979enforcing rules like reserved checkouts do. 5980 5981The rest of this chapter describes how these various 5982models work, and some of the issues involved in 5983choosing between them. 5984 5985@ignore 5986Here is a draft reserved checkout design or discussion 5987of the issues. This seems like as good a place as any 5988for this. 5989 5990Might want a cvs lock/cvs unlock--in which the names 5991differ from edit/unedit because the network must be up 5992for these to work. unedit gives an error if there is a 5993reserved checkout in place (so that people don't 5994accidentally leave locks around); unlock gives an error 5995if one is not in place (this is more arguable; perhaps 5996it should act like unedit in that case). 5997 5998On the other hand, might want it so that emacs, 5999scripts, etc., can get ready to edit a file without 6000having to know which model is in use. In that case we 6001would have a "cvs watch lock" (or .cvsrc?) (that is, 6002three settings, "on", "off", and "lock"). Having cvs 6003watch lock set would cause a get to record in the CVS 6004directory which model is in use, and cause "cvs edit" 6005to change behaviors. We'd want a way to query which 6006setting is in effect (this would be handy even if it is 6007only "on" or "off" as presently). If lock is in 6008effect, then commit would require a lock before 6009allowing a checkin; chmod wouldn't suffice (might be 6010debatable--see chmod comment below, in watches--but it 6011is the way people expect RCS to work and I can't think 6012of any significant downside. On the other hand, maybe 6013it isn't worth bothering, because people who are used 6014to RCS wouldn't think to use chmod anyway). 6015 6016Implementation: use file attributes or use RCS 6017locking. The former avoids more dependence on RCS 6018behaviors we will need to re-implement as we librarify 6019RCS, and makes it easier to import/export RCS files (in 6020that context, want to ignore the locker field). But 6021note that RCS locks are per-branch, which is the 6022correct behavior (this is also an issue for the "watch 6023on" features; they should be per-branch too). 6024 6025Here are a few more random notes about implementation 6026details, assuming "cvs watch lock" and 6027 6028CVS/Watched file? Or try to fit this into CVS/Entries somehow? 6029Cases: (1) file is checked out (unreserved or with watch on) by old 6030version of @sc{cvs}, now we do something with new one, (2) file is checked 6031out by new version, now we do something with old one. 6032 6033Remote protocol would have a "Watched" analogous to "Mode". Of course 6034it would apply to all Updated-like requests. How do we keep this 6035setting up to date? I guess that there wants to be a Watched request, 6036and the server would send a new one if it isn't up to date? (Ugh--hard 6037to implement and slows down "cvs -q update"--is there an easier way?) 6038 6039"cvs edit"--checks CVS/Watched, and if watch lock, then sends 6040"edit-lock" request. Which comes back with a Checked-in with 6041appropriate Watched (off, on, lock, locked, or some such?), or error 6042message if already locked. 6043 6044"cvs commit"--only will commit if off/on/locked. lock is not OK. 6045 6046Doc: 6047note that "cvs edit" must be connected to network if watch lock is in 6048effect. 6049 6050Talk about what to do if someone has locked a file and you want to 6051edit that file. (breaking locks, or lack thereof). 6052 6053 6054One other idea (which could work along with the 6055existing "cvs admin -l" reserved checkouts, as well as 6056the above): 6057 6058"cvs editors" could show who has the file locked, if 6059someone does. 6060 6061@end ignore 6062 6063@menu 6064* File status:: A file can be in several states 6065* Updating a file:: Bringing a file up-to-date 6066* Conflicts example:: An informative example 6067* Informing others:: To cooperate you must inform 6068* Concurrency:: Simultaneous repository access 6069* Watches:: Mechanisms to track who is editing files 6070* Choosing a model:: Reserved or unreserved checkouts? 6071@end menu 6072 6073@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6074@node File status 6075@section File status 6076@cindex File status 6077@cindex Status of a file 6078 6079@c Shouldn't this start with an example or something, 6080@c introducing the unreserved checkout model? Before we 6081@c dive into listing states? 6082Based on what operations you have performed on a 6083checked out file, and what operations others have 6084performed to that file in the repository, one can 6085classify a file in a number of states. The states, as 6086reported by the @code{status} command, are: 6087 6088@c The order of items is chosen to group logically 6089@c similar outputs together. 6090@c People who want alphabetical can use the index... 6091@table @asis 6092@cindex Up-to-date 6093@item Up-to-date 6094The file is identical with the latest revision in the 6095repository for the branch in use. 6096@c FIXME: should we clarify "in use"? The answer is 6097@c sticky tags, and trying to distinguish branch sticky 6098@c tags from non-branch sticky tags seems rather awkward 6099@c here. 6100@c FIXME: What happens with non-branch sticky tags? Is 6101@c a stuck file "Up-to-date" or "Needs checkout" or what? 6102 6103@item Locally Modified 6104@cindex Locally Modified 6105You have edited the file, and not yet committed your changes. 6106 6107@item Locally Added 6108@cindex Locally Added 6109You have added the file with @code{add}, and not yet 6110committed your changes. 6111@c There are many cases involving the file being 6112@c added/removed/modified in the working directory, and 6113@c added/removed/modified in the repository, which we 6114@c don't try to describe here. I'm not sure that "cvs 6115@c status" produces a non-confusing output in most of 6116@c those cases. 6117 6118@item Locally Removed 6119@cindex Locally Removed 6120You have removed the file with @code{remove}, and not yet 6121committed your changes. 6122 6123@item Needs Checkout 6124@cindex Needs Checkout 6125Someone else has committed a newer revision to the 6126repository. The name is slightly misleading; you will 6127ordinarily use @code{update} rather than 6128@code{checkout} to get that newer revision. 6129 6130@item Needs Patch 6131@cindex Needs Patch 6132@c See also newb-123j0 in sanity.sh (although that case 6133@c should probably be changed rather than documented). 6134Like Needs Checkout, but the @sc{cvs} server will send 6135a patch rather than the entire file. Sending a patch or 6136sending an entire file accomplishes the same thing. 6137 6138@item Needs Merge 6139@cindex Needs Merge 6140Someone else has committed a newer revision to the repository, and you 6141have also made modifications to the file. 6142 6143@item Unresolved Conflict 6144@cindex Unresolved Conflict 6145@c FIXCVS - This file status needs to be changed to some more informative 6146@c text that distinguishes it more clearly from each of the Locally Added, 6147@c File had conflicts on merge, and Unknown status types, but an exact and 6148@c succinct wording escapes me at the moment. 6149A file with the same name as this new file has been added to the repository 6150from a second workspace. This file will need to be moved out of the way 6151to allow an @code{update} to complete. 6152 6153@item File had conflicts on merge 6154@cindex File had conflicts on merge 6155@c is it worth saying that this message was "Unresolved 6156@c Conflict" in CVS 1.9 and earlier? I'm inclined to 6157@c think that is unnecessarily confusing to new users. 6158This is like Locally Modified, except that a previous 6159@code{update} command gave a conflict. If you have not 6160already done so, you need to 6161resolve the conflict as described in @ref{Conflicts example}. 6162 6163@item Unknown 6164@cindex Unknown 6165@sc{cvs} doesn't know anything about this file. For 6166example, you have created a new file and have not run 6167@code{add}. 6168@c 6169@c "Entry Invalid" and "Classify Error" are also in the 6170@c status.c. The latter definitely indicates a CVS bug 6171@c (should it be worded more like "internal error" so 6172@c people submit bug reports if they see it?). The former 6173@c I'm not as sure; I haven't tracked down whether/when it 6174@c appears in "cvs status" output. 6175 6176@end table 6177 6178To help clarify the file status, @code{status} also 6179reports the @code{Working revision} which is the 6180revision that the file in the working directory derives 6181from, and the @code{Repository revision} which is the 6182latest revision in the repository for the branch in 6183use. 6184The @samp{Commit Identifier} reflects the unique commitid 6185of the @code{commit}. 6186@c FIXME: should we clarify "in use"? The answer is 6187@c sticky tags, and trying to distinguish branch sticky 6188@c tags from non-branch sticky tags seems rather awkward 6189@c here. 6190@c FIXME: What happens with non-branch sticky tags? 6191@c What is the Repository Revision there? See the 6192@c comment at vn_rcs in cvs.h, which is kind of 6193@c confused--we really need to document better what this 6194@c field contains. 6195@c Q: Should we document "New file!" and other such 6196@c outputs or are they self-explanatory? 6197@c FIXME: what about the date to the right of "Working 6198@c revision"? It doesn't appear with client/server and 6199@c seems unnecessary (redundant with "ls -l") so 6200@c perhaps it should be removed for non-client/server too? 6201@c FIXME: Need some examples. 6202@c FIXME: Working revision can also be something like 6203@c "-1.3" for a locally removed file. Not at all 6204@c self-explanatory (and it is possible that CVS should 6205@c be changed rather than documenting this). 6206 6207@c Would be nice to have an @example showing output 6208@c from cvs status, with comments showing the xref 6209@c where each part of the output is described. This 6210@c might fit in nicely if it is desirable to split this 6211@c node in two; one to introduce "cvs status" and one 6212@c to list each of the states. 6213The options to @code{status} are listed in 6214@ref{Invoking CVS}. For information on its @code{Sticky tag} 6215and @code{Sticky date} output, see @ref{Sticky tags}. 6216For information on its @code{Sticky options} output, 6217see the @samp{-k} option in @ref{update options}. 6218 6219You can think of the @code{status} and @code{update} 6220commands as somewhat complementary. You use 6221@code{update} to bring your files up to date, and you 6222can use @code{status} to give you some idea of what an 6223@code{update} would do (of course, the state of the 6224repository might change before you actually run 6225@code{update}). In fact, if you want a command to 6226display file status in a more brief format than is 6227displayed by the @code{status} command, you can invoke 6228 6229@cindex update, to display file status 6230@example 6231$ cvs -n -q update 6232@end example 6233 6234The @samp{-n} option means to not actually do the 6235update, but merely to display statuses; the @samp{-q} 6236option avoids printing the name of each directory. For 6237more information on the @code{update} command, and 6238these options, see @ref{Invoking CVS}. 6239 6240@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6241@node Updating a file 6242@section Bringing a file up to date 6243@cindex Bringing a file up to date 6244@cindex Updating a file 6245@cindex Merging a file 6246@cindex Update, introduction 6247 6248When you want to update or merge a file, use the @code{cvs update -d} 6249command. For files that are not up to date this is roughly equivalent 6250to a @code{checkout} command: the newest revision of the file is 6251extracted from the repository and put in your working directory. The 6252@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} 6253that you wish it to create directories added by other developers. 6254 6255Your modifications to a file are never lost when you 6256use @code{update}. If no newer revision exists, 6257running @code{update} has no effect. If you have 6258edited the file, and a newer revision is available, 6259@sc{cvs} will merge all changes into your working copy. 6260 6261For instance, imagine that you checked out revision 1.4 and started 6262editing it. In the meantime someone else committed revision 1.5, and 6263shortly after that revision 1.6. If you run @code{update} on the file 6264now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 6265your file. 6266 6267@cindex Overlap 6268If any of the changes between 1.4 and 1.6 were made too 6269close to any of the changes you have made, an 6270@dfn{overlap} occurs. In such cases a warning is 6271printed, and the resulting file includes both 6272versions of the lines that overlap, delimited by 6273special markers. 6274@xref{update}, for a complete description of the 6275@code{update} command. 6276 6277@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6278@node Conflicts example 6279@section Conflicts example 6280@cindex Merge, an example 6281@cindex Example of merge 6282@cindex driver.c (merge example) 6283 6284Suppose revision 1.4 of @file{driver.c} contains this: 6285 6286@example 6287#include <stdio.h> 6288 6289void main() 6290@{ 6291 parse(); 6292 if (nerr == 0) 6293 gencode(); 6294 else 6295 fprintf(stderr, "No code generated.\n"); 6296 exit(nerr == 0 ? 0 : 1); 6297@} 6298@end example 6299 6300@noindent 6301Revision 1.6 of @file{driver.c} contains this: 6302 6303@example 6304#include <stdio.h> 6305 6306int main(int argc, 6307 char **argv) 6308@{ 6309 parse(); 6310 if (argc != 1) 6311 @{ 6312 fprintf(stderr, "tc: No args expected.\n"); 6313 exit(1); 6314 @} 6315 if (nerr == 0) 6316 gencode(); 6317 else 6318 fprintf(stderr, "No code generated.\n"); 6319 exit(!!nerr); 6320@} 6321@end example 6322 6323@noindent 6324Your working copy of @file{driver.c}, based on revision 63251.4, contains this before you run @samp{cvs update}: 6326@c -- Really include "cvs"? 6327 6328@example 6329#include <stdlib.h> 6330#include <stdio.h> 6331 6332void main() 6333@{ 6334 init_scanner(); 6335 parse(); 6336 if (nerr == 0) 6337 gencode(); 6338 else 6339 fprintf(stderr, "No code generated.\n"); 6340 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6341@} 6342@end example 6343 6344@noindent 6345You run @samp{cvs update}: 6346@c -- Really include "cvs"? 6347 6348@example 6349$ cvs update driver.c 6350RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 6351retrieving revision 1.4 6352retrieving revision 1.6 6353Merging differences between 1.4 and 1.6 into driver.c 6354rcsmerge warning: overlaps during merge 6355cvs update: conflicts found in driver.c 6356C driver.c 6357@end example 6358 6359@noindent 6360@cindex Conflicts (merge example) 6361@sc{cvs} tells you that there were some conflicts. 6362Your original working file is saved unmodified in 6363@file{.#driver.c.1.4}. The new version of 6364@file{driver.c} contains this: 6365 6366@example 6367#include <stdlib.h> 6368#include <stdio.h> 6369 6370int main(int argc, 6371 char **argv) 6372@{ 6373 init_scanner(); 6374 parse(); 6375 if (argc != 1) 6376 @{ 6377 fprintf(stderr, "tc: No args expected.\n"); 6378 exit(1); 6379 @} 6380 if (nerr == 0) 6381 gencode(); 6382 else 6383 fprintf(stderr, "No code generated.\n"); 6384@asis{}<<<<<<< driver.c 6385 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6386@asis{}======= 6387 exit(!!nerr); 6388@asis{}>>>>>>> 1.6 6389@} 6390@end example 6391 6392@noindent 6393@cindex Markers, conflict 6394@cindex Conflict markers 6395@cindex <<<<<<< 6396@cindex >>>>>>> 6397@cindex ======= 6398 6399Note how all non-overlapping modifications are incorporated in your working 6400copy, and that the overlapping section is clearly marked with 6401@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 6402 6403@cindex Resolving a conflict 6404@cindex Conflict resolution 6405You resolve the conflict by editing the file, removing the markers and 6406the erroneous line. Suppose you end up with this file: 6407@c -- Add xref to the pcl-cvs manual when it talks 6408@c -- about this. 6409@example 6410#include <stdlib.h> 6411#include <stdio.h> 6412 6413int main(int argc, 6414 char **argv) 6415@{ 6416 init_scanner(); 6417 parse(); 6418 if (argc != 1) 6419 @{ 6420 fprintf(stderr, "tc: No args expected.\n"); 6421 exit(1); 6422 @} 6423 if (nerr == 0) 6424 gencode(); 6425 else 6426 fprintf(stderr, "No code generated.\n"); 6427 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6428@} 6429@end example 6430 6431@noindent 6432You can now go ahead and commit this as revision 1.7. 6433 6434@example 6435$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 6436Checking in driver.c; 6437/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 6438new revision: 1.7; previous revision: 1.6 6439done 6440@end example 6441 6442For your protection, @sc{cvs} will refuse to check in a 6443file if a conflict occurred and you have not resolved 6444the conflict. Currently to resolve a conflict, you 6445must change the timestamp on the file. In previous 6446versions of @sc{cvs}, you also needed to 6447insure that the file contains no conflict markers. 6448Because 6449your file may legitimately contain conflict markers (that 6450is, occurrences of @samp{>>>>>>> } at the start of a 6451line that don't mark a conflict), the current 6452version of @sc{cvs} will print a warning and proceed to 6453check in the file. 6454@c The old behavior was really icky; the only way out 6455@c was to start hacking on 6456@c the @code{CVS/Entries} file or other such workarounds. 6457@c 6458@c If the timestamp thing isn't considered nice enough, 6459@c maybe there should be a "cvs resolved" command 6460@c which clears the conflict indication. For a nice user 6461@c interface, this should be invoked by an interactive 6462@c merge tool like emerge rather than by the user 6463@c directly--such a tool can verify that the user has 6464@c really dealt with each conflict. 6465 6466@cindex emerge 6467If you use release 1.04 or later of pcl-cvs (a @sc{gnu} 6468Emacs front-end for @sc{cvs}) you can use an Emacs 6469package called emerge to help you resolve conflicts. 6470See the documentation for pcl-cvs. 6471 6472@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6473@node Informing others 6474@section Informing others about commits 6475@cindex Informing others 6476@cindex Spreading information 6477@cindex Mail, automatic mail on commit 6478 6479It is often useful to inform others when you commit a 6480new revision of a file. The @samp{-i} option of the 6481@file{modules} file, or the @file{loginfo} file, can be 6482used to automate this process. @xref{modules}. 6483@xref{loginfo}. You can use these features of @sc{cvs} 6484to, for instance, instruct @sc{cvs} to mail a 6485message to all developers, or post a message to a local 6486newsgroup. 6487@c -- More text would be nice here. 6488 6489@node Concurrency 6490@section Several developers simultaneously attempting to run CVS 6491 6492@cindex Locks, cvs, introduction 6493@c For a discussion of *why* CVS creates locks, see 6494@c the comment at the start of src/lock.c 6495If several developers try to run @sc{cvs} at the same 6496time, one may get the following message: 6497 6498@example 6499[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 6500@end example 6501 6502@cindex #cvs.rfl, removing 6503@cindex #cvs.wfl, removing 6504@cindex #cvs.lock, removing 6505@sc{cvs} will try again every 30 seconds, and either 6506continue with the operation or print the message again, 6507if it still needs to wait. If a lock seems to stick 6508around for an undue amount of time, find the person 6509holding the lock and ask them about the cvs command 6510they are running. If they aren't running a cvs 6511command, look in the repository directory mentioned in 6512the message and remove files which they own whose names 6513start with @file{#cvs.rfl}, 6514@file{#cvs.wfl}, or @file{#cvs.lock}. 6515 6516Note that these locks are to protect @sc{cvs}'s 6517internal data structures and have no relationship to 6518the word @dfn{lock} in the sense used by 6519@sc{rcs}---which refers to reserved checkouts 6520(@pxref{Multiple developers}). 6521 6522Any number of people can be reading from a given 6523repository at a time; only when someone is writing do 6524the locks prevent other people from reading or writing. 6525 6526@cindex Atomic transactions, lack of 6527@cindex Transactions, atomic, lack of 6528@c the following talks about what one might call commit/update 6529@c atomicity. 6530@c Probably also should say something about 6531@c commit/commit atomicity, that is, "An update will 6532@c not get partial versions of more than one commit". 6533@c CVS currently has this property and I guess we can 6534@c make it a documented feature. 6535@c For example one person commits 6536@c a/one.c and b/four.c and another commits a/two.c and 6537@c b/three.c. Then an update cannot get the new a/one.c 6538@c and a/two.c and the old b/four.c and b/three.c. 6539One might hope for the following property: 6540 6541@quotation 6542If someone commits some changes in one cvs command, 6543then an update by someone else will either get all the 6544changes, or none of them. 6545@end quotation 6546 6547@noindent 6548but @sc{cvs} does @emph{not} have this property. For 6549example, given the files 6550 6551@example 6552a/one.c 6553a/two.c 6554b/three.c 6555b/four.c 6556@end example 6557 6558@noindent 6559if someone runs 6560 6561@example 6562cvs ci a/two.c b/three.c 6563@end example 6564 6565@noindent 6566and someone else runs @code{cvs update} at the same 6567time, the person running @code{update} might get only 6568the change to @file{b/three.c} and not the change to 6569@file{a/two.c}. 6570 6571@node Watches 6572@section Mechanisms to track who is editing files 6573@cindex Watches 6574 6575For many groups, use of @sc{cvs} in its default mode is 6576perfectly satisfactory. Users may sometimes go to 6577check in a modification only to find that another 6578modification has intervened, but they deal with it and 6579proceed with their check in. Other groups prefer to be 6580able to know who is editing what files, so that if two 6581people try to edit the same file they can choose to 6582talk about who is doing what when rather than be 6583surprised at check in time. The features in this 6584section allow such coordination, while retaining the 6585ability of two developers to edit the same file at the 6586same time. 6587 6588@c Some people might ask why CVS does not enforce the 6589@c rule on chmod, by requiring a cvs edit before a cvs 6590@c commit. The main reason is that it could always be 6591@c circumvented--one could edit the file, and 6592@c then when ready to check it in, do the cvs edit and put 6593@c in the new contents and do the cvs commit. One 6594@c implementation note: if we _do_ want to have cvs commit 6595@c require a cvs edit, we should store the state on 6596@c whether the cvs edit has occurred in the working 6597@c directory, rather than having the server try to keep 6598@c track of what working directories exist. 6599@c FIXME: should the above discussion be part of the 6600@c manual proper, somewhere, not just in a comment? 6601For maximum benefit developers should use @code{cvs 6602edit} (not @code{chmod}) to make files read-write to 6603edit them, and @code{cvs release} (not @code{rm}) to 6604discard a working directory which is no longer in use, 6605but @sc{cvs} is not able to enforce this behavior. 6606 6607If a development team wants stronger enforcement of 6608watches and all team members are using a @sc{cvs} client version 1.12.10 or 6609greater to access a @sc{cvs} server version 1.12.10 or greater, they can 6610enable advisory locks. To enable advisory locks, have all developers 6611put "edit -c" and "commit -c" into all .cvsrc files, 6612and make files default to read only by turning on watches 6613or putting "cvs -r" into all .cvsrc files. 6614This prevents multiple people from editting a file at 6615the same time (unless explicitly overriden with @samp{-f}). 6616 6617@c I'm a little dissatisfied with this presentation, 6618@c because "watch on"/"edit"/"editors" are one set of 6619@c functionality, and "watch add"/"watchers" is another 6620@c which is somewhat orthogonal even though they interact in 6621@c various ways. But I think it might be 6622@c confusing to describe them separately (e.g. "watch 6623@c add" with loginfo). I don't know. 6624 6625@menu 6626* Setting a watch:: Telling CVS to watch certain files 6627* Getting Notified:: Telling CVS to notify you 6628* Editing files:: How to edit a file which is being watched 6629* Watch information:: Information about who is watching and editing 6630* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 6631@end menu 6632 6633@node Setting a watch 6634@subsection Telling CVS to watch certain files 6635 6636To enable the watch features, you first specify that 6637certain files are to be watched. 6638 6639@cindex watch on (subcommand) 6640@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 6641 6642@cindex Read-only files, and watches 6643Specify that developers should run @code{cvs edit} 6644before editing @var{files}. @sc{cvs} will create working 6645copies of @var{files} read-only, to remind developers 6646to run the @code{cvs edit} command before working on 6647them. 6648 6649If @var{files} includes the name of a directory, @sc{cvs} 6650arranges to watch all files added to the corresponding 6651repository directory, and sets a default for files 6652added in the future; this allows the user to set 6653notification policies on a per-directory basis. The 6654contents of the directory are processed recursively, 6655unless the @code{-l} option is given. 6656The @code{-R} option can be used to force recursion if the @code{-l} 6657option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 6658 6659If @var{files} is omitted, it defaults to the current directory. 6660 6661@cindex watch off (subcommand) 6662@end deffn 6663 6664@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 6665 6666Do not create @var{files} read-only on checkout; thus, 6667developers will not be reminded to use @code{cvs edit} 6668and @code{cvs unedit}. 6669@ignore 6670@sc{cvs} will check out @var{files} 6671read-write as usual, unless other permissions override 6672due to the @code{PreservePermissions} option being 6673enabled in the @file{config} administrative file 6674(@pxref{Special Files}, @pxref{config}) 6675@end ignore 6676 6677The @var{files} and options are processed as for @code{cvs 6678watch on}. 6679 6680@end deffn 6681 6682@node Getting Notified 6683@subsection Telling CVS to notify you 6684 6685You can tell @sc{cvs} that you want to receive 6686notifications about various actions taken on a file. 6687You can do this without using @code{cvs watch on} for 6688the file, but generally you will want to use @code{cvs 6689watch on}, to remind developers to use the @code{cvs edit} 6690command. 6691 6692@cindex watch add (subcommand) 6693@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6694 6695Add the current user to the list of people to receive notification of 6696work done on @var{files}. 6697 6698The @code{-a} option specifies what kinds of events @sc{cvs} should notify 6699the user about. @var{action} is one of the following: 6700 6701@table @code 6702 6703@item edit 6704Another user has applied the @code{cvs edit} command (described 6705below) to a watched file. 6706 6707@item commit 6708Another user has committed changes to one of the named @var{files}. 6709 6710@item unedit 6711Another user has abandoned editing a file (other than by committing changes). 6712They can do this in several ways, by: 6713 6714@itemize @bullet 6715 6716@item 6717applying the @code{cvs unedit} command (described below) to the file 6718 6719@item 6720applying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6721(or recursively to a directory more than one level up) 6722 6723@item 6724deleting the file and allowing @code{cvs update} to recreate it 6725 6726@end itemize 6727 6728@item all 6729All of the above. 6730 6731@item none 6732None of the above. (This is useful with @code{cvs edit}, 6733described below.) 6734 6735@end table 6736 6737The @code{-a} option may appear more than once, or not at all. If 6738omitted, the action defaults to @code{all}. 6739 6740The @var{files} and options are processed as for 6741@code{cvs watch on}. 6742 6743@end deffn 6744 6745 6746@cindex watch remove (subcommand) 6747@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6748 6749Remove a notification request established using @code{cvs watch add}; 6750the arguments are the same. If the @code{-a} option is present, only 6751watches for the specified actions are removed. 6752 6753@end deffn 6754 6755@cindex notify (admin file) 6756When the conditions exist for notification, @sc{cvs} 6757calls the @file{notify} administrative file. Edit 6758@file{notify} as one edits the other administrative 6759files (@pxref{Intro administrative files}). This 6760file follows the usual conventions for administrative 6761files (@pxref{syntax}), where each line is a regular 6762expression followed by a command to execute. The 6763command should contain a single occurrence of @samp{%s} 6764which will be replaced by the user to notify; the rest 6765of the information regarding the notification will be 6766supplied to the command on standard input. The 6767standard thing to put in the @code{notify} file is the 6768single line: 6769 6770@example 6771ALL mail %s -s "CVS notification" 6772@end example 6773 6774@noindent 6775This causes users to be notified by electronic mail. 6776@c FIXME: should it be this hard to set up this 6777@c behavior (and the result when one fails to do so, 6778@c silent failure to notify, so non-obvious)? Should 6779@c CVS give a warning if no line in notify matches (and 6780@c document the use of "DEFAULT :" for the case where 6781@c skipping the notification is indeed desired)? 6782 6783@cindex users (admin file) 6784Note that if you set this up in the straightforward 6785way, users receive notifications on the server machine. 6786One could of course write a @file{notify} script which 6787directed notifications elsewhere, but to make this 6788easy, @sc{cvs} allows you to associate a notification 6789address for each user. To do so create a file 6790@file{users} in @file{CVSROOT} with a line for each 6791user in the format @var{user}:@var{value}. Then 6792instead of passing the name of the user to be notified 6793to @file{notify}, @sc{cvs} will pass the @var{value} 6794(normally an email address on some other machine). 6795 6796@sc{cvs} does not notify you for your own changes. 6797Currently this check is done based on whether the user 6798name of the person taking the action which triggers 6799notification matches the user name of the person 6800getting notification. In fact, in general, the watches 6801features only track one edit by each user. It probably 6802would be more useful if watches tracked each working 6803directory separately, so this behavior might be worth 6804changing. 6805@c "behavior might be worth changing" is an effort to 6806@c point to future directions while also not promising 6807@c that "they" (as in "why don't they fix CVS to....") 6808@c will do this. 6809@c one implementation issue is identifying whether a 6810@c working directory is same or different. Comparing 6811@c pathnames/hostnames is hopeless, but having the server 6812@c supply a serial number which the client stores in the 6813@c CVS directory as a magic cookie should work. 6814 6815@node Editing files 6816@subsection How to edit a file which is being watched 6817 6818@cindex Checkout, as term for getting ready to edit 6819Since a file which is being watched is checked out 6820read-only, you cannot simply edit it. To make it 6821read-write, and inform others that you are planning to 6822edit it, use the @code{cvs edit} command. Some systems 6823call this a @dfn{checkout}, but @sc{cvs} uses that term 6824for obtaining a copy of the sources (@pxref{Getting the 6825source}), an operation which those systems call a 6826@dfn{get} or a @dfn{fetch}. 6827@c Issue to think about: should we transition CVS 6828@c towards the "get" terminology? "cvs get" is already a 6829@c synonym for "cvs checkout" and that section of the 6830@c manual refers to "Getting the source". If this is 6831@c done, needs to be done gingerly (for example, we should 6832@c still accept "checkout" in .cvsrc files indefinitely 6833@c even if the CVS's messages are changed from "cvs checkout: " 6834@c to "cvs get: "). 6835@c There is a concern about whether "get" is not as 6836@c good for novices because it is a more general term 6837@c than "checkout" (and thus arguably harder to assign 6838@c a technical meaning for). 6839 6840@cindex edit (subcommand) 6841@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6842 6843Prepare to edit the working files @var{files}. @sc{cvs} makes the 6844@var{files} read-write, and notifies users who have requested 6845@code{edit} notification for any of @var{files}. 6846 6847The @code{cvs edit} command accepts the same options as the 6848@code{cvs watch add} command, and establishes a temporary watch for the 6849user on @var{files}; @sc{cvs} will remove the watch when @var{files} are 6850@code{unedit}ed or @code{commit}ted. If the user does not wish to 6851receive notifications, she should specify @code{-a none}. 6852 6853The @var{files} and the options are processed as for the @code{cvs 6854watch} commands. 6855 6856There are two additional options that @code{cvs edit} understands as of 6857@sc{cvs} client and server versions 1.12.10 but @code{cvs watch} does not. 6858The first is @code{-c}, which causes @code{cvs edit} to fail if anyone else 6859is editting the file. This is probably only useful when @samp{edit -c} and 6860@samp{commit -c} are specified in all developers' @file{.cvsrc} files. This 6861behavior may be overriden this via the @code{-f} option, which overrides 6862@code{-c} and allows multiple edits to succeed. 6863 6864@ignore 6865@strong{Caution: If the @code{PreservePermissions} 6866option is enabled in the repository (@pxref{config}), 6867@sc{cvs} will not change the permissions on any of the 6868@var{files}. The reason for this change is to ensure 6869that using @samp{cvs edit} does not interfere with the 6870ability to store file permissions in the @sc{cvs} 6871repository.} 6872@end ignore 6873 6874@end deffn 6875 6876Normally when you are done with a set of changes, you 6877use the @code{cvs commit} command, which checks in your 6878changes and returns the watched files to their usual 6879read-only state. But if you instead decide to abandon 6880your changes, or not to make any changes, you can use 6881the @code{cvs unedit} command. 6882 6883@cindex unedit (subcommand) 6884@cindex Abandoning work 6885@cindex Reverting to repository version 6886@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 6887 6888Abandon work on the working files @var{files}, and revert them to the 6889repository versions on which they are based. @sc{cvs} makes those 6890@var{files} read-only for which users have requested notification using 6891@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 6892notification for any of @var{files}. 6893 6894The @var{files} and options are processed as for the 6895@code{cvs watch} commands. 6896 6897If watches are not in use, the @code{unedit} command 6898probably does not work, and the way to revert to the 6899repository version is with the command @code{cvs update -C file} 6900(@pxref{update}). 6901The meaning is 6902not precisely the same; the latter may also 6903bring in some changes which have been made in the 6904repository since the last time you updated. 6905@c It would be a useful enhancement to CVS to make 6906@c unedit work in the non-watch case as well. 6907@end deffn 6908 6909When using client/server @sc{cvs}, you can use the 6910@code{cvs edit} and @code{cvs unedit} commands even if 6911@sc{cvs} is unable to successfully communicate with the 6912server; the notifications will be sent upon the next 6913successful @sc{cvs} command. 6914 6915@node Watch information 6916@subsection Information about who is watching and editing 6917 6918@cindex watchers (subcommand) 6919@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 6920 6921List the users currently watching changes to @var{files}. The report 6922includes the files being watched, and the mail address of each watcher. 6923 6924The @var{files} and options are processed as for the 6925@code{cvs watch} commands. 6926 6927@end deffn 6928 6929 6930@cindex editors (subcommand) 6931@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 6932 6933List the users currently working on @var{files}. The report 6934includes the mail address of each user, the time when the user began 6935working with the file, and the host and path of the working directory 6936containing the file. 6937 6938The @var{files} and options are processed as for the 6939@code{cvs watch} commands. 6940 6941@end deffn 6942 6943@node Watches Compatibility 6944@subsection Using watches with old versions of CVS 6945 6946@cindex CVS 1.6, and watches 6947If you use the watch features on a repository, it 6948creates @file{CVS} directories in the repository and 6949stores the information about watches in that directory. 6950If you attempt to use @sc{cvs} 1.6 or earlier with the 6951repository, you get an error message such as the 6952following (all on one line): 6953 6954@example 6955cvs update: cannot open CVS/Entries for reading: 6956No such file or directory 6957@end example 6958 6959@noindent 6960and your operation will likely be aborted. To use the 6961watch features, you must upgrade all copies of @sc{cvs} 6962which use that repository in local or server mode. If 6963you cannot upgrade, use the @code{watch off} and 6964@code{watch remove} commands to remove all watches, and 6965that will restore the repository to a state which 6966@sc{cvs} 1.6 can cope with. 6967 6968@node Choosing a model 6969@section Choosing between reserved or unreserved checkouts 6970@cindex Choosing, reserved or unreserved checkouts 6971 6972Reserved and unreserved checkouts each have pros and 6973cons. Let it be said that a lot of this is a matter of 6974opinion or what works given different groups' working 6975styles, but here is a brief description of some of the 6976issues. There are many ways to organize a team of 6977developers. @sc{cvs} does not try to enforce a certain 6978organization. It is a tool that can be used in several 6979ways. 6980 6981Reserved checkouts can be very counter-productive. If 6982two persons want to edit different parts of a file, 6983there may be no reason to prevent either of them from 6984doing so. Also, it is common for someone to take out a 6985lock on a file, because they are planning to edit it, 6986but then forget to release the lock. 6987 6988@c "many groups"? specifics? cites to papers on this? 6989@c some way to weasel-word it a bit more so we don't 6990@c need facts :-)? 6991People, especially people who are familiar with 6992reserved checkouts, often wonder how often conflicts 6993occur if unreserved checkouts are used, and how 6994difficult they are to resolve. The experience with 6995many groups is that they occur rarely and usually are 6996relatively straightforward to resolve. 6997 6998The rarity of serious conflicts may be surprising, until one realizes 6999that they occur only when two developers disagree on the proper design 7000for a given section of code; such a disagreement suggests that the 7001team has not been communicating properly in the first place. In order 7002to collaborate under @emph{any} source management regimen, developers 7003must agree on the general design of the system; given this agreement, 7004overlapping changes are usually straightforward to merge. 7005 7006In some cases unreserved checkouts are clearly 7007inappropriate. If no merge tool exists for the kind of 7008file you are managing (for example word processor files 7009or files edited by Computer Aided Design programs), and 7010it is not desirable to change to a program which uses a 7011mergeable data format, then resolving conflicts is 7012going to be unpleasant enough that you generally will 7013be better off to simply avoid the conflicts instead, by 7014using reserved checkouts. 7015 7016The watches features described above in @ref{Watches} 7017can be considered to be an intermediate model between 7018reserved checkouts and unreserved checkouts. When you 7019go to edit a file, it is possible to find out who else 7020is editing it. And rather than having the system 7021simply forbid both people editing the file, it can tell 7022you what the situation is and let you figure out 7023whether it is a problem in that particular case or not. 7024Therefore, for some groups watches can be 7025considered the best of both the reserved checkout and unreserved 7026checkout worlds. 7027 7028As of @sc{cvs} client and server versions 1.12.10, you may also enable 7029advisory locks by putting @samp{edit -c} and @samp{commit -c} in all 7030developers' @file{.cvsrc} files. After this is done, @code{cvs edit} 7031will fail if there are any other editors, and @code{cvs commit} will 7032fail if the committer has not registered to edit the file via @code{cvs edit}. 7033This is most effective in conjunction with files checked out read-only by 7034default, which may be enabled by turning on watches in the repository or by 7035putting @samp{cvs -r} in all @file{.cvsrc} files. 7036 7037 7038@c --------------------------------------------------------------------- 7039@node Revision management 7040@chapter Revision management 7041@cindex Revision management 7042 7043@c -- This chapter could be expanded a lot. 7044@c -- Experiences are very welcome! 7045 7046If you have read this far, you probably have a pretty 7047good grasp on what @sc{cvs} can do for you. This 7048chapter talks a little about things that you still have 7049to decide. 7050 7051If you are doing development on your own using @sc{cvs} 7052you could probably skip this chapter. The questions 7053this chapter takes up become more important when more 7054than one person is working in a repository. 7055 7056@menu 7057* When to commit:: Some discussion on the subject 7058@end menu 7059 7060@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7061@node When to commit 7062@section When to commit? 7063@cindex When to commit 7064@cindex Committing, when to 7065@cindex Policy 7066 7067Your group should decide which policy to use regarding 7068commits. Several policies are possible, and as your 7069experience with @sc{cvs} grows you will probably find 7070out what works for you. 7071 7072If you commit files too quickly you might commit files 7073that do not even compile. If your partner updates his 7074working sources to include your buggy file, he will be 7075unable to compile the code. On the other hand, other 7076persons will not be able to benefit from the 7077improvements you make to the code if you commit very 7078seldom, and conflicts will probably be more common. 7079 7080It is common to only commit files after making sure 7081that they can be compiled. Some sites require that the 7082files pass a test suite. Policies like this can be 7083enforced using the commitinfo file 7084(@pxref{commitinfo}), but you should think twice before 7085you enforce such a convention. By making the 7086development environment too controlled it might become 7087too regimented and thus counter-productive to the real 7088goal, which is to get software written. 7089 7090@c --------------------------------------------------------------------- 7091@node Keyword substitution 7092@chapter Keyword substitution 7093@cindex Keyword substitution 7094@cindex Keyword expansion 7095@cindex Identifying files 7096 7097@comment Be careful when editing this chapter. 7098@comment Remember that this file is kept under 7099@comment version control, so we must not accidentally 7100@comment include a valid keyword in the running text. 7101 7102As long as you edit source files inside a working 7103directory you can always find out the state of 7104your files via @samp{cvs status} and @samp{cvs log}. 7105But as soon as you export the files from your 7106development environment it becomes harder to identify 7107which revisions they are. 7108 7109@sc{cvs} can use a mechanism known as @dfn{keyword 7110substitution} (or @dfn{keyword expansion}) to help 7111identifying the files. Embedded strings of the form 7112@code{$@var{keyword}$} and 7113@code{$@var{keyword}:@dots{}$} in a file are replaced 7114with strings of the form 7115@code{$@var{keyword}:@var{value}$} whenever you obtain 7116a new revision of the file. 7117 7118@menu 7119* Keyword list:: Keywords 7120* Using keywords:: Using keywords 7121* Avoiding substitution:: Avoiding substitution 7122* Substitution modes:: Substitution modes 7123* Configuring keyword expansion:: Configuring keyword expansion 7124* Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. 7125@end menu 7126 7127@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7128@node Keyword list 7129@section Keyword List 7130@cindex Keyword List 7131 7132@c FIXME: need some kind of example here I think, 7133@c perhaps in a 7134@c "Keyword intro" node. The intro in the "Keyword 7135@c substitution" node itself seems OK, but to launch 7136@c into a list of the keywords somehow seems too abrupt. 7137 7138This is a list of the keywords: 7139 7140@table @code 7141@cindex Author keyword 7142@item $@splitrcskeyword{Author}$ 7143The login name of the user who checked in the revision. 7144 7145@cindex CVSHeader keyword 7146@item $@splitrcskeyword{CVSHeader}$ 7147A standard header (similar to $@splitrcskeyword{Header}$, but with 7148the CVS root stripped off). It contains the relative 7149pathname of the @sc{rcs} file to the CVS root, the 7150revision number, the date (UTC), the author, the state, 7151and the locker (if locked). Files will normally never 7152be locked when you use @sc{cvs}. 7153 7154Note that this keyword has only been recently 7155introduced to @sc{cvs} and may cause problems with 7156existing installations if $@splitrcskeyword{CVSHeader}$ is already 7157in the files for a different purpose. This keyword may 7158be excluded using the @code{KeywordExpand=eCVSHeader} 7159in the @file{CVSROOT/config} file. 7160See @ref{Configuring keyword expansion} for more details. 7161 7162@cindex Date keyword 7163@item $@splitrcskeyword{Date}$ 7164The date and time (UTC) the revision was checked in. 7165 7166@cindex Header keyword 7167@item $@splitrcskeyword{Header}$ 7168A standard header containing the full pathname of the 7169@sc{rcs} file, the revision number, the date (UTC), the 7170author, the state, and the locker (if locked). Files 7171will normally never be locked when you use @sc{cvs}. 7172 7173@cindex Id keyword 7174@item $@splitrcskeyword{Id}$ 7175Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} 7176filename is without a path. 7177 7178@cindex Name keyword 7179@item $@splitrcskeyword{Name}$ 7180Tag name used to check out this file. The keyword is 7181expanded only if one checks out with an explicit tag 7182name. For example, when running the command @code{cvs 7183co -r first}, the keyword expands to @samp{Name: first}. 7184 7185@cindex Locker keyword 7186@item $@splitrcskeyword{Locker}$ 7187The login name of the user who locked the revision 7188(empty if not locked, which is the normal case unless 7189@code{cvs admin -l} is in use). 7190 7191@cindex Log keyword 7192@cindex MaxCommentLeaderLength 7193@cindex UseArchiveCommentLeader 7194@cindex Log keyword, configuring substitution behavior 7195@item $@splitrcskeyword{Log}$ 7196The log message supplied during commit, preceded by a 7197header containing the @sc{rcs} filename, the revision 7198number, the author, and the date (UTC). Existing log 7199messages are @emph{not} replaced. Instead, the new log 7200message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}. 7201By default, each new line is prefixed with the same string which 7202precedes the @code{$@splitrcskeyword{Log}$} keyword, unless it exceeds the 7203@code{MaxCommentLeaderLength} set in @file{CVSROOT/config}. 7204 7205For example, if the file contains: 7206 7207@example 7208 /* Here is what people have been up to: 7209 * 7210 * $@splitrcskeyword{Log}: frob.c,v $ 7211 * Revision 1.1 1997/01/03 14:23:51 joe 7212 * Add the superfrobnicate option 7213 * 7214 */ 7215@end example 7216 7217@noindent 7218then additional lines which are added when expanding 7219the @code{$@splitrcskeyword{Log}$} keyword will be preceded by @samp{ * }. 7220Unlike previous versions of @sc{cvs} and @sc{rcs}, the 7221@dfn{comment leader} from the @sc{rcs} file is not used. 7222The @code{$@splitrcskeyword{Log}$} keyword is useful for 7223accumulating a complete change log in a source file, 7224but for several reasons it can be problematic. 7225 7226If the prefix of the @code{$@splitrcskeyword{Log}$} keyword turns out to be 7227longer than @code{MaxCommentLeaderLength}, CVS will skip expansion of this 7228keyword unless @code{UseArchiveCommentLeader} is also set in 7229@file{CVSROOT/config} and a @samp{comment leader} is set in the RCS archive 7230file, in which case the comment leader will be used instead. For more on 7231setting the comment leader in the RCS archive file, @xref{admin}. For more 7232on configuring the default @code{$@splitrcskeyword{Log}$} substitution 7233behavior, @xref{config}. 7234 7235@xref{Log keyword}. 7236 7237@cindex RCSfile keyword 7238@item $@splitrcskeyword{RCSfile}$ 7239The name of the RCS file without a path. 7240 7241@cindex Revision keyword 7242@item $@splitrcskeyword{Revision}$ 7243The revision number assigned to the revision. 7244 7245@cindex Source keyword 7246@item $@splitrcskeyword{Source}$ 7247The full pathname of the RCS file. 7248 7249@cindex State keyword 7250@item $@splitrcskeyword{State}$ 7251The state assigned to the revision. States can be 7252assigned with @code{cvs admin -s}---see @ref{admin options}. 7253 7254@cindex Local keyword 7255@item Local keyword 7256The @code{LocalKeyword} option in the @file{CVSROOT/config} file 7257may be used to specify a local keyword which is to be 7258used as an alias for one of the keywords: $@splitrcskeyword{Id}$, 7259$@splitrcskeyword{Header}$, or $@splitrcskeyword{CVSHeader}$. For 7260example, if the @file{CVSROOT/config} file contains 7261a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a 7262file with the local keyword $@splitrcskeyword{MYBSD}$ will be 7263expanded as if it were a $@splitrcskeyword{CVSHeader}$ keyword. If 7264the src/frob.c file contained this keyword, it might 7265look something like this: 7266 7267@example 7268 /* 7269 * $@splitrcskeyword{MYBSD}: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 7270 */ 7271@end example 7272 7273Many repositories make use of a such a ``local 7274keyword'' feature. An old patch to @sc{cvs} provided 7275the @code{LocalKeyword} feature using a @code{tag=} 7276option and called this the ``custom tag'' or ``local 7277tag'' feature. It was used in conjunction with the 7278what they called the @code{tagexpand=} option. In 7279@sc{cvs} this other option is known as the 7280@code{KeywordExpand} option. 7281See @ref{Configuring keyword expansion} for more 7282details. 7283 7284Examples from popular projects include: 7285$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7286$@splitrcskeyword{OpenBSD}$, $@splitrcskeyword{XFree86}$, 7287$@splitrcskeyword{Xorg}$. 7288 7289The advantage of this is that you can include your 7290local version information in a file using this local 7291keyword without disrupting the upstream version 7292information (which may be a different local keyword or 7293a standard keyword). Allowing bug reports and the like 7294to more properly identify the source of the original 7295bug to the third-party and reducing the number of 7296conflicts that arise during an import of a new version. 7297 7298All keyword expansion except the local keyword may be 7299disabled using the @code{KeywordExpand} option in 7300the @file{CVSROOT/config} file---see 7301@ref{Configuring keyword expansion} for more details. 7302 7303@end table 7304 7305@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7306@node Using keywords 7307@section Using keywords 7308 7309To include a keyword string you simply include the 7310relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the 7311file, and commit the file. @sc{cvs} will automatically (Or, 7312more accurately, as part of the update run that 7313automatically happens after a commit.) 7314expand the string as part of the commit operation. 7315 7316It is common to embed the @code{$@splitrcskeyword{Id}$} string in 7317the source files so that it gets passed through to 7318generated files. For example, if you are managing 7319computer program source code, you might include a 7320variable which is initialized to contain that string. 7321Or some C compilers may provide a @code{#pragma ident} 7322directive. Or a document management system might 7323provide a way to pass a string through to generated 7324files. 7325 7326@c Would be nice to give an example, but doing this in 7327@c portable C is not possible and the problem with 7328@c picking any one language (VMS HELP files, Ada, 7329@c troff, whatever) is that people use CVS for all 7330@c kinds of files. 7331 7332@cindex Ident (shell command) 7333The @code{ident} command (which is part of the @sc{rcs} 7334package) can be used to extract keywords and their 7335values from a file. This can be handy for text files, 7336but it is even more useful for extracting keywords from 7337binary files. 7338 7339@example 7340$ ident samp.c 7341samp.c: 7342 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7343$ gcc samp.c 7344$ ident a.out 7345a.out: 7346 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7347@end example 7348 7349@cindex What (shell command) 7350S@sc{ccs} is another popular revision control system. 7351It has a command, @code{what}, which is very similar to 7352@code{ident} and used for the same purpose. Many sites 7353without @sc{rcs} have @sc{sccs}. Since @code{what} 7354looks for the character sequence @code{@@(#)} it is 7355easy to include keywords that are detected by either 7356command. Simply prefix the keyword with the 7357magic @sc{sccs} phrase, like this: 7358 7359@example 7360static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 7361@end example 7362 7363@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7364@node Avoiding substitution 7365@section Avoiding substitution 7366 7367Keyword substitution has its disadvantages. Sometimes 7368you might want the literal text string 7369@samp{$@splitrcskeyword{Author}$} to appear inside a file without 7370@sc{cvs} interpreting it as a keyword and expanding it 7371into something like @samp{$@splitrcskeyword{Author}: ceder $}. 7372 7373There is unfortunately no way to selectively turn off 7374keyword substitution. You can use @samp{-ko} 7375(@pxref{Substitution modes}) to turn off keyword 7376substitution entirely. 7377 7378In many cases you can avoid using keywords in 7379the source, even though they appear in the final 7380product. For example, the source for this manual 7381contains @samp{$@@asis@{@}Author$} whenever the text 7382@samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff} 7383and @code{troff} you can embed the null-character 7384@code{\&} inside the keyword for a similar effect. 7385 7386It is also possible to specify an explicit list of 7387keywords to include or exclude using the 7388@code{KeywordExpand} option in the 7389@file{CVSROOT/config} file--see @ref{Configuring keyword expansion} 7390for more details. This feature is intended primarily 7391for use with the @code{LocalKeyword} option--see 7392@ref{Keyword list}. 7393 7394@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7395@node Substitution modes 7396@section Substitution modes 7397@cindex Keyword substitution, changing modes 7398@cindex -k (keyword substitution) 7399@cindex Kflag 7400 7401@c FIXME: This could be made more coherent, by expanding it 7402@c with more examples or something. 7403Each file has a stored default substitution mode, and 7404each working directory copy of a file also has a 7405substitution mode. The former is set by the @samp{-k} 7406option to @code{cvs add} and @code{cvs admin}; the 7407latter is set by the @samp{-k} or @samp{-A} options to @code{cvs 7408checkout} or @code{cvs update}. 7409@code{cvs diff} and @code{cvs rdiff} also 7410have @samp{-k} options. 7411For some examples, 7412see @ref{Binary files}, and @ref{Merging and keywords}. 7413@c The fact that -A is overloaded to mean both reset 7414@c sticky options and reset sticky tags/dates is 7415@c somewhat questionable. Perhaps there should be 7416@c separate options to reset sticky options (e.g. -k 7417@c A") and tags/dates (someone suggested -r HEAD could 7418@c do this instead of setting a sticky tag of "HEAD" 7419@c as in the status quo but I haven't thought much 7420@c about that idea. Of course -r .reset or something 7421@c could be coined if this needs to be a new option). 7422@c On the other hand, having -A mean "get things back 7423@c into the state after a fresh checkout" has a certain 7424@c appeal, and maybe there is no sufficient reason for 7425@c creeping featurism in this area. 7426 7427The modes available are: 7428 7429@table @samp 7430@item -kkv 7431Generate keyword strings using the default form, e.g. 7432@code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision} 7433keyword. 7434 7435@item -kkvl 7436Like @samp{-kkv}, except that a locker's name is always 7437inserted if the given revision is currently locked. 7438The locker's name is only relevant if @code{cvs admin 7439-l} is in use. 7440 7441@item -kk 7442Generate only keyword names in keyword strings; omit 7443their values. For example, for the @code{Revision} 7444keyword, generate the string @code{$@splitrcskeyword{Revision}$} 7445instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option 7446is useful to ignore differences due to keyword 7447substitution when comparing different revisions of a 7448file (@pxref{Merging and keywords}). 7449 7450@item -ko 7451Generate the old keyword string, present in the working 7452file just before it was checked in. For example, for 7453the @code{Revision} keyword, generate the string 7454@code{$@splitrcskeyword{Revision}: 1.1 $} instead of 7455@code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the 7456string appeared when the file was checked in. 7457 7458@item -kb 7459Like @samp{-ko}, but also inhibit conversion of line 7460endings between the canonical form in which they are 7461stored in the repository (linefeed only), and the form 7462appropriate to the operating system in use on the 7463client. For systems, like unix, which use linefeed 7464only to terminate lines, this is very similar to 7465@samp{-ko}. For more information on binary files, see 7466@ref{Binary files}. In @sc{cvs} version 1.12.2 and later 7467@samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or 7468@code{cvs import} may not be overridden by a @samp{-k} option 7469specified on the command line. 7470 7471@item -kv 7472Generate only keyword values for keyword strings. For 7473example, for the @code{Revision} keyword, generate the string 7474@code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. 7475This can help generate files in programming languages 7476where it is hard to strip keyword delimiters like 7477@code{$@splitrcskeyword{Revision}: $} from a string. However, 7478further keyword substitution cannot be performed once 7479the keyword names are removed, so this option should be 7480used with care. 7481 7482One often would like to use @samp{-kv} with @code{cvs 7483export}---@pxref{export}. But be aware that doesn't 7484handle an export containing binary files correctly. 7485 7486@end table 7487 7488@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7489@node Configuring keyword expansion 7490@section Configuring Keyword Expansion 7491@cindex Configuring keyword expansion 7492 7493In a repository that includes third-party software on 7494vendor branches, it is sometimes helpful to configure 7495CVS to use a local keyword instead of the standard 7496$@splitrcskeyword{Id}$ or $@splitrcskeyword{Header}$ keywords. Examples from 7497real projects include $@splitrcskeyword{Xorg}$, $@splitrcskeyword{XFree86}$, 7498$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7499$@splitrcskeyword{OpenBSD}$, and even $@splitrcskeyword{dotat}$. 7500The advantage of this is that 7501you can include your local version information in a 7502file using this local keyword (sometimes called a 7503``custom tag'' or a ``local tag'') without disrupting 7504the upstream version information (which may be a 7505different local keyword or a standard keyword). In 7506these cases, it is typically desirable to disable the 7507expansion of all keywords except the configured local 7508keyword. 7509 7510The @code{KeywordExpand} option in the 7511@file{CVSROOT/config} file is intended to allow for the 7512either the explicit exclusion of a keyword or list of 7513keywords, or for the explicit inclusion of a keyword or 7514a list of keywords. This list may include the 7515@code{LocalKeyword} that has been configured. 7516 7517The @code{KeywordExpand} option is followed by 7518@code{=} and the next character may either be @code{i} 7519to start an inclusion list or @code{e} to start an 7520exclusion list. If the following lines were added to 7521the @file{CVSROOT/config} file: 7522 7523@example 7524 # Add a "MyBSD" keyword and restrict keyword 7525 # expansion 7526 LocalKeyword=MyBSD=CVSHeader 7527 KeywordExpand=iMyBSD 7528@end example 7529 7530then only the $@splitrcskeyword{MyBSD}$ keyword would be expanded. 7531A list may be used. The this example: 7532 7533@example 7534 # Add a "MyBSD" keyword and restrict keyword 7535 # expansion to the MyBSD, Name and Date keywords. 7536 LocalKeyword=MyBSD=CVSHeader 7537 KeywordExpand=iMyBSD,Name,Date 7538@end example 7539 7540would allow $@splitrcskeyword{MyBSD}$, $@splitrcskeyword{Name}$, and 7541$@splitrcskeyword{Date}$ to be expanded. 7542 7543It is also possible to configure an exclusion list 7544using the following: 7545 7546@example 7547 # Do not expand the non-RCS keyword CVSHeader 7548 KeywordExpand=eCVSHeader 7549@end example 7550 7551This allows @sc{cvs} to ignore the recently introduced 7552$@splitrcskeyword{CVSHeader}$ keyword and retain all of the 7553others. The exclusion entry could also contain the 7554standard RCS keyword list, but this could be confusing 7555to users that expect RCS keywords to be expanded, so 7556care should be taken to properly set user expectations 7557for a repository that is configured in that manner. 7558 7559If there is a desire to not have any RCS keywords 7560expanded and not use the @code{-ko} flags everywhere, 7561an administrator may disable all keyword expansion 7562using the @file{CVSROOT/config} line: 7563 7564@example 7565 # Do not expand any RCS keywords 7566 KeywordExpand=i 7567@end example 7568 7569this could be confusing to users that expect RCS 7570keywords like $@splitrcskeyword{Id}$ to be expanded properly, 7571so care should be taken to properly set user 7572expectations for a repository so configured. 7573 7574It should be noted that a patch to provide both the 7575@code{KeywordExpand} and @code{LocalKeyword} features 7576has been around a long time. However, that patch 7577implemented these features using @code{tag=} and 7578@code{tagexpand=} keywords and those keywords are NOT 7579recognized. 7580 7581@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7582@node Log keyword 7583@section Problems with the $@splitrcskeyword{Log}$ keyword. 7584 7585The @code{$@splitrcskeyword{Log}$} keyword is somewhat 7586controversial. As long as you are working on your 7587development system the information is easily accessible 7588even if you do not use the @code{$@splitrcskeyword{Log}$} 7589keyword---just do a @code{cvs log}. Once you export 7590the file the history information might be useless 7591anyhow. 7592 7593A more serious concern is that @sc{cvs} is not good at 7594handling @code{$@splitrcskeyword{Log}$} entries when a branch is 7595merged onto the main trunk. Conflicts often result 7596from the merging operation. 7597@c Might want to check whether the CVS implementation 7598@c of RCS_merge has this problem the same way rcsmerge 7599@c does. I would assume so.... 7600 7601People also tend to "fix" the log entries in the file 7602(correcting spelling mistakes and maybe even factual 7603errors). If that is done the information from 7604@code{cvs log} will not be consistent with the 7605information inside the file. This may or may not be a 7606problem in real life. 7607 7608It has been suggested that the @code{$@splitrcskeyword{Log}$} 7609keyword should be inserted @emph{last} in the file, and 7610not in the files header, if it is to be used at all. 7611That way the long list of change messages will not 7612interfere with everyday source file browsing. 7613 7614@c --------------------------------------------------------------------- 7615@node Tracking sources 7616@chapter Tracking third-party sources 7617@cindex Third-party sources 7618@cindex Tracking sources 7619 7620@c FIXME: Need discussion of added and removed files. 7621@c FIXME: This doesn't really adequately introduce the 7622@c concepts of "vendor" and "you". They don't *have* 7623@c to be separate organizations or separate people. 7624@c We want a description which is somewhat more based on 7625@c the technical issues of which sources go where, but 7626@c also with enough examples of how this relates to 7627@c relationships like customer-supplier, developer-QA, 7628@c maintainer-contributor, or whatever, to make it 7629@c seem concrete. 7630If you modify a program to better fit your site, you 7631probably want to include your modifications when the next 7632release of the program arrives. @sc{cvs} can help you with 7633this task. 7634 7635@cindex Vendor 7636@cindex Vendor branch 7637@cindex Branch, vendor- 7638In the terminology used in @sc{cvs}, the supplier of the 7639program is called a @dfn{vendor}. The unmodified 7640distribution from the vendor is checked in on its own 7641branch, the @dfn{vendor branch}. @sc{cvs} reserves branch 76421.1.1 for this use. 7643 7644When you modify the source and commit it, your revision 7645will end up on the main trunk. When a new release is 7646made by the vendor, you commit it on the vendor branch 7647and copy the modifications onto the main trunk. 7648 7649Use the @code{import} command to create and update 7650the vendor branch. When you import a new file, 7651(usually) the vendor branch is made the `head' revision, so 7652anyone that checks out a copy of the file gets that 7653revision. When a local modification is committed it is 7654placed on the main trunk, and made the `head' 7655revision. 7656 7657@menu 7658* First import:: Importing for the first time 7659* Update imports:: Updating with the import command 7660* Reverting local changes:: Reverting to the latest vendor release 7661* Binary files in imports:: Binary files require special handling 7662* Keywords in imports:: Keyword substitution might be undesirable 7663* Multiple vendor branches:: What if you get sources from several places? 7664@end menu 7665 7666@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7667@node First import 7668@section Importing for the first time 7669@cindex Importing modules 7670 7671@c Should mention naming conventions for vendor tags, 7672@c release tags, and perhaps directory names. 7673Use the @code{import} command to check in the sources 7674for the first time. When you use the @code{import} 7675command to track third-party sources, the @dfn{vendor 7676tag} and @dfn{release tags} are useful. The 7677@dfn{vendor tag} is a symbolic name for the branch 7678(which is always 1.1.1, unless you use the @samp{-b 7679@var{branch}} flag---see @ref{Multiple vendor branches}.). The 7680@dfn{release tags} are symbolic names for a particular 7681release, such as @samp{FSF_0_04}. 7682 7683@c I'm not completely sure this belongs here. But 7684@c we need to say it _somewhere_ reasonably obvious; it 7685@c is a common misconception among people first learning CVS 7686Note that @code{import} does @emph{not} change the 7687directory in which you invoke it. In particular, it 7688does not set up that directory as a @sc{cvs} working 7689directory; if you want to work with the sources import 7690them first and then check them out into a different 7691directory (@pxref{Getting the source}). 7692 7693@cindex wdiff (import example) 7694Suppose you have the sources to a program called 7695@code{wdiff} in a directory @file{wdiff-0.04}, 7696and are going to make private modifications that you 7697want to be able to use even when new releases are made 7698in the future. You start by importing the source to 7699your repository: 7700 7701@example 7702$ cd wdiff-0.04 7703$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 7704@end example 7705 7706The vendor tag is named @samp{FSF_DIST} in the above 7707example, and the only release tag assigned is 7708@samp{WDIFF_0_04}. 7709@c FIXME: Need to say where fsf/wdiff comes from. 7710 7711@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7712@node Update imports 7713@section Updating with the import command 7714 7715When a new release of the source arrives, you import it into the 7716repository with the same @code{import} command that you used to set up 7717the repository in the first place. The only difference is that you 7718specify a different release tag this time: 7719 7720@example 7721$ tar xfz wdiff-0.05.tar.gz 7722$ cd wdiff-0.05 7723$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 7724@end example 7725 7726@strong{WARNING: If you use a release tag that already exists in one of the 7727repository archives, files removed by an import may not be detected.} 7728 7729For files that have not been modified locally, the newly created 7730revision becomes the head revision. If you have made local 7731changes, @code{import} will warn you that you must merge the changes 7732into the main trunk, and tell you to use @samp{checkout -j} to do so: 7733 7734@c FIXME: why "wdiff" here and "fsf/wdiff" in the 7735@c "import"? I think the assumption is that one has 7736@c "wdiff fsf/wdiff" or some such in modules, but it 7737@c would be better to not use modules in this example. 7738@example 7739$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 7740@end example 7741 7742@noindent 7743The above command will check out the latest revision of 7744@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 7745since yesterday into the working copy. If any conflicts arise during 7746the merge they should be resolved in the normal way (@pxref{Conflicts 7747example}). Then, the modified files may be committed. 7748 7749However, it is much better to use the two release tags rather than using 7750a date on the branch as suggested above: 7751 7752@example 7753$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 7754@end example 7755 7756@noindent 7757The reason this is better is that 7758using a date, as suggested above, assumes that you do 7759not import more than one release of a product per day. 7760More importantly, using the release tags allows @sc{cvs} to detect files 7761that were removed between the two vendor releases and mark them for 7762removal. Since @code{import} has no way to detect removed files, you 7763should do a merge like this even if @code{import} doesn't tell you to. 7764 7765@node Reverting local changes 7766@section Reverting to the latest vendor release 7767 7768You can also revert local changes completely and return 7769to the latest vendor release by changing the `head' 7770revision back to the vendor branch on all files. For 7771example, if you have a checked-out copy of the sources 7772in @file{~/work.d/wdiff}, and you want to revert to the 7773vendor's version for all the files in that directory, 7774you would type: 7775 7776@example 7777$ cd ~/work.d/wdiff 7778$ cvs admin -bFSF_DIST . 7779@end example 7780 7781@noindent 7782You must specify the @samp{-bFSF_DIST} without any space 7783after the @samp{-b}. @xref{admin options}. 7784 7785@node Binary files in imports 7786@section How to handle binary files with cvs import 7787 7788Use the @samp{-k} wrapper option to tell import which 7789files are binary. @xref{Wrappers}. 7790 7791@node Keywords in imports 7792@section How to handle keyword substitution with cvs import 7793 7794The sources which you are importing may contain 7795keywords (@pxref{Keyword substitution}). For example, 7796the vendor may use @sc{cvs} or some other system 7797which uses similar keyword expansion syntax. If you 7798just import the files in the default fashion, then 7799the keyword expansions supplied by the vendor will 7800be replaced by keyword expansions supplied by your 7801own copy of @sc{cvs}. It may be more convenient to 7802maintain the expansions supplied by the vendor, so 7803that this information can supply information about 7804the sources that you imported from the vendor. 7805 7806To maintain the keyword expansions supplied by the 7807vendor, supply the @samp{-ko} option to @code{cvs 7808import} the first time you import the file. 7809This will turn off keyword expansion 7810for that file entirely, so if you want to be more 7811selective you'll have to think about what you want 7812and use the @samp{-k} option to @code{cvs update} or 7813@code{cvs admin} as appropriate. 7814@c Supplying -ko to import if the file already existed 7815@c has no effect. Not clear to me whether it should 7816@c or not. 7817 7818@node Multiple vendor branches 7819@section Multiple vendor branches 7820 7821All the examples so far assume that there is only one 7822vendor from which you are getting sources. In some 7823situations you might get sources from a variety of 7824places. For example, suppose that you are dealing with 7825a project where many different people and teams are 7826modifying the software. There are a variety of ways to 7827handle this, but in some cases you have a bunch of 7828source trees lying around and what you want to do more 7829than anything else is just to all put them in @sc{cvs} so 7830that you at least have them in one place. 7831 7832For handling situations in which there may be more than 7833one vendor, you may specify the @samp{-b} option to 7834@code{cvs import}. It takes as an argument the vendor 7835branch to import to. The default is @samp{-b 1.1.1}. 7836 7837For example, suppose that there are two teams, the red 7838team and the blue team, that are sending you sources. 7839You want to import the red team's efforts to branch 78401.1.1 and use the vendor tag RED. You want to import 7841the blue team's efforts to branch 1.1.3 and use the 7842vendor tag BLUE. So the commands you might use are: 7843 7844@example 7845$ cvs import dir RED RED_1-0 7846$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 7847@end example 7848 7849Note that if your vendor tag does not match your 7850@samp{-b} option, @sc{cvs} will not detect this case! For 7851example, 7852 7853@example 7854$ cvs import -b 1.1.3 dir RED RED_1-0 7855@end example 7856 7857@noindent 7858Be careful; this kind of mismatch is sure to sow 7859confusion or worse. I can't think of a useful purpose 7860for the ability to specify a mismatch here, but if you 7861discover such a use, don't. @sc{cvs} is likely to make this 7862an error in some future release. 7863 7864@c Probably should say more about the semantics of 7865@c multiple branches. What about the default branch? 7866@c What about joining (perhaps not as useful with 7867@c multiple branches, or perhaps it is. Either way 7868@c should be mentioned). 7869 7870@c I'm not sure about the best location for this. In 7871@c one sense, it might belong right after we've introduced 7872@c CVS's basic version control model, because people need 7873@c to figure out builds right away. The current location 7874@c is based on the theory that it kind of akin to the 7875@c "Revision management" section. 7876@node Builds 7877@chapter How your build system interacts with CVS 7878@cindex Builds 7879@cindex make 7880 7881As mentioned in the introduction, @sc{cvs} does not 7882contain software for building your software from source 7883code. This section describes how various aspects of 7884your build system might interact with @sc{cvs}. 7885 7886@c Is there a way to discuss this without reference to 7887@c tools other than CVS? I'm not sure there is; I 7888@c wouldn't think that people who learn CVS first would 7889@c even have this concern. 7890One common question, especially from people who are 7891accustomed to @sc{rcs}, is how to make their build get 7892an up to date copy of the sources. The answer to this 7893with @sc{cvs} is two-fold. First of all, since 7894@sc{cvs} itself can recurse through directories, there 7895is no need to modify your @file{Makefile} (or whatever 7896configuration file your build tool uses) to make sure 7897each file is up to date. Instead, just use two 7898commands, first @code{cvs -q update} and then 7899@code{make} or whatever the command is to invoke your 7900build tool. Secondly, you do not necessarily 7901@emph{want} to get a copy of a change someone else made 7902until you have finished your own work. One suggested 7903approach is to first update your sources, then 7904implement, build and 7905test the change you were thinking of, and then commit 7906your sources (updating first if necessary). By 7907periodically (in between changes, using the approach 7908just described) updating your entire tree, you ensure 7909that your sources are sufficiently up to date. 7910 7911@cindex Bill of materials 7912One common need is to record which versions of which 7913source files went into a particular build. This kind 7914of functionality is sometimes called @dfn{bill of 7915materials} or something similar. The best way to do 7916this with @sc{cvs} is to use the @code{tag} command to 7917record which versions went into a given build 7918(@pxref{Tags}). 7919 7920Using @sc{cvs} in the most straightforward manner 7921possible, each developer will have a copy of the entire 7922source tree which is used in a particular build. If 7923the source tree is small, or if developers are 7924geographically dispersed, this is the preferred 7925solution. In fact one approach for larger projects is 7926to break a project down into smaller 7927@c I say subsystem instead of module because they may or 7928@c may not use the modules file. 7929separately-compiled subsystems, and arrange a way of 7930releasing them internally so that each developer need 7931check out only those subsystems which they are 7932actively working on. 7933 7934Another approach is to set up a structure which allows 7935developers to have their own copies of some files, and 7936for other files to access source files from a central 7937location. Many people have come up with some such a 7938@c two such people are paul@sander.cupertino.ca.us (for 7939@c a previous employer) 7940@c and gunnar.tornblom@se.abb.com (spicm and related tools), 7941@c but as far as I know 7942@c no one has nicely packaged or released such a system (or 7943@c instructions for constructing one). 7944system using features such as the symbolic link feature 7945found in many operating systems, or the @code{VPATH} 7946feature found in many versions of @code{make}. One build 7947tool which is designed to help with this kind of thing 7948is Odin (see 7949@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 7950@c Should we be saying more about Odin? Or how you use 7951@c it with CVS? Also, the Prime Time Freeware for Unix 7952@c disk (see http://www.ptf.com/) has Odin (with a nice 7953@c paragraph summarizing it on the web), so that might be a 7954@c semi-"official" place to point people. 7955@c 7956@c Of course, many non-CVS systems have this kind of 7957@c functionality, for example OSF's ODE 7958@c (http://www.osf.org/ode/) or mk 7959@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 7960@c He has changed providers in the past; a search engine search 7961@c for "Peter Ziobrzynski" probably won't get too many 7962@c spurious hits :-). A more stable URL might be 7963@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 7964@c there is any point in mentioning them here unless they 7965@c can work with CVS. 7966 7967@c --------------------------------------------------------------------- 7968@node Special Files 7969@chapter Special Files 7970 7971@cindex Special files 7972@cindex Device nodes 7973@cindex Ownership, saving in CVS 7974@cindex Permissions, saving in CVS 7975@cindex Hard links 7976@cindex Symbolic links 7977 7978In normal circumstances, @sc{cvs} works only with regular 7979files. Every file in a project is assumed to be 7980persistent; it must be possible to open, read and close 7981them; and so on. @sc{cvs} also ignores file permissions and 7982ownerships, leaving such issues to be resolved by the 7983developer at installation time. In other words, it is 7984not possible to "check in" a device into a repository; 7985if the device file cannot be opened, @sc{cvs} will refuse to 7986handle it. Files also lose their ownerships and 7987permissions during repository transactions. 7988 7989@ignore 7990If the configuration variable @code{PreservePermissions} 7991(@pxref{config}) is set in the repository, @sc{cvs} will 7992save the following file characteristics in the 7993repository: 7994 7995@itemize @bullet 7996@item user and group ownership 7997@item permissions 7998@item major and minor device numbers 7999@item symbolic links 8000@item hard link structure 8001@end itemize 8002 8003Using the @code{PreservePermissions} option affects the 8004behavior of @sc{cvs} in several ways. First, some of the 8005new operations supported by @sc{cvs} are not accessible to 8006all users. In particular, file ownership and special 8007file characteristics may only be changed by the 8008superuser. When the @code{PreservePermissions} 8009configuration variable is set, therefore, users will 8010have to be `root' in order to perform @sc{cvs} operations. 8011 8012When @code{PreservePermissions} is in use, some @sc{cvs} 8013operations (such as @samp{cvs status}) will not 8014recognize a file's hard link structure, and so will 8015emit spurious warnings about mismatching hard links. 8016The reason is that @sc{cvs}'s internal structure does not 8017make it easy for these operations to collect all the 8018necessary data about hard links, so they check for file 8019conflicts with inaccurate data. 8020 8021A more subtle difference is that @sc{cvs} considers a file 8022to have changed only if its contents have changed 8023(specifically, if the modification time of the working 8024file does not match that of the repository's file). 8025Therefore, if only the permissions, ownership or hard 8026linkage have changed, or if a device's major or minor 8027numbers have changed, @sc{cvs} will not notice. In order to 8028commit such a change to the repository, you must force 8029the commit with @samp{cvs commit -f}. This also means 8030that if a file's permissions have changed and the 8031repository file is newer than the working copy, 8032performing @samp{cvs update} will silently change the 8033permissions on the working copy. 8034 8035Changing hard links in a @sc{cvs} repository is particularly 8036delicate. Suppose that file @file{foo} is linked to 8037file @file{old}, but is later relinked to file 8038@file{new}. You can wind up in the unusual situation 8039where, although @file{foo}, @file{old} and @file{new} 8040have all had their underlying link patterns changed, 8041only @file{foo} and @file{new} have been modified, so 8042@file{old} is not considered a candidate for checking 8043in. It can be very easy to produce inconsistent 8044results this way. Therefore, we recommend that when it 8045is important to save hard links in a repository, the 8046prudent course of action is to @code{touch} any file 8047whose linkage or status has changed since the last 8048checkin. Indeed, it may be wise to @code{touch *} 8049before each commit in a directory with complex hard 8050link structures. 8051 8052It is worth noting that only regular files may 8053be merged, for reasons that hopefully are obvious. If 8054@samp{cvs update} or @samp{cvs checkout -j} attempts to 8055merge a symbolic link with a regular file, or two 8056device files for different kinds of devices, @sc{cvs} will 8057report a conflict and refuse to perform the merge. At 8058the same time, @samp{cvs diff} will not report any 8059differences between these files, since no meaningful 8060textual comparisons can be made on files which contain 8061no text. 8062 8063The @code{PreservePermissions} features do not work 8064with client/server @sc{cvs}. Another limitation is 8065that hard links must be to other files within the same 8066directory; hard links across directories are not 8067supported. 8068@end ignore 8069 8070@c --------------------------------------------------------------------- 8071@c ----- START MAN 1 ----- 8072@node CVS commands 8073@appendix Guide to CVS commands 8074 8075This appendix describes the overall structure of 8076@sc{cvs} commands, and describes some commands in 8077detail (others are described elsewhere; for a quick 8078reference to @sc{cvs} commands, @pxref{Invoking CVS}). 8079@c The idea is that we want to move the commands which 8080@c are described here into the main body of the manual, 8081@c in the process reorganizing the manual to be 8082@c organized around what the user wants to do, not 8083@c organized around CVS commands. 8084@c 8085@c Note that many users do expect a manual which is 8086@c organized by command. At least some users do. 8087@c One good addition to the "organized by command" 8088@c section (if any) would be "see also" links. 8089@c The awk manual might be a good example; it has a 8090@c reference manual which is more verbose than Invoking 8091@c CVS but probably somewhat less verbose than CVS 8092@c Commands. 8093 8094@menu 8095* Structure:: Overall structure of CVS commands 8096* Exit status:: Indicating CVS's success or failure 8097* ~/.cvsrc:: Default options with the ~/.cvsrc file 8098* Global options:: Options you give to the left of cvs_command 8099* Common options:: Options you give to the right of cvs_command 8100* Date input formats:: Acceptable formats for date specifications 8101* add:: Add files and directories to the repository 8102* admin:: Administration 8103* annotate:: What revision modified each line of a file? 8104* checkout:: Checkout sources for editing 8105* commit:: Check files into the repository 8106* diff:: Show differences between revisions 8107* export:: Export sources from CVS, similar to checkout 8108* history:: Show status of files and users 8109* import:: Import sources into CVS, using vendor branches 8110* init:: Initialize a repository 8111* log:: Show log messages for files 8112* ls & rls:: List files in the repository 8113* rdiff:: 'patch' format diffs between releases 8114* release:: Indicate that a directory is no longer in use 8115* remove:: Remove files from active development 8116* server & pserver:: Act as a server for a client on stdin/stdout 8117* update:: Bring work tree in sync with repository 8118@end menu 8119 8120@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8121@node Structure 8122@appendixsec Overall structure of CVS commands 8123@cindex Structure 8124@cindex CVS command structure 8125@cindex Command structure 8126@cindex Format of CVS commands 8127 8128The overall format of all @sc{cvs} commands is: 8129 8130@example 8131cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 8132@end example 8133 8134@table @code 8135@item cvs 8136The name of the @sc{cvs} program. 8137 8138@item cvs_options 8139Some options that affect all sub-commands of @sc{cvs}. These are 8140described below. 8141 8142@item cvs_command 8143One of several different sub-commands. Some of the commands have 8144aliases that can be used instead; those aliases are noted in the 8145reference manual for that command. There are only two situations 8146where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 8147list of available commands, and @samp{cvs -v} displays version 8148information on @sc{cvs} itself. 8149 8150@item command_options 8151Options that are specific for the command. 8152 8153@item command_args 8154Arguments to the commands. 8155@end table 8156 8157There is unfortunately some confusion between 8158@code{cvs_options} and @code{command_options}. 8159When given as a @code{cvs_option}, some options only 8160affect some of the commands. When given as a 8161@code{command_option} it may have a different meaning, and 8162be accepted by more commands. In other words, do not 8163take the above categorization too seriously. Look at 8164the documentation instead. 8165 8166@node Exit status 8167@appendixsec CVS's exit status 8168@cindex Exit status, of CVS 8169 8170@sc{cvs} can indicate to the calling environment whether it 8171succeeded or failed by setting its @dfn{exit status}. 8172The exact way of testing the exit status will vary from 8173one operating system to another. For example in a unix 8174shell script the @samp{$?} variable will be 0 if the 8175last command returned a successful exit status, or 8176greater than 0 if the exit status indicated failure. 8177 8178If @sc{cvs} is successful, it returns a successful status; 8179if there is an error, it prints an error message and 8180returns a failure status. The one exception to this is 8181the @code{cvs diff} command. It will return a 8182successful status if it found no differences, or a 8183failure status if there were differences or if there 8184was an error. Because this behavior provides no good 8185way to detect errors, in the future it is possible that 8186@code{cvs diff} will be changed to behave like the 8187other @sc{cvs} commands. 8188@c It might seem like checking whether cvs -q diff 8189@c produces empty or non-empty output can tell whether 8190@c there were differences or not. But it seems like 8191@c there are cases with output but no differences 8192@c (testsuite basica-8b). It is not clear to me how 8193@c useful it is for a script to be able to check 8194@c whether there were differences. 8195@c FIXCVS? In previous versions of CVS, cvs diff 8196@c returned 0 for no differences, 1 for differences, or 8197@c 2 for errors. Is this behavior worth trying to 8198@c bring back (but what does it mean for VMS?)? 8199 8200@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8201@node ~/.cvsrc 8202@appendixsec Default options and the ~/.cvsrc file 8203@cindex .cvsrc file 8204@cindex Option defaults 8205 8206There are some @code{command_options} that are used so 8207often that you might have set up an alias or some other 8208means to make sure you always specify that option. One 8209example (the one that drove the implementation of the 8210@file{.cvsrc} support, actually) is that many people find the 8211default output of the @samp{diff} command to be very 8212hard to read, and that either context diffs or unidiffs 8213are much easier to understand. 8214 8215The @file{~/.cvsrc} file is a way that you can add 8216default options to @code{cvs_commands} within cvs, 8217instead of relying on aliases or other shell scripts. 8218 8219The format of the @file{~/.cvsrc} file is simple. The 8220file is searched for a line that begins with the same 8221name as the @code{cvs_command} being executed. If a 8222match is found, then the remainder of the line is split 8223up (at whitespace characters) into separate options and 8224added to the command arguments @emph{before} any 8225options from the command line. 8226 8227If a command has two names (e.g., @code{checkout} and 8228@code{co}), the official name, not necessarily the one 8229used on the command line, will be used to match against 8230the file. So if this is the contents of the user's 8231@file{~/.cvsrc} file: 8232 8233@example 8234log -N 8235diff -uN 8236rdiff -u 8237update -Pd 8238checkout -P 8239release -d 8240@end example 8241 8242@noindent 8243the command @samp{cvs checkout foo} would have the 8244@samp{-P} option added to the arguments, as well as 8245@samp{cvs co foo}. 8246 8247With the example file above, the output from @samp{cvs 8248diff foobar} will be in unidiff format. @samp{cvs diff 8249-c foobar} will provide context diffs, as usual. 8250Getting "old" format diffs would be slightly more 8251complicated, because @code{diff} doesn't have an option 8252to specify use of the "old" format, so you would need 8253@samp{cvs -f diff foobar}. 8254 8255In place of the command name you can use @code{cvs} to 8256specify global options (@pxref{Global options}). For 8257example the following line in @file{.cvsrc} 8258 8259@example 8260cvs -z6 8261@end example 8262 8263@noindent 8264causes @sc{cvs} to use compression level 6. 8265 8266@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8267@node Global options 8268@appendixsec Global options 8269@cindex Options, global 8270@cindex Global options 8271@cindex Left-hand options 8272 8273The available @samp{cvs_options} (that are given to the 8274left of @samp{cvs_command}) are: 8275 8276@table @code 8277@item --allow-root=@var{rootdir} 8278May be invoked multiple times to specify one legal @sc{cvsroot} directory with 8279each invocation. Also causes CVS to preparse the configuration file for each 8280specified root, which can be useful when configuring write proxies, See 8281@ref{Password authentication server} & @ref{Write proxies}. 8282 8283@cindex Authentication, stream 8284@cindex Stream authentication 8285@item -a 8286Authenticate all communication between the client and 8287the server. Only has an effect on the @sc{cvs} client. 8288As of this writing, this is only implemented when using 8289a GSSAPI connection (@pxref{GSSAPI authenticated}). 8290Authentication prevents certain sorts of attacks 8291involving hijacking the active @sc{tcp} connection. 8292Enabling authentication does not enable encryption. 8293 8294@cindex RCSBIN, overriding 8295@cindex Overriding RCSBIN 8296@item -b @var{bindir} 8297In @sc{cvs} 1.9.18 and older, this specified that 8298@sc{rcs} programs are in the @var{bindir} directory. 8299Current versions of @sc{cvs} do not run @sc{rcs} 8300programs; for compatibility this option is accepted, 8301but it does nothing. 8302 8303@cindex TMPDIR, environment variable 8304@cindex temporary file directory, set via command line 8305@cindex temporary file directory, set via environment variable 8306@cindex temporary file directory, set via config 8307@cindex temporary files, location of 8308@item -T @var{tempdir} 8309Use @var{tempdir} as the directory where temporary files are 8310located. 8311 8312The @sc{cvs} client and server store temporary files in a temporary directory. 8313The path to this temporary directory is set via, in order of precedence: 8314 8315@itemize @bullet 8316@item 8317The argument to the global @samp{-T} option. 8318 8319@item 8320The value set for @code{TmpDir} in the config file (server only - 8321@pxref{config}). 8322 8323@item 8324The contents of the @code{$TMPDIR} environment variable (@code{%TMPDIR%} on 8325Windows - @pxref{Environment variables}). 8326 8327@item 8328/tmp 8329 8330@end itemize 8331 8332Temporary directories should always be specified as an absolute pathname. 8333When running a CVS client, @samp{-T} affects only the local process; 8334specifying @samp{-T} for the client has no effect on the server and 8335vice versa. 8336 8337@cindex CVSROOT, overriding 8338@cindex Overriding CVSROOT 8339@item -d @var{cvs_root_directory} 8340Use @var{cvs_root_directory} as the root directory 8341pathname of the repository. Overrides the setting of 8342the @code{$CVSROOT} environment variable. @xref{Repository}. 8343 8344@cindex EDITOR, overriding 8345@cindex Overriding EDITOR 8346@item -e @var{editor} 8347Use @var{editor} to enter revision log information. Overrides the 8348setting of the @code{$CVSEDITOR} and @code{$EDITOR} 8349environment variables. For more information, see 8350@ref{Committing your changes}. 8351 8352@item -f 8353Do not read the @file{~/.cvsrc} file. This 8354option is most often used because of the 8355non-orthogonality of the @sc{cvs} option set. For 8356example, the @samp{cvs log} option @samp{-N} (turn off 8357display of tag names) does not have a corresponding 8358option to turn the display on. So if you have 8359@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 8360you may need to use @samp{-f} to show the tag names. 8361 8362@item -H 8363@itemx --help 8364Display usage information about the specified @samp{cvs_command} 8365(but do not actually execute the command). If you don't specify 8366a command name, @samp{cvs -H} displays overall help for 8367@sc{cvs}, including a list of other help options. 8368@c It seems to me it is better to document it this way 8369@c rather than trying to update this documentation 8370@c every time that we add a --help-foo option. But 8371@c perhaps that is confusing... 8372 8373@cindex Read-only repository mode 8374@item -R 8375Turns on read-only repository mode. This allows one to check out from a 8376read-only repository, such as within an anoncvs server, or from a @sc{cd-rom} 8377repository. 8378 8379Same effect as if the @code{CVSREADONLYFS} environment 8380variable is set. Using @samp{-R} can also considerably 8381speed up checkouts over NFS. 8382 8383@cindex Read-only mode 8384@item -n 8385Do not change any files. Attempt to execute the 8386@samp{cvs_command}, but only to issue reports; do not remove, 8387update, or merge any existing files, or create any new files. 8388 8389Note that @sc{cvs} will not necessarily produce exactly 8390the same output as without @samp{-n}. In some cases 8391the output will be the same, but in other cases 8392@sc{cvs} will skip some of the processing that would 8393have been required to produce the exact same output. 8394 8395@item -Q 8396Cause the command to be really quiet; the command will only 8397generate output for serious problems. 8398 8399@item -q 8400Cause the command to be somewhat quiet; informational messages, 8401such as reports of recursion through subdirectories, are 8402suppressed. 8403 8404@cindex Read-only files, and -r 8405@item -r 8406Make new working files read-only. Same effect 8407as if the @code{$CVSREAD} environment variable is set 8408(@pxref{Environment variables}). The default is to 8409make working files writable, unless watches are on 8410(@pxref{Watches}). 8411 8412@item -s @var{variable}=@var{value} 8413Set a user variable (@pxref{Variables}). 8414 8415@cindex Trace 8416@item -t 8417Trace program execution; display messages showing the steps of 8418@sc{cvs} activity. Particularly useful with @samp{-n} to explore the 8419potential impact of an unfamiliar command. 8420 8421@item -v 8422@item --version 8423Display version and copyright information for @sc{cvs}. 8424 8425@cindex CVSREAD, overriding 8426@cindex Overriding CVSREAD 8427@item -w 8428Make new working files read-write. Overrides the 8429setting of the @code{$CVSREAD} environment variable. 8430Files are created read-write by default, unless @code{$CVSREAD} is 8431set or @samp{-r} is given. 8432@c Note that -w only overrides -r and CVSREAD; it has 8433@c no effect on files which are readonly because of 8434@c "cvs watch on". My guess is that is the way it 8435@c should be (or should "cvs -w get" on a watched file 8436@c be the same as a get and a cvs edit?), but I'm not 8437@c completely sure whether to document it this way. 8438 8439@item -x 8440@cindex Encryption 8441Encrypt all communication between the client and the 8442server. Only has an effect on the @sc{cvs} client. As 8443of this writing, this is only implemented when using a 8444GSSAPI connection (@pxref{GSSAPI authenticated}) or a 8445Kerberos connection (@pxref{Kerberos authenticated}). 8446Enabling encryption implies that message traffic is 8447also authenticated. Encryption support is not 8448available by default; it must be enabled using a 8449special configure option, @file{--enable-encryption}, 8450when you build @sc{cvs}. 8451 8452@item -z @var{level} 8453@cindex Compression 8454@cindex Gzip 8455Request compression @var{level} for network traffic. 8456@sc{cvs} interprets @var{level} identically to the @code{gzip} program. 8457Valid levels are 1 (high speed, low compression) to 84589 (low speed, high compression), or 0 to disable 8459compression (the default). Data sent to the server will 8460be compressed at the requested level and the client will request 8461the server use the same compression level for data returned. The 8462server will use the closest level allowed by the server administrator to 8463compress returned data. This option only has an effect when passed to 8464the @sc{cvs} client. 8465@end table 8466 8467@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8468@node Common options 8469@appendixsec Common command options 8470@cindex Common options 8471@cindex Right-hand options 8472 8473This section describes the @samp{command_options} that 8474are available across several @sc{cvs} commands. These 8475options are always given to the right of 8476@samp{cvs_command}. Not all 8477commands support all of these options; each option is 8478only supported for commands where it makes sense. 8479However, when a command has one of these options you 8480can almost always count on the same behavior of the 8481option as in other commands. (Other command options, 8482which are listed with the individual commands, may have 8483different behavior from one @sc{cvs} command to the other). 8484 8485@strong{Note: the @samp{history} command is an exception; it supports 8486many options that conflict even with these standard options.} 8487 8488@table @code 8489@cindex Dates 8490@cindex Time 8491@cindex Specifying dates 8492@item -D @var{date_spec} 8493Use the most recent revision no later than @var{date_spec}. 8494@var{date_spec} is a single argument, a date description 8495specifying a date in the past. 8496 8497The specification is @dfn{sticky} when you use it to make a 8498private copy of a source file; that is, when you get a working 8499file using @samp{-D}, @sc{cvs} records the date you specified, so that 8500further updates in the same directory will use the same date 8501(for more information on sticky tags/dates, @pxref{Sticky tags}). 8502 8503@samp{-D} is available with the @code{annotate}, @code{checkout}, 8504@code{diff}, @code{export}, @code{history}, @code{ls}, 8505@code{rdiff}, @code{rls}, @code{rtag}, @code{tag}, and @code{update} commands. 8506(The @code{history} command uses this option in a 8507slightly different way; @pxref{history options}). 8508 8509For a complete description of the date formats accepted by @sc{cvs}, 8510@ref{Date input formats}. 8511@c What other formats should we accept? I don't want 8512@c to start accepting a whole mess of non-standard 8513@c new formats (there are a lot which are in wide use in 8514@c one context or another), but practicality does 8515@c dictate some level of flexibility. 8516@c * POSIX.2 (e.g. touch, ls output, date) and other 8517@c POSIX and/or de facto unix standards (e.g. at). The 8518@c practice here is too inconsistent to be of any use. 8519@c * VMS dates. This is not a formal standard, but 8520@c there is a published specification (see SYS$ASCTIM 8521@c and SYS$BINTIM in the _VMS System Services Reference 8522@c Manual_), it is implemented consistently in VMS 8523@c utilities, and VMS users will expect CVS running on 8524@c VMS to support this format (and if we're going to do 8525@c that, better to make CVS support it on all 8526@c platforms. Maybe). 8527@c 8528@c One more note: In output, CVS should consistently 8529@c use one date format, and that format should be one that 8530@c it accepts in input as well. The former isn't 8531@c really true (see survey below), and I'm not 8532@c sure that either of those formats is accepted in 8533@c input. 8534@c 8535@c cvs log 8536@c current 1996/01/02 13:45:31 8537@c Internet 02 Jan 1996 13:45:31 UT 8538@c ISO 1996-01-02 13:45:31 8539@c cvs ann 8540@c current 02-Jan-96 8541@c Internet-like 02 Jan 96 8542@c ISO 96-01-02 8543@c cvs status 8544@c current Tue Jun 11 02:54:53 1996 8545@c Internet [Tue,] 11 Jun 1996 02:54:53 8546@c ISO 1996-06-11 02:54:53 8547@c note: date possibly should be omitted entirely for 8548@c other reasons. 8549@c cvs editors 8550@c current Tue Jun 11 02:54:53 1996 GMT 8551@c cvs history 8552@c current 06/11 02:54 +0000 8553@c any others? 8554@c There is a good chance the proper solution has to 8555@c involve at least some level of letting the user 8556@c decide which format (with the default being the 8557@c formats CVS has always used; changing these might be 8558@c _very_ disruptive since scripts may very well be 8559@c parsing them). 8560@c 8561@c Another random bit of prior art concerning dates is 8562@c the strptime function which takes templates such as 8563@c "%m/%d/%y", and apparent a variant of getdate() 8564@c which also honors them. See 8565@c X/Open CAE Specification, System Interfaces and 8566@c Headers Issue 4, Version 2 (September 1994), in the 8567@c entry for getdate() on page 231 8568 8569Remember to quote the argument to the @samp{-D} 8570flag so that your shell doesn't interpret spaces as 8571argument separators. A command using the @samp{-D} 8572flag can look like this: 8573 8574@example 8575$ cvs diff -D "1 hour ago" cvs.texinfo 8576@end example 8577 8578@cindex Forcing a tag match 8579@item -f 8580When you specify a particular date or tag to @sc{cvs} commands, they 8581normally ignore files that do not contain the tag (or did not 8582exist prior to the date) that you specified. Use the @samp{-f} option 8583if you want files retrieved even when there is no match for the 8584tag or date. (The most recent revision of the file 8585will be used). 8586 8587Note that even with @samp{-f}, a tag that you specify 8588must exist (that is, in some file, not necessary in 8589every file). This is so that @sc{cvs} will continue to 8590give an error if you mistype a tag name. 8591 8592@need 800 8593@samp{-f} is available with these commands: 8594@code{annotate}, @code{checkout}, @code{export}, 8595@code{rdiff}, @code{rtag}, and @code{update}. 8596 8597@strong{WARNING: The @code{commit} and @code{remove} 8598commands also have a 8599@samp{-f} option, but it has a different behavior for 8600those commands. See @ref{commit options}, and 8601@ref{Removing files}.} 8602 8603@item -k @var{kflag} 8604Override the default processing of RCS keywords other than 8605@samp{-kb}. @xref{Keyword substitution}, for the meaning of 8606@var{kflag}. Used with the @code{checkout} and @code{update} 8607commands, your @var{kflag} specification is 8608@dfn{sticky}; that is, when you use this option 8609with a @code{checkout} or @code{update} command, 8610@sc{cvs} associates your selected @var{kflag} with any files 8611it operates on, and continues to use that @var{kflag} with future 8612commands on the same files until you specify otherwise. 8613 8614The @samp{-k} option is available with the @code{add}, 8615@code{checkout}, @code{diff}, @code{export}, @code{import}, 8616@code{rdiff}, and @code{update} commands. 8617 8618@strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag 8619overrode the @samp{-kb} indication for a binary file. This could 8620sometimes corrupt binary files. @xref{Merging and keywords}, for 8621more.} 8622 8623@item -l 8624Local; run only in current working directory, rather than 8625recursing through subdirectories. 8626 8627Available with the following commands: @code{annotate}, @code{checkout}, 8628@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8629@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, 8630@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8631and @code{watchers}. 8632 8633@cindex Editor, avoiding invocation of 8634@cindex Avoiding editor invocation 8635@item -m @var{message} 8636Use @var{message} as log information, instead of 8637invoking an editor. 8638 8639Available with the following commands: @code{add}, 8640@code{commit} and @code{import}. 8641 8642@item -n 8643Do not run any tag program. (A program can be 8644specified to run in the modules 8645database (@pxref{modules}); this option bypasses it). 8646 8647@strong{Note: this is not the same as the @samp{cvs -n} 8648program option, which you can specify to the left of a cvs command!} 8649 8650Available with the @code{checkout}, @code{commit}, @code{export}, 8651and @code{rtag} commands. 8652 8653@item -P 8654Prune empty directories. See @ref{Removing directories}. 8655 8656@item -p 8657Pipe the files retrieved from the repository to standard output, 8658rather than writing them in the current directory. Available 8659with the @code{checkout} and @code{update} commands. 8660 8661@item -R 8662Process directories recursively. This is the default for all @sc{cvs} 8663commands, with the exception of @code{ls} & @code{rls}. 8664 8665Available with the following commands: @code{annotate}, @code{checkout}, 8666@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8667@code{ls}, @code{rdiff}, @code{remove}, @code{rls}, @code{rtag}, 8668@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8669and @code{watchers}. 8670 8671@item -r @var{tag} 8672@item -r @var{tag}[:@var{date}] 8673@cindex HEAD, special tag 8674@cindex BASE, special tag 8675Use the revision specified by the @var{tag} argument (and the @var{date} 8676argument for the commands which accept it) instead of the 8677default @dfn{head} revision. As well as arbitrary tags defined 8678with the @code{tag} or @code{rtag} command, two special tags are 8679always available: @samp{HEAD} refers to the most recent version 8680available in the repository, and @samp{BASE} refers to the 8681revision you last checked out into the current working directory. 8682 8683@c FIXME: What does HEAD really mean? I believe that 8684@c the current answer is the head of the default branch 8685@c for all cvs commands except diff. For diff, it 8686@c seems to be (a) the head of the trunk (or the default 8687@c branch?) if there is no sticky tag, (b) the head of the 8688@c branch for the sticky tag, if there is a sticky tag. 8689@c (b) is ugly as it differs 8690@c from what HEAD means for other commands, but people 8691@c and/or scripts are quite possibly used to it. 8692@c See "head" tests in sanity.sh. 8693@c Probably the best fix is to introduce two new 8694@c special tags, ".thead" for the head of the trunk, 8695@c and ".bhead" for the head of the current branch. 8696@c Then deprecate HEAD. This has the advantage of 8697@c not surprising people with a change to HEAD, and a 8698@c side benefit of also phasing out the poorly-named 8699@c HEAD (see discussion of reserved tag names in node 8700@c "Tags"). Of course, .thead and .bhead should be 8701@c carefully implemented (with the implementation the 8702@c same for "diff" as for everyone else), test cases 8703@c written (similar to the ones in "head"), new tests 8704@c cases written for things like default branches, &c. 8705 8706The tag specification is sticky when you use this 8707with @code{checkout} or @code{update} to make your own 8708copy of a file: @sc{cvs} remembers the tag and continues to use it on 8709future update commands, until you specify otherwise (for more information 8710on sticky tags/dates, @pxref{Sticky tags}). 8711 8712The tag can be either a symbolic or numeric tag, as 8713described in @ref{Tags}, or the name of a branch, as 8714described in @ref{Branching and merging}. 8715When @var{tag} is the name of a 8716branch, some commands accept the optional @var{date} argument to specify 8717the revision as of the given date on the branch. 8718When a command expects a specific revision, 8719the name of a branch is interpreted as the most recent 8720revision on that branch. 8721 8722Specifying the @samp{-q} global option along with the 8723@samp{-r} command option is often useful, to suppress 8724the warning messages when the @sc{rcs} file 8725does not contain the specified tag. 8726 8727@strong{Note: this is not the same as the overall @samp{cvs -r} option, 8728which you can specify to the left of a @sc{cvs} command!} 8729 8730@samp{-r @var{tag}} is available with the @code{commit} and @code{history} 8731commands. 8732 8733@samp{-r @var{tag}[:@var{date}]} is available with the @code{annotate}, 8734@code{checkout}, @code{diff}, @code{export}, @code{rdiff}, @code{rtag}, 8735and @code{update} commands. 8736 8737@item -W 8738Specify file names that should be filtered. You can 8739use this option repeatedly. The spec can be a file 8740name pattern of the same type that you can specify in 8741the @file{.cvswrappers} file. 8742Available with the following commands: @code{import}, 8743and @code{update}. 8744 8745@end table 8746 8747@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8748@include getdate-cvs.texi 8749 8750@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8751@node add 8752@appendixsec add---Add files and directories to the repository 8753@cindex add (subcommand) 8754 8755@itemize @bullet 8756@item 8757Synopsis: add [-k rcs-kflag] [-m message] files... 8758@item 8759Requires: repository, working directory. 8760@item 8761Changes: repository, working directory. 8762@end itemize 8763 8764The @code{add} command is used to present new files 8765and directories for addition into the @sc{cvs} 8766repository. When @code{add} is used on a directory, 8767a new directory is created in the repository 8768immediately. When used on a file, only the working 8769directory is updated. Changes to the repository are 8770not made until the @code{commit} command is used on 8771the newly added file. 8772 8773The @code{add} command also resurrects files that 8774have been previously removed. This can be done 8775before or after the @code{commit} command is used 8776to finalize the removal of files. Resurrected files 8777are restored into the working directory at the time 8778the @code{add} command is executed. 8779 8780@menu 8781* add options:: add options 8782* add examples:: add examples 8783@end menu 8784 8785@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8786@node add options 8787@appendixsubsec add options 8788 8789These standard options are supported by @code{add} 8790(@pxref{Common options}, for a complete description of 8791them): 8792 8793@table @code 8794@item -k @var{kflag} 8795Process keywords according to @var{kflag}. See 8796@ref{Keyword substitution}. 8797This option is sticky; future updates of 8798this file in this working directory will use the same 8799@var{kflag}. The @code{status} command can be viewed 8800to see the sticky options. For more information on 8801the @code{status} command, @xref{Invoking CVS}. 8802 8803@item -m @var{message} 8804Use @var{message} as the log message, instead of 8805invoking an editor. 8806@end table 8807 8808@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8809@node add examples 8810@appendixsubsec add examples 8811 8812@appendixsubsubsec Adding a directory 8813 8814@example 8815$ mkdir doc 8816$ cvs add doc 8817Directory /path/to/repository/doc added to the repository 8818@end example 8819 8820@appendixsubsubsec Adding a file 8821 8822@example 8823 8824$ >TODO 8825$ cvs add TODO 8826cvs add: scheduling file `TODO' for addition 8827cvs add: use 'cvs commit' to add this file permanently 8828@end example 8829 8830@appendixsubsubsec Undoing a @code{remove} command 8831 8832@example 8833$ rm -f makefile 8834$ cvs remove makefile 8835cvs remove: scheduling `makefile' for removal 8836cvs remove: use 'cvs commit' to remove this file permanently 8837$ cvs add makefile 8838U makefile 8839cvs add: makefile, version 1.2, resurrected 8840@end example 8841 8842@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8843@node admin 8844@appendixsec admin---Administration 8845@cindex Admin (subcommand) 8846 8847@itemize @bullet 8848@item 8849Requires: repository, working directory. 8850@item 8851Changes: repository. 8852@item 8853Synonym: rcs 8854@end itemize 8855 8856This is the @sc{cvs} interface to assorted 8857administrative facilities. Some of them have 8858questionable usefulness for @sc{cvs} but exist for 8859historical purposes. Some of the questionable options 8860are likely to disappear in the future. This command 8861@emph{does} work recursively, so extreme care should be 8862used. 8863 8864@cindex cvsadmin 8865@cindex UserAdminOptions, in CVSROOT/config 8866On unix, if there is a group named @code{cvsadmin}, 8867only members of that group can run @code{cvs admin} 8868commands, except for those specified using the 8869@code{UserAdminOptions} configuration option in the 8870@file{CVSROOT/config} file. Options specified using 8871@code{UserAdminOptions} can be run by any user. See 8872@ref{config} for more on @code{UserAdminOptions}. 8873 8874The @code{cvsadmin} group should exist on the server, 8875or any system running the non-client/server @sc{cvs}. 8876To disallow @code{cvs admin} for all users, create a 8877group with no users in it. On NT, the @code{cvsadmin} 8878feature does not exist and all users 8879can run @code{cvs admin}. 8880 8881@menu 8882* admin options:: admin options 8883@end menu 8884 8885@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8886@node admin options 8887@appendixsubsec admin options 8888 8889Some of these options have questionable usefulness for 8890@sc{cvs} but exist for historical purposes. Some even 8891make it impossible to use @sc{cvs} until you undo the 8892effect! 8893 8894@table @code 8895@item -A@var{oldfile} 8896Might not work together with @sc{cvs}. Append the 8897access list of @var{oldfile} to the access list of the 8898@sc{rcs} file. 8899 8900@item -a@var{logins} 8901Might not work together with @sc{cvs}. Append the 8902login names appearing in the comma-separated list 8903@var{logins} to the access list of the @sc{rcs} file. 8904 8905@item -b[@var{rev}] 8906Set the default branch to @var{rev}. In @sc{cvs}, you 8907normally do not manipulate default branches; sticky 8908tags (@pxref{Sticky tags}) are a better way to decide 8909which branch you want to work on. There is one reason 8910to run @code{cvs admin -b}: to revert to the vendor's 8911version when using vendor branches (@pxref{Reverting 8912local changes}). 8913There can be no space between @samp{-b} and its argument. 8914@c Hmm, we don't document the usage where rev is 8915@c omitted. Maybe that usage can/should be deprecated 8916@c (and replaced with -bHEAD or something?) (so we can toss 8917@c the optional argument). Note that -bHEAD does not 8918@c work, as of 17 Sep 1997, but probably will once "cvs 8919@c admin" is internal to CVS. 8920 8921@cindex Comment leader 8922@item -c@var{string} 8923Sets the comment leader to @var{string}. The comment 8924leader is not used by current versions of @sc{cvs} or 8925@sc{rcs} 5.7. Therefore, you can almost surely not 8926worry about it. @xref{Keyword substitution}. 8927 8928@item -e[@var{logins}] 8929Might not work together with @sc{cvs}. Erase the login 8930names appearing in the comma-separated list 8931@var{logins} from the access list of the RCS file. If 8932@var{logins} is omitted, erase the entire access list. 8933There can be no space between @samp{-e} and its argument. 8934 8935@item -I 8936Run interactively, even if the standard input is not a 8937terminal. This option does not work with the 8938client/server @sc{cvs} and is likely to disappear in 8939a future release of @sc{cvs}. 8940 8941@item -i 8942Useless with @sc{cvs}. This creates and initializes a 8943new @sc{rcs} file, without depositing a revision. With 8944@sc{cvs}, add files with the @code{cvs add} command 8945(@pxref{Adding files}). 8946 8947@item -k@var{subst} 8948Set the default keyword 8949substitution to @var{subst}. @xref{Keyword 8950substitution}. Giving an explicit @samp{-k} option to 8951@code{cvs update}, @code{cvs export}, or @code{cvs 8952checkout} overrides this default. 8953 8954@item -l[@var{rev}] 8955Lock the revision with number @var{rev}. If a branch 8956is given, lock the latest revision on that branch. If 8957@var{rev} is omitted, lock the latest revision on the 8958default branch. There can be no space between 8959@samp{-l} and its argument. 8960 8961This can be used in conjunction with the 8962@file{rcslock.pl} script in the @file{contrib} 8963directory of the @sc{cvs} source distribution to 8964provide reserved checkouts (where only one user can be 8965editing a given file at a time). See the comments in 8966that file for details (and see the @file{README} file 8967in that directory for disclaimers about the unsupported 8968nature of contrib). According to comments in that 8969file, locking must set to strict (which is the default). 8970 8971@item -L 8972Set locking to strict. Strict locking means that the 8973owner of an RCS file is not exempt from locking for 8974checkin. For use with @sc{cvs}, strict locking must be 8975set; see the discussion under the @samp{-l} option above. 8976 8977@cindex Changing a log message 8978@cindex Replacing a log message 8979@cindex Correcting a log message 8980@cindex Fixing a log message 8981@cindex Log message, correcting 8982@item -m@var{rev}:@var{msg} 8983Replace the log message of revision @var{rev} with 8984@var{msg}. 8985 8986@c The rcs -M option, to suppress sending mail, has never been 8987@c documented as a cvs admin option. 8988 8989@item -N@var{name}[:[@var{rev}]] 8990Act like @samp{-n}, except override any previous 8991assignment of @var{name}. For use with magic branches, 8992see @ref{Magic branch numbers}. 8993 8994@item -n@var{name}[:[@var{rev}]] 8995Associate the symbolic name @var{name} with the branch 8996or revision @var{rev}. It is normally better to use 8997@samp{cvs tag} or @samp{cvs rtag} instead. Delete the 8998symbolic name if both @samp{:} and @var{rev} are 8999omitted; otherwise, print an error message if 9000@var{name} is already associated with another number. 9001If @var{rev} is symbolic, it is expanded before 9002association. A @var{rev} consisting of a branch number 9003followed by a @samp{.} stands for the current latest 9004revision in the branch. A @samp{:} with an empty 9005@var{rev} stands for the current latest revision on the 9006default branch, normally the trunk. For example, 9007@samp{cvs admin -n@var{name}:} associates @var{name} with the 9008current latest revision of all the RCS files; 9009this contrasts with @samp{cvs admin -n@var{name}:$} which 9010associates @var{name} with the revision numbers 9011extracted from keyword strings in the corresponding 9012working files. 9013 9014@cindex Deleting revisions 9015@cindex Outdating revisions 9016@cindex Saving space 9017@item -o@var{range} 9018Deletes (@dfn{outdates}) the revisions given by 9019@var{range}. 9020 9021Note that this command can be quite dangerous unless 9022you know @emph{exactly} what you are doing (for example 9023see the warnings below about how the 9024@var{rev1}:@var{rev2} syntax is confusing). 9025 9026If you are short on disc this option might help you. 9027But think twice before using it---there is no way short 9028of restoring the latest backup to undo this command! 9029If you delete different revisions than you planned, 9030either due to carelessness or (heaven forbid) a @sc{cvs} 9031bug, there is no opportunity to correct the error 9032before the revisions are deleted. It probably would be 9033a good idea to experiment on a copy of the repository 9034first. 9035 9036Specify @var{range} in one of the following ways: 9037 9038@table @code 9039@item @var{rev1}::@var{rev2} 9040Collapse all revisions between rev1 and rev2, so that 9041@sc{cvs} only stores the differences associated with going 9042from rev1 to rev2, not intermediate steps. For 9043example, after @samp{-o 1.3::1.5} one can retrieve 9044revision 1.3, revision 1.5, or the differences to get 9045from 1.3 to 1.5, but not the revision 1.4, or the 9046differences between 1.3 and 1.4. Other examples: 9047@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 9048effect, because there are no intermediate revisions to 9049remove. 9050 9051@item ::@var{rev} 9052Collapse revisions between the beginning of the branch 9053containing @var{rev} and @var{rev} itself. The 9054branchpoint and @var{rev} are left intact. For 9055example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 9056revision 1.3.2.5, and everything in between, but leaves 90571.3 and 1.3.2.6 intact. 9058 9059@item @var{rev}:: 9060Collapse revisions between @var{rev} and the end of the 9061branch containing @var{rev}. Revision @var{rev} is 9062left intact but the head revision is deleted. 9063 9064@item @var{rev} 9065Delete the revision @var{rev}. For example, @samp{-o 90661.3} is equivalent to @samp{-o 1.2::1.4}. 9067 9068@item @var{rev1}:@var{rev2} 9069Delete the revisions from @var{rev1} to @var{rev2}, 9070inclusive, on the same branch. One will not be able to 9071retrieve @var{rev1} or @var{rev2} or any of the 9072revisions in between. For example, the command 9073@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 9074It means to delete revisions up to, and including, the 9075tag R_1_02. But beware! If there are files that have not 9076changed between R_1_02 and R_1_03 the file will have 9077@emph{the same} numerical revision number assigned to 9078the tags R_1_02 and R_1_03. So not only will it be 9079impossible to retrieve R_1_02; R_1_03 will also have to 9080be restored from the tapes! In most cases you want to 9081specify @var{rev1}::@var{rev2} instead. 9082 9083@item :@var{rev} 9084Delete revisions from the beginning of the 9085branch containing @var{rev} up to and including 9086@var{rev}. 9087 9088@item @var{rev}: 9089Delete revisions from revision @var{rev}, including 9090@var{rev} itself, to the end of the branch containing 9091@var{rev}. 9092@end table 9093 9094None of the revisions to be deleted may have 9095branches or locks. 9096 9097If any of the revisions to be deleted have symbolic 9098names, and one specifies one of the @samp{::} syntaxes, 9099then @sc{cvs} will give an error and not delete any 9100revisions. If you really want to delete both the 9101symbolic names and the revisions, first delete the 9102symbolic names with @code{cvs tag -d}, then run 9103@code{cvs admin -o}. If one specifies the 9104non-@samp{::} syntaxes, then @sc{cvs} will delete the 9105revisions but leave the symbolic names pointing to 9106nonexistent revisions. This behavior is preserved for 9107compatibility with previous versions of @sc{cvs}, but 9108because it isn't very useful, in the future it may 9109change to be like the @samp{::} case. 9110 9111Due to the way @sc{cvs} handles branches @var{rev} 9112cannot be specified symbolically if it is a branch. 9113@xref{Magic branch numbers}, for an explanation. 9114@c FIXME: is this still true? I suspect not. 9115 9116Make sure that no-one has checked out a copy of the 9117revision you outdate. Strange things will happen if he 9118starts to edit it and tries to check it back in. For 9119this reason, this option is not a good way to take back 9120a bogus commit; commit a new revision undoing the bogus 9121change instead (@pxref{Merging two revisions}). 9122 9123@item -q 9124Run quietly; do not print diagnostics. 9125 9126@item -s@var{state}[:@var{rev}] 9127Useful with @sc{cvs}. Set the state attribute of the 9128revision @var{rev} to @var{state}. If @var{rev} is a 9129branch number, assume the latest revision on that 9130branch. If @var{rev} is omitted, assume the latest 9131revision on the default branch. Any identifier is 9132acceptable for @var{state}. A useful set of states is 9133@samp{Exp} (for experimental), @samp{Stab} (for 9134stable), and @samp{Rel} (for released). By default, 9135the state of a new revision is set to @samp{Exp} when 9136it is created. The state is visible in the output from 9137@var{cvs log} (@pxref{log}), and in the 9138@samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords 9139(@pxref{Keyword substitution}). Note that @sc{cvs} 9140uses the @code{dead} state for its own purposes (@pxref{Attic}); to 9141take a file to or from the @code{dead} state use 9142commands like @code{cvs remove} and @code{cvs add} 9143(@pxref{Adding and removing}), not @code{cvs admin -s}. 9144 9145@item -t[@var{file}] 9146Useful with @sc{cvs}. Write descriptive text from the 9147contents of the named @var{file} into the RCS file, 9148deleting the existing text. The @var{file} pathname 9149may not begin with @samp{-}. The descriptive text can be seen in the 9150output from @samp{cvs log} (@pxref{log}). 9151There can be no space between @samp{-t} and its argument. 9152 9153If @var{file} is omitted, 9154obtain the text from standard input, terminated by 9155end-of-file or by a line containing @samp{.} by itself. 9156Prompt for the text if interaction is possible; see 9157@samp{-I}. 9158 9159@item -t-@var{string} 9160Similar to @samp{-t@var{file}}. Write descriptive text 9161from the @var{string} into the @sc{rcs} file, deleting 9162the existing text. 9163There can be no space between @samp{-t} and its argument. 9164 9165@c The rcs -T option, do not update last-mod time for 9166@c minor changes, has never been documented as a 9167@c cvs admin option. 9168 9169@item -U 9170Set locking to non-strict. Non-strict locking means 9171that the owner of a file need not lock a revision for 9172checkin. For use with @sc{cvs}, strict locking must be 9173set; see the discussion under the @samp{-l} option 9174above. 9175 9176@item -u[@var{rev}] 9177See the option @samp{-l} above, for a discussion of 9178using this option with @sc{cvs}. Unlock the revision 9179with number @var{rev}. If a branch is given, unlock 9180the latest revision on that branch. If @var{rev} is 9181omitted, remove the latest lock held by the caller. 9182Normally, only the locker of a revision may unlock it; 9183somebody else unlocking a revision breaks the lock. 9184This causes the original locker to be sent a @code{commit} 9185notification (@pxref{Getting Notified}). 9186There can be no space between @samp{-u} and its argument. 9187 9188@item -V@var{n} 9189In previous versions of @sc{cvs}, this option meant to 9190write an @sc{rcs} file which would be acceptable to 9191@sc{rcs} version @var{n}, but it is now obsolete and 9192specifying it will produce an error. 9193@c Note that -V without an argument has never been 9194@c documented as a cvs admin option. 9195 9196@item -x@var{suffixes} 9197In previous versions of @sc{cvs}, this was documented 9198as a way of specifying the names of the @sc{rcs} 9199files. However, @sc{cvs} has always required that the 9200@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 9201this option has never done anything useful. 9202 9203@c The rcs -z option, to specify the timezone, has 9204@c never been documented as a cvs admin option. 9205@end table 9206 9207@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9208@node annotate 9209@appendixsec annotate---What revision modified each line of a file? 9210@cindex annotate (subcommand) 9211 9212@itemize @bullet 9213@item 9214Synopsis: annotate [options] files@dots{} 9215@item 9216Requires: repository. 9217@item 9218Changes: nothing. 9219@end itemize 9220 9221For each file in @var{files}, print the head revision 9222of the trunk, together with information on the last 9223modification for each line. 9224 9225@menu 9226* annotate options:: annotate options 9227* annotate example:: annotate example 9228@end menu 9229 9230@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9231@node annotate options 9232@appendixsubsec annotate options 9233 9234These standard options are supported by @code{annotate} 9235(@pxref{Common options}, for a complete description of 9236them): 9237 9238@table @code 9239@item -l 9240Local directory only, no recursion. 9241 9242@item -R 9243Process directories recursively. 9244 9245@item -f 9246Use head revision if tag/date not found. 9247 9248@item -F 9249Annotate binary files. 9250 9251@item -r @var{tag}[:@var{date}] 9252Annotate file as of specified revision/tag or, when @var{date} is specified 9253and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9254existed on @var{date}. See @ref{Common options}. 9255 9256@item -D @var{date} 9257Annotate file as of specified date. 9258@end table 9259 9260@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9261@node annotate example 9262@appendixsubsec annotate example 9263 9264For example: 9265 9266@example 9267$ cvs annotate ssfile 9268Annotations for ssfile 9269*************** 92701.1 (mary 27-Mar-96): ssfile line 1 92711.2 (joe 28-Mar-96): ssfile line 2 9272@end example 9273 9274The file @file{ssfile} currently contains two lines. 9275The @code{ssfile line 1} line was checked in by 9276@code{mary} on March 27. Then, on March 28, @code{joe} 9277added a line @code{ssfile line 2}, without modifying 9278the @code{ssfile line 1} line. This report doesn't 9279tell you anything about lines which have been deleted 9280or replaced; you need to use @code{cvs diff} for that 9281(@pxref{diff}). 9282 9283The options to @code{cvs annotate} are listed in 9284@ref{Invoking CVS}, and can be used to select the files 9285and revisions to annotate. The options are described 9286in more detail there and in @ref{Common options}. 9287 9288@c FIXME: maybe an example using the options? Just 9289@c what it means to select a revision might be worth a 9290@c few words of explanation ("you want to see who 9291@c changed this line *before* 1.4"...). 9292 9293@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9294@node checkout 9295@appendixsec checkout---Check out sources for editing 9296@cindex checkout (subcommand) 9297@cindex co (subcommand) 9298 9299@itemize @bullet 9300@item 9301Synopsis: checkout [options] modules@dots{} 9302@item 9303Requires: repository. 9304@item 9305Changes: working directory. 9306@item 9307Synonyms: co, get 9308@end itemize 9309 9310Create or update a working directory containing copies of the 9311source files specified by @var{modules}. You must execute 9312@code{checkout} before using most of the other @sc{cvs} 9313commands, since most of them operate on your working 9314directory. 9315 9316The @var{modules} are either 9317symbolic names for some 9318collection of source directories and files, or paths to 9319directories or files in the repository. The symbolic 9320names are defined in the @samp{modules} file. 9321@xref{modules}. 9322@c Needs an example, particularly of the non-"modules" 9323@c case but probably of both. 9324 9325@c FIXME: this seems like a very odd place to introduce 9326@c people to how CVS works. The bit about unreserved 9327@c checkouts is also misleading as it depends on how 9328@c things are set up. 9329Depending on the modules you specify, @code{checkout} may 9330recursively create directories and populate them with 9331the appropriate source files. You can then edit these 9332source files at any time (regardless of whether other 9333software developers are editing their own copies of the 9334sources); update them to include new changes applied by 9335others to the source repository; or commit your work as 9336a permanent change to the source repository. 9337 9338Note that @code{checkout} is used to create 9339directories. The top-level directory created is always 9340added to the directory where @code{checkout} is 9341invoked, and usually has the same name as the specified 9342module. In the case of a module alias, the created 9343sub-directory may have a different name, but you can be 9344sure that it will be a sub-directory, and that 9345@code{checkout} will show the relative path leading to 9346each file as it is extracted into your private work 9347area (unless you specify the @samp{-Q} global option). 9348 9349The files created by @code{checkout} are created 9350read-write, unless the @samp{-r} option to @sc{cvs} 9351(@pxref{Global options}) is specified, the 9352@code{CVSREAD} environment variable is specified 9353(@pxref{Environment variables}), or a watch is in 9354effect for that file (@pxref{Watches}). 9355 9356Note that running @code{checkout} on a directory that was already 9357built by a prior @code{checkout} is also permitted. 9358This is similar to specifying the @samp{-d} option 9359to the @code{update} command in the sense that new 9360directories that have been created in the repository 9361will appear in your work area. 9362However, @code{checkout} takes a module name whereas 9363@code{update} takes a directory name. Also 9364to use @code{checkout} this way it must be run from the 9365top level directory (where you originally ran 9366@code{checkout} from), so before you run 9367@code{checkout} to update an existing directory, don't 9368forget to change your directory to the top level 9369directory. 9370 9371For the output produced by the @code{checkout} command 9372see @ref{update output}. 9373 9374@menu 9375* checkout options:: checkout options 9376* checkout examples:: checkout examples 9377@end menu 9378 9379@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9380@node checkout options 9381@appendixsubsec checkout options 9382 9383These standard options are supported by @code{checkout} 9384(@pxref{Common options}, for a complete description of 9385them): 9386 9387@table @code 9388@item -D @var{date} 9389Use the most recent revision no later than @var{date}. 9390This option is sticky, and implies @samp{-P}. See 9391@ref{Sticky tags}, for more information on sticky tags/dates. 9392 9393@item -f 9394Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision is 9395found, retrieve the most recent revision (instead of ignoring the file). 9396 9397@item -k @var{kflag} 9398Process keywords according to @var{kflag}. See 9399@ref{Keyword substitution}. 9400This option is sticky; future updates of 9401this file in this working directory will use the same 9402@var{kflag}. The @code{status} command can be viewed 9403to see the sticky options. See @ref{Invoking CVS}, for 9404more information on the @code{status} command. 9405 9406@item -l 9407Local; run only in current working directory. 9408 9409@item -n 9410Do not run any checkout program (as specified 9411with the @samp{-o} option in the modules file; 9412@pxref{modules}). 9413 9414@item -P 9415Prune empty directories. See @ref{Moving directories}. 9416 9417@item -p 9418Pipe files to the standard output. 9419 9420@item -R 9421Checkout directories recursively. This option is on by default. 9422 9423@item -r @var{tag}[:@var{date}] 9424Checkout the revision specified by @var{tag} or, when @var{date} is specified 9425and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9426existed on @var{date}. This option is sticky, and implies @samp{-P}. 9427See @ref{Sticky tags}, for more information on sticky tags/dates. Also, 9428see @ref{Common options}. 9429@end table 9430 9431In addition to those, you can use these special command 9432options with @code{checkout}: 9433 9434@table @code 9435@item -A 9436Reset any sticky tags, dates, or @samp{-k} options. 9437See @ref{Sticky tags}, for more information on sticky tags/dates. 9438 9439@item -c 9440Copy the module file, sorted, to the standard output, 9441instead of creating or modifying any files or 9442directories in your working directory. 9443 9444@item -d @var{dir} 9445Create a directory called @var{dir} for the working 9446files, instead of using the module name. In general, 9447using this flag is equivalent to using @samp{mkdir 9448@var{dir}; cd @var{dir}} followed by the checkout 9449command without the @samp{-d} flag. 9450 9451There is an important exception, however. It is very 9452convenient when checking out a single item to have the 9453output appear in a directory that doesn't contain empty 9454intermediate directories. In this case @emph{only}, 9455@sc{cvs} tries to ``shorten'' pathnames to avoid those empty 9456directories. 9457 9458For example, given a module @samp{foo} that contains 9459the file @samp{bar.c}, the command @samp{cvs co -d dir 9460foo} will create directory @samp{dir} and place 9461@samp{bar.c} inside. Similarly, given a module 9462@samp{bar} which has subdirectory @samp{baz} wherein 9463there is a file @samp{quux.c}, the command @samp{cvs co 9464-d dir bar/baz} will create directory @samp{dir} and 9465place @samp{quux.c} inside. 9466 9467Using the @samp{-N} flag will defeat this behavior. 9468Given the same module definitions above, @samp{cvs co 9469-N -d dir foo} will create directories @samp{dir/foo} 9470and place @samp{bar.c} inside, while @samp{cvs co -N -d 9471dir bar/baz} will create directories @samp{dir/bar/baz} 9472and place @samp{quux.c} inside. 9473 9474@item -j @var{tag} 9475With two @samp{-j} options, merge changes from the 9476revision specified with the first @samp{-j} option to 9477the revision specified with the second @samp{j} option, 9478into the working directory. 9479 9480With one @samp{-j} option, merge changes from the 9481ancestor revision to the revision specified with the 9482@samp{-j} option, into the working directory. The 9483ancestor revision is the common ancestor of the 9484revision which the working directory is based on, and 9485the revision specified in the @samp{-j} option. 9486 9487In addition, each -j option can contain an optional 9488date specification which, when used with branches, can 9489limit the chosen revision to one within a specific 9490date. An optional date is specified by adding a colon 9491(:) to the tag: 9492@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 9493 9494@xref{Branching and merging}. 9495 9496@item -N 9497Only useful together with @samp{-d @var{dir}}. With 9498this option, @sc{cvs} will not ``shorten'' module paths 9499in your working directory when you check out a single 9500module. See the @samp{-d} flag for examples and a 9501discussion. 9502 9503@item -s 9504Like @samp{-c}, but include the status of all modules, 9505and sort it by the status string. @xref{modules}, for 9506info about the @samp{-s} option that is used inside the 9507modules file to set the module status. 9508@end table 9509 9510@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9511@node checkout examples 9512@appendixsubsec checkout examples 9513 9514Get a copy of the module @samp{tc}: 9515 9516@example 9517$ cvs checkout tc 9518@end example 9519 9520Get a copy of the module @samp{tc} as it looked one day 9521ago: 9522 9523@example 9524$ cvs checkout -D yesterday tc 9525@end example 9526 9527@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9528@node commit 9529@appendixsec commit---Check files into the repository 9530@cindex commit (subcommand) 9531 9532@itemize @bullet 9533@item 9534Synopsis: commit [-lnRf] [-m 'log_message' | 9535-F file] [-r revision] [files@dots{}] 9536@item 9537Requires: working directory, repository. 9538@item 9539Changes: repository. 9540@item 9541Synonym: ci 9542@end itemize 9543 9544Use @code{commit} when you want to incorporate changes 9545from your working source files into the source 9546repository. 9547 9548If you don't specify particular files to commit, all of 9549the files in your working current directory are 9550examined. @code{commit} is careful to change in the 9551repository only those files that you have really 9552changed. By default (or if you explicitly specify the 9553@samp{-R} option), files in subdirectories are also 9554examined and committed if they have changed; you can 9555use the @samp{-l} option to limit @code{commit} to the 9556current directory only. 9557 9558@code{commit} verifies that the selected files are up 9559to date with the current revisions in the source 9560repository; it will notify you, and exit without 9561committing, if any of the specified files must be made 9562current first with @code{update} (@pxref{update}). 9563@code{commit} does not call the @code{update} command 9564for you, but rather leaves that for you to do when the 9565time is right. 9566 9567When all is well, an editor is invoked to allow you to 9568enter a log message that will be written to one or more 9569logging programs (@pxref{modules}, and @pxref{loginfo}) 9570and placed in the @sc{rcs} file inside the 9571repository. This log message can be retrieved with the 9572@code{log} command; see @ref{log}. You can specify the 9573log message on the command line with the @samp{-m 9574@var{message}} option, and thus avoid the editor invocation, 9575or use the @samp{-F @var{file}} option to specify 9576that the argument file contains the log message. 9577 9578At @code{commit}, a unique commitid is placed in the @sc{rcs} 9579file inside the repository. All files committed at once 9580get the same commitid. The commitid can be retrieved with 9581the @code{log} and @code{status} command; see @ref{log}, 9582@ref{File status}. 9583 9584@menu 9585* commit options:: commit options 9586* commit examples:: commit examples 9587@end menu 9588 9589@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9590@node commit options 9591@appendixsubsec commit options 9592 9593These standard options are supported by @code{commit} 9594(@pxref{Common options}, for a complete description of 9595them): 9596 9597@table @code 9598@item -l 9599Local; run only in current working directory. 9600 9601@item -R 9602Commit directories recursively. This is on by default. 9603 9604@item -r @var{revision} 9605Commit to @var{revision}. @var{revision} must be 9606either a branch, or a revision on the main trunk that 9607is higher than any existing revision number 9608(@pxref{Assigning revisions}). You 9609cannot commit to a specific revision on a branch. 9610@c FIXME: Need xref for branch case. 9611@end table 9612 9613@code{commit} also supports these options: 9614 9615@table @code 9616@item -c 9617Refuse to commit files unless the user has registered a valid edit on the 9618file via @code{cvs edit}. This is most useful when @samp{commit -c} 9619and @samp{edit -c} have been placed in all @file{.cvsrc} files. 9620A commit can be forced anyways by either registering an edit retroactively 9621via @code{cvs edit} (no changes to the file will be lost) or using the 9622@code{-f} option to commit. Support for @code{commit -c} requires both 9623client and a server versions 1.12.10 or greater. 9624 9625@item -F @var{file} 9626Read the log message from @var{file}, instead 9627of invoking an editor. 9628 9629@item -f 9630Note that this is not the standard behavior of 9631the @samp{-f} option as defined in @ref{Common options}. 9632 9633Force @sc{cvs} to commit a new revision even if you haven't 9634made any changes to the file. As of @sc{cvs} version 1.12.10, 9635it also causes the @code{-c} option to be ignored. If the current revision 9636of @var{file} is 1.7, then the following two commands 9637are equivalent: 9638 9639@example 9640$ cvs commit -f @var{file} 9641$ cvs commit -r 1.8 @var{file} 9642@end example 9643 9644@c This is odd, but it's how CVS has worked for some 9645@c time. 9646The @samp{-f} option disables recursion (i.e., it 9647implies @samp{-l}). To force @sc{cvs} to commit a new 9648revision for all files in all subdirectories, you must 9649use @samp{-f -R}. 9650 9651@item -m @var{message} 9652Use @var{message} as the log message, instead of 9653invoking an editor. 9654@end table 9655 9656@need 2000 9657@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9658@node commit examples 9659@appendixsubsec commit examples 9660 9661@c FIXME: this material wants to be somewhere 9662@c in "Branching and merging". 9663 9664@appendixsubsubsec Committing to a branch 9665 9666You can commit to a branch revision (one that has an 9667even number of dots) with the @samp{-r} option. To 9668create a branch revision, use the @samp{-b} option 9669of the @code{rtag} or @code{tag} commands 9670(@pxref{Branching and merging}). Then, either @code{checkout} or 9671@code{update} can be used to base your sources on the 9672newly created branch. From that point on, all 9673@code{commit} changes made within these working sources 9674will be automatically added to a branch revision, 9675thereby not disturbing main-line development in any 9676way. For example, if you had to create a patch to the 96771.2 version of the product, even though the 2.0 version 9678is already under development, you might do: 9679 9680@example 9681$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 9682$ cvs checkout -r FCS1_2_Patch product_module 9683$ cd product_module 9684[[ hack away ]] 9685$ cvs commit 9686@end example 9687 9688@noindent 9689This works automatically since the @samp{-r} option is 9690sticky. 9691 9692@appendixsubsubsec Creating the branch after editing 9693 9694Say you have been working on some extremely 9695experimental software, based on whatever revision you 9696happened to checkout last week. If others in your 9697group would like to work on this software with you, but 9698without disturbing main-line development, you could 9699commit your change to a new branch. Others can then 9700checkout your experimental stuff and utilize the full 9701benefit of @sc{cvs} conflict resolution. The scenario might 9702look like: 9703 9704@c FIXME: Should we be recommending tagging the branchpoint? 9705@example 9706[[ hacked sources are present ]] 9707$ cvs tag -b EXPR1 9708$ cvs update -r EXPR1 9709$ cvs commit 9710@end example 9711 9712The @code{update} command will make the @samp{-r 9713EXPR1} option sticky on all files. Note that your 9714changes to the files will never be removed by the 9715@code{update} command. The @code{commit} will 9716automatically commit to the correct branch, because the 9717@samp{-r} is sticky. You could also do like this: 9718 9719@c FIXME: Should we be recommending tagging the branchpoint? 9720@example 9721[[ hacked sources are present ]] 9722$ cvs tag -b EXPR1 9723$ cvs commit -r EXPR1 9724@end example 9725 9726@noindent 9727but then, only those files that were changed by you 9728will have the @samp{-r EXPR1} sticky flag. If you hack 9729away, and commit without specifying the @samp{-r EXPR1} 9730flag, some files may accidentally end up on the main 9731trunk. 9732 9733To work with you on the experimental change, others 9734would simply do 9735 9736@example 9737$ cvs checkout -r EXPR1 whatever_module 9738@end example 9739 9740@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9741@node diff 9742@appendixsec diff---Show differences between revisions 9743@cindex diff (subcommand) 9744 9745@itemize @bullet 9746@item 9747Synopsis: diff [-lR] [-k kflag] [format_options] [(-r rev1[:date1] | -D date1) [-r rev2[:date2] | -D date2]] [files@dots{}] 9748@item 9749Requires: working directory, repository. 9750@item 9751Changes: nothing. 9752@end itemize 9753 9754The @code{diff} command is used to compare different 9755revisions of files. The default action is to compare 9756your working files with the revisions they were based 9757on, and report any differences that are found. 9758 9759If any file names are given, only those files are 9760compared. If any directories are given, all files 9761under them will be compared. 9762 9763The exit status for diff is different than for other 9764@sc{cvs} commands; for details @ref{Exit status}. 9765 9766@menu 9767* diff options:: diff options 9768* diff examples:: diff examples 9769@end menu 9770 9771@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9772@node diff options 9773@appendixsubsec diff options 9774 9775These standard options are supported by @code{diff} 9776(@pxref{Common options}, for a complete description of 9777them): 9778 9779@table @code 9780@item -D @var{date} 9781Use the most recent revision no later than @var{date}. 9782See @samp{-r} for how this affects the comparison. 9783 9784@item -k @var{kflag} 9785Process keywords according to @var{kflag}. See 9786@ref{Keyword substitution}. 9787 9788@item -l 9789Local; run only in current working directory. 9790 9791@item -R 9792Examine directories recursively. This option is on by 9793default. 9794 9795@item -r @var{tag}[:@var{date}] 9796Compare with revision specified by @var{tag} or, when @var{date} is specified 9797and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9798existed on @var{date}. Zero, one or two 9799@samp{-r} options can be present. With no @samp{-r} 9800option, the working file will be compared with the 9801revision it was based on. With one @samp{-r}, that 9802revision will be compared to your current working file. 9803With two @samp{-r} options those two revisions will be 9804compared (and your working file will not affect the 9805outcome in any way). 9806@c We should be a lot more explicit, with examples, 9807@c about the difference between "cvs diff" and "cvs 9808@c diff -r HEAD". This often confuses new users. 9809 9810One or both @samp{-r} options can be replaced by a 9811@samp{-D @var{date}} option, described above. 9812@end table 9813 9814@c Conceptually, this is a disaster. There are 3 9815@c zillion diff formats that we support via the diff 9816@c library. It is not obvious to me that we should 9817@c document them all. Maybe just the most common ones 9818@c like -c and -u, and think about phasing out the 9819@c obscure ones. 9820@c FIXCVS: also should be a way to specify an external 9821@c diff program (which can be different for different 9822@c file types) and pass through 9823@c arbitrary options, so that the user can do 9824@c "--pass=-Z --pass=foo" or something even if CVS 9825@c doesn't know about the "-Z foo" option to diff. 9826@c This would fit nicely with deprecating/eliminating 9827@c the obscure options of the diff library, because it 9828@c would let people specify an external GNU diff if 9829@c they are into that sort of thing. 9830The following options specify the format of the 9831output. They have the same meaning as in GNU diff. 9832Most options have two equivalent names, one of which is a single letter 9833preceded by @samp{-}, and the other of which is a long name preceded by 9834@samp{--}. 9835 9836@table @samp 9837@item -@var{lines} 9838Show @var{lines} (an integer) lines of context. This option does not 9839specify an output format by itself; it has no effect unless it is 9840combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9841operation, @code{patch} typically needs at least two lines of context. 9842 9843@item -a 9844Treat all files as text and compare them line-by-line, even if they 9845do not seem to be text. 9846 9847@item -b 9848Ignore trailing white space and consider all other sequences of one or 9849more white space characters to be equivalent. 9850 9851@item -B 9852Ignore changes that just insert or delete blank lines. 9853 9854@item --binary 9855Read and write data in binary mode. 9856 9857@item --brief 9858Report only whether the files differ, not the details of the 9859differences. 9860 9861@item -c 9862Use the context output format. 9863 9864@item -C @var{lines} 9865@itemx --context@r{[}=@var{lines}@r{]} 9866Use the context output format, showing @var{lines} (an integer) lines of 9867context, or three if @var{lines} is not given. 9868For proper operation, @code{patch} typically needs at least two lines of 9869context. 9870 9871@item --changed-group-format=@var{format} 9872Use @var{format} to output a line group containing differing lines from 9873both files in if-then-else format. @xref{Line group formats}. 9874 9875@item -d 9876Change the algorithm to perhaps find a smaller set of changes. This makes 9877@code{diff} slower (sometimes much slower). 9878 9879@item -e 9880@itemx --ed 9881Make output that is a valid @code{ed} script. 9882 9883@item --expand-tabs 9884Expand tabs to spaces in the output, to preserve the alignment of tabs 9885in the input files. 9886 9887@item -f 9888Make output that looks vaguely like an @code{ed} script but has changes 9889in the order they appear in the file. 9890 9891@item -F @var{regexp} 9892In context and unified format, for each hunk of differences, show some 9893of the last preceding line that matches @var{regexp}. 9894 9895@item --forward-ed 9896Make output that looks vaguely like an @code{ed} script but has changes 9897in the order they appear in the file. 9898 9899@item -H 9900Use heuristics to speed handling of large files that have numerous 9901scattered small changes. 9902 9903@item --horizon-lines=@var{lines} 9904Do not discard the last @var{lines} lines of the common prefix 9905and the first @var{lines} lines of the common suffix. 9906 9907@item -i 9908Ignore changes in case; consider upper- and lower-case letters 9909equivalent. 9910 9911@item -I @var{regexp} 9912Ignore changes that just insert or delete lines that match @var{regexp}. 9913 9914@item --ifdef=@var{name} 9915Make merged if-then-else output using @var{name}. 9916 9917@item --ignore-all-space 9918Ignore white space when comparing lines. 9919 9920@item --ignore-blank-lines 9921Ignore changes that just insert or delete blank lines. 9922 9923@item --ignore-case 9924Ignore changes in case; consider upper- and lower-case to be the same. 9925 9926@item --ignore-matching-lines=@var{regexp} 9927Ignore changes that just insert or delete lines that match @var{regexp}. 9928 9929@item --ignore-space-change 9930Ignore trailing white space and consider all other sequences of one or 9931more white space characters to be equivalent. 9932 9933@item --initial-tab 9934Output a tab rather than a space before the text of a line in normal or 9935context format. This causes the alignment of tabs in the line to look 9936normal. 9937 9938@item -L @var{label} 9939Use @var{label} instead of the file name in the context format 9940and unified format headers. 9941 9942@item --label=@var{label} 9943Use @var{label} instead of the file name in the context format 9944and unified format headers. 9945 9946@item --left-column 9947Print only the left column of two common lines in side by side format. 9948 9949@item --line-format=@var{format} 9950Use @var{format} to output all input lines in if-then-else format. 9951@xref{Line formats}. 9952 9953@item --minimal 9954Change the algorithm to perhaps find a smaller set of changes. This 9955makes @code{diff} slower (sometimes much slower). 9956 9957@item -n 9958Output RCS-format diffs; like @samp{-f} except that each command 9959specifies the number of lines affected. 9960 9961@item -N 9962@itemx --new-file 9963In directory comparison, if a file is found in only one directory, 9964treat it as present but empty in the other directory. 9965 9966@item --new-group-format=@var{format} 9967Use @var{format} to output a group of lines taken from just the second 9968file in if-then-else format. @xref{Line group formats}. 9969 9970@item --new-line-format=@var{format} 9971Use @var{format} to output a line taken from just the second file in 9972if-then-else format. @xref{Line formats}. 9973 9974@item --old-group-format=@var{format} 9975Use @var{format} to output a group of lines taken from just the first 9976file in if-then-else format. @xref{Line group formats}. 9977 9978@item --old-line-format=@var{format} 9979Use @var{format} to output a line taken from just the first file in 9980if-then-else format. @xref{Line formats}. 9981 9982@item -p 9983Show which C function each change is in. 9984 9985@item --rcs 9986Output RCS-format diffs; like @samp{-f} except that each command 9987specifies the number of lines affected. 9988 9989@item --report-identical-files 9990@itemx -s 9991Report when two files are the same. 9992 9993@item --show-c-function 9994Show which C function each change is in. 9995 9996@item --show-function-line=@var{regexp} 9997In context and unified format, for each hunk of differences, show some 9998of the last preceding line that matches @var{regexp}. 9999 10000@item --side-by-side 10001Use the side by side output format. 10002 10003@item --speed-large-files 10004Use heuristics to speed handling of large files that have numerous 10005scattered small changes. 10006 10007@item --suppress-common-lines 10008Do not print common lines in side by side format. 10009 10010@item -t 10011Expand tabs to spaces in the output, to preserve the alignment of tabs 10012in the input files. 10013 10014@item -T 10015Output a tab rather than a space before the text of a line in normal or 10016context format. This causes the alignment of tabs in the line to look 10017normal. 10018 10019@item --text 10020Treat all files as text and compare them line-by-line, even if they 10021do not appear to be text. 10022 10023@item -u 10024Use the unified output format. 10025 10026@item --unchanged-group-format=@var{format} 10027Use @var{format} to output a group of common lines taken from both files 10028in if-then-else format. @xref{Line group formats}. 10029 10030@item --unchanged-line-format=@var{format} 10031Use @var{format} to output a line common to both files in if-then-else 10032format. @xref{Line formats}. 10033 10034@item -U @var{lines} 10035@itemx --unified@r{[}=@var{lines}@r{]} 10036Use the unified output format, showing @var{lines} (an integer) lines of 10037context, or three if @var{lines} is not given. 10038For proper operation, @code{patch} typically needs at least two lines of 10039context. 10040 10041@item -w 10042Ignore white space when comparing lines. 10043 10044@item -W @var{columns} 10045@itemx --width=@var{columns} 10046Use an output width of @var{columns} in side by side format. 10047 10048@item -y 10049Use the side by side output format. 10050@end table 10051 10052@menu 10053* Line group formats:: Line group formats 10054* Line formats:: Line formats 10055@end menu 10056 10057@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10058@node Line group formats 10059@appendixsubsubsec Line group formats 10060 10061Line group formats let you specify formats suitable for many 10062applications that allow if-then-else input, including programming 10063languages and text formatting languages. A line group format specifies 10064the output format for a contiguous group of similar lines. 10065 10066For example, the following command compares the TeX file @file{myfile} 10067with the original version from the repository, 10068and outputs a merged file in which old regions are 10069surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 10070regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 10071 10072@example 10073cvs diff \ 10074 --old-group-format='\begin@{em@} 10075%<\end@{em@} 10076' \ 10077 --new-group-format='\begin@{bf@} 10078%>\end@{bf@} 10079' \ 10080 myfile 10081@end example 10082 10083The following command is equivalent to the above example, but it is a 10084little more verbose, because it spells out the default line group formats. 10085 10086@example 10087cvs diff \ 10088 --old-group-format='\begin@{em@} 10089%<\end@{em@} 10090' \ 10091 --new-group-format='\begin@{bf@} 10092%>\end@{bf@} 10093' \ 10094 --unchanged-group-format='%=' \ 10095 --changed-group-format='\begin@{em@} 10096%<\end@{em@} 10097\begin@{bf@} 10098%>\end@{bf@} 10099' \ 10100 myfile 10101@end example 10102 10103Here is a more advanced example, which outputs a diff listing with 10104headers containing line numbers in a ``plain English'' style. 10105 10106@example 10107cvs diff \ 10108 --unchanged-group-format='' \ 10109 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 10110%<' \ 10111 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 10112%>' \ 10113 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 10114%<-------- to: 10115%>' \ 10116 myfile 10117@end example 10118 10119To specify a line group format, use one of the options 10120listed below. You can specify up to four line group formats, one for 10121each kind of line group. You should quote @var{format}, because it 10122typically contains shell metacharacters. 10123 10124@table @samp 10125@item --old-group-format=@var{format} 10126These line groups are hunks containing only lines from the first file. 10127The default old group format is the same as the changed group format if 10128it is specified; otherwise it is a format that outputs the line group as-is. 10129 10130@item --new-group-format=@var{format} 10131These line groups are hunks containing only lines from the second 10132file. The default new group format is same as the changed group 10133format if it is specified; otherwise it is a format that outputs the 10134line group as-is. 10135 10136@item --changed-group-format=@var{format} 10137These line groups are hunks containing lines from both files. The 10138default changed group format is the concatenation of the old and new 10139group formats. 10140 10141@item --unchanged-group-format=@var{format} 10142These line groups contain lines common to both files. The default 10143unchanged group format is a format that outputs the line group as-is. 10144@end table 10145 10146In a line group format, ordinary characters represent themselves; 10147conversion specifications start with @samp{%} and have one of the 10148following forms. 10149 10150@table @samp 10151@item %< 10152stands for the lines from the first file, including the trailing newline. 10153Each line is formatted according to the old line format (@pxref{Line formats}). 10154 10155@item %> 10156stands for the lines from the second file, including the trailing newline. 10157Each line is formatted according to the new line format. 10158 10159@item %= 10160stands for the lines common to both files, including the trailing newline. 10161Each line is formatted according to the unchanged line format. 10162 10163@item %% 10164stands for @samp{%}. 10165 10166@item %c'@var{C}' 10167where @var{C} is a single character, stands for @var{C}. 10168@var{C} may not be a backslash or an apostrophe. 10169For example, @samp{%c':'} stands for a colon, even inside 10170the then-part of an if-then-else format, which a colon would 10171normally terminate. 10172 10173@item %c'\@var{O}' 10174where @var{O} is a string of 1, 2, or 3 octal digits, 10175stands for the character with octal code @var{O}. 10176For example, @samp{%c'\0'} stands for a null character. 10177 10178@item @var{F}@var{n} 10179where @var{F} is a @code{printf} conversion specification and @var{n} is one 10180of the following letters, stands for @var{n}'s value formatted with @var{F}. 10181 10182@table @samp 10183@item e 10184The line number of the line just before the group in the old file. 10185 10186@item f 10187The line number of the first line in the group in the old file; 10188equals @var{e} + 1. 10189 10190@item l 10191The line number of the last line in the group in the old file. 10192 10193@item m 10194The line number of the line just after the group in the old file; 10195equals @var{l} + 1. 10196 10197@item n 10198The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 10199 10200@item E, F, L, M, N 10201Likewise, for lines in the new file. 10202 10203@end table 10204 10205The @code{printf} conversion specification can be @samp{%d}, 10206@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 10207lower case hexadecimal, or upper case hexadecimal output 10208respectively. After the @samp{%} the following options can appear in 10209sequence: a @samp{-} specifying left-justification; an integer 10210specifying the minimum field width; and a period followed by an 10211optional integer specifying the minimum number of digits. 10212For example, @samp{%5dN} prints the number of new lines in the group 10213in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 10214 10215@item (@var{A}=@var{B}?@var{T}:@var{E}) 10216If @var{A} equals @var{B} then @var{T} else @var{E}. 10217@var{A} and @var{B} are each either a decimal constant 10218or a single letter interpreted as above. 10219This format spec is equivalent to @var{T} if 10220@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 10221 10222For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 10223@samp{no lines} if @var{N} (the number of lines in the group in the 10224new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 10225otherwise. 10226@end table 10227 10228@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10229@node Line formats 10230@appendixsubsubsec Line formats 10231 10232Line formats control how each line taken from an input file is 10233output as part of a line group in if-then-else format. 10234 10235For example, the following command outputs text with a one-column 10236change indicator to the left of the text. The first column of output 10237is @samp{-} for deleted lines, @samp{|} for added lines, and a space 10238for unchanged lines. The formats contain newline characters where 10239newlines are desired on output. 10240 10241@example 10242cvs diff \ 10243 --old-line-format='-%l 10244' \ 10245 --new-line-format='|%l 10246' \ 10247 --unchanged-line-format=' %l 10248' \ 10249 myfile 10250@end example 10251 10252To specify a line format, use one of the following options. You should 10253quote @var{format}, since it often contains shell metacharacters. 10254 10255@table @samp 10256@item --old-line-format=@var{format} 10257formats lines just from the first file. 10258 10259@item --new-line-format=@var{format} 10260formats lines just from the second file. 10261 10262@item --unchanged-line-format=@var{format} 10263formats lines common to both files. 10264 10265@item --line-format=@var{format} 10266formats all lines; in effect, it sets all three above options simultaneously. 10267@end table 10268 10269In a line format, ordinary characters represent themselves; 10270conversion specifications start with @samp{%} and have one of the 10271following forms. 10272 10273@table @samp 10274@item %l 10275stands for the contents of the line, not counting its trailing 10276newline (if any). This format ignores whether the line is incomplete. 10277 10278@item %L 10279stands for the contents of the line, including its trailing newline 10280(if any). If a line is incomplete, this format preserves its 10281incompleteness. 10282 10283@item %% 10284stands for @samp{%}. 10285 10286@item %c'@var{C}' 10287where @var{C} is a single character, stands for @var{C}. 10288@var{C} may not be a backslash or an apostrophe. 10289For example, @samp{%c':'} stands for a colon. 10290 10291@item %c'\@var{O}' 10292where @var{O} is a string of 1, 2, or 3 octal digits, 10293stands for the character with octal code @var{O}. 10294For example, @samp{%c'\0'} stands for a null character. 10295 10296@item @var{F}n 10297where @var{F} is a @code{printf} conversion specification, 10298stands for the line number formatted with @var{F}. 10299For example, @samp{%.5dn} prints the line number using the 10300@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 10301more about printf conversion specifications. 10302 10303@end table 10304 10305The default line format is @samp{%l} followed by a newline character. 10306 10307If the input contains tab characters and it is important that they line 10308up on output, you should ensure that @samp{%l} or @samp{%L} in a line 10309format is just after a tab stop (e.g.@: by preceding @samp{%l} or 10310@samp{%L} with a tab character), or you should use the @samp{-t} or 10311@samp{--expand-tabs} option. 10312 10313Taken together, the line and line group formats let you specify many 10314different formats. For example, the following command uses a format 10315similar to @code{diff}'s normal format. You can tailor this command 10316to get fine control over @code{diff}'s output. 10317 10318@example 10319cvs diff \ 10320 --old-line-format='< %l 10321' \ 10322 --new-line-format='> %l 10323' \ 10324 --old-group-format='%df%(f=l?:,%dl)d%dE 10325%<' \ 10326 --new-group-format='%dea%dF%(F=L?:,%dL) 10327%>' \ 10328 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 10329%<--- 10330%>' \ 10331 --unchanged-group-format='' \ 10332 myfile 10333@end example 10334 10335@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10336@node diff examples 10337@appendixsubsec diff examples 10338 10339The following line produces a Unidiff (@samp{-u} flag) 10340between revision 1.14 and 1.19 of 10341@file{backend.c}. Due to the @samp{-kk} flag no 10342keywords are substituted, so differences that only depend 10343on keyword substitution are ignored. 10344 10345@example 10346$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 10347@end example 10348 10349Suppose the experimental branch EXPR1 was based on a 10350set of files tagged RELEASE_1_0. To see what has 10351happened on that branch, the following can be used: 10352 10353@example 10354$ cvs diff -r RELEASE_1_0 -r EXPR1 10355@end example 10356 10357A command like this can be used to produce a context 10358diff between two releases: 10359 10360@example 10361$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 10362@end example 10363 10364If you are maintaining ChangeLogs, a command like the following 10365just before you commit your changes may help you write 10366the ChangeLog entry. All local modifications that have 10367not yet been committed will be printed. 10368 10369@example 10370$ cvs diff -u | less 10371@end example 10372 10373@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10374@node export 10375@appendixsec export---Export sources from CVS, similar to checkout 10376@cindex export (subcommand) 10377 10378@itemize @bullet 10379@item 10380Synopsis: export [-flNnR] (-r rev[:date] | -D date) [-k subst] [-d dir] module@dots{} 10381@item 10382Requires: repository. 10383@item 10384Changes: current directory. 10385@end itemize 10386 10387This command is a variant of @code{checkout}; use it 10388when you want a copy of the source for module without 10389the @sc{cvs} administrative directories. For example, you 10390might use @code{export} to prepare source for shipment 10391off-site. This command requires that you specify a 10392date or tag (with @samp{-D} or @samp{-r}), so that you 10393can count on reproducing the source you ship to others 10394(and thus it always prunes empty directories). 10395 10396One often would like to use @samp{-kv} with @code{cvs 10397export}. This causes any keywords to be 10398expanded such that an import done at some other site 10399will not lose the keyword revision information. But be 10400aware that doesn't handle an export containing binary 10401files correctly. Also be aware that after having used 10402@samp{-kv}, one can no longer use the @code{ident} 10403command (which is part of the @sc{rcs} suite---see 10404ident(1)) which looks for keyword strings. If 10405you want to be able to use @code{ident} you must not 10406use @samp{-kv}. 10407 10408@menu 10409* export options:: export options 10410@end menu 10411 10412@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10413@node export options 10414@appendixsubsec export options 10415 10416These standard options are supported by @code{export} 10417(@pxref{Common options}, for a complete description of 10418them): 10419 10420@table @code 10421@item -D @var{date} 10422Use the most recent revision no later than @var{date}. 10423 10424@item -f 10425If no matching revision is found, retrieve the most 10426recent revision (instead of ignoring the file). 10427 10428@item -l 10429Local; run only in current working directory. 10430 10431@item -n 10432Do not run any checkout program. 10433 10434@item -R 10435Export directories recursively. This is on by default. 10436 10437@item -r @var{tag}[:@var{date}] 10438Export the revision specified by @var{tag} or, when @var{date} is specified 10439and @var{tag} is a branch tag, the version from the branch @var{tag} as it 10440existed on @var{date}. See @ref{Common options}. 10441@end table 10442 10443In addition, these options (that are common to 10444@code{checkout} and @code{export}) are also supported: 10445 10446@table @code 10447@item -d @var{dir} 10448Create a directory called @var{dir} for the working 10449files, instead of using the module name. 10450@xref{checkout options}, for complete details on how 10451@sc{cvs} handles this flag. 10452 10453@item -k @var{subst} 10454Set keyword expansion mode (@pxref{Substitution modes}). 10455 10456@item -N 10457Only useful together with @samp{-d @var{dir}}. 10458@xref{checkout options}, for complete details on how 10459@sc{cvs} handles this flag. 10460@end table 10461 10462@ignore 10463@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10464@c @node export examples 10465@appendixsubsec export examples 10466 10467Contributed examples are gratefully accepted. 10468@c -- Examples here!! 10469@end ignore 10470 10471@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10472@node history 10473@appendixsec history---Show status of files and users 10474@cindex history (subcommand) 10475 10476@itemize @bullet 10477@item 10478Synopsis: history [-report] [-flags] [-options args] [files@dots{}] 10479@item 10480Requires: the file @file{$CVSROOT/CVSROOT/history} 10481@item 10482Changes: nothing. 10483@end itemize 10484 10485@sc{cvs} can keep a history log that tracks each use of most @sc{cvs} 10486commands. You can use @code{history} to display this information in 10487various formats. 10488 10489To enable logging, the @samp{LogHistory} config option must be set to 10490some value other than the empty string and the history file specified by 10491the @samp{HistoryLogPath} option must be writable by all users who may run 10492the @sc{cvs} executable (@pxref{config}). 10493 10494To enable the @code{history} command, logging must be enabled as above and 10495the @samp{HistorySearchPath} config option (@pxref{config}) must be set to 10496specify some number of the history logs created thereby and these files must 10497be readable by each user who might run the @code{history} command. 10498 10499Creating a repository via the @code{cvs init} command will enable logging of 10500all possible events to a single history log file 10501(@file{$CVSROOT/CVSROOT/history}) with read and write permissions for all 10502users (@pxref{Creating a repository}). 10503 10504@strong{Note: @code{history} uses @samp{-f}, @samp{-l}, 10505@samp{-n}, and @samp{-p} in ways that conflict with the 10506normal use inside @sc{cvs} (@pxref{Common options}).} 10507 10508@menu 10509* history options:: history options 10510@end menu 10511 10512@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10513@node history options 10514@appendixsubsec history options 10515 10516Several options (shown above as @samp{-report}) control what 10517kind of report is generated: 10518 10519@table @code 10520@item -c 10521Report on each time commit was used (i.e., each time 10522the repository was modified). 10523 10524@item -e 10525Everything (all record types). Equivalent to 10526specifying @samp{-x} with all record types. Of course, 10527@samp{-e} will also include record types which are 10528added in a future version of @sc{cvs}; if you are 10529writing a script which can only handle certain record 10530types, you'll want to specify @samp{-x}. 10531 10532@item -m @var{module} 10533Report on a particular module. (You can meaningfully 10534use @samp{-m} more than once on the command line.) 10535 10536@item -o 10537Report on checked-out modules. This is the default report type. 10538 10539@item -T 10540Report on all tags. 10541 10542@item -x @var{type} 10543Extract a particular set of record types @var{type} from the @sc{cvs} 10544history. The types are indicated by single letters, 10545which you may specify in combination. 10546 10547Certain commands have a single record type: 10548 10549@table @code 10550@item F 10551release 10552@item O 10553checkout 10554@item E 10555export 10556@item T 10557rtag 10558@end table 10559 10560@noindent 10561One of five record types may result from an update: 10562 10563@table @code 10564@item C 10565A merge was necessary but collisions were 10566detected (requiring manual merging). 10567@item G 10568A merge was necessary and it succeeded. 10569@item U 10570A working file was copied from the repository. 10571@item P 10572A working file was patched to match the repository. 10573@item W 10574The working copy of a file was deleted during 10575update (because it was gone from the repository). 10576@end table 10577 10578@noindent 10579One of three record types results from commit: 10580 10581@table @code 10582@item A 10583A file was added for the first time. 10584@item M 10585A file was modified. 10586@item R 10587A file was removed. 10588@end table 10589@end table 10590 10591The options shown as @samp{-flags} constrain or expand 10592the report without requiring option arguments: 10593 10594@table @code 10595@item -a 10596Show data for all users (the default is to show data 10597only for the user executing @code{history}). 10598 10599@item -l 10600Show last modification only. 10601 10602@item -w 10603Show only the records for modifications done from the 10604same working directory where @code{history} is 10605executing. 10606@end table 10607 10608The options shown as @samp{-options @var{args}} constrain the report 10609based on an argument: 10610 10611@table @code 10612@item -b @var{str} 10613Show data back to a record containing the string 10614@var{str} in either the module name, the file name, or 10615the repository path. 10616 10617@item -D @var{date} 10618Show data since @var{date}. This is slightly different 10619from the normal use of @samp{-D @var{date}}, which 10620selects the newest revision older than @var{date}. 10621 10622@item -f @var{file} 10623Show data for a particular file 10624(you can specify several @samp{-f} options on the same command line). 10625This is equivalent to specifying the file on the command line. 10626 10627@item -n @var{module} 10628Show data for a particular module 10629(you can specify several @samp{-n} options on the same command line). 10630 10631@item -p @var{repository} 10632Show data for a particular source repository (you 10633can specify several @samp{-p} options on the same command 10634line). 10635 10636@item -r @var{rev} 10637Show records referring to revisions since the revision 10638or tag named @var{rev} appears in individual @sc{rcs} 10639files. Each @sc{rcs} file is searched for the revision or 10640tag. 10641 10642@item -t @var{tag} 10643Show records since tag @var{tag} was last added to the 10644history file. This differs from the @samp{-r} flag 10645above in that it reads only the history file, not the 10646@sc{rcs} files, and is much faster. 10647 10648@item -u @var{name} 10649Show records for user @var{name}. 10650 10651@item -z @var{timezone} 10652Show times in the selected records using the specified 10653time zone instead of UTC. 10654@end table 10655 10656@ignore 10657@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10658@c @node history examples 10659@appendixsubsec history examples 10660 10661Contributed examples will gratefully be accepted. 10662@c -- Examples here! 10663@end ignore 10664 10665@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10666@node import 10667@appendixsec import---Import sources into CVS, using vendor branches 10668@cindex import (subcommand) 10669 10670@c FIXME: This node is way too long for one which has subnodes. 10671 10672@itemize @bullet 10673@item 10674Synopsis: import [-options] repository vendortag releasetag@dots{} 10675@item 10676Requires: Repository, source distribution directory. 10677@item 10678Changes: repository. 10679@end itemize 10680 10681Use @code{import} to incorporate an entire source 10682distribution from an outside source (e.g., a source 10683vendor) into your source repository directory. You can 10684use this command both for initial creation of a 10685repository, and for wholesale updates to the module 10686from the outside source. @xref{Tracking sources}, for 10687a discussion on this subject. 10688 10689The @var{repository} argument gives a directory name 10690(or a path to a directory) under the @sc{cvs} root directory 10691for repositories; if the directory did not exist, 10692import creates it. 10693 10694When you use import for updates to source that has been 10695modified in your source repository (since a prior 10696import), it will notify you of any files that conflict 10697in the two branches of development; use @samp{checkout 10698-j} to reconcile the differences, as import instructs 10699you to do. 10700 10701If @sc{cvs} decides a file should be ignored 10702(@pxref{cvsignore}), it does not import it and prints 10703@samp{I } followed by the filename (@pxref{import output}, for a 10704complete description of the output). 10705 10706If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 10707any file whose names match the specifications in that 10708file will be treated as packages and the appropriate 10709filtering will be performed on the file/directory 10710before being imported. @xref{Wrappers}. 10711 10712The outside source is saved in a first-level 10713branch, by default 1.1.1. Updates are leaves of this 10714branch; for example, files from the first imported 10715collection of source will be revision 1.1.1.1, then 10716files from the first imported update will be revision 107171.1.1.2, and so on. 10718 10719At least three arguments are required. 10720@var{repository} is needed to identify the collection 10721of source. @var{vendortag} is a tag for the entire 10722branch (e.g., for 1.1.1). You must also specify at 10723least one @var{releasetag} to uniquely identify the files at 10724the leaves created each time you execute @code{import}. The 10725@var{releasetag} should be new, not previously existing in the 10726repository file, and uniquely identify the imported release, 10727 10728@c I'm not completely sure this belongs here. But 10729@c we need to say it _somewhere_ reasonably obvious; it 10730@c is a common misconception among people first learning CVS 10731Note that @code{import} does @emph{not} change the 10732directory in which you invoke it. In particular, it 10733does not set up that directory as a @sc{cvs} working 10734directory; if you want to work with the sources import 10735them first and then check them out into a different 10736directory (@pxref{Getting the source}). 10737 10738@menu 10739* import options:: import options 10740* import output:: import output 10741* import examples:: import examples 10742@end menu 10743 10744@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10745@node import options 10746@appendixsubsec import options 10747 10748This standard option is supported by @code{import} 10749(@pxref{Common options}, for a complete description): 10750 10751@table @code 10752@item -m @var{message} 10753Use @var{message} as log information, instead of 10754invoking an editor. 10755@end table 10756 10757There are the following additional special options. 10758 10759@table @code 10760@item -b @var{branch} 10761See @ref{Multiple vendor branches}. 10762 10763@item -k @var{subst} 10764Indicate the keyword expansion mode desired. This 10765setting will apply to all files created during the 10766import, but not to any files that previously existed in 10767the repository. See @ref{Substitution modes}, for a 10768list of valid @samp{-k} settings. 10769 10770@item -I @var{name} 10771Specify file names that should be ignored during 10772import. You can use this option repeatedly. To avoid 10773ignoring any files at all (even those ignored by 10774default), specify `-I !'. 10775 10776@var{name} can be a file name pattern of the same type 10777that you can specify in the @file{.cvsignore} file. 10778@xref{cvsignore}. 10779@c -- Is this really true? 10780 10781@item -W @var{spec} 10782Specify file names that should be filtered during 10783import. You can use this option repeatedly. 10784 10785@var{spec} can be a file name pattern of the same type 10786that you can specify in the @file{.cvswrappers} 10787file. @xref{Wrappers}. 10788 10789@item -X 10790Modify the algorithm used by @sc{cvs} when importing new files 10791so that new files do not immediately appear on the main trunk. 10792 10793Specifically, this flag causes @sc{cvs} to mark new files as 10794if they were deleted on the main trunk, by taking the following 10795steps for each file in addition to those normally taken on import: 10796creating a new revision on the main trunk indicating that 10797the new file is @code{dead}, resetting the new file's default branch, 10798and placing the file in the Attic (@pxref{Attic}) directory. 10799 10800Use of this option can be forced on a repository-wide basis 10801by setting the @samp{ImportNewFilesToVendorBranchOnly} option in 10802CVSROOT/config (@pxref{config}). 10803@end table 10804 10805@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10806@node import output 10807@appendixsubsec import output 10808 10809@code{import} keeps you informed of its progress by printing a line 10810for each file, preceded by one character indicating the status of the file: 10811 10812@table @code 10813@item U @var{file} 10814The file already exists in the repository and has not been locally 10815modified; a new revision has been created (if necessary). 10816 10817@item N @var{file} 10818The file is a new file which has been added to the repository. 10819 10820@item C @var{file} 10821The file already exists in the repository but has been locally modified; 10822you will have to merge the changes. 10823 10824@item I @var{file} 10825The file is being ignored (@pxref{cvsignore}). 10826 10827@cindex Symbolic link, importing 10828@cindex Link, symbolic, importing 10829@c FIXME: also (somewhere else) probably 10830@c should be documenting what happens if you "cvs add" 10831@c a symbolic link. Also maybe what happens if 10832@c you manually create symbolic links within the 10833@c repository (? - not sure why we'd want to suggest 10834@c doing that). 10835@item L @var{file} 10836The file is a symbolic link; @code{cvs import} ignores symbolic links. 10837People periodically suggest that this behavior should 10838be changed, but if there is a consensus on what it 10839should be changed to, it is not apparent. 10840(Various options in the @file{modules} file can be used 10841to recreate symbolic links on checkout, update, etc.; 10842@pxref{modules}.) 10843@end table 10844 10845@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10846@node import examples 10847@appendixsubsec import examples 10848 10849See @ref{Tracking sources}, and @ref{From files}. 10850 10851@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10852@node init 10853@appendixsec init---Initialize a repository 10854@cindex init (subcommand) 10855 10856@itemize @bullet 10857@item 10858Synopsis: init 10859@item 10860Requires: working directory. 10861@item 10862Changes: repository, working directory. 10863@end itemize 10864 10865The @code{init} command initializes a repository by adding the 10866@file{CVSROOT} subdirectory and some default control files. You must 10867use this command or initialize the repository in some other way before 10868you can use it. Specify the root of the repository with the general 10869@code{-d} option. This will set up an empty repository in the 10870@sc{cvs} root specified in the usual way (@pxref{Repository}). 10871For example, 10872 10873@code{cvs init} is careful to never overwrite any 10874existing files in the repository, so no harm is done if 10875you run @code{cvs init} on an already set-up 10876repository. Note you may need to be a member of the 10877group @code{cvsadmin} to do this. 10878 10879Note @code{init} will enable history logging; if you don't want that, 10880remove the history file after running @code{init}. @xref{history file}. 10881 10882@menu 10883* init examples: init examples 10884@end menu 10885 10886@node init examples 10887@appendixsubsec init examples 10888 10889@example 10890$ cvs -d /usr/local/cvsroot init 10891@end example 10892 10893@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10894@node log 10895@appendixsec log---Print out log information for files 10896@cindex log (subcommand) 10897 10898@itemize @bullet 10899@item 10900Synopsis: log [options] [files@dots{}] 10901@item 10902Requires: repository, working directory. 10903@item 10904Changes: nothing. 10905@end itemize 10906 10907Display log information for files. @code{log} used to 10908call the @sc{rcs} utility @code{rlog}. Although this 10909is no longer true in the current sources, this history 10910determines the format of the output and the options, 10911which are not quite in the style of the other @sc{cvs} 10912commands. 10913 10914@cindex Timezone, in output 10915@cindex Zone, time, in output 10916The output includes the location of the @sc{rcs} file, 10917the @dfn{head} revision (the latest revision on the 10918trunk), all symbolic names (tags) and some other 10919things. For each revision, the revision number, the 10920date, the author, the number of lines added/deleted, the commitid 10921and the log message are printed. All dates are displayed 10922in local time at the client. This is typically specified in 10923the @code{$TZ} environment variable, which can be set to 10924govern how @code{log} displays dates. 10925 10926@strong{Note: @code{log} uses @samp{-R} in a way that conflicts 10927with the normal use inside @sc{cvs} (@pxref{Common options}).} 10928 10929@menu 10930* log options:: log options 10931* log examples:: log examples 10932@end menu 10933 10934@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10935@node log options 10936@appendixsubsec log options 10937 10938By default, @code{log} prints all information that is 10939available. All other options restrict the output. Note that the revision 10940selection options (@code{-d}, @code{-r}, @code{-s}, and @code{-w}) have no 10941effect, other than possibly causing a search for files in Attic directories, 10942when used in conjunction with the options that restrict the output to only 10943@code{log} header fields (@code{-b}, @code{-h}, @code{-R}, and @code{-t}) 10944unless the @code{-S} option is also specified. 10945 10946@table @code 10947@item -b 10948Print information about the revisions on the default 10949branch, normally the highest branch on the trunk. 10950 10951@item -d @var{dates} 10952Print information about revisions with a checkin 10953date/time in the range given by the 10954semicolon-separated list of dates. The date formats 10955accepted are those accepted by the @samp{-D} option to 10956many other @sc{cvs} commands (@pxref{Common options}). 10957Dates can be combined into ranges as follows: 10958 10959@c Should we be thinking about accepting ISO8601 10960@c ranges? For example "1972-09-10/1972-09-12". 10961@table @code 10962@item @var{d1}<@var{d2} 10963@itemx @var{d2}>@var{d1} 10964Select the revisions that were deposited between 10965@var{d1} and @var{d2}. 10966 10967@item <@var{d} 10968@itemx @var{d}> 10969Select all revisions dated @var{d} or earlier. 10970 10971@item @var{d}< 10972@itemx >@var{d} 10973Select all revisions dated @var{d} or later. 10974 10975@item @var{d} 10976Select the single, latest revision dated @var{d} or 10977earlier. 10978@end table 10979 10980The @samp{>} or @samp{<} characters may be followed by 10981@samp{=} to indicate an inclusive range rather than an 10982exclusive one. 10983 10984Note that the separator is a semicolon (;). 10985 10986@item -h 10987Print only the name of the @sc{rcs} file, name 10988of the file in the working directory, head, 10989default branch, access list, locks, symbolic names, and 10990suffix. 10991 10992@item -l 10993Local; run only in current working directory. (Default 10994is to run recursively). 10995 10996@item -N 10997Do not print the list of tags for this file. This 10998option can be very useful when your site uses a lot of 10999tags, so rather than "more"'ing over 3 pages of tag 11000information, the log information is presented without 11001tags at all. 11002 11003@item -R 11004Print only the name of the @sc{rcs} file. 11005 11006@c Note that using a bare revision (in addition to not 11007@c being explicitly documented here) is potentially 11008@c confusing; it shows the log message to get from the 11009@c previous revision to that revision. "-r1.3 -r1.6" 11010@c (equivalent to "-r1.3,1.6") is even worse; it 11011@c prints the messages to get from 1.2 to 1.3 and 1.5 11012@c to 1.6. By analogy with "cvs diff", users might 11013@c expect that it is more like specifying a range. 11014@c It is not 100% clear to me how much of this should 11015@c be documented (for example, multiple -r options 11016@c perhaps could/should be deprecated given the false 11017@c analogy with "cvs diff"). 11018@c In general, this section should be rewritten to talk 11019@c about messages to get from revision rev1 to rev2, 11020@c rather than messages for revision rev2 (that is, the 11021@c messages are associated with a change not a static 11022@c revision and failing to make this distinction causes 11023@c much confusion). 11024@item -r@var{revisions} 11025Print information about revisions given in the 11026comma-separated list @var{revisions} of revisions and 11027ranges. The following table explains the available 11028range formats: 11029 11030@table @code 11031@item @var{rev1}:@var{rev2} 11032Revisions @var{rev1} to @var{rev2} (which must be on 11033the same branch). 11034 11035@item @var{rev1}::@var{rev2} 11036The same, but excluding @var{rev1}. 11037 11038@item :@var{rev} 11039@itemx ::@var{rev} 11040Revisions from the beginning of the branch up to 11041and including @var{rev}. 11042 11043@item @var{rev}: 11044Revisions starting with @var{rev} to the end of the 11045branch containing @var{rev}. 11046 11047@item @var{rev}:: 11048Revisions starting just after @var{rev} to the end of the 11049branch containing @var{rev}. 11050 11051@item @var{branch} 11052An argument that is a branch means all revisions on 11053that branch. 11054 11055@item @var{branch1}:@var{branch2} 11056@itemx @var{branch1}::@var{branch2} 11057A range of branches means all revisions 11058on the branches in that range. 11059 11060@item @var{branch}. 11061The latest revision in @var{branch}. 11062@end table 11063 11064A bare @samp{-r} with no revisions means the latest 11065revision on the default branch, normally the trunk. 11066There can be no space between the @samp{-r} option and 11067its argument. 11068 11069@item -S 11070Suppress the header if no revisions are selected. 11071 11072@item -s @var{states} 11073Print information about revisions whose state 11074attributes match one of the states given in the 11075comma-separated list @var{states}. Individual states may 11076be any text string, though @sc{cvs} commonly only uses two 11077states, @samp{Exp} and @samp{dead}. See @ref{admin options} 11078for more information. 11079 11080@item -t 11081Print the same as @samp{-h}, plus the descriptive text. 11082 11083@item -w@var{logins} 11084Print information about revisions checked in by users 11085with login names appearing in the comma-separated list 11086@var{logins}. If @var{logins} is omitted, the user's 11087login is assumed. There can be no space between the 11088@samp{-w} option and its argument. 11089@end table 11090 11091@code{log} prints the intersection of the revisions 11092selected with the options @samp{-d}, @samp{-s}, and 11093@samp{-w}, intersected with the union of the revisions 11094selected by @samp{-b} and @samp{-r}. 11095 11096@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11097@node log examples 11098@appendixsubsec log examples 11099 11100@cindex Timezone, in output 11101@cindex Zone, time, in output 11102Since @code{log} shows dates in local time, 11103you might want to see them in Coordinated Universal Time (UTC) or 11104some other timezone. 11105To do this you can set your @code{$TZ} environment 11106variable before invoking @sc{cvs}: 11107 11108@example 11109$ TZ=UTC cvs log foo.c 11110$ TZ=EST cvs log bar.c 11111@end example 11112 11113(If you are using a @code{csh}-style shell, like @code{tcsh}, 11114you would need to prefix the examples above with @code{env}.) 11115 11116@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11117@node ls & rls 11118@appendixsec ls & rls 11119@cindex ls (subcommand) 11120@cindex rls (subcommand) 11121 11122@itemize @bullet 11123@item 11124ls [-e | -l] [-RP] [-r tag[:date]] [-D date] [path@dots{}] 11125@item 11126Requires: repository for @code{rls}, repository & working directory for 11127@code{ls}. 11128@item 11129Changes: nothing. 11130@item 11131Synonym: @code{dir} & @code{list} are synonyms for @code{ls} and @code{rdir} 11132& @code{rlist} are synonyms for @code{rls}. 11133@end itemize 11134 11135The @code{ls} and @code{rls} commands are used to list 11136files and directories in the repository. 11137 11138By default @code{ls} lists the files and directories 11139that belong in your working directory, what would be 11140there after an @code{update}. 11141 11142By default @code{rls} lists the files and directories 11143on the tip of the trunk in the topmost directory of the 11144repository. 11145 11146Both commands accept an optional list of file and 11147directory names, relative to the working directory for 11148@code{ls} and the topmost directory of the repository 11149for @code{rls}. Neither is recursive by default. 11150 11151@menu 11152* ls & rls options:: ls & rls options 11153* rls examples: rls examples 11154@end menu 11155 11156@node ls & rls options 11157@appendixsubsec ls & rls options 11158 11159These standard options are supported by @code{ls} & @code{rls}: 11160 11161@table @code 11162@item -d 11163Show dead revisions (with tag when specified). 11164 11165@item -e 11166Display in CVS/Entries format. This format is meant to remain easily parsable 11167by automation. 11168 11169@item -l 11170Display all details. 11171 11172@item -P 11173Don't list contents of empty directories when recursing. 11174 11175@item -R 11176List recursively. 11177 11178@item -r @var{tag}[:@var{date}] 11179Show files specified by @var{tag} or, when @var{date} is specified 11180and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11181existed on @var{date}. See @ref{Common options}. 11182 11183@item -D @var{date} 11184Show files from date. 11185@end table 11186 11187@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11188@node rls examples 11189@appendixsubsec rls examples 11190 11191@example 11192$ cvs rls 11193cvs rls: Listing module: `.' 11194CVSROOT 11195first-dir 11196@end example 11197 11198@example 11199$ cvs rls CVSROOT 11200cvs rls: Listing module: `CVSROOT' 11201checkoutlist 11202commitinfo 11203config 11204cvswrappers 11205loginfo 11206modules 11207notify 11208rcsinfo 11209taginfo 11210verifymsg 11211 11212@end example 11213 11214@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11215@node rdiff 11216@appendixsec rdiff---'patch' format diffs between releases 11217@cindex rdiff (subcommand) 11218 11219@itemize @bullet 11220@item 11221rdiff [-flags] [-V vn] (-r tag1[:date1] | -D date1) [-r tag2[:date2] | -D date2] modules@dots{} 11222@item 11223Requires: repository. 11224@item 11225Changes: nothing. 11226@item 11227Synonym: patch 11228@end itemize 11229 11230Builds a Larry Wall format patch(1) file between two 11231releases, that can be fed directly into the @code{patch} 11232program to bring an old release up-to-date with the new 11233release. (This is one of the few @sc{cvs} commands that 11234operates directly from the repository, and doesn't 11235require a prior checkout.) The diff output is sent to 11236the standard output device. 11237 11238You can specify (using the standard @samp{-r} and 11239@samp{-D} options) any combination of one or two 11240revisions or dates. If only one revision or date is 11241specified, the patch file reflects differences between 11242that revision or date and the current head revisions in 11243the @sc{rcs} file. 11244 11245Note that if the software release affected is contained 11246in more than one directory, then it may be necessary to 11247specify the @samp{-p} option to the @code{patch} command when 11248patching the old sources, so that @code{patch} is able to find 11249the files that are located in other directories. 11250 11251@menu 11252* rdiff options:: rdiff options 11253* rdiff examples:: rdiff examples 11254@end menu 11255 11256@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11257@node rdiff options 11258@appendixsubsec rdiff options 11259 11260These standard options are supported by @code{rdiff} 11261(@pxref{Common options}, for a complete description of 11262them): 11263 11264@table @code 11265@item -D @var{date} 11266Use the most recent revision no later than @var{date}. 11267 11268@item -f 11269If no matching revision is found, retrieve the most 11270recent revision (instead of ignoring the file). 11271 11272@item -k @var{kflag} 11273Process keywords according to @var{kflag}. See 11274@ref{Keyword substitution}. 11275 11276@item -l 11277Local; don't descend subdirectories. 11278 11279@item -p 11280Show which C function each change is in. 11281 11282@item -R 11283Examine directories recursively. This option is on by default. 11284 11285@item -r @var{tag} 11286Use the revision specified by @var{tag}, or when @var{date} is specified 11287and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11288existed on @var{date}. See @ref{Common options}. 11289@end table 11290 11291In addition to the above, these options are available: 11292 11293@table @code 11294@item -c 11295Use the context diff format. This is the default format. 11296 11297@item -s 11298Create a summary change report instead of a patch. The 11299summary includes information about files that were 11300changed or added between the releases. It is sent to 11301the standard output device. This is useful for finding 11302out, for example, which files have changed between two 11303dates or revisions. 11304 11305@item -t 11306A diff of the top two revisions is sent to the standard 11307output device. This is most useful for seeing what the 11308last change to a file was. 11309 11310@item -u 11311Use the unidiff format for the context diffs. 11312Remember that old versions 11313of the @code{patch} program can't handle the unidiff 11314format, so if you plan to post this patch to the net 11315you should probably not use @samp{-u}. 11316 11317@item -V @var{vn} 11318Expand keywords according to the rules current in 11319@sc{rcs} version @var{vn} (the expansion format changed with 11320@sc{rcs} version 5). Note that this option is no 11321longer accepted. @sc{cvs} will always expand keywords the 11322way that @sc{rcs} version 5 does. 11323@end table 11324 11325@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11326@node rdiff examples 11327@appendixsubsec rdiff examples 11328 11329Suppose you receive mail from @t{foo@@example.net} asking for an 11330update from release 1.2 to 1.4 of the tc compiler. You 11331have no such patches on hand, but with @sc{cvs} that can 11332easily be fixed with a command such as this: 11333 11334@example 11335$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 11336$$ Mail -s 'The patches you asked for' foo@@example.net 11337@end example 11338 11339Suppose you have made release 1.3, and forked a branch 11340called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1} 11341corresponds to release 1.3.1, which was made some time 11342ago. Now, you want to see how much development has been 11343done on the branch. This command can be used: 11344 11345@example 11346$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 11347cvs rdiff: Diffing module-name 11348File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 11349File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 11350File bar.h,v changed from revision 1.29.2.1 to 1.2 11351@end example 11352 11353@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11354@node release 11355@appendixsec release---Indicate that a Module is no longer in use 11356@cindex release (subcommand) 11357 11358@itemize @bullet 11359@item 11360release [-d] directories@dots{} 11361@item 11362Requires: Working directory. 11363@item 11364Changes: Working directory, history log. 11365@end itemize 11366 11367This command is meant to safely cancel the effect of 11368@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it 11369isn't strictly necessary to use this command. You can 11370always simply delete your working directory, if you 11371like; but you risk losing changes you may have 11372forgotten, and you leave no trace in the @sc{cvs} history 11373file (@pxref{history file}) that you've abandoned your 11374checkout. 11375 11376Use @samp{cvs release} to avoid these problems. This 11377command checks that no uncommitted changes are 11378present; that you are executing it from immediately 11379above a @sc{cvs} working directory; and that the repository 11380recorded for your files is the same as the repository 11381defined in the module database. 11382 11383If all these conditions are true, @samp{cvs release} 11384leaves a record of its execution (attesting to your 11385intentionally abandoning your checkout) in the @sc{cvs} 11386history log. 11387 11388@menu 11389* release options:: release options 11390* release output:: release output 11391* release examples:: release examples 11392@end menu 11393 11394@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11395@node release options 11396@appendixsubsec release options 11397 11398The @code{release} command supports one command option: 11399 11400@table @code 11401@item -d 11402Delete your working copy of the file if the release 11403succeeds. If this flag is not given your files will 11404remain in your working directory. 11405 11406@strong{WARNING: The @code{release} command deletes 11407all directories and files recursively. This 11408has the very serious side-effect that any directory 11409that you have created inside your checked-out sources, 11410and not added to the repository (using the @code{add} 11411command; @pxref{Adding files}) will be silently deleted---even 11412if it is non-empty!} 11413@end table 11414 11415@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11416@node release output 11417@appendixsubsec release output 11418 11419Before @code{release} releases your sources it will 11420print a one-line message for any file that is not 11421up-to-date. 11422 11423@table @code 11424@item U @var{file} 11425@itemx P @var{file} 11426There exists a newer revision of this file in the 11427repository, and you have not modified your local copy 11428of the file (@samp{U} and @samp{P} mean the same thing). 11429 11430@item A @var{file} 11431The file has been added to your private copy of the 11432sources, but has not yet been committed to the 11433repository. If you delete your copy of the sources 11434this file will be lost. 11435 11436@item R @var{file} 11437The file has been removed from your private copy of the 11438sources, but has not yet been removed from the 11439repository, since you have not yet committed the 11440removal. @xref{commit}. 11441 11442@item M @var{file} 11443The file is modified in your working directory. There 11444might also be a newer revision inside the repository. 11445 11446@item ? @var{file} 11447@var{file} is in your working directory, but does not 11448correspond to anything in the source repository, and is 11449not in the list of files for @sc{cvs} to ignore (see the 11450description of the @samp{-I} option, and 11451@pxref{cvsignore}). If you remove your working 11452sources, this file will be lost. 11453@end table 11454 11455@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11456@node release examples 11457@appendixsubsec release examples 11458 11459Release the @file{tc} directory, and delete your local working copy 11460of the files. 11461 11462@example 11463$ cd .. # @r{You must stand immediately above the} 11464 # @r{sources when you issue @samp{cvs release}.} 11465$ cvs release -d tc 11466You have [0] altered files in this repository. 11467Are you sure you want to release (and delete) directory `tc': y 11468$ 11469@end example 11470 11471@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11472@node remove 11473@appendixsec remove---Remove files from active use 11474@cindex remove (subcommand) 11475 11476@itemize @bullet 11477@item 11478Synopsis: remove [-flR] [files...] 11479@item 11480Requires: repository, working directory. 11481@item 11482Changes: working directory. 11483@end itemize 11484 11485The @code{remove} command is used to remove unwanted 11486files from active use. The user normally deletes the 11487files from the working directory prior to invocation 11488of the @code{remove} command. Only the working 11489directory is updated. Changes to the repository are 11490not made until the @code{commit} command is run. 11491 11492The @code{remove} command does not delete files from 11493from the repository. @sc{cvs} keeps all historical 11494data in the repository so that it is possible to 11495reconstruct previous states of the projects under 11496revision control. 11497 11498To undo @sc{cvs} @code{remove} or to resurrect files 11499that were previously removed, @xref{add}. 11500 11501@menu 11502* remove options:: remove options 11503* remove examples:: remove examples 11504@end menu 11505 11506@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11507@node remove options 11508@appendixsubsec remove options 11509 11510These standard options are supported by @code{remove} 11511(@pxref{Common options} for a complete description of 11512them): 11513 11514@table @code 11515@item -l 11516Local; run only in current working directory. See @ref{Recursive behavior}. 11517 11518@item -R 11519Process directories recursively. See @ref{Recursive behavior}. 11520 11521@end table 11522 11523In addition, these options are also supported: 11524 11525@table @code 11526@item -f 11527Note that this is not the standard behavior of 11528the @samp{-f} option as defined in @ref{Common options}. 11529 11530Delete files before removing them. 11531 11532Entire directory hierarchies are easily removed 11533using @samp{-f}, but take note that it is not as 11534easy to resurrect directory hierarchies as it is 11535to remove them. 11536 11537@end table 11538 11539@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11540@node remove examples 11541@appendixsubsec remove examples 11542 11543@appendixsubsubsec Removing a file 11544 11545@example 11546$ cvs remove remove.me 11547cvs remove: file `remove.me' still in working directory 11548cvs remove: 1 file exists; remove it first 11549$ rm -f remove.me 11550$ cvs remove remove.me 11551cvs remove: scheduling `remove.me' for removal 11552cvs remove: use 'cvs commit' to remove this file permanently 11553 11554$ ls remove.it 11555remove.it 11556$ cvs remove -f remove.it 11557cvs remove: scheduling `remove.it' for removal 11558cvs remove: use 'cvs commit' to remove this file permanently 11559@end example 11560 11561@appendixsubsubsec Removing entire directories 11562@example 11563$ tree -d a 11564a 11565|-- CVS 11566`-- b 11567 `-- CVS 11568 115693 directories 11570$ cvs remove -f a 11571cvs remove: Removing a 11572cvs remove: Removing a/b 11573cvs remove: scheduling `a/b/c' for removal 11574cvs remove: use 'cvs commit' to remove this file permanently 11575@end example 11576 11577@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11578@node server & pserver 11579@appendixsec server & pserver---Act as a server for a client on stdin/stdout 11580@cindex pserver (subcommand) 11581@cindex server (subcommand) 11582 11583@itemize @bullet 11584@item 11585pserver [-c path] 11586 11587server [-c path] 11588@item 11589Requires: repository, client conversation on stdin/stdout 11590@item 11591Changes: Repository or, indirectly, client working directory. 11592@end itemize 11593 11594The @sc{cvs} @code{server} and @code{pserver} commands are used to provide 11595repository access to remote clients and expect a client conversation on 11596stdin & stdout. Typically these commands are launched from @code{inetd} or 11597via @code{ssh} (@pxref{Remote repositories}). 11598 11599@code{server} expects that the client has already been authenticated somehow, 11600typically via @sc{ssh}, and @code{pserver} attempts to authenticate the client 11601itself. 11602 11603Only one option is available with the @code{server} and @code{pserver} 11604commands: 11605 11606@cindex configuration file 11607@table @code 11608@item -c path 11609Load configuration from @var{path} rather than the default location 11610@file{$CVSROOT/CVSROOT/config} (@pxref{config}). @var{path} must be 11611@file{/etc/cvs.conf} or prefixed by @file{/etc/cvs/}. This option is 11612supported beginning with @sc{cvs} release 1.12.13. 11613@end table 11614 11615@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11616@node update 11617@appendixsec update---Bring work tree in sync with repository 11618@cindex update (subcommand) 11619 11620@itemize @bullet 11621@item 11622update [-ACdflPpRt] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag[:date] | -D date] [-W spec] files@dots{} 11623@item 11624Requires: repository, working directory. 11625@item 11626Changes: working directory. 11627@end itemize 11628 11629After you've run @code{checkout} to create your private copy 11630of source from the common repository, other developers 11631will continue changing the central source. From time 11632to time, when it is convenient in your development 11633process, you can use the @code{update} command from 11634within your working directory to reconcile your work 11635with any revisions applied to the source repository 11636since your last checkout or update. Without the @code{-C} 11637option, @code{update} will also merge any differences 11638between the local copy of files and their base revisions 11639into any destination revisions specified with @code{-r}, 11640@code{-D}, or @code{-A}. 11641 11642@menu 11643* update options:: update options 11644* update output:: update output 11645@end menu 11646 11647@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11648@node update options 11649@appendixsubsec update options 11650 11651These standard options are available with @code{update} 11652(@pxref{Common options}, for a complete description of 11653them): 11654 11655@table @code 11656@item -D date 11657Use the most recent revision no later than @var{date}. 11658This option is sticky, and implies @samp{-P}. 11659See @ref{Sticky tags}, for more information on sticky tags/dates. 11660 11661@item -f 11662Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision 11663is found, retrieve the most recent revision (instead of ignoring the file). 11664 11665@item -k @var{kflag} 11666Process keywords according to @var{kflag}. See 11667@ref{Keyword substitution}. 11668This option is sticky; future updates of 11669this file in this working directory will use the same 11670@var{kflag}. The @code{status} command can be viewed 11671to see the sticky options. See @ref{Invoking CVS}, for 11672more information on the @code{status} command. 11673 11674@item -l 11675Local; run only in current working directory. @xref{Recursive behavior}. 11676 11677@item -P 11678Prune empty directories. See @ref{Moving directories}. 11679 11680@item -p 11681Pipe files to the standard output. 11682 11683@item -R 11684Update directories recursively (default). @xref{Recursive 11685behavior}. 11686 11687@item -r @var{tag}[:@var{date}] 11688Retrieve the revisions specified by @var{tag} or, when @var{date} is specified 11689and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11690existed on @var{date}. This option is sticky, and implies @samp{-P}. 11691See @ref{Sticky tags}, for more information on sticky tags/dates. Also 11692see @ref{Common options}. 11693 11694@item -t 11695Preserve source timestamps. Unlike @code{checkout}, where files are created 11696using the original timestamp of the file in the repository, @code{update} 11697updates files using the current time of the machine. This is convenient 11698because updated files appear newer than any other files on the system so 11699@code{make(1)} knows that their corresponding built artifacts are out of date 11700and they will get rebuilt. The @samp{-t} flag instead preserves the timestamps 11701of the original repository files, behaving exactly like @code{checkout}. 11702This is useful for maintaining a tree in the original checked-out state. 11703@end table 11704 11705@need 800 11706These special options are also available with 11707@code{update}. 11708 11709@table @code 11710@item -A 11711Reset any sticky tags, dates, or @samp{-k} options. 11712See @ref{Sticky tags}, for more information on sticky tags/dates. 11713 11714@item -C 11715Overwrite locally modified files with clean copies from 11716the repository (the modified file is saved in 11717@file{.#@var{file}.@var{revision}}, however). 11718 11719@item -d 11720Create any directories that exist in the repository if 11721they're missing from the working directory. Normally, 11722@code{update} acts only on directories and files that 11723were already enrolled in your working directory. 11724 11725This is useful for updating directories that were 11726created in the repository since the initial checkout; 11727but it has an unfortunate side effect. If you 11728deliberately avoided certain directories in the 11729repository when you created your working directory 11730(either through use of a module name or by listing 11731explicitly the files and directories you wanted on the 11732command line), then updating with @samp{-d} will create 11733those directories, which may not be what you want. 11734 11735@item -I @var{name} 11736Ignore files whose names match @var{name} (in your 11737working directory) during the update. You can specify 11738@samp{-I} more than once on the command line to specify 11739several files to ignore. Use @samp{-I !} to avoid 11740ignoring any files at all. @xref{cvsignore}, for other 11741ways to make @sc{cvs} ignore some files. 11742 11743@item -W@var{spec} 11744Specify file names that should be filtered during 11745update. You can use this option repeatedly. 11746 11747@var{spec} can be a file name pattern of the same type 11748that you can specify in the @file{.cvswrappers} 11749file. @xref{Wrappers}. 11750 11751@item -j@var{revision} 11752With two @samp{-j} options, merge changes from the 11753revision specified with the first @samp{-j} option to 11754the revision specified with the second @samp{j} option, 11755into the working directory. 11756 11757With one @samp{-j} option, merge changes from the 11758ancestor revision to the revision specified with the 11759@samp{-j} option, into the working directory. The 11760ancestor revision is the common ancestor of the 11761revision which the working directory is based on, and 11762the revision specified in the @samp{-j} option. 11763 11764Note that using a single @samp{-j @var{tagname}} option rather than 11765@samp{-j @var{branchname}} to merge changes from a branch will 11766often not remove files which were removed on the branch. 11767@xref{Merging adds and removals}, for more. 11768 11769In addition, each @samp{-j} option can contain an optional 11770date specification which, when used with branches, can 11771limit the chosen revision to one within a specific 11772date. An optional date is specified by adding a colon 11773(:) to the tag: 11774@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 11775 11776@xref{Branching and merging}. 11777 11778@end table 11779 11780@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11781@node update output 11782@appendixsubsec update output 11783 11784@code{update} and @code{checkout} keep you informed of 11785their progress by printing a line for each file, preceded 11786by one character indicating the status of the file: 11787 11788@table @code 11789@item U @var{file} 11790The file was brought up to date with respect to the 11791repository. This is done for any file that exists in 11792the repository but not in your working directory, and for files 11793that you haven't changed but are not the most recent 11794versions available in the repository. 11795 11796@item P @var{file} 11797Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 11798file. This accomplishes the same thing as @samp{U} using less bandwidth. 11799 11800@item A @var{file} 11801The file has been added to your private copy of the 11802sources, and will be added to the source repository 11803when you run @code{commit} on the file. This is a 11804reminder to you that the file needs to be committed. 11805 11806@item R @var{file} 11807The file has been removed from your private copy of the 11808sources, and will be removed from the source repository 11809when you run @code{commit} on the file. This is a 11810reminder to you that the file needs to be committed. 11811 11812@item M @var{file} 11813The file is modified in your working directory. 11814 11815@samp{M} can indicate one of two states for a file 11816you're working on: either there were no modifications 11817to the same file in the repository, so that your file 11818remains as you last saw it; or there were modifications 11819in the repository as well as in your copy, but they 11820were merged successfully, without conflict, in your 11821working directory. 11822 11823@sc{cvs} will print some messages if it merges your work, 11824and a backup copy of your working file (as it looked 11825before you ran @code{update}) will be made. The exact 11826name of that file is printed while @code{update} runs. 11827 11828@item C @var{file} 11829@cindex .# files 11830@cindex __ files (VMS) 11831A conflict was detected while trying to merge your 11832changes to @var{file} with changes from the source 11833repository. @var{file} (the copy in your working 11834directory) is now the result of attempting to merge 11835the two revisions; an unmodified copy of your file 11836is also in your working directory, with the name 11837@file{.#@var{file}.@var{revision}} where @var{revision} 11838is the revision that your modified file started 11839from. Resolve the conflict as described in 11840@ref{Conflicts example}. 11841@c "some systems" as in out-of-the-box OSes? Not as 11842@c far as I know. We need to advise sysadmins as well 11843@c as users how to set up this kind of purge, if that is 11844@c what they want. 11845@c We also might want to think about cleaner solutions, 11846@c like having CVS remove the .# file once the conflict 11847@c has been resolved or something like that. 11848(Note that some systems automatically purge 11849files that begin with @file{.#} if they have not been 11850accessed for a few days. If you intend to keep a copy 11851of your original file, it is a very good idea to rename 11852it.) Under @sc{vms}, the file name starts with 11853@file{__} rather than @file{.#}. 11854 11855@item ? @var{file} 11856@var{file} is in your working directory, but does not 11857correspond to anything in the source repository, and is 11858not in the list of files for @sc{cvs} to ignore (see the 11859description of the @samp{-I} option, and 11860@pxref{cvsignore}). 11861@end table 11862 11863@c ----- END MAN 1 ----- 11864@c --------------------------------------------------------------------- 11865@node Invoking CVS 11866@appendix Quick reference to CVS commands 11867@cindex Command reference 11868@cindex Reference, commands 11869@cindex Invoking CVS 11870 11871This appendix describes how to invoke @sc{cvs}, with 11872references to where each command or feature is 11873described in detail. For other references run the 11874@code{cvs --help} command, or see @ref{Index}. 11875 11876A @sc{cvs} command looks like: 11877 11878@example 11879cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 11880@end example 11881 11882Global options: 11883 11884@table @code 11885@item --allow-root=@var{rootdir} 11886Specify legal @sc{cvsroot} directory (server only) (not 11887in @sc{cvs} 1.9 and older). See @ref{Password 11888authentication server}. 11889 11890@item -a 11891Authenticate all communication (client only) (not in @sc{cvs} 118921.9 and older). See @ref{Global options}. 11893 11894@item -b 11895Specify RCS location (@sc{cvs} 1.9 and older). See 11896@ref{Global options}. 11897 11898@item -d @var{root} 11899Specify the @sc{cvsroot}. See @ref{Repository}. 11900 11901@item -e @var{editor} 11902Edit messages with @var{editor}. See @ref{Committing 11903your changes}. 11904 11905@item -f 11906Do not read the @file{~/.cvsrc} file. See @ref{Global 11907options}. 11908 11909@item -H 11910@itemx --help 11911Print a help message. See @ref{Global options}. 11912 11913@item -n 11914Do not change any files. See @ref{Global options}. 11915 11916@item -Q 11917Be really quiet. See @ref{Global options}. 11918 11919@item -q 11920Be somewhat quiet. See @ref{Global options}. 11921 11922@item -r 11923Make new working files read-only. See @ref{Global options}. 11924 11925@item -s @var{variable}=@var{value} 11926Set a user variable. See @ref{Variables}. 11927 11928@item -T @var{tempdir} 11929Put temporary files in @var{tempdir}. See @ref{Global 11930options}. 11931 11932@item -t 11933Trace @sc{cvs} execution. See @ref{Global options}. 11934 11935@item -v 11936@item --version 11937Display version and copyright information for @sc{cvs}. 11938 11939@item -w 11940Make new working files read-write. See @ref{Global 11941options}. 11942 11943@item -x 11944Encrypt all communication (client only). 11945See @ref{Global options}. 11946 11947@item -z @var{gzip-level} 11948@cindex Compression 11949@cindex Gzip 11950Set the compression level (client only). 11951See @ref{Global options}. 11952@end table 11953 11954Keyword expansion modes (@pxref{Substitution modes}): 11955 11956@example 11957-kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 11958-kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11959-kk $@splitrcskeyword{Id}$ 11960-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 11961-ko @i{no expansion} 11962-kb @i{no expansion, file is binary} 11963@end example 11964 11965Keywords (@pxref{Keyword list}): 11966 11967@example 11968$@splitrcskeyword{Author}: joe $ 11969$@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ 11970$@splitrcskeyword{CVSHeader}: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11971$@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11972$@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11973$@splitrcskeyword{Locker}: harry $ 11974$@splitrcskeyword{Name}: snapshot_1_14 $ 11975$@splitrcskeyword{RCSfile}: file1,v $ 11976$@splitrcskeyword{Revision}: 1.1 $ 11977$@splitrcskeyword{Source}: /home/files/file1,v $ 11978$@splitrcskeyword{State}: Exp $ 11979$@splitrcskeyword{Log}: file1,v $ 11980Revision 1.1 1993/12/09 03:30:17 joe 11981Initial revision 11982 11983@end example 11984 11985@c The idea behind this table is that we want each item 11986@c to be a sentence or two at most. Preferably a 11987@c single line. 11988@c 11989@c In some cases refs to "foo options" are just to get 11990@c this thing written quickly, not because the "foo 11991@c options" node is really the best place to point. 11992Commands, command options, and command arguments: 11993 11994@table @code 11995@c ------------------------------------------------------------ 11996@item add [@var{options}] [@var{files}@dots{}] 11997Add a new file/directory. See @ref{Adding files}. 11998 11999@table @code 12000@item -k @var{kflag} 12001Set keyword expansion. 12002 12003@item -m @var{msg} 12004Set file description. 12005@end table 12006 12007@c ------------------------------------------------------------ 12008@item admin [@var{options}] [@var{files}@dots{}] 12009Administration of history files in the repository. See 12010@ref{admin}. 12011@c This list omits those options which are not 12012@c documented as being useful with CVS. That might be 12013@c a mistake... 12014 12015@table @code 12016@item -b[@var{rev}] 12017Set default branch. See @ref{Reverting local changes}. 12018 12019@item -c@var{string} 12020Set comment leader. 12021 12022@item -k@var{subst} 12023Set keyword substitution. See @ref{Keyword 12024substitution}. 12025 12026@item -l[@var{rev}] 12027Lock revision @var{rev}, or latest revision. 12028 12029@item -m@var{rev}:@var{msg} 12030Replace the log message of revision @var{rev} with 12031@var{msg}. 12032 12033@item -o@var{range} 12034Delete revisions from the repository. See 12035@ref{admin options}. 12036 12037@item -q 12038Run quietly; do not print diagnostics. 12039 12040@item -s@var{state}[:@var{rev}] 12041Set the state. See @ref{admin options} for more information on possible 12042states. 12043 12044@c Does not work for client/server CVS 12045@item -t 12046Set file description from standard input. 12047 12048@item -t@var{file} 12049Set file description from @var{file}. 12050 12051@item -t-@var{string} 12052Set file description to @var{string}. 12053 12054@item -u[@var{rev}] 12055Unlock revision @var{rev}, or latest revision. 12056@end table 12057 12058@c ------------------------------------------------------------ 12059@item annotate [@var{options}] [@var{files}@dots{}] 12060Show last revision where each line was modified. See 12061@ref{annotate}. 12062 12063@table @code 12064@item -D @var{date} 12065Annotate the most recent revision no later than 12066@var{date}. See @ref{Common options}. 12067 12068@item -F 12069Force annotation of binary files. (Without this option, 12070binary files are skipped with a message.) 12071 12072@item -f 12073Use head revision if tag/date not found. See 12074@ref{Common options}. 12075 12076@item -l 12077Local; run only in current working directory. @xref{Recursive behavior}. 12078 12079@item -R 12080Operate recursively (default). @xref{Recursive 12081behavior}. 12082 12083@item -r @var{tag}[:@var{date}] 12084Annotate revisions specified by @var{tag} or, when @var{date} is specified 12085and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12086existed on @var{date}. See @ref{Common options}. 12087@end table 12088 12089@c ------------------------------------------------------------ 12090@item checkout [@var{options}] @var{modules}@dots{} 12091Get a copy of the sources. See @ref{checkout}. 12092 12093@table @code 12094@item -A 12095Reset any sticky tags/date/options. See @ref{Sticky 12096tags} and @ref{Keyword substitution}. 12097 12098@item -c 12099Output the module database. See @ref{checkout options}. 12100 12101@item -D @var{date} 12102Check out revisions as of @var{date} (is sticky). See 12103@ref{Common options}. 12104 12105@item -d @var{dir} 12106Check out into @var{dir}. See @ref{checkout options}. 12107 12108@item -f 12109Use head revision if tag/date not found. See 12110@ref{Common options}. 12111 12112@c Probably want to use rev1/rev2 style like for diff 12113@c -r. Here and in on-line help. 12114@item -j @var{tag}[:@var{date}] 12115Merge in the change specified by @var{tag}, or when @var{date} is specified 12116and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12117existed on @var{date}. See @ref{checkout options}. 12118 12119@item -k @var{kflag} 12120Use @var{kflag} keyword expansion. See 12121@ref{Substitution modes}. 12122 12123@item -l 12124Local; run only in current working directory. @xref{Recursive behavior}. 12125 12126@item -N 12127Don't ``shorten'' module paths if -d specified. See 12128@ref{checkout options}. 12129 12130@item -n 12131Do not run module program (if any). See @ref{checkout options}. 12132 12133@item -P 12134Prune empty directories. See @ref{Moving directories}. 12135 12136@item -p 12137Check out files to standard output (avoids 12138stickiness). See @ref{checkout options}. 12139 12140@item -R 12141Operate recursively (default). @xref{Recursive 12142behavior}. 12143 12144@item -r @var{tag}[:@var{date}] 12145Checkout the revision already tagged with @var{tag} or, when @var{date} is 12146specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12147as it existed on @var{date}. This . See @ref{Common options}. 12148 12149@item -s 12150Like -c, but include module status. See @ref{checkout options}. 12151@end table 12152 12153@c ------------------------------------------------------------ 12154@item commit [@var{options}] [@var{files}@dots{}] 12155Check changes into the repository. See @ref{commit}. 12156 12157@table @code 12158@item -c 12159Check for valid edits before committing. Requires a @sc{cvs} client and server 12160both version 1.12.10 or greater. 12161 12162@item -F @var{file} 12163Read log message from @var{file}. See @ref{commit options}. 12164 12165@item -f 12166@c What is this "disables recursion"? It is from the 12167@c on-line help; is it documented in this manual? 12168Force the file to be committed; disables recursion. 12169See @ref{commit options}. 12170 12171@item -l 12172Local; run only in current working directory. See @ref{Recursive behavior}. 12173 12174@item -m @var{msg} 12175Use @var{msg} as log message. See @ref{commit options}. 12176 12177@item -n 12178Do not run module program (if any). See @ref{commit options}. 12179 12180@item -R 12181Operate recursively (default). @xref{Recursive 12182behavior}. 12183 12184@item -r @var{rev} 12185Commit to @var{rev}. See @ref{commit options}. 12186@c FIXME: should be dragging over text from 12187@c commit options, especially if it can be cleaned up 12188@c and made concise enough. 12189@end table 12190 12191@c ------------------------------------------------------------ 12192@item diff [@var{options}] [@var{files}@dots{}] 12193Show differences between revisions. See @ref{diff}. 12194In addition to the options shown below, accepts a wide 12195variety of options to control output style, for example 12196@samp{-c} for context diffs. 12197 12198@table @code 12199@item -D @var{date1} 12200Diff revision for date against working file. See 12201@ref{diff options}. 12202 12203@item -D @var{date2} 12204Diff @var{rev1}/@var{date1} against @var{date2}. See 12205@ref{diff options}. 12206 12207@item -l 12208Local; run only in current working directory. See @ref{Recursive behavior}. 12209 12210@item -N 12211Include diffs for added and removed files. See 12212@ref{diff options}. 12213 12214@item -R 12215Operate recursively (default). @xref{Recursive 12216behavior}. 12217 12218@item -r @var{tag1}[:@var{date1}] 12219Diff the revisions specified by @var{tag1} or, when @var{date1} is specified 12220and @var{tag1} is a branch tag, the version from the branch @var{tag1} as it 12221existed on @var{date1}, against the working file. See @ref{diff options} 12222and @ref{Common options}. 12223 12224@item -r @var{tag2}[:@var{date2}] 12225Diff the revisions specified by @var{tag2} or, when @var{date2} is specified 12226and @var{tag2} is a branch tag, the version from the branch @var{tag2} as it 12227existed on @var{date2}, against @var{rev1}/@var{date1}. See @ref{diff options} 12228and @ref{Common options}. 12229@end table 12230 12231@c ------------------------------------------------------------ 12232@item edit [@var{options}] [@var{files}@dots{}] 12233Get ready to edit a watched file. See @ref{Editing files}. 12234 12235@table @code 12236@item -a @var{actions} 12237Specify actions for temporary watch, where 12238@var{actions} is @code{edit}, @code{unedit}, 12239@code{commit}, @code{all}, or @code{none}. See 12240@ref{Editing files}. 12241 12242@item -c 12243Check edits: Edit fails if someone else is already editting the file. 12244Requires a @sc{cvs} client and server both of version 1.12.10 or greater. 12245 12246@item -f 12247Force edit; ignore other edits. Added in CVS 1.12.10. 12248 12249@item -l 12250Local; run only in current working directory. See @ref{Recursive behavior}. 12251 12252@item -R 12253Operate recursively (default). @xref{Recursive 12254behavior}. 12255@end table 12256 12257@c ------------------------------------------------------------ 12258@item editors [@var{options}] [@var{files}@dots{}] 12259See who is editing a watched file. See @ref{Watch information}. 12260 12261@table @code 12262@item -l 12263Local; run only in current working directory. See @ref{Recursive behavior}. 12264 12265@item -R 12266Operate recursively (default). @xref{Recursive 12267behavior}. 12268@end table 12269 12270@c ------------------------------------------------------------ 12271@item export [@var{options}] @var{modules}@dots{} 12272Export files from @sc{cvs}. See @ref{export}. 12273 12274@table @code 12275@item -D @var{date} 12276Check out revisions as of @var{date}. See 12277@ref{Common options}. 12278 12279@item -d @var{dir} 12280Check out into @var{dir}. See @ref{export options}. 12281 12282@item -f 12283Use head revision if tag/date not found. See 12284@ref{Common options}. 12285 12286@item -k @var{kflag} 12287Use @var{kflag} keyword expansion. See 12288@ref{Substitution modes}. 12289 12290@item -l 12291Local; run only in current working directory. @xref{Recursive behavior}. 12292 12293@item -N 12294Don't ``shorten'' module paths if -d specified. See 12295@ref{export options}. 12296 12297@item -n 12298Do not run module program (if any). See @ref{export options}. 12299 12300@item -R 12301Operate recursively (default). @xref{Recursive 12302behavior}. 12303 12304@item -r @var{tag}[:@var{date}] 12305Export the revisions specified by @var{tag} or, when @var{date} is specified 12306and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12307existed on @var{date}. See @ref{Common options}. 12308@end table 12309 12310@c ------------------------------------------------------------ 12311@item history [@var{options}] [@var{files}@dots{}] 12312Show repository access history. See @ref{history}. 12313 12314@table @code 12315@item -a 12316All users (default is self). See @ref{history options}. 12317 12318@item -b @var{str} 12319Back to record with @var{str} in module/file/repos 12320field. See @ref{history options}. 12321 12322@item -c 12323Report on committed (modified) files. See @ref{history options}. 12324 12325@item -D @var{date} 12326Since @var{date}. See @ref{history options}. 12327 12328@item -e 12329Report on all record types. See @ref{history options}. 12330 12331@item -l 12332Last modified (committed or modified report). See @ref{history options}. 12333 12334@item -m @var{module} 12335Report on @var{module} (repeatable). See @ref{history options}. 12336 12337@item -n @var{module} 12338In @var{module}. See @ref{history options}. 12339 12340@item -o 12341Report on checked out modules. See @ref{history options}. 12342 12343@item -p @var{repository} 12344In @var{repository}. See @ref{history options}. 12345 12346@item -r @var{rev} 12347Since revision @var{rev}. See @ref{history options}. 12348 12349@item -T 12350@c What the @#$@# is a TAG? Same as a tag? This 12351@c wording is also in the online-line help. 12352Produce report on all TAGs. See @ref{history options}. 12353 12354@item -t @var{tag} 12355Since tag record placed in history file (by anyone). 12356See @ref{history options}. 12357 12358@item -u @var{user} 12359For user @var{user} (repeatable). See @ref{history options}. 12360 12361@item -w 12362Working directory must match. See @ref{history options}. 12363 12364@item -x @var{types} 12365Report on @var{types}, one or more of 12366@code{TOEFWUPCGMAR}. See @ref{history options}. 12367 12368@item -z @var{zone} 12369Output for time zone @var{zone}. See @ref{history options}. 12370@end table 12371 12372@c ------------------------------------------------------------ 12373@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 12374Import files into @sc{cvs}, using vendor branches. See 12375@ref{import}. 12376 12377@table @code 12378@item -b @var{bra} 12379Import to vendor branch @var{bra}. See 12380@ref{Multiple vendor branches}. 12381 12382@item -d 12383Use the file's modification time as the time of 12384import. See @ref{import options}. 12385 12386@item -k @var{kflag} 12387Set default keyword substitution mode. See 12388@ref{import options}. 12389 12390@item -m @var{msg} 12391Use @var{msg} for log message. See 12392@ref{import options}. 12393 12394@item -I @var{ign} 12395More files to ignore (! to reset). See 12396@ref{import options}. 12397 12398@item -W @var{spec} 12399More wrappers. See @ref{import options}. 12400@end table 12401 12402@c ------------------------------------------------------------ 12403@item init 12404Create a @sc{cvs} repository if it doesn't exist. See 12405@ref{Creating a repository}. 12406 12407@c ------------------------------------------------------------ 12408@item kserver 12409Kerberos authenticated server. 12410See @ref{Kerberos authenticated}. 12411 12412@c ------------------------------------------------------------ 12413@item log [@var{options}] [@var{files}@dots{}] 12414Print out history information for files. See @ref{log}. 12415 12416@table @code 12417@item -b 12418Only list revisions on the default branch. See @ref{log options}. 12419 12420@item -d @var{dates} 12421Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12422latest before). See @ref{log options}. 12423 12424@item -h 12425Only print header. See @ref{log options}. 12426 12427@item -l 12428Local; run only in current working directory. See @ref{Recursive behavior}. 12429 12430@item -N 12431Do not list tags. See @ref{log options}. 12432 12433@item -R 12434Only print name of RCS file. See @ref{log options}. 12435 12436@item -r@var{revs} 12437Only list revisions @var{revs}. See @ref{log options}. 12438 12439@item -s @var{states} 12440Only list revisions with specified states. See @ref{log options}. 12441 12442@item -t 12443Only print header and descriptive text. See @ref{log 12444options}. 12445 12446@item -w@var{logins} 12447Only list revisions checked in by specified logins. See @ref{log options}. 12448@end table 12449 12450@c ------------------------------------------------------------ 12451@item login 12452Prompt for password for authenticating server. See 12453@ref{Password authentication client}. 12454 12455@c ------------------------------------------------------------ 12456@item logout 12457Remove stored password for authenticating server. See 12458@ref{Password authentication client}. 12459 12460@c ------------------------------------------------------------ 12461@item pserver 12462Password authenticated server. 12463See @ref{Password authentication server}. 12464 12465@c ------------------------------------------------------------ 12466@item rannotate [@var{options}] [@var{modules}@dots{}] 12467Show last revision where each line was modified. See 12468@ref{annotate}. 12469 12470@table @code 12471@item -D @var{date} 12472Annotate the most recent revision no later than 12473@var{date}. See @ref{Common options}. 12474 12475@item -F 12476Force annotation of binary files. (Without this option, 12477binary files are skipped with a message.) 12478 12479@item -f 12480Use head revision if tag/date not found. See 12481@ref{Common options}. 12482 12483@item -l 12484Local; run only in current working directory. @xref{Recursive behavior}. 12485 12486@item -R 12487Operate recursively (default). @xref{Recursive behavior}. 12488 12489@item -r @var{tag}[:@var{date}] 12490Annotate the revision specified by @var{tag} or, when @var{date} is specified 12491and @var{tag} is a branch tag, the version from the branch @var{tag} 12492as it existed on @var{date}. See @ref{Common options}. 12493@end table 12494 12495@c ------------------------------------------------------------ 12496@item rdiff [@var{options}] @var{modules}@dots{} 12497Show differences between releases. See @ref{rdiff}. 12498 12499@table @code 12500@item -c 12501Context diff output format (default). See @ref{rdiff options}. 12502 12503@item -D @var{date} 12504Select revisions based on @var{date}. See @ref{Common options}. 12505 12506@item -f 12507Use head revision if tag/date not found. See 12508@ref{Common options}. 12509 12510@item -l 12511Local; run only in current working directory. See @ref{Recursive behavior}. 12512 12513@item -R 12514Operate recursively (default). @xref{Recursive 12515behavior}. 12516 12517@item -r @var{tag}[:@var{date}] 12518Select the revisions specified by @var{tag} or, when @var{date} is specified 12519and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12520existed on @var{date}. See @ref{diff options} and @ref{Common options}. 12521 12522@item -s 12523Short patch - one liner per file. See @ref{rdiff options}. 12524 12525@item -t 12526Top two diffs - last change made to the file. See 12527@ref{diff options}. 12528 12529@item -u 12530Unidiff output format. See @ref{rdiff options}. 12531 12532@item -V @var{vers} 12533Use RCS Version @var{vers} for keyword expansion (obsolete). See 12534@ref{rdiff options}. 12535@end table 12536 12537@c ------------------------------------------------------------ 12538@item release [@var{options}] @var{directory} 12539Indicate that a directory is no longer in use. See 12540@ref{release}. 12541 12542@table @code 12543@item -d 12544Delete the given directory. See @ref{release options}. 12545@end table 12546 12547@c ------------------------------------------------------------ 12548@item remove [@var{options}] [@var{files}@dots{}] 12549Remove an entry from the repository. See @ref{Removing files}. 12550 12551@table @code 12552@item -f 12553Delete the file before removing it. See @ref{Removing files}. 12554 12555@item -l 12556Local; run only in current working directory. See @ref{Recursive behavior}. 12557 12558@item -R 12559Operate recursively (default). @xref{Recursive 12560behavior}. 12561@end table 12562 12563@c ------------------------------------------------------------ 12564@item rlog [@var{options}] [@var{files}@dots{}] 12565Print out history information for modules. See @ref{log}. 12566 12567@table @code 12568@item -b 12569Only list revisions on the default branch. See @ref{log options}. 12570 12571@item -d @var{dates} 12572Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12573latest before). See @ref{log options}. 12574 12575@item -h 12576Only print header. See @ref{log options}. 12577 12578@item -l 12579Local; run only in current working directory. See @ref{Recursive behavior}. 12580 12581@item -N 12582Do not list tags. See @ref{log options}. 12583 12584@item -R 12585Only print name of RCS file. See @ref{log options}. 12586 12587@item -r@var{revs} 12588Only list revisions @var{revs}. See @ref{log options}. 12589 12590@item -s @var{states} 12591Only list revisions with specified states. See @ref{log options}. 12592 12593@item -t 12594Only print header and descriptive text. See @ref{log options}. 12595 12596@item -w@var{logins} 12597Only list revisions checked in by specified logins. See @ref{log options}. 12598@end table 12599 12600@c ------------------------------------------------------------ 12601@item rtag [@var{options}] @var{tag} @var{modules}@dots{} 12602Add a symbolic tag to a module. 12603See @ref{Revisions} and @ref{Branching and merging}. 12604 12605@table @code 12606@item -a 12607Clear tag from removed files that would not otherwise 12608be tagged. See @ref{Tagging add/remove}. 12609 12610@item -b 12611Create a branch named @var{tag}. See @ref{Branching and merging}. 12612 12613@item -B 12614Used in conjunction with -F or -d, enables movement and deletion of 12615branch tags. Use with extreme caution. 12616 12617@item -D @var{date} 12618Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12619 12620@item -d 12621Delete @var{tag}. See @ref{Modifying tags}. 12622 12623@item -F 12624Move @var{tag} if it already exists. See @ref{Modifying tags}. 12625 12626@item -f 12627Force a head revision match if tag/date not found. 12628See @ref{Tagging by date/tag}. 12629 12630@item -l 12631Local; run only in current working directory. See @ref{Recursive behavior}. 12632 12633@item -n 12634No execution of tag program. See @ref{Common options}. 12635 12636@item -R 12637Operate recursively (default). @xref{Recursive 12638behavior}. 12639 12640@item -r @var{tag}[:@var{date}] 12641Tag the revision already tagged with @var{tag} or, when @var{date} is specified 12642and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12643existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12644@end table 12645 12646@c ------------------------------------------------------------ 12647@item server 12648Rsh server. See @ref{Connecting via rsh}. 12649 12650@c ------------------------------------------------------------ 12651@item status [@var{options}] @var{files}@dots{} 12652Display status information in a working directory. See 12653@ref{File status}. 12654 12655@table @code 12656@item -l 12657Local; run only in current working directory. See @ref{Recursive behavior}. 12658 12659@item -R 12660Operate recursively (default). @xref{Recursive behavior}. 12661 12662@item -v 12663Include tag information for file. See @ref{Tags}. 12664@end table 12665 12666@c ------------------------------------------------------------ 12667@item tag [@var{options}] @var{tag} [@var{files}@dots{}] 12668Add a symbolic tag to checked out version of files. 12669See @ref{Revisions} and @ref{Branching and merging}. 12670 12671@table @code 12672@item -b 12673Create a branch named @var{tag}. See @ref{Branching and merging}. 12674 12675@item -c 12676Check that working files are unmodified. See 12677@ref{Tagging the working directory}. 12678 12679@item -D @var{date} 12680Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12681 12682@item -d 12683Delete @var{tag}. See @ref{Modifying tags}. 12684 12685@item -F 12686Move @var{tag} if it already exists. See @ref{Modifying tags}. 12687 12688@item -f 12689Force a head revision match if tag/date not found. 12690See @ref{Tagging by date/tag}. 12691 12692@item -l 12693Local; run only in current working directory. See @ref{Recursive behavior}. 12694 12695@item -R 12696Operate recursively (default). @xref{Recursive behavior}. 12697 12698@item -r @var{tag}[:@var{date}] 12699Tag the revision already tagged with @var{tag}, or when @var{date} is specified 12700and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12701existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12702@end table 12703 12704@c ------------------------------------------------------------ 12705@item unedit [@var{options}] [@var{files}@dots{}] 12706Undo an edit command. See @ref{Editing files}. 12707 12708@table @code 12709@item -l 12710Local; run only in current working directory. See @ref{Recursive behavior}. 12711 12712@item -R 12713Operate recursively (default). @xref{Recursive behavior}. 12714@end table 12715 12716@c ------------------------------------------------------------ 12717@item update [@var{options}] [@var{files}@dots{}] 12718Bring work tree in sync with repository. See 12719@ref{update}. 12720 12721@table @code 12722@item -A 12723Reset any sticky tags/date/options. See @ref{Sticky 12724tags} and @ref{Keyword substitution}. 12725 12726@item -C 12727Overwrite locally modified files with clean copies from 12728the repository (the modified file is saved in 12729@file{.#@var{file}.@var{revision}}, however). 12730 12731@item -D @var{date} 12732Check out revisions as of @var{date} (is sticky). See 12733@ref{Common options}. 12734 12735@item -d 12736Create directories. See @ref{update options}. 12737 12738@item -f 12739Use head revision if tag/date not found. See 12740@ref{Common options}. 12741 12742@item -I @var{ign} 12743More files to ignore (! to reset). See 12744@ref{import options}. 12745 12746@c Probably want to use rev1/rev2 style like for diff 12747@c -r. Here and in on-line help. 12748@item -j @var{tag}[:@var{date}] 12749Merge in changes from revisions specified by @var{tag} or, when @var{date} is 12750specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12751as it existed on @var{date}. See @ref{update options}. 12752 12753@item -k @var{kflag} 12754Use @var{kflag} keyword expansion. See 12755@ref{Substitution modes}. 12756 12757@item -l 12758Local; run only in current working directory. @xref{Recursive behavior}. 12759 12760@item -P 12761Prune empty directories. See @ref{Moving directories}. 12762 12763@item -p 12764Check out files to standard output (avoids 12765stickiness). See @ref{update options}. 12766 12767@item -R 12768Operate recursively (default). @xref{Recursive 12769behavior}. 12770 12771@item -r @var{tag}[:@var{date}] 12772Checkout the revisions specified by @var{tag} or, when @var{date} is specified 12773and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12774existed on @var{date}. See @ref{Common options}. 12775 12776@item -W @var{spec} 12777More wrappers. See @ref{import options}. 12778@end table 12779 12780@c ------------------------------------------------------------ 12781@item version 12782@cindex version (subcommand) 12783 12784Display the version of @sc{cvs} being used. If the repository 12785is remote, display both the client and server versions. 12786 12787@c ------------------------------------------------------------ 12788@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 12789 12790on/off: turn on/off read-only checkouts of files. See 12791@ref{Setting a watch}. 12792 12793add/remove: add or remove notification on actions. See 12794@ref{Getting Notified}. 12795 12796@table @code 12797@item -a @var{actions} 12798Specify actions for temporary watch, where 12799@var{actions} is @code{edit}, @code{unedit}, 12800@code{commit}, @code{all}, or @code{none}. See 12801@ref{Editing files}. 12802 12803@item -l 12804Local; run only in current working directory. See @ref{Recursive behavior}. 12805 12806@item -R 12807Operate recursively (default). @xref{Recursive 12808behavior}. 12809@end table 12810 12811@c ------------------------------------------------------------ 12812@item watchers [@var{options}] [@var{files}@dots{}] 12813See who is watching a file. See @ref{Watch information}. 12814 12815@table @code 12816@item -l 12817Local; run only in current working directory. See @ref{Recursive behavior}. 12818 12819@item -R 12820Operate recursively (default). @xref{Recursive 12821behavior}. 12822@end table 12823 12824@end table 12825 12826@c --------------------------------------------------------------------- 12827@node Administrative files 12828@appendix Reference manual for Administrative files 12829@cindex Administrative files (reference) 12830@cindex Files, reference manual 12831@cindex Reference manual (files) 12832@cindex CVSROOT (file) 12833 12834Inside the repository, in the directory 12835@file{$CVSROOT/CVSROOT}, there are a number of 12836supportive files for @sc{cvs}. You can use @sc{cvs} in a limited 12837fashion without any of them, but if they are set up 12838properly they can help make life easier. For a 12839discussion of how to edit them, see @ref{Intro 12840administrative files}. 12841 12842The most important of these files is the @file{modules} 12843file, which defines the modules inside the repository. 12844 12845@menu 12846* modules:: Defining modules 12847* Wrappers:: Specify binary-ness based on file name 12848* Trigger Scripts:: Launch scripts in response to server events 12849* rcsinfo:: Templates for the log messages 12850* cvsignore:: Ignoring files via cvsignore 12851* checkoutlist:: Adding your own administrative files 12852* history file:: History information 12853* Variables:: Various variables are expanded 12854* config:: Miscellaneous CVS configuration 12855@end menu 12856 12857@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12858@node modules 12859@appendixsec The modules file 12860@cindex Modules (admin file) 12861@cindex Defining modules (reference manual) 12862 12863The @file{modules} file records your definitions of 12864names for collections of source code. @sc{cvs} will 12865use these definitions if you use @sc{cvs} to update the 12866modules file (use normal commands like @code{add}, 12867@code{commit}, etc). 12868 12869The @file{modules} file may contain blank lines and 12870comments (lines beginning with @samp{#}) as well as 12871module definitions. Long lines can be continued on the 12872next line by specifying a backslash (@samp{\}) as the 12873last character on the line. 12874 12875There are three basic types of modules: alias modules, 12876regular modules, and ampersand modules. The difference 12877between them is the way that they map files in the 12878repository to files in the working directory. In all 12879of the following examples, the top-level repository 12880contains a directory called @file{first-dir}, which 12881contains two files, @file{file1} and @file{file2}, and a 12882directory @file{sdir}. @file{first-dir/sdir} contains 12883a file @file{sfile}. 12884 12885@c FIXME: should test all the examples in this section. 12886 12887@menu 12888* Alias modules:: The simplest kind of module 12889* Regular modules:: 12890* Ampersand modules:: 12891* Excluding directories:: Excluding directories from a module 12892* Module options:: Regular and ampersand modules can take options 12893* Module program options:: How the modules ``program options'' programs 12894 are run. 12895@end menu 12896 12897@node Alias modules 12898@appendixsubsec Alias modules 12899@cindex Alias modules 12900@cindex -a, in modules file 12901 12902Alias modules are the simplest kind of module: 12903 12904@table @code 12905@item @var{mname} -a @var{aliases}@dots{} 12906This represents the simplest way of defining a module 12907@var{mname}. The @samp{-a} flags the definition as a 12908simple alias: @sc{cvs} will treat any use of @var{mname} (as 12909a command argument) as if the list of names 12910@var{aliases} had been specified instead. 12911@var{aliases} may contain either other module names or 12912paths. When you use paths in aliases, @code{checkout} 12913creates all intermediate directories in the working 12914directory, just as if the path had been specified 12915explicitly in the @sc{cvs} arguments. 12916@end table 12917 12918For example, if the modules file contains: 12919 12920@example 12921amodule -a first-dir 12922@end example 12923 12924@noindent 12925then the following two commands are equivalent: 12926 12927@example 12928$ cvs co amodule 12929$ cvs co first-dir 12930@end example 12931 12932@noindent 12933and they each would provide output such as: 12934 12935@example 12936cvs checkout: Updating first-dir 12937U first-dir/file1 12938U first-dir/file2 12939cvs checkout: Updating first-dir/sdir 12940U first-dir/sdir/sfile 12941@end example 12942 12943@node Regular modules 12944@appendixsubsec Regular modules 12945@cindex Regular modules 12946 12947@table @code 12948@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 12949In the simplest case, this form of module definition 12950reduces to @samp{@var{mname} @var{dir}}. This defines 12951all the files in directory @var{dir} as module mname. 12952@var{dir} is a relative path (from @code{$CVSROOT}) to a 12953directory of source in the source repository. In this 12954case, on checkout, a single directory called 12955@var{mname} is created as a working directory; no 12956intermediate directory levels are used by default, even 12957if @var{dir} was a path involving several directory 12958levels. 12959@end table 12960 12961For example, if a module is defined by: 12962 12963@example 12964regmodule first-dir 12965@end example 12966 12967@noindent 12968then regmodule will contain the files from first-dir: 12969 12970@example 12971$ cvs co regmodule 12972cvs checkout: Updating regmodule 12973U regmodule/file1 12974U regmodule/file2 12975cvs checkout: Updating regmodule/sdir 12976U regmodule/sdir/sfile 12977$ 12978@end example 12979 12980By explicitly specifying files in the module definition 12981after @var{dir}, you can select particular files from 12982directory @var{dir}. Here is 12983an example: 12984 12985@example 12986regfiles first-dir/sdir sfile 12987@end example 12988 12989@noindent 12990With this definition, getting the regfiles module 12991will create a single working directory 12992@file{regfiles} containing the file listed, which 12993comes from a directory deeper 12994in the @sc{cvs} source repository: 12995 12996@example 12997$ cvs co regfiles 12998U regfiles/sfile 12999$ 13000@end example 13001 13002@node Ampersand modules 13003@appendixsubsec Ampersand modules 13004@cindex Ampersand modules 13005@cindex &, in modules file 13006 13007A module definition can refer to other modules by 13008including @samp{&@var{module}} in its definition. 13009@example 13010@var{mname} [ options ] @var{&module}@dots{} 13011@end example 13012 13013Then getting the module creates a subdirectory for each such 13014module, in the directory containing the module. For 13015example, if modules contains 13016 13017@example 13018ampermod &first-dir 13019@end example 13020 13021@noindent 13022then a checkout will create an @code{ampermod} directory 13023which contains a directory called @code{first-dir}, 13024which in turns contains all the directories and files 13025which live there. For example, the command 13026 13027@example 13028$ cvs co ampermod 13029@end example 13030 13031@noindent 13032will create the following files: 13033 13034@example 13035ampermod/first-dir/file1 13036ampermod/first-dir/file2 13037ampermod/first-dir/sdir/sfile 13038@end example 13039 13040There is one quirk/bug: the messages that @sc{cvs} 13041prints omit the @file{ampermod}, and thus do not 13042correctly display the location to which it is checking 13043out the files: 13044 13045@example 13046$ cvs co ampermod 13047cvs checkout: Updating first-dir 13048U first-dir/file1 13049U first-dir/file2 13050cvs checkout: Updating first-dir/sdir 13051U first-dir/sdir/sfile 13052$ 13053@end example 13054 13055Do not rely on this buggy behavior; it may get fixed in 13056a future release of @sc{cvs}. 13057 13058@c FIXCVS: What happens if regular and & modules are 13059@c combined, as in "ampermodule first-dir &second-dir"? 13060@c When I tried it, it seemed to just ignore the 13061@c "first-dir". I think perhaps it should be an error 13062@c (but this needs further investigation). 13063@c In addition to discussing what each one does, we 13064@c should put in a few words about why you would use one or 13065@c the other in various situations. 13066 13067@node Excluding directories 13068@appendixsubsec Excluding directories 13069@cindex Excluding directories, in modules file 13070@cindex !, in modules file 13071 13072An alias module may exclude particular directories from 13073other modules by using an exclamation mark (@samp{!}) 13074before the name of each directory to be excluded. 13075 13076For example, if the modules file contains: 13077 13078@example 13079exmodule -a !first-dir/sdir first-dir 13080@end example 13081 13082@noindent 13083then checking out the module @samp{exmodule} will check 13084out everything in @samp{first-dir} except any files in 13085the subdirectory @samp{first-dir/sdir}. 13086@c Note that the "!first-dir/sdir" sometimes must be listed 13087@c before "first-dir". That seems like a probable bug, in which 13088@c case perhaps it should be fixed (to allow either 13089@c order) rather than documented. See modules4 in testsuite. 13090 13091@node Module options 13092@appendixsubsec Module options 13093@cindex Options, in modules file 13094 13095Either regular modules or ampersand modules can contain 13096options, which supply additional information concerning 13097the module. 13098 13099@table @code 13100@cindex -d, in modules file 13101@item -d @var{name} 13102Name the working directory something other than the 13103module name. 13104@c FIXME: Needs a bunch of examples, analogous to the 13105@c examples for alias, regular, and ampersand modules 13106@c which show where the files go without -d. 13107 13108@cindex Export program 13109@cindex -e, in modules file 13110@item -e @var{prog} 13111Specify a program @var{prog} to run whenever files in a 13112module are exported. @var{prog} runs with a single 13113argument, the module name. 13114@c FIXME: Is it run on server? client? 13115 13116@cindex Checkout program 13117@cindex -o, in modules file 13118@item -o @var{prog} 13119Specify a program @var{prog} to run whenever files in a 13120module are checked out. @var{prog} runs with a single 13121argument, the module name. See @ref{Module program options} for 13122information on how @var{prog} is called. 13123@c FIXME: Is it run on server? client? 13124 13125@cindex Status of a module 13126@cindex Module status 13127@cindex -s, in modules file 13128@item -s @var{status} 13129Assign a status to the module. When the module file is 13130printed with @samp{cvs checkout -s} the modules are 13131sorted according to primarily module status, and 13132secondarily according to the module name. This option 13133has no other meaning. You can use this option for 13134several things besides status: for instance, list the 13135person that is responsible for this module. 13136 13137@cindex Tag program 13138@cindex -t, in modules file 13139@item -t @var{prog} 13140Specify a program @var{prog} to run whenever files in a 13141module are tagged with @code{rtag}. @var{prog} runs 13142with two arguments: the module name and the symbolic 13143tag specified to @code{rtag}. It is not run 13144when @code{tag} is executed. Generally you will find 13145that the @file{taginfo} file is a better solution (@pxref{taginfo}). 13146@c FIXME: Is it run on server? client? 13147@c Problems with -t include: 13148@c * It is run after the tag not before 13149@c * It doesn't get passed all the information that 13150@c taginfo does ("mov", &c). 13151@c * It only is run for rtag, not tag. 13152@end table 13153 13154You should also see @pxref{Module program options} about how the 13155``program options'' programs are run. 13156 13157@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13158 13159@node Module program options 13160@appendixsubsec How the modules file ``program options'' programs are run 13161@cindex Modules file program options 13162@cindex -t, in modules file 13163@cindex -o, in modules file 13164@cindex -e, in modules file 13165 13166@noindent 13167For checkout, rtag, and export, the program is server-based, and as such the 13168following applies:- 13169 13170If using remote access methods (pserver, ext, etc.), 13171@sc{cvs} will execute this program on the server from a temporary 13172directory. The path is searched for this program. 13173 13174If using ``local access'' (on a local or remote NFS file system, i.e. 13175repository set just to a path), 13176the program will be executed from the newly checked-out tree, if 13177found there, or alternatively searched for in the path if not. 13178 13179The programs are all run after the operation has effectively 13180completed. 13181 13182 13183@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13184@node Wrappers 13185@appendixsec The cvswrappers file 13186@cindex cvswrappers (admin file) 13187@cindex CVSWRAPPERS, environment variable 13188@cindex Wrappers 13189 13190@c FIXME: need some better way of separating this out 13191@c by functionality. -m is 13192@c one feature, and -k is a another. And this discussion 13193@c should be better motivated (e.g. start with the 13194@c problems, then explain how the feature solves it). 13195 13196Wrappers refers to a @sc{cvs} feature which lets you 13197control certain settings based on the name of the file 13198which is being operated on. The settings are @samp{-k} 13199for binary files, and @samp{-m} for nonmergeable text 13200files. 13201 13202The @samp{-m} option 13203specifies the merge methodology that should be used when 13204a non-binary file is updated. @code{MERGE} means the usual 13205@sc{cvs} behavior: try to merge the files. @code{COPY} 13206means that @code{cvs update} will refuse to merge 13207files, as it also does for files specified as binary 13208with @samp{-kb} (but if the file is specified as 13209binary, there is no need to specify @samp{-m 'COPY'}). 13210@sc{cvs} will provide the user with the 13211two versions of the files, and require the user using 13212mechanisms outside @sc{cvs}, to insert any necessary 13213changes. 13214 13215@strong{WARNING: do not use @code{COPY} with 13216@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 13217copy one version of your file over the other, wiping 13218out the previous contents.} 13219@c Ordinarily we don't document the behavior of old 13220@c versions. But this one is so dangerous, I think we 13221@c must. I almost renamed it to -m 'NOMERGE' so we 13222@c could say "never use -m 'COPY'". 13223The @samp{-m} wrapper option only affects behavior when 13224merging is done on update; it does not affect how files 13225are stored. See @ref{Binary files}, for more on 13226binary files. 13227 13228The basic format of the file @file{cvswrappers} is: 13229 13230@c FIXME: @example is all wrong for this. Use @deffn or 13231@c something more sensible. 13232@example 13233wildcard [option value][option value]... 13234 13235where option is one of 13236-m update methodology value: MERGE or COPY 13237-k keyword expansion value: expansion mode 13238 13239and value is a single-quote delimited value. 13240@end example 13241 13242@ignore 13243@example 13244*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' 13245*.c -t 'indent %s %s' 13246@end example 13247@c When does the filter need to be an absolute pathname 13248@c and when will something like the above work? I 13249@c suspect it relates to the PATH of the server (which 13250@c in turn depends on all kinds of stuff, e.g. inetd 13251@c for pserver). I'm not sure whether/where to discuss 13252@c this. 13253@c FIXME: What do the %s's stand for? 13254 13255@noindent 13256The above example of a @file{cvswrappers} file 13257states that all files/directories that end with a @code{.nib} 13258should be filtered with the @file{wrap} program before 13259checking the file into the repository. The file should 13260be filtered though the @file{unwrap} program when the 13261file is checked out of the repository. The 13262@file{cvswrappers} file also states that a @code{COPY} 13263methodology should be used when updating the files in 13264the repository (that is, no merging should be performed). 13265 13266@c What pitfalls arise when using indent this way? Is 13267@c it a winning thing to do? Would be nice to at least 13268@c hint at those issues; we want our examples to tell 13269@c how to solve problems, not just to say that cvs can 13270@c do certain things. 13271The last example line says that all files that end with 13272@code{.c} should be filtered with @file{indent} 13273before being checked into the repository. Unlike the previous 13274example, no filtering of the @code{.c} file is done when 13275it is checked out of the repository. 13276@noindent 13277The @code{-t} filter is called with two arguments, 13278the first is the name of the file/directory to filter 13279and the second is the pathname to where the resulting 13280filtered file should be placed. 13281 13282@noindent 13283The @code{-f} filter is called with one argument, 13284which is the name of the file to filter from. The end 13285result of this filter will be a file in the users directory 13286that they can work on as they normally would. 13287 13288Note that the @samp{-t}/@samp{-f} features do not 13289conveniently handle one portion of @sc{cvs}'s operation: 13290determining when files are modified. @sc{cvs} will still 13291want a file (or directory) to exist, and it will use 13292its modification time to determine whether a file is 13293modified. If @sc{cvs} erroneously thinks a file is 13294unmodified (for example, a directory is unchanged but 13295one of the files within it is changed), you can force 13296it to check in the file anyway by specifying the 13297@samp{-f} option to @code{cvs commit} (@pxref{commit 13298options}). 13299@c This is, of course, a serious design flaw in -t/-f. 13300@c Probably the whole functionality needs to be 13301@c redesigned (starting from requirements) to fix this. 13302@end ignore 13303 13304@c FIXME: We don't document -W or point to where it is 13305@c documented. Or .cvswrappers. 13306For example, the following command imports a 13307directory, treating files whose name ends in 13308@samp{.exe} as binary: 13309 13310@example 13311cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 13312@end example 13313 13314@c Another good example, would be storing files 13315@c (e.g. binary files) compressed in the repository. 13316@c :::::::::::::::::: 13317@c cvswrappers 13318@c :::::::::::::::::: 13319@c *.t12 -m 'COPY' 13320@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 13321@c 13322@c :::::::::::::::::: 13323@c gunzipcp 13324@c :::::::::::::::::: 13325@c : 13326@c [ -f $1 ] || exit 1 13327@c zcat $1 > /tmp/.#$1.$$ 13328@c mv /tmp/.#$1.$$ $1 13329@c 13330@c :::::::::::::::::: 13331@c gzipcp 13332@c :::::::::::::::::: 13333@c : 13334@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 13335@c if [ ! -d $DIRNAME ] ; then 13336@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 13337@c fi 13338@c gzip -c $DIRNAME > $2 13339@c One catch--"cvs diff" will not invoke the wrappers 13340@c (probably a CVS bug, although I haven't thought it out). 13341 13342@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13343@node Trigger Scripts 13344@appendixsec The Trigger Scripts 13345@cindex info files 13346@cindex trigger scripts 13347@cindex script hooks 13348 13349@c FIXME 13350@c Somewhere there needs to be a more "how-to" guide to writing these. 13351@c One particular issue that people sometimes are worried about is performance, 13352@c and the impact of writing in perl or sh or ____. Performance comparisons 13353@c should probably remain outside the scope of this document, but at least 13354@c _that_ much could be referenced, perhaps with links to other sources. 13355 13356Several of the administrative files support triggers, or the launching external 13357scripts or programs at specific times before or after particular events, during 13358the execution of @sc{cvs} commands. These hooks can be used to prevent certain 13359actions, log them, and/or maintain anything else you deem practical. 13360 13361All the trigger scripts are launched in a copy of the user sandbox being 13362committed, on the server, in client-server mode. In local mode, the scripts 13363are actually launched directly from the user sandbox directory being committed. 13364For most intents and purposes, the same scripts can be run in both locations 13365without alteration. 13366 13367@menu 13368* syntax:: The common syntax 13369* Trigger Script Security:: Trigger script security 13370 13371* commit files:: The commit support files (commitinfo, 13372 verifymsg, loginfo) 13373* commitinfo:: Pre-commit checking 13374* verifymsg:: How are log messages evaluated? 13375* loginfo:: Where should log messages be sent? 13376 13377* postadmin:: Logging admin commands 13378* taginfo:: Verifying/Logging tags 13379* posttag:: Logging tags 13380* postwatch:: Logging watch commands 13381 13382* preproxy:: Launch a script on a secondary server prior 13383 to becoming a write proxy 13384* postproxy:: Launch a script on a secondary server after 13385 completing proxy operations 13386@end menu 13387 13388@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13389@node syntax 13390@appendixsubsec The common syntax 13391@cindex info files, common syntax 13392@cindex script hooks, common syntax 13393@cindex trigger script hooks, common syntax 13394@cindex syntax of trigger script hooks 13395 13396@c FIXME: having this so totally separate from the 13397@c Variables node is rather bogus. 13398 13399The administrative files such as @file{commitinfo}, 13400@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 13401all have a common format. The purpose of the files are 13402described later on. The common syntax is described 13403here. 13404 13405@cindex Regular expression syntax 13406Each line contains the following: 13407 13408@itemize @bullet 13409@cindex @samp{ALL} keyword, in lieu of regular expressions in script hooks 13410@cindex @samp{DEFAULT} keyword, in lieu of regular expressions in script hooks 13411@item 13412A regular expression or the literal string @samp{DEFAULT}. Some script hooks 13413also support the literal string @samp{ALL}. Other than the @samp{ALL} and 13414@samp{DEFAULT} keywords, this is a basic regular expression in the syntax used 13415by GNU emacs. See the descriptions of the individual script hooks for 13416information on whether the @samp{ALL} keyword is supported 13417(@pxref{Trigger Scripts}). 13418@c FIXME: What we probably should be saying is "POSIX Basic 13419@c Regular Expression with the following extensions (`\(' 13420@c `\|' '+' etc)" 13421@c rather than define it with reference to emacs. 13422@c The reference to emacs is not strictly speaking 13423@c true, as we don't support \=, \s, or \S. Also it isn't 13424@c clear we should document and/or promise to continue to 13425@c support all the obscure emacs extensions like \<. 13426@c Also need to better cite (or include) full 13427@c documentation for the syntax. 13428@c Also see comment in configure.in about what happens to the 13429@c syntax if we pick up a system-supplied regexp matcher. 13430 13431@item 13432A whitespace separator---one or more spaces and/or tabs. 13433 13434@item 13435A file name or command-line template. 13436@end itemize 13437 13438@noindent 13439Blank lines are ignored. Lines that start with the 13440character @samp{#} are treated as comments. Long lines 13441unfortunately can @emph{not} be broken in two parts in 13442any way. 13443 13444The first regular expression that matches the current 13445directory name in the repository or the first line containing @samp{DEFAULT} 13446in lieu of a regular expression is used and all lines containing @samp{ALL} is 13447used for the hooks which support the @samp{ALL} keyword. The rest of the line 13448is used as a file name or command-line template as appropriate. See the 13449descriptions of the individual script hooks for information on whether the 13450@samp{ALL} keyword is supported (@pxref{Trigger Scripts}). 13451 13452@cindex format strings 13453@cindex format strings, common syntax 13454@cindex info files, common syntax, format strings 13455@cindex Common syntax of info files, format strings 13456@noindent 13457@emph{Note: The following information on format strings is valid 13458as long as the line @code{UseNewInfoFmtStrings=yes} appears in 13459your repository's config file (@pxref{config}). Otherwise, 13460default format strings may be appended to the command line and 13461the @samp{loginfo} file, especially, can exhibit slightly 13462different behavior. For more information, 13463@xref{Updating Commit Files}.} 13464 13465In the cases where the second segment of the matched line is a 13466command line template (e.g. @file{commitinfo}, @file{loginfo}, 13467& @file{verifymsg}), the command line template may contain format 13468strings which will be replaced with specific values before the 13469script is run. 13470@c FIXCVS then FIXME - it really would make sense to allow %r & maybe even %p 13471@c to be used in rcsinfo to construct a path, but I haven't 13472@c coded this yet. 13473 13474Format strings can represent a single variable or one or more 13475attributes of a list variable. An example of a list variable 13476would be the list available to scripts hung on the loginfo hooks 13477- the list of files which were just committed. In the case of 13478loginfo, three attributes are available for each list item: file 13479name, precommit version, and postcommit version. 13480 13481Format strings consist of a @samp{%} character followed by an optional 13482@samp{@{} (required in the multiple list attribute case), a 13483single format character representing a variable or a single attribute of 13484list elements or multiple format characters representing attributes of 13485list elements, and a closing @samp{@}} when the open bracket was present. 13486 13487@emph{Flat format strings}, or single format characters which get replaced 13488with a single value, will generate a single argument 13489to the called script, regardless of whether the replacement variable contains 13490white space or other special characters. 13491 13492@emph{List attributes} will generate an argument for each attribute 13493requested for each list item. For example, @samp{%@{sVv@}} 13494in a @file{loginfo} command template will generate three 13495arguments (file name, precommit version, postcommit version, 13496...) for each file committed. As in the flat format string 13497case, each attribute will be passed in as a single argument 13498regardless of whether it contains white space or other 13499special characters. 13500 13501@samp{%%} will be replaced with a literal @samp{%}. 13502 13503The format strings available to all script hooks are: 13504 13505@table @t 13506@item c 13507The canonical name of the command being executed. For instance, in the case of 13508a hook run from @code{cvs up}, @sc{cvs} would replace @samp{%c} with the string 13509@samp{update} and, in the case of a hook run from @code{cvs ci}, @sc{cvs} would 13510replace @samp{%c} with the string @samp{commit}. 13511@item n 13512The null, or empty, string. 13513@item p 13514The name of the directory being operated on within the repository. 13515@item r 13516The name of the repository (the path portion of @code{$CVSROOT}). 13517@item R 13518On a server, the name of the referrer, if any. The referrer is the CVSROOT the 13519client reports it used to contact a server which then referred it to this 13520server. Should usually be set on a primary server with a write proxy setup. 13521@end table 13522 13523Other format strings are file specific. See the docs on the 13524particular script hooks for more information 13525(@pxref{Trigger Scripts}). 13526 13527As an example, the following line in a @file{loginfo} file would 13528match only the directory @file{module} and any subdirectories of 13529@file{module}: 13530 13531@example 13532^module\(/\|$\) (echo; echo %p; echo %@{sVv@}; cat) >>$CVSROOT/CVSROOT/commitlog 13533@end example 13534 13535Using this same line and assuming a commit of new revisions 135361.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27, 13537respectively, of file1 and file2 in module, something like the 13538following log message should be appended to commitlog: 13539 13540@example 13541 13542module 13543file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1 13544Update of /cvsroot/module 13545In directory localhost.localdomain:/home/jrandom/work/module 13546 13547Modified Files: 13548 file1 file2 13549Log Message: 13550A log message. 13551@end example 13552 13553@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13554@node Trigger Script Security 13555@appendixsubsec Security and the Trigger Scripts 13556@cindex info files, security 13557@cindex script hooks, security 13558@cindex trigger scripts, security 13559 13560Security is a huge subject, and implementing a secure system is a non-trivial 13561task. This section will barely touch on all the issues involved, but it is 13562well to note that, as with any script you will be allowing an untrusted 13563user to run on your server, there are measures you can take to help prevent 13564your trigger scripts from being abused. 13565 13566For instance, since the CVS trigger scripts all run in a copy of the user's 13567sandbox on the server, a naively coded Perl trigger script which attempts to 13568use a Perl module that is not installed on the system can be hijacked by any 13569user with commit access who is checking in a file with the correct name. Other 13570scripting languages may be vulnerable to similar hacks. 13571 13572One way to make a script more secure, at least with Perl, is to use scripts 13573which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. 13574In the most basic terms, this causes Perl to avoid running code that may have 13575come from an external source. Please run the @code{perldoc perlsec} command 13576for more on Perl security. Again, other languages may implement other security 13577verification hooks which look more or less like Perl's "taint-check" mechanism. 13578 13579@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13580@node commit files 13581@appendixsubsec The commit support files 13582@cindex Commits, administrative support files 13583@cindex commit files, see Info files 13584 13585The @samp{-i} flag in the @file{modules} file can be 13586used to run a certain program whenever files are 13587committed (@pxref{modules}). The files described in 13588this section provide other, more flexible, ways to run 13589programs whenever something is committed. 13590 13591There are three kinds of programs that can be run on 13592commit. They are specified in files in the repository, 13593as described below. The following table summarizes the 13594file names and the purpose of the corresponding 13595programs. 13596 13597@table @file 13598@item commitinfo 13599The program is responsible for checking that the commit 13600is allowed. If it exits with a non-zero exit status 13601the commit will be aborted. @xref{commitinfo}. 13602 13603@item verifymsg 13604The specified program is used to evaluate the log message, 13605and possibly verify that it contains all required 13606fields. This is most useful in combination with the 13607@file{rcsinfo} file, which can hold a log message 13608template (@pxref{rcsinfo}). @xref{verifymsg}. 13609 13610@item loginfo 13611The specified program is called when the commit is 13612complete. It receives the log message and some 13613additional information and can store the log message in 13614a file, or mail it to appropriate persons, or maybe 13615post it to a local newsgroup, or@dots{} Your 13616imagination is the limit! @xref{loginfo}. 13617@end table 13618 13619@menu 13620* Updating Commit Files:: Updating legacy repositories to stop using 13621 deprecated command line template formats 13622@end menu 13623 13624@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13625@node Updating Commit Files 13626@appendixsubsubsec Updating legacy repositories to stop using deprecated command line template formats 13627@cindex info files, common syntax, updating legacy repositories 13628@cindex Syntax of info files, updating legacy repositories 13629@cindex Common syntax of info files, updating legacy repositories 13630New repositories are created set to use the new format strings by default, so 13631if you are creating a new repository, you shouldn't have to worry about this 13632section. 13633 13634If you are attempting to maintain a legacy repository which was 13635making use of the @file{commitinfo}, @file{editinfo}, @file{verifymsg}, 13636@file{loginfo}, and/or @file{taginfo} script hooks, you should have no 13637immediate problems with using the current @sc{cvs} executable, but your users 13638will probably start to see deprecation warnings. 13639 13640The reason for this is that all of the script hooks have been updated to 13641use a new command line parser that extensibly supports multiple 13642@file{loginfo} & @file{notify} style format strings (@pxref{syntax}) 13643and this support is not completely compatible with the old style format 13644strings. 13645 13646The quick upgrade method is to stick a @samp{1} after each format string 13647in your old @file{loginfo} file. For example: 13648 13649@example 13650DEFAULT (echo ""; id; echo %@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13651@end example 13652 13653would become: 13654 13655@example 13656DEFAULT (echo ""; id; echo %1@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13657@end example 13658 13659If you were counting on the fact that only the first @samp{%} in the line was 13660replaced as a format string, you may also have to double up any further 13661percent signs on the line. 13662 13663If you did this all at once and checked it in, everything should still be 13664running properly. 13665 13666Now add the following line to your config file (@pxref{config}): 13667@example 13668UseNewInfoFmtStrings=yes 13669@end example 13670 13671Everything should still be running properly, but your users will probably 13672start seeing new deprecation warnings. 13673 13674Dealing with the deprecation warnings now generated by @file{commitinfo}, 13675@file{editinfo}, @file{verifymsg}, and @file{taginfo} should be easy. Simply 13676specify what are currently implicit arguments explicitly. This means appending 13677the following strings to each active command line template in each file: 13678@table @code 13679@item commitinfo 13680@samp{ %r/%p %s} 13681@item editinfo 13682@samp{ %l} 13683@item taginfo 13684@samp{ %t %o %p %@{sv@}} 13685@item verifymsg 13686@samp{ %l} 13687@end table 13688 13689If you don't desire that any of the newly available information be passed to 13690the scripts hanging off of these hooks, no further modifications to these 13691files should be necessary to insure current and future compatibility with 13692@sc{cvs}'s format strings. 13693 13694Fixing @file{loginfo} could be a little tougher. The old style 13695@file{loginfo} format strings caused a single space and comma separated 13696argument to be passed in in place of the format string. This is what will 13697continue to be generated due to the deprecated @samp{1} you inserted into 13698the format strings. 13699 13700Since the new format separates each individual item and passes it into the 13701script as a separate argument (for a good reason - arguments containing commas 13702and/or white space are now parsable), to remove the deprecated @samp{1} from 13703your @file{loginfo} command line templates, you will most likely have to 13704rewrite any scripts called by the hook to handle the new argument format. 13705 13706Also note that the way @samp{%} followed by unrecognized characters and by 13707@samp{@{@}} was treated in past versions of CVS is not strictly adhered to as 13708there were bugs in the old versions. Specifically, @samp{%@{@}} would eat the 13709next character and unrecognized strings resolved only to the empty string, 13710which was counter to what was stated in the documentation. This version will 13711do what the documentation said it should have (if you were using only some 13712combination of @samp{%@{sVv@}}, e.g. @samp{%@{sVv@}}, @samp{%@{sV@}}, or 13713@samp{%v}, you should have no troubles). 13714 13715On the bright side, you should have plenty of time to do this before all 13716support for the old format strings is removed from @sc{cvs}, so you can just 13717put up with the deprecation warnings for awhile if you like. 13718 13719@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13720@node commitinfo 13721@appendixsubsec Commitinfo 13722@cindex @file{commitinfo} 13723@cindex Commits, precommit verification of 13724@cindex commitinfo (admin file) 13725@cindex info files, commitinfo 13726@cindex script hooks, commitinfo 13727@cindex trigger scripts, commitinfo 13728@cindex info files, precommit verification of commits 13729@cindex script hooks, precommit verification of commits 13730@cindex trigger scripts, precommit verification of commits 13731 13732The @file{commitinfo} file defines programs to execute 13733whenever @samp{cvs commit} is about to execute. These 13734programs are used for pre-commit checking to verify 13735that the modified, added and removed files are really 13736ready to be committed. This could be used, for 13737instance, to verify that the changed files conform to 13738to your site's standards for coding practice. 13739 13740The @file{commitinfo} file has the standard form for script hooks 13741(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13742a command to execute. It supports only the DEFAULT keywords. 13743 13744@cindex format strings, commitinfo admin file 13745In addition to the common format strings (@pxref{syntax}), 13746@file{commitinfo} supports: 13747 13748@table @t 13749@item @{s@} 13750a list of the names of files to be committed 13751@end table 13752 13753@cindex commitinfo (admin file), updating legacy repositories 13754@cindex compatibility notes, commitinfo admin file 13755Currently, if no format strings are specified, a default 13756string of @samp{ %r/%p %@{s@}} will be appended to the command 13757line template before replacement is performed, but this 13758feature is deprecated. It is simply in place so that legacy 13759repositories will remain compatible with the new @sc{cvs} application. 13760For information on updating, @pxref{Updating Commit Files}. 13761 13762@cindex Exit status, of commitinfo 13763@cindex commitinfo (admin file), exit status 13764The first line with a regular expression matching the 13765directory within the repository will be used. If the 13766command returns a non-zero exit status the commit will 13767be aborted. 13768@c FIXME: need example(s) of what "directory within the 13769@c repository" means. 13770 13771@cindex @file{commitinfo}, working directory 13772@cindex @file{commitinfo}, command environment 13773The command will be run in the root of the workspace 13774containing the new versions of any files the user would like 13775to modify (commit), @emph{or in a copy of the workspace on 13776the server (@pxref{Remote repositories})}. If a file is 13777being removed, there will be no copy of the file under the 13778current directory. If a file is being added, there will be 13779no corresponding archive file in the repository unless the 13780file is being resurrected. 13781 13782Note that both the repository directory and the corresponding 13783Attic (@pxref{Attic}) directory may need to be checked to 13784locate the archive file corresponding to any given file being 13785committed. Much of the information about the specific commit 13786request being made, including the destination branch, commit 13787message, and command line options specified, is not available 13788to the command. 13789 13790@c FIXME: should discuss using commitinfo to control 13791@c who has checkin access to what (e.g. Joe can check into 13792@c directories a, b, and c, and Mary can check into 13793@c directories b, c, and d--note this case cannot be 13794@c conveniently handled with unix groups). Of course, 13795@c adding a new set of features to CVS might be a more 13796@c natural way to fix this problem than telling people to 13797@c use commitinfo. 13798@c FIXME: Should make some reference, especially in 13799@c the context of controlling who has access, to the fact 13800@c that commitinfo can be circumvented. Perhaps 13801@c mention SETXID (but has it been carefully examined 13802@c for holes?). This fits in with the discussion of 13803@c general CVS security in "Password authentication 13804@c security" (the bit which is not pserver-specific). 13805 13806@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13807@node verifymsg 13808@appendixsubsec Verifying log messages 13809@cindex @file{verifymsg} (admin file) 13810@cindex Log message, verifying 13811@cindex logging, commits 13812 13813Once you have entered a log message, you can evaluate 13814that message to check for specific content, such as 13815a bug ID. Use the @file{verifymsg} file to 13816specify a program that is used to verify the log message. 13817This program could be a simple script that checks 13818that the entered message contains the required fields. 13819 13820The @file{verifymsg} file is often most useful together 13821with the @file{rcsinfo} file, which can be used to 13822specify a log message template (@pxref{rcsinfo}). 13823 13824The @file{verifymsg} file has the standard form for script hooks 13825(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13826a command to execute. It supports only the DEFAULT keywords. 13827 13828@cindex format strings, verifymsg admin file 13829In addition to the common format strings (@pxref{syntax}), 13830@file{verifymsg} supports: 13831 13832@table @t 13833@item l 13834the full path to the file containing the log message to be verified 13835@item @{sV@} 13836File attributes, where: 13837@table @t 13838@item s 13839file name 13840@item V 13841old version number (pre-checkin) 13842@end table 13843@end table 13844 13845@cindex verifymsg (admin/commit file), updating legacy repositories 13846@cindex compatibility notes, verifymsg admin file 13847Currently, if no format strings are specified, a default 13848string of @samp{ %l} will be appended to the command 13849line template before replacement is performed, but this 13850feature is deprecated. It is simply in place so that legacy 13851repositories will remain compatible with the new @sc{cvs} application. 13852For information on updating, @pxref{Updating Commit Files}. 13853 13854One thing that should be noted is that the @samp{ALL} 13855keyword is not supported. If more than one matching 13856line is found, the first one is used. This can be 13857useful for specifying a default verification script in a 13858directory, and then overriding it in a subdirectory. 13859 13860@cindex Exit status, of @file{verifymsg} 13861If the verification script exits with a non-zero exit status, 13862the commit is aborted. 13863 13864@cindex @file{verifymsg}, changing the log message 13865In the default configuration, CVS allows the 13866verification script to change the log message. This is 13867controlled via the RereadLogAfterVerify CVSROOT/config 13868option. 13869 13870When @samp{RereadLogAfterVerify=always} or 13871@samp{RereadLogAfterVerify=stat}, the log message will 13872either always be reread after the verification script 13873is run or reread only if the log message file status 13874has changed. 13875 13876@xref{config}, for more on CVSROOT/config options. 13877 13878It is NOT a good idea for a @file{verifymsg} script to 13879interact directly with the user in the various 13880client/server methods. For the @code{pserver} method, 13881there is no protocol support for communicating between 13882@file{verifymsg} and the client on the remote end. For the 13883@code{ext} and @code{server} methods, it is possible 13884for CVS to become confused by the characters going 13885along the same channel as the CVS protocol 13886messages. See @ref{Remote repositories}, for more 13887information on client/server setups. In addition, at the time 13888the @file{verifymsg} script runs, the CVS 13889server has locks in place in the repository. If control is 13890returned to the user here then other users may be stuck waiting 13891for access to the repository. 13892 13893This option can be useful if you find yourself using an 13894rcstemplate that needs to be modified to remove empty 13895elements or to fill in default values. It can also be 13896useful if the rcstemplate has changed in the repository 13897and the CVS/Template was not updated, but is able to be 13898adapted to the new format by the verification script 13899that is run by @file{verifymsg}. 13900 13901An example of an update might be to change all 13902occurrences of 'BugId:' to be 'DefectId:' (which can be 13903useful if the rcstemplate has recently been changed and 13904there are still checked-out user trees with cached 13905copies in the CVS/Template file of the older version). 13906 13907Another example of an update might be to delete a line 13908that contains 'BugID: none' from the log message after 13909validation of that value as being allowed is made. 13910 13911@menu 13912* verifymsg example:: Verifymsg example 13913@end menu 13914 13915@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13916@node verifymsg example 13917@appendixsubsubsec Verifying log messages 13918@cindex verifymsg, example 13919The following is a little silly example of a 13920@file{verifymsg} file, together with the corresponding 13921@file{rcsinfo} file, the log message template and a 13922verification script. We begin with the log message template. 13923We want to always record a bug-id number on the first 13924line of the log message. The rest of log message is 13925free text. The following template is found in the file 13926@file{/usr/cvssupport/tc.template}. 13927 13928@example 13929BugId: 13930@end example 13931 13932The script @file{/usr/cvssupport/bugid.verify} is used to 13933evaluate the log message. 13934 13935@example 13936#!/bin/sh 13937# 13938# bugid.verify filename 13939# 13940# Verify that the log message contains a valid bugid 13941# on the first line. 13942# 13943if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 13944 exit 0 13945elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 13946 # It is okay to allow commits with 'BugId: none', 13947 # but do not put that text into the real log message. 13948 grep -v '^BugId:[ ]*none$' > $1.rewrite 13949 mv $1.rewrite $1 13950 exit 0 13951else 13952 echo "No BugId found." 13953 exit 1 13954fi 13955@end example 13956 13957The @file{verifymsg} file contains this line: 13958 13959@example 13960^tc /usr/cvssupport/bugid.verify %l 13961@end example 13962 13963The @file{rcsinfo} file contains this line: 13964 13965@example 13966^tc /usr/cvssupport/tc.template 13967@end example 13968 13969The @file{config} file contains this line: 13970 13971@example 13972RereadLogAfterVerify=always 13973@end example 13974 13975 13976 13977@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13978@node loginfo 13979@appendixsubsec Loginfo 13980@cindex loginfo (admin file) 13981@cindex logging, commits 13982@cindex Storing log messages 13983@cindex Mailing log messages 13984@cindex Distributing log messages 13985@cindex Log messages 13986 13987The @file{loginfo} file is used to control where log information is sent after 13988versioned changes are made to repository archive files and after directories 13989are added ot the repository. @ref{posttag} for how to log tagging 13990information and @ref{postadmin} for how to log changes due to the @code{admin} 13991command. 13992 13993The @file{loginfo} file has the standard form for script hooks 13994(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13995a command to execute. It supports the ALL and DEFAULT keywords. 13996 13997Any specified scripts are called: 13998 13999@table @code 14000@item commit 14001Once per directory, immediately after a successfully completing the commit of 14002all files within that directory. 14003@item import 14004Once per import, immediately after completion of all write operations. 14005@item add 14006Immediately after the successful @code{add} of a directory. 14007@end table 14008 14009Any script called via @file{loginfo} will be fed the log information on its 14010standard input. Note that the filter program @strong{must} read @strong{all} 14011of the log information from its standard input or @sc{cvs} may fail with a 14012broken pipe signal. 14013 14014@cindex format strings, loginfo admin file 14015In addition to the common format strings (@pxref{syntax}), 14016@file{loginfo} supports: 14017 14018@table @t 14019@item @{stVv@} 14020File attributes, where: 14021@table @t 14022@item s 14023file name 14024@item T 14025tag name of destination, or the empty string when there is no associated 14026tag name (this usually means the trunk) 14027@item V 14028old version number (pre-checkin) 14029@item v 14030new version number (post-checkin) 14031@end table 14032@end table 14033 14034For example, some valid format strings are @samp{%%}, 14035@samp{%s}, @samp{%@{s@}}, and @samp{%@{stVv@}}. 14036 14037@cindex loginfo (admin file), updating legacy repositories 14038@cindex compatibility notes, loginfo admin file 14039Currently, if @samp{UseNewInfoFmtStrings} is not set in the @file{config} 14040administration file (@pxref{config}), the format strings will be substituted 14041as they were in past versions of @sc{cvs}, but this feature is deprecated. 14042It is simply in place so that legacy repositories will remain compatible with 14043the new @sc{cvs} application. For information on updating, 14044please see @ref{Updating Commit Files}. 14045 14046As an example, if @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%p} 14047and @samp{%@{sVv@}} are the format strings, and three files (@t{ChangeLog}, 14048@t{Makefile}, @t{foo.c}) were modified, the output might be: 14049 14050@example 14051yoyodyne/tc ChangeLog 1.1 1.2 Makefile 1.3 1.4 foo.c 1.12 1.13 14052@end example 14053 14054Note: when @sc{cvs} is accessing a remote repository, 14055@file{loginfo} will be run on the @emph{remote} 14056(i.e., server) side, not the client side (@pxref{Remote 14057repositories}). 14058 14059@menu 14060* loginfo example:: Loginfo example 14061* Keeping a checked out copy:: Updating a tree on every checkin 14062@end menu 14063 14064@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14065@node loginfo example 14066@appendixsubsubsec Loginfo example 14067 14068The following @file{loginfo} file, together with the 14069tiny shell-script below, appends all log messages 14070to the file @file{$CVSROOT/CVSROOT/commitlog}, 14071and any commits to the administrative files (inside 14072the @file{CVSROOT} directory) are also logged in 14073@file{/usr/adm/cvsroot-log}. 14074Commits to the @file{prog1} directory are mailed to @t{ceder}. 14075 14076@c FIXME: is it a CVS feature or bug that only the 14077@c first matching line is used? It is documented 14078@c above, but is it useful? For example, if we wanted 14079@c to run both "cvs-log" and "Mail" for the CVSROOT 14080@c directory, it is kind of awkward if 14081@c only the first matching line is used. 14082@example 14083ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 14084^CVSROOT\(/\|$\) /usr/local/bin/cvs-log /usr/adm/cvsroot-log $USER 14085^prog1\(/\|$\) Mail -s "%p %s" ceder 14086@end example 14087 14088The shell-script @file{/usr/local/bin/cvs-log} looks 14089like this: 14090 14091@example 14092#!/bin/sh 14093(echo "------------------------------------------------------"; 14094 echo -n "$2 "; 14095 date; 14096 echo; 14097 cat) >> $1 14098@end example 14099 14100 14101 14102@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14103@node Keeping a checked out copy 14104@appendixsubsubsec Keeping a checked out copy 14105 14106@c What other index entries? It seems like 14107@c people might want to use a lot of different 14108@c words for this functionality. 14109@cindex Keeping a checked out copy 14110@cindex Checked out copy, keeping 14111@cindex Web pages, maintaining with CVS 14112 14113It is often useful to maintain a directory tree which 14114contains files which correspond to the latest version 14115in the repository. For example, other developers might 14116want to refer to the latest sources without having to 14117check them out, or you might be maintaining a web site 14118with @sc{cvs} and want every checkin to cause the files 14119used by the web server to be updated. 14120@c Can we offer more details on the web example? Or 14121@c point the user at how to figure it out? This text 14122@c strikes me as sufficient for someone who already has 14123@c some idea of what we mean but not enough for the naive 14124@c user/sysadmin to understand it and set it up. 14125 14126The way to do this is by having loginfo invoke 14127@code{cvs update}. Doing so in the naive way will 14128cause a problem with locks, so the @code{cvs update} 14129must be run in the background. 14130@c Should we try to describe the problem with locks? 14131@c It seems like a digression for someone who just 14132@c wants to know how to make it work. 14133@c Another choice which might work for a single file 14134@c is to use "cvs -n update -p" which doesn't take 14135@c out locks (I think) but I don't see many advantages 14136@c of that and we might as well document something which 14137@c works for multiple files. 14138Here is an example for unix (this should all be on one line): 14139 14140@example 14141^cyclic-pages\(/\|$\) (date; cat; (sleep 2; cd /u/www/local-docs; 14142 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 14143@end example 14144 14145This will cause checkins to repository directory @code{cyclic-pages} 14146and its subdirectories to update the checked 14147out tree in @file{/u/www/local-docs}. 14148@c More info on some of the details? The "sleep 2" is 14149@c so if we are lucky the lock will be gone by the time 14150@c we start and we can wait 2 seconds instead of 30. 14151 14152 14153 14154@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14155@node postadmin 14156@appendixsubsec Logging admin commands 14157@cindex postadmin (admin file) 14158@cindex script hook, postadmin 14159@cindex Admin commands, logging 14160 14161The @file{postadmin} file defines programs to execute after an @code{admin} 14162command modifies files. The @file{postadmin} file has the standard form 14163for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14164expression followed by a command to execute. It supports the ALL and DEFAULT 14165keywords. 14166 14167@cindex format strings, postadmin admin file 14168The @file{postadmin} file supports no format strings other than the common 14169ones (@pxref{syntax}), 14170 14171 14172 14173@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14174@node taginfo 14175@appendixsubsec Taginfo 14176@cindex taginfo (admin file) 14177@cindex script hook, taginfo 14178@cindex Tags, logging 14179@cindex Tags, verifying 14180The @file{taginfo} file defines programs to execute 14181when someone executes a @code{tag} or @code{rtag} 14182command. The @file{taginfo} file has the standard form 14183for script hooks (@pxref{Trigger Scripts}), where each line 14184is a regular expression followed by a command to execute. 14185It supports the ALL and DEFAULT keywords. 14186 14187@cindex format strings, taginfo admin file 14188In addition to the common format strings (@pxref{syntax}), 14189@file{taginfo} supports: 14190 14191@table @t 14192@item b 14193tag type (@code{T} for branch, @code{N} for not-branch, or @code{?} for 14194unknown, as during delete operations) 14195@item o 14196operation (@code{add} for @code{tag}, @code{mov} for @code{tag -F}, or 14197@code{del} for @code{tag -d}) 14198@item t 14199new tag name 14200@item @{sTVv@} 14201file attributes, where: 14202@table @t 14203@item s 14204file name 14205@item T 14206tag name of destination, or the empty string when there is no associated 14207tag name (this usually means the trunk) 14208@item V 14209old version number (for a move or delete operation) 14210@item v 14211new version number (for an add or move operation) 14212@end table 14213@end table 14214 14215For example, some valid format strings are @samp{%%}, @samp{%p}, @samp{%t}, 14216@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 14217 14218@cindex taginfo (admin file), updating legacy repositories 14219@cindex compatibility notes, taginfo admin file 14220Currently, if no format strings are specified, a default 14221string of @samp{ %t %o %p %@{sv@}} will be appended to the command 14222line template before replacement is performed, but this 14223feature is deprecated. It is simply in place so that legacy 14224repositories will remain compatible with the new @sc{cvs} application. 14225For information on updating, @pxref{Updating Commit Files}. 14226 14227@cindex Exit status, of taginfo admin file 14228@cindex taginfo (admin file), exit status 14229A non-zero exit of the filter program will cause the tag to be 14230aborted. 14231 14232Here is an example of using @file{taginfo} to log @code{tag} and @code{rtag} 14233commands. In the @file{taginfo} file put: 14234 14235@example 14236ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %@{sVv@} 14237@end example 14238 14239@noindent 14240Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 14241following script: 14242 14243@example 14244#!/bin/sh 14245echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 14246@end example 14247 14248 14249 14250@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14251@node posttag 14252@appendixsubsec Logging tags 14253@cindex posttag (admin file) 14254@cindex script hook, posttag 14255@cindex Tags, logging 14256 14257The @file{posttag} file defines programs to execute after a @code{tag} or 14258@code{rtag} command modifies files. The @file{posttag} file has the standard 14259form for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14260expression followed by a command to execute. It supports the ALL and DEFAULT 14261keywords. 14262 14263@cindex format strings, posttag admin file 14264The @file{posttag} admin file supports the same format strings as the 14265@file{taginfo} file (@pxref{taginfo}), 14266 14267 14268 14269@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14270@node postwatch 14271@appendixsubsec Logging watch commands 14272@cindex postwatch (admin file) 14273@cindex script hook, postwatch 14274@cindex Watch family of commands, logging 14275 14276The @file{postwatch} file defines programs to execute after any command (for 14277instance, @code{watch}, @code{edit}, @code{unedit}, or @code{commit}) modifies 14278any @file{CVS/fileattr} file in the repository (@pxref{Watches}). The 14279@file{postwatch} file has the standard form for script hooks 14280(@pxref{Trigger Scripts}), where each line is a regular expression followed by 14281a command to execute. It supports the ALL and DEFAULT keywords. 14282 14283@cindex format strings, postwatch admin file 14284The @file{postwatch} file supports no format strings other than the common 14285ones (@pxref{syntax}), but it is worth noting that the @code{%c} format string 14286may not be replaced as you might expect. Client runs of @code{edit} and 14287@code{unedit} can sometimes skip contacting the @sc{cvs} server and cache the 14288notification of the file attribute change to be sent the next time the client 14289contacts the server for whatever other reason, 14290 14291 14292 14293@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14294@node preproxy 14295@appendixsubsec Launch a Script before Proxying 14296@cindex preproxy (admin file) 14297@cindex script hook, preproxy 14298@cindex Write proxy, verifying 14299@cindex Write proxy, logging 14300 14301The @file{preproxy} file defines programs to execute after a secondary 14302server receives a write request from a client, just before it starts up the 14303primary server and becomes a write proxy. This hook could be used to 14304dial a modem, launch an SSH tunnel, establish a VPN, or anything else that 14305might be necessary to do before contacting the primary server. 14306 14307@file{preproxy} scripts are called once, at the time of the write request, with 14308the repository argument (if requested) set from the topmost directory sent by 14309the client. 14310 14311The @file{preproxy} file has the standard form 14312for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14313expression followed by a command to execute. It supports the ALL and DEFAULT 14314keywords. 14315 14316@cindex format strings, preproxy admin file 14317In addition to the common format strings, the @file{preproxy} file supports the 14318following format string: 14319 14320@table @t 14321@item P 14322the CVSROOT string which specifies the primary server 14323@end table 14324 14325 14326 14327@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14328@node postproxy 14329@appendixsubsec Launch a Script after Proxying 14330@cindex postproxy (admin file) 14331@cindex script hook, postproxy 14332@cindex Write proxy, logging 14333@cindex Write proxy, pull updates 14334@cindex secondary server, pull updates 14335 14336The @file{postproxy} file defines programs to execute after a secondary 14337server notes that the connection to the primary server has shut down and before 14338it releases the client by shutting down the connection to the client. 14339This could hook could be used to 14340disconnect a modem, an SSH tunnel, a VPN, or anything else that 14341might be necessary to do after contacting the primary server. This hook should 14342also be used to pull updates from the primary server before allowing the client 14343which did the write to disconnect since otherwise the client's next read 14344request may generate error messages and fail upon encountering an out of date 14345repository on the secondary server. 14346 14347@file{postproxy} scripts are called once per directory. 14348 14349The @file{postproxy} file has the standard form 14350for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14351expression followed by a command to execute. It supports the ALL and DEFAULT 14352keywords. 14353 14354@cindex format strings, postproxy admin file 14355In addition to the common format strings, the @file{postproxy} file supports 14356the following format string: 14357 14358@table @t 14359@item P 14360the CVSROOT string which specifies the primary server 14361@end table 14362 14363 14364 14365@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14366@node rcsinfo 14367@appendixsec Rcsinfo 14368@cindex rcsinfo (admin file) 14369@cindex Form for log message 14370@cindex Log message template 14371@cindex Template for log message 14372@cindex logging, commits 14373 14374The @file{rcsinfo} file can be used to specify a form to 14375edit when filling out the commit log. The 14376@file{rcsinfo} file has a syntax similar to the 14377@file{verifymsg}, @file{commitinfo} and @file{loginfo} 14378files. @xref{syntax}. Unlike the other files the second 14379part is @emph{not} a command-line template. Instead, 14380the part after the regular expression should be a full pathname to 14381a file containing the log message template. 14382 14383If the repository name does not match any of the 14384regular expressions in this file, the @samp{DEFAULT} 14385line is used, if it is specified. 14386 14387All occurrences of the name @samp{ALL} appearing as a 14388regular expression are used in addition to the first 14389matching regular expression or @samp{DEFAULT}. 14390 14391@c FIXME: should be offering advice, somewhere around 14392@c here, about where to put the template file. The 14393@c verifymsg example uses /usr/cvssupport but doesn't 14394@c say anything about what that directory is for or 14395@c whether it is hardwired into CVS or who creates 14396@c it or anything. In particular we should say 14397@c how to version control the template file. A 14398@c probably better answer than the /usr/cvssupport 14399@c stuff is to use checkoutlist (with xref to the 14400@c checkoutlist doc). 14401@c Also I am starting to see a connection between 14402@c this and the Keeping a checked out copy node. 14403@c Probably want to say something about that. 14404The log message template will be used as a default log 14405message. If you specify a log message with @samp{cvs 14406commit -m @var{message}} or @samp{cvs commit -f 14407@var{file}} that log message will override the 14408template. 14409 14410@xref{verifymsg}, for an example @file{rcsinfo} 14411file. 14412 14413When @sc{cvs} is accessing a remote repository, 14414the contents of @file{rcsinfo} at the time a directory 14415is first checked out will specify a template. This 14416template will be updated on all @samp{cvs update} 14417commands. It will also be added to new directories 14418added with a @samp{cvs add new-directory} command. 14419In versions of @sc{cvs} prior to version 1.12, the 14420@file{CVS/Template} file was not updated. If the 14421@sc{cvs} server is at version 1.12 or higher an older 14422client may be used and the @file{CVS/Template} will 14423be updated from the server. 14424 14425@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14426@node cvsignore 14427@appendixsec Ignoring files via cvsignore 14428@cindex cvsignore (admin file), global 14429@cindex Global cvsignore 14430@cindex Ignoring files 14431@c -- This chapter should maybe be moved to the 14432@c tutorial part of the manual? 14433 14434There are certain file names that frequently occur 14435inside your working copy, but that you don't want to 14436put under @sc{cvs} control. Examples are all the object 14437files that you get while you compile your sources. 14438Normally, when you run @samp{cvs update}, it prints a 14439line for each file it encounters that it doesn't know 14440about (@pxref{update output}). 14441 14442@sc{cvs} has a list of files (or sh(1) file name patterns) 14443that it should ignore while running @code{update}, 14444@code{import} and @code{release}. 14445@c -- Are those the only three commands affected? 14446This list is constructed in the following way. 14447 14448@itemize @bullet 14449@item 14450The list is initialized to include certain file name 14451patterns: names associated with @sc{cvs} 14452administration, or with other common source control 14453systems; common names for patch files, object files, 14454archive files, and editor backup files; and other names 14455that are usually artifacts of assorted utilities. 14456Currently, the default list of ignored file name 14457patterns is: 14458 14459@cindex Ignored files 14460@cindex Automatically ignored files 14461@example 14462 RCS SCCS CVS CVS.adm 14463 RCSLOG cvslog.* 14464 tags TAGS 14465 .make.state .nse_depinfo 14466 *~ #* .#* ,* _$* *$ 14467 *.old *.bak *.BAK *.orig *.rej .del-* 14468 *.a *.olb *.o *.obj *.so *.exe 14469 *.Z *.elc *.ln 14470 core 14471@end example 14472 14473@item 14474The per-repository list in 14475@file{$CVSROOT/CVSROOT/cvsignore} is appended to 14476the list, if that file exists. 14477 14478@item 14479The per-user list in @file{.cvsignore} in your home 14480directory is appended to the list, if it exists. 14481 14482@item 14483Any entries in the environment variable 14484@code{$CVSIGNORE} is appended to the list. 14485 14486@item 14487Any @samp{-I} options given to @sc{cvs} is appended. 14488 14489@item 14490As @sc{cvs} traverses through your directories, the contents 14491of any @file{.cvsignore} will be appended to the list. 14492The patterns found in @file{.cvsignore} are only valid 14493for the directory that contains them, not for 14494any sub-directories. 14495@end itemize 14496 14497In any of the 5 places listed above, a single 14498exclamation mark (@samp{!}) clears the ignore list. 14499This can be used if you want to store any file which 14500normally is ignored by @sc{cvs}. 14501 14502Specifying @samp{-I !} to @code{cvs import} will import 14503everything, which is generally what you want to do if 14504you are importing files from a pristine distribution or 14505any other source which is known to not contain any 14506extraneous files. However, looking at the rules above 14507you will see there is a fly in the ointment; if the 14508distribution contains any @file{.cvsignore} files, then 14509the patterns from those files will be processed even if 14510@samp{-I !} is specified. The only workaround is to 14511remove the @file{.cvsignore} files in order to do the 14512import. Because this is awkward, in the future 14513@samp{-I !} might be modified to override 14514@file{.cvsignore} files in each directory. 14515 14516Note that the syntax of the ignore files consists of a 14517series of lines, each of which contains a space 14518separated list of filenames. This offers no clean way 14519to specify filenames which contain spaces, but you can 14520use a workaround like @file{foo?bar} to match a file 14521named @file{foo bar} (it also matches @file{fooxbar} 14522and the like). Also note that there is currently no 14523way to specify comments. 14524@c FIXCVS? I don't _like_ this syntax at all, but 14525@c changing it raises all the usual compatibility 14526@c issues and I'm also not sure what to change it to. 14527 14528@node checkoutlist 14529@appendixsec The checkoutlist file 14530@cindex checkoutlist 14531 14532It may be helpful to use @sc{cvs} to maintain your own 14533files in the @file{CVSROOT} directory. For example, 14534suppose that you have a script @file{logcommit.pl} 14535which you run by including the following line in the 14536@file{commitinfo} administrative file: 14537 14538@example 14539ALL $CVSROOT/CVSROOT/logcommit.pl %r/%p %s 14540@end example 14541 14542To maintain @file{logcommit.pl} with @sc{cvs} you would 14543add the following line to the @file{checkoutlist} 14544administrative file: 14545 14546@example 14547logcommit.pl 14548@end example 14549 14550The format of @file{checkoutlist} is one line for each 14551file that you want to maintain using @sc{cvs}, giving 14552the name of the file, followed optionally by more whitespace 14553and any error message that should print if the file cannot be 14554checked out into CVSROOT after a commit: 14555 14556@example 14557logcommit.pl Could not update CVSROOT/logcommit.pl. 14558@end example 14559 14560After setting up @file{checkoutlist} in this fashion, 14561the files listed there will function just like 14562@sc{cvs}'s built-in administrative files. For example, 14563when checking in one of the files you should get a 14564message such as: 14565 14566@example 14567cvs commit: Rebuilding administrative file database 14568@end example 14569 14570@noindent 14571and the checked out copy in the @file{CVSROOT} 14572directory should be updated. 14573 14574Note that listing @file{passwd} (@pxref{Password 14575authentication server}) in @file{checkoutlist} is not 14576recommended for security reasons. 14577 14578For information about keeping a checkout out copy in a 14579more general context than the one provided by 14580@file{checkoutlist}, see @ref{Keeping a checked out 14581copy}. 14582 14583@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14584@node history file 14585@appendixsec The history file 14586@cindex History file 14587@cindex Log information, saving 14588 14589By default, the file @file{$CVSROOT/CVSROOT/history} is used 14590to log information for the @code{history} command (@pxref{history}). 14591This file name may be changed with the @samp{HistoryLogPath} and 14592@samp{HistorySearchPath} config options (@pxref{config}). 14593 14594The file format of the @file{history} file is 14595documented only in comments in the @sc{cvs} source 14596code, but generally programs should use the @code{cvs 14597history} command to access it anyway, in case the 14598format changes with future releases of @sc{cvs}. 14599 14600@node Variables 14601@appendixsec Expansions in administrative files 14602@cindex Internal variables 14603@cindex Variables 14604 14605Sometimes in writing an administrative file, you might 14606want the file to be able to know various things based 14607on environment @sc{cvs} is running in. There are 14608several mechanisms to do that. 14609 14610To find the home directory of the user running @sc{cvs} 14611(from the @code{HOME} environment variable), use 14612@samp{~} followed by @samp{/} or the end of the line. 14613Likewise for the home directory of @var{user}, use 14614@samp{~@var{user}}. These variables are expanded on 14615the server machine, and don't get any reasonable 14616expansion if pserver (@pxref{Password authenticated}) 14617is in use; therefore user variables (see below) may be 14618a better choice to customize behavior based on the user 14619running @sc{cvs}. 14620@c Based on these limitations, should we deprecate ~? 14621@c What is it good for? Are people using it? 14622 14623One may want to know about various pieces of 14624information internal to @sc{cvs}. A @sc{cvs} internal 14625variable has the syntax @code{$@{@var{variable}@}}, 14626where @var{variable} starts with a letter and consists 14627of alphanumeric characters and @samp{_}. If the 14628character following @var{variable} is a 14629non-alphanumeric character other than @samp{_}, the 14630@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 14631internal variables are: 14632 14633@table @code 14634@item CVSROOT 14635@cindex CVSROOT, internal variable 14636This is the absolute path to the current @sc{cvs} root directory. 14637@xref{Repository}, for a description of the various 14638ways to specify this, but note that the internal 14639variable contains just the directory and not any 14640of the access method information. 14641 14642@item RCSBIN 14643@cindex RCSBIN, internal variable 14644In @sc{cvs} 1.9.18 and older, this specified the 14645directory where @sc{cvs} was looking for @sc{rcs} 14646programs. Because @sc{cvs} no longer runs @sc{rcs} 14647programs, specifying this internal variable is now an 14648error. 14649 14650@item CVSEDITOR 14651@cindex CVSEDITOR, internal variable 14652@itemx EDITOR 14653@cindex EDITOR, internal variable 14654@itemx VISUAL 14655@cindex VISUAL, internal variable 14656These all expand to the same value, which is the editor 14657that @sc{cvs} is using. @xref{Global options}, for how 14658to specify this. 14659 14660@item USER 14661@cindex USER, internal variable 14662Username of the user running @sc{cvs} (on the @sc{cvs} 14663server machine). 14664When using pserver, this is the user specified in the repository 14665specification which need not be the same as the username the 14666server is running as (@pxref{Password authentication server}). 14667Do not confuse this with the environment variable of the same name. 14668 14669@item SESSIONID 14670@cindex COMMITID, internal variable 14671Unique Session ID of the @sc{cvs} process. This is a 14672random string of printable characters of at least 16 14673characters length. Users should assume that it may 14674someday grow to at most 256 characters in length. 14675 14676@item COMMITID 14677@cindex COMMITID, internal variable 14678Unique Session ID of the @sc{cvs} process. This is a 14679random string of printable characters of at least 16 14680characters length. Users should assume that it may 14681someday grow to at most 256 characters in length. 14682@end table 14683 14684If you want to pass a value to the administrative files 14685which the user who is running @sc{cvs} can specify, 14686use a user variable. 14687@cindex User variables 14688To expand a user variable, the 14689administrative file contains 14690@code{$@{=@var{variable}@}}. To set a user variable, 14691specify the global option @samp{-s} to @sc{cvs}, with 14692argument @code{@var{variable}=@var{value}}. It may be 14693particularly useful to specify this option via 14694@file{.cvsrc} (@pxref{~/.cvsrc}). 14695 14696For example, if you want the administrative file to 14697refer to a test directory you might create a user 14698variable @code{TESTDIR}. Then if @sc{cvs} is invoked 14699as 14700 14701@example 14702cvs -s TESTDIR=/work/local/tests 14703@end example 14704 14705@noindent 14706and the 14707administrative file contains @code{sh 14708$@{=TESTDIR@}/runtests}, then that string is expanded 14709to @code{sh /work/local/tests/runtests}. 14710 14711All other strings containing @samp{$} are reserved; 14712there is no way to quote a @samp{$} character so that 14713@samp{$} represents itself. 14714 14715Environment variables passed to administrative files are: 14716 14717@table @code 14718@cindex environment variables, passed to administrative files 14719 14720@item CVS_USER 14721@cindex CVS_USER, environment variable 14722The @sc{cvs}-specific username provided by the user, if it 14723can be provided (currently just for the pserver access 14724method), and to the empty string otherwise. (@code{CVS_USER} 14725and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 14726is used to map @sc{cvs} usernames to system usernames.) 14727 14728@item LOGNAME 14729@cindex LOGNAME, environment variable 14730The username of the system user. 14731 14732@item USER 14733@cindex USER, environment variable 14734Same as @code{LOGNAME}. 14735Do not confuse this with the internal variable of the same name. 14736@end table 14737 14738@node config 14739@appendixsec The CVSROOT/config configuration file 14740 14741@cindex configuration file 14742@cindex config, in CVSROOT 14743@cindex CVSROOT/config 14744 14745Usually, the @file{config} file is found at @file{$CVSROOT/CVSROOT/config}, 14746but this may be overridden on the @code{pserver} and @code{server} command 14747lines (@pxref{server & pserver}). 14748 14749The administrative file @file{config} contains various 14750miscellaneous settings which affect the behavior of 14751@sc{cvs}. The syntax is slightly different from the 14752other administrative files. 14753 14754Leading white space on any line is ignored, though the syntax is very strict 14755and will reject spaces and tabs almost anywhere else. 14756 14757Empty lines, lines containing nothing but white space, and lines which start 14758with @samp{#} (discounting any leading white space) are ignored. 14759 14760@c FIXME: where do we define comments for the other 14761@c administrative files. 14762Other lines consist of the optional leading white space, a keyword, @samp{=}, 14763and a value. Please note again that this syntax is very strict. 14764Extraneous spaces or tabs, other than the leading white space, are not 14765permitted on these lines. 14766@c See comments in parseinfo.c:parse_config for more 14767@c discussion of this strictness. 14768 14769As of CVS 1.12.13, lines of the form @samp{[@var{CVSROOT}]} mark the subsequent 14770section of the config file as applying only to certain repositories. Multiple 14771@samp{[@var{CVSROOT}]} lines without intervening 14772@samp{@var{KEYWORD}=@var{VALUE}} pairs cause processing to fall through, 14773processing subsequent keywords for any root in the list. Finally, keywords 14774and values which appear before any @samp{[@var{CVSROOT}]} lines are defaults, 14775and may to apply to any repository. For example, consider the following file: 14776 14777@example 14778# Defaults 14779LogHistory=TMAR 14780 14781[/cvsroots/team1] 14782 LockDir=/locks/team1 14783 14784[/cvsroots/team2] 14785 LockDir=/locks/team2 14786 14787[/cvsroots/team3] 14788 LockDir=/locks/team3 14789 14790[/cvsroots/team4] 14791 LockDir=/locks/team4 14792 14793[/cvsroots/team3] 14794[/cvsroots/team4] 14795 # Override logged commands for teams 3 & 4. 14796 LogHistory=all 14797@end example 14798 14799This example file sets up separate lock directories for each project, as well 14800as a default set of logged commands overridden for the example's team 3 & 14801team 4. This syntax could be useful, for instance, if you wished to share a 14802single config file, for instance @file{/etc/cvs.conf}, among several 14803repositories. 14804 14805Currently defined keywords are: 14806 14807@table @code 14808@cindex HistoryLogPath, in CVSROOT/config 14809@item HistorySearchPath=@var{pattern} 14810Request that @sc{cvs} look for its history information in files matching 14811@var{pattern}, which is a standard UNIX file glob. If @var{pattern} matches 14812multiple files, all will be searched in lexicographically sorted order. 14813@xref{history}, and @ref{history file}, for more. 14814 14815If no value is supplied for this option, it defaults to 14816@file{$CVSROOT/CVSROOT/history}. 14817 14818@cindex HistorySearchPath, in CVSROOT/config 14819@item HistoryLogPath=@var{path} 14820Control where @sc{cvs} logs its history. If the file does not exist, @sc{cvs} 14821will attempt to create it. Format strings, as available to the GNU C 14822@code{strftime} function and often the UNIX date command, and the string 14823@var{$CVSROOT} will be substituted in this path. For example, consider the 14824line: 14825 14826@example 14827HistoryLogPath=$CVSROOT/CVSROOT/history/%Y-%m-%d 14828@end example 14829 14830This line would cause @sc{cvs} to attempt to create its history file in a 14831subdirectory (@file{history}) of the configuration directory (@file{CVSROOT}) 14832with a name equal to the current date representation in the ISO8601 format (for 14833example, on May 11, 2005, @sc{cvs} would attempt to log its history under the 14834repository root directory in a file named @file{CVSROOT/history/2005-05-11}). 14835@xref{history}, and @ref{history file}, for more. 14836 14837If no value is supplied for this option, it defaults to 14838@file{$CVSROOT/CVSROOT/history}. 14839 14840@cindex ImportNewFilesToVendorBranchOnly, in CVSROOT/config 14841@cindex import, config admin file 14842@cindex config (admin file), import 14843@item ImportNewFilesToVendorBranchOnly=@var{value} 14844Specify whether @code{cvs import} should always behave as if the 14845@samp{-X} flag was specified on the command line. 14846@var{value} may be either @samp{yes} or @samp{no}. If set to @samp{yes}, 14847all uses of @code{cvs import} on the repository will behave as if the 14848@samp{-X} flag was set. The default value is @samp{no}. 14849 14850@cindex KeywordExpand, in CVSROOT/config 14851@item KeywordExpand=@var{value} 14852Specify @samp{i} followed by a list of keywords to be expanded 14853(for example, @samp{KeywordExpand=iMYCVS,Name,Date}), 14854or @samp{e} followed by a list of keywords not to be expanded 14855(for example, @samp{KeywordExpand=eCVSHeader}). 14856For more on keyword expansion, see @ref{Configuring keyword expansion}. 14857 14858@cindex LocalKeyword, in CVSROOT/config 14859@item LocalKeyword=@var{value} 14860Specify a local alias for a standard keyword. 14861For example, @samp{LocalKeyword=MYCVS=CVSHeader}. 14862For more on local keywords, see @ref{Keyword substitution}. 14863 14864@cindex LockDir, in CVSROOT/config 14865@item LockDir=@var{directory} 14866Put @sc{cvs} lock files in @var{directory} rather than 14867directly in the repository. This is useful if you want 14868to let users read from the repository while giving them 14869write access only to @var{directory}, not to the 14870repository. 14871It can also be used to put the locks on a very fast 14872in-memory file system to speed up locking and unlocking 14873the repository. 14874You need to create @var{directory}, but 14875@sc{cvs} will create subdirectories of @var{directory} as it 14876needs them. For information on @sc{cvs} locks, see 14877@ref{Concurrency}. 14878 14879@c Mention this in Compatibility section? 14880Before enabling the LockDir option, make sure that you 14881have tracked down and removed any copies of @sc{cvs} 1.9 or 14882older. Such versions neither support LockDir, nor will 14883give an error indicating that they don't support it. 14884The result, if this is allowed to happen, is that some 14885@sc{cvs} users will put the locks one place, and others will 14886put them another place, and therefore the repository 14887could become corrupted. @sc{cvs} 1.10 does not support 14888LockDir but it will print a warning if run on a 14889repository with LockDir enabled. 14890 14891@cindex LogHistory, in CVSROOT/config 14892@item LogHistory=@var{value} 14893Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). 14894Default of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log 14895all transactions. Any subset of the default is 14896legal. (For example, to only log transactions that modify the 14897@file{*,v} files, use @samp{LogHistory=TMAR}.) To disable history logging 14898completely, use @samp{LogHistory=}. 14899 14900@cindex MaxCommentLeaderLength, in CVSROOT/config 14901@cindex Log keyword, configuring substitution behavior 14902@item MaxCommentLeaderLength=@var{length} 14903Set to some length, in bytes, where a trailing @samp{k}, @samp{M}, @samp{G}, 14904or @samp{T} causes the preceding nubmer to be interpreted as kilobytes, 14905megabytes, gigabytes, or terrabytes, respectively, will cause 14906@code{$@splitrcskeyword{Log}$} keywords (@pxref{Keyword substitution}), with 14907more than @var{length} bytes preceding it on a line to be ignored (or to fall 14908back on the comment leader set in the RCS archive file - see 14909@code{UseArchiveCommentLeader} below). Defaults to 20 bytes to allow checkouts 14910to proceed normally when they include binary files containing 14911@code{$@splitrcskeyword{Log}$} keywords and which users have neglected to mark 14912as binary. 14913 14914@cindex MinCompressionLevel, in CVSROOT/config 14915@cindex MaxCompressionLevel, in CVSROOT/config 14916@cindex Compression levels, restricting on server 14917@item MinCompressionLevel=@var{value} 14918@itemx MaxCompressionLevel=@var{value} 14919Restricts the level of compression used by the @sc{cvs} server to a @var{value} 14920between 0 and 9. @var{value}s 1 through 9 are the same @sc{zlib} compression 14921levels accepted by the @samp{-z} option (@pxref{Global options}), and 0 means 14922no compression. When one or both of these keys are set and a client requests a 14923level outside the specified range, the server will simply use the closest 14924permissable level. Clients will continue compressing at the level requested by 14925the user. 14926 14927The exception is when level 0 (no compression) is not available and the client 14928fails to request any compression. The @sc{cvs} server will then exit with an 14929error message when it becomes apparent that the client is not going to request 14930compression. This will not happen with clients version 1.12.13 and later since 14931these client versions allow the server to notify them that they must request 14932some level of compression. 14933 14934@ignore 14935@cindex PreservePermissions, in CVSROOT/config 14936@item PreservePermissions=@var{value} 14937Enable support for saving special device files, 14938symbolic links, file permissions and ownerships in the 14939repository. The default value is @samp{no}. 14940@xref{Special Files}, for the full implications of using 14941this keyword. 14942@end ignore 14943 14944@cindex PrimaryServer, in CVSROOT/config 14945@cindex Primary server 14946@cindex Secondary server 14947@cindex proxy, write 14948@cindex write proxy 14949@item PrimaryServer=@var{CVSROOT} 14950When specified, and the repository specified by @var{CVSROOT} is not the one 14951currently being accessed, then the server will turn itself into a transparent 14952proxy to @var{CVSROOT} for write requests. The @var{hostname} configured as 14953part of @var{CVSROOT} must resolve to the same string returned by the 14954@command{uname} command on the primary server for this to work. Host name 14955resolution is performed via some combination of @command{named}, a broken out 14956line from @file{/etc/hosts}, and the Network Information Service (NIS or YP), 14957depending on the configuration of the particular system. 14958 14959Only the @samp{:ext:} method is 14960currently supported for primaries (actually, @samp{:fork:} is supported as 14961well, but only for testing - if you find another use for accessing a primary 14962via the @samp{:fork:} method, please send a note to @email{bug-cvs@@nongnu.org} 14963about it). See @ref{Write proxies} for more on configuring and using write 14964proxies. 14965 14966@cindex RCSBIN, in CVSROOT/config 14967@item RCSBIN=@var{bindir} 14968For @sc{cvs} 1.9.12 through 1.9.18, this setting told 14969@sc{cvs} to look for @sc{rcs} programs in the 14970@var{bindir} directory. Current versions of @sc{cvs} 14971do not run @sc{rcs} programs; for compatibility this 14972setting is accepted, but it does nothing. 14973 14974@cindex RereadLogAfterVerify, in CVSROOT/config 14975@cindex @file{verifymsg}, changing the log message 14976@item RereadLogAfterVerify=@var{value} 14977Modify the @samp{commit} command such that CVS will reread the 14978log message after running the program specified by @file{verifymsg}. 14979@var{value} may be one of @samp{yes} or @samp{always}, indicating that 14980the log message should always be reread; @samp{no} 14981or @samp{never}, indicating that it should never be 14982reread; or @var{value} may be @samp{stat}, indicating 14983that the file should be checked with the file system 14984@samp{stat()} function to see if it has changed (see warning below) 14985before rereading. The default value is @samp{always}. 14986 14987@strong{Note: the `stat' mode can cause CVS to pause for up to 14988one extra second per directory committed. This can be less IO and 14989CPU intensive but is not recommended for use with large repositories} 14990 14991@xref{verifymsg}, for more information on how verifymsg 14992may be used. 14993 14994@cindex SystemAuth, in CVSROOT/config 14995@item SystemAuth=@var{value} 14996If @var{value} is @samp{yes}, then pserver should check 14997for users in the system's user database if not found in 14998@file{CVSROOT/passwd}. If it is @samp{no}, then all 14999pserver users must exist in @file{CVSROOT/passwd}. 15000The default is @samp{yes}. For more on pserver, see 15001@ref{Password authenticated}. 15002 15003@cindex TmpDir, in config 15004@cindex temporary files, location of 15005@cindex temporary directory, set in config 15006@item TmpDir=@var{path} 15007Specify @var{path} as the directory to create temporary files in. 15008@xref{Global options}, for more on setting the path to the temporary 15009directory. This option first appeared with @sc{cvs} release 1.12.13. 15010 15011@cindex TopLevelAdmin, in CVSROOT/config 15012@item TopLevelAdmin=@var{value} 15013Modify the @samp{checkout} command to create a 15014@samp{CVS} directory at the top level of the new 15015working directory, in addition to @samp{CVS} 15016directories created within checked-out directories. 15017The default value is @samp{no}. 15018 15019This option is useful if you find yourself performing 15020many commands at the top level of your working 15021directory, rather than in one of the checked out 15022subdirectories. The @file{CVS} directory created there 15023will mean you don't have to specify @code{CVSROOT} for 15024each command. It also provides a place for the 15025@file{CVS/Template} file (@pxref{Working directory 15026storage}). 15027 15028@cindex UseArchiveCommentLeader, in CVSROOT/config 15029@cindex Log keyword, configuring substitution behavior 15030@item UseArchiveCommentLeader=@var{value} 15031Set to @code{true}, if the text preceding a @code{$@splitrcskeyword{Log}$} 15032keyword is found to exceed @code{MaxCommentLeaderLength} (above) bytes, then 15033the comment leader set in the RCS archive file (@pxref{admin}), if any, will 15034be used instead. If there is no comment leader set in the archive file or 15035@var{value} is set to @samp{false}, then the keyword will not be expanded 15036(@pxref{Keyword list}). To force the comment leader in the RCS archive file to 15037be used exclusively (and @code{$@splitrcskeyword{Log}$} expansion skipped in 15038files where the comment leader has not been set in the archive file), set 15039@var{value} and set @code{MaxCommentLeaderLength} to @code{0}. 15040 15041@cindex UseNewInfoFmtStrings, in CVSROOT/config 15042@cindex format strings, config admin file 15043@cindex config (admin file), updating legacy repositories 15044@cindex compatibility notes, config admin file 15045@item UseNewInfoFmtStrings=@var{value} 15046Specify whether @sc{cvs} should support the new or old command line 15047template model for the commit support files (@pxref{commit files}). 15048This configuration variable began life in deprecation and is only here 15049in order to give people time to update legacy repositories to use the new 15050format string syntax before support for the old syntax is removed. For 15051information on updating your repository to support the new model, 15052please see @ref{Updating Commit Files}. 15053 15054@emph{Note that new repositories (created with the @code{cvs init} command) 15055will have this value set to @samp{yes}, but the default value is @samp{no}.} 15056 15057@cindex UserAdminOptions, in CVSROOT/config 15058@item UserAdminOptions=@var{value} 15059Control what options will be allowed with the @code{cvs admin} 15060command (@pxref{admin}) for users not in the @code{cvsadmin} group. 15061The @var{value} string is a list of single character options 15062which should be allowed. If a user who is not a member of the 15063@code{cvsadmin} group tries to execute any @code{cvs admin} 15064option which is not listed they will will receive an error message 15065reporting that the option is restricted. 15066 15067If no @code{cvsadmin} group exists on the server, @sc{cvs} will 15068ignore the @code{UserAdminOptions} keyword (@pxref{admin}). 15069 15070When not specified, @code{UserAdminOptions} defaults to 15071@samp{k}. In other words, it defaults to allowing 15072users outside of the @code{cvsadmin} group to use the 15073@code{cvs admin} command only to change the default keyword 15074expansion mode for files. 15075 15076As an example, to restrict users not in the @code{cvsadmin} 15077group to using @code{cvs admin} to change the default keyword 15078substitution mode, lock revisions, unlock revisions, and 15079replace the log message, use @samp{UserAdminOptions=klum}. 15080@end table 15081 15082 15083 15084@c --------------------------------------------------------------------- 15085@node Environment variables 15086@appendix All environment variables which affect CVS 15087@cindex Environment variables 15088@cindex Reference manual for variables 15089 15090This is a complete list of all environment variables 15091that affect @sc{cvs} (Windows users, please bear with this list; 15092$VAR is equivalent to %VAR% at the Windows command prompt). 15093 15094@table @code 15095@cindex CVSIGNORE, environment variable 15096@item $CVSIGNORE 15097A whitespace-separated list of file name patterns that 15098@sc{cvs} should ignore. @xref{cvsignore}. 15099 15100@cindex CVSWRAPPERS, environment variable 15101@item $CVSWRAPPERS 15102A whitespace-separated list of file name patterns that 15103@sc{cvs} should treat as wrappers. @xref{Wrappers}. 15104 15105@cindex CVSREAD, environment variable 15106@cindex Read-only files, and CVSREAD 15107@item $CVSREAD 15108If this is set, @code{checkout} and @code{update} will 15109try hard to make the files in your working directory 15110read-only. When this is not set, the default behavior 15111is to permit modification of your working files. 15112 15113@cindex CVSREADONLYFS, environment variable 15114@item $CVSREADONLYFS 15115Turns on read-only repository mode. This allows one to 15116check out from a read-only repository, such as within 15117an anoncvs server, or from a @sc{cd-rom} repository. 15118 15119It has the same effect as if the @samp{-R} command-line 15120option is used. This can also allow the use of 15121read-only NFS repositories. 15122 15123@item $CVSUMASK 15124Controls permissions of files in the repository. See 15125@ref{File permissions}. 15126 15127@item $CVSROOT 15128Should contain the full pathname to the root of the @sc{cvs} 15129source repository (where the @sc{rcs} files are 15130kept). This information must be available to @sc{cvs} for 15131most commands to execute; if @code{$CVSROOT} is not set, 15132or if you wish to override it for one invocation, you 15133can supply it on the command line: @samp{cvs -d cvsroot 15134cvs_command@dots{}} Once you have checked out a working 15135directory, @sc{cvs} stores the appropriate root (in 15136the file @file{CVS/Root}), so normally you only need to 15137worry about this when initially checking out a working 15138directory. 15139 15140@item $CVSEDITOR 15141@cindex CVSEDITOR, environment variable 15142@itemx $EDITOR 15143@cindex EDITOR, environment variable 15144@itemx $VISUAL 15145@cindex VISUAL, environment variable 15146Specifies the program to use for recording log messages 15147during commit. @code{$CVSEDITOR} overrides 15148@code{$EDITOR}, which overrides @code{$VISUAL}. 15149See @ref{Committing your changes} for more or 15150@ref{Global options} for alternative ways of specifying a 15151log editor. 15152 15153@cindex PATH, environment variable 15154@item $PATH 15155If @code{$RCSBIN} is not set, and no path is compiled 15156into @sc{cvs}, it will use @code{$PATH} to try to find all 15157programs it uses. 15158 15159@cindex HOME, environment variable 15160@item $HOME 15161@cindex HOMEPATH, environment variable 15162@item $HOMEPATH 15163@cindex HOMEDRIVE, environment variable 15164@item $HOMEDRIVE 15165Used to locate the directory where the @file{.cvsrc} 15166file, and other such files, are searched. On Unix, @sc{cvs} 15167just checks for @code{HOME}. On Windows NT, the system will 15168set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 15169for example to @file{\joe}. On Windows 95, you'll 15170probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 15171@c We are being vague about whether HOME works on 15172@c Windows; see long comment in windows-NT/filesubr.c. 15173 15174@cindex CVS_RSH, environment variable 15175@item $CVS_RSH 15176Specifies the external program which @sc{cvs} connects with, 15177when @code{:ext:} access method is specified. 15178@pxref{Connecting via rsh}. 15179 15180@item $CVS_SERVER 15181Used in client-server mode when accessing a remote 15182repository using @sc{rsh}. It specifies the name of 15183the program to start on the server side (and any 15184necessary arguments) when accessing a remote repository 15185using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 15186The default value for @code{:ext:} and @code{:server:} is @code{cvs}; 15187the default value for @code{:fork:} is the name used to run the client. 15188@pxref{Connecting via rsh} 15189 15190@item $CVS_PASSFILE 15191Used in client-server mode when accessing the @code{cvs 15192login server}. Default value is @file{$HOME/.cvspass}. 15193@pxref{Password authentication client} 15194 15195@cindex CVS_CLIENT_PORT 15196@item $CVS_CLIENT_PORT 15197Used in client-server mode to set the port to use when accessing the server 15198via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 15199if the port is not specified in the CVSROOT. 15200@pxref{Remote repositories} 15201 15202@cindex CVS_PROXY_PORT 15203@item $CVS_PROXY_PORT 15204Used in client-server mode to set the port to use when accessing a server 15205via a web proxy, if the port is not specified in the CVSROOT. Works with 15206GSSAPI, and the password authentication protocol. 15207@pxref{Remote repositories} 15208 15209@cindex CVS_RCMD_PORT, environment variable 15210@item $CVS_RCMD_PORT 15211Used in client-server mode. If set, specifies the port 15212number to be used when accessing the @sc{rcmd} demon on 15213the server side. (Currently not used for Unix clients). 15214 15215@cindex CVS_CLIENT_LOG, environment variable 15216@item $CVS_CLIENT_LOG 15217Used for debugging only in client-server 15218mode. If set, everything sent to the server is logged 15219into @file{@code{$CVS_CLIENT_LOG}.in} and everything 15220sent from the server is logged into 15221@file{@code{$CVS_CLIENT_LOG}.out}. 15222 15223@cindex CVS_SERVER_SLEEP, environment variable 15224@item $CVS_SERVER_SLEEP 15225Used only for debugging the server side in 15226client-server mode. If set, delays the start of the 15227server child process the specified amount of 15228seconds so that you can attach to it with a debugger. 15229 15230@cindex CVS_IGNORE_REMOTE_ROOT, environment variable 15231@item $CVS_IGNORE_REMOTE_ROOT 15232For @sc{cvs} 1.10 and older, setting this variable 15233prevents @sc{cvs} from overwriting the @file{CVS/Root} 15234file when the @samp{-d} global option is specified. 15235Later versions of @sc{cvs} do not rewrite 15236@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 15237effect. 15238 15239@cindex CVS_LOCAL_BRANCH_NUM, environment variable 15240@item $CVS_LOCAL_BRANCH_NUM 15241Setting this variable allows some control over the 15242branch number that is assigned. This is specifically to 15243support the local commit feature of CVSup. If one sets 15244@code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches 15245the local repository, the revision numbers will look 15246like 1.66.1000.xx. There is almost a dead-set certainty 15247that there will be no conflicts with version numbers. 15248 15249@cindex COMSPEC, environment variable 15250@item $COMSPEC 15251Used under OS/2 only. It specifies the name of the 15252command interpreter and defaults to @sc{cmd.exe}. 15253 15254@cindex TMPDIR, environment variable 15255@cindex temporary file directory, set via environment variable 15256@cindex temporary files, location of 15257@item $TMPDIR 15258Directory in which temporary files are located. 15259@xref{Global options}, for more on setting the temporary directory. 15260 15261@cindex CVS_PID, environment variable 15262@item $CVS_PID 15263This is the process identification (aka pid) number of 15264the @sc{cvs} process. It is often useful in the 15265programs and/or scripts specified by the 15266@file{commitinfo}, @file{verifymsg}, @file{loginfo} 15267files. 15268@end table 15269 15270@node Compatibility 15271@appendix Compatibility between CVS Versions 15272 15273@cindex CVS, versions of 15274@cindex Versions, of CVS 15275@cindex Compatibility, between CVS versions 15276@c We don't mention versions older than CVS 1.3 15277@c on the theory that it would clutter it up for the vast 15278@c majority of people, who don't have anything that old. 15279@c 15280The repository format is compatible going back to 15281@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 15282you have copies of @sc{cvs} 1.6 or older and you want 15283to use the optional developer communication features. 15284@c If you "cvs rm" and commit using 1.3, then you'll 15285@c want to run "rcs -sdead <file,v>" on each of the 15286@c files in the Attic if you then want 1.5 and 15287@c later to recognize those files as dead (I think the 15288@c symptom if this is not done is that files reappear 15289@c in joins). (Wait: the above will work but really to 15290@c be strictly correct we should suggest checking 15291@c in a new revision rather than just changing the 15292@c state of the head revision, shouldn't we?). 15293@c The old convert.sh script was for this, but it never 15294@c did get updated to reflect use of the RCS "dead" 15295@c state. 15296@c Note: this is tricky to document without confusing 15297@c people--need to carefully say what CVS version we 15298@c are talking about and keep in mind the distinction 15299@c between a 15300@c repository created with 1.3 and on which one now 15301@c uses 1.5+, and a repository on which one wants to 15302@c use both versions side by side (e.g. during a 15303@c transition period). 15304@c Wait, can't CVS just detect the case in which a file 15305@c is in the Attic but the head revision is not dead? 15306@c Not sure whether this should produce a warning or 15307@c something, and probably needs further thought, but 15308@c it would appear that the situation can be detected. 15309@c 15310@c We might want to separate out the 1.3 compatibility 15311@c section (for repository & working directory) from the 15312@c rest--that might help avoid confusing people who 15313@c are upgrading (for example) from 1.6 to 1.8. 15314@c 15315@c A minor incompatibility is if a current version of CVS 15316@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 15317@c see this as if there is no tag. Seems to me this is 15318@c too obscure to mention. 15319 15320The working directory format is compatible going back 15321to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 15322and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 15323a working directory checked out with @sc{cvs} 1.3, 15324@sc{cvs} will convert it, but to go back to @sc{cvs} 153251.3 you need to check out a new working directory with 15326@sc{cvs} 1.3. 15327 15328The remote protocol is interoperable going back to @sc{cvs} 1.5, but no 15329further (1.5 was the first official release with the remote protocol, 15330but some older versions might still be floating around). In many 15331cases you need to upgrade both the client and the server to take 15332advantage of new features and bug fixes, however. 15333 15334@c Perhaps should be saying something here about the 15335@c "D" lines in Entries (written by CVS 1.9; 1.8 and 15336@c older don't use them). These are supposed to be 15337@c compatible in both directions, but I'm not sure 15338@c they quite are 100%. One common gripe is if you 15339@c "rm -r" a directory and 1.9 gets confused, as it 15340@c still sees it in Entries. That one is fixed in 15341@c (say) 1.9.6. Someone else reported problems with 15342@c starting with a directory which was checked out with 15343@c an old version, and then using a new version, and 15344@c some "D" lines appeared, but not for every 15345@c directory, causing some directories to be skipped. 15346@c They weren't sure how to reproduce this, though. 15347 15348@c --------------------------------------------------------------------- 15349@node Troubleshooting 15350@appendix Troubleshooting 15351 15352If you are having trouble with @sc{cvs}, this appendix 15353may help. If there is a particular error message which 15354you are seeing, then you can look up the message 15355alphabetically. If not, you can look through the 15356section on other problems to see if your problem is 15357mentioned there. 15358 15359@menu 15360* Error messages:: Partial list of CVS errors 15361* Connection:: Trouble making a connection to a CVS server 15362* Other problems:: Problems not readily listed by error message 15363@end menu 15364 15365@ignore 15366@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 15367@c @node Bad administrative files 15368@appendixsec Bad administrative files 15369 15370@c -- Give hints on how to fix them 15371@end ignore 15372 15373@node Error messages 15374@appendixsec Partial list of error messages 15375 15376Here is a partial list of error messages that you may 15377see from @sc{cvs}. It is not a complete list---@sc{cvs} 15378is capable of printing many, many error messages, often 15379with parts of them supplied by the operating system, 15380but the intention is to list the common and/or 15381potentially confusing error messages. 15382 15383The messages are alphabetical, but introductory text 15384such as @samp{cvs update: } is not considered in 15385ordering them. 15386 15387In some cases the list includes messages printed by old 15388versions of @sc{cvs} (partly because users may not be 15389sure which version of @sc{cvs} they are using at any 15390particular moment). 15391@c If we want to start retiring messages, perhaps we 15392@c should pick a cutoff version (for example, no more 15393@c messages which are specific to versions before 1.9) 15394@c and then move the old messages to an "old messages" 15395@c node rather than deleting them completely. 15396 15397@table @code 15398@c FIXME: What is the correct way to format a multiline 15399@c error message here? Maybe @table is the wrong 15400@c choice? Texinfo gurus? 15401@item @var{file}:@var{line}: Assertion '@var{text}' failed 15402The exact format of this message may vary depending on 15403your system. It indicates a bug in @sc{cvs}, which can 15404be handled as described in @ref{BUGS}. 15405 15406@item cvs @var{command}: authorization failed: server @var{host} rejected access 15407This is a generic response when trying to connect to a 15408pserver server which chooses not to provide a 15409specific reason for denying authorization. Check that 15410the username and password specified are correct and 15411that the @code{CVSROOT} specified is allowed by @samp{--allow-root} 15412in @file{inetd.conf}. See @ref{Password authenticated}. 15413 15414@item cvs @var{command}: conflict: removed @var{file} was modified by second party 15415This message indicates that you removed a file, and 15416someone else modified it. To resolve the conflict, 15417first run @samp{cvs add @var{file}}. If desired, look 15418at the other party's modification to decide whether you 15419still want to remove it. If you don't want to remove 15420it, stop here. If you do want to remove it, proceed 15421with @samp{cvs remove @var{file}} and commit your 15422removal. 15423@c Tests conflicts2-142b* in sanity.sh test for this. 15424 15425@item cannot change permissions on temporary directory 15426@example 15427Operation not permitted 15428@end example 15429This message has been happening in a non-reproducible, 15430occasional way when we run the client/server testsuite, 15431both on Red Hat Linux 3.0.3 and 4.1. We haven't been 15432able to figure out what causes it, nor is it known 15433whether it is specific to Linux (or even to this 15434particular machine!). If the problem does occur on 15435other unices, @samp{Operation not permitted} would be 15436likely to read @samp{Not owner} or whatever the system 15437in question uses for the unix @code{EPERM} error. If 15438you have any information to add, please let us know as 15439described in @ref{BUGS}. If you experience this error 15440while using @sc{cvs}, retrying the operation which 15441produced it should work fine. 15442@c This has been seen in a variety of tests, including 15443@c multibranch-2, multibranch-5, and basic1-24-rm-rm, 15444@c so it doesn't seem particularly specific to any one 15445@c test. 15446 15447@item cvs [server aborted]: Cannot check out files into the repository itself 15448The obvious cause for this message (especially for 15449non-client/server @sc{cvs}) is that the @sc{cvs} root 15450is, for example, @file{/usr/local/cvsroot} and you try 15451to check out files when you are in a subdirectory, such 15452as @file{/usr/local/cvsroot/test}. However, there is a 15453more subtle cause, which is that the temporary 15454directory on the server is set to a subdirectory of the 15455root (which is also not allowed). If this is the 15456problem, set the temporary directory to somewhere else, 15457for example @file{/var/tmp}; see @code{TMPDIR} in 15458@ref{Environment variables}, for how to set the 15459temporary directory. 15460 15461@item cannot commit files as 'root' 15462See @samp{'root' is not allowed to commit files}. 15463 15464@c For one example see basica-1a10 in the testsuite 15465@c For another example, "cvs co ." on NT; see comment 15466@c at windows-NT/filesubr.c (expand_wild). 15467@c For another example, "cvs co foo/bar" where foo exists. 15468@item cannot open CVS/Entries for reading: No such file or directory 15469This generally indicates a @sc{cvs} internal error, and 15470can be handled as with other @sc{cvs} bugs 15471(@pxref{BUGS}). Usually there is a workaround---the 15472exact nature of which would depend on the situation but 15473which hopefully could be figured out. 15474 15475@c This is more obscure than it might sound; it only 15476@c happens if you run "cvs init" from a directory which 15477@c contains a CVS/Root file at the start. 15478@item cvs [init aborted]: cannot open CVS/Root: No such file or directory 15479This message is harmless. Provided it is not 15480accompanied by other errors, the operation has 15481completed successfully. This message should not occur 15482with current versions of @sc{cvs}, but it is documented 15483here for the benefit of @sc{cvs} 1.9 and older. 15484 15485@item cvs server: cannot open /root/.cvsignore: Permission denied 15486@itemx cvs [server aborted]: can't chdir(/root): Permission denied 15487See @ref{Connection}. 15488 15489@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 15490This message has been reported as intermittently 15491happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 15492unknown; if you know more about what causes it, let us 15493know as described in @ref{BUGS}. 15494 15495@item cvs [@var{command} aborted]: cannot start server via rcmd 15496This, unfortunately, is a rather nonspecific error 15497message which @sc{cvs} 1.9 will print if you are 15498running the @sc{cvs} client and it is having trouble 15499connecting to the server. Current versions of @sc{cvs} 15500should print a much more specific error message. If 15501you get this message when you didn't mean to run the 15502client at all, you probably forgot to specify 15503@code{:local:}, as described in @ref{Repository}. 15504 15505@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 15506@sc{cvs} 1.9 and older will print this message 15507when trying to check in a binary file if 15508@sc{rcs} is not correctly installed. Re-read the 15509instructions that came with your @sc{rcs} distribution 15510and the @sc{install} file in the @sc{cvs} 15511distribution. Alternately, upgrade to a current 15512version of @sc{cvs}, which checks in files itself 15513rather than via @sc{rcs}. 15514 15515@item cvs checkout: could not check out @var{file} 15516With @sc{cvs} 1.9, this can mean that the @code{co} program 15517(part of @sc{rcs}) returned a failure. It should be 15518preceded by another error message, however it has been 15519observed without another error message and the cause is 15520not well-understood. With the current version of @sc{cvs}, 15521which does not run @code{co}, if this message occurs 15522without another error message, it is definitely a @sc{cvs} 15523bug (@pxref{BUGS}). 15524@c My current suspicion is that the RCS in the rcs (not 15525@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 15526@c CD is bad (remains to be confirmed). 15527@c There is also a report of something which looks 15528@c very similar on SGI, Irix 5.2, so I dunno. 15529 15530@item cvs [login aborted]: could not find out home directory 15531This means that you need to set the environment 15532variables that @sc{cvs} uses to locate your home directory. 15533See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 15534@ref{Environment variables}. 15535 15536@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 15537@sc{cvs} 1.9 and older will print this message if there was 15538a problem finding the @code{rcsmerge} program. Make 15539sure that it is in your @code{PATH}, or upgrade to a 15540current version of @sc{cvs}, which does not require 15541an external @code{rcsmerge} program. 15542 15543@item cvs [update aborted]: could not patch @var{file}: No such file or directory 15544This means that there was a problem finding the 15545@code{patch} program. Make sure that it is in your 15546@code{PATH}. Note that despite appearances the message 15547is @emph{not} referring to whether it can find @var{file}. 15548If both the client and the server are running a current 15549version of @sc{cvs}, then there is no need for an 15550external patch program and you should not see this 15551message. But if either client or server is running 15552@sc{cvs} 1.9, then you need @code{patch}. 15553 15554@item cvs update: could not patch @var{file}; will refetch 15555This means that for whatever reason the client was 15556unable to apply a patch that the server sent. The 15557message is nothing to be concerned about, because 15558inability to apply the patch only slows things down and 15559has no effect on what @sc{cvs} does. 15560@c xref to update output. Or File status? 15561@c Or some place else that 15562@c explains this whole "patch"/P/Needs Patch thing? 15563 15564@item dying gasps from @var{server} unexpected 15565There is a known bug in the server for @sc{cvs} 1.9.18 15566and older which can cause this. For me, this was 15567reproducible if I used the @samp{-t} global option. It 15568was fixed by Andy Piper's 14 Nov 1997 change to 15569src/filesubr.c, if anyone is curious. 15570If you see the message, 15571you probably can just retry the operation which failed, 15572or if you have discovered information concerning its 15573cause, please let us know as described in @ref{BUGS}. 15574 15575@item end of file from server (consult above messages if any) 15576The most common cause for this message is if you are 15577using an external @code{rsh} program and it exited with 15578an error. In this case the @code{rsh} program should 15579have printed a message, which will appear before the 15580above message. For more information on setting up a 15581@sc{cvs} client and server, see @ref{Remote repositories}. 15582 15583@item cvs [update aborted]: EOF in key in RCS file @var{file},v 15584@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 15585This means that there is a syntax error in the given 15586@sc{rcs} file. Note that this might be true even if @sc{rcs} can 15587read the file OK; @sc{cvs} does more error checking of 15588errors in the RCS file. That is why you may see this 15589message when upgrading from @sc{cvs} 1.9 to @sc{cvs} 155901.10. The likely cause for the original corruption is 15591hardware, the operating system, or the like. Of 15592course, if you find a case in which @sc{cvs} seems to 15593corrupting the file, by all means report it, 15594(@pxref{BUGS}). 15595There are quite a few variations of this error message, 15596depending on exactly where in the @sc{rcs} file @sc{cvs} 15597finds the syntax error. 15598 15599@cindex mkmodules 15600@item cvs commit: Executing 'mkmodules' 15601This means that your repository is set up for a version 15602of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 156031.8 or later, the above message will be preceded by 15604 15605@example 15606cvs commit: Rebuilding administrative file database 15607@end example 15608 15609If you see both messages, the database is being rebuilt 15610twice, which is unnecessary but harmless. If you wish 15611to avoid the duplication, and you have no versions of 15612@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 15613every place it appears in your @code{modules} 15614file. For more information on the @code{modules} file, 15615see @ref{modules}. 15616 15617@c This message comes from "co", and I believe is 15618@c possible only with older versions of CVS which call 15619@c co. The problem with being able to create the bogus 15620@c RCS file still exists, though (and I think maybe 15621@c there is a different symptom(s) now). 15622@c FIXME: Would be nice to have a more exact wording 15623@c for this message. 15624@item missing author 15625Typically this can happen if you created an RCS file 15626with your username set to empty. @sc{cvs} will, bogusly, 15627create an illegal RCS file with no value for the author 15628field. The solution is to make sure your username is 15629set to a non-empty value and re-create the RCS file. 15630@c "make sure your username is set" is complicated in 15631@c and of itself, as there are the environment 15632@c variables the system login name, &c, and it depends 15633@c on the version of CVS. 15634 15635@item cvs [checkout aborted]: no such tag @var{tag} 15636This message means that @sc{cvs} isn't familiar with 15637the tag @var{tag}. Usually the root cause is that you have 15638mistyped a tag name. Ocassionally this can also occur because the 15639users creating tags do not have permissions to write to the 15640@file{CVSROOT/val-tags} file (@pxref{File permissions}, for more). 15641 15642Prior to @sc{cvs} version 1.12.10, there were a few relatively 15643obscure cases where a given tag could be created in an archive 15644file in the repository but @sc{cvs} would require the user to 15645@c Search sanity.sh for "no such tag" to see some of 15646@c the relatively obscure cases. 15647try a few other @sc{cvs} commands involving that tag 15648until one was found whch caused @sc{cvs} to update 15649@cindex CVSROOT/val-tags file, forcing tags into 15650@cindex val-tags file, forcing tags into 15651the @file{val-tags} file, at which point the originally failing command 15652would begin to work. This same method can be used to repair a @file{val-tags} 15653file that becomes out of date due to the permissions problem mentioned above. 15654This updating is only required once per tag - once a tag is listed in 15655@file{val-tags}, it stays there. 15656 15657Note that using @samp{tag -f} to not require tag matches did not and 15658does not override this check (@pxref{Common options}). 15659 15660@item *PANIC* administration files missing 15661This typically means that there is a directory named 15662@sc{cvs} but it does not contain the administrative files 15663which @sc{cvs} puts in a CVS directory. If the problem is 15664that you created a CVS directory via some mechanism 15665other than @sc{cvs}, then the answer is simple, use a name 15666other than @sc{cvs}. If not, it indicates a @sc{cvs} bug 15667(@pxref{BUGS}). 15668 15669@item rcs error: Unknown option: -x,v/ 15670This message will be followed by a usage message for 15671@sc{rcs}. It means that you have an old version of 15672@sc{rcs} (probably supplied with your operating 15673system), as well as an old version of @sc{cvs}. 15674@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 15675later; current versions of @sc{cvs} do not run @sc{rcs} programs. 15676@c For more information on installing @sc{cvs}, see 15677@c (FIXME: where? it depends on whether you are 15678@c getting binaries or sources or what). 15679@c The message can also say "ci error" or something 15680@c instead of "rcs error", I suspect. 15681 15682@item cvs [server aborted]: received broken pipe signal 15683This message can be caused by a loginfo program that fails to 15684read all of the log information from its standard input. 15685If you find it happening in any other circumstances, 15686please let us know as described in @ref{BUGS}. 15687 15688@item 'root' is not allowed to commit files 15689When committing a permanent change, @sc{cvs} makes a log entry of 15690who committed the change. If you are committing the change logged 15691in as "root" (not under "su" or other root-priv giving program), 15692@sc{cvs} cannot determine who is actually making the change. 15693As such, by default, @sc{cvs} disallows changes to be committed by users 15694logged in as "root". (You can disable this option by passing the 15695@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 15696On some systems this means editing the appropriate @file{config.h} file 15697before building @sc{cvs}.) 15698 15699@item cvs [server aborted]: Secondary out of sync with primary! 15700 15701This usually means that the version of @sc{cvs} running on a secondary 15702server is incompatible with the version running on the primary server 15703(@pxref{Write proxies}). 15704This will not occur if the client supports redirection. 15705 15706It is not the version number that is significant here, but the list of 15707supported requests that the servers provide to the client. 15708For example, even if both servers were the same version, 15709if the secondary was compiled with GSSAPI support and the primary was not, 15710the list of supported requests provided by the two servers 15711would be different and the secondary would not work as a transparent 15712proxy to the primary. 15713Conversely, even if the two servers were radically different versions 15714but both provided the same list of valid requests to the client, 15715the transparent proxy would succeed. 15716 15717@item Terminated with fatal signal 11 15718This message usually indicates that @sc{cvs} (the server, if you're 15719using client/server mode) has run out of (virtual) memory. 15720Although @sc{cvs} tries to catch the error and issue a more meaningful 15721message, there are many circumstances where that is not possible. 15722If you appear to have lots of memory available to the system, 15723the problem is most likely that you're running into a system-wide 15724limit on the amount of memory a single process can use or a 15725similar process-specific limit. 15726The mechanisms for displaying and setting such limits vary from 15727system to system, so you'll have to consult an expert for your 15728particular system if you don't know how to do that. 15729 15730@item Too many arguments! 15731This message is typically printed by the @file{log.pl} 15732script which is in the @file{contrib} directory in the 15733@sc{cvs} source distribution. In some versions of 15734@sc{cvs}, @file{log.pl} has been part of the default 15735@sc{cvs} installation. The @file{log.pl} script gets 15736called from the @file{loginfo} administrative file. 15737Check that the arguments passed in @file{loginfo} match 15738what your version of @file{log.pl} expects. In 15739particular, the @file{log.pl} from @sc{cvs} 1.3 and 15740older expects the log file as an argument whereas the 15741@file{log.pl} from @sc{cvs} 1.5 and newer expects the 15742log file to be specified with a @samp{-f} option. Of 15743course, if you don't need @file{log.pl} you can just 15744comment it out of @file{loginfo}. 15745 15746@item cvs [update aborted]: unexpected EOF reading @var{file},v 15747See @samp{EOF in key in RCS file}. 15748 15749@item cvs [login aborted]: unrecognized auth response from @var{server} 15750This message typically means that the server is not set 15751up properly. For example, if @file{inetd.conf} points 15752to a nonexistent cvs executable. To debug it further, 15753find the log file which inetd writes 15754(@file{/var/log/messages} or whatever inetd uses on 15755your system). For details, see @ref{Connection}, and 15756@ref{Password authentication server}. 15757 15758@item cvs commit: Up-to-date check failed for `@var{file}' 15759This means that someone else has committed a change to 15760that file since the last time that you did a @code{cvs 15761update}. So before proceeding with your @code{cvs 15762commit} you need to @code{cvs update}. @sc{cvs} will merge 15763the changes that you made and the changes that the 15764other person made. If it does not detect any conflicts 15765it will report @samp{M @var{file}} and you are ready 15766to @code{cvs commit}. If it detects conflicts it will 15767print a message saying so, will report @samp{C @var{file}}, 15768and you need to manually resolve the 15769conflict. For more details on this process see 15770@ref{Conflicts example}. 15771 15772@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 15773@example 15774Only one of [exEX3] allowed 15775@end example 15776This indicates a problem with the installation of 15777@code{diff3} and @code{rcsmerge}. Specifically 15778@code{rcsmerge} was compiled to look for GNU diff3, but 15779it is finding unix diff3 instead. The exact text of 15780the message will vary depending on the system. The 15781simplest solution is to upgrade to a current version of 15782@sc{cvs}, which does not rely on external 15783@code{rcsmerge} or @code{diff3} programs. 15784 15785@item warning: unrecognized response `@var{text}' from cvs server 15786If @var{text} contains a valid response (such as 15787@samp{ok}) followed by an extra carriage return 15788character (on many systems this will cause the second 15789part of the message to overwrite the first part), then 15790it probably means that you are using the @samp{:ext:} 15791access method with a version of rsh, such as most 15792non-unix rsh versions, which does not by default 15793provide a transparent data stream. In such cases you 15794probably want to try @samp{:server:} instead of 15795@samp{:ext:}. If @var{text} is something else, this 15796may signify a problem with your @sc{cvs} server. 15797Double-check your installation against the instructions 15798for setting up the @sc{cvs} server. 15799@c FIXCVS: should be printing CR as \r or \015 or some 15800@c such, probably. 15801 15802@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 15803This is a normal message, not an error. See 15804@ref{Concurrency}, for more details. 15805 15806@item cvs commit: warning: editor session failed 15807@cindex Exit status, of editor 15808This means that the editor which @sc{cvs} is using exits with a nonzero 15809exit status. Some versions of vi will do this even when there was not 15810a problem editing the file. If so, point the 15811@code{CVSEDITOR} environment variable to a small script 15812such as: 15813 15814@example 15815#!/bin/sh 15816vi $* 15817exit 0 15818@end example 15819 15820@item cvs update: warning: @var{file} was lost 15821This means that the working copy of @var{file} has been deleted 15822but it has not been removed from @sc{cvs}. 15823This is nothing to be concerned about, 15824the update will just recreate the local file from the repository. 15825(This is a convenient way to discard local changes to a file: 15826just delete it and then run @code{cvs update}.) 15827 15828@item cvs update: warning: @var{file} is not (any longer) pertinent 15829This means that the working copy of @var{file} has been deleted, 15830it has not been removed from @sc{cvs} in the current working directory, 15831but it has been removed from @sc{cvs} in some other working directory. 15832This is nothing to be concerned about, 15833the update would have removed the local file anyway. 15834 15835@end table 15836 15837@node Connection 15838@appendixsec Trouble making a connection to a CVS server 15839 15840This section concerns what to do if you are having 15841trouble making a connection to a @sc{cvs} server. If 15842you are running the @sc{cvs} command line client 15843running on Windows, first upgrade the client to 15844@sc{cvs} 1.9.12 or later. The error reporting in 15845earlier versions provided much less information about 15846what the problem was. If the client is non-Windows, 15847@sc{cvs} 1.9 should be fine. 15848 15849If the error messages are not sufficient to track down 15850the problem, the next steps depend largely on which 15851access method you are using. 15852 15853@table @code 15854@cindex :ext:, troubleshooting 15855@item :ext: 15856Try running the rsh program from the command line. For 15857example: "rsh servername cvs -v" should print @sc{cvs} 15858version information. If this doesn't work, you need to 15859fix it before you can worry about @sc{cvs} problems. 15860 15861@cindex :server:, troubleshooting 15862@item :server: 15863You don't need a command line rsh program to use this 15864access method, but if you have an rsh program around, 15865it may be useful as a debugging tool. Follow the 15866directions given for :ext:. 15867 15868@cindex :pserver:, troubleshooting 15869@item :pserver: 15870Errors along the lines of "connection refused" typically indicate 15871that inetd isn't even listening for connections on port 2401 15872whereas errors like "connection reset by peer", 15873"received broken pipe signal", "recv() from server: EOF", 15874or "end of file from server" 15875typically indicate that inetd is listening for 15876connections but is unable to start @sc{cvs} (this is frequently 15877caused by having an incorrect path in @file{inetd.conf} 15878or by firewall software rejecting the connection). 15879"unrecognized auth response" errors are caused by a bad command 15880line in @file{inetd.conf}, typically an invalid option or forgetting 15881to put the @samp{pserver} command at the end of the line. 15882Another less common problem is invisible control characters that 15883your editor "helpfully" added without you noticing. 15884 15885One good debugging tool is to "telnet servername 158862401". After connecting, send any text (for example 15887"foo" followed by return). If @sc{cvs} is working 15888correctly, it will respond with 15889 15890@example 15891cvs [pserver aborted]: bad auth protocol start: foo 15892@end example 15893 15894If instead you get: 15895 15896@example 15897Usage: cvs [cvs-options] command [command-options-and-arguments] 15898... 15899@end example 15900 15901@noindent 15902then you're missing the @samp{pserver} command at the end of the 15903line in @file{inetd.conf}; check to make sure that the entire command 15904is on one line and that it's complete. 15905 15906Likewise, if you get something like: 15907 15908@example 15909Unknown command: `pserved' 15910 15911CVS commands are: 15912 add Add a new file/directory to the repository 15913... 15914@end example 15915 15916@noindent 15917then you've misspelled @samp{pserver} in some way. If it isn't 15918obvious, check for invisible control characters (particularly 15919carriage returns) in @file{inetd.conf}. 15920 15921If it fails to work at all, then make sure inetd is working 15922right. Change the invocation in @file{inetd.conf} to run the 15923echo program instead of cvs. For example: 15924 15925@example 159262401 stream tcp nowait root /bin/echo echo hello 15927@end example 15928 15929After making that change and instructing inetd to 15930re-read its configuration file, "telnet servername 159312401" should show you the text hello and then the 15932server should close the connection. If this doesn't 15933work, you need to fix it before you can worry about 15934@sc{cvs} problems. 15935 15936On AIX systems, the system will often have its own 15937program trying to use port 2401. This is AIX's problem 15938in the sense that port 2401 is registered for use with 15939@sc{cvs}. I hear that there is an AIX patch available 15940to address this problem. 15941 15942Another good debugging tool is the @samp{-d} 15943(debugging) option to inetd. Consult your system 15944documentation for more information. 15945 15946If you seem to be connecting but get errors like: 15947 15948@example 15949cvs server: cannot open /root/.cvsignore: Permission denied 15950cvs [server aborted]: can't chdir(/root): Permission denied 15951@end example 15952 15953@noindent 15954then you probably haven't specified @samp{-f} in @file{inetd.conf}. 15955(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 15956your system setting the @code{$HOME} environment variable 15957for programs being run by inetd. In this case, you can either 15958have inetd run a shell script that unsets @code{$HOME} and then runs 15959@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 15960environment.) 15961 15962If you can connect successfully for a while but then can't, 15963you've probably hit inetd's rate limit. 15964(If inetd receives too many requests for the same service 15965in a short period of time, it assumes that something is wrong 15966and temporarily disables the service.) 15967Check your inetd documentation to find out how to adjust the 15968rate limit (some versions of inetd have a single rate limit, 15969others allow you to set the limit for each service separately.) 15970@end table 15971 15972@node Other problems 15973@appendixsec Other common problems 15974 15975Here is a list of problems which do not fit into the 15976above categories. They are in no particular order. 15977 15978@itemize @bullet 15979@item 15980On Windows, if there is a 30 second or so delay when 15981you run a @sc{cvs} command, it may mean that you have 15982your home directory set to @file{C:/}, for example (see 15983@code{HOMEDRIVE} and @code{HOMEPATH} in 15984@ref{Environment variables}). @sc{cvs} expects the home 15985directory to not end in a slash, for example @file{C:} 15986or @file{C:\cvs}. 15987@c FIXCVS: CVS should at least detect this and print an 15988@c error, presumably. 15989 15990@item 15991If you are running @sc{cvs} 1.9.18 or older, and 15992@code{cvs update} finds a conflict and tries to 15993merge, as described in @ref{Conflicts example}, but 15994doesn't tell you there were conflicts, then you may 15995have an old version of @sc{rcs}. The easiest solution 15996probably is to upgrade to a current version of 15997@sc{cvs}, which does not rely on external @sc{rcs} 15998programs. 15999@end itemize 16000 16001@c --------------------------------------------------------------------- 16002@node Credits 16003@appendix Credits 16004 16005@cindex Contributors (manual) 16006@cindex Credits (manual) 16007Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 16008wrote the manual pages which were distributed with 16009@sc{cvs} 1.3. Much of their text was copied into this 16010manual. He also read an early draft 16011of this manual and contributed many ideas and 16012corrections. 16013 16014The mailing-list @code{info-cvs} is sometimes 16015informative. I have included information from postings 16016made by the following persons: 16017David G. Grubbs <@t{dgg@@think.com}>. 16018 16019Some text has been extracted from the man pages for 16020@sc{rcs}. 16021 16022The @sc{cvs} @sc{faq} by David G. Grubbs has provided 16023useful material. The @sc{faq} is no longer maintained, 16024however, and this manual is about the closest thing there 16025is to a successor (with respect to documenting how to 16026use @sc{cvs}, at least). 16027 16028In addition, the following persons have helped by 16029telling me about mistakes I've made: 16030 16031@display 16032Roxanne Brunskill <@t{rbrunski@@datap.ca}>, 16033Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 16034Karl Pingle <@t{pingle@@acuson.com}>, 16035Thomas A Peterson <@t{tap@@src.honeywell.com}>, 16036Inge Wallin <@t{ingwa@@signum.se}>, 16037Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 16038and Michael Brown <@t{brown@@wi.extrel.com}>. 16039@end display 16040 16041The list of contributors here is not comprehensive; for a more 16042complete list of who has contributed to this manual see 16043the file @file{doc/ChangeLog} in the @sc{cvs} source 16044distribution. 16045 16046@c --------------------------------------------------------------------- 16047@node BUGS 16048@appendix Dealing with bugs in CVS or this manual 16049 16050@cindex Bugs in this manual or CVS 16051Neither @sc{cvs} nor this manual is perfect, and they 16052probably never will be. If you are having trouble 16053using @sc{cvs}, or think you have found a bug, there 16054are a number of things you can do about it. Note that 16055if the manual is unclear, that can be considered a bug 16056in the manual, so these problems are often worth doing 16057something about as well as problems with @sc{cvs} itself. 16058 16059@cindex Reporting bugs 16060@cindex Bugs, reporting 16061@cindex Errors, reporting 16062@itemize @bullet 16063@item 16064If you want someone to help you and fix bugs that you 16065report, there are companies which will do that for a 16066fee. One such company is: 16067 16068@cindex Ximbiot 16069@cindex Support, getting CVS support 16070@example 16071Ximbiot 16072319 S. River St. 16073Harrisburg, PA 17104-1657 16074USA 16075Email: info@@ximbiot.com 16076Phone: (717) 579-6168 16077Fax: (717) 234-3125 16078@url{http://ximbiot.com/} 16079 16080@end example 16081 16082@item 16083If you got @sc{cvs} through a distributor, such as an 16084operating system vendor or a vendor of freeware 16085@sc{cd-rom}s, you may wish to see whether the 16086distributor provides support. Often, they will provide 16087no support or minimal support, but this may vary from 16088distributor to distributor. 16089 16090@item 16091If you have the skills and time to do so, you may wish 16092to fix the bug yourself. If you wish to submit your 16093fix for inclusion in future releases of @sc{cvs}, see 16094the file @sc{hacking} in the @sc{cvs} source 16095distribution. It contains much more information on the 16096process of submitting fixes. 16097 16098@item 16099There may be resources on the net which can help. A 16100good place to start is: 16101 16102@example 16103@url{http://cvs.nongnu.org/} 16104@end example 16105 16106If you are so inspired, increasing the information 16107available on the net is likely to be appreciated. For 16108example, before the standard @sc{cvs} distribution 16109worked on Windows 95, there was a web page with some 16110explanation and patches for running @sc{cvs} on Windows 1611195, and various people helped out by mentioning this 16112page on mailing lists or newsgroups when the subject 16113came up. 16114 16115@item 16116It is also possible to report bugs to @email{bug-cvs@@nongnu.org}. 16117Note that someone may or may not want to do anything 16118with your bug report---if you need a solution consider 16119one of the options mentioned above. People probably do 16120want to hear about bugs which are particularly severe 16121in consequences and/or easy to fix, however. You can 16122also increase your odds by being as clear as possible 16123about the exact nature of the bug and any other 16124relevant information. The way to report bugs is to 16125send email to @email{bug-cvs@@nongnu.org}. Note 16126that submissions to @email{bug-cvs@@nongnu.org} may be distributed 16127under the terms of the @sc{gnu} Public License, so if 16128you don't like this, don't submit them. There is 16129usually no justification for sending mail directly to 16130one of the @sc{cvs} maintainers rather than to 16131@email{bug-cvs@@nongnu.org}; those maintainers who want to hear 16132about such bug reports read @email{bug-cvs@@nongnu.org}. Also note 16133that sending a bug report to other mailing lists or 16134newsgroups is @emph{not} a substitute for sending it to 16135@email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on 16136whatever forum you prefer, but there are not 16137necessarily any maintainers reading bug reports sent 16138anywhere except @email{bug-cvs@@nongnu.org}. 16139@end itemize 16140 16141@cindex Known bugs in this manual or CVS 16142People often ask if there is a list of known bugs or 16143whether a particular bug is a known one. The file 16144@sc{bugs} in the @sc{cvs} source distribution is one 16145list of known bugs, but it doesn't necessarily try to 16146be comprehensive. Perhaps there will never be a 16147comprehensive, detailed list of known bugs. 16148 16149@c --------------------------------------------------------------------- 16150@node Index 16151@unnumbered Index 16152@cindex Index 16153 16154@printindex cp 16155 16156@bye 16157 16158Local Variables: 16159fill-column: 55 16160End: 16161