cvs.texinfo revision 1.6
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@cindex init (subcommand) 1943To create a repository, run the @code{cvs init} 1944command. It will set up an empty repository in the 1945@sc{cvs} root specified in the usual way 1946(@pxref{Repository}). For example, 1947 1948@example 1949cvs -d /usr/local/cvsroot init 1950@end example 1951 1952@code{cvs init} is careful to never overwrite any 1953existing files in the repository, so no harm is done if 1954you run @code{cvs init} on an already set-up 1955repository. Note you may need to be a member of the 1956group @code{cvsadmin} to do this. 1957 1958@code{cvs init} will enable history logging; if you 1959don't want that, remove the history file after running 1960@code{cvs init}. @xref{history file}. 1961 1962@node Backing up 1963@section Backing up a repository 1964@cindex Repository, backing up 1965@cindex Backing up, repository 1966 1967There is nothing particularly magical about the files 1968in the repository; for the most part it is possible to 1969back them up just like any other files. However, there 1970are a few issues to consider. 1971 1972@cindex Locks, cvs, and backups 1973@cindex #cvs.rfl, and backups 1974The first is that to be paranoid, one should either not 1975use @sc{cvs} during the backup, or have the backup 1976program lock @sc{cvs} while doing the backup. To not 1977use @sc{cvs}, you might forbid logins to machines which 1978can access the repository, turn off your @sc{cvs} 1979server, or similar mechanisms. The details would 1980depend on your operating system and how you have 1981@sc{cvs} set up. To lock @sc{cvs}, you would create 1982@file{#cvs.rfl} locks in each repository directory. 1983See @ref{Concurrency}, for more on @sc{cvs} locks. 1984Having said all this, if you just back up without any 1985of these precautions, the results are unlikely to be 1986particularly dire. Restoring from backup, the 1987repository might be in an inconsistent state, but this 1988would not be particularly hard to fix manually. 1989 1990When you restore a repository from backup, assuming 1991that changes in the repository were made after the time 1992of the backup, working directories which were not 1993affected by the failure may refer to revisions which no 1994longer exist in the repository. Trying to run @sc{cvs} 1995in such directories will typically produce an error 1996message. One way to get those changes back into the 1997repository is as follows: 1998 1999@itemize @bullet 2000@item 2001Get a new working directory. 2002 2003@item 2004Copy the files from the working directory from before 2005the failure over to the new working directory (do not 2006copy the contents of the @file{CVS} directories, of 2007course). 2008 2009@item 2010Working in the new working directory, use commands such 2011as @code{cvs update} and @code{cvs diff} to figure out 2012what has changed, and then when you are ready, commit 2013the changes into the repository. 2014@end itemize 2015 2016@node Moving a repository 2017@section Moving a repository 2018@cindex Repository, moving 2019@cindex Moving a repository 2020@cindex Copying a repository 2021 2022Just as backing up the files in the repository is 2023pretty much like backing up any other files, if you 2024need to move a repository from one place to another it 2025is also pretty much like just moving any other 2026collection of files. 2027 2028The main thing to consider is that working directories 2029point to the repository. The simplest way to deal with 2030a moved repository is to just get a fresh working 2031directory after the move. Of course, you'll want to 2032make sure that the old working directory had been 2033checked in before the move, or you figured out some 2034other way to make sure that you don't lose any 2035changes. If you really do want to reuse the existing 2036working directory, it should be possible with manual 2037surgery on the @file{CVS/Repository} files. You can 2038see @ref{Working directory storage}, for information on 2039the @file{CVS/Repository} and @file{CVS/Root} files, but 2040unless you are sure you want to bother, it probably 2041isn't worth it. 2042@c FIXME: Surgery on CVS/Repository should be avoided 2043@c by making RELATIVE_REPOS the default. 2044@c FIXME-maybe: might want some documented way to 2045@c change the CVS/Root files in some particular tree. 2046@c But then again, I don't know, maybe just having 2047@c people do this in perl/shell/&c isn't so bad... 2048 2049@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2050@node Remote repositories 2051@section Remote repositories 2052@cindex Repositories, remote 2053@cindex Remote repositories 2054@cindex Client/Server Operation 2055@cindex Server, CVS 2056@cindex Remote repositories, port specification 2057@cindex Repositories, remote, port specification 2058@cindex Client/Server Operation, port specification 2059@cindex pserver (client/server connection method), port specification 2060@cindex kserver (client/server connection method), port specification 2061@cindex gserver (client/server connection method), port specification 2062@cindex port, specifying for remote repositories 2063 2064 Your working copy of the sources can be on a 2065different machine than the repository. Using @sc{cvs} 2066in this manner is known as @dfn{client/server} 2067operation. You run @sc{cvs} on a machine which can 2068mount your working directory, known as the 2069@dfn{client}, and tell it to communicate to a machine 2070which can mount the repository, known as the 2071@dfn{server}. Generally, using a remote 2072repository is just like using a local one, except that 2073the format of the repository name is: 2074 2075@example 2076[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 2077@end example 2078 2079Specifying a password in the repository name is not recommended during 2080checkout, since this will cause @sc{cvs} to store a cleartext copy of the 2081password in each created directory. @code{cvs login} first instead 2082(@pxref{Password authentication client}). 2083 2084The details of exactly what needs to be set up depend 2085on how you are connecting to the server. 2086 2087@c Should we try to explain which platforms are which? 2088@c Platforms like unix and VMS, which only allow 2089@c privileged programs to bind to sockets <1024 lose on 2090@c :server: 2091@c Platforms like Mac and VMS, whose rsh program is 2092@c unusable or nonexistent, lose on :ext: 2093@c Platforms like OS/2 and NT probably could plausibly 2094@c default either way (modulo -b troubles). 2095 2096@menu 2097* Server requirements:: Memory and other resources for servers 2098* The connection method:: Connection methods and method options 2099* Connecting via rsh:: Using the @code{rsh} program to connect 2100* Password authenticated:: Direct connections using passwords 2101* GSSAPI authenticated:: Direct connections using GSSAPI 2102* Kerberos authenticated:: Direct connections with Kerberos 2103* Connecting via fork:: Using a forked @code{cvs server} to connect 2104* Write proxies:: Distributing load across several CVS servers 2105@end menu 2106 2107@node Server requirements 2108@subsection Server requirements 2109 2110The quick answer to what sort of machine is suitable as 2111a server is that requirements are modest---a server 2112with 32M of memory or even less can handle a fairly 2113large source tree with a fair amount of activity. 2114@c Say something about CPU speed too? I'm even less sure 2115@c what to say on that subject... 2116 2117The real answer, of course, is more complicated. 2118Estimating the known areas of large memory consumption 2119should be sufficient to estimate memory requirements. 2120There are two such areas documented here; other memory 2121consumption should be small by comparison (if you find 2122that is not the case, let us know, as described in 2123@ref{BUGS}, so we can update this documentation). 2124 2125The first area of big memory consumption is large 2126checkouts, when using the @sc{cvs} server. The server 2127consists of two processes for each client that it is 2128serving. Memory consumption on the child process 2129should remain fairly small. Memory consumption on the 2130parent process, particularly if the network connection 2131to the client is slow, can be expected to grow to 2132slightly more than the size of the sources in a single 2133directory, or two megabytes, whichever is larger. 2134@c "two megabytes" of course is SERVER_HI_WATER. But 2135@c we don't mention that here because we are 2136@c documenting the default configuration of CVS. If it 2137@c is a "standard" thing to change that value, it 2138@c should be some kind of run-time configuration. 2139@c 2140@c See cvsclient.texi for more on the design decision 2141@c to not have locks in place while waiting for the 2142@c client, which is what results in memory consumption 2143@c as high as this. 2144 2145Multiplying the size of each @sc{cvs} server by the 2146number of servers which you expect to have active at 2147one time should give an idea of memory requirements for 2148the server. For the most part, the memory consumed by 2149the parent process probably can be swap space rather 2150than physical memory. 2151@c Has anyone verified that notion about swap space? 2152@c I say it based pretty much on guessing that the 2153@c ->text of the struct buffer_data only gets accessed 2154@c in a first in, first out fashion, but I haven't 2155@c looked very closely. 2156 2157@c What about disk usage in /tmp on the server? I think that 2158@c it can be substantial, but I haven't looked at this 2159@c again and tried to figure it out ("cvs import" is 2160@c probably the worst case...). 2161 2162The second area of large memory consumption is 2163@code{diff}, when checking in large files. This is 2164required even for binary files. The rule of thumb is 2165to allow about ten times the size of the largest file 2166you will want to check in, although five times may be 2167adequate. For example, if you want to check in a file 2168which is 10 megabytes, you should have 100 megabytes of 2169memory on the machine doing the checkin (the server 2170machine for client/server, or the machine running 2171@sc{cvs} for non-client/server). This can be swap 2172space rather than physical memory. Because the memory 2173is only required briefly, there is no particular need 2174to allow memory for more than one such checkin at a 2175time. 2176@c The 5-10 times rule of thumb is from Paul Eggert for 2177@c GNU diff. I don't think it is in the GNU diff 2178@c manual or anyplace like that. 2179@c 2180@c Probably we could be saying more about 2181@c non-client/server CVS. 2182@c I would guess for non-client/server CVS in an NFS 2183@c environment the biggest issues are the network and 2184@c the NFS server. 2185 2186Resource consumption for the client is even more 2187modest---any machine with enough capacity to run the 2188operating system in question should have little 2189trouble. 2190@c Is that true? I think the client still wants to 2191@c (bogusly) store entire files in memory at times. 2192 2193For information on disk space requirements, see 2194@ref{Creating a repository}. 2195 2196@node The connection method 2197@subsection The connection method 2198 2199In its simplest form, the @var{method} portion of the repository string 2200(@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork}, 2201@samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some 2202platforms, @samp{server}. 2203 2204If @var{method} is not specified, and the repository 2205name starts with a @samp{/}, then the default is @code{local}. 2206If @var{method} is not specified, and the repository 2207name does not start with a @samp{/}, then the default is @code{ext} 2208or @code{server}, depending on your platform; both the @samp{ext} 2209and @samp{server} methods are described in @ref{Connecting via rsh}. 2210 2211@cindex connection method options 2212@cindex options, connection method 2213The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection 2214methods all accept optional method options, specified as part of the 2215@var{method} string, like so: 2216 2217@example 2218:@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data} 2219@end example 2220 2221@sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though 2222it may sometimes be sensitive to the case of @var{arg}. The possible method 2223options are as follows: 2224 2225@table @code 2226@cindex CVS_PROXY_PORT 2227@cindex proxy, method option 2228@cindex proxyport, method option 2229@cindex proxies, web, connecting via 2230@cindex web proxies, connecting via 2231@cindex proxies, HTTP, connecting via 2232@cindex HTTP proxies, connecting via 2233@item proxy=@var{hostname} 2234@itemx proxyport=@var{port} 2235These two method options can be used to connect via an HTTP tunnel style web 2236proxy. @var{hostname} should be the name of the HTTP proxy server to connect 2237through and @var{port} is the port number on the HTTP proxy server to connect 2238via. @var{port} defaults to 8080. 2239 2240@strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy 2241server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.} 2242 2243For example, to connect pserver via a web proxy listening on port 8000 of 2244www.myproxy.net, you would use a method of: 2245 2246@example 2247:pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string} 2248@end example 2249 2250@strong{NOTE: In the above example, @var{pserver_connection_string} is still 2251required to connect and authenticate to the CVS server, as noted in the 2252upcoming sections on password authentication, @code{gserver}, and 2253@code{kserver}. The example above only demonstrates a modification to the 2254@var{method} portion of the repository name.} 2255 2256These options first appeared in @sc{cvs} version 1.12.7 and are valid as 2257modifcations to the @code{gserver} and @code{pserver} connection methods. 2258 2259@cindex CVS_RSH method option 2260@item CVS_RSH=@var{path} 2261This method option can be used with the @code{ext} method to specify the path 2262the @sc{cvs} client will use to find the remote shell used to contact the 2263@sc{cvs} server and takes precedence over any path specified in the 2264@code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}). For 2265example, to connect to a @sc{cvs} server via the local 2266@file{/path/to/ssh/command} command, you could choose to specify the following 2267@var{path} via the @code{CVS_RSH} method option: 2268 2269@example 2270:ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string} 2271@end example 2272 2273This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2274as a modifcation to the @code{ext} connection method. 2275 2276@cindex CVS_SERVER method option 2277@item CVS_SERVER=@var{path} 2278This method option can be used with the @code{ext} and @code{fork} methods to 2279specify the path @sc{cvs} will use to find the @sc{cvs} executable on the 2280@sc{cvs} server and takes precedence over any path specified in the 2281@code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}). For 2282example, to select the remote @file{/path/to/cvs/command} executable as your 2283@sc{cvs} server application on the @sc{cvs} server machine, you could choose to 2284specify the following @var{path} via the @code{CVS_SERVER} method option: 2285 2286@example 2287:ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string} 2288@end example 2289 2290@noindent 2291or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your 2292@code{$PATH} on the @sc{cvs} server: 2293 2294@example 2295:ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string} 2296@end example 2297 2298This method option first appeared in @sc{cvs} version 1.12.11 and is valid 2299as a modifcation to both the @code{ext} and @code{fork} connection methods. 2300 2301@cindex Redirect, method option 2302@item Redirect=@var{boolean-state} 2303The @code{Redirect} method option determines whether the @sc{cvs} client will 2304allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually 2305for write requests, as in a write proxy setup. 2306 2307A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config} 2308file options is acceptable here (@pxref{config}). For example, @samp{on}, 2309@samp{off}, @samp{true}, and @samp{false} are all valid values for 2310@var{boolean-state}. @var{boolean-state} for the @code{Redirect} method option 2311defaults to @samp{on}. 2312 2313This option will have no effect when talking to any non-secondary @sc{cvs} 2314server. For more on write proxies and secondary servers, please see 2315@ref{Write proxies}. 2316 2317This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2318as a modifcation to the @code{ext} connection method. 2319@end table 2320 2321As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER} 2322options, a method specification like the following would work: 2323 2324@example 2325:ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command: 2326@end example 2327 2328This means that you would not need to have 2329the @code{CVS_SERVER} or @code{CVS_RSH} environment 2330variables set correctly. See @ref{Connecting via rsh}, for more details on 2331these environment variables. 2332 2333@node Connecting via rsh 2334@subsection Connecting with rsh 2335 2336@cindex rsh 2337@sc{cvs} uses the @samp{rsh} protocol to perform these 2338operations, so the remote user host needs to have a 2339@file{.rhosts} file which grants access to the local 2340user. Note that the program that @sc{cvs} uses for this 2341purpose may be specified using the @file{--with-rsh} 2342flag to configure. 2343 2344For example, suppose you are the user @samp{mozart} on 2345the local machine @samp{toe.example.com}, and the 2346server machine is @samp{faun.example.org}. On 2347faun, put the following line into the file 2348@file{.rhosts} in @samp{bach}'s home directory: 2349 2350@example 2351toe.example.com mozart 2352@end example 2353 2354@noindent 2355Then test that @samp{rsh} is working with 2356 2357@example 2358rsh -l bach faun.example.org 'echo $PATH' 2359@end example 2360 2361@cindex CVS_SERVER, environment variable 2362Next you have to make sure that @code{rsh} will be able 2363to find the server. Make sure that the path which 2364@code{rsh} printed in the above example includes the 2365directory containing a program named @code{cvs} which 2366is the server. You need to set the path in 2367@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 2368or @file{.profile}. Alternately, you can set the 2369environment variable @code{CVS_SERVER} on the client 2370machine to the filename of the server you want to use, 2371for example @file{/usr/local/bin/cvs-1.6}. 2372For the @code{ext} and @code{fork} methods, you may 2373also specify @var{CVS_SERVER} as an otpion in the 2374@var{CVSROOT} so that you may use different servers for 2375differnt roots. See @ref{Remote repositories} for more 2376details. 2377 2378There is no need to edit @file{inetd.conf} or start a 2379@sc{cvs} server daemon. 2380 2381@cindex :server:, setting up 2382@cindex :ext:, setting up 2383@cindex Kerberos, using kerberized rsh 2384@cindex SSH (rsh replacement) 2385@cindex rsh replacements (Kerberized, SSH, &c) 2386There are two access methods that you use in @code{CVSROOT} 2387for rsh. @code{:server:} specifies an internal rsh 2388client, which is supported only by some @sc{cvs} ports. 2389@code{:ext:} specifies an external rsh program. By 2390default this is @code{rsh} (unless otherwise specified 2391by the @file{--with-rsh} flag to configure) but you may set the 2392@code{CVS_RSH} environment variable to invoke another 2393program which can access the remote server (for 2394example, @code{remsh} on HP-UX 9 because @code{rsh} is 2395something different). It must be a program which can 2396transmit data to and from the server without modifying 2397it; for example the Windows NT @code{rsh} is not 2398suitable since it by default translates between CRLF 2399and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 2400to @code{rsh} to get around this, but since this could 2401potentially cause problems for programs other than the 2402standard @code{rsh}, it may change in the future. If 2403you set @code{CVS_RSH} to @code{SSH} or some other rsh 2404replacement, the instructions in the rest of this 2405section concerning @file{.rhosts} and so on are likely 2406to be inapplicable; consult the documentation for your rsh 2407replacement. 2408 2409You may choose to specify the @var{CVS_RSH} option as a method option 2410in the @var{CVSROOT} string to allow you to use different connection tools 2411for different roots (@pxref{The connection method}). For example, allowing 2412some roots to use @code{CVS_RSH=remsh} and some to use 2413@code{CVS_RSH=ssh} for the @code{ext} method. See also 2414the @ref{Remote repositories} for more details. 2415@c See also the comment in src/client.c for rationale 2416@c concerning "rsh" being the default and never 2417@c "remsh". 2418 2419Continuing our example, supposing you want to access 2420the module @file{foo} in the repository 2421@file{/usr/local/cvsroot/}, on machine 2422@file{faun.example.org}, you are ready to go: 2423 2424@example 2425cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2426@end example 2427 2428@noindent 2429(The @file{bach@@} can be omitted if the username is 2430the same on both the local and remote hosts.) 2431 2432@c Should we mention "rsh host echo hi" and "rsh host 2433@c cat" (the latter followed by typing text and ^D) 2434@c as troubleshooting techniques? Probably yes 2435@c (people tend to have trouble setting this up), 2436@c but this kind of thing can be hard to spell out. 2437 2438@node Password authenticated 2439@subsection Direct connection with password authentication 2440 2441The @sc{cvs} client can also connect to the server 2442using a password protocol. This is particularly useful 2443if using @code{rsh} is not feasible (for example, 2444the server is behind a firewall), and Kerberos also is 2445not available. 2446 2447 To use this method, it is necessary to make 2448some adjustments on both the server and client sides. 2449 2450@menu 2451* Password authentication server:: Setting up the server 2452* Password authentication client:: Using the client 2453* Password authentication security:: What this method does and does not do 2454@end menu 2455 2456@node Password authentication server 2457@subsubsection Setting up the server for password authentication 2458 2459First of all, you probably want to tighten the 2460permissions on the @file{$CVSROOT} and 2461@file{$CVSROOT/CVSROOT} directories. See @ref{Password 2462authentication security}, for more details. 2463 2464@cindex pserver (subcommand) 2465@cindex Remote repositories, port specification 2466@cindex Repositories, remote, port specification 2467@cindex Client/Server Operation, port specification 2468@cindex pserver (client/server connection method), port specification 2469@cindex kserver (client/server connection method), port specification 2470@cindex gserver (client/server connection method), port specification 2471@cindex port, specifying for remote repositories 2472@cindex Password server, setting up 2473@cindex Authenticating server, setting up 2474@cindex inetd, configuring for pserver 2475@cindex xinetd, configuring for pserver 2476@c FIXME: this isn't quite right regarding port 2477@c numbers; CVS looks up "cvspserver" in 2478@c /etc/services (on unix, but what about non-unix?). 2479On the server side, the file @file{/etc/inetd.conf} 2480needs to be edited so @code{inetd} knows to run the 2481command @code{cvs pserver} when it receives a 2482connection on the right port. By default, the port 2483number is 2401; it would be different if your client 2484were compiled with @code{CVS_AUTH_PORT} defined to 2485something else, though. This can also be specified in the CVSROOT variable 2486(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 2487environment variable (@pxref{Environment variables}). 2488 2489 If your @code{inetd} allows raw port numbers in 2490@file{/etc/inetd.conf}, then the following (all on a 2491single line in @file{inetd.conf}) should be sufficient: 2492 2493@example 24942401 stream tcp nowait root /usr/local/bin/cvs 2495cvs -f --allow-root=/usr/cvsroot pserver 2496@end example 2497 2498@noindent 2499(You could also use the 2500@samp{-T} option to specify a temporary directory.) 2501 2502The @samp{--allow-root} option specifies the allowable 2503@sc{cvsroot} directory. Clients which attempt to use a 2504different @sc{cvsroot} directory will not be allowed to 2505connect. If there is more than one @sc{cvsroot} 2506directory which you want to allow, repeat the option. 2507(Unfortunately, many versions of @code{inetd} have very small 2508limits on the number of arguments and/or the total length 2509of the command. The usual solution to this problem is 2510to have @code{inetd} run a shell script which then invokes 2511@sc{cvs} with the necessary arguments.) 2512 2513 If your @code{inetd} wants a symbolic service 2514name instead of a raw port number, then put this in 2515@file{/etc/services}: 2516 2517@example 2518cvspserver 2401/tcp 2519@end example 2520 2521@noindent 2522and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 2523 2524If your system uses @code{xinetd} instead of @code{inetd}, 2525the procedure is slightly different. 2526Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2527 2528@example 2529service cvspserver 2530@{ 2531 port = 2401 2532 socket_type = stream 2533 protocol = tcp 2534 wait = no 2535 user = root 2536 passenv = PATH 2537 server = /usr/local/bin/cvs 2538 server_args = -f --allow-root=/usr/cvsroot pserver 2539@} 2540@end example 2541 2542@noindent 2543(If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2544the @code{port} line.) 2545 2546 Once the above is taken care of, restart your 2547@code{inetd}, or do whatever is necessary to force it 2548to reread its initialization files. 2549 2550If you are having trouble setting this up, see 2551@ref{Connection}. 2552 2553@cindex CVS passwd file 2554@cindex passwd (admin file) 2555Because the client stores and transmits passwords in 2556cleartext (almost---see @ref{Password authentication 2557security}, for details), a separate @sc{cvs} password 2558file is generally used, so people don't compromise 2559their regular passwords when they access the 2560repository. This file is 2561@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 2562administrative files}). It uses a colon-separated 2563format, similar to @file{/etc/passwd} on Unix systems, 2564except that it has fewer fields: @sc{cvs} username, 2565optional password, and an optional system username for 2566@sc{cvs} to run as if authentication succeeds. Here is 2567an example @file{passwd} file with five entries: 2568 2569@example 2570anonymous: 2571bach:ULtgRLXo7NRxs 2572spwang:1sOp854gDF3DY 2573melissa:tGX1fS8sun6rY:pubcvs 2574qproj:XR4EZcEs0szik:pubcvs 2575@end example 2576 2577@noindent 2578(The passwords are encrypted according to the standard 2579Unix @code{crypt()} function, so it is possible to 2580paste in passwords directly from regular Unix 2581@file{/etc/passwd} files.) 2582 2583The first line in the example will grant access to any 2584@sc{cvs} client attempting to authenticate as user 2585@code{anonymous}, no matter what password they use, 2586including an empty password. (This is typical for 2587sites granting anonymous read-only access; for 2588information on how to do the "read-only" part, see 2589@ref{Read-only access}.) 2590 2591The second and third lines will grant access to 2592@code{bach} and @code{spwang} if they supply their 2593respective plaintext passwords. 2594 2595@cindex User aliases 2596The fourth line will grant access to @code{melissa}, if 2597she supplies the correct password, but her @sc{cvs} 2598operations will actually run on the server side under 2599the system user @code{pubcvs}. Thus, there need not be 2600any system user named @code{melissa}, but there 2601@emph{must} be one named @code{pubcvs}. 2602 2603The fifth line shows that system user identities can be 2604shared: any client who successfully authenticates as 2605@code{qproj} will actually run as @code{pubcvs}, just 2606as @code{melissa} does. That way you could create a 2607single, shared system user for each project in your 2608repository, and give each developer their own line in 2609the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 2610username on each line would be different, but the 2611system username would be the same. The reason to have 2612different @sc{cvs} usernames is that @sc{cvs} will log their 2613actions under those names: when @code{melissa} commits 2614a change to a project, the checkin is recorded in the 2615project's history under the name @code{melissa}, not 2616@code{pubcvs}. And the reason to have them share a 2617system username is so that you can arrange permissions 2618in the relevant area of the repository such that only 2619that account has write-permission there. 2620 2621If the system-user field is present, all 2622password-authenticated @sc{cvs} commands run as that 2623user; if no system user is specified, @sc{cvs} simply 2624takes the @sc{cvs} username as the system username and 2625runs commands as that user. In either case, if there 2626is no such user on the system, then the @sc{cvs} 2627operation will fail (regardless of whether the client 2628supplied a valid password). 2629 2630The password and system-user fields can both be omitted 2631(and if the system-user field is omitted, then also 2632omit the colon that would have separated it from the 2633encrypted password). For example, this would be a 2634valid @file{$CVSROOT/CVSROOT/passwd} file: 2635 2636@example 2637anonymous::pubcvs 2638fish:rKa5jzULzmhOo:kfogel 2639sussman:1sOp854gDF3DY 2640@end example 2641 2642@noindent 2643When the password field is omitted or empty, then the 2644client's authentication attempt will succeed with any 2645password, including the empty string. However, the 2646colon after the @sc{cvs} username is always necessary, 2647even if the password is empty. 2648 2649@sc{cvs} can also fall back to use system authentication. 2650When authenticating a password, the server first checks 2651for the user in the @file{$CVSROOT/CVSROOT/passwd} 2652file. If it finds the user, it will use that entry for 2653authentication as described above. But if it does not 2654find the user, or if the @sc{cvs} @file{passwd} file 2655does not exist, then the server can try to authenticate 2656the username and password using the operating system's 2657user-lookup routines (this "fallback" behavior can be 2658disabled by setting @code{SystemAuth=no} in the 2659@sc{cvs} @file{config} file, @pxref{config}). 2660 2661The default fallback behavior is to look in 2662@file{/etc/passwd} for this system user unless your 2663system has PAM (Pluggable Authentication Modules) 2664and your @sc{cvs} server executable was configured to 2665use it at compile time (using @code{./configure --enable-pam} - see the 2666INSTALL file for more). In this case, PAM will be consulted instead. 2667This means that @sc{cvs} can be configured to use any password 2668authentication source PAM can be configured to use (possibilities 2669include a simple UNIX password, NIS, LDAP, and others) in its 2670global configuration file (usually @file{/etc/pam.conf} 2671or possibly @file{/etc/pam.d/cvs}). See your PAM documentation 2672for more details on PAM configuration. 2673 2674Note that PAM is an experimental feature in @sc{cvs} and feedback is 2675encouraged. Please send a mail to one of the @sc{cvs} mailing lists 2676(@code{info-cvs@@nongnu.org} or @code{bug-cvs@@nongnu.org}) if you use the 2677@sc{cvs} PAM support. 2678 2679@strong{WARNING: Using PAM gives the system administrator much more 2680flexibility about how @sc{cvs} users are authenticated but 2681no more security than other methods. See below for more.} 2682 2683CVS needs an "auth", "account" and "session" module in the 2684PAM configuration file. A typical PAM configuration 2685would therefore have the following lines 2686in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 2687system @file{/etc/passwd} authentication: 2688 2689@example 2690cvs auth required pam_unix.so 2691cvs account required pam_unix.so 2692cvs session required pam_unix.so 2693@end example 2694 2695The the equivalent @file{/etc/pam.d/cvs} would contain 2696 2697@example 2698auth required pam_unix.so 2699account required pam_unix.so 2700session required pam_unix.so 2701@end example 2702 2703Some systems require a full path to the module so that 2704@file{pam_unix.so} (Linux) would become something like 2705@file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris). 2706See the @file{contrib/pam} subdirectory of the @sc{cvs} 2707source distribution for further example configurations. 2708 2709The PAM service name given above as "cvs" is just 2710the service name in the default configuration and can be 2711set using 2712@code{./configure --with-hardcoded-pam-service-name=<pam-service-name>} 2713before compiling. @sc{cvs} can also be configured to use whatever 2714name it is invoked as as its PAM service name using 2715@code{./configure --without-hardcoded-pam-service-name}, but this 2716feature should not be used if you may not have control of the name 2717@sc{cvs} will be invoked as. 2718 2719Be aware, also, that falling back to system 2720authentication might be a security risk: @sc{cvs} 2721operations would then be authenticated with that user's 2722regular login password, and the password flies across 2723the network in plaintext. See @ref{Password 2724authentication security} for more on this. 2725This may be more of a problem with PAM authentication 2726because it is likely that the source of the system 2727password is some central authentication service like 2728LDAP which is also used to authenticate other services. 2729 2730On the other hand, PAM makes it very easy to change your password 2731regularly. If they are given the option of a one-password system for 2732all of their activities, users are often more willing to change their 2733password on a regular basis. 2734 2735In the non-PAM configuration where the password is stored in the 2736@file{CVSROOT/passwd} file, it is difficult to change passwords on a 2737regular basis since only administrative users (or in some cases 2738processes that act as an administrative user) are typically given 2739access to modify this file. Either there needs to be some 2740hand-crafted web page or set-uid program to update the file, or the 2741update needs to be done by submitting a request to an administrator to 2742perform the duty by hand. In the first case, having to remember to 2743update a separate password on a periodic basis can be difficult. In 2744the second case, the manual nature of the change will typically mean 2745that the password will not be changed unless it is absolutely 2746necessary. 2747 2748Note that PAM administrators should probably avoid configuring 2749one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If 2750OTPs are desired, the administrator may wish to encourage the use of 2751one of the other Client/Server access methods. See the section on 2752@pxref{Remote repositories} for a list of other methods. 2753 2754Right now, the only way to put a password in the 2755@sc{cvs} @file{passwd} file is to paste it there from 2756somewhere else. Someday, there may be a @code{cvs 2757passwd} command. 2758 2759Unlike many of the files in @file{$CVSROOT/CVSROOT}, it 2760is normal to edit the @file{passwd} file in-place, 2761rather than via @sc{cvs}. This is because of the 2762possible security risks of having the @file{passwd} 2763file checked out to people's working copies. If you do 2764want to include the @file{passwd} file in checkouts of 2765@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 2766 2767@c We might also suggest using the @code{htpasswd} command 2768@c from freely available web servers as well, but that 2769@c would open up a can of worms in that the users next 2770@c questions are likely to be "where do I get it?" and 2771@c "how do I use it?" 2772@c Also note that htpasswd, at least the version I had, 2773@c likes to clobber the third field. 2774 2775@node Password authentication client 2776@subsubsection Using the client with password authentication 2777@cindex Login (subcommand) 2778@cindex Password client, using 2779@cindex Authenticated client, using 2780@cindex :pserver:, setting up 2781To run a @sc{cvs} command on a remote repository via 2782the password-authenticating server, one specifies the 2783@code{pserver} protocol, optional username, repository host, an 2784optional port number, and path to the repository. For example: 2785 2786@example 2787cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 2788@end example 2789 2790@noindent 2791or 2792 2793@example 2794CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 2795cvs checkout someproj 2796@end example 2797 2798However, unless you're connecting to a public-access 2799repository (i.e., one where that username doesn't 2800require a password), you'll need to supply a password or @dfn{log in} first. 2801Logging in verifies your password with the repository and stores it in a file. 2802It's done with the @code{login} command, which will 2803prompt you interactively for the password if you didn't supply one as part of 2804@var{$CVSROOT}: 2805 2806@example 2807cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 2808CVS password: 2809@end example 2810 2811@noindent 2812or 2813 2814@example 2815cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 2816@end example 2817 2818After you enter the password, @sc{cvs} verifies it with 2819the server. If the verification succeeds, then that 2820combination of username, host, repository, and password 2821is permanently recorded, so future transactions with 2822that repository won't require you to run @code{cvs 2823login}. (If verification fails, @sc{cvs} will exit 2824complaining that the password was incorrect, and 2825nothing will be recorded.) 2826 2827The records are stored, by default, in the file 2828@file{$HOME/.cvspass}. That file's format is 2829human-readable, and to a degree human-editable, but 2830note that the passwords are not stored in 2831cleartext---they are trivially encoded to protect them 2832from "innocent" compromise (i.e., inadvertent viewing 2833by a system administrator or other non-malicious 2834person). 2835 2836@cindex CVS_PASSFILE, environment variable 2837You can change the default location of this file by 2838setting the @code{CVS_PASSFILE} environment variable. 2839If you use this variable, make sure you set it 2840@emph{before} @code{cvs login} is run. If you were to 2841set it after running @code{cvs login}, then later 2842@sc{cvs} commands would be unable to look up the 2843password for transmission to the server. 2844 2845Once you have logged in, all @sc{cvs} commands using 2846that remote repository and username will authenticate 2847with the stored password. So, for example 2848 2849@example 2850cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2851@end example 2852 2853@noindent 2854should just work (unless the password changes on the 2855server side, in which case you'll have to re-run 2856@code{cvs login}). 2857 2858Note that if the @samp{:pserver:} were not present in 2859the repository specification, @sc{cvs} would assume it 2860should use @code{rsh} to connect with the server 2861instead (@pxref{Connecting via rsh}). 2862 2863Of course, once you have a working copy checked out and 2864are running @sc{cvs} commands from within it, there is 2865no longer any need to specify the repository 2866explicitly, because @sc{cvs} can deduce the repository 2867from the working copy's @file{CVS} subdirectory. 2868 2869@c FIXME: seems to me this needs somewhat more 2870@c explanation. 2871@cindex Logout (subcommand) 2872The password for a given remote repository can be 2873removed from the @code{CVS_PASSFILE} by using the 2874@code{cvs logout} command. 2875 2876@node Password authentication security 2877@subsubsection Security considerations with password authentication 2878 2879@cindex Security, of pserver 2880The passwords are stored on the client side in a 2881trivial encoding of the cleartext, and transmitted in 2882the same encoding. The encoding is done only to 2883prevent inadvertent password compromises (i.e., a 2884system administrator accidentally looking at the file), 2885and will not prevent even a naive attacker from gaining 2886the password. 2887 2888@c FIXME: The bit about "access to the repository 2889@c implies general access to the system is *not* specific 2890@c to pserver; it applies to kerberos and SSH and 2891@c everything else too. Should reorganize the 2892@c documentation to make this clear. 2893The separate @sc{cvs} password file (@pxref{Password 2894authentication server}) allows people 2895to use a different password for repository access than 2896for login access. On the other hand, once a user has 2897non-read-only 2898access to the repository, she can execute programs on 2899the server system through a variety of means. Thus, repository 2900access implies fairly broad system access as well. It 2901might be possible to modify @sc{cvs} to prevent that, 2902but no one has done so as of this writing. 2903@c OpenBSD uses chroot() and copies the repository to 2904@c provide anonymous read-only access (for details see 2905@c http://www.openbsd.org/anoncvs.shar). While this 2906@c closes the most obvious holes, I'm not sure it 2907@c closes enough holes to recommend it (plus it is 2908@c *very* easy to accidentally screw up a setup of this 2909@c type). 2910 2911Note that because the @file{$CVSROOT/CVSROOT} directory 2912contains @file{passwd} and other files which are used 2913to check security, you must control the permissions on 2914this directory as tightly as the permissions on 2915@file{/etc}. The same applies to the @file{$CVSROOT} 2916directory itself and any directory 2917above it in the tree. Anyone who has write access to 2918such a directory will have the ability to become any 2919user on the system. Note that these permissions are 2920typically tighter than you would use if you are not 2921using pserver. 2922@c TODO: Would be really nice to document/implement a 2923@c scheme where the CVS server can run as some non-root 2924@c user, e.g. "cvs". CVSROOT/passwd would contain a 2925@c bunch of entries of the form foo:xxx:cvs (or the "cvs" 2926@c would be implicit). This would greatly reduce 2927@c security risks such as those hinted at in the 2928@c previous paragraph. I think minor changes to CVS 2929@c might be required but mostly this would just need 2930@c someone who wants to play with it, document it, &c. 2931 2932In summary, anyone who gets the password gets 2933repository access (which may imply some measure of general system 2934access as well). The password is available to anyone 2935who can sniff network packets or read a protected 2936(i.e., user read-only) file. If you want real 2937security, get Kerberos. 2938 2939@node GSSAPI authenticated 2940@subsection Direct connection with GSSAPI 2941 2942@cindex GSSAPI 2943@cindex Security, GSSAPI 2944@cindex :gserver:, setting up 2945@cindex Kerberos, using :gserver: 2946GSSAPI is a generic interface to network security 2947systems such as Kerberos 5. 2948If you have a working GSSAPI library, you can have 2949@sc{cvs} connect via a direct @sc{tcp} connection, 2950authenticating with GSSAPI. 2951 2952To do this, @sc{cvs} needs to be compiled with GSSAPI 2953support; when configuring @sc{cvs} it tries to detect 2954whether GSSAPI libraries using Kerberos version 5 are 2955present. You can also use the @file{--with-gssapi} 2956flag to configure. 2957 2958The connection is authenticated using GSSAPI, but the 2959message stream is @emph{not} authenticated by default. 2960You must use the @code{-a} global option to request 2961stream authentication. 2962 2963The data transmitted is @emph{not} encrypted by 2964default. Encryption support must be compiled into both 2965the client and the server; use the 2966@file{--enable-encrypt} configure option to turn it on. 2967You must then use the @code{-x} global option to 2968request encryption. 2969 2970GSSAPI connections are handled on the server side by 2971the same server which handles the password 2972authentication server; see @ref{Password authentication 2973server}. If you are using a GSSAPI mechanism such as 2974Kerberos which provides for strong authentication, you 2975will probably want to disable the ability to 2976authenticate via cleartext passwords. To do so, create 2977an empty @file{CVSROOT/passwd} password file, and set 2978@code{SystemAuth=no} in the config file 2979(@pxref{config}). 2980 2981The GSSAPI server uses a principal name of 2982cvs/@var{hostname}, where @var{hostname} is the 2983canonical name of the server host. You will have to 2984set this up as required by your GSSAPI mechanism. 2985 2986To connect using GSSAPI, use the @samp{:gserver:} method. For 2987example, 2988 2989@example 2990cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 2991@end example 2992 2993@node Kerberos authenticated 2994@subsection Direct connection with Kerberos 2995 2996@cindex Kerberos, using :kserver: 2997@cindex Security, Kerberos 2998@cindex :kserver:, setting up 2999The easiest way to use Kerberos is to use the Kerberos 3000@code{rsh}, as described in @ref{Connecting via rsh}. 3001The main disadvantage of using rsh is that all the data 3002needs to pass through additional programs, so it may be 3003slower. So if you have Kerberos installed you can 3004connect via a direct @sc{tcp} connection, 3005authenticating with Kerberos. 3006 3007This section concerns the Kerberos network security 3008system, version 4. Kerberos version 5 is supported via 3009the GSSAPI generic network security interface, as 3010described in the previous section. 3011 3012To do this, @sc{cvs} needs to be compiled with Kerberos 3013support; when configuring @sc{cvs} it tries to detect 3014whether Kerberos is present or you can use the 3015@file{--with-krb4} flag to configure. 3016 3017The data transmitted is @emph{not} encrypted by 3018default. Encryption support must be compiled into both 3019the client and server; use the 3020@file{--enable-encryption} configure option to turn it 3021on. You must then use the @code{-x} global option to 3022request encryption. 3023 3024The CVS client will attempt to connect to port 1999 by default. 3025 3026@cindex kinit 3027When you want to use @sc{cvs}, get a ticket in the 3028usual way (generally @code{kinit}); it must be a ticket 3029which allows you to log into the server machine. Then 3030you are ready to go: 3031 3032@example 3033cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 3034@end example 3035 3036Previous versions of @sc{cvs} would fall back to a 3037connection via rsh; this version will not do so. 3038 3039@node Connecting via fork 3040@subsection Connecting with fork 3041 3042@cindex fork, access method 3043@cindex :fork:, setting up 3044This access method allows you to connect to a 3045repository on your local disk via the remote protocol. 3046In other words it does pretty much the same thing as 3047@code{:local:}, but various quirks, bugs and the like are 3048those of the remote @sc{cvs} rather than the local 3049@sc{cvs}. 3050 3051For day-to-day operations you might prefer either 3052@code{:local:} or @code{:fork:}, depending on your 3053preferences. Of course @code{:fork:} comes in 3054particularly handy in testing or 3055debugging @code{cvs} and the remote protocol. 3056Specifically, we avoid all of the network-related 3057setup/configuration, timeouts, and authentication 3058inherent in the other remote access methods but still 3059create a connection which uses the remote protocol. 3060 3061To connect using the @code{fork} method, use 3062@samp{:fork:} and the pathname to your local 3063repository. For example: 3064 3065@example 3066cvs -d :fork:/usr/local/cvsroot checkout foo 3067@end example 3068 3069@cindex CVS_SERVER, and :fork: 3070As with @code{:ext:}, the server is called @samp{cvs} 3071by default, or the value of the @code{CVS_SERVER} 3072environment variable. 3073 3074 3075@node Write proxies 3076@subsection Distributing load across several CVS servers 3077 3078@cindex PrimaryServer, in CVSROOT/config 3079@cindex Primary server 3080@cindex Secondary server 3081@cindex proxy, write 3082@cindex write proxy 3083@sc{cvs} can be configured to distribute usage across several @sc{cvs} 3084servers. This is accomplished by means of one or more @dfn{write proxies}, or 3085@dfn{secondary servers}, for a single @dfn{primary server}. 3086 3087When a @sc{cvs} client accesses a secondary server and only sends read 3088requests, then the secondary server handles the entire request. If the client 3089sends any write requests, however, the secondary server asks the client to 3090redirect its write request to the primary server, if the client supports 3091redirect requests, and otherwise becomes a transparent proxy for the primary 3092server, which actually handles the write request. 3093 3094In this manner, any number of read-only secondary servers may be configured as 3095write proxies for the primary server, effectively distributing the load from 3096all read operations between the secondary servers and restricting the load on 3097the primary server to write operations and pushing changes to the secondaries. 3098 3099Primary servers will not automatically push changes to secondaries. This must 3100be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, & 3101@file{postwatch} scripts (@pxref{Trigger Scripts}) like the following: 3102 3103@example 3104ALL rsync -gopr -essh ./ secondary:/cvsroot/%p & 3105@end example 3106 3107You would probably actually want to lock directories for write on the secondary 3108and for read on the primary before running the @samp{rsync} in the above 3109example, but describing such a setup is beyond the scope of this document. 3110 3111A secondary advantage of a write proxy setup is that users pointing at the 3112secondary server can still execute fast read operations while on a network that 3113connects to the primary over a slow link or even one where the link to the 3114primary is periodically broken. Only write operations will require the network 3115link to the primary. 3116 3117To configure write proxies, the primary must be specified with the 3118@samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}). For the 3119transparent proxy mode to work, all secondary servers must also be running the 3120same version of the @sc{cvs} server, or at least one that provides the same 3121list of supported requests to the client as the primary server. This is not 3122necessary for redirection. 3123 3124Once a primary server is configured, secondary servers may be configured by: 3125 3126@enumerate 3127@item 3128Duplicating the primary repository at the new location. 3129@item 3130Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and 3131@file{postwatch} files on the primary to propagate writes to the new secondary. 3132@item 3133Configure remote access to the secondary(ies) as you would configure access 3134to any other CVS server (@pxref{Remote repositories}). 3135@item 3136Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to 3137@strong{all} incovations of the secondary server if the path to the @sc{cvs} 3138repository directory is different on the two servers and you wish to support 3139clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier 3140clients do not handle the @samp{Redirect} response). 3141 3142Please note, again, that writethrough proxy suport requires 3143@code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all} 3144incovations of the secondary server, not just @samp{pserver} invocations. 3145This may require a wrapper script for the @sc{cvs} executable 3146on your server machine. 3147@end enumerate 3148 3149 3150@c --------------------------------------------------------------------- 3151@node Read-only access 3152@section Read-only repository access 3153@cindex Read-only repository access 3154@cindex readers (admin file) 3155@cindex writers (admin file) 3156 3157 It is possible to grant read-only repository 3158access to people using the password-authenticated 3159server (@pxref{Password authenticated}). (The 3160other access methods do not have explicit support for 3161read-only users because those methods all assume login 3162access to the repository machine anyway, and therefore 3163the user can do whatever local file permissions allow 3164her to do.) 3165 3166 A user who has read-only access can do only 3167those @sc{cvs} operations which do not modify the 3168repository, except for certain ``administrative'' files 3169(such as lock files and the history file). It may be 3170desirable to use this feature in conjunction with 3171user-aliasing (@pxref{Password authentication server}). 3172 3173Unlike with previous versions of @sc{cvs}, read-only 3174users should be able merely to read the repository, and 3175not to execute programs on the server or otherwise gain 3176unexpected levels of access. Or to be more accurate, 3177the @emph{known} holes have been plugged. Because this 3178feature is new and has not received a comprehensive 3179security audit, you should use whatever level of 3180caution seems warranted given your attitude concerning 3181security. 3182 3183 There are two ways to specify read-only access 3184for a user: by inclusion, and by exclusion. 3185 3186 "Inclusion" means listing that user 3187specifically in the @file{$CVSROOT/CVSROOT/readers} 3188file, which is simply a newline-separated list of 3189users. Here is a sample @file{readers} file: 3190 3191@example 3192melissa 3193splotnik 3194jrandom 3195@end example 3196 3197@noindent 3198 (Don't forget the newline after the last user.) 3199 3200 "Exclusion" means explicitly listing everyone 3201who has @emph{write} access---if the file 3202 3203@example 3204$CVSROOT/CVSROOT/writers 3205@end example 3206 3207@noindent 3208exists, then only 3209those users listed in it have write access, and 3210everyone else has read-only access (of course, even the 3211read-only users still need to be listed in the 3212@sc{cvs} @file{passwd} file). The 3213@file{writers} file has the same format as the 3214@file{readers} file. 3215 3216 Note: if your @sc{cvs} @file{passwd} 3217file maps cvs users onto system users (@pxref{Password 3218authentication server}), make sure you deny or grant 3219read-only access using the @emph{cvs} usernames, not 3220the system usernames. That is, the @file{readers} and 3221@file{writers} files contain cvs usernames, which may 3222or may not be the same as system usernames. 3223 3224 Here is a complete description of the server's 3225behavior in deciding whether to grant read-only or 3226read-write access: 3227 3228 If @file{readers} exists, and this user is 3229listed in it, then she gets read-only access. Or if 3230@file{writers} exists, and this user is NOT listed in 3231it, then she also gets read-only access (this is true 3232even if @file{readers} exists but she is not listed 3233there). Otherwise, she gets full read-write access. 3234 3235 Of course there is a conflict if the user is 3236listed in both files. This is resolved in the more 3237conservative way, it being better to protect the 3238repository too much than too little: such a user gets 3239read-only access. 3240 3241@node Server temporary directory 3242@section Temporary directories for the server 3243@cindex Temporary directories, and server 3244@cindex Server, temporary directories 3245 3246While running, the @sc{cvs} server creates temporary 3247directories. They are named 3248 3249@example 3250cvs-serv@var{pid} 3251@end example 3252 3253@noindent 3254where @var{pid} is the process identification number of 3255the server. 3256They are located in the directory specified by 3257the @samp{-T} global option (@pxref{Global options}), 3258the @code{TMPDIR} environment variable (@pxref{Environment variables}), 3259or, failing that, @file{/tmp}. 3260 3261In most cases the server will remove the temporary 3262directory when it is done, whether it finishes normally 3263or abnormally. However, there are a few cases in which 3264the server does not or cannot remove the temporary 3265directory, for example: 3266 3267@itemize @bullet 3268@item 3269If the server aborts due to an internal server error, 3270it may preserve the directory to aid in debugging 3271 3272@item 3273If the server is killed in a way that it has no way of 3274cleaning up (most notably, @samp{kill -KILL} on unix). 3275 3276@item 3277If the system shuts down without an orderly shutdown, 3278which tells the server to clean up. 3279@end itemize 3280 3281In cases such as this, you will need to manually remove 3282the @file{cvs-serv@var{pid}} directories. As long as 3283there is no server running with process identification 3284number @var{pid}, it is safe to do so. 3285 3286@c --------------------------------------------------------------------- 3287@node Starting a new project 3288@chapter Starting a project with CVS 3289@cindex Starting a project with CVS 3290@cindex Creating a project 3291 3292@comment --moduledb-- 3293Because renaming files and moving them between 3294directories is somewhat inconvenient, the first thing 3295you do when you start a new project should be to think 3296through your file organization. It is not impossible 3297to rename or move files, but it does increase the 3298potential for confusion and @sc{cvs} does have some 3299quirks particularly in the area of renaming 3300directories. @xref{Moving files}. 3301 3302What to do next depends on the situation at hand. 3303 3304@menu 3305* Setting up the files:: Getting the files into the repository 3306* Defining the module:: How to make a module of the files 3307@end menu 3308@c -- File permissions! 3309 3310@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3311@node Setting up the files 3312@section Setting up the files 3313 3314The first step is to create the files inside the repository. This can 3315be done in a couple of different ways. 3316 3317@c -- The contributed scripts 3318@menu 3319* From files:: This method is useful with old projects 3320 where files already exists. 3321* From other version control systems:: Old projects where you want to 3322 preserve history from another system. 3323* From scratch:: Creating a directory tree from scratch. 3324@end menu 3325 3326@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3327@node From files 3328@subsection Creating a directory tree from a number of files 3329@cindex Importing files 3330 3331When you begin using @sc{cvs}, you will probably already have several 3332projects that can be 3333put under @sc{cvs} control. In these cases the easiest way is to use the 3334@code{import} command. An example is probably the easiest way to 3335explain how to use it. If the files you want to install in 3336@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 3337repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 3338 3339@example 3340$ cd @var{wdir} 3341$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 3342@end example 3343 3344Unless you supply a log message with the @samp{-m} 3345flag, @sc{cvs} starts an editor and prompts for a 3346message. The string @samp{yoyo} is a @dfn{vendor tag}, 3347and @samp{start} is a @dfn{release tag}. They may fill 3348no purpose in this context, but since @sc{cvs} requires 3349them they must be present. @xref{Tracking sources}, for 3350more information about them. 3351 3352You can now verify that it worked, and remove your 3353original source directory. 3354@c FIXME: Need to say more about "verify that it 3355@c worked". What should the user look for in the output 3356@c from "diff -r"? 3357 3358@example 3359$ cd .. 3360$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 3361$ diff -r @var{wdir} yoyodyne/@var{rdir} 3362$ rm -r @var{wdir} 3363@end example 3364 3365@noindent 3366Erasing the original sources is a good idea, to make sure that you do 3367not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 3368Of course, it would be wise to make sure that you have 3369a backup of the sources before you remove them. 3370 3371The @code{checkout} command can either take a module 3372name as argument (as it has done in all previous 3373examples) or a path name relative to @code{$CVSROOT}, 3374as it did in the example above. 3375 3376It is a good idea to check that the permissions 3377@sc{cvs} sets on the directories inside @code{$CVSROOT} 3378are reasonable, and that they belong to the proper 3379groups. @xref{File permissions}. 3380 3381If some of the files you want to import are binary, you 3382may want to use the wrappers features to specify which 3383files are binary and which are not. @xref{Wrappers}. 3384 3385@c The node name is too long, but I am having trouble 3386@c thinking of something more concise. 3387@node From other version control systems 3388@subsection Creating Files From Other Version Control Systems 3389@cindex Importing files, from other version control systems 3390 3391If you have a project which you are maintaining with 3392another version control system, such as @sc{rcs}, you 3393may wish to put the files from that project into 3394@sc{cvs}, and preserve the revision history of the 3395files. 3396 3397@table @asis 3398@cindex RCS, importing files from 3399@item From RCS 3400If you have been using @sc{rcs}, find the @sc{rcs} 3401files---usually a file named @file{foo.c} will have its 3402@sc{rcs} file in @file{RCS/foo.c,v} (but it could be 3403other places; consult the @sc{rcs} documentation for 3404details). Then create the appropriate directories in 3405@sc{cvs} if they do not already exist. Then copy the 3406files into the appropriate directories in the @sc{cvs} 3407repository (the name in the repository must be the name 3408of the source file with @samp{,v} added; the files go 3409directly in the appropriate directory of the repository, 3410not in an @file{RCS} subdirectory). This is one of the 3411few times when it is a good idea to access the @sc{cvs} 3412repository directly, rather than using @sc{cvs} 3413commands. Then you are ready to check out a new 3414working directory. 3415@c Someday there probably should be a "cvs import -t 3416@c rcs" or some such. It could even create magic 3417@c branches. It could also do something about the case 3418@c where the RCS file had a (non-magic) "0" branch. 3419 3420The @sc{rcs} file should not be locked when you move it 3421into @sc{cvs}; if it is, @sc{cvs} will have trouble 3422letting you operate on it. 3423@c What is the easiest way to unlock your files if you 3424@c have them locked? Especially if you have a lot of them? 3425@c This is a CVS bug/misfeature; importing RCS files 3426@c should ignore whether they are locked and leave them in 3427@c an unlocked state. Yet another reason for a separate 3428@c "import RCS file" command. 3429 3430@c How many is "many"? Or do they just import RCS files? 3431@item From another version control system 3432Many version control systems have the ability to export 3433@sc{rcs} files in the standard format. If yours does, 3434export the @sc{rcs} files and then follow the above 3435instructions. 3436 3437Failing that, probably your best bet is to write a 3438script that will check out the files one revision at a 3439time using the command line interface to the other 3440system, and then check the revisions into @sc{cvs}. 3441The @file{sccs2rcs} script mentioned below may be a 3442useful example to follow. 3443 3444@cindex SCCS, importing files from 3445@item From SCCS 3446There is a script in the @file{contrib} directory of 3447the @sc{cvs} source distribution called @file{sccs2rcs} 3448which converts @sc{sccs} files to @sc{rcs} files. 3449Note: you must run it on a machine which has both 3450@sc{sccs} and @sc{rcs} installed, and like everything 3451else in contrib it is unsupported (your mileage may 3452vary). 3453 3454@cindex PVCS, importing files from 3455@item From PVCS 3456There is a script in the @file{contrib} directory of 3457the @sc{cvs} source distribution called @file{pvcs_to_rcs} 3458which converts @sc{pvcs} archives to @sc{rcs} files. 3459You must run it on a machine which has both 3460@sc{pvcs} and @sc{rcs} installed, and like everything 3461else in contrib it is unsupported (your mileage may 3462vary). See the comments in the script for details. 3463@end table 3464@c CMZ and/or PATCHY were systems that were used in the 3465@c high energy physics community (especially for 3466@c CERNLIB). CERN has replaced them with CVS, but the 3467@c CAR format seems to live on as a way to submit 3468@c changes. There is a program car2cvs which converts 3469@c but I'm not sure where one gets a copy. 3470@c Not sure it is worth mentioning here, since it would 3471@c appear to affect only one particular community. 3472@c Best page for more information is: 3473@c http://wwwcn1.cern.ch/asd/cvs/index.html 3474@c See also: 3475@c http://ecponion.cern.ch/ecpsa/cernlib.html 3476 3477@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3478@node From scratch 3479@subsection Creating a directory tree from scratch 3480 3481@c Also/instead should be documenting 3482@c $ cvs co -l . 3483@c $ mkdir tc 3484@c $ cvs add tc 3485@c $ cd tc 3486@c $ mkdir man 3487@c $ cvs add man 3488@c etc. 3489@c Using import to create the directories only is 3490@c probably a somewhat confusing concept. 3491For a new project, the easiest thing to do is probably 3492to create an empty directory structure, like this: 3493 3494@example 3495$ mkdir tc 3496$ mkdir tc/man 3497$ mkdir tc/testing 3498@end example 3499 3500After that, you use the @code{import} command to create 3501the corresponding (empty) directory structure inside 3502the repository: 3503 3504@example 3505$ cd tc 3506$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 3507@end example 3508 3509This will add yoyodyne/@var{dir} as a directory under 3510@code{$CVSROOT}. 3511 3512Use @code{checkout} to get the new project. Then, use @code{add} 3513to add files (and new directories) as needed. 3514 3515@example 3516$ cd .. 3517$ cvs co yoyodyne/@var{dir} 3518@end example 3519 3520Check that the permissions @sc{cvs} sets on the 3521directories inside @code{$CVSROOT} are reasonable. 3522 3523@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3524@node Defining the module 3525@section Defining the module 3526@cindex Defining a module 3527@cindex Editing the modules file 3528@cindex Module, defining 3529@cindex Modules file, changing 3530 3531The next step is to define the module in the 3532@file{modules} file. This is not strictly necessary, 3533but modules can be convenient in grouping together 3534related files and directories. 3535 3536In simple cases these steps are sufficient to define a module. 3537 3538@enumerate 3539@item 3540Get a working copy of the modules file. 3541 3542@example 3543$ cvs checkout CVSROOT/modules 3544$ cd CVSROOT 3545@end example 3546 3547@item 3548Edit the file and insert a line that defines the module. @xref{Intro 3549administrative files}, for an introduction. @xref{modules}, for a full 3550description of the modules file. You can use the 3551following line to define the module @samp{tc}: 3552 3553@example 3554tc yoyodyne/tc 3555@end example 3556 3557@item 3558Commit your changes to the modules file. 3559 3560@example 3561$ cvs commit -m "Added the tc module." modules 3562@end example 3563 3564@item 3565Release the modules module. 3566 3567@example 3568$ cd .. 3569$ cvs release -d CVSROOT 3570@end example 3571@end enumerate 3572 3573@c --------------------------------------------------------------------- 3574@node Revisions 3575@chapter Revisions 3576 3577For many uses of @sc{cvs}, one doesn't need to worry 3578too much about revision numbers; @sc{cvs} assigns 3579numbers such as @code{1.1}, @code{1.2}, and so on, and 3580that is all one needs to know. However, some people 3581prefer to have more knowledge and control concerning 3582how @sc{cvs} assigns revision numbers. 3583 3584If one wants to keep track of a set of revisions 3585involving more than one file, such as which revisions 3586went into a particular release, one uses a @dfn{tag}, 3587which is a symbolic revision which can be assigned to a 3588numeric revision in each file. 3589 3590@menu 3591* Revision numbers:: The meaning of a revision number 3592* Versions revisions releases:: Terminology used in this manual 3593* Assigning revisions:: Assigning revisions 3594* Tags:: Tags--Symbolic revisions 3595* Tagging the working directory:: The cvs tag command 3596* Tagging by date/tag:: The cvs rtag command 3597* Modifying tags:: Adding, renaming, and deleting tags 3598* Tagging add/remove:: Tags with adding and removing files 3599* Sticky tags:: Certain tags are persistent 3600@end menu 3601 3602@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3603@node Revision numbers 3604@section Revision numbers 3605@cindex Revision numbers 3606@cindex Revision tree 3607@cindex Linear development 3608@cindex Number, revision- 3609@cindex Decimal revision number 3610@cindex Branch number 3611@cindex Number, branch 3612 3613Each version of a file has a unique @dfn{revision 3614number}. Revision numbers look like @samp{1.1}, 3615@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 3616A revision number always has an even number of 3617period-separated decimal integers. By default revision 36181.1 is the first revision of a file. Each successive 3619revision is given a new number by increasing the 3620rightmost number by one. The following figure displays 3621a few revisions, with newer revisions to the right. 3622 3623@example 3624 +-----+ +-----+ +-----+ +-----+ +-----+ 3625 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 3626 +-----+ +-----+ +-----+ +-----+ +-----+ 3627@end example 3628 3629It is also possible to end up with numbers containing 3630more than one period, for example @samp{1.3.2.2}. Such 3631revisions represent revisions on branches 3632(@pxref{Branching and merging}); such revision numbers 3633are explained in detail in @ref{Branches and 3634revisions}. 3635 3636@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3637@node Versions revisions releases 3638@section Versions, revisions and releases 3639@cindex Revisions, versions and releases 3640@cindex Versions, revisions and releases 3641@cindex Releases, revisions and versions 3642 3643A file can have several versions, as described above. 3644Likewise, a software product can have several versions. 3645A software product is often given a version number such 3646as @samp{4.1.1}. 3647 3648Versions in the first sense are called @dfn{revisions} 3649in this document, and versions in the second sense are 3650called @dfn{releases}. To avoid confusion, the word 3651@dfn{version} is almost never used in this document. 3652 3653@node Assigning revisions 3654@section Assigning revisions 3655 3656@c We avoid the "major revision" terminology. It seems 3657@c like jargon. Hopefully "first number" is clear enough. 3658@c 3659@c Well, in the context of software release numbers, 3660@c "major" and "minor" release or version numbers are 3661@c documented in at least the GNU Coding Standards, but I'm 3662@c still not sure I find that a valid reason to apply the 3663@c terminology to RCS revision numbers. "First", "Second", 3664@c "subsequent", and so on is almost surely clearer, 3665@c especially to a novice reader. -DRP 3666By default, @sc{cvs} will assign numeric revisions by 3667leaving the first number the same and incrementing the 3668second number. For example, @code{1.1}, @code{1.2}, 3669@code{1.3}, etc. 3670 3671When adding a new file, the second number will always 3672be one and the first number will equal the highest 3673first number of any file in that directory. For 3674example, the current directory contains files whose 3675highest numbered revisions are @code{1.7}, @code{3.1}, 3676and @code{4.12}, then an added file will be given the 3677numeric revision @code{4.1}. 3678(When using client/server @sc{cvs}, 3679only files that are actually sent to the server are considered.) 3680 3681@c This is sort of redundant with something we said a 3682@c while ago. Somewhere we need a better way of 3683@c introducing how the first number can be anything 3684@c except "1", perhaps. Also I don't think this 3685@c presentation is clear on why we are discussing releases 3686@c and first numbers of numeric revisions in the same 3687@c breath. 3688Normally there is no reason to care 3689about the revision numbers---it is easier to treat them 3690as internal numbers that @sc{cvs} maintains, and tags 3691provide a better way to distinguish between things like 3692release 1 versus release 2 of your product 3693(@pxref{Tags}). However, if you want to set the 3694numeric revisions, the @samp{-r} option to @code{cvs 3695commit} can do that. The @samp{-r} option implies the 3696@samp{-f} option, in the sense that it causes the 3697files to be committed even if they are not modified. 3698 3699For example, to bring all your files up to 3700revision 3.0 (including those that haven't changed), 3701you might invoke: 3702 3703@example 3704$ cvs commit -r 3.0 3705@end example 3706 3707Note that the number you specify with @samp{-r} must be 3708larger than any existing revision number. That is, if 3709revision 3.0 exists, you cannot @samp{cvs commit 3710-r 1.3}. If you want to maintain several releases in 3711parallel, you need to use a branch (@pxref{Branching and merging}). 3712 3713@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3714@node Tags 3715@section Tags--Symbolic revisions 3716@cindex Tags 3717 3718The revision numbers live a life of their own. They 3719need not have anything at all to do with the release 3720numbers of your software product. Depending 3721on how you use @sc{cvs} the revision numbers might change several times 3722between two releases. As an example, some of the 3723source files that make up @sc{rcs} 5.6 have the following 3724revision numbers: 3725@cindex RCS revision numbers 3726 3727@example 3728ci.c 5.21 3729co.c 5.9 3730ident.c 5.3 3731rcs.c 5.12 3732rcsbase.h 5.11 3733rcsdiff.c 5.10 3734rcsedit.c 5.11 3735rcsfcmp.c 5.9 3736rcsgen.c 5.10 3737rcslex.c 5.11 3738rcsmap.c 5.2 3739rcsutil.c 5.10 3740@end example 3741 3742@cindex tag (subcommand), introduction 3743@cindex Tags, symbolic name 3744@cindex Symbolic name (tag) 3745@cindex Name, symbolic (tag) 3746@cindex HEAD, as reserved tag name 3747@cindex BASE, as reserved tag name 3748You can use the @code{tag} command to give a symbolic name to a 3749certain revision of a file. You can use the @samp{-v} flag to the 3750@code{status} command to see all tags that a file has, and 3751which revision numbers they represent. Tag names must 3752start with an uppercase or lowercase letter and can 3753contain uppercase and lowercase letters, digits, 3754@samp{-}, and @samp{_}. The two tag names @code{BASE} 3755and @code{HEAD} are reserved for use by @sc{cvs}. It 3756is expected that future names which are special to 3757@sc{cvs} will be specially named, for example by 3758starting with @samp{.}, rather than being named analogously to 3759@code{BASE} and @code{HEAD}, to avoid conflicts with 3760actual tag names. 3761@c Including a character such as % or = has also been 3762@c suggested as the naming convention for future 3763@c special tag names. Starting with . is nice because 3764@c that is not a legal tag name as far as RCS is concerned. 3765@c FIXME: CVS actually accepts quite a few characters 3766@c in tag names, not just the ones documented above 3767@c (see RCS_check_tag). RCS 3768@c defines legitimate tag names by listing illegal 3769@c characters rather than legal ones. CVS is said to lose its 3770@c mind if you try to use "/" (try making such a tag sticky 3771@c and using "cvs status" client/server--see remote 3772@c protocol format for entries line for probable cause). 3773@c TODO: The testsuite 3774@c should test for whatever are documented above as 3775@c officially-OK tag names, and CVS should at least reject 3776@c characters that won't work, like "/". 3777 3778You'll want to choose some convention for naming tags, 3779based on information such as the name of the program 3780and the version number of the release. For example, 3781one might take the name of the program, immediately 3782followed by the version number with @samp{.} changed to 3783@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 3784@code{cvs1-9}. If you choose a consistent convention, 3785then you won't constantly be guessing whether a tag is 3786@code{cvs-1-9} or @code{cvs1_9} or what. You might 3787even want to consider enforcing your convention in the 3788@file{taginfo} file (@pxref{taginfo}). 3789@c Might be nice to say more about using taginfo this 3790@c way, like giving an example, or pointing out any particular 3791@c issues which arise. 3792 3793@cindex Adding a tag 3794@cindex Tags, example 3795The following example shows how you can add a tag to a 3796file. The commands must be issued inside your working 3797directory. That is, you should issue the 3798command in the directory where @file{backend.c} 3799resides. 3800 3801@example 3802$ cvs tag rel-0-4 backend.c 3803T backend.c 3804$ cvs status -v backend.c 3805=================================================================== 3806File: backend.c Status: Up-to-date 3807 3808 Version: 1.4 Tue Dec 1 14:39:01 1992 3809 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 3810 Sticky Tag: (none) 3811 Sticky Date: (none) 3812 Sticky Options: (none) 3813 3814 Existing Tags: 3815 rel-0-4 (revision: 1.4) 3816 3817@end example 3818 3819For a complete summary of the syntax of @code{cvs tag}, 3820including the various options, see @ref{Invoking CVS}. 3821 3822There is seldom reason to tag a file in isolation. A more common use is 3823to tag all the files that constitute a module with the same tag at 3824strategic points in the development life-cycle, such as when a release 3825is made. 3826 3827@example 3828$ cvs tag rel-1-0 . 3829cvs tag: Tagging . 3830T Makefile 3831T backend.c 3832T driver.c 3833T frontend.c 3834T parser.c 3835@end example 3836 3837@noindent 3838(When you give @sc{cvs} a directory as argument, it generally applies the 3839operation to all the files in that directory, and (recursively), to any 3840subdirectories that it may contain. @xref{Recursive behavior}.) 3841 3842@cindex Retrieving an old revision using tags 3843@cindex Tags, retrieving old revisions 3844The @code{checkout} command has a flag, @samp{-r}, that lets you check out 3845a certain revision of a module. This flag makes it easy to 3846retrieve the sources that make up release 1.0 of the module @samp{tc} at 3847any time in the future: 3848 3849@example 3850$ cvs checkout -r rel-1-0 tc 3851@end example 3852 3853@noindent 3854This is useful, for instance, if someone claims that there is a bug in 3855that release, but you cannot find the bug in the current working copy. 3856 3857You can also check out a module as it was on any branch at any given date. 3858@xref{checkout options}. When specifying @samp{-r} or @samp{-D} to 3859any of these commands, you will need beware of sticky 3860tags; see @ref{Sticky tags}. 3861 3862When you tag more than one file with the same tag you 3863can think about the tag as "a curve drawn through a 3864matrix of filename vs. revision number." Say we have 5 3865files with the following revisions: 3866 3867@example 3868@group 3869 file1 file2 file3 file4 file5 3870 3871 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 3872 1.2*- 1.2 1.2 -1.2*- 3873 1.3 \- 1.3*- 1.3 / 1.3 3874 1.4 \ 1.4 / 1.4 3875 \-1.5*- 1.5 3876 1.6 3877@end group 3878@end example 3879 3880At some time in the past, the @code{*} versions were tagged. 3881You can think of the tag as a handle attached to the curve 3882drawn through the tagged revisions. When you pull on 3883the handle, you get all the tagged revisions. Another 3884way to look at it is that you "sight" through a set of 3885revisions that is "flat" along the tagged revisions, 3886like this: 3887 3888@example 3889@group 3890 file1 file2 file3 file4 file5 3891 3892 1.1 3893 1.2 3894 1.1 1.3 _ 3895 1.1 1.2 1.4 1.1 / 3896 1.2*----1.3*----1.5*----1.2*----1.1* (--- <--- Look here 3897 1.3 1.6 1.3 \_ 3898 1.4 1.4 3899 1.5 3900@end group 3901@end example 3902 3903@node Tagging the working directory 3904@section Specifying what to tag from the working directory 3905 3906@cindex tag (subcommand) 3907The example in the previous section demonstrates one of 3908the most common ways to choose which revisions to tag. 3909Namely, running the @code{cvs tag} command without 3910arguments causes @sc{cvs} to select the revisions which 3911are checked out in the current working directory. For 3912example, if the copy of @file{backend.c} in working 3913directory was checked out from revision 1.4, then 3914@sc{cvs} will tag revision 1.4. Note that the tag is 3915applied immediately to revision 1.4 in the repository; 3916tagging is not like modifying a file, or other 3917operations in which one first modifies the working 3918directory and then runs @code{cvs commit} to transfer 3919that modification to the repository. 3920 3921One potentially surprising aspect of the fact that 3922@code{cvs tag} operates on the repository is that you 3923are tagging the checked-in revisions, which may differ 3924from locally modified files in your working directory. 3925If you want to avoid doing this by mistake, specify the 3926@samp{-c} option to @code{cvs tag}. If there are any 3927locally modified files, @sc{cvs} will abort with an 3928error before it tags any files: 3929 3930@example 3931$ cvs tag -c rel-0-4 3932cvs tag: backend.c is locally modified 3933cvs [tag aborted]: correct the above errors first! 3934@end example 3935 3936@node Tagging by date/tag 3937@section Specifying what to tag by date or revision 3938@cindex rtag (subcommand) 3939 3940The @code{cvs rtag} command tags the repository as of a 3941certain date or time (or can be used to tag the latest 3942revision). @code{rtag} works directly on the 3943repository contents (it requires no prior checkout and 3944does not look for a working directory). 3945 3946The following options specify which date or revision to 3947tag. See @ref{Common options}, for a complete 3948description of them. 3949 3950@table @code 3951@item -D @var{date} 3952Tag the most recent revision no later than @var{date}. 3953 3954@item -f 3955Only useful with the @samp{-D} or @samp{-r} 3956flags. If no matching revision is found, use the most 3957recent revision (instead of ignoring the file). 3958 3959@item -r @var{tag}[:@var{date}] 3960Tag the revision already tagged with @var{tag} or, when @var{date} is specified 3961and @var{tag} is a branch tag, the version from the branch @var{tag} as it 3962existed on @var{date}. See @ref{Common options}. 3963@end table 3964 3965The @code{cvs tag} command also allows one to specify 3966files by revision or date, using the same @samp{-r}, 3967@samp{-D}, and @samp{-f} options. However, this 3968feature is probably not what you want. The reason is 3969that @code{cvs tag} chooses which files to tag based on 3970the files that exist in the working directory, rather 3971than the files which existed as of the given tag/date. 3972Therefore, you are generally better off using @code{cvs 3973rtag}. The exceptions might be cases like: 3974 3975@example 3976cvs tag -r 1.4 stable backend.c 3977@end example 3978 3979@node Modifying tags 3980@section Deleting, moving, and renaming tags 3981 3982@c Also see: 3983@c "How do I move or rename a magic branch tag?" 3984@c in the FAQ (I think the issues it talks about still 3985@c apply, but this could use some sanity.sh work). 3986 3987Normally one does not modify tags. They exist in order 3988to record the history of the repository and so deleting 3989them or changing their meaning would, generally, not be 3990what you want. 3991 3992However, there might be cases in which one uses a tag 3993temporarily or accidentally puts one in the wrong 3994place. Therefore, one might delete, move, or rename a 3995tag. 3996 3997@noindent 3998@strong{WARNING: the commands in this section are 3999dangerous; they permanently discard historical 4000information and it can be difficult or impossible to 4001recover from errors. If you are a @sc{cvs} 4002administrator, you may consider restricting these 4003commands with the @file{taginfo} file (@pxref{taginfo}).} 4004 4005@cindex Deleting tags 4006@cindex Deleting branch tags 4007@cindex Removing tags 4008@cindex Removing branch tags 4009@cindex Tags, deleting 4010@cindex Branch tags, deleting 4011To delete a tag, specify the @samp{-d} option to either 4012@code{cvs tag} or @code{cvs rtag}. For example: 4013 4014@example 4015cvs rtag -d rel-0-4 tc 4016@end example 4017 4018@noindent 4019deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 4020In the event that branch tags are encountered within the repository 4021with the given name, a warning message will be issued and the branch 4022tag will not be deleted. If you are absolutely certain you know what 4023you are doing, the @code{-B} option may be specified to allow deletion 4024of branch tags. In that case, any non-branch tags encountered will 4025trigger warnings and will not be deleted. 4026 4027@noindent 4028@strong{WARNING: Moving branch tags is very dangerous! If you think 4029you need the @code{-B} option, think again and ask your @sc{cvs} 4030administrator about it (if that isn't you). There is almost certainly 4031another way to accomplish what you want to accomplish.} 4032 4033@cindex Moving tags 4034@cindex Moving branch tags 4035@cindex Tags, moving 4036@cindex Branch tags, moving 4037When we say @dfn{move} a tag, we mean to make the same 4038name point to different revisions. For example, the 4039@code{stable} tag may currently point to revision 1.4 4040of @file{backend.c} and perhaps we want to make it 4041point to revision 1.6. To move a non-branch tag, specify the 4042@samp{-F} option to either @code{cvs tag} or @code{cvs 4043rtag}. For example, the task just mentioned might be 4044accomplished as: 4045 4046@example 4047cvs tag -r 1.6 -F stable backend.c 4048@end example 4049 4050@noindent 4051If any branch tags are encountered in the repository 4052with the given name, a warning is issued and the branch 4053tag is not disturbed. If you are absolutely certain you 4054wish to move the branch tag, the @code{-B} option may be specified. 4055In that case, non-branch tags encountered with the given 4056name are ignored with a warning message. 4057 4058@noindent 4059@strong{WARNING: Moving branch tags is very dangerous! If you think you 4060need the @code{-B} option, think again and ask your @sc{cvs} 4061administrator about it (if that isn't you). There is almost certainly 4062another way to accomplish what you want to accomplish.} 4063 4064@cindex Renaming tags 4065@cindex Tags, renaming 4066When we say @dfn{rename} a tag, we mean to make a 4067different name point to the same revisions as the old 4068tag. For example, one may have misspelled the tag name 4069and want to correct it (hopefully before others are 4070relying on the old spelling). To rename a tag, first 4071create a new tag using the @samp{-r} option to 4072@code{cvs rtag}, and then delete the old name. (Caution: 4073this method will not work with branch tags.) 4074This leaves the new tag on exactly the 4075same files as the old tag. For example: 4076 4077@example 4078cvs rtag -r old-name-0-4 rel-0-4 tc 4079cvs rtag -d old-name-0-4 tc 4080@end example 4081 4082@node Tagging add/remove 4083@section Tagging and adding and removing files 4084 4085The subject of exactly how tagging interacts with 4086adding and removing files is somewhat obscure; for the 4087most part @sc{cvs} will keep track of whether files 4088exist or not without too much fussing. By default, 4089tags are applied to only files which have a revision 4090corresponding to what is being tagged. Files which did 4091not exist yet, or which were already removed, simply 4092omit the tag, and @sc{cvs} knows to treat the absence 4093of a tag as meaning that the file didn't exist as of 4094that tag. 4095 4096However, this can lose a small amount of information. 4097For example, suppose a file was added and then removed. 4098Then, if the tag is missing for that file, there is no 4099way to know whether the tag refers to the time before 4100the file was added, or the time after it was removed. 4101If you specify the @samp{-r} option to @code{cvs rtag}, 4102then @sc{cvs} tags the files which have been removed, 4103and thereby avoids this problem. For example, one 4104might specify @code{-r HEAD} to tag the head. 4105 4106On the subject of adding and removing files, the 4107@code{cvs rtag} command has a @samp{-a} option which 4108means to clear the tag from removed files that would 4109not otherwise be tagged. For example, one might 4110specify this option in conjunction with @samp{-F} when 4111moving a tag. If one moved a tag without @samp{-a}, 4112then the tag in the removed files might still refer to 4113the old revision, rather than reflecting the fact that 4114the file had been removed. I don't think this is 4115necessary if @samp{-r} is specified, as noted above. 4116 4117@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4118@node Sticky tags 4119@section Sticky tags 4120@cindex Sticky tags 4121@cindex Tags, sticky 4122 4123@c A somewhat related issue is per-directory sticky 4124@c tags (see comment at CVS/Tag in node Working 4125@c directory storage); we probably want to say 4126@c something like "you can set a sticky tag for only 4127@c some files, but you don't want to" or some such. 4128 4129Sometimes a working copy's revision has extra data 4130associated with it, for example it might be on a branch 4131(@pxref{Branching and merging}), or restricted to 4132versions prior to a certain date by @samp{checkout -D} 4133or @samp{update -D}. Because this data persists -- 4134that is, it applies to subsequent commands in the 4135working copy -- we refer to it as @dfn{sticky}. 4136 4137Most of the time, stickiness is an obscure aspect of 4138@sc{cvs} that you don't need to think about. However, 4139even if you don't want to use the feature, you may need 4140to know @emph{something} about sticky tags (for 4141example, how to avoid them!). 4142 4143You can use the @code{status} command to see if any 4144sticky tags or dates are set: 4145 4146@example 4147$ cvs status driver.c 4148=================================================================== 4149File: driver.c Status: Up-to-date 4150 4151 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 4152 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 4153 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4154 Sticky Date: (none) 4155 Sticky Options: (none) 4156 4157@end example 4158 4159@cindex Resetting sticky tags 4160@cindex Sticky tags, resetting 4161@cindex Deleting sticky tags 4162The sticky tags will remain on your working files until 4163you delete them with @samp{cvs update -A}. The 4164@samp{-A} option merges local changes into the version of the 4165file from the head of the trunk, removing any sticky tags, 4166dates, or options. See @ref{update} for more on the operation 4167of @code{cvs update}. 4168 4169@cindex Sticky date 4170The most common use of sticky tags is to identify which 4171branch one is working on, as described in 4172@ref{Accessing branches}. However, non-branch 4173sticky tags have uses as well. For example, 4174suppose that you want to avoid updating your working 4175directory, to isolate yourself from possibly 4176destabilizing changes other people are making. You 4177can, of course, just refrain from running @code{cvs 4178update}. But if you want to avoid updating only a 4179portion of a larger tree, then sticky tags can help. 4180If you check out a certain revision (such as 1.4) it 4181will become sticky. Subsequent @code{cvs update} 4182commands will 4183not retrieve the latest revision until you reset the 4184tag with @code{cvs update -A}. Likewise, use of the 4185@samp{-D} option to @code{update} or @code{checkout} 4186sets a @dfn{sticky date}, which, similarly, causes that 4187date to be used for future retrievals. 4188 4189People often want to retrieve an old version of 4190a file without setting a sticky tag. This can 4191be done with the @samp{-p} option to @code{checkout} or 4192@code{update}, which sends the contents of the file to 4193standard output. For example: 4194@example 4195$ cvs update -p -r 1.1 file1 >file1 4196=================================================================== 4197Checking out file1 4198RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 4199VERS: 1.1 4200*************** 4201$ 4202@end example 4203 4204However, this isn't the easiest way, if you are asking 4205how to undo a previous checkin (in this example, put 4206@file{file1} back to the way it was as of revision 42071.1). In that case you are better off using the 4208@samp{-j} option to @code{update}; for further 4209discussion see @ref{Merging two revisions}. 4210 4211@c --------------------------------------------------------------------- 4212@node Branching and merging 4213@chapter Branching and merging 4214@cindex Branching 4215@cindex Merging 4216@cindex Copying changes 4217@cindex Main trunk and branches 4218@cindex Revision tree, making branches 4219@cindex Branches, copying changes between 4220@cindex Changes, copying between branches 4221@cindex Modifications, copying between branches 4222 4223@sc{cvs} allows you to isolate changes onto a separate 4224line of development, known as a @dfn{branch}. When you 4225change files on a branch, those changes do not appear 4226on the main trunk or other branches. 4227 4228Later you can move changes from one branch to another 4229branch (or the main trunk) by @dfn{merging}. Merging 4230involves first running @code{cvs update -j}, to merge 4231the changes into the working directory. 4232You can then commit that revision, and thus effectively 4233copy the changes onto another branch. 4234 4235@menu 4236* Branches motivation:: What branches are good for 4237* Creating a branch:: Creating a branch 4238* Accessing branches:: Checking out and updating branches 4239* Branches and revisions:: Branches are reflected in revision numbers 4240* Magic branch numbers:: Magic branch numbers 4241* Merging a branch:: Merging an entire branch 4242* Merging more than once:: Merging from a branch several times 4243* Merging two revisions:: Merging differences between two revisions 4244* Merging adds and removals:: What if files are added or removed? 4245* Merging and keywords:: Avoiding conflicts due to keyword substitution 4246@end menu 4247 4248@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4249@node Branches motivation 4250@section What branches are good for 4251@cindex Branches motivation 4252@cindex What branches are good for 4253@cindex Motivation for branches 4254 4255@c FIXME: this node mentions one way to use branches, 4256@c but it is by no means the only way. For example, 4257@c the technique of committing a new feature on a branch, 4258@c until it is ready for the main trunk. The whole 4259@c thing is generally speaking more akin to the 4260@c "Revision management" node although it isn't clear to 4261@c me whether policy matters should be centralized or 4262@c distributed throughout the relevant sections. 4263Suppose that release 1.0 of tc has been made. You are continuing to 4264develop tc, planning to create release 1.1 in a couple of months. After a 4265while your customers start to complain about a fatal bug. You check 4266out release 1.0 (@pxref{Tags}) and find the bug 4267(which turns out to have a trivial fix). However, the current revision 4268of the sources are in a state of flux and are not expected to be stable 4269for at least another month. There is no way to make a 4270bug fix release based on the newest sources. 4271 4272The thing to do in a situation like this is to create a @dfn{branch} on 4273the revision trees for all the files that make up 4274release 1.0 of tc. You can then make 4275modifications to the branch without disturbing the main trunk. When the 4276modifications are finished you can elect to either incorporate them on 4277the main trunk, or leave them on the branch. 4278 4279@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4280@node Creating a branch 4281@section Creating a branch 4282@cindex Creating a branch 4283@cindex Branch, creating a 4284@cindex tag (subcommand), creating a branch using 4285@cindex rtag (subcommand), creating a branch using 4286 4287You can create a branch with @code{tag -b}; for 4288example, assuming you're in a working copy: 4289 4290@example 4291$ cvs tag -b rel-1-0-patches 4292@end example 4293 4294@c FIXME: we should be more explicit about the value of 4295@c having a tag on the branchpoint. For example 4296@c "cvs tag rel-1-0-patches-branchpoint" before 4297@c the "cvs tag -b". This points out that 4298@c rel-1-0-patches is a pretty awkward name for 4299@c this example (more so than for the rtag example 4300@c below). 4301 4302This splits off a branch based on the current revisions 4303in the working copy, assigning that branch the name 4304@samp{rel-1-0-patches}. 4305 4306It is important to understand that branches get created 4307in the repository, not in the working copy. Creating a 4308branch based on current revisions, as the above example 4309does, will @emph{not} automatically switch the working 4310copy to be on the new branch. For information on how 4311to do that, see @ref{Accessing branches}. 4312 4313You can also create a branch without reference to any 4314working copy, by using @code{rtag}: 4315 4316@example 4317$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 4318@end example 4319 4320@samp{-r rel-1-0} says that this branch should be 4321rooted at the revision that 4322corresponds to the tag @samp{rel-1-0}. It need not 4323be the most recent revision -- it's often useful to 4324split a branch off an old revision (for example, when 4325fixing a bug in a past release otherwise known to be 4326stable). 4327 4328As with @samp{tag}, the @samp{-b} flag tells 4329@code{rtag} to create a branch (rather than just a 4330symbolic revision name). Note that the numeric 4331revision number that matches @samp{rel-1-0} will 4332probably be different from file to file. 4333 4334So, the full effect of the command is to create a new 4335branch -- named @samp{rel-1-0-patches} -- in module 4336@samp{tc}, rooted in the revision tree at the point tagged 4337by @samp{rel-1-0}. 4338 4339@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4340@node Accessing branches 4341@section Accessing branches 4342@cindex Check out a branch 4343@cindex Retrieve a branch 4344@cindex Access a branch 4345@cindex Identifying a branch 4346@cindex Branch, check out 4347@cindex Branch, retrieving 4348@cindex Branch, accessing 4349@cindex Branch, identifying 4350 4351You can retrieve a branch in one of two ways: by 4352checking it out fresh from the repository, or by 4353switching an existing working copy over to the branch. 4354 4355To check out a branch from the repository, invoke 4356@samp{checkout} with the @samp{-r} flag, followed by 4357the tag name of the branch (@pxref{Creating a branch}): 4358 4359@example 4360$ cvs checkout -r rel-1-0-patches tc 4361@end example 4362 4363Or, if you already have a working copy, you can switch 4364it to a given branch with @samp{update -r}: 4365 4366@example 4367$ cvs update -r rel-1-0-patches tc 4368@end example 4369 4370@noindent 4371or equivalently: 4372 4373@example 4374$ cd tc 4375$ cvs update -r rel-1-0-patches 4376@end example 4377 4378It does not matter if the working copy was originally 4379on the main trunk or on some other branch -- the above 4380command will switch it to the named branch. And 4381similarly to a regular @samp{update} command, 4382@samp{update -r} merges any changes you have made, 4383notifying you of conflicts where they occur. 4384 4385Once you have a working copy tied to a particular 4386branch, it remains there until you tell it otherwise. 4387This means that changes checked in from the working 4388copy will add new revisions on that branch, while 4389leaving the main trunk and other branches unaffected. 4390 4391@cindex Branches, sticky 4392To find out what branch a working copy is on, you can 4393use the @samp{status} command. In its output, look for 4394the field named @samp{Sticky tag} (@pxref{Sticky tags}) 4395-- that's @sc{cvs}'s way of telling you the branch, if 4396any, of the current working files: 4397 4398@example 4399$ cvs status -v driver.c backend.c 4400=================================================================== 4401File: driver.c Status: Up-to-date 4402 4403 Version: 1.7 Sat Dec 5 18:25:54 1992 4404 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 4405 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4406 Sticky Date: (none) 4407 Sticky Options: (none) 4408 4409 Existing Tags: 4410 rel-1-0-patches (branch: 1.7.2) 4411 rel-1-0 (revision: 1.7) 4412 4413=================================================================== 4414File: backend.c Status: Up-to-date 4415 4416 Version: 1.4 Tue Dec 1 14:39:01 1992 4417 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 4418 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 4419 Sticky Date: (none) 4420 Sticky Options: (none) 4421 4422 Existing Tags: 4423 rel-1-0-patches (branch: 1.4.2) 4424 rel-1-0 (revision: 1.4) 4425 rel-0-4 (revision: 1.4) 4426 4427@end example 4428 4429Don't be confused by the fact that the branch numbers 4430for each file are different (@samp{1.7.2} and 4431@samp{1.4.2} respectively). The branch tag is the 4432same, @samp{rel-1-0-patches}, and the files are 4433indeed on the same branch. The numbers simply reflect 4434the point in each file's revision history at which the 4435branch was made. In the above example, one can deduce 4436that @samp{driver.c} had been through more changes than 4437@samp{backend.c} before this branch was created. 4438 4439See @ref{Branches and revisions} for details about how 4440branch numbers are constructed. 4441 4442@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4443@node Branches and revisions 4444@section Branches and revisions 4445@cindex Branch number 4446@cindex Number, branch 4447@cindex Revision numbers (branches) 4448 4449Ordinarily, a file's revision history is a linear 4450series of increments (@pxref{Revision numbers}): 4451 4452@example 4453 +-----+ +-----+ +-----+ +-----+ +-----+ 4454 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 4455 +-----+ +-----+ +-----+ +-----+ +-----+ 4456@end example 4457 4458However, @sc{cvs} is not limited to linear development. The 4459@dfn{revision tree} can be split into @dfn{branches}, 4460where each branch is a self-maintained line of 4461development. Changes made on one branch can easily be 4462moved back to the main trunk. 4463 4464Each branch has a @dfn{branch number}, consisting of an 4465odd number of period-separated decimal integers. The 4466branch number is created by appending an integer to the 4467revision number where the corresponding branch forked 4468off. Having branch numbers allows more than one branch 4469to be forked off from a certain revision. 4470 4471@need 3500 4472All revisions on a branch have revision numbers formed 4473by appending an ordinal number to the branch number. 4474The following figure illustrates branching with an 4475example. 4476 4477@example 4478@c This example used to have a 1.2.2.4 revision, which 4479@c might help clarify that development can continue on 4480@c 1.2.2. Might be worth reinstating if it can be done 4481@c without overfull hboxes. 4482@group 4483 +-------------+ 4484 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 4485 / +-------------+ 4486 / 4487 / 4488 +---------+ +---------+ +---------+ 4489Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4490 / +---------+ +---------+ +---------+ 4491 / 4492 / 4493+-----+ +-----+ +-----+ +-----+ +-----+ 4494! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4495+-----+ +-----+ +-----+ +-----+ +-----+ 4496 ! 4497 ! 4498 ! +---------+ +---------+ +---------+ 4499Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 4500 +---------+ +---------+ +---------+ 4501 4502@end group 4503@end example 4504 4505@c -- However, at least for me the figure is not enough. I suggest more 4506@c -- text to accompany it. "A picture is worth a thousand words", so you 4507@c -- have to make sure the reader notices the couple of hundred words 4508@c -- *you* had in mind more than the others! 4509 4510@c -- Why an even number of segments? This section implies that this is 4511@c -- how the main trunk is distinguished from branch roots, but you never 4512@c -- explicitly say that this is the purpose of the [by itself rather 4513@c -- surprising] restriction to an even number of segments. 4514 4515The exact details of how the branch number is 4516constructed is not something you normally need to be 4517concerned about, but here is how it works: When 4518@sc{cvs} creates a branch number it picks the first 4519unused even integer, starting with 2. So when you want 4520to create a branch from revision 6.4 it will be 4521numbered 6.4.2. All branch numbers ending in a zero 4522(such as 6.4.0) are used internally by @sc{cvs} 4523(@pxref{Magic branch numbers}). The branch 1.1.1 has a 4524special meaning. @xref{Tracking sources}. 4525 4526@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4527@node Magic branch numbers 4528@section Magic branch numbers 4529 4530@c Want xref to here from "log"? 4531 4532This section describes a @sc{cvs} feature called 4533@dfn{magic branches}. For most purposes, you need not 4534worry about magic branches; @sc{cvs} handles them for 4535you. However, they are visible to you in certain 4536circumstances, so it may be useful to have some idea of 4537how it works. 4538 4539Externally, branch numbers consist of an odd number of 4540dot-separated decimal integers. @xref{Revision 4541numbers}. That is not the whole truth, however. For 4542efficiency reasons @sc{cvs} sometimes inserts an extra 0 4543in the second rightmost position (1.2.4 becomes 45441.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 4545on). 4546 4547@sc{cvs} does a pretty good job at hiding these so 4548called magic branches, but in a few places the hiding 4549is incomplete: 4550 4551@itemize @bullet 4552@ignore 4553@c This is in ignore as I'm taking their word for it, 4554@c that this was fixed 4555@c a long time ago. But before deleting this 4556@c entirely, I'd rather verify it (and add a test 4557@c case to the testsuite). 4558@item 4559The magic branch can appear in the output from 4560@code{cvs status} in vanilla @sc{cvs} 1.3. This is 4561fixed in @sc{cvs} 1.3-s2. 4562 4563@end ignore 4564@item 4565The magic branch number appears in the output from 4566@code{cvs log}. 4567@c What output should appear instead? 4568 4569@item 4570You cannot specify a symbolic branch name to @code{cvs 4571admin}. 4572 4573@end itemize 4574 4575@c Can CVS do this automatically the first time 4576@c you check something in to that branch? Should 4577@c it? 4578You can use the @code{admin} command to reassign a 4579symbolic name to a branch the way @sc{rcs} expects it 4580to be. If @code{R4patches} is assigned to the branch 45811.4.2 (magic branch number 1.4.0.2) in file 4582@file{numbers.c} you can do this: 4583 4584@example 4585$ cvs admin -NR4patches:1.4.2 numbers.c 4586@end example 4587 4588It only works if at least one revision is already 4589committed on the branch. Be very careful so that you 4590do not assign the tag to the wrong number. (There is 4591no way to see how the tag was assigned yesterday). 4592 4593@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4594@node Merging a branch 4595@section Merging an entire branch 4596@cindex Merging a branch 4597@cindex -j (merging branches) 4598 4599You can merge changes made on a branch into your working copy by giving 4600the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 4601@samp{-j @var{branchname}} option it merges the changes made between the 4602greatest common ancestor (GCA) of the branch and the destination revision (in 4603the simple case below the GCA is the point where the branch forked) and the 4604newest revision on that branch into your working copy. 4605 4606@cindex Join 4607The @samp{-j} stands for ``join''. 4608 4609@cindex Branch merge example 4610@cindex Example, branch merge 4611@cindex Merge, branch example 4612Consider this revision tree: 4613 4614@example 4615+-----+ +-----+ +-----+ +-----+ 4616! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 4617+-----+ +-----+ +-----+ +-----+ 4618 ! 4619 ! 4620 ! +---------+ +---------+ 4621Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4622 +---------+ +---------+ 4623@end example 4624 4625@noindent 4626The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 4627following example assumes that the module @samp{mod} contains only one 4628file, @file{m.c}. 4629 4630@example 4631$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 4632 4633$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 4634 # @r{i.e. the changes between revision 1.2} 4635 # @r{and 1.2.2.2, into your working copy} 4636 # @r{of the file.} 4637 4638$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 4639@end example 4640 4641A conflict can result from a merge operation. If that 4642happens, you should resolve it before committing the 4643new revision. @xref{Conflicts example}. 4644 4645If your source files contain keywords (@pxref{Keyword substitution}), 4646you might be getting more conflicts than strictly necessary. See 4647@ref{Merging and keywords}, for information on how to avoid this. 4648 4649The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 4650same effect as above could be achieved with this: 4651 4652@example 4653$ cvs checkout -j R1fix mod 4654$ cvs commit -m "Included R1fix" 4655@end example 4656 4657It should be noted that @code{update -j @var{tagname}} will also work but may 4658not produce the desired result. @xref{Merging adds and removals}, for more. 4659 4660@node Merging more than once 4661@section Merging from a branch several times 4662 4663Continuing our example, the revision tree now looks 4664like this: 4665 4666@example 4667+-----+ +-----+ +-----+ +-----+ +-----+ 4668! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4669+-----+ +-----+ +-----+ +-----+ +-----+ 4670 ! * 4671 ! * 4672 ! +---------+ +---------+ 4673Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4674 +---------+ +---------+ 4675@end example 4676 4677@noindent 4678where the starred line represents the merge from the 4679@samp{R1fix} branch to the main trunk, as just 4680discussed. 4681 4682Now suppose that development continues on the 4683@samp{R1fix} branch: 4684 4685@example 4686+-----+ +-----+ +-----+ +-----+ +-----+ 4687! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4688+-----+ +-----+ +-----+ +-----+ +-----+ 4689 ! * 4690 ! * 4691 ! +---------+ +---------+ +---------+ 4692Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4693 +---------+ +---------+ +---------+ 4694@end example 4695 4696@noindent 4697and then you want to merge those new changes onto the 4698main trunk. If you just use the @code{cvs update -j 4699R1fix m.c} command again, @sc{cvs} will attempt to 4700merge again the changes which you have already merged, 4701which can have undesirable side effects. 4702 4703So instead you need to specify that you only want to 4704merge the changes on the branch which have not yet been 4705merged into the trunk. To do that you specify two 4706@samp{-j} options, and @sc{cvs} merges the changes from 4707the first revision to the second revision. For 4708example, in this case the simplest way would be 4709 4710@example 4711cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 4712 # @r{head of the R1fix branch} 4713@end example 4714 4715The problem with this is that you need to specify the 47161.2.2.2 revision manually. A slightly better approach 4717might be to use the date the last merge was done: 4718 4719@example 4720cvs update -j R1fix:yesterday -j R1fix m.c 4721@end example 4722 4723Better yet, tag the R1fix branch after every merge into 4724the trunk, and then use that tag for subsequent merges: 4725 4726@example 4727cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 4728@end example 4729 4730@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4731@node Merging two revisions 4732@section Merging differences between any two revisions 4733@cindex Merging two revisions 4734@cindex Revisions, merging differences between 4735@cindex Differences, merging 4736 4737With two @samp{-j @var{revision}} flags, the @code{update} 4738(and @code{checkout}) command can merge the differences 4739between any two revisions into your working file. 4740 4741@cindex Undoing a change 4742@cindex Removing a change 4743@example 4744$ cvs update -j 1.5 -j 1.3 backend.c 4745@end example 4746 4747@noindent 4748will undo all changes made between revision 47491.3 and 1.5. Note the order of the revisions! 4750 4751If you try to use this option when operating on 4752multiple files, remember that the numeric revisions will 4753probably be very different between the various files. 4754You almost always use symbolic 4755tags rather than revision numbers when operating on 4756multiple files. 4757 4758@cindex Restoring old version of removed file 4759@cindex Resurrecting old version of dead file 4760Specifying two @samp{-j} options can also undo file 4761removals or additions. For example, suppose you have 4762a file 4763named @file{file1} which existed as revision 1.1, and 4764you then removed it (thus adding a dead revision 1.2). 4765Now suppose you want to add it again, with the same 4766contents it had previously. Here is how to do it: 4767 4768@example 4769$ cvs update -j 1.2 -j 1.1 file1 4770U file1 4771$ cvs commit -m test 4772Checking in file1; 4773/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 4774new revision: 1.3; previous revision: 1.2 4775done 4776$ 4777@end example 4778 4779@node Merging adds and removals 4780@section Merging can add or remove files 4781 4782If the changes which you are merging involve removing 4783or adding some files, @code{update -j} will reflect 4784such additions or removals. 4785 4786@c FIXME: This example needs a lot more explanation. 4787@c We also need other examples for some of the other 4788@c cases (not all--there are too many--as long as we present a 4789@c coherent general principle). 4790For example: 4791@example 4792cvs update -A 4793touch a b c 4794cvs add a b c ; cvs ci -m "added" a b c 4795cvs tag -b branchtag 4796cvs update -r branchtag 4797touch d ; cvs add d 4798rm a ; cvs rm a 4799cvs ci -m "added d, removed a" 4800cvs update -A 4801cvs update -jbranchtag 4802@end example 4803 4804After these commands are executed and a @samp{cvs commit} is done, 4805file @file{a} will be removed and file @file{d} added in the main branch. 4806@c (which was determined by trying it) 4807 4808Note that using a single static tag (@samp{-j @var{tagname}}) 4809rather than a dynamic tag (@samp{-j @var{branchname}}) to merge 4810changes from a branch will usually not remove files which were removed on the 4811branch since @sc{cvs} does not automatically add static tags to dead revisions. 4812The exception to this rule occurs when 4813a static tag has been attached to a dead revision manually. Use the branch tag 4814to merge all changes from the branch or use two static tags as merge endpoints 4815to be sure that all intended changes are propagated in the merge. 4816 4817@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4818@node Merging and keywords 4819@section Merging and keywords 4820@cindex Merging, and keyword substitution 4821@cindex Keyword substitution, and merging 4822@cindex -j (merging branches), and keyword substitution 4823@cindex -kk, to avoid conflicts during a merge 4824 4825If you merge files containing keywords (@pxref{Keyword 4826substitution}), you will normally get numerous 4827conflicts during the merge, because the keywords are 4828expanded differently in the revisions which you are 4829merging. 4830 4831Therefore, you will often want to specify the 4832@samp{-kk} (@pxref{Substitution modes}) switch to the 4833merge command line. By substituting just the name of 4834the keyword, not the expanded value of that keyword, 4835this option ensures that the revisions which you are 4836merging will be the same as each other, and avoid 4837spurious conflicts. 4838 4839For example, suppose you have a file like this: 4840 4841@example 4842 +---------+ 4843 _! 1.1.2.1 ! <- br1 4844 / +---------+ 4845 / 4846 / 4847+-----+ +-----+ 4848! 1.1 !----! 1.2 ! 4849+-----+ +-----+ 4850@end example 4851 4852@noindent 4853and your working directory is currently on the trunk 4854(revision 1.2). Then you might get the following 4855results from a merge: 4856 4857@example 4858$ cat file1 4859key $@splitrcskeyword{Revision}: 1.2 $ 4860. . . 4861$ cvs update -j br1 4862U file1 4863RCS file: /cvsroot/first-dir/file1,v 4864retrieving revision 1.1 4865retrieving revision 1.1.2.1 4866Merging differences between 1.1 and 1.1.2.1 into file1 4867rcsmerge: warning: conflicts during merge 4868$ cat file1 4869@asis{}<<<<<<< file1 4870key $@splitrcskeyword{Revision}: 1.2 $ 4871@asis{}======= 4872key $@splitrcskeyword{Revision}: 1.1.2.1 $ 4873@asis{}>>>>>>> 1.1.2.1 4874. . . 4875@end example 4876 4877What happened was that the merge tried to merge the 4878differences between 1.1 and 1.1.2.1 into your working 4879directory. So, since the keyword changed from 4880@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 4881@sc{cvs} tried to merge that change into your working 4882directory, which conflicted with the fact that your 4883working directory had contained @code{Revision: 1.2}. 4884 4885Here is what happens if you had used @samp{-kk}: 4886 4887@example 4888$ cat file1 4889key $@splitrcskeyword{Revision}: 1.2 $ 4890. . . 4891$ cvs update -kk -j br1 4892U file1 4893RCS file: /cvsroot/first-dir/file1,v 4894retrieving revision 1.1 4895retrieving revision 1.1.2.1 4896Merging differences between 1.1 and 1.1.2.1 into file1 4897$ cat file1 4898key $@splitrcskeyword{Revision}$ 4899. . . 4900@end example 4901 4902What is going on here is that revision 1.1 and 1.1.2.1 4903both expand as plain @code{Revision}, and therefore 4904merging the changes between them into the working 4905directory need not change anything. Therefore, there 4906is no conflict. 4907 4908@strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a 4909major problem with using @samp{-kk} on merges. Namely, @samp{-kk} 4910overrode any default keyword expansion mode set in the archive file in 4911the repository. This could, unfortunately for some users, cause data 4912corruption in binary files (with a default keyword expansion mode set 4913to @samp{-kb}). Therefore, when a repository contained binary files, 4914conflicts had to be dealt with manually rather than using @samp{-kk} in 4915a merge command.} 4916 4917In @sc{cvs} version 1.12.2 and later, the keyword expansion mode 4918provided on the command line to any @sc{cvs} command no longer 4919overrides the @samp{-kb} keyword expansion mode setting for binary 4920files, though it will still override other default keyword expansion 4921modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts 4922on lines containing RCS keywords, even when your repository contains 4923binary files. 4924 4925@c --------------------------------------------------------------------- 4926@node Recursive behavior 4927@chapter Recursive behavior 4928@cindex Recursive (directory descending) 4929@cindex Directory, descending 4930@cindex Descending directories 4931@cindex Subdirectories 4932 4933Almost all of the subcommands of @sc{cvs} work 4934recursively when you specify a directory as an 4935argument. For instance, consider this directory 4936structure: 4937 4938@example 4939 @code{$HOME} 4940 | 4941 +--@t{tc} 4942 | | 4943 +--@t{CVS} 4944 | (internal @sc{cvs} files) 4945 +--@t{Makefile} 4946 +--@t{backend.c} 4947 +--@t{driver.c} 4948 +--@t{frontend.c} 4949 +--@t{parser.c} 4950 +--@t{man} 4951 | | 4952 | +--@t{CVS} 4953 | | (internal @sc{cvs} files) 4954 | +--@t{tc.1} 4955 | 4956 +--@t{testing} 4957 | 4958 +--@t{CVS} 4959 | (internal @sc{cvs} files) 4960 +--@t{testpgm.t} 4961 +--@t{test2.t} 4962@end example 4963 4964@noindent 4965If @file{tc} is the current working directory, the 4966following is true: 4967 4968@itemize @bullet 4969@item 4970@samp{cvs update testing} is equivalent to 4971 4972@example 4973cvs update testing/testpgm.t testing/test2.t 4974@end example 4975 4976@item 4977@samp{cvs update testing man} updates all files in the 4978subdirectories 4979 4980@item 4981@samp{cvs update .} or just @samp{cvs update} updates 4982all files in the @code{tc} directory 4983@end itemize 4984 4985If no arguments are given to @code{update} it will 4986update all files in the current working directory and 4987all its subdirectories. In other words, @file{.} is a 4988default argument to @code{update}. This is also true 4989for most of the @sc{cvs} subcommands, not only the 4990@code{update} command. 4991 4992The recursive behavior of the @sc{cvs} subcommands can be 4993turned off with the @samp{-l} option. 4994Conversely, the @samp{-R} option can be used to force recursion if 4995@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 4996 4997@example 4998$ cvs update -l # @r{Don't update files in subdirectories} 4999@end example 5000 5001@c --------------------------------------------------------------------- 5002@node Adding and removing 5003@chapter Adding, removing, and renaming files and directories 5004 5005In the course of a project, one will often add new 5006files. Likewise with removing or renaming, or with 5007directories. The general concept to keep in mind in 5008all these cases is that instead of making an 5009irreversible change you want @sc{cvs} to record the 5010fact that a change has taken place, just as with 5011modifying an existing file. The exact mechanisms to do 5012this in @sc{cvs} vary depending on the situation. 5013 5014@menu 5015* Adding files:: Adding files 5016* Removing files:: Removing files 5017* Removing directories:: Removing directories 5018* Moving files:: Moving and renaming files 5019* Moving directories:: Moving and renaming directories 5020@end menu 5021 5022@node Adding files 5023@section Adding files to a directory 5024@cindex Adding files 5025 5026To add a new file to a directory, follow these steps. 5027 5028@itemize @bullet 5029@item 5030You must have a working copy of the directory. 5031@xref{Getting the source}. 5032 5033@item 5034Create the new file inside your working copy of the directory. 5035 5036@item 5037Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you 5038want to version control the file. If the file contains 5039binary data, specify @samp{-kb} (@pxref{Binary files}). 5040 5041@item 5042Use @samp{cvs commit @var{filename}} to actually check 5043in the file into the repository. Other developers 5044cannot see the file until you perform this step. 5045@end itemize 5046 5047You can also use the @code{add} command to add a new 5048directory. 5049@c FIXCVS and/or FIXME: Adding a directory doesn't 5050@c require the commit step. This probably can be 5051@c considered a CVS bug, but it is possible we should 5052@c warn people since this behavior probably won't be 5053@c changing right away. 5054 5055Unlike most other commands, the @code{add} command is 5056not recursive. You have to expcicitly name files and 5057directories that you wish to add to the repository. 5058However, each directory will need to be added 5059separately before you will be able to add new files 5060to those directories. 5061 5062@example 5063$ mkdir -p foo/bar 5064$ cp ~/myfile foo/bar/myfile 5065$ cvs add foo foo/bar 5066$ cvs add foo/bar/myfile 5067@end example 5068 5069@cindex add (subcommand) 5070@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 5071 5072Schedule @var{files} to be added to the repository. 5073The files or directories specified with @code{add} must 5074already exist in the current directory. To add a whole 5075new directory hierarchy to the source repository (for 5076example, files received from a third-party vendor), use 5077the @code{import} command instead. @xref{import}. 5078 5079The added files are not placed in the source repository 5080until you use @code{commit} to make the change 5081permanent. Doing an @code{add} on a file that was 5082removed with the @code{remove} command will undo the 5083effect of the @code{remove}, unless a @code{commit} 5084command intervened. @xref{Removing files}, for an 5085example. 5086 5087The @samp{-k} option specifies the default way that 5088this file will be checked out; for more information see 5089@ref{Substitution modes}. 5090 5091@c As noted in BUGS, -m is broken client/server (Nov 5092@c 96). Also see testsuite log2-* tests. 5093The @samp{-m} option specifies a description for the 5094file. This description appears in the history log (if 5095it is enabled, @pxref{history file}). It will also be 5096saved in the version history inside the repository when 5097the file is committed. The @code{log} command displays 5098this description. The description can be changed using 5099@samp{admin -t}. @xref{admin}. If you omit the 5100@samp{-m @var{description}} flag, an empty string will 5101be used. You will not be prompted for a description. 5102@end deffn 5103 5104For example, the following commands add the file 5105@file{backend.c} to the repository: 5106 5107@c This example used to specify 5108@c -m "Optimizer and code generation passes." 5109@c to the cvs add command, but that doesn't work 5110@c client/server (see log2 in sanity.sh). Should fix CVS, 5111@c but also seems strange to document things which 5112@c don't work... 5113@example 5114$ cvs add backend.c 5115$ cvs commit -m "Early version. Not yet compilable." backend.c 5116@end example 5117 5118When you add a file it is added only on the branch 5119which you are working on (@pxref{Branching and merging}). You can 5120later merge the additions to another branch if you want 5121(@pxref{Merging adds and removals}). 5122@c Should we mention that earlier versions of CVS 5123@c lacked this feature (1.3) or implemented it in a buggy 5124@c way (well, 1.8 had many bugs in cvs update -j)? 5125@c Should we mention the bug/limitation regarding a 5126@c file being a regular file on one branch and a directory 5127@c on another? 5128@c FIXME: This needs an example, or several, here or 5129@c elsewhere, for it to make much sense. 5130@c Somewhere we need to discuss the aspects of death 5131@c support which don't involve branching, I guess. 5132@c Like the ability to re-create a release from a tag. 5133 5134@c --------------------------------------------------------------------- 5135@node Removing files 5136@section Removing files 5137@cindex Removing files 5138@cindex Deleting files 5139 5140@c FIXME: this node wants to be split into several 5141@c smaller nodes. Could make these children of 5142@c "Adding and removing", probably (death support could 5143@c be its own section, for example, as could the 5144@c various bits about undoing mistakes in adding and 5145@c removing). 5146Directories change. New files are added, and old files 5147disappear. Still, you want to be able to retrieve an 5148exact copy of old releases. 5149 5150Here is what you can do to remove a file, 5151but remain able to retrieve old revisions: 5152 5153@itemize @bullet 5154@c FIXME: should probably be saying something about 5155@c having a working directory in the first place. 5156@item 5157Make sure that you have not made any uncommitted 5158modifications to the file. @xref{Viewing differences}, 5159for one way to do that. You can also use the 5160@code{status} or @code{update} command. If you remove 5161the file without committing your changes, you will of 5162course not be able to retrieve the file as it was 5163immediately before you deleted it. 5164 5165@item 5166Remove the file from your working copy of the directory. 5167You can for instance use @code{rm}. 5168 5169@item 5170Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that 5171you really want to delete the file. 5172 5173@item 5174Use @samp{cvs commit @var{filename}} to actually 5175perform the removal of the file from the repository. 5176@end itemize 5177 5178@c FIXME: Somehow this should be linked in with a more 5179@c general discussion of death support. I don't know 5180@c whether we want to use the term "death support" or 5181@c not (we can perhaps get by without it), but we do 5182@c need to discuss the "dead" state in "cvs log" and 5183@c related subjects. The current discussion is 5184@c scattered around, and not xref'd to each other. 5185@c FIXME: I think this paragraph wants to be moved 5186@c later down, at least after the first example. 5187When you commit the removal of the file, @sc{cvs} 5188records the fact that the file no longer exists. It is 5189possible for a file to exist on only some branches and 5190not on others, or to re-add another file with the same 5191name later. @sc{cvs} will correctly create or not create 5192the file, based on the @samp{-r} and @samp{-D} options 5193specified to @code{checkout} or @code{update}. 5194 5195@c FIXME: This style seems to clash with how we 5196@c document things in general. 5197@cindex Remove (subcommand) 5198@deffn Command {cvs remove} [options] files @dots{} 5199 5200Schedule file(s) to be removed from the repository 5201(files which have not already been removed from the 5202working directory are not processed). This command 5203does not actually remove the file from the repository 5204until you commit the removal. For a full list of 5205options, see @ref{Invoking CVS}. 5206@end deffn 5207 5208Here is an example of removing several files: 5209 5210@example 5211$ cd test 5212$ rm *.c 5213$ cvs remove 5214cvs remove: Removing . 5215cvs remove: scheduling a.c for removal 5216cvs remove: scheduling b.c for removal 5217cvs remove: use 'cvs commit' to remove these files permanently 5218$ cvs ci -m "Removed unneeded files" 5219cvs commit: Examining . 5220cvs commit: Committing . 5221@end example 5222 5223As a convenience you can remove the file and @code{cvs 5224remove} it in one step, by specifying the @samp{-f} 5225option. For example, the above example could also be 5226done like this: 5227 5228@example 5229$ cd test 5230$ cvs remove -f *.c 5231cvs remove: scheduling a.c for removal 5232cvs remove: scheduling b.c for removal 5233cvs remove: use 'cvs commit' to remove these files permanently 5234$ cvs ci -m "Removed unneeded files" 5235cvs commit: Examining . 5236cvs commit: Committing . 5237@end example 5238 5239If you execute @code{remove} for a file, and then 5240change your mind before you commit, you can undo the 5241@code{remove} with an @code{add} command. 5242@ignore 5243@c is this worth saying or not? Somehow it seems 5244@c confusing to me. 5245Of course, 5246since you have removed your copy of file in the working 5247directory, @sc{cvs} does not necessarily bring back the 5248contents of the file from right before you executed 5249@code{remove}; instead it gets the file from the 5250repository again. 5251@end ignore 5252 5253@c FIXME: what if you change your mind after you commit 5254@c it? (answer is also "cvs add" but we don't say that...). 5255@c We need some index entries for thinks like "undoing 5256@c removal" too. 5257 5258@example 5259$ ls 5260CVS ja.h oj.c 5261$ rm oj.c 5262$ cvs remove oj.c 5263cvs remove: scheduling oj.c for removal 5264cvs remove: use 'cvs commit' to remove this file permanently 5265$ cvs add oj.c 5266U oj.c 5267cvs add: oj.c, version 1.1.1.1, resurrected 5268@end example 5269 5270If you realize your mistake before you run the 5271@code{remove} command you can use @code{update} to 5272resurrect the file: 5273 5274@example 5275$ rm oj.c 5276$ cvs update oj.c 5277cvs update: warning: oj.c was lost 5278U oj.c 5279@end example 5280 5281When you remove a file it is removed only on the branch 5282which you are working on (@pxref{Branching and merging}). You can 5283later merge the removals to another branch if you want 5284(@pxref{Merging adds and removals}). 5285 5286@node Removing directories 5287@section Removing directories 5288@cindex Removing directories 5289@cindex Directories, removing 5290 5291In concept, removing directories is somewhat similar to 5292removing files---you want the directory to not exist in 5293your current working directories, but you also want to 5294be able to retrieve old releases in which the directory 5295existed. 5296 5297The way that you remove a directory is to remove all 5298the files in it. You don't remove the directory 5299itself; there is no way to do that. 5300Instead you specify the @samp{-P} option to 5301@code{cvs update} or @code{cvs checkout}, 5302which will cause @sc{cvs} to remove empty 5303directories from working directories. 5304(Note that @code{cvs export} always removes empty directories.) 5305Probably the 5306best way to do this is to always specify @samp{-P}; if 5307you want an empty directory then put a dummy file (for 5308example @file{.keepme}) in it to prevent @samp{-P} from 5309removing it. 5310 5311@c I'd try to give a rationale for this, but I'm not 5312@c sure there is a particularly convincing one. What 5313@c we would _like_ is for CVS to do a better job of version 5314@c controlling whether directories exist, to eliminate the 5315@c need for -P and so that a file can be a directory in 5316@c one revision and a regular file in another. 5317Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5318options of @code{checkout}. This way, 5319@sc{cvs} will be able to correctly create the directory 5320or not depending on whether the particular version you 5321are checking out contains any files in that directory. 5322 5323@c --------------------------------------------------------------------- 5324@node Moving files 5325@section Moving and renaming files 5326@cindex Moving files 5327@cindex Renaming files 5328@cindex Files, moving 5329 5330Moving files to a different directory or renaming them 5331is not difficult, but some of the ways in which this 5332works may be non-obvious. (Moving or renaming a 5333directory is even harder. @xref{Moving directories}.). 5334 5335The examples below assume that the file @var{old} is renamed to 5336@var{new}. 5337 5338@menu 5339* Outside:: The normal way to Rename 5340* Inside:: A tricky, alternative way 5341* Rename by copying:: Another tricky, alternative way 5342@end menu 5343 5344@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5345@node Outside 5346@subsection The Normal way to Rename 5347 5348@c More rename issues. Not sure whether these are 5349@c worth documenting; I'm putting them here because 5350@c it seems to be as good a place as any to try to 5351@c set down the issues. 5352@c * "cvs annotate" will annotate either the new 5353@c file or the old file; it cannot annotate _each 5354@c line_ based on whether it was last changed in the 5355@c new or old file. Unlike "cvs log", where the 5356@c consequences of having to select either the new 5357@c or old name seem fairly benign, this may be a 5358@c real advantage to having CVS know about renames 5359@c other than as a deletion and an addition. 5360 5361The normal way to move a file is to copy @var{old} to 5362@var{new}, and then issue the normal @sc{cvs} commands 5363to remove @var{old} from the repository, and add 5364@var{new} to it. 5365@c The following sentence is not true: one must cd into 5366@c the directory to run "cvs add". 5367@c (Both @var{old} and @var{new} could 5368@c contain relative paths, for example @file{foo/bar.c}). 5369 5370@example 5371$ mv @var{old} @var{new} 5372$ cvs remove @var{old} 5373$ cvs add @var{new} 5374$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 5375@end example 5376 5377This is the simplest way to move a file, it is not 5378error-prone, and it preserves the history of what was 5379done. Note that to access the history of the file you 5380must specify the old or the new name, depending on what 5381portion of the history you are accessing. For example, 5382@code{cvs log @var{old}} will give the log up until the 5383time of the rename. 5384 5385When @var{new} is committed its revision numbers will 5386start again, usually at 1.1, so if that bothers you, 5387use the @samp{-r @var{tag}} option to commit. For more 5388information see @ref{Assigning revisions}. 5389 5390@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5391@node Inside 5392@subsection Moving the history file 5393 5394This method is more dangerous, since it involves moving 5395files inside the repository. Read this entire section 5396before trying it out! 5397 5398@example 5399$ cd $CVSROOT/@var{dir} 5400$ mv @var{old},v @var{new},v 5401@end example 5402 5403@noindent 5404Advantages: 5405 5406@itemize @bullet 5407@item 5408The log of changes is maintained intact. 5409 5410@item 5411The revision numbers are not affected. 5412@end itemize 5413 5414@noindent 5415Disadvantages: 5416 5417@itemize @bullet 5418@item 5419Old releases cannot easily be fetched from the 5420repository. (The file will show up as @var{new} even 5421in revisions from the time before it was renamed). 5422 5423@item 5424There is no log information of when the file was renamed. 5425 5426@item 5427Nasty things might happen if someone accesses the history file 5428while you are moving it. Make sure no one else runs any of the @sc{cvs} 5429commands while you move it. 5430@end itemize 5431 5432@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5433@node Rename by copying 5434@subsection Copying the history file 5435 5436This way also involves direct modifications to the 5437repository. It is safe, but not without drawbacks. 5438 5439@example 5440# @r{Copy the @sc{rcs} file inside the repository} 5441$ cd $CVSROOT/@var{dir} 5442$ cp @var{old},v @var{new},v 5443# @r{Remove the old file} 5444$ cd ~/@var{dir} 5445$ rm @var{old} 5446$ cvs remove @var{old} 5447$ cvs commit @var{old} 5448# @r{Remove all tags from @var{new}} 5449$ cvs update @var{new} 5450$ cvs log @var{new} # @r{Remember the non-branch tag names} 5451$ cvs tag -d @var{tag1} @var{new} 5452$ cvs tag -d @var{tag2} @var{new} 5453@dots{} 5454@end example 5455 5456By removing the tags you will be able to check out old 5457revisions. 5458 5459@noindent 5460Advantages: 5461 5462@itemize @bullet 5463@item 5464@c FIXME: Is this true about -D now that we have death 5465@c support? See 5B.3 in the FAQ. 5466Checking out old revisions works correctly, as long as 5467you use @samp{-r @var{tag}} and not @samp{-D @var{date}} 5468to retrieve the revisions. 5469 5470@item 5471The log of changes is maintained intact. 5472 5473@item 5474The revision numbers are not affected. 5475@end itemize 5476 5477@noindent 5478Disadvantages: 5479 5480@itemize @bullet 5481@item 5482You cannot easily see the history of the file across the rename. 5483 5484@ignore 5485@c Is this true? I don't see how the revision numbers 5486@c _could_ start over, when new,v is just old,v with 5487@c the tags deleted. 5488@c If there is some need to reinstate this text, 5489@c it is "usually 1.1", not "1.0" and it needs an 5490@c xref to Assigning revisions 5491@item 5492Unless you use the @samp{-r @var{tag}} (@pxref{commit 5493options}) flag when @var{new} is committed its revision 5494numbers will start at 1.0 again. 5495@end ignore 5496@end itemize 5497 5498@c --------------------------------------------------------------------- 5499@node Moving directories 5500@section Moving and renaming directories 5501@cindex Moving directories 5502@cindex Renaming directories 5503@cindex Directories, moving 5504 5505The normal way to rename or move a directory is to 5506rename or move each file within it as described in 5507@ref{Outside}. Then check out with the @samp{-P} 5508option, as described in @ref{Removing directories}. 5509 5510If you really want to hack the repository to rename or 5511delete a directory in the repository, you can do it 5512like this: 5513 5514@enumerate 5515@item 5516Inform everyone who has a checked out copy of the directory that the 5517directory will be renamed. They should commit all their changes in all their 5518copies of the project containing the directory to be removed, and remove 5519all their working copies of said project, before you take the steps below. 5520 5521@item 5522Rename the directory inside the repository. 5523 5524@example 5525$ cd $CVSROOT/@var{parent-dir} 5526$ mv @var{old-dir} @var{new-dir} 5527@end example 5528 5529@item 5530Fix the @sc{cvs} administrative files, if necessary (for 5531instance if you renamed an entire module). 5532 5533@item 5534Tell everyone that they can check out again and continue 5535working. 5536 5537@end enumerate 5538 5539If someone had a working copy the @sc{cvs} commands will 5540cease to work for him, until he removes the directory 5541that disappeared inside the repository. 5542 5543It is almost always better to move the files in the 5544directory instead of moving the directory. If you move the 5545directory you are unlikely to be able to retrieve old 5546releases correctly, since they probably depend on the 5547name of the directories. 5548 5549@c --------------------------------------------------------------------- 5550@node History browsing 5551@chapter History browsing 5552@cindex History browsing 5553@cindex Traceability 5554@cindex Isolation 5555 5556@ignore 5557@c This is too long for an introduction (goal is 5558@c one 20x80 character screen), and also mixes up a 5559@c variety of issues (parallel development, history, 5560@c maybe even touches on process control). 5561 5562@c -- @quote{To lose ones history is to lose ones soul.} 5563@c -- /// 5564@c -- ///Those who cannot remember the past are condemned to repeat it. 5565@c -- /// -- George Santayana 5566@c -- /// 5567 5568@sc{cvs} tries to make it easy for a group of people to work 5569together. This is done in two ways: 5570 5571@itemize @bullet 5572@item 5573Isolation---You have your own working copy of the 5574source. You are not affected by modifications made by 5575others until you decide to incorporate those changes 5576(via the @code{update} command---@pxref{update}). 5577 5578@item 5579Traceability---When something has changed, you can 5580always see @emph{exactly} what changed. 5581@end itemize 5582 5583There are several features of @sc{cvs} that together lead 5584to traceability: 5585 5586@itemize @bullet 5587@item 5588Each revision of a file has an accompanying log 5589message. 5590 5591@item 5592All commits are optionally logged to a central history 5593database. 5594 5595@item 5596Logging information can be sent to a user-defined 5597program (@pxref{loginfo}). 5598@end itemize 5599 5600@c -- More text here. 5601 5602This chapter should talk about the history file, the 5603@code{log} command, the usefulness of ChangeLogs 5604even when you run @sc{cvs}, and things like that. 5605 5606@end ignore 5607 5608@c kind of lame, in a lot of ways the above text inside 5609@c the @ignore motivates this chapter better 5610Once you have used @sc{cvs} to store a version control 5611history---what files have changed when, how, and by 5612whom, there are a variety of mechanisms for looking 5613through the history. 5614 5615@c FIXME: should also be talking about how you look at 5616@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 5617@menu 5618* log messages:: Log messages 5619* history database:: The history database 5620* user-defined logging:: User-defined logging 5621@end menu 5622 5623@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5624@node log messages 5625@section Log messages 5626 5627@c FIXME: @xref to place where we talk about how to 5628@c specify message to commit. 5629Whenever you commit a file you specify a log message. 5630 5631@c FIXME: bring the information here, and get rid of or 5632@c greatly shrink the "log" node. 5633To look through the log messages which have been 5634specified for every revision which has been committed, 5635use the @code{cvs log} command (@pxref{log}). 5636 5637@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5638@node history database 5639@section The history database 5640 5641@c FIXME: bring the information from the history file 5642@c and history nodes here. Rewrite it to be motivated 5643@c better (start out by clearly explaining what gets 5644@c logged in history, for example). 5645You can use the history file (@pxref{history file}) to 5646log various @sc{cvs} actions. To retrieve the 5647information from the history file, use the @code{cvs 5648history} command (@pxref{history}). 5649 5650Note: you can control what is logged to this file by using the 5651@samp{LogHistory} keyword in the @file{CVSROOT/config} file 5652(@pxref{config}). 5653 5654@c 5655@c The history database has many problems: 5656@c * It is very unclear what field means what. This 5657@c could be improved greatly by better documentation, 5658@c but there are still non-orthogonalities (for 5659@c example, tag does not record the "repository" 5660@c field but most records do). 5661@c * Confusion about files, directories, and modules. 5662@c Some commands record one, some record others. 5663@c * File removal is not logged. There is an 'R' 5664@c record type documented, but CVS never uses it. 5665@c * Tags are only logged for the "cvs rtag" command, 5666@c not "cvs tag". The fix for this is not completely 5667@c clear (see above about modules vs. files). 5668@c * Are there other cases of operations that are not 5669@c logged? One would hope for all changes to the 5670@c repository to be logged somehow (particularly 5671@c operations like tagging, "cvs admin -k", and other 5672@c operations which do not record a history that one 5673@c can get with "cvs log"). Operations on the working 5674@c directory, like export, get, and release, are a 5675@c second category also covered by the current "cvs 5676@c history". 5677@c * The history file does not record the options given 5678@c to a command. The most serious manifestation of 5679@c this is perhaps that it doesn't record whether a command 5680@c was recursive. It is not clear to me whether one 5681@c wants to log at a level very close to the command 5682@c line, as a sort of way of logging each command 5683@c (more or less), or whether one wants 5684@c to log more at the level of what was changed (or 5685@c something in between), but either way the current 5686@c information has pretty big gaps. 5687@c * Further details about a tag--like whether it is a 5688@c branch tag or, if a non-branch tag, which branch it 5689@c is on. One can find out this information about the 5690@c tag as it exists _now_, but if the tag has been 5691@c moved, one doesn't know what it was like at the time 5692@c the history record was written. 5693@c * Whether operating on a particular tag, date, or 5694@c options was implicit (sticky) or explicit. 5695@c 5696@c Another item, only somewhat related to the above, is a 5697@c way to control what is logged in the history file. 5698@c This is probably the only good way to handle 5699@c different people having different ideas about 5700@c information/space tradeoffs. 5701@c 5702@c It isn't really clear that it makes sense to try to 5703@c patch up the history file format as it exists now to 5704@c include all that stuff. It might be better to 5705@c design a whole new CVSROOT/nhistory file and "cvs 5706@c nhistory" command, or some such, or in some other 5707@c way trying to come up with a clean break from the 5708@c past, which can address the above concerns. Another 5709@c open question is how/whether this relates to 5710@c taginfo/loginfo/etc. 5711 5712@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5713@node user-defined logging 5714@section User-defined logging 5715 5716@c FIXME: probably should centralize this information 5717@c here, at least to some extent. Maybe by moving the 5718@c loginfo, etc., nodes here and replacing 5719@c the "user-defined logging" node with one node for 5720@c each method. 5721You can customize @sc{cvs} to log various kinds of 5722actions, in whatever manner you choose. These 5723mechanisms operate by executing a script at various 5724times. The script might append a message to a file 5725listing the information and the programmer who created 5726it, or send mail to a group of developers, or, perhaps, 5727post a message to a particular newsgroup. To log 5728commits, use the @file{loginfo} file (@pxref{loginfo}), and 5729to log tagging operations, use the @file{taginfo} file 5730(@pxref{taginfo}). 5731 5732@c FIXME: What is difference between doing it in the 5733@c modules file and using loginfo/taginfo? Why should 5734@c user use one or the other? 5735To log commits, checkouts, exports, and tags, 5736respectively, you can also use the @samp{-i}, 5737@samp{-o}, @samp{-e}, and @samp{-t} options in the 5738modules file. For a more flexible way of giving 5739notifications to various users, which requires less in 5740the way of keeping centralized scripts up to date, use 5741the @code{cvs watch add} command (@pxref{Getting 5742Notified}); this command is useful even if you are not 5743using @code{cvs watch on}. 5744 5745@c --------------------------------------------------------------------- 5746@node Binary files 5747@chapter Handling binary files 5748@cindex Binary files 5749 5750The most common use for @sc{cvs} is to store text 5751files. With text files, @sc{cvs} can merge revisions, 5752display the differences between revisions in a 5753human-visible fashion, and other such operations. 5754However, if you are willing to give up a few of these 5755abilities, @sc{cvs} can store binary files. For 5756example, one might store a web site in @sc{cvs} 5757including both text files and binary images. 5758 5759@menu 5760* Binary why:: More details on issues with binary files 5761* Binary howto:: How to store them 5762@end menu 5763 5764@node Binary why 5765@section The issues with binary files 5766 5767While the need to manage binary files may seem obvious 5768if the files that you customarily work with are binary, 5769putting them into version control does present some 5770additional issues. 5771 5772One basic function of version control is to show the 5773differences between two revisions. For example, if 5774someone else checked in a new version of a file, you 5775may wish to look at what they changed and determine 5776whether their changes are good. For text files, 5777@sc{cvs} provides this functionality via the @code{cvs 5778diff} command. For binary files, it may be possible to 5779extract the two revisions and then compare them with a 5780tool external to @sc{cvs} (for example, word processing 5781software often has such a feature). If there is no 5782such tool, one must track changes via other mechanisms, 5783such as urging people to write good log messages, and 5784hoping that the changes they actually made were the 5785changes that they intended to make. 5786 5787Another ability of a version control system is the 5788ability to merge two revisions. For @sc{cvs} this 5789happens in two contexts. The first is when users make 5790changes in separate working directories 5791(@pxref{Multiple developers}). The second is when one 5792merges explicitly with the @samp{update -j} command 5793(@pxref{Branching and merging}). 5794 5795In the case of text 5796files, @sc{cvs} can merge changes made independently, 5797and signal a conflict if the changes conflict. With 5798binary files, the best that @sc{cvs} can do is present 5799the two different copies of the file, and leave it to 5800the user to resolve the conflict. The user may choose 5801one copy or the other, or may run an external merge 5802tool which knows about that particular file format, if 5803one exists. 5804Note that having the user merge relies primarily on the 5805user to not accidentally omit some changes, and thus is 5806potentially error prone. 5807 5808If this process is thought to be undesirable, the best 5809choice may be to avoid merging. To avoid the merges 5810that result from separate working directories, see the 5811discussion of reserved checkouts (file locking) in 5812@ref{Multiple developers}. To avoid the merges 5813resulting from branches, restrict use of branches. 5814 5815@node Binary howto 5816@section How to store binary files 5817 5818There are two issues with using @sc{cvs} to store 5819binary files. The first is that @sc{cvs} by default 5820converts line endings between the canonical form in 5821which they are stored in the repository (linefeed 5822only), and the form appropriate to the operating system 5823in use on the client (for example, carriage return 5824followed by line feed for Windows NT). 5825 5826The second is that a binary file might happen to 5827contain data which looks like a keyword (@pxref{Keyword 5828substitution}), so keyword expansion must be turned 5829off. 5830 5831@c FIXME: the third is that one can't do merges with 5832@c binary files. xref to Multiple Developers and the 5833@c reserved checkout issues. 5834 5835The @samp{-kb} option available with some @sc{cvs} 5836commands insures that neither line ending conversion 5837nor keyword expansion will be done. 5838 5839Here is an example of how you can create a new file 5840using the @samp{-kb} flag: 5841 5842@example 5843$ echo '$@splitrcskeyword{Id}$' > kotest 5844$ cvs add -kb -m"A test file" kotest 5845$ cvs ci -m"First checkin; contains a keyword" kotest 5846@end example 5847 5848If a file accidentally gets added without @samp{-kb}, 5849one can use the @code{cvs admin} command to recover. 5850For example: 5851 5852@example 5853$ echo '$@splitrcskeyword{Id}$' > kotest 5854$ cvs add -m"A test file" kotest 5855$ cvs ci -m"First checkin; contains a keyword" kotest 5856$ cvs admin -kb kotest 5857$ cvs update -A kotest 5858# @r{For non-unix systems:} 5859# @r{Copy in a good copy of the file from outside CVS} 5860$ cvs commit -m "make it binary" kotest 5861@end example 5862 5863@c Trying to describe this for both unix and non-unix 5864@c in the same description is very confusing. Might 5865@c want to split the two, or just ditch the unix "shortcut" 5866@c (unixheads don't do much with binary files, anyway). 5867@c This used to say "(Try the above example, and do a 5868@c @code{cat kotest} after every command)". But that 5869@c only really makes sense for the unix case. 5870When you check in the file @file{kotest} the file is 5871not preserved as a binary file, because you did not 5872check it in as a binary file. The @code{cvs 5873admin -kb} command sets the default keyword 5874substitution method for this file, but it does not 5875alter the working copy of the file that you have. If you need to 5876cope with line endings (that is, you are using 5877@sc{cvs} on a non-unix system), then you need to 5878check in a new copy of the file, as shown by the 5879@code{cvs commit} command above. 5880On unix, the @code{cvs update -A} command suffices. 5881@c FIXME: should also describe what the *other users* 5882@c need to do, if they have checked out copies which 5883@c have been corrupted by lack of -kb. I think maybe 5884@c "cvs update -kb" or "cvs 5885@c update -A" would suffice, although the user who 5886@c reported this suggested removing the file, manually 5887@c removing it from CVS/Entries, and then "cvs update" 5888(Note that you can use @code{cvs log} to determine the default keyword 5889substitution method for a file and @code{cvs status} to determine 5890the keyword substitution method for a working copy.) 5891 5892However, in using @code{cvs admin -k} to change the 5893keyword expansion, be aware that the keyword expansion 5894mode is not version controlled. This means that, for 5895example, that if you have a text file in old releases, 5896and a binary file with the same name in new releases, 5897@sc{cvs} provides no way to check out the file in text 5898or binary mode depending on what version you are 5899checking out. There is no good workaround for this 5900problem. 5901 5902You can also set a default for whether @code{cvs add} 5903and @code{cvs import} treat a file as binary based on 5904its name; for example you could say that files who 5905names end in @samp{.exe} are binary. @xref{Wrappers}. 5906There is currently no way to have @sc{cvs} detect 5907whether a file is binary based on its contents. The 5908main difficulty with designing such a feature is that 5909it is not clear how to distinguish between binary and 5910non-binary files, and the rules to apply would vary 5911considerably with the operating system. 5912@c For example, it would be good on MS-DOS-family OSes 5913@c for anything containing ^Z to be binary. Having 5914@c characters with the 8th bit set imply binary is almost 5915@c surely a bad idea in the context of ISO-8859-* and 5916@c other such character sets. On VMS or the Mac, we 5917@c could use the OS's file typing. This is a 5918@c commonly-desired feature, and something of this sort 5919@c may make sense. But there are a lot of pitfalls here. 5920@c 5921@c Another, probably better, way to tell is to read the 5922@c file in text mode, write it to a temp file in text 5923@c mode, and then do a binary mode compare of the two 5924@c files. If they differ, it is a binary file. This 5925@c might have problems on VMS (or some other system 5926@c with several different text modes), but in general 5927@c should be relatively portable. The only other 5928@c downside I can think of is that it would be fairly 5929@c slow, but that is perhaps a small price to pay for 5930@c not having your files corrupted. Another issue is 5931@c what happens if you import a text file with bare 5932@c linefeeds on Windows. Such files will show up on 5933@c Windows sometimes (I think some native windows 5934@c programs even write them, on occasion). Perhaps it 5935@c is reasonable to treat such files as binary; after 5936@c all it is something of a presumption to assume that 5937@c the user would want the linefeeds converted to CRLF. 5938 5939@c --------------------------------------------------------------------- 5940@node Multiple developers 5941@chapter Multiple developers 5942@cindex Multiple developers 5943@cindex Team of developers 5944@cindex File locking 5945@cindex Locking files 5946@cindex Working copy 5947@cindex Reserved checkouts 5948@cindex Unreserved checkouts 5949@cindex RCS-style locking 5950 5951When more than one person works on a software project 5952things often get complicated. Often, two people try to 5953edit the same file simultaneously. One solution, known 5954as @dfn{file locking} or @dfn{reserved checkouts}, is 5955to allow only one person to edit each file at a time. 5956This is the only solution with some version control 5957systems, including @sc{rcs} and @sc{sccs}. Currently 5958the usual way to get reserved checkouts with @sc{cvs} 5959is the @code{cvs admin -l} command (@pxref{admin 5960options}). This is not as nicely integrated into 5961@sc{cvs} as the watch features, described below, but it 5962seems that most people with a need for reserved 5963checkouts find it adequate. 5964@c Or "find it better than worrying about implementing 5965@c nicely integrated reserved checkouts" or ...? 5966 5967As of @sc{cvs} version 1.12.10, another technique for getting most of the 5968effect of reserved checkouts is to enable advisory locks. To enable advisory 5969locks, have all developers put "edit -c", "commit -c" in their 5970.cvsrc file, and turn on watches in the repository. This 5971prevents them from doing a @code{cvs edit} if anyone is 5972already editting the file. It also may 5973be possible to use plain watches together with suitable 5974procedures (not enforced by software), to avoid having 5975two people edit at the same time. 5976 5977@c Our unreserved checkout model might not 5978@c be quite the same as others. For example, I 5979@c think that some systems will tend to create a branch 5980@c in the case where CVS prints "up-to-date check failed". 5981@c It isn't clear to me whether we should try to 5982@c explore these subtleties; it could easily just 5983@c confuse people. 5984The default model with @sc{cvs} is known as 5985@dfn{unreserved checkouts}. In this model, developers 5986can edit their own @dfn{working copy} of a file 5987simultaneously. The first person that commits his 5988changes has no automatic way of knowing that another 5989has started to edit it. Others will get an error 5990message when they try to commit the file. They must 5991then use @sc{cvs} commands to bring their working copy 5992up to date with the repository revision. This process 5993is almost automatic. 5994 5995@c FIXME? should probably use the word "watch" here, to 5996@c tie this into the text below and above. 5997@sc{cvs} also supports mechanisms which facilitate 5998various kinds of communication, without actually 5999enforcing rules like reserved checkouts do. 6000 6001The rest of this chapter describes how these various 6002models work, and some of the issues involved in 6003choosing between them. 6004 6005@ignore 6006Here is a draft reserved checkout design or discussion 6007of the issues. This seems like as good a place as any 6008for this. 6009 6010Might want a cvs lock/cvs unlock--in which the names 6011differ from edit/unedit because the network must be up 6012for these to work. unedit gives an error if there is a 6013reserved checkout in place (so that people don't 6014accidentally leave locks around); unlock gives an error 6015if one is not in place (this is more arguable; perhaps 6016it should act like unedit in that case). 6017 6018On the other hand, might want it so that emacs, 6019scripts, etc., can get ready to edit a file without 6020having to know which model is in use. In that case we 6021would have a "cvs watch lock" (or .cvsrc?) (that is, 6022three settings, "on", "off", and "lock"). Having cvs 6023watch lock set would cause a get to record in the CVS 6024directory which model is in use, and cause "cvs edit" 6025to change behaviors. We'd want a way to query which 6026setting is in effect (this would be handy even if it is 6027only "on" or "off" as presently). If lock is in 6028effect, then commit would require a lock before 6029allowing a checkin; chmod wouldn't suffice (might be 6030debatable--see chmod comment below, in watches--but it 6031is the way people expect RCS to work and I can't think 6032of any significant downside. On the other hand, maybe 6033it isn't worth bothering, because people who are used 6034to RCS wouldn't think to use chmod anyway). 6035 6036Implementation: use file attributes or use RCS 6037locking. The former avoids more dependence on RCS 6038behaviors we will need to re-implement as we librarify 6039RCS, and makes it easier to import/export RCS files (in 6040that context, want to ignore the locker field). But 6041note that RCS locks are per-branch, which is the 6042correct behavior (this is also an issue for the "watch 6043on" features; they should be per-branch too). 6044 6045Here are a few more random notes about implementation 6046details, assuming "cvs watch lock" and 6047 6048CVS/Watched file? Or try to fit this into CVS/Entries somehow? 6049Cases: (1) file is checked out (unreserved or with watch on) by old 6050version of @sc{cvs}, now we do something with new one, (2) file is checked 6051out by new version, now we do something with old one. 6052 6053Remote protocol would have a "Watched" analogous to "Mode". Of course 6054it would apply to all Updated-like requests. How do we keep this 6055setting up to date? I guess that there wants to be a Watched request, 6056and the server would send a new one if it isn't up to date? (Ugh--hard 6057to implement and slows down "cvs -q update"--is there an easier way?) 6058 6059"cvs edit"--checks CVS/Watched, and if watch lock, then sends 6060"edit-lock" request. Which comes back with a Checked-in with 6061appropriate Watched (off, on, lock, locked, or some such?), or error 6062message if already locked. 6063 6064"cvs commit"--only will commit if off/on/locked. lock is not OK. 6065 6066Doc: 6067note that "cvs edit" must be connected to network if watch lock is in 6068effect. 6069 6070Talk about what to do if someone has locked a file and you want to 6071edit that file. (breaking locks, or lack thereof). 6072 6073 6074One other idea (which could work along with the 6075existing "cvs admin -l" reserved checkouts, as well as 6076the above): 6077 6078"cvs editors" could show who has the file locked, if 6079someone does. 6080 6081@end ignore 6082 6083@menu 6084* File status:: A file can be in several states 6085* Updating a file:: Bringing a file up-to-date 6086* Conflicts example:: An informative example 6087* Informing others:: To cooperate you must inform 6088* Concurrency:: Simultaneous repository access 6089* Watches:: Mechanisms to track who is editing files 6090* Choosing a model:: Reserved or unreserved checkouts? 6091@end menu 6092 6093@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6094@node File status 6095@section File status 6096@cindex File status 6097@cindex Status of a file 6098 6099@c Shouldn't this start with an example or something, 6100@c introducing the unreserved checkout model? Before we 6101@c dive into listing states? 6102Based on what operations you have performed on a 6103checked out file, and what operations others have 6104performed to that file in the repository, one can 6105classify a file in a number of states. The states, as 6106reported by the @code{status} command, are: 6107 6108@c The order of items is chosen to group logically 6109@c similar outputs together. 6110@c People who want alphabetical can use the index... 6111@table @asis 6112@cindex Up-to-date 6113@item Up-to-date 6114The file is identical with the latest revision in the 6115repository for the branch in use. 6116@c FIXME: should we clarify "in use"? The answer is 6117@c sticky tags, and trying to distinguish branch sticky 6118@c tags from non-branch sticky tags seems rather awkward 6119@c here. 6120@c FIXME: What happens with non-branch sticky tags? Is 6121@c a stuck file "Up-to-date" or "Needs checkout" or what? 6122 6123@item Locally Modified 6124@cindex Locally Modified 6125You have edited the file, and not yet committed your changes. 6126 6127@item Locally Added 6128@cindex Locally Added 6129You have added the file with @code{add}, and not yet 6130committed your changes. 6131@c There are many cases involving the file being 6132@c added/removed/modified in the working directory, and 6133@c added/removed/modified in the repository, which we 6134@c don't try to describe here. I'm not sure that "cvs 6135@c status" produces a non-confusing output in most of 6136@c those cases. 6137 6138@item Locally Removed 6139@cindex Locally Removed 6140You have removed the file with @code{remove}, and not yet 6141committed your changes. 6142 6143@item Needs Checkout 6144@cindex Needs Checkout 6145Someone else has committed a newer revision to the 6146repository. The name is slightly misleading; you will 6147ordinarily use @code{update} rather than 6148@code{checkout} to get that newer revision. 6149 6150@item Needs Patch 6151@cindex Needs Patch 6152@c See also newb-123j0 in sanity.sh (although that case 6153@c should probably be changed rather than documented). 6154Like Needs Checkout, but the @sc{cvs} server will send 6155a patch rather than the entire file. Sending a patch or 6156sending an entire file accomplishes the same thing. 6157 6158@item Needs Merge 6159@cindex Needs Merge 6160Someone else has committed a newer revision to the repository, and you 6161have also made modifications to the file. 6162 6163@item Unresolved Conflict 6164@cindex Unresolved Conflict 6165@c FIXCVS - This file status needs to be changed to some more informative 6166@c text that distinguishes it more clearly from each of the Locally Added, 6167@c File had conflicts on merge, and Unknown status types, but an exact and 6168@c succinct wording escapes me at the moment. 6169A file with the same name as this new file has been added to the repository 6170from a second workspace. This file will need to be moved out of the way 6171to allow an @code{update} to complete. 6172 6173@item File had conflicts on merge 6174@cindex File had conflicts on merge 6175@c is it worth saying that this message was "Unresolved 6176@c Conflict" in CVS 1.9 and earlier? I'm inclined to 6177@c think that is unnecessarily confusing to new users. 6178This is like Locally Modified, except that a previous 6179@code{update} command gave a conflict. If you have not 6180already done so, you need to 6181resolve the conflict as described in @ref{Conflicts example}. 6182 6183@item Unknown 6184@cindex Unknown 6185@sc{cvs} doesn't know anything about this file. For 6186example, you have created a new file and have not run 6187@code{add}. 6188@c 6189@c "Entry Invalid" and "Classify Error" are also in the 6190@c status.c. The latter definitely indicates a CVS bug 6191@c (should it be worded more like "internal error" so 6192@c people submit bug reports if they see it?). The former 6193@c I'm not as sure; I haven't tracked down whether/when it 6194@c appears in "cvs status" output. 6195 6196@end table 6197 6198To help clarify the file status, @code{status} also 6199reports the @code{Working revision} which is the 6200revision that the file in the working directory derives 6201from, and the @code{Repository revision} which is the 6202latest revision in the repository for the branch in 6203use. 6204The @samp{Commit Identifier} reflects the unique commitid 6205of the @code{commit}. 6206@c FIXME: should we clarify "in use"? The answer is 6207@c sticky tags, and trying to distinguish branch sticky 6208@c tags from non-branch sticky tags seems rather awkward 6209@c here. 6210@c FIXME: What happens with non-branch sticky tags? 6211@c What is the Repository Revision there? See the 6212@c comment at vn_rcs in cvs.h, which is kind of 6213@c confused--we really need to document better what this 6214@c field contains. 6215@c Q: Should we document "New file!" and other such 6216@c outputs or are they self-explanatory? 6217@c FIXME: what about the date to the right of "Working 6218@c revision"? It doesn't appear with client/server and 6219@c seems unnecessary (redundant with "ls -l") so 6220@c perhaps it should be removed for non-client/server too? 6221@c FIXME: Need some examples. 6222@c FIXME: Working revision can also be something like 6223@c "-1.3" for a locally removed file. Not at all 6224@c self-explanatory (and it is possible that CVS should 6225@c be changed rather than documenting this). 6226 6227@c Would be nice to have an @example showing output 6228@c from cvs status, with comments showing the xref 6229@c where each part of the output is described. This 6230@c might fit in nicely if it is desirable to split this 6231@c node in two; one to introduce "cvs status" and one 6232@c to list each of the states. 6233The options to @code{status} are listed in 6234@ref{Invoking CVS}. For information on its @code{Sticky tag} 6235and @code{Sticky date} output, see @ref{Sticky tags}. 6236For information on its @code{Sticky options} output, 6237see the @samp{-k} option in @ref{update options}. 6238 6239You can think of the @code{status} and @code{update} 6240commands as somewhat complementary. You use 6241@code{update} to bring your files up to date, and you 6242can use @code{status} to give you some idea of what an 6243@code{update} would do (of course, the state of the 6244repository might change before you actually run 6245@code{update}). In fact, if you want a command to 6246display file status in a more brief format than is 6247displayed by the @code{status} command, you can invoke 6248 6249@cindex update, to display file status 6250@example 6251$ cvs -n -q update 6252@end example 6253 6254The @samp{-n} option means to not actually do the 6255update, but merely to display statuses; the @samp{-q} 6256option avoids printing the name of each directory. For 6257more information on the @code{update} command, and 6258these options, see @ref{Invoking CVS}. 6259 6260@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6261@node Updating a file 6262@section Bringing a file up to date 6263@cindex Bringing a file up to date 6264@cindex Updating a file 6265@cindex Merging a file 6266@cindex Update, introduction 6267 6268When you want to update or merge a file, use the @code{cvs update -d} 6269command. For files that are not up to date this is roughly equivalent 6270to a @code{checkout} command: the newest revision of the file is 6271extracted from the repository and put in your working directory. The 6272@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} 6273that you wish it to create directories added by other developers. 6274 6275Your modifications to a file are never lost when you 6276use @code{update}. If no newer revision exists, 6277running @code{update} has no effect. If you have 6278edited the file, and a newer revision is available, 6279@sc{cvs} will merge all changes into your working copy. 6280 6281For instance, imagine that you checked out revision 1.4 and started 6282editing it. In the meantime someone else committed revision 1.5, and 6283shortly after that revision 1.6. If you run @code{update} on the file 6284now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 6285your file. 6286 6287@cindex Overlap 6288If any of the changes between 1.4 and 1.6 were made too 6289close to any of the changes you have made, an 6290@dfn{overlap} occurs. In such cases a warning is 6291printed, and the resulting file includes both 6292versions of the lines that overlap, delimited by 6293special markers. 6294@xref{update}, for a complete description of the 6295@code{update} command. 6296 6297@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6298@node Conflicts example 6299@section Conflicts example 6300@cindex Merge, an example 6301@cindex Example of merge 6302@cindex driver.c (merge example) 6303 6304Suppose revision 1.4 of @file{driver.c} contains this: 6305 6306@example 6307#include <stdio.h> 6308 6309void main() 6310@{ 6311 parse(); 6312 if (nerr == 0) 6313 gencode(); 6314 else 6315 fprintf(stderr, "No code generated.\n"); 6316 exit(nerr == 0 ? 0 : 1); 6317@} 6318@end example 6319 6320@noindent 6321Revision 1.6 of @file{driver.c} contains this: 6322 6323@example 6324#include <stdio.h> 6325 6326int main(int argc, 6327 char **argv) 6328@{ 6329 parse(); 6330 if (argc != 1) 6331 @{ 6332 fprintf(stderr, "tc: No args expected.\n"); 6333 exit(1); 6334 @} 6335 if (nerr == 0) 6336 gencode(); 6337 else 6338 fprintf(stderr, "No code generated.\n"); 6339 exit(!!nerr); 6340@} 6341@end example 6342 6343@noindent 6344Your working copy of @file{driver.c}, based on revision 63451.4, contains this before you run @samp{cvs update}: 6346@c -- Really include "cvs"? 6347 6348@example 6349#include <stdlib.h> 6350#include <stdio.h> 6351 6352void main() 6353@{ 6354 init_scanner(); 6355 parse(); 6356 if (nerr == 0) 6357 gencode(); 6358 else 6359 fprintf(stderr, "No code generated.\n"); 6360 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6361@} 6362@end example 6363 6364@noindent 6365You run @samp{cvs update}: 6366@c -- Really include "cvs"? 6367 6368@example 6369$ cvs update driver.c 6370RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 6371retrieving revision 1.4 6372retrieving revision 1.6 6373Merging differences between 1.4 and 1.6 into driver.c 6374rcsmerge warning: overlaps during merge 6375cvs update: conflicts found in driver.c 6376C driver.c 6377@end example 6378 6379@noindent 6380@cindex Conflicts (merge example) 6381@sc{cvs} tells you that there were some conflicts. 6382Your original working file is saved unmodified in 6383@file{.#driver.c.1.4}. The new version of 6384@file{driver.c} contains this: 6385 6386@example 6387#include <stdlib.h> 6388#include <stdio.h> 6389 6390int main(int argc, 6391 char **argv) 6392@{ 6393 init_scanner(); 6394 parse(); 6395 if (argc != 1) 6396 @{ 6397 fprintf(stderr, "tc: No args expected.\n"); 6398 exit(1); 6399 @} 6400 if (nerr == 0) 6401 gencode(); 6402 else 6403 fprintf(stderr, "No code generated.\n"); 6404@asis{}<<<<<<< driver.c 6405 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6406@asis{}======= 6407 exit(!!nerr); 6408@asis{}>>>>>>> 1.6 6409@} 6410@end example 6411 6412@noindent 6413@cindex Markers, conflict 6414@cindex Conflict markers 6415@cindex <<<<<<< 6416@cindex >>>>>>> 6417@cindex ======= 6418 6419Note how all non-overlapping modifications are incorporated in your working 6420copy, and that the overlapping section is clearly marked with 6421@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 6422 6423@cindex Resolving a conflict 6424@cindex Conflict resolution 6425You resolve the conflict by editing the file, removing the markers and 6426the erroneous line. Suppose you end up with this file: 6427@c -- Add xref to the pcl-cvs manual when it talks 6428@c -- about this. 6429@example 6430#include <stdlib.h> 6431#include <stdio.h> 6432 6433int main(int argc, 6434 char **argv) 6435@{ 6436 init_scanner(); 6437 parse(); 6438 if (argc != 1) 6439 @{ 6440 fprintf(stderr, "tc: No args expected.\n"); 6441 exit(1); 6442 @} 6443 if (nerr == 0) 6444 gencode(); 6445 else 6446 fprintf(stderr, "No code generated.\n"); 6447 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6448@} 6449@end example 6450 6451@noindent 6452You can now go ahead and commit this as revision 1.7. 6453 6454@example 6455$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 6456Checking in driver.c; 6457/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 6458new revision: 1.7; previous revision: 1.6 6459done 6460@end example 6461 6462For your protection, @sc{cvs} will refuse to check in a 6463file if a conflict occurred and you have not resolved 6464the conflict. Currently to resolve a conflict, you 6465must change the timestamp on the file. In previous 6466versions of @sc{cvs}, you also needed to 6467insure that the file contains no conflict markers. 6468Because 6469your file may legitimately contain conflict markers (that 6470is, occurrences of @samp{>>>>>>> } at the start of a 6471line that don't mark a conflict), the current 6472version of @sc{cvs} will print a warning and proceed to 6473check in the file. 6474@c The old behavior was really icky; the only way out 6475@c was to start hacking on 6476@c the @code{CVS/Entries} file or other such workarounds. 6477@c 6478@c If the timestamp thing isn't considered nice enough, 6479@c maybe there should be a "cvs resolved" command 6480@c which clears the conflict indication. For a nice user 6481@c interface, this should be invoked by an interactive 6482@c merge tool like emerge rather than by the user 6483@c directly--such a tool can verify that the user has 6484@c really dealt with each conflict. 6485 6486@cindex emerge 6487If you use release 1.04 or later of pcl-cvs (a @sc{gnu} 6488Emacs front-end for @sc{cvs}) you can use an Emacs 6489package called emerge to help you resolve conflicts. 6490See the documentation for pcl-cvs. 6491 6492@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6493@node Informing others 6494@section Informing others about commits 6495@cindex Informing others 6496@cindex Spreading information 6497@cindex Mail, automatic mail on commit 6498 6499It is often useful to inform others when you commit a 6500new revision of a file. The @samp{-i} option of the 6501@file{modules} file, or the @file{loginfo} file, can be 6502used to automate this process. @xref{modules}. 6503@xref{loginfo}. You can use these features of @sc{cvs} 6504to, for instance, instruct @sc{cvs} to mail a 6505message to all developers, or post a message to a local 6506newsgroup. 6507@c -- More text would be nice here. 6508 6509@node Concurrency 6510@section Several developers simultaneously attempting to run CVS 6511 6512@cindex Locks, cvs, introduction 6513@c For a discussion of *why* CVS creates locks, see 6514@c the comment at the start of src/lock.c 6515If several developers try to run @sc{cvs} at the same 6516time, one may get the following message: 6517 6518@example 6519[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 6520@end example 6521 6522@cindex #cvs.rfl, removing 6523@cindex #cvs.wfl, removing 6524@cindex #cvs.lock, removing 6525@sc{cvs} will try again every 30 seconds, and either 6526continue with the operation or print the message again, 6527if it still needs to wait. If a lock seems to stick 6528around for an undue amount of time, find the person 6529holding the lock and ask them about the cvs command 6530they are running. If they aren't running a cvs 6531command, look in the repository directory mentioned in 6532the message and remove files which they own whose names 6533start with @file{#cvs.rfl}, 6534@file{#cvs.wfl}, or @file{#cvs.lock}. 6535 6536Note that these locks are to protect @sc{cvs}'s 6537internal data structures and have no relationship to 6538the word @dfn{lock} in the sense used by 6539@sc{rcs}---which refers to reserved checkouts 6540(@pxref{Multiple developers}). 6541 6542Any number of people can be reading from a given 6543repository at a time; only when someone is writing do 6544the locks prevent other people from reading or writing. 6545 6546@cindex Atomic transactions, lack of 6547@cindex Transactions, atomic, lack of 6548@c the following talks about what one might call commit/update 6549@c atomicity. 6550@c Probably also should say something about 6551@c commit/commit atomicity, that is, "An update will 6552@c not get partial versions of more than one commit". 6553@c CVS currently has this property and I guess we can 6554@c make it a documented feature. 6555@c For example one person commits 6556@c a/one.c and b/four.c and another commits a/two.c and 6557@c b/three.c. Then an update cannot get the new a/one.c 6558@c and a/two.c and the old b/four.c and b/three.c. 6559One might hope for the following property: 6560 6561@quotation 6562If someone commits some changes in one cvs command, 6563then an update by someone else will either get all the 6564changes, or none of them. 6565@end quotation 6566 6567@noindent 6568but @sc{cvs} does @emph{not} have this property. For 6569example, given the files 6570 6571@example 6572a/one.c 6573a/two.c 6574b/three.c 6575b/four.c 6576@end example 6577 6578@noindent 6579if someone runs 6580 6581@example 6582cvs ci a/two.c b/three.c 6583@end example 6584 6585@noindent 6586and someone else runs @code{cvs update} at the same 6587time, the person running @code{update} might get only 6588the change to @file{b/three.c} and not the change to 6589@file{a/two.c}. 6590 6591@node Watches 6592@section Mechanisms to track who is editing files 6593@cindex Watches 6594 6595For many groups, use of @sc{cvs} in its default mode is 6596perfectly satisfactory. Users may sometimes go to 6597check in a modification only to find that another 6598modification has intervened, but they deal with it and 6599proceed with their check in. Other groups prefer to be 6600able to know who is editing what files, so that if two 6601people try to edit the same file they can choose to 6602talk about who is doing what when rather than be 6603surprised at check in time. The features in this 6604section allow such coordination, while retaining the 6605ability of two developers to edit the same file at the 6606same time. 6607 6608@c Some people might ask why CVS does not enforce the 6609@c rule on chmod, by requiring a cvs edit before a cvs 6610@c commit. The main reason is that it could always be 6611@c circumvented--one could edit the file, and 6612@c then when ready to check it in, do the cvs edit and put 6613@c in the new contents and do the cvs commit. One 6614@c implementation note: if we _do_ want to have cvs commit 6615@c require a cvs edit, we should store the state on 6616@c whether the cvs edit has occurred in the working 6617@c directory, rather than having the server try to keep 6618@c track of what working directories exist. 6619@c FIXME: should the above discussion be part of the 6620@c manual proper, somewhere, not just in a comment? 6621For maximum benefit developers should use @code{cvs 6622edit} (not @code{chmod}) to make files read-write to 6623edit them, and @code{cvs release} (not @code{rm}) to 6624discard a working directory which is no longer in use, 6625but @sc{cvs} is not able to enforce this behavior. 6626 6627If a development team wants stronger enforcement of 6628watches and all team members are using a @sc{cvs} client version 1.12.10 or 6629greater to access a @sc{cvs} server version 1.12.10 or greater, they can 6630enable advisory locks. To enable advisory locks, have all developers 6631put "edit -c" and "commit -c" into all .cvsrc files, 6632and make files default to read only by turning on watches 6633or putting "cvs -r" into all .cvsrc files. 6634This prevents multiple people from editting a file at 6635the same time (unless explicitly overriden with @samp{-f}). 6636 6637@c I'm a little dissatisfied with this presentation, 6638@c because "watch on"/"edit"/"editors" are one set of 6639@c functionality, and "watch add"/"watchers" is another 6640@c which is somewhat orthogonal even though they interact in 6641@c various ways. But I think it might be 6642@c confusing to describe them separately (e.g. "watch 6643@c add" with loginfo). I don't know. 6644 6645@menu 6646* Setting a watch:: Telling CVS to watch certain files 6647* Getting Notified:: Telling CVS to notify you 6648* Editing files:: How to edit a file which is being watched 6649* Watch information:: Information about who is watching and editing 6650* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 6651@end menu 6652 6653@node Setting a watch 6654@subsection Telling CVS to watch certain files 6655 6656To enable the watch features, you first specify that 6657certain files are to be watched. 6658 6659@cindex watch on (subcommand) 6660@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 6661 6662@cindex Read-only files, and watches 6663Specify that developers should run @code{cvs edit} 6664before editing @var{files}. @sc{cvs} will create working 6665copies of @var{files} read-only, to remind developers 6666to run the @code{cvs edit} command before working on 6667them. 6668 6669If @var{files} includes the name of a directory, @sc{cvs} 6670arranges to watch all files added to the corresponding 6671repository directory, and sets a default for files 6672added in the future; this allows the user to set 6673notification policies on a per-directory basis. The 6674contents of the directory are processed recursively, 6675unless the @code{-l} option is given. 6676The @code{-R} option can be used to force recursion if the @code{-l} 6677option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 6678 6679If @var{files} is omitted, it defaults to the current directory. 6680 6681@cindex watch off (subcommand) 6682@end deffn 6683 6684@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 6685 6686Do not create @var{files} read-only on checkout; thus, 6687developers will not be reminded to use @code{cvs edit} 6688and @code{cvs unedit}. 6689@ignore 6690@sc{cvs} will check out @var{files} 6691read-write as usual, unless other permissions override 6692due to the @code{PreservePermissions} option being 6693enabled in the @file{config} administrative file 6694(@pxref{Special Files}, @pxref{config}) 6695@end ignore 6696 6697The @var{files} and options are processed as for @code{cvs 6698watch on}. 6699 6700@end deffn 6701 6702@node Getting Notified 6703@subsection Telling CVS to notify you 6704 6705You can tell @sc{cvs} that you want to receive 6706notifications about various actions taken on a file. 6707You can do this without using @code{cvs watch on} for 6708the file, but generally you will want to use @code{cvs 6709watch on}, to remind developers to use the @code{cvs edit} 6710command. 6711 6712@cindex watch add (subcommand) 6713@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6714 6715Add the current user to the list of people to receive notification of 6716work done on @var{files}. 6717 6718The @code{-a} option specifies what kinds of events @sc{cvs} should notify 6719the user about. @var{action} is one of the following: 6720 6721@table @code 6722 6723@item edit 6724Another user has applied the @code{cvs edit} command (described 6725below) to a watched file. 6726 6727@item commit 6728Another user has committed changes to one of the named @var{files}. 6729 6730@item unedit 6731Another user has abandoned editing a file (other than by committing changes). 6732They can do this in several ways, by: 6733 6734@itemize @bullet 6735 6736@item 6737applying the @code{cvs unedit} command (described below) to the file 6738 6739@item 6740applying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6741(or recursively to a directory more than one level up) 6742 6743@item 6744deleting the file and allowing @code{cvs update} to recreate it 6745 6746@end itemize 6747 6748@item all 6749All of the above. 6750 6751@item none 6752None of the above. (This is useful with @code{cvs edit}, 6753described below.) 6754 6755@end table 6756 6757The @code{-a} option may appear more than once, or not at all. If 6758omitted, the action defaults to @code{all}. 6759 6760The @var{files} and options are processed as for 6761@code{cvs watch on}. 6762 6763@end deffn 6764 6765 6766@cindex watch remove (subcommand) 6767@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6768 6769Remove a notification request established using @code{cvs watch add}; 6770the arguments are the same. If the @code{-a} option is present, only 6771watches for the specified actions are removed. 6772 6773@end deffn 6774 6775@cindex notify (admin file) 6776When the conditions exist for notification, @sc{cvs} 6777calls the @file{notify} administrative file. Edit 6778@file{notify} as one edits the other administrative 6779files (@pxref{Intro administrative files}). This 6780file follows the usual conventions for administrative 6781files (@pxref{syntax}), where each line is a regular 6782expression followed by a command to execute. The 6783command should contain a single occurrence of @samp{%s} 6784which will be replaced by the user to notify; the rest 6785of the information regarding the notification will be 6786supplied to the command on standard input. The 6787standard thing to put in the @code{notify} file is the 6788single line: 6789 6790@example 6791ALL mail %s -s "CVS notification" 6792@end example 6793 6794@noindent 6795This causes users to be notified by electronic mail. 6796@c FIXME: should it be this hard to set up this 6797@c behavior (and the result when one fails to do so, 6798@c silent failure to notify, so non-obvious)? Should 6799@c CVS give a warning if no line in notify matches (and 6800@c document the use of "DEFAULT :" for the case where 6801@c skipping the notification is indeed desired)? 6802 6803@cindex users (admin file) 6804Note that if you set this up in the straightforward 6805way, users receive notifications on the server machine. 6806One could of course write a @file{notify} script which 6807directed notifications elsewhere, but to make this 6808easy, @sc{cvs} allows you to associate a notification 6809address for each user. To do so create a file 6810@file{users} in @file{CVSROOT} with a line for each 6811user in the format @var{user}:@var{value}. Then 6812instead of passing the name of the user to be notified 6813to @file{notify}, @sc{cvs} will pass the @var{value} 6814(normally an email address on some other machine). 6815 6816@sc{cvs} does not notify you for your own changes. 6817Currently this check is done based on whether the user 6818name of the person taking the action which triggers 6819notification matches the user name of the person 6820getting notification. In fact, in general, the watches 6821features only track one edit by each user. It probably 6822would be more useful if watches tracked each working 6823directory separately, so this behavior might be worth 6824changing. 6825@c "behavior might be worth changing" is an effort to 6826@c point to future directions while also not promising 6827@c that "they" (as in "why don't they fix CVS to....") 6828@c will do this. 6829@c one implementation issue is identifying whether a 6830@c working directory is same or different. Comparing 6831@c pathnames/hostnames is hopeless, but having the server 6832@c supply a serial number which the client stores in the 6833@c CVS directory as a magic cookie should work. 6834 6835@node Editing files 6836@subsection How to edit a file which is being watched 6837 6838@cindex Checkout, as term for getting ready to edit 6839Since a file which is being watched is checked out 6840read-only, you cannot simply edit it. To make it 6841read-write, and inform others that you are planning to 6842edit it, use the @code{cvs edit} command. Some systems 6843call this a @dfn{checkout}, but @sc{cvs} uses that term 6844for obtaining a copy of the sources (@pxref{Getting the 6845source}), an operation which those systems call a 6846@dfn{get} or a @dfn{fetch}. 6847@c Issue to think about: should we transition CVS 6848@c towards the "get" terminology? "cvs get" is already a 6849@c synonym for "cvs checkout" and that section of the 6850@c manual refers to "Getting the source". If this is 6851@c done, needs to be done gingerly (for example, we should 6852@c still accept "checkout" in .cvsrc files indefinitely 6853@c even if the CVS's messages are changed from "cvs checkout: " 6854@c to "cvs get: "). 6855@c There is a concern about whether "get" is not as 6856@c good for novices because it is a more general term 6857@c than "checkout" (and thus arguably harder to assign 6858@c a technical meaning for). 6859 6860@cindex edit (subcommand) 6861@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6862 6863Prepare to edit the working files @var{files}. @sc{cvs} makes the 6864@var{files} read-write, and notifies users who have requested 6865@code{edit} notification for any of @var{files}. 6866 6867The @code{cvs edit} command accepts the same options as the 6868@code{cvs watch add} command, and establishes a temporary watch for the 6869user on @var{files}; @sc{cvs} will remove the watch when @var{files} are 6870@code{unedit}ed or @code{commit}ted. If the user does not wish to 6871receive notifications, she should specify @code{-a none}. 6872 6873The @var{files} and the options are processed as for the @code{cvs 6874watch} commands. 6875 6876There are two additional options that @code{cvs edit} understands as of 6877@sc{cvs} client and server versions 1.12.10 but @code{cvs watch} does not. 6878The first is @code{-c}, which causes @code{cvs edit} to fail if anyone else 6879is editting the file. This is probably only useful when @samp{edit -c} and 6880@samp{commit -c} are specified in all developers' @file{.cvsrc} files. This 6881behavior may be overriden this via the @code{-f} option, which overrides 6882@code{-c} and allows multiple edits to succeed. 6883 6884@ignore 6885@strong{Caution: If the @code{PreservePermissions} 6886option is enabled in the repository (@pxref{config}), 6887@sc{cvs} will not change the permissions on any of the 6888@var{files}. The reason for this change is to ensure 6889that using @samp{cvs edit} does not interfere with the 6890ability to store file permissions in the @sc{cvs} 6891repository.} 6892@end ignore 6893 6894@end deffn 6895 6896Normally when you are done with a set of changes, you 6897use the @code{cvs commit} command, which checks in your 6898changes and returns the watched files to their usual 6899read-only state. But if you instead decide to abandon 6900your changes, or not to make any changes, you can use 6901the @code{cvs unedit} command. 6902 6903@cindex unedit (subcommand) 6904@cindex Abandoning work 6905@cindex Reverting to repository version 6906@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 6907 6908Abandon work on the working files @var{files}, and revert them to the 6909repository versions on which they are based. @sc{cvs} makes those 6910@var{files} read-only for which users have requested notification using 6911@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 6912notification for any of @var{files}. 6913 6914The @var{files} and options are processed as for the 6915@code{cvs watch} commands. 6916 6917If watches are not in use, the @code{unedit} command 6918probably does not work, and the way to revert to the 6919repository version is with the command @code{cvs update -C file} 6920(@pxref{update}). 6921The meaning is 6922not precisely the same; the latter may also 6923bring in some changes which have been made in the 6924repository since the last time you updated. 6925@c It would be a useful enhancement to CVS to make 6926@c unedit work in the non-watch case as well. 6927@end deffn 6928 6929When using client/server @sc{cvs}, you can use the 6930@code{cvs edit} and @code{cvs unedit} commands even if 6931@sc{cvs} is unable to successfully communicate with the 6932server; the notifications will be sent upon the next 6933successful @sc{cvs} command. 6934 6935@node Watch information 6936@subsection Information about who is watching and editing 6937 6938@cindex watchers (subcommand) 6939@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 6940 6941List the users currently watching changes to @var{files}. The report 6942includes the files being watched, and the mail address of each watcher. 6943 6944The @var{files} and options are processed as for the 6945@code{cvs watch} commands. 6946 6947@end deffn 6948 6949 6950@cindex editors (subcommand) 6951@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 6952 6953List the users currently working on @var{files}. The report 6954includes the mail address of each user, the time when the user began 6955working with the file, and the host and path of the working directory 6956containing the file. 6957 6958The @var{files} and options are processed as for the 6959@code{cvs watch} commands. 6960 6961@end deffn 6962 6963@node Watches Compatibility 6964@subsection Using watches with old versions of CVS 6965 6966@cindex CVS 1.6, and watches 6967If you use the watch features on a repository, it 6968creates @file{CVS} directories in the repository and 6969stores the information about watches in that directory. 6970If you attempt to use @sc{cvs} 1.6 or earlier with the 6971repository, you get an error message such as the 6972following (all on one line): 6973 6974@example 6975cvs update: cannot open CVS/Entries for reading: 6976No such file or directory 6977@end example 6978 6979@noindent 6980and your operation will likely be aborted. To use the 6981watch features, you must upgrade all copies of @sc{cvs} 6982which use that repository in local or server mode. If 6983you cannot upgrade, use the @code{watch off} and 6984@code{watch remove} commands to remove all watches, and 6985that will restore the repository to a state which 6986@sc{cvs} 1.6 can cope with. 6987 6988@node Choosing a model 6989@section Choosing between reserved or unreserved checkouts 6990@cindex Choosing, reserved or unreserved checkouts 6991 6992Reserved and unreserved checkouts each have pros and 6993cons. Let it be said that a lot of this is a matter of 6994opinion or what works given different groups' working 6995styles, but here is a brief description of some of the 6996issues. There are many ways to organize a team of 6997developers. @sc{cvs} does not try to enforce a certain 6998organization. It is a tool that can be used in several 6999ways. 7000 7001Reserved checkouts can be very counter-productive. If 7002two persons want to edit different parts of a file, 7003there may be no reason to prevent either of them from 7004doing so. Also, it is common for someone to take out a 7005lock on a file, because they are planning to edit it, 7006but then forget to release the lock. 7007 7008@c "many groups"? specifics? cites to papers on this? 7009@c some way to weasel-word it a bit more so we don't 7010@c need facts :-)? 7011People, especially people who are familiar with 7012reserved checkouts, often wonder how often conflicts 7013occur if unreserved checkouts are used, and how 7014difficult they are to resolve. The experience with 7015many groups is that they occur rarely and usually are 7016relatively straightforward to resolve. 7017 7018The rarity of serious conflicts may be surprising, until one realizes 7019that they occur only when two developers disagree on the proper design 7020for a given section of code; such a disagreement suggests that the 7021team has not been communicating properly in the first place. In order 7022to collaborate under @emph{any} source management regimen, developers 7023must agree on the general design of the system; given this agreement, 7024overlapping changes are usually straightforward to merge. 7025 7026In some cases unreserved checkouts are clearly 7027inappropriate. If no merge tool exists for the kind of 7028file you are managing (for example word processor files 7029or files edited by Computer Aided Design programs), and 7030it is not desirable to change to a program which uses a 7031mergeable data format, then resolving conflicts is 7032going to be unpleasant enough that you generally will 7033be better off to simply avoid the conflicts instead, by 7034using reserved checkouts. 7035 7036The watches features described above in @ref{Watches} 7037can be considered to be an intermediate model between 7038reserved checkouts and unreserved checkouts. When you 7039go to edit a file, it is possible to find out who else 7040is editing it. And rather than having the system 7041simply forbid both people editing the file, it can tell 7042you what the situation is and let you figure out 7043whether it is a problem in that particular case or not. 7044Therefore, for some groups watches can be 7045considered the best of both the reserved checkout and unreserved 7046checkout worlds. 7047 7048As of @sc{cvs} client and server versions 1.12.10, you may also enable 7049advisory locks by putting @samp{edit -c} and @samp{commit -c} in all 7050developers' @file{.cvsrc} files. After this is done, @code{cvs edit} 7051will fail if there are any other editors, and @code{cvs commit} will 7052fail if the committer has not registered to edit the file via @code{cvs edit}. 7053This is most effective in conjunction with files checked out read-only by 7054default, which may be enabled by turning on watches in the repository or by 7055putting @samp{cvs -r} in all @file{.cvsrc} files. 7056 7057 7058@c --------------------------------------------------------------------- 7059@node Revision management 7060@chapter Revision management 7061@cindex Revision management 7062 7063@c -- This chapter could be expanded a lot. 7064@c -- Experiences are very welcome! 7065 7066If you have read this far, you probably have a pretty 7067good grasp on what @sc{cvs} can do for you. This 7068chapter talks a little about things that you still have 7069to decide. 7070 7071If you are doing development on your own using @sc{cvs} 7072you could probably skip this chapter. The questions 7073this chapter takes up become more important when more 7074than one person is working in a repository. 7075 7076@menu 7077* When to commit:: Some discussion on the subject 7078@end menu 7079 7080@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7081@node When to commit 7082@section When to commit? 7083@cindex When to commit 7084@cindex Committing, when to 7085@cindex Policy 7086 7087Your group should decide which policy to use regarding 7088commits. Several policies are possible, and as your 7089experience with @sc{cvs} grows you will probably find 7090out what works for you. 7091 7092If you commit files too quickly you might commit files 7093that do not even compile. If your partner updates his 7094working sources to include your buggy file, he will be 7095unable to compile the code. On the other hand, other 7096persons will not be able to benefit from the 7097improvements you make to the code if you commit very 7098seldom, and conflicts will probably be more common. 7099 7100It is common to only commit files after making sure 7101that they can be compiled. Some sites require that the 7102files pass a test suite. Policies like this can be 7103enforced using the commitinfo file 7104(@pxref{commitinfo}), but you should think twice before 7105you enforce such a convention. By making the 7106development environment too controlled it might become 7107too regimented and thus counter-productive to the real 7108goal, which is to get software written. 7109 7110@c --------------------------------------------------------------------- 7111@node Keyword substitution 7112@chapter Keyword substitution 7113@cindex Keyword substitution 7114@cindex Keyword expansion 7115@cindex Identifying files 7116 7117@comment Be careful when editing this chapter. 7118@comment Remember that this file is kept under 7119@comment version control, so we must not accidentally 7120@comment include a valid keyword in the running text. 7121 7122As long as you edit source files inside a working 7123directory you can always find out the state of 7124your files via @samp{cvs status} and @samp{cvs log}. 7125But as soon as you export the files from your 7126development environment it becomes harder to identify 7127which revisions they are. 7128 7129@sc{cvs} can use a mechanism known as @dfn{keyword 7130substitution} (or @dfn{keyword expansion}) to help 7131identifying the files. Embedded strings of the form 7132@code{$@var{keyword}$} and 7133@code{$@var{keyword}:@dots{}$} in a file are replaced 7134with strings of the form 7135@code{$@var{keyword}:@var{value}$} whenever you obtain 7136a new revision of the file. 7137 7138@menu 7139* Keyword list:: Keywords 7140* Using keywords:: Using keywords 7141* Avoiding substitution:: Avoiding substitution 7142* Substitution modes:: Substitution modes 7143* Configuring keyword expansion:: Configuring keyword expansion 7144* Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. 7145@end menu 7146 7147@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7148@node Keyword list 7149@section Keyword List 7150@cindex Keyword List 7151 7152@c FIXME: need some kind of example here I think, 7153@c perhaps in a 7154@c "Keyword intro" node. The intro in the "Keyword 7155@c substitution" node itself seems OK, but to launch 7156@c into a list of the keywords somehow seems too abrupt. 7157 7158This is a list of the keywords: 7159 7160@table @code 7161@cindex Author keyword 7162@item $@splitrcskeyword{Author}$ 7163The login name of the user who checked in the revision. 7164 7165@cindex CVSHeader keyword 7166@item $@splitrcskeyword{CVSHeader}$ 7167A standard header (similar to $@splitrcskeyword{Header}$, but with 7168the CVS root stripped off). It contains the relative 7169pathname of the @sc{rcs} file to the CVS root, the 7170revision number, the date (UTC), the author, the state, 7171and the locker (if locked). Files will normally never 7172be locked when you use @sc{cvs}. 7173 7174Note that this keyword has only been recently 7175introduced to @sc{cvs} and may cause problems with 7176existing installations if $@splitrcskeyword{CVSHeader}$ is already 7177in the files for a different purpose. This keyword may 7178be excluded using the @code{KeywordExpand=eCVSHeader} 7179in the @file{CVSROOT/config} file. 7180See @ref{Configuring keyword expansion} for more details. 7181 7182@cindex Date keyword 7183@item $@splitrcskeyword{Date}$ 7184The date and time (UTC) the revision was checked in. 7185 7186@cindex Header keyword 7187@item $@splitrcskeyword{Header}$ 7188A standard header containing the full pathname of the 7189@sc{rcs} file, the revision number, the date (UTC), the 7190author, the state, and the locker (if locked). Files 7191will normally never be locked when you use @sc{cvs}. 7192 7193@cindex Id keyword 7194@item $@splitrcskeyword{Id}$ 7195Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} 7196filename is without a path. 7197 7198@cindex Name keyword 7199@item $@splitrcskeyword{Name}$ 7200Tag name used to check out this file. The keyword is 7201expanded only if one checks out with an explicit tag 7202name. For example, when running the command @code{cvs 7203co -r first}, the keyword expands to @samp{Name: first}. 7204 7205@cindex Locker keyword 7206@item $@splitrcskeyword{Locker}$ 7207The login name of the user who locked the revision 7208(empty if not locked, which is the normal case unless 7209@code{cvs admin -l} is in use). 7210 7211@cindex Log keyword 7212@cindex MaxCommentLeaderLength 7213@cindex UseArchiveCommentLeader 7214@cindex Log keyword, configuring substitution behavior 7215@item $@splitrcskeyword{Log}$ 7216The log message supplied during commit, preceded by a 7217header containing the @sc{rcs} filename, the revision 7218number, the author, and the date (UTC). Existing log 7219messages are @emph{not} replaced. Instead, the new log 7220message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}. 7221By default, each new line is prefixed with the same string which 7222precedes the @code{$@splitrcskeyword{Log}$} keyword, unless it exceeds the 7223@code{MaxCommentLeaderLength} set in @file{CVSROOT/config}. 7224 7225For example, if the file contains: 7226 7227@example 7228 /* Here is what people have been up to: 7229 * 7230 * $@splitrcskeyword{Log}: frob.c,v $ 7231 * Revision 1.1 1997/01/03 14:23:51 joe 7232 * Add the superfrobnicate option 7233 * 7234 */ 7235@end example 7236 7237@noindent 7238then additional lines which are added when expanding 7239the @code{$@splitrcskeyword{Log}$} keyword will be preceded by @samp{ * }. 7240Unlike previous versions of @sc{cvs} and @sc{rcs}, the 7241@dfn{comment leader} from the @sc{rcs} file is not used. 7242The @code{$@splitrcskeyword{Log}$} keyword is useful for 7243accumulating a complete change log in a source file, 7244but for several reasons it can be problematic. 7245 7246If the prefix of the @code{$@splitrcskeyword{Log}$} keyword turns out to be 7247longer than @code{MaxCommentLeaderLength}, CVS will skip expansion of this 7248keyword unless @code{UseArchiveCommentLeader} is also set in 7249@file{CVSROOT/config} and a @samp{comment leader} is set in the RCS archive 7250file, in which case the comment leader will be used instead. For more on 7251setting the comment leader in the RCS archive file, @xref{admin}. For more 7252on configuring the default @code{$@splitrcskeyword{Log}$} substitution 7253behavior, @xref{config}. 7254 7255@xref{Log keyword}. 7256 7257@cindex RCSfile keyword 7258@item $@splitrcskeyword{RCSfile}$ 7259The name of the RCS file without a path. 7260 7261@cindex Revision keyword 7262@item $@splitrcskeyword{Revision}$ 7263The revision number assigned to the revision. 7264 7265@cindex Source keyword 7266@item $@splitrcskeyword{Source}$ 7267The full pathname of the RCS file. 7268 7269@cindex State keyword 7270@item $@splitrcskeyword{State}$ 7271The state assigned to the revision. States can be 7272assigned with @code{cvs admin -s}---see @ref{admin options}. 7273 7274@cindex Local keyword 7275@item Local keyword 7276The @code{LocalKeyword} option in the @file{CVSROOT/config} file 7277may be used to specify a local keyword which is to be 7278used as an alias for one of the keywords: $@splitrcskeyword{Id}$, 7279$@splitrcskeyword{Header}$, or $@splitrcskeyword{CVSHeader}$. For 7280example, if the @file{CVSROOT/config} file contains 7281a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a 7282file with the local keyword $@splitrcskeyword{MYBSD}$ will be 7283expanded as if it were a $@splitrcskeyword{CVSHeader}$ keyword. If 7284the src/frob.c file contained this keyword, it might 7285look something like this: 7286 7287@example 7288 /* 7289 * $@splitrcskeyword{MYBSD}: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 7290 */ 7291@end example 7292 7293Many repositories make use of a such a ``local 7294keyword'' feature. An old patch to @sc{cvs} provided 7295the @code{LocalKeyword} feature using a @code{tag=} 7296option and called this the ``custom tag'' or ``local 7297tag'' feature. It was used in conjunction with the 7298what they called the @code{tagexpand=} option. In 7299@sc{cvs} this other option is known as the 7300@code{KeywordExpand} option. 7301See @ref{Configuring keyword expansion} for more 7302details. 7303 7304Examples from popular projects include: 7305$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7306$@splitrcskeyword{OpenBSD}$, $@splitrcskeyword{XFree86}$, 7307$@splitrcskeyword{Xorg}$. 7308 7309The advantage of this is that you can include your 7310local version information in a file using this local 7311keyword without disrupting the upstream version 7312information (which may be a different local keyword or 7313a standard keyword). Allowing bug reports and the like 7314to more properly identify the source of the original 7315bug to the third-party and reducing the number of 7316conflicts that arise during an import of a new version. 7317 7318All keyword expansion except the local keyword may be 7319disabled using the @code{KeywordExpand} option in 7320the @file{CVSROOT/config} file---see 7321@ref{Configuring keyword expansion} for more details. 7322 7323@end table 7324 7325@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7326@node Using keywords 7327@section Using keywords 7328 7329To include a keyword string you simply include the 7330relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the 7331file, and commit the file. @sc{cvs} will automatically (Or, 7332more accurately, as part of the update run that 7333automatically happens after a commit.) 7334expand the string as part of the commit operation. 7335 7336It is common to embed the @code{$@splitrcskeyword{Id}$} string in 7337the source files so that it gets passed through to 7338generated files. For example, if you are managing 7339computer program source code, you might include a 7340variable which is initialized to contain that string. 7341Or some C compilers may provide a @code{#pragma ident} 7342directive. Or a document management system might 7343provide a way to pass a string through to generated 7344files. 7345 7346@c Would be nice to give an example, but doing this in 7347@c portable C is not possible and the problem with 7348@c picking any one language (VMS HELP files, Ada, 7349@c troff, whatever) is that people use CVS for all 7350@c kinds of files. 7351 7352@cindex Ident (shell command) 7353The @code{ident} command (which is part of the @sc{rcs} 7354package) can be used to extract keywords and their 7355values from a file. This can be handy for text files, 7356but it is even more useful for extracting keywords from 7357binary files. 7358 7359@example 7360$ ident samp.c 7361samp.c: 7362 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7363$ gcc samp.c 7364$ ident a.out 7365a.out: 7366 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7367@end example 7368 7369@cindex What (shell command) 7370S@sc{ccs} is another popular revision control system. 7371It has a command, @code{what}, which is very similar to 7372@code{ident} and used for the same purpose. Many sites 7373without @sc{rcs} have @sc{sccs}. Since @code{what} 7374looks for the character sequence @code{@@(#)} it is 7375easy to include keywords that are detected by either 7376command. Simply prefix the keyword with the 7377magic @sc{sccs} phrase, like this: 7378 7379@example 7380static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 7381@end example 7382 7383@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7384@node Avoiding substitution 7385@section Avoiding substitution 7386 7387Keyword substitution has its disadvantages. Sometimes 7388you might want the literal text string 7389@samp{$@splitrcskeyword{Author}$} to appear inside a file without 7390@sc{cvs} interpreting it as a keyword and expanding it 7391into something like @samp{$@splitrcskeyword{Author}: ceder $}. 7392 7393There is unfortunately no way to selectively turn off 7394keyword substitution. You can use @samp{-ko} 7395(@pxref{Substitution modes}) to turn off keyword 7396substitution entirely. 7397 7398In many cases you can avoid using keywords in 7399the source, even though they appear in the final 7400product. For example, the source for this manual 7401contains @samp{$@@asis@{@}Author$} whenever the text 7402@samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff} 7403and @code{troff} you can embed the null-character 7404@code{\&} inside the keyword for a similar effect. 7405 7406It is also possible to specify an explicit list of 7407keywords to include or exclude using the 7408@code{KeywordExpand} option in the 7409@file{CVSROOT/config} file--see @ref{Configuring keyword expansion} 7410for more details. This feature is intended primarily 7411for use with the @code{LocalKeyword} option--see 7412@ref{Keyword list}. 7413 7414@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7415@node Substitution modes 7416@section Substitution modes 7417@cindex Keyword substitution, changing modes 7418@cindex -k (keyword substitution) 7419@cindex Kflag 7420 7421@c FIXME: This could be made more coherent, by expanding it 7422@c with more examples or something. 7423Each file has a stored default substitution mode, and 7424each working directory copy of a file also has a 7425substitution mode. The former is set by the @samp{-k} 7426option to @code{cvs add} and @code{cvs admin}; the 7427latter is set by the @samp{-k} or @samp{-A} options to @code{cvs 7428checkout} or @code{cvs update}. 7429@code{cvs diff} and @code{cvs rdiff} also 7430have @samp{-k} options. 7431For some examples, 7432see @ref{Binary files}, and @ref{Merging and keywords}. 7433@c The fact that -A is overloaded to mean both reset 7434@c sticky options and reset sticky tags/dates is 7435@c somewhat questionable. Perhaps there should be 7436@c separate options to reset sticky options (e.g. -k 7437@c A") and tags/dates (someone suggested -r HEAD could 7438@c do this instead of setting a sticky tag of "HEAD" 7439@c as in the status quo but I haven't thought much 7440@c about that idea. Of course -r .reset or something 7441@c could be coined if this needs to be a new option). 7442@c On the other hand, having -A mean "get things back 7443@c into the state after a fresh checkout" has a certain 7444@c appeal, and maybe there is no sufficient reason for 7445@c creeping featurism in this area. 7446 7447The modes available are: 7448 7449@table @samp 7450@item -kkv 7451Generate keyword strings using the default form, e.g. 7452@code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision} 7453keyword. 7454 7455@item -kkvl 7456Like @samp{-kkv}, except that a locker's name is always 7457inserted if the given revision is currently locked. 7458The locker's name is only relevant if @code{cvs admin 7459-l} is in use. 7460 7461@item -kk 7462Generate only keyword names in keyword strings; omit 7463their values. For example, for the @code{Revision} 7464keyword, generate the string @code{$@splitrcskeyword{Revision}$} 7465instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option 7466is useful to ignore differences due to keyword 7467substitution when comparing different revisions of a 7468file (@pxref{Merging and keywords}). 7469 7470@item -ko 7471Generate the old keyword string, present in the working 7472file just before it was checked in. For example, for 7473the @code{Revision} keyword, generate the string 7474@code{$@splitrcskeyword{Revision}: 1.1 $} instead of 7475@code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the 7476string appeared when the file was checked in. 7477 7478@item -kb 7479Like @samp{-ko}, but also inhibit conversion of line 7480endings between the canonical form in which they are 7481stored in the repository (linefeed only), and the form 7482appropriate to the operating system in use on the 7483client. For systems, like unix, which use linefeed 7484only to terminate lines, this is very similar to 7485@samp{-ko}. For more information on binary files, see 7486@ref{Binary files}. In @sc{cvs} version 1.12.2 and later 7487@samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or 7488@code{cvs import} may not be overridden by a @samp{-k} option 7489specified on the command line. 7490 7491@item -kv 7492Generate only keyword values for keyword strings. For 7493example, for the @code{Revision} keyword, generate the string 7494@code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. 7495This can help generate files in programming languages 7496where it is hard to strip keyword delimiters like 7497@code{$@splitrcskeyword{Revision}: $} from a string. However, 7498further keyword substitution cannot be performed once 7499the keyword names are removed, so this option should be 7500used with care. 7501 7502One often would like to use @samp{-kv} with @code{cvs 7503export}---@pxref{export}. But be aware that doesn't 7504handle an export containing binary files correctly. 7505 7506@end table 7507 7508@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7509@node Configuring keyword expansion 7510@section Configuring Keyword Expansion 7511@cindex Configuring keyword expansion 7512 7513In a repository that includes third-party software on 7514vendor branches, it is sometimes helpful to configure 7515CVS to use a local keyword instead of the standard 7516$@splitrcskeyword{Id}$ or $@splitrcskeyword{Header}$ keywords. Examples from 7517real projects include $@splitrcskeyword{Xorg}$, $@splitrcskeyword{XFree86}$, 7518$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7519$@splitrcskeyword{OpenBSD}$, and even $@splitrcskeyword{dotat}$. 7520The advantage of this is that 7521you can include your local version information in a 7522file using this local keyword (sometimes called a 7523``custom tag'' or a ``local tag'') without disrupting 7524the upstream version information (which may be a 7525different local keyword or a standard keyword). In 7526these cases, it is typically desirable to disable the 7527expansion of all keywords except the configured local 7528keyword. 7529 7530The @code{KeywordExpand} option in the 7531@file{CVSROOT/config} file is intended to allow for the 7532either the explicit exclusion of a keyword or list of 7533keywords, or for the explicit inclusion of a keyword or 7534a list of keywords. This list may include the 7535@code{LocalKeyword} that has been configured. 7536 7537The @code{KeywordExpand} option is followed by 7538@code{=} and the next character may either be @code{i} 7539to start an inclusion list or @code{e} to start an 7540exclusion list. If the following lines were added to 7541the @file{CVSROOT/config} file: 7542 7543@example 7544 # Add a "MyBSD" keyword and restrict keyword 7545 # expansion 7546 LocalKeyword=MyBSD=CVSHeader 7547 KeywordExpand=iMyBSD 7548@end example 7549 7550then only the $@splitrcskeyword{MyBSD}$ keyword would be expanded. 7551A list may be used. The this example: 7552 7553@example 7554 # Add a "MyBSD" keyword and restrict keyword 7555 # expansion to the MyBSD, Name and Date keywords. 7556 LocalKeyword=MyBSD=CVSHeader 7557 KeywordExpand=iMyBSD,Name,Date 7558@end example 7559 7560would allow $@splitrcskeyword{MyBSD}$, $@splitrcskeyword{Name}$, and 7561$@splitrcskeyword{Date}$ to be expanded. 7562 7563It is also possible to configure an exclusion list 7564using the following: 7565 7566@example 7567 # Do not expand the non-RCS keyword CVSHeader 7568 KeywordExpand=eCVSHeader 7569@end example 7570 7571This allows @sc{cvs} to ignore the recently introduced 7572$@splitrcskeyword{CVSHeader}$ keyword and retain all of the 7573others. The exclusion entry could also contain the 7574standard RCS keyword list, but this could be confusing 7575to users that expect RCS keywords to be expanded, so 7576care should be taken to properly set user expectations 7577for a repository that is configured in that manner. 7578 7579If there is a desire to not have any RCS keywords 7580expanded and not use the @code{-ko} flags everywhere, 7581an administrator may disable all keyword expansion 7582using the @file{CVSROOT/config} line: 7583 7584@example 7585 # Do not expand any RCS keywords 7586 KeywordExpand=i 7587@end example 7588 7589this could be confusing to users that expect RCS 7590keywords like $@splitrcskeyword{Id}$ to be expanded properly, 7591so care should be taken to properly set user 7592expectations for a repository so configured. 7593 7594It should be noted that a patch to provide both the 7595@code{KeywordExpand} and @code{LocalKeyword} features 7596has been around a long time. However, that patch 7597implemented these features using @code{tag=} and 7598@code{tagexpand=} keywords and those keywords are NOT 7599recognized. 7600 7601@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7602@node Log keyword 7603@section Problems with the $@splitrcskeyword{Log}$ keyword. 7604 7605The @code{$@splitrcskeyword{Log}$} keyword is somewhat 7606controversial. As long as you are working on your 7607development system the information is easily accessible 7608even if you do not use the @code{$@splitrcskeyword{Log}$} 7609keyword---just do a @code{cvs log}. Once you export 7610the file the history information might be useless 7611anyhow. 7612 7613A more serious concern is that @sc{cvs} is not good at 7614handling @code{$@splitrcskeyword{Log}$} entries when a branch is 7615merged onto the main trunk. Conflicts often result 7616from the merging operation. 7617@c Might want to check whether the CVS implementation 7618@c of RCS_merge has this problem the same way rcsmerge 7619@c does. I would assume so.... 7620 7621People also tend to "fix" the log entries in the file 7622(correcting spelling mistakes and maybe even factual 7623errors). If that is done the information from 7624@code{cvs log} will not be consistent with the 7625information inside the file. This may or may not be a 7626problem in real life. 7627 7628It has been suggested that the @code{$@splitrcskeyword{Log}$} 7629keyword should be inserted @emph{last} in the file, and 7630not in the files header, if it is to be used at all. 7631That way the long list of change messages will not 7632interfere with everyday source file browsing. 7633 7634@c --------------------------------------------------------------------- 7635@node Tracking sources 7636@chapter Tracking third-party sources 7637@cindex Third-party sources 7638@cindex Tracking sources 7639 7640@c FIXME: Need discussion of added and removed files. 7641@c FIXME: This doesn't really adequately introduce the 7642@c concepts of "vendor" and "you". They don't *have* 7643@c to be separate organizations or separate people. 7644@c We want a description which is somewhat more based on 7645@c the technical issues of which sources go where, but 7646@c also with enough examples of how this relates to 7647@c relationships like customer-supplier, developer-QA, 7648@c maintainer-contributor, or whatever, to make it 7649@c seem concrete. 7650If you modify a program to better fit your site, you 7651probably want to include your modifications when the next 7652release of the program arrives. @sc{cvs} can help you with 7653this task. 7654 7655@cindex Vendor 7656@cindex Vendor branch 7657@cindex Branch, vendor- 7658In the terminology used in @sc{cvs}, the supplier of the 7659program is called a @dfn{vendor}. The unmodified 7660distribution from the vendor is checked in on its own 7661branch, the @dfn{vendor branch}. @sc{cvs} reserves branch 76621.1.1 for this use. 7663 7664When you modify the source and commit it, your revision 7665will end up on the main trunk. When a new release is 7666made by the vendor, you commit it on the vendor branch 7667and copy the modifications onto the main trunk. 7668 7669Use the @code{import} command to create and update 7670the vendor branch. When you import a new file, 7671(usually) the vendor branch is made the `head' revision, so 7672anyone that checks out a copy of the file gets that 7673revision. When a local modification is committed it is 7674placed on the main trunk, and made the `head' 7675revision. 7676 7677@menu 7678* First import:: Importing for the first time 7679* Update imports:: Updating with the import command 7680* Reverting local changes:: Reverting to the latest vendor release 7681* Binary files in imports:: Binary files require special handling 7682* Keywords in imports:: Keyword substitution might be undesirable 7683* Multiple vendor branches:: What if you get sources from several places? 7684@end menu 7685 7686@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7687@node First import 7688@section Importing for the first time 7689@cindex Importing modules 7690 7691@c Should mention naming conventions for vendor tags, 7692@c release tags, and perhaps directory names. 7693Use the @code{import} command to check in the sources 7694for the first time. When you use the @code{import} 7695command to track third-party sources, the @dfn{vendor 7696tag} and @dfn{release tags} are useful. The 7697@dfn{vendor tag} is a symbolic name for the branch 7698(which is always 1.1.1, unless you use the @samp{-b 7699@var{branch}} flag---see @ref{Multiple vendor branches}.). The 7700@dfn{release tags} are symbolic names for a particular 7701release, such as @samp{FSF_0_04}. 7702 7703@c I'm not completely sure this belongs here. But 7704@c we need to say it _somewhere_ reasonably obvious; it 7705@c is a common misconception among people first learning CVS 7706Note that @code{import} does @emph{not} change the 7707directory in which you invoke it. In particular, it 7708does not set up that directory as a @sc{cvs} working 7709directory; if you want to work with the sources import 7710them first and then check them out into a different 7711directory (@pxref{Getting the source}). 7712 7713@cindex wdiff (import example) 7714Suppose you have the sources to a program called 7715@code{wdiff} in a directory @file{wdiff-0.04}, 7716and are going to make private modifications that you 7717want to be able to use even when new releases are made 7718in the future. You start by importing the source to 7719your repository: 7720 7721@example 7722$ cd wdiff-0.04 7723$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 7724@end example 7725 7726The vendor tag is named @samp{FSF_DIST} in the above 7727example, and the only release tag assigned is 7728@samp{WDIFF_0_04}. 7729@c FIXME: Need to say where fsf/wdiff comes from. 7730 7731@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7732@node Update imports 7733@section Updating with the import command 7734 7735When a new release of the source arrives, you import it into the 7736repository with the same @code{import} command that you used to set up 7737the repository in the first place. The only difference is that you 7738specify a different release tag this time: 7739 7740@example 7741$ tar xfz wdiff-0.05.tar.gz 7742$ cd wdiff-0.05 7743$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 7744@end example 7745 7746@strong{WARNING: If you use a release tag that already exists in one of the 7747repository archives, files removed by an import may not be detected.} 7748 7749For files that have not been modified locally, the newly created 7750revision becomes the head revision. If you have made local 7751changes, @code{import} will warn you that you must merge the changes 7752into the main trunk, and tell you to use @samp{checkout -j} to do so: 7753 7754@c FIXME: why "wdiff" here and "fsf/wdiff" in the 7755@c "import"? I think the assumption is that one has 7756@c "wdiff fsf/wdiff" or some such in modules, but it 7757@c would be better to not use modules in this example. 7758@example 7759$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 7760@end example 7761 7762@noindent 7763The above command will check out the latest revision of 7764@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 7765since yesterday into the working copy. If any conflicts arise during 7766the merge they should be resolved in the normal way (@pxref{Conflicts 7767example}). Then, the modified files may be committed. 7768 7769However, it is much better to use the two release tags rather than using 7770a date on the branch as suggested above: 7771 7772@example 7773$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 7774@end example 7775 7776@noindent 7777The reason this is better is that 7778using a date, as suggested above, assumes that you do 7779not import more than one release of a product per day. 7780More importantly, using the release tags allows @sc{cvs} to detect files 7781that were removed between the two vendor releases and mark them for 7782removal. Since @code{import} has no way to detect removed files, you 7783should do a merge like this even if @code{import} doesn't tell you to. 7784 7785@node Reverting local changes 7786@section Reverting to the latest vendor release 7787 7788You can also revert local changes completely and return 7789to the latest vendor release by changing the `head' 7790revision back to the vendor branch on all files. For 7791example, if you have a checked-out copy of the sources 7792in @file{~/work.d/wdiff}, and you want to revert to the 7793vendor's version for all the files in that directory, 7794you would type: 7795 7796@example 7797$ cd ~/work.d/wdiff 7798$ cvs admin -bFSF_DIST . 7799@end example 7800 7801@noindent 7802You must specify the @samp{-bFSF_DIST} without any space 7803after the @samp{-b}. @xref{admin options}. 7804 7805@node Binary files in imports 7806@section How to handle binary files with cvs import 7807 7808Use the @samp{-k} wrapper option to tell import which 7809files are binary. @xref{Wrappers}. 7810 7811@node Keywords in imports 7812@section How to handle keyword substitution with cvs import 7813 7814The sources which you are importing may contain 7815keywords (@pxref{Keyword substitution}). For example, 7816the vendor may use @sc{cvs} or some other system 7817which uses similar keyword expansion syntax. If you 7818just import the files in the default fashion, then 7819the keyword expansions supplied by the vendor will 7820be replaced by keyword expansions supplied by your 7821own copy of @sc{cvs}. It may be more convenient to 7822maintain the expansions supplied by the vendor, so 7823that this information can supply information about 7824the sources that you imported from the vendor. 7825 7826To maintain the keyword expansions supplied by the 7827vendor, supply the @samp{-ko} option to @code{cvs 7828import} the first time you import the file. 7829This will turn off keyword expansion 7830for that file entirely, so if you want to be more 7831selective you'll have to think about what you want 7832and use the @samp{-k} option to @code{cvs update} or 7833@code{cvs admin} as appropriate. 7834@c Supplying -ko to import if the file already existed 7835@c has no effect. Not clear to me whether it should 7836@c or not. 7837 7838@node Multiple vendor branches 7839@section Multiple vendor branches 7840 7841All the examples so far assume that there is only one 7842vendor from which you are getting sources. In some 7843situations you might get sources from a variety of 7844places. For example, suppose that you are dealing with 7845a project where many different people and teams are 7846modifying the software. There are a variety of ways to 7847handle this, but in some cases you have a bunch of 7848source trees lying around and what you want to do more 7849than anything else is just to all put them in @sc{cvs} so 7850that you at least have them in one place. 7851 7852For handling situations in which there may be more than 7853one vendor, you may specify the @samp{-b} option to 7854@code{cvs import}. It takes as an argument the vendor 7855branch to import to. The default is @samp{-b 1.1.1}. 7856 7857For example, suppose that there are two teams, the red 7858team and the blue team, that are sending you sources. 7859You want to import the red team's efforts to branch 78601.1.1 and use the vendor tag RED. You want to import 7861the blue team's efforts to branch 1.1.3 and use the 7862vendor tag BLUE. So the commands you might use are: 7863 7864@example 7865$ cvs import dir RED RED_1-0 7866$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 7867@end example 7868 7869Note that if your vendor tag does not match your 7870@samp{-b} option, @sc{cvs} will not detect this case! For 7871example, 7872 7873@example 7874$ cvs import -b 1.1.3 dir RED RED_1-0 7875@end example 7876 7877@noindent 7878Be careful; this kind of mismatch is sure to sow 7879confusion or worse. I can't think of a useful purpose 7880for the ability to specify a mismatch here, but if you 7881discover such a use, don't. @sc{cvs} is likely to make this 7882an error in some future release. 7883 7884@c Probably should say more about the semantics of 7885@c multiple branches. What about the default branch? 7886@c What about joining (perhaps not as useful with 7887@c multiple branches, or perhaps it is. Either way 7888@c should be mentioned). 7889 7890@c I'm not sure about the best location for this. In 7891@c one sense, it might belong right after we've introduced 7892@c CVS's basic version control model, because people need 7893@c to figure out builds right away. The current location 7894@c is based on the theory that it kind of akin to the 7895@c "Revision management" section. 7896@node Builds 7897@chapter How your build system interacts with CVS 7898@cindex Builds 7899@cindex make 7900 7901As mentioned in the introduction, @sc{cvs} does not 7902contain software for building your software from source 7903code. This section describes how various aspects of 7904your build system might interact with @sc{cvs}. 7905 7906@c Is there a way to discuss this without reference to 7907@c tools other than CVS? I'm not sure there is; I 7908@c wouldn't think that people who learn CVS first would 7909@c even have this concern. 7910One common question, especially from people who are 7911accustomed to @sc{rcs}, is how to make their build get 7912an up to date copy of the sources. The answer to this 7913with @sc{cvs} is two-fold. First of all, since 7914@sc{cvs} itself can recurse through directories, there 7915is no need to modify your @file{Makefile} (or whatever 7916configuration file your build tool uses) to make sure 7917each file is up to date. Instead, just use two 7918commands, first @code{cvs -q update} and then 7919@code{make} or whatever the command is to invoke your 7920build tool. Secondly, you do not necessarily 7921@emph{want} to get a copy of a change someone else made 7922until you have finished your own work. One suggested 7923approach is to first update your sources, then 7924implement, build and 7925test the change you were thinking of, and then commit 7926your sources (updating first if necessary). By 7927periodically (in between changes, using the approach 7928just described) updating your entire tree, you ensure 7929that your sources are sufficiently up to date. 7930 7931@cindex Bill of materials 7932One common need is to record which versions of which 7933source files went into a particular build. This kind 7934of functionality is sometimes called @dfn{bill of 7935materials} or something similar. The best way to do 7936this with @sc{cvs} is to use the @code{tag} command to 7937record which versions went into a given build 7938(@pxref{Tags}). 7939 7940Using @sc{cvs} in the most straightforward manner 7941possible, each developer will have a copy of the entire 7942source tree which is used in a particular build. If 7943the source tree is small, or if developers are 7944geographically dispersed, this is the preferred 7945solution. In fact one approach for larger projects is 7946to break a project down into smaller 7947@c I say subsystem instead of module because they may or 7948@c may not use the modules file. 7949separately-compiled subsystems, and arrange a way of 7950releasing them internally so that each developer need 7951check out only those subsystems which they are 7952actively working on. 7953 7954Another approach is to set up a structure which allows 7955developers to have their own copies of some files, and 7956for other files to access source files from a central 7957location. Many people have come up with some such a 7958@c two such people are paul@sander.cupertino.ca.us (for 7959@c a previous employer) 7960@c and gunnar.tornblom@se.abb.com (spicm and related tools), 7961@c but as far as I know 7962@c no one has nicely packaged or released such a system (or 7963@c instructions for constructing one). 7964system using features such as the symbolic link feature 7965found in many operating systems, or the @code{VPATH} 7966feature found in many versions of @code{make}. One build 7967tool which is designed to help with this kind of thing 7968is Odin (see 7969@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 7970@c Should we be saying more about Odin? Or how you use 7971@c it with CVS? Also, the Prime Time Freeware for Unix 7972@c disk (see http://www.ptf.com/) has Odin (with a nice 7973@c paragraph summarizing it on the web), so that might be a 7974@c semi-"official" place to point people. 7975@c 7976@c Of course, many non-CVS systems have this kind of 7977@c functionality, for example OSF's ODE 7978@c (http://www.osf.org/ode/) or mk 7979@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 7980@c He has changed providers in the past; a search engine search 7981@c for "Peter Ziobrzynski" probably won't get too many 7982@c spurious hits :-). A more stable URL might be 7983@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 7984@c there is any point in mentioning them here unless they 7985@c can work with CVS. 7986 7987@c --------------------------------------------------------------------- 7988@node Special Files 7989@chapter Special Files 7990 7991@cindex Special files 7992@cindex Device nodes 7993@cindex Ownership, saving in CVS 7994@cindex Permissions, saving in CVS 7995@cindex Hard links 7996@cindex Symbolic links 7997 7998In normal circumstances, @sc{cvs} works only with regular 7999files. Every file in a project is assumed to be 8000persistent; it must be possible to open, read and close 8001them; and so on. @sc{cvs} also ignores file permissions and 8002ownerships, leaving such issues to be resolved by the 8003developer at installation time. In other words, it is 8004not possible to "check in" a device into a repository; 8005if the device file cannot be opened, @sc{cvs} will refuse to 8006handle it. Files also lose their ownerships and 8007permissions during repository transactions. 8008 8009@ignore 8010If the configuration variable @code{PreservePermissions} 8011(@pxref{config}) is set in the repository, @sc{cvs} will 8012save the following file characteristics in the 8013repository: 8014 8015@itemize @bullet 8016@item user and group ownership 8017@item permissions 8018@item major and minor device numbers 8019@item symbolic links 8020@item hard link structure 8021@end itemize 8022 8023Using the @code{PreservePermissions} option affects the 8024behavior of @sc{cvs} in several ways. First, some of the 8025new operations supported by @sc{cvs} are not accessible to 8026all users. In particular, file ownership and special 8027file characteristics may only be changed by the 8028superuser. When the @code{PreservePermissions} 8029configuration variable is set, therefore, users will 8030have to be `root' in order to perform @sc{cvs} operations. 8031 8032When @code{PreservePermissions} is in use, some @sc{cvs} 8033operations (such as @samp{cvs status}) will not 8034recognize a file's hard link structure, and so will 8035emit spurious warnings about mismatching hard links. 8036The reason is that @sc{cvs}'s internal structure does not 8037make it easy for these operations to collect all the 8038necessary data about hard links, so they check for file 8039conflicts with inaccurate data. 8040 8041A more subtle difference is that @sc{cvs} considers a file 8042to have changed only if its contents have changed 8043(specifically, if the modification time of the working 8044file does not match that of the repository's file). 8045Therefore, if only the permissions, ownership or hard 8046linkage have changed, or if a device's major or minor 8047numbers have changed, @sc{cvs} will not notice. In order to 8048commit such a change to the repository, you must force 8049the commit with @samp{cvs commit -f}. This also means 8050that if a file's permissions have changed and the 8051repository file is newer than the working copy, 8052performing @samp{cvs update} will silently change the 8053permissions on the working copy. 8054 8055Changing hard links in a @sc{cvs} repository is particularly 8056delicate. Suppose that file @file{foo} is linked to 8057file @file{old}, but is later relinked to file 8058@file{new}. You can wind up in the unusual situation 8059where, although @file{foo}, @file{old} and @file{new} 8060have all had their underlying link patterns changed, 8061only @file{foo} and @file{new} have been modified, so 8062@file{old} is not considered a candidate for checking 8063in. It can be very easy to produce inconsistent 8064results this way. Therefore, we recommend that when it 8065is important to save hard links in a repository, the 8066prudent course of action is to @code{touch} any file 8067whose linkage or status has changed since the last 8068checkin. Indeed, it may be wise to @code{touch *} 8069before each commit in a directory with complex hard 8070link structures. 8071 8072It is worth noting that only regular files may 8073be merged, for reasons that hopefully are obvious. If 8074@samp{cvs update} or @samp{cvs checkout -j} attempts to 8075merge a symbolic link with a regular file, or two 8076device files for different kinds of devices, @sc{cvs} will 8077report a conflict and refuse to perform the merge. At 8078the same time, @samp{cvs diff} will not report any 8079differences between these files, since no meaningful 8080textual comparisons can be made on files which contain 8081no text. 8082 8083The @code{PreservePermissions} features do not work 8084with client/server @sc{cvs}. Another limitation is 8085that hard links must be to other files within the same 8086directory; hard links across directories are not 8087supported. 8088@end ignore 8089 8090@c --------------------------------------------------------------------- 8091@c ----- START MAN 1 ----- 8092@node CVS commands 8093@appendix Guide to CVS commands 8094 8095This appendix describes the overall structure of 8096@sc{cvs} commands, and describes some commands in 8097detail (others are described elsewhere; for a quick 8098reference to @sc{cvs} commands, @pxref{Invoking CVS}). 8099@c The idea is that we want to move the commands which 8100@c are described here into the main body of the manual, 8101@c in the process reorganizing the manual to be 8102@c organized around what the user wants to do, not 8103@c organized around CVS commands. 8104@c 8105@c Note that many users do expect a manual which is 8106@c organized by command. At least some users do. 8107@c One good addition to the "organized by command" 8108@c section (if any) would be "see also" links. 8109@c The awk manual might be a good example; it has a 8110@c reference manual which is more verbose than Invoking 8111@c CVS but probably somewhat less verbose than CVS 8112@c Commands. 8113 8114@menu 8115* Structure:: Overall structure of CVS commands 8116* Exit status:: Indicating CVS's success or failure 8117* ~/.cvsrc:: Default options with the ~/.cvsrc file 8118* Global options:: Options you give to the left of cvs_command 8119* Common options:: Options you give to the right of cvs_command 8120* Date input formats:: Acceptable formats for date specifications 8121* add:: Add files and directories to the repository 8122* admin:: Administration 8123* annotate:: What revision modified each line of a file? 8124* checkout:: Checkout sources for editing 8125* commit:: Check files into the repository 8126* diff:: Show differences between revisions 8127* export:: Export sources from CVS, similar to checkout 8128* history:: Show status of files and users 8129* import:: Import sources into CVS, using vendor branches 8130* init:: Initialize a repository 8131* log:: Show log messages for files 8132* ls & rls:: List files in the repository 8133* rdiff:: 'patch' format diffs between releases 8134* release:: Indicate that a directory is no longer in use 8135* remove:: Remove files from active development 8136* server & pserver:: Act as a server for a client on stdin/stdout 8137* update:: Bring work tree in sync with repository 8138@end menu 8139 8140@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8141@node Structure 8142@appendixsec Overall structure of CVS commands 8143@cindex Structure 8144@cindex CVS command structure 8145@cindex Command structure 8146@cindex Format of CVS commands 8147 8148The overall format of all @sc{cvs} commands is: 8149 8150@example 8151cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 8152@end example 8153 8154@table @code 8155@item cvs 8156The name of the @sc{cvs} program. 8157 8158@item cvs_options 8159Some options that affect all sub-commands of @sc{cvs}. These are 8160described below. 8161 8162@item cvs_command 8163One of several different sub-commands. Some of the commands have 8164aliases that can be used instead; those aliases are noted in the 8165reference manual for that command. There are only two situations 8166where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 8167list of available commands, and @samp{cvs -v} displays version 8168information on @sc{cvs} itself. 8169 8170@item command_options 8171Options that are specific for the command. 8172 8173@item command_args 8174Arguments to the commands. 8175@end table 8176 8177There is unfortunately some confusion between 8178@code{cvs_options} and @code{command_options}. 8179When given as a @code{cvs_option}, some options only 8180affect some of the commands. When given as a 8181@code{command_option} it may have a different meaning, and 8182be accepted by more commands. In other words, do not 8183take the above categorization too seriously. Look at 8184the documentation instead. 8185 8186@node Exit status 8187@appendixsec CVS's exit status 8188@cindex Exit status, of CVS 8189 8190@sc{cvs} can indicate to the calling environment whether it 8191succeeded or failed by setting its @dfn{exit status}. 8192The exact way of testing the exit status will vary from 8193one operating system to another. For example in a unix 8194shell script the @samp{$?} variable will be 0 if the 8195last command returned a successful exit status, or 8196greater than 0 if the exit status indicated failure. 8197 8198If @sc{cvs} is successful, it returns a successful status; 8199if there is an error, it prints an error message and 8200returns a failure status. The one exception to this is 8201the @code{cvs diff} command. It will return a 8202successful status if it found no differences, or a 8203failure status if there were differences or if there 8204was an error. Because this behavior provides no good 8205way to detect errors, in the future it is possible that 8206@code{cvs diff} will be changed to behave like the 8207other @sc{cvs} commands. 8208@c It might seem like checking whether cvs -q diff 8209@c produces empty or non-empty output can tell whether 8210@c there were differences or not. But it seems like 8211@c there are cases with output but no differences 8212@c (testsuite basica-8b). It is not clear to me how 8213@c useful it is for a script to be able to check 8214@c whether there were differences. 8215@c FIXCVS? In previous versions of CVS, cvs diff 8216@c returned 0 for no differences, 1 for differences, or 8217@c 2 for errors. Is this behavior worth trying to 8218@c bring back (but what does it mean for VMS?)? 8219 8220@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8221@node ~/.cvsrc 8222@appendixsec Default options and the ~/.cvsrc file 8223@cindex .cvsrc file 8224@cindex Option defaults 8225 8226There are some @code{command_options} that are used so 8227often that you might have set up an alias or some other 8228means to make sure you always specify that option. One 8229example (the one that drove the implementation of the 8230@file{.cvsrc} support, actually) is that many people find the 8231default output of the @samp{diff} command to be very 8232hard to read, and that either context diffs or unidiffs 8233are much easier to understand. 8234 8235The @file{~/.cvsrc} file is a way that you can add 8236default options to @code{cvs_commands} within cvs, 8237instead of relying on aliases or other shell scripts. 8238 8239The format of the @file{~/.cvsrc} file is simple. The 8240file is searched for a line that begins with the same 8241name as the @code{cvs_command} being executed. If a 8242match is found, then the remainder of the line is split 8243up (at whitespace characters) into separate options and 8244added to the command arguments @emph{before} any 8245options from the command line. 8246 8247If a command has two names (e.g., @code{checkout} and 8248@code{co}), the official name, not necessarily the one 8249used on the command line, will be used to match against 8250the file. So if this is the contents of the user's 8251@file{~/.cvsrc} file: 8252 8253@example 8254log -N 8255diff -uN 8256rdiff -u 8257update -Pd 8258checkout -P 8259release -d 8260@end example 8261 8262@noindent 8263the command @samp{cvs checkout foo} would have the 8264@samp{-P} option added to the arguments, as well as 8265@samp{cvs co foo}. 8266 8267With the example file above, the output from @samp{cvs 8268diff foobar} will be in unidiff format. @samp{cvs diff 8269-c foobar} will provide context diffs, as usual. 8270Getting "old" format diffs would be slightly more 8271complicated, because @code{diff} doesn't have an option 8272to specify use of the "old" format, so you would need 8273@samp{cvs -f diff foobar}. 8274 8275In place of the command name you can use @code{cvs} to 8276specify global options (@pxref{Global options}). For 8277example the following line in @file{.cvsrc} 8278 8279@example 8280cvs -z6 8281@end example 8282 8283@noindent 8284causes @sc{cvs} to use compression level 6. 8285 8286@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8287@node Global options 8288@appendixsec Global options 8289@cindex Options, global 8290@cindex Global options 8291@cindex Left-hand options 8292 8293The available @samp{cvs_options} (that are given to the 8294left of @samp{cvs_command}) are: 8295 8296@table @code 8297@item --allow-root=@var{rootdir} 8298May be invoked multiple times to specify one legal @sc{cvsroot} directory with 8299each invocation. Also causes CVS to preparse the configuration file for each 8300specified root, which can be useful when configuring write proxies, See 8301@ref{Password authentication server} & @ref{Write proxies}. 8302 8303@cindex Authentication, stream 8304@cindex Stream authentication 8305@item -a 8306Authenticate all communication between the client and 8307the server. Only has an effect on the @sc{cvs} client. 8308As of this writing, this is only implemented when using 8309a GSSAPI connection (@pxref{GSSAPI authenticated}). 8310Authentication prevents certain sorts of attacks 8311involving hijacking the active @sc{tcp} connection. 8312Enabling authentication does not enable encryption. 8313 8314@cindex RCSBIN, overriding 8315@cindex Overriding RCSBIN 8316@item -b @var{bindir} 8317In @sc{cvs} 1.9.18 and older, this specified that 8318@sc{rcs} programs are in the @var{bindir} directory. 8319Current versions of @sc{cvs} do not run @sc{rcs} 8320programs; for compatibility this option is accepted, 8321but it does nothing. 8322 8323@cindex TMPDIR, environment variable 8324@cindex temporary file directory, set via command line 8325@cindex temporary file directory, set via environment variable 8326@cindex temporary file directory, set via config 8327@cindex temporary files, location of 8328@item -T @var{tempdir} 8329Use @var{tempdir} as the directory where temporary files are 8330located. 8331 8332The @sc{cvs} client and server store temporary files in a temporary directory. 8333The path to this temporary directory is set via, in order of precedence: 8334 8335@itemize @bullet 8336@item 8337The argument to the global @samp{-T} option. 8338 8339@item 8340The value set for @code{TmpDir} in the config file (server only - 8341@pxref{config}). 8342 8343@item 8344The contents of the @code{$TMPDIR} environment variable (@code{%TMPDIR%} on 8345Windows - @pxref{Environment variables}). 8346 8347@item 8348/tmp 8349 8350@end itemize 8351 8352Temporary directories should always be specified as an absolute pathname. 8353When running a CVS client, @samp{-T} affects only the local process; 8354specifying @samp{-T} for the client has no effect on the server and 8355vice versa. 8356 8357@cindex CVSROOT, overriding 8358@cindex Overriding CVSROOT 8359@item -d @var{cvs_root_directory} 8360Use @var{cvs_root_directory} as the root directory 8361pathname of the repository. Overrides the setting of 8362the @code{$CVSROOT} environment variable. @xref{Repository}. 8363 8364@cindex EDITOR, overriding 8365@cindex Overriding EDITOR 8366@item -e @var{editor} 8367Use @var{editor} to enter revision log information. Overrides the 8368setting of the @code{$CVSEDITOR} and @code{$EDITOR} 8369environment variables. For more information, see 8370@ref{Committing your changes}. 8371 8372@item -f 8373Do not read the @file{~/.cvsrc} file. This 8374option is most often used because of the 8375non-orthogonality of the @sc{cvs} option set. For 8376example, the @samp{cvs log} option @samp{-N} (turn off 8377display of tag names) does not have a corresponding 8378option to turn the display on. So if you have 8379@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 8380you may need to use @samp{-f} to show the tag names. 8381 8382@item -H 8383@itemx --help 8384Display usage information about the specified @samp{cvs_command} 8385(but do not actually execute the command). If you don't specify 8386a command name, @samp{cvs -H} displays overall help for 8387@sc{cvs}, including a list of other help options. 8388@c It seems to me it is better to document it this way 8389@c rather than trying to update this documentation 8390@c every time that we add a --help-foo option. But 8391@c perhaps that is confusing... 8392 8393@cindex Read-only repository mode 8394@item -R 8395Turns on read-only repository mode. This allows one to check out from a 8396read-only repository, such as within an anoncvs server, or from a @sc{cd-rom} 8397repository. 8398 8399Same effect as if the @code{CVSREADONLYFS} environment 8400variable is set. Using @samp{-R} can also considerably 8401speed up checkouts over NFS. 8402 8403@cindex Read-only mode 8404@item -n 8405Do not change any files. Attempt to execute the 8406@samp{cvs_command}, but only to issue reports; do not remove, 8407update, or merge any existing files, or create any new files. 8408 8409Note that @sc{cvs} will not necessarily produce exactly 8410the same output as without @samp{-n}. In some cases 8411the output will be the same, but in other cases 8412@sc{cvs} will skip some of the processing that would 8413have been required to produce the exact same output. 8414 8415@item -Q 8416Cause the command to be really quiet; the command will only 8417generate output for serious problems. 8418 8419@item -q 8420Cause the command to be somewhat quiet; informational messages, 8421such as reports of recursion through subdirectories, are 8422suppressed. 8423 8424@cindex Read-only files, and -r 8425@item -r 8426Make new working files read-only. Same effect 8427as if the @code{$CVSREAD} environment variable is set 8428(@pxref{Environment variables}). The default is to 8429make working files writable, unless watches are on 8430(@pxref{Watches}). 8431 8432@item -s @var{variable}=@var{value} 8433Set a user variable (@pxref{Variables}). 8434 8435@cindex Trace 8436@item -t 8437Trace program execution; display messages showing the steps of 8438@sc{cvs} activity. Particularly useful with @samp{-n} to explore the 8439potential impact of an unfamiliar command. 8440 8441@item -v 8442@item --version 8443Display version and copyright information for @sc{cvs}. 8444 8445@cindex CVSREAD, overriding 8446@cindex Overriding CVSREAD 8447@item -w 8448Make new working files read-write. Overrides the 8449setting of the @code{$CVSREAD} environment variable. 8450Files are created read-write by default, unless @code{$CVSREAD} is 8451set or @samp{-r} is given. 8452@c Note that -w only overrides -r and CVSREAD; it has 8453@c no effect on files which are readonly because of 8454@c "cvs watch on". My guess is that is the way it 8455@c should be (or should "cvs -w get" on a watched file 8456@c be the same as a get and a cvs edit?), but I'm not 8457@c completely sure whether to document it this way. 8458 8459@item -x 8460@cindex Encryption 8461Encrypt all communication between the client and the 8462server. Only has an effect on the @sc{cvs} client. As 8463of this writing, this is only implemented when using a 8464GSSAPI connection (@pxref{GSSAPI authenticated}) or a 8465Kerberos connection (@pxref{Kerberos authenticated}). 8466Enabling encryption implies that message traffic is 8467also authenticated. Encryption support is not 8468available by default; it must be enabled using a 8469special configure option, @file{--enable-encryption}, 8470when you build @sc{cvs}. 8471 8472@item -z @var{level} 8473@cindex Compression 8474@cindex Gzip 8475Request compression @var{level} for network traffic. 8476@sc{cvs} interprets @var{level} identically to the @code{gzip} program. 8477Valid levels are 1 (high speed, low compression) to 84789 (low speed, high compression), or 0 to disable 8479compression (the default). Data sent to the server will 8480be compressed at the requested level and the client will request 8481the server use the same compression level for data returned. The 8482server will use the closest level allowed by the server administrator to 8483compress returned data. This option only has an effect when passed to 8484the @sc{cvs} client. 8485@end table 8486 8487@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8488@node Common options 8489@appendixsec Common command options 8490@cindex Common options 8491@cindex Right-hand options 8492 8493This section describes the @samp{command_options} that 8494are available across several @sc{cvs} commands. These 8495options are always given to the right of 8496@samp{cvs_command}. Not all 8497commands support all of these options; each option is 8498only supported for commands where it makes sense. 8499However, when a command has one of these options you 8500can almost always count on the same behavior of the 8501option as in other commands. (Other command options, 8502which are listed with the individual commands, may have 8503different behavior from one @sc{cvs} command to the other). 8504 8505@strong{Note: the @samp{history} command is an exception; it supports 8506many options that conflict even with these standard options.} 8507 8508@table @code 8509@cindex Dates 8510@cindex Time 8511@cindex Specifying dates 8512@item -D @var{date_spec} 8513Use the most recent revision no later than @var{date_spec}. 8514@var{date_spec} is a single argument, a date description 8515specifying a date in the past. 8516 8517The specification is @dfn{sticky} when you use it to make a 8518private copy of a source file; that is, when you get a working 8519file using @samp{-D}, @sc{cvs} records the date you specified, so that 8520further updates in the same directory will use the same date 8521(for more information on sticky tags/dates, @pxref{Sticky tags}). 8522 8523@samp{-D} is available with the @code{annotate}, @code{checkout}, 8524@code{diff}, @code{export}, @code{history}, @code{ls}, 8525@code{rdiff}, @code{rls}, @code{rtag}, @code{tag}, and @code{update} commands. 8526(The @code{history} command uses this option in a 8527slightly different way; @pxref{history options}). 8528 8529For a complete description of the date formats accepted by @sc{cvs}, 8530@ref{Date input formats}. 8531@c What other formats should we accept? I don't want 8532@c to start accepting a whole mess of non-standard 8533@c new formats (there are a lot which are in wide use in 8534@c one context or another), but practicality does 8535@c dictate some level of flexibility. 8536@c * POSIX.2 (e.g. touch, ls output, date) and other 8537@c POSIX and/or de facto unix standards (e.g. at). The 8538@c practice here is too inconsistent to be of any use. 8539@c * VMS dates. This is not a formal standard, but 8540@c there is a published specification (see SYS$ASCTIM 8541@c and SYS$BINTIM in the _VMS System Services Reference 8542@c Manual_), it is implemented consistently in VMS 8543@c utilities, and VMS users will expect CVS running on 8544@c VMS to support this format (and if we're going to do 8545@c that, better to make CVS support it on all 8546@c platforms. Maybe). 8547@c 8548@c One more note: In output, CVS should consistently 8549@c use one date format, and that format should be one that 8550@c it accepts in input as well. The former isn't 8551@c really true (see survey below), and I'm not 8552@c sure that either of those formats is accepted in 8553@c input. 8554@c 8555@c cvs log 8556@c current 1996/01/02 13:45:31 8557@c Internet 02 Jan 1996 13:45:31 UT 8558@c ISO 1996-01-02 13:45:31 8559@c cvs ann 8560@c current 02-Jan-96 8561@c Internet-like 02 Jan 96 8562@c ISO 96-01-02 8563@c cvs status 8564@c current Tue Jun 11 02:54:53 1996 8565@c Internet [Tue,] 11 Jun 1996 02:54:53 8566@c ISO 1996-06-11 02:54:53 8567@c note: date possibly should be omitted entirely for 8568@c other reasons. 8569@c cvs editors 8570@c current Tue Jun 11 02:54:53 1996 GMT 8571@c cvs history 8572@c current 06/11 02:54 +0000 8573@c any others? 8574@c There is a good chance the proper solution has to 8575@c involve at least some level of letting the user 8576@c decide which format (with the default being the 8577@c formats CVS has always used; changing these might be 8578@c _very_ disruptive since scripts may very well be 8579@c parsing them). 8580@c 8581@c Another random bit of prior art concerning dates is 8582@c the strptime function which takes templates such as 8583@c "%m/%d/%y", and apparent a variant of getdate() 8584@c which also honors them. See 8585@c X/Open CAE Specification, System Interfaces and 8586@c Headers Issue 4, Version 2 (September 1994), in the 8587@c entry for getdate() on page 231 8588 8589Remember to quote the argument to the @samp{-D} 8590flag so that your shell doesn't interpret spaces as 8591argument separators. A command using the @samp{-D} 8592flag can look like this: 8593 8594@example 8595$ cvs diff -D "1 hour ago" cvs.texinfo 8596@end example 8597 8598@cindex Forcing a tag match 8599@item -f 8600When you specify a particular date or tag to @sc{cvs} commands, they 8601normally ignore files that do not contain the tag (or did not 8602exist prior to the date) that you specified. Use the @samp{-f} option 8603if you want files retrieved even when there is no match for the 8604tag or date. (The most recent revision of the file 8605will be used). 8606 8607Note that even with @samp{-f}, a tag that you specify 8608must exist (that is, in some file, not necessary in 8609every file). This is so that @sc{cvs} will continue to 8610give an error if you mistype a tag name. 8611 8612@need 800 8613@samp{-f} is available with these commands: 8614@code{annotate}, @code{checkout}, @code{export}, 8615@code{rdiff}, @code{rtag}, and @code{update}. 8616 8617@strong{WARNING: The @code{commit} and @code{remove} 8618commands also have a 8619@samp{-f} option, but it has a different behavior for 8620those commands. See @ref{commit options}, and 8621@ref{Removing files}.} 8622 8623@item -k @var{kflag} 8624Override the default processing of RCS keywords other than 8625@samp{-kb}. @xref{Keyword substitution}, for the meaning of 8626@var{kflag}. Used with the @code{checkout} and @code{update} 8627commands, your @var{kflag} specification is 8628@dfn{sticky}; that is, when you use this option 8629with a @code{checkout} or @code{update} command, 8630@sc{cvs} associates your selected @var{kflag} with any files 8631it operates on, and continues to use that @var{kflag} with future 8632commands on the same files until you specify otherwise. 8633 8634The @samp{-k} option is available with the @code{add}, 8635@code{checkout}, @code{diff}, @code{export}, @code{import}, 8636@code{rdiff}, and @code{update} commands. 8637 8638@strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag 8639overrode the @samp{-kb} indication for a binary file. This could 8640sometimes corrupt binary files. @xref{Merging and keywords}, for 8641more.} 8642 8643@item -l 8644Local; run only in current working directory, rather than 8645recursing through subdirectories. 8646 8647Available with the following commands: @code{annotate}, @code{checkout}, 8648@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8649@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, 8650@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8651and @code{watchers}. 8652 8653@cindex Editor, avoiding invocation of 8654@cindex Avoiding editor invocation 8655@item -m @var{message} 8656Use @var{message} as log information, instead of 8657invoking an editor. 8658 8659Available with the following commands: @code{add}, 8660@code{commit} and @code{import}. 8661 8662@item -n 8663Do not run any tag program. (A program can be 8664specified to run in the modules 8665database (@pxref{modules}); this option bypasses it). 8666 8667@strong{Note: this is not the same as the @samp{cvs -n} 8668program option, which you can specify to the left of a cvs command!} 8669 8670Available with the @code{checkout}, @code{commit}, @code{export}, 8671and @code{rtag} commands. 8672 8673@item -P 8674Prune empty directories. See @ref{Removing directories}. 8675 8676@item -p 8677Pipe the files retrieved from the repository to standard output, 8678rather than writing them in the current directory. Available 8679with the @code{checkout} and @code{update} commands. 8680 8681@item -R 8682Process directories recursively. This is the default for all @sc{cvs} 8683commands, with the exception of @code{ls} & @code{rls}. 8684 8685Available with the following commands: @code{annotate}, @code{checkout}, 8686@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8687@code{ls}, @code{rdiff}, @code{remove}, @code{rls}, @code{rtag}, 8688@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8689and @code{watchers}. 8690 8691@item -r @var{tag} 8692@item -r @var{tag}[:@var{date}] 8693@cindex HEAD, special tag 8694@cindex BASE, special tag 8695Use the revision specified by the @var{tag} argument (and the @var{date} 8696argument for the commands which accept it) instead of the 8697default @dfn{head} revision. As well as arbitrary tags defined 8698with the @code{tag} or @code{rtag} command, two special tags are 8699always available: @samp{HEAD} refers to the most recent version 8700available in the repository, and @samp{BASE} refers to the 8701revision you last checked out into the current working directory. 8702 8703@c FIXME: What does HEAD really mean? I believe that 8704@c the current answer is the head of the default branch 8705@c for all cvs commands except diff. For diff, it 8706@c seems to be (a) the head of the trunk (or the default 8707@c branch?) if there is no sticky tag, (b) the head of the 8708@c branch for the sticky tag, if there is a sticky tag. 8709@c (b) is ugly as it differs 8710@c from what HEAD means for other commands, but people 8711@c and/or scripts are quite possibly used to it. 8712@c See "head" tests in sanity.sh. 8713@c Probably the best fix is to introduce two new 8714@c special tags, ".thead" for the head of the trunk, 8715@c and ".bhead" for the head of the current branch. 8716@c Then deprecate HEAD. This has the advantage of 8717@c not surprising people with a change to HEAD, and a 8718@c side benefit of also phasing out the poorly-named 8719@c HEAD (see discussion of reserved tag names in node 8720@c "Tags"). Of course, .thead and .bhead should be 8721@c carefully implemented (with the implementation the 8722@c same for "diff" as for everyone else), test cases 8723@c written (similar to the ones in "head"), new tests 8724@c cases written for things like default branches, &c. 8725 8726The tag specification is sticky when you use this 8727with @code{checkout} or @code{update} to make your own 8728copy of a file: @sc{cvs} remembers the tag and continues to use it on 8729future update commands, until you specify otherwise (for more information 8730on sticky tags/dates, @pxref{Sticky tags}). 8731 8732The tag can be either a symbolic or numeric tag, as 8733described in @ref{Tags}, or the name of a branch, as 8734described in @ref{Branching and merging}. 8735When @var{tag} is the name of a 8736branch, some commands accept the optional @var{date} argument to specify 8737the revision as of the given date on the branch. 8738When a command expects a specific revision, 8739the name of a branch is interpreted as the most recent 8740revision on that branch. 8741 8742Specifying the @samp{-q} global option along with the 8743@samp{-r} command option is often useful, to suppress 8744the warning messages when the @sc{rcs} file 8745does not contain the specified tag. 8746 8747@strong{Note: this is not the same as the overall @samp{cvs -r} option, 8748which you can specify to the left of a @sc{cvs} command!} 8749 8750@samp{-r @var{tag}} is available with the @code{commit} and @code{history} 8751commands. 8752 8753@samp{-r @var{tag}[:@var{date}]} is available with the @code{annotate}, 8754@code{checkout}, @code{diff}, @code{export}, @code{rdiff}, @code{rtag}, 8755and @code{update} commands. 8756 8757@item -W 8758Specify file names that should be filtered. You can 8759use this option repeatedly. The spec can be a file 8760name pattern of the same type that you can specify in 8761the @file{.cvswrappers} file. 8762Available with the following commands: @code{import}, 8763and @code{update}. 8764 8765@end table 8766 8767@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8768@include getdate-cvs.texi 8769 8770@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8771@node add 8772@appendixsec add---Add files and directories to the repository 8773@cindex add (subcommand) 8774 8775@itemize @bullet 8776@item 8777Synopsis: add [-k rcs-kflag] [-m message] files... 8778@item 8779Requires: repository, working directory. 8780@item 8781Changes: repository, working directory. 8782@end itemize 8783 8784The @code{add} command is used to present new files 8785and directories for addition into the @sc{cvs} 8786repository. When @code{add} is used on a directory, 8787a new directory is created in the repository 8788immediately. When used on a file, only the working 8789directory is updated. Changes to the repository are 8790not made until the @code{commit} command is used on 8791the newly added file. 8792 8793The @code{add} command also resurrects files that 8794have been previously removed. This can be done 8795before or after the @code{commit} command is used 8796to finalize the removal of files. Resurrected files 8797are restored into the working directory at the time 8798the @code{add} command is executed. 8799 8800@menu 8801* add options:: add options 8802* add examples:: add examples 8803@end menu 8804 8805@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8806@node add options 8807@appendixsubsec add options 8808 8809These standard options are supported by @code{add} 8810(@pxref{Common options}, for a complete description of 8811them): 8812 8813@table @code 8814@item -k @var{kflag} 8815Process keywords according to @var{kflag}. See 8816@ref{Keyword substitution}. 8817This option is sticky; future updates of 8818this file in this working directory will use the same 8819@var{kflag}. The @code{status} command can be viewed 8820to see the sticky options. For more information on 8821the @code{status} command, @xref{Invoking CVS}. 8822 8823@item -m @var{message} 8824Use @var{message} as the log message, instead of 8825invoking an editor. 8826@end table 8827 8828@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8829@node add examples 8830@appendixsubsec add examples 8831 8832@appendixsubsubsec Adding a directory 8833 8834@example 8835$ mkdir doc 8836$ cvs add doc 8837Directory /path/to/repository/doc added to the repository 8838@end example 8839 8840@appendixsubsubsec Adding a file 8841 8842@example 8843 8844$ >TODO 8845$ cvs add TODO 8846cvs add: scheduling file `TODO' for addition 8847cvs add: use 'cvs commit' to add this file permanently 8848@end example 8849 8850@appendixsubsubsec Undoing a @code{remove} command 8851 8852@example 8853$ rm -f makefile 8854$ cvs remove makefile 8855cvs remove: scheduling `makefile' for removal 8856cvs remove: use 'cvs commit' to remove this file permanently 8857$ cvs add makefile 8858U makefile 8859cvs add: makefile, version 1.2, resurrected 8860@end example 8861 8862@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8863@node admin 8864@appendixsec admin---Administration 8865@cindex Admin (subcommand) 8866 8867@itemize @bullet 8868@item 8869Requires: repository, working directory. 8870@item 8871Changes: repository. 8872@item 8873Synonym: rcs 8874@end itemize 8875 8876This is the @sc{cvs} interface to assorted 8877administrative facilities. Some of them have 8878questionable usefulness for @sc{cvs} but exist for 8879historical purposes. Some of the questionable options 8880are likely to disappear in the future. This command 8881@emph{does} work recursively, so extreme care should be 8882used. 8883 8884@cindex cvsadmin 8885@cindex UserAdminOptions, in CVSROOT/config 8886On unix, if there is a group named @code{cvsadmin}, 8887only members of that group can run @code{cvs admin} 8888commands, except for those specified using the 8889@code{UserAdminOptions} configuration option in the 8890@file{CVSROOT/config} file. Options specified using 8891@code{UserAdminOptions} can be run by any user. See 8892@ref{config} for more on @code{UserAdminOptions}. 8893 8894The @code{cvsadmin} group should exist on the server, 8895or any system running the non-client/server @sc{cvs}. 8896To disallow @code{cvs admin} for all users, create a 8897group with no users in it. On NT, the @code{cvsadmin} 8898feature does not exist and all users 8899can run @code{cvs admin}. 8900 8901@menu 8902* admin options:: admin options 8903@end menu 8904 8905@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8906@node admin options 8907@appendixsubsec admin options 8908 8909Some of these options have questionable usefulness for 8910@sc{cvs} but exist for historical purposes. Some even 8911make it impossible to use @sc{cvs} until you undo the 8912effect! 8913 8914@table @code 8915@item -A@var{oldfile} 8916Might not work together with @sc{cvs}. Append the 8917access list of @var{oldfile} to the access list of the 8918@sc{rcs} file. 8919 8920@item -a@var{logins} 8921Might not work together with @sc{cvs}. Append the 8922login names appearing in the comma-separated list 8923@var{logins} to the access list of the @sc{rcs} file. 8924 8925@item -b[@var{rev}] 8926Set the default branch to @var{rev}. In @sc{cvs}, you 8927normally do not manipulate default branches; sticky 8928tags (@pxref{Sticky tags}) are a better way to decide 8929which branch you want to work on. There is one reason 8930to run @code{cvs admin -b}: to revert to the vendor's 8931version when using vendor branches (@pxref{Reverting 8932local changes}). 8933There can be no space between @samp{-b} and its argument. 8934@c Hmm, we don't document the usage where rev is 8935@c omitted. Maybe that usage can/should be deprecated 8936@c (and replaced with -bHEAD or something?) (so we can toss 8937@c the optional argument). Note that -bHEAD does not 8938@c work, as of 17 Sep 1997, but probably will once "cvs 8939@c admin" is internal to CVS. 8940 8941@cindex Comment leader 8942@item -c@var{string} 8943Sets the comment leader to @var{string}. The comment 8944leader is not used by current versions of @sc{cvs} or 8945@sc{rcs} 5.7. Therefore, you can almost surely not 8946worry about it. @xref{Keyword substitution}. 8947 8948@item -e[@var{logins}] 8949Might not work together with @sc{cvs}. Erase the login 8950names appearing in the comma-separated list 8951@var{logins} from the access list of the RCS file. If 8952@var{logins} is omitted, erase the entire access list. 8953There can be no space between @samp{-e} and its argument. 8954 8955@item -I 8956Run interactively, even if the standard input is not a 8957terminal. This option does not work with the 8958client/server @sc{cvs} and is likely to disappear in 8959a future release of @sc{cvs}. 8960 8961@item -i 8962Useless with @sc{cvs}. This creates and initializes a 8963new @sc{rcs} file, without depositing a revision. With 8964@sc{cvs}, add files with the @code{cvs add} command 8965(@pxref{Adding files}). 8966 8967@item -k@var{subst} 8968Set the default keyword 8969substitution to @var{subst}. @xref{Keyword 8970substitution}. Giving an explicit @samp{-k} option to 8971@code{cvs update}, @code{cvs export}, or @code{cvs 8972checkout} overrides this default. 8973 8974@item -l[@var{rev}] 8975Lock the revision with number @var{rev}. If a branch 8976is given, lock the latest revision on that branch. If 8977@var{rev} is omitted, lock the latest revision on the 8978default branch. There can be no space between 8979@samp{-l} and its argument. 8980 8981This can be used in conjunction with the 8982@file{rcslock.pl} script in the @file{contrib} 8983directory of the @sc{cvs} source distribution to 8984provide reserved checkouts (where only one user can be 8985editing a given file at a time). See the comments in 8986that file for details (and see the @file{README} file 8987in that directory for disclaimers about the unsupported 8988nature of contrib). According to comments in that 8989file, locking must set to strict (which is the default). 8990 8991@item -L 8992Set locking to strict. Strict locking means that the 8993owner of an RCS file is not exempt from locking for 8994checkin. For use with @sc{cvs}, strict locking must be 8995set; see the discussion under the @samp{-l} option above. 8996 8997@cindex Changing a log message 8998@cindex Replacing a log message 8999@cindex Correcting a log message 9000@cindex Fixing a log message 9001@cindex Log message, correcting 9002@item -m@var{rev}:@var{msg} 9003Replace the log message of revision @var{rev} with 9004@var{msg}. 9005 9006@c The rcs -M option, to suppress sending mail, has never been 9007@c documented as a cvs admin option. 9008 9009@item -N@var{name}[:[@var{rev}]] 9010Act like @samp{-n}, except override any previous 9011assignment of @var{name}. For use with magic branches, 9012see @ref{Magic branch numbers}. 9013 9014@item -n@var{name}[:[@var{rev}]] 9015Associate the symbolic name @var{name} with the branch 9016or revision @var{rev}. It is normally better to use 9017@samp{cvs tag} or @samp{cvs rtag} instead. Delete the 9018symbolic name if both @samp{:} and @var{rev} are 9019omitted; otherwise, print an error message if 9020@var{name} is already associated with another number. 9021If @var{rev} is symbolic, it is expanded before 9022association. A @var{rev} consisting of a branch number 9023followed by a @samp{.} stands for the current latest 9024revision in the branch. A @samp{:} with an empty 9025@var{rev} stands for the current latest revision on the 9026default branch, normally the trunk. For example, 9027@samp{cvs admin -n@var{name}:} associates @var{name} with the 9028current latest revision of all the RCS files; 9029this contrasts with @samp{cvs admin -n@var{name}:$} which 9030associates @var{name} with the revision numbers 9031extracted from keyword strings in the corresponding 9032working files. 9033 9034@cindex Deleting revisions 9035@cindex Outdating revisions 9036@cindex Saving space 9037@item -o@var{range} 9038Deletes (@dfn{outdates}) the revisions given by 9039@var{range}. 9040 9041Note that this command can be quite dangerous unless 9042you know @emph{exactly} what you are doing (for example 9043see the warnings below about how the 9044@var{rev1}:@var{rev2} syntax is confusing). 9045 9046If you are short on disc this option might help you. 9047But think twice before using it---there is no way short 9048of restoring the latest backup to undo this command! 9049If you delete different revisions than you planned, 9050either due to carelessness or (heaven forbid) a @sc{cvs} 9051bug, there is no opportunity to correct the error 9052before the revisions are deleted. It probably would be 9053a good idea to experiment on a copy of the repository 9054first. 9055 9056Specify @var{range} in one of the following ways: 9057 9058@table @code 9059@item @var{rev1}::@var{rev2} 9060Collapse all revisions between rev1 and rev2, so that 9061@sc{cvs} only stores the differences associated with going 9062from rev1 to rev2, not intermediate steps. For 9063example, after @samp{-o 1.3::1.5} one can retrieve 9064revision 1.3, revision 1.5, or the differences to get 9065from 1.3 to 1.5, but not the revision 1.4, or the 9066differences between 1.3 and 1.4. Other examples: 9067@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 9068effect, because there are no intermediate revisions to 9069remove. 9070 9071@item ::@var{rev} 9072Collapse revisions between the beginning of the branch 9073containing @var{rev} and @var{rev} itself. The 9074branchpoint and @var{rev} are left intact. For 9075example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 9076revision 1.3.2.5, and everything in between, but leaves 90771.3 and 1.3.2.6 intact. 9078 9079@item @var{rev}:: 9080Collapse revisions between @var{rev} and the end of the 9081branch containing @var{rev}. Revision @var{rev} is 9082left intact but the head revision is deleted. 9083 9084@item @var{rev} 9085Delete the revision @var{rev}. For example, @samp{-o 90861.3} is equivalent to @samp{-o 1.2::1.4}. 9087 9088@item @var{rev1}:@var{rev2} 9089Delete the revisions from @var{rev1} to @var{rev2}, 9090inclusive, on the same branch. One will not be able to 9091retrieve @var{rev1} or @var{rev2} or any of the 9092revisions in between. For example, the command 9093@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 9094It means to delete revisions up to, and including, the 9095tag R_1_02. But beware! If there are files that have not 9096changed between R_1_02 and R_1_03 the file will have 9097@emph{the same} numerical revision number assigned to 9098the tags R_1_02 and R_1_03. So not only will it be 9099impossible to retrieve R_1_02; R_1_03 will also have to 9100be restored from the tapes! In most cases you want to 9101specify @var{rev1}::@var{rev2} instead. 9102 9103@item :@var{rev} 9104Delete revisions from the beginning of the 9105branch containing @var{rev} up to and including 9106@var{rev}. 9107 9108@item @var{rev}: 9109Delete revisions from revision @var{rev}, including 9110@var{rev} itself, to the end of the branch containing 9111@var{rev}. 9112@end table 9113 9114None of the revisions to be deleted may have 9115branches or locks. 9116 9117If any of the revisions to be deleted have symbolic 9118names, and one specifies one of the @samp{::} syntaxes, 9119then @sc{cvs} will give an error and not delete any 9120revisions. If you really want to delete both the 9121symbolic names and the revisions, first delete the 9122symbolic names with @code{cvs tag -d}, then run 9123@code{cvs admin -o}. If one specifies the 9124non-@samp{::} syntaxes, then @sc{cvs} will delete the 9125revisions but leave the symbolic names pointing to 9126nonexistent revisions. This behavior is preserved for 9127compatibility with previous versions of @sc{cvs}, but 9128because it isn't very useful, in the future it may 9129change to be like the @samp{::} case. 9130 9131Due to the way @sc{cvs} handles branches @var{rev} 9132cannot be specified symbolically if it is a branch. 9133@xref{Magic branch numbers}, for an explanation. 9134@c FIXME: is this still true? I suspect not. 9135 9136Make sure that no-one has checked out a copy of the 9137revision you outdate. Strange things will happen if he 9138starts to edit it and tries to check it back in. For 9139this reason, this option is not a good way to take back 9140a bogus commit; commit a new revision undoing the bogus 9141change instead (@pxref{Merging two revisions}). 9142 9143@item -q 9144Run quietly; do not print diagnostics. 9145 9146@item -s@var{state}[:@var{rev}] 9147Useful with @sc{cvs}. Set the state attribute of the 9148revision @var{rev} to @var{state}. If @var{rev} is a 9149branch number, assume the latest revision on that 9150branch. If @var{rev} is omitted, assume the latest 9151revision on the default branch. Any identifier is 9152acceptable for @var{state}. A useful set of states is 9153@samp{Exp} (for experimental), @samp{Stab} (for 9154stable), and @samp{Rel} (for released). By default, 9155the state of a new revision is set to @samp{Exp} when 9156it is created. The state is visible in the output from 9157@var{cvs log} (@pxref{log}), and in the 9158@samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords 9159(@pxref{Keyword substitution}). Note that @sc{cvs} 9160uses the @code{dead} state for its own purposes (@pxref{Attic}); to 9161take a file to or from the @code{dead} state use 9162commands like @code{cvs remove} and @code{cvs add} 9163(@pxref{Adding and removing}), not @code{cvs admin -s}. 9164 9165@item -t[@var{file}] 9166Useful with @sc{cvs}. Write descriptive text from the 9167contents of the named @var{file} into the RCS file, 9168deleting the existing text. The @var{file} pathname 9169may not begin with @samp{-}. The descriptive text can be seen in the 9170output from @samp{cvs log} (@pxref{log}). 9171There can be no space between @samp{-t} and its argument. 9172 9173If @var{file} is omitted, 9174obtain the text from standard input, terminated by 9175end-of-file or by a line containing @samp{.} by itself. 9176Prompt for the text if interaction is possible; see 9177@samp{-I}. 9178 9179@item -t-@var{string} 9180Similar to @samp{-t@var{file}}. Write descriptive text 9181from the @var{string} into the @sc{rcs} file, deleting 9182the existing text. 9183There can be no space between @samp{-t} and its argument. 9184 9185@c The rcs -T option, do not update last-mod time for 9186@c minor changes, has never been documented as a 9187@c cvs admin option. 9188 9189@item -U 9190Set locking to non-strict. Non-strict locking means 9191that the owner of a file need not lock a revision for 9192checkin. For use with @sc{cvs}, strict locking must be 9193set; see the discussion under the @samp{-l} option 9194above. 9195 9196@item -u[@var{rev}] 9197See the option @samp{-l} above, for a discussion of 9198using this option with @sc{cvs}. Unlock the revision 9199with number @var{rev}. If a branch is given, unlock 9200the latest revision on that branch. If @var{rev} is 9201omitted, remove the latest lock held by the caller. 9202Normally, only the locker of a revision may unlock it; 9203somebody else unlocking a revision breaks the lock. 9204This causes the original locker to be sent a @code{commit} 9205notification (@pxref{Getting Notified}). 9206There can be no space between @samp{-u} and its argument. 9207 9208@item -V@var{n} 9209In previous versions of @sc{cvs}, this option meant to 9210write an @sc{rcs} file which would be acceptable to 9211@sc{rcs} version @var{n}, but it is now obsolete and 9212specifying it will produce an error. 9213@c Note that -V without an argument has never been 9214@c documented as a cvs admin option. 9215 9216@item -x@var{suffixes} 9217In previous versions of @sc{cvs}, this was documented 9218as a way of specifying the names of the @sc{rcs} 9219files. However, @sc{cvs} has always required that the 9220@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 9221this option has never done anything useful. 9222 9223@c The rcs -z option, to specify the timezone, has 9224@c never been documented as a cvs admin option. 9225@end table 9226 9227@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9228@node annotate 9229@appendixsec annotate---What revision modified each line of a file? 9230@cindex annotate (subcommand) 9231 9232@itemize @bullet 9233@item 9234Synopsis: annotate [options] files@dots{} 9235@item 9236Requires: repository. 9237@item 9238Changes: nothing. 9239@end itemize 9240 9241For each file in @var{files}, print the head revision 9242of the trunk, together with information on the last 9243modification for each line. 9244 9245@menu 9246* annotate options:: annotate options 9247* annotate example:: annotate example 9248@end menu 9249 9250@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9251@node annotate options 9252@appendixsubsec annotate options 9253 9254These standard options are supported by @code{annotate} 9255(@pxref{Common options}, for a complete description of 9256them): 9257 9258@table @code 9259@item -l 9260Local directory only, no recursion. 9261 9262@item -R 9263Process directories recursively. 9264 9265@item -f 9266Use head revision if tag/date not found. 9267 9268@item -F 9269Annotate binary files. 9270 9271@item -r @var{tag}[:@var{date}] 9272Annotate file as of specified revision/tag or, when @var{date} is specified 9273and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9274existed on @var{date}. See @ref{Common options}. 9275 9276@item -D @var{date} 9277Annotate file as of specified date. 9278@end table 9279 9280@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9281@node annotate example 9282@appendixsubsec annotate example 9283 9284For example: 9285 9286@example 9287$ cvs annotate ssfile 9288Annotations for ssfile 9289*************** 92901.1 (mary 27-Mar-96): ssfile line 1 92911.2 (joe 28-Mar-96): ssfile line 2 9292@end example 9293 9294The file @file{ssfile} currently contains two lines. 9295The @code{ssfile line 1} line was checked in by 9296@code{mary} on March 27. Then, on March 28, @code{joe} 9297added a line @code{ssfile line 2}, without modifying 9298the @code{ssfile line 1} line. This report doesn't 9299tell you anything about lines which have been deleted 9300or replaced; you need to use @code{cvs diff} for that 9301(@pxref{diff}). 9302 9303The options to @code{cvs annotate} are listed in 9304@ref{Invoking CVS}, and can be used to select the files 9305and revisions to annotate. The options are described 9306in more detail there and in @ref{Common options}. 9307 9308@c FIXME: maybe an example using the options? Just 9309@c what it means to select a revision might be worth a 9310@c few words of explanation ("you want to see who 9311@c changed this line *before* 1.4"...). 9312 9313@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9314@node checkout 9315@appendixsec checkout---Check out sources for editing 9316@cindex checkout (subcommand) 9317@cindex co (subcommand) 9318 9319@itemize @bullet 9320@item 9321Synopsis: checkout [options] modules@dots{} 9322@item 9323Requires: repository. 9324@item 9325Changes: working directory. 9326@item 9327Synonyms: co, get 9328@end itemize 9329 9330Create or update a working directory containing copies of the 9331source files specified by @var{modules}. You must execute 9332@code{checkout} before using most of the other @sc{cvs} 9333commands, since most of them operate on your working 9334directory. 9335 9336The @var{modules} are either 9337symbolic names for some 9338collection of source directories and files, or paths to 9339directories or files in the repository. The symbolic 9340names are defined in the @samp{modules} file. 9341@xref{modules}. 9342@c Needs an example, particularly of the non-"modules" 9343@c case but probably of both. 9344 9345@c FIXME: this seems like a very odd place to introduce 9346@c people to how CVS works. The bit about unreserved 9347@c checkouts is also misleading as it depends on how 9348@c things are set up. 9349Depending on the modules you specify, @code{checkout} may 9350recursively create directories and populate them with 9351the appropriate source files. You can then edit these 9352source files at any time (regardless of whether other 9353software developers are editing their own copies of the 9354sources); update them to include new changes applied by 9355others to the source repository; or commit your work as 9356a permanent change to the source repository. 9357 9358Note that @code{checkout} is used to create 9359directories. The top-level directory created is always 9360added to the directory where @code{checkout} is 9361invoked, and usually has the same name as the specified 9362module. In the case of a module alias, the created 9363sub-directory may have a different name, but you can be 9364sure that it will be a sub-directory, and that 9365@code{checkout} will show the relative path leading to 9366each file as it is extracted into your private work 9367area (unless you specify the @samp{-Q} global option). 9368 9369The files created by @code{checkout} are created 9370read-write, unless the @samp{-r} option to @sc{cvs} 9371(@pxref{Global options}) is specified, the 9372@code{CVSREAD} environment variable is specified 9373(@pxref{Environment variables}), or a watch is in 9374effect for that file (@pxref{Watches}). 9375 9376Note that running @code{checkout} on a directory that was already 9377built by a prior @code{checkout} is also permitted. 9378This is similar to specifying the @samp{-d} option 9379to the @code{update} command in the sense that new 9380directories that have been created in the repository 9381will appear in your work area. 9382However, @code{checkout} takes a module name whereas 9383@code{update} takes a directory name. Also 9384to use @code{checkout} this way it must be run from the 9385top level directory (where you originally ran 9386@code{checkout} from), so before you run 9387@code{checkout} to update an existing directory, don't 9388forget to change your directory to the top level 9389directory. 9390 9391For the output produced by the @code{checkout} command 9392see @ref{update output}. 9393 9394@menu 9395* checkout options:: checkout options 9396* checkout examples:: checkout examples 9397@end menu 9398 9399@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9400@node checkout options 9401@appendixsubsec checkout options 9402 9403These standard options are supported by @code{checkout} 9404(@pxref{Common options}, for a complete description of 9405them): 9406 9407@table @code 9408@item -D @var{date} 9409Use the most recent revision no later than @var{date}. 9410This option is sticky, and implies @samp{-P}. See 9411@ref{Sticky tags}, for more information on sticky tags/dates. 9412 9413@item -f 9414Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision is 9415found, retrieve the most recent revision (instead of ignoring the file). 9416 9417@item -k @var{kflag} 9418Process keywords according to @var{kflag}. See 9419@ref{Keyword substitution}. 9420This option is sticky; future updates of 9421this file in this working directory will use the same 9422@var{kflag}. The @code{status} command can be viewed 9423to see the sticky options. See @ref{Invoking CVS}, for 9424more information on the @code{status} command. 9425 9426@item -l 9427Local; run only in current working directory. 9428 9429@item -n 9430Do not run any checkout program (as specified 9431with the @samp{-o} option in the modules file; 9432@pxref{modules}). 9433 9434@item -P 9435Prune empty directories. See @ref{Moving directories}. 9436 9437@item -p 9438Pipe files to the standard output. 9439 9440@item -R 9441Checkout directories recursively. This option is on by default. 9442 9443@item -r @var{tag}[:@var{date}] 9444Checkout the revision specified by @var{tag} or, when @var{date} is specified 9445and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9446existed on @var{date}. This option is sticky, and implies @samp{-P}. 9447See @ref{Sticky tags}, for more information on sticky tags/dates. Also, 9448see @ref{Common options}. 9449@end table 9450 9451In addition to those, you can use these special command 9452options with @code{checkout}: 9453 9454@table @code 9455@item -A 9456Reset any sticky tags, dates, or @samp{-k} options. 9457See @ref{Sticky tags}, for more information on sticky tags/dates. 9458 9459@item -c 9460Copy the module file, sorted, to the standard output, 9461instead of creating or modifying any files or 9462directories in your working directory. 9463 9464@item -d @var{dir} 9465Create a directory called @var{dir} for the working 9466files, instead of using the module name. In general, 9467using this flag is equivalent to using @samp{mkdir 9468@var{dir}; cd @var{dir}} followed by the checkout 9469command without the @samp{-d} flag. 9470 9471There is an important exception, however. It is very 9472convenient when checking out a single item to have the 9473output appear in a directory that doesn't contain empty 9474intermediate directories. In this case @emph{only}, 9475@sc{cvs} tries to ``shorten'' pathnames to avoid those empty 9476directories. 9477 9478For example, given a module @samp{foo} that contains 9479the file @samp{bar.c}, the command @samp{cvs co -d dir 9480foo} will create directory @samp{dir} and place 9481@samp{bar.c} inside. Similarly, given a module 9482@samp{bar} which has subdirectory @samp{baz} wherein 9483there is a file @samp{quux.c}, the command @samp{cvs co 9484-d dir bar/baz} will create directory @samp{dir} and 9485place @samp{quux.c} inside. 9486 9487Using the @samp{-N} flag will defeat this behavior. 9488Given the same module definitions above, @samp{cvs co 9489-N -d dir foo} will create directories @samp{dir/foo} 9490and place @samp{bar.c} inside, while @samp{cvs co -N -d 9491dir bar/baz} will create directories @samp{dir/bar/baz} 9492and place @samp{quux.c} inside. 9493 9494@item -j @var{tag} 9495With two @samp{-j} options, merge changes from the 9496revision specified with the first @samp{-j} option to 9497the revision specified with the second @samp{j} option, 9498into the working directory. 9499 9500With one @samp{-j} option, merge changes from the 9501ancestor revision to the revision specified with the 9502@samp{-j} option, into the working directory. The 9503ancestor revision is the common ancestor of the 9504revision which the working directory is based on, and 9505the revision specified in the @samp{-j} option. 9506 9507In addition, each -j option can contain an optional 9508date specification which, when used with branches, can 9509limit the chosen revision to one within a specific 9510date. An optional date is specified by adding a colon 9511(:) to the tag: 9512@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 9513 9514@xref{Branching and merging}. 9515 9516@item -N 9517Only useful together with @samp{-d @var{dir}}. With 9518this option, @sc{cvs} will not ``shorten'' module paths 9519in your working directory when you check out a single 9520module. See the @samp{-d} flag for examples and a 9521discussion. 9522 9523@item -s 9524Like @samp{-c}, but include the status of all modules, 9525and sort it by the status string. @xref{modules}, for 9526info about the @samp{-s} option that is used inside the 9527modules file to set the module status. 9528@end table 9529 9530@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9531@node checkout examples 9532@appendixsubsec checkout examples 9533 9534Get a copy of the module @samp{tc}: 9535 9536@example 9537$ cvs checkout tc 9538@end example 9539 9540Get a copy of the module @samp{tc} as it looked one day 9541ago: 9542 9543@example 9544$ cvs checkout -D yesterday tc 9545@end example 9546 9547@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9548@node commit 9549@appendixsec commit---Check files into the repository 9550@cindex commit (subcommand) 9551 9552@itemize @bullet 9553@item 9554Synopsis: commit [-lnRf] [-m 'log_message' | 9555-F file] [-r revision] [files@dots{}] 9556@item 9557Requires: working directory, repository. 9558@item 9559Changes: repository. 9560@item 9561Synonym: ci 9562@end itemize 9563 9564Use @code{commit} when you want to incorporate changes 9565from your working source files into the source 9566repository. 9567 9568If you don't specify particular files to commit, all of 9569the files in your working current directory are 9570examined. @code{commit} is careful to change in the 9571repository only those files that you have really 9572changed. By default (or if you explicitly specify the 9573@samp{-R} option), files in subdirectories are also 9574examined and committed if they have changed; you can 9575use the @samp{-l} option to limit @code{commit} to the 9576current directory only. 9577 9578@code{commit} verifies that the selected files are up 9579to date with the current revisions in the source 9580repository; it will notify you, and exit without 9581committing, if any of the specified files must be made 9582current first with @code{update} (@pxref{update}). 9583@code{commit} does not call the @code{update} command 9584for you, but rather leaves that for you to do when the 9585time is right. 9586 9587When all is well, an editor is invoked to allow you to 9588enter a log message that will be written to one or more 9589logging programs (@pxref{modules}, and @pxref{loginfo}) 9590and placed in the @sc{rcs} file inside the 9591repository. This log message can be retrieved with the 9592@code{log} command; see @ref{log}. You can specify the 9593log message on the command line with the @samp{-m 9594@var{message}} option, and thus avoid the editor invocation, 9595or use the @samp{-F @var{file}} option to specify 9596that the argument file contains the log message. 9597 9598At @code{commit}, a unique commitid is placed in the @sc{rcs} 9599file inside the repository. All files committed at once 9600get the same commitid. The commitid can be retrieved with 9601the @code{log} and @code{status} command; see @ref{log}, 9602@ref{File status}. 9603 9604@menu 9605* commit options:: commit options 9606* commit examples:: commit examples 9607@end menu 9608 9609@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9610@node commit options 9611@appendixsubsec commit options 9612 9613These standard options are supported by @code{commit} 9614(@pxref{Common options}, for a complete description of 9615them): 9616 9617@table @code 9618@item -l 9619Local; run only in current working directory. 9620 9621@item -R 9622Commit directories recursively. This is on by default. 9623 9624@item -r @var{revision} 9625Commit to @var{revision}. @var{revision} must be 9626either a branch, or a revision on the main trunk that 9627is higher than any existing revision number 9628(@pxref{Assigning revisions}). You 9629cannot commit to a specific revision on a branch. 9630@c FIXME: Need xref for branch case. 9631@end table 9632 9633@code{commit} also supports these options: 9634 9635@table @code 9636@item -c 9637Refuse to commit files unless the user has registered a valid edit on the 9638file via @code{cvs edit}. This is most useful when @samp{commit -c} 9639and @samp{edit -c} have been placed in all @file{.cvsrc} files. 9640A commit can be forced anyways by either registering an edit retroactively 9641via @code{cvs edit} (no changes to the file will be lost) or using the 9642@code{-f} option to commit. Support for @code{commit -c} requires both 9643client and a server versions 1.12.10 or greater. 9644 9645@item -F @var{file} 9646Read the log message from @var{file}, instead 9647of invoking an editor. 9648 9649@item -f 9650Note that this is not the standard behavior of 9651the @samp{-f} option as defined in @ref{Common options}. 9652 9653Force @sc{cvs} to commit a new revision even if you haven't 9654made any changes to the file. As of @sc{cvs} version 1.12.10, 9655it also causes the @code{-c} option to be ignored. If the current revision 9656of @var{file} is 1.7, then the following two commands 9657are equivalent: 9658 9659@example 9660$ cvs commit -f @var{file} 9661$ cvs commit -r 1.8 @var{file} 9662@end example 9663 9664@c This is odd, but it's how CVS has worked for some 9665@c time. 9666The @samp{-f} option disables recursion (i.e., it 9667implies @samp{-l}). To force @sc{cvs} to commit a new 9668revision for all files in all subdirectories, you must 9669use @samp{-f -R}. 9670 9671@item -m @var{message} 9672Use @var{message} as the log message, instead of 9673invoking an editor. 9674@end table 9675 9676@need 2000 9677@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9678@node commit examples 9679@appendixsubsec commit examples 9680 9681@c FIXME: this material wants to be somewhere 9682@c in "Branching and merging". 9683 9684@appendixsubsubsec Committing to a branch 9685 9686You can commit to a branch revision (one that has an 9687even number of dots) with the @samp{-r} option. To 9688create a branch revision, use the @samp{-b} option 9689of the @code{rtag} or @code{tag} commands 9690(@pxref{Branching and merging}). Then, either @code{checkout} or 9691@code{update} can be used to base your sources on the 9692newly created branch. From that point on, all 9693@code{commit} changes made within these working sources 9694will be automatically added to a branch revision, 9695thereby not disturbing main-line development in any 9696way. For example, if you had to create a patch to the 96971.2 version of the product, even though the 2.0 version 9698is already under development, you might do: 9699 9700@example 9701$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 9702$ cvs checkout -r FCS1_2_Patch product_module 9703$ cd product_module 9704[[ hack away ]] 9705$ cvs commit 9706@end example 9707 9708@noindent 9709This works automatically since the @samp{-r} option is 9710sticky. 9711 9712@appendixsubsubsec Creating the branch after editing 9713 9714Say you have been working on some extremely 9715experimental software, based on whatever revision you 9716happened to checkout last week. If others in your 9717group would like to work on this software with you, but 9718without disturbing main-line development, you could 9719commit your change to a new branch. Others can then 9720checkout your experimental stuff and utilize the full 9721benefit of @sc{cvs} conflict resolution. The scenario might 9722look like: 9723 9724@c FIXME: Should we be recommending tagging the branchpoint? 9725@example 9726[[ hacked sources are present ]] 9727$ cvs tag -b EXPR1 9728$ cvs update -r EXPR1 9729$ cvs commit 9730@end example 9731 9732The @code{update} command will make the @samp{-r 9733EXPR1} option sticky on all files. Note that your 9734changes to the files will never be removed by the 9735@code{update} command. The @code{commit} will 9736automatically commit to the correct branch, because the 9737@samp{-r} is sticky. You could also do like this: 9738 9739@c FIXME: Should we be recommending tagging the branchpoint? 9740@example 9741[[ hacked sources are present ]] 9742$ cvs tag -b EXPR1 9743$ cvs commit -r EXPR1 9744@end example 9745 9746@noindent 9747but then, only those files that were changed by you 9748will have the @samp{-r EXPR1} sticky flag. If you hack 9749away, and commit without specifying the @samp{-r EXPR1} 9750flag, some files may accidentally end up on the main 9751trunk. 9752 9753To work with you on the experimental change, others 9754would simply do 9755 9756@example 9757$ cvs checkout -r EXPR1 whatever_module 9758@end example 9759 9760@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9761@node diff 9762@appendixsec diff---Show differences between revisions 9763@cindex diff (subcommand) 9764 9765@itemize @bullet 9766@item 9767Synopsis: diff [-lR] [-k kflag] [format_options] [(-r rev1[:date1] | -D date1) [-r rev2[:date2] | -D date2]] [files@dots{}] 9768@item 9769Requires: working directory, repository. 9770@item 9771Changes: nothing. 9772@end itemize 9773 9774The @code{diff} command is used to compare different 9775revisions of files. The default action is to compare 9776your working files with the revisions they were based 9777on, and report any differences that are found. 9778 9779If any file names are given, only those files are 9780compared. If any directories are given, all files 9781under them will be compared. 9782 9783The exit status for diff is different than for other 9784@sc{cvs} commands; for details @ref{Exit status}. 9785 9786@menu 9787* diff options:: diff options 9788* diff examples:: diff examples 9789@end menu 9790 9791@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9792@node diff options 9793@appendixsubsec diff options 9794 9795These standard options are supported by @code{diff} 9796(@pxref{Common options}, for a complete description of 9797them): 9798 9799@table @code 9800@item -D @var{date} 9801Use the most recent revision no later than @var{date}. 9802See @samp{-r} for how this affects the comparison. 9803 9804@item -k @var{kflag} 9805Process keywords according to @var{kflag}. See 9806@ref{Keyword substitution}. 9807 9808@item -l 9809Local; run only in current working directory. 9810 9811@item -R 9812Examine directories recursively. This option is on by 9813default. 9814 9815@item -r @var{tag}[:@var{date}] 9816Compare with revision specified by @var{tag} or, when @var{date} is specified 9817and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9818existed on @var{date}. Zero, one or two 9819@samp{-r} options can be present. With no @samp{-r} 9820option, the working file will be compared with the 9821revision it was based on. With one @samp{-r}, that 9822revision will be compared to your current working file. 9823With two @samp{-r} options those two revisions will be 9824compared (and your working file will not affect the 9825outcome in any way). 9826@c We should be a lot more explicit, with examples, 9827@c about the difference between "cvs diff" and "cvs 9828@c diff -r HEAD". This often confuses new users. 9829 9830One or both @samp{-r} options can be replaced by a 9831@samp{-D @var{date}} option, described above. 9832@end table 9833 9834@c Conceptually, this is a disaster. There are 3 9835@c zillion diff formats that we support via the diff 9836@c library. It is not obvious to me that we should 9837@c document them all. Maybe just the most common ones 9838@c like -c and -u, and think about phasing out the 9839@c obscure ones. 9840@c FIXCVS: also should be a way to specify an external 9841@c diff program (which can be different for different 9842@c file types) and pass through 9843@c arbitrary options, so that the user can do 9844@c "--pass=-Z --pass=foo" or something even if CVS 9845@c doesn't know about the "-Z foo" option to diff. 9846@c This would fit nicely with deprecating/eliminating 9847@c the obscure options of the diff library, because it 9848@c would let people specify an external GNU diff if 9849@c they are into that sort of thing. 9850The following options specify the format of the 9851output. They have the same meaning as in GNU diff. 9852Most options have two equivalent names, one of which is a single letter 9853preceded by @samp{-}, and the other of which is a long name preceded by 9854@samp{--}. 9855 9856@table @samp 9857@item -@var{lines} 9858Show @var{lines} (an integer) lines of context. This option does not 9859specify an output format by itself; it has no effect unless it is 9860combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9861operation, @code{patch} typically needs at least two lines of context. 9862 9863@item -a 9864Treat all files as text and compare them line-by-line, even if they 9865do not seem to be text. 9866 9867@item -b 9868Ignore trailing white space and consider all other sequences of one or 9869more white space characters to be equivalent. 9870 9871@item -B 9872Ignore changes that just insert or delete blank lines. 9873 9874@item --binary 9875Read and write data in binary mode. 9876 9877@item --brief 9878Report only whether the files differ, not the details of the 9879differences. 9880 9881@item -c 9882Use the context output format. 9883 9884@item -C @var{lines} 9885@itemx --context@r{[}=@var{lines}@r{]} 9886Use the context output format, showing @var{lines} (an integer) lines of 9887context, or three if @var{lines} is not given. 9888For proper operation, @code{patch} typically needs at least two lines of 9889context. 9890 9891@item --changed-group-format=@var{format} 9892Use @var{format} to output a line group containing differing lines from 9893both files in if-then-else format. @xref{Line group formats}. 9894 9895@item -d 9896Change the algorithm to perhaps find a smaller set of changes. This makes 9897@code{diff} slower (sometimes much slower). 9898 9899@item -e 9900@itemx --ed 9901Make output that is a valid @code{ed} script. 9902 9903@item --expand-tabs 9904Expand tabs to spaces in the output, to preserve the alignment of tabs 9905in the input files. 9906 9907@item -f 9908Make output that looks vaguely like an @code{ed} script but has changes 9909in the order they appear in the file. 9910 9911@item -F @var{regexp} 9912In context and unified format, for each hunk of differences, show some 9913of the last preceding line that matches @var{regexp}. 9914 9915@item --forward-ed 9916Make output that looks vaguely like an @code{ed} script but has changes 9917in the order they appear in the file. 9918 9919@item -H 9920Use heuristics to speed handling of large files that have numerous 9921scattered small changes. 9922 9923@item --horizon-lines=@var{lines} 9924Do not discard the last @var{lines} lines of the common prefix 9925and the first @var{lines} lines of the common suffix. 9926 9927@item -i 9928Ignore changes in case; consider upper- and lower-case letters 9929equivalent. 9930 9931@item -I @var{regexp} 9932Ignore changes that just insert or delete lines that match @var{regexp}. 9933 9934@item --ifdef=@var{name} 9935Make merged if-then-else output using @var{name}. 9936 9937@item --ignore-all-space 9938Ignore white space when comparing lines. 9939 9940@item --ignore-blank-lines 9941Ignore changes that just insert or delete blank lines. 9942 9943@item --ignore-case 9944Ignore changes in case; consider upper- and lower-case to be the same. 9945 9946@item --ignore-matching-lines=@var{regexp} 9947Ignore changes that just insert or delete lines that match @var{regexp}. 9948 9949@item --ignore-space-change 9950Ignore trailing white space and consider all other sequences of one or 9951more white space characters to be equivalent. 9952 9953@item --initial-tab 9954Output a tab rather than a space before the text of a line in normal or 9955context format. This causes the alignment of tabs in the line to look 9956normal. 9957 9958@item -L @var{label} 9959Use @var{label} instead of the file name in the context format 9960and unified format headers. 9961 9962@item --label=@var{label} 9963Use @var{label} instead of the file name in the context format 9964and unified format headers. 9965 9966@item --left-column 9967Print only the left column of two common lines in side by side format. 9968 9969@item --line-format=@var{format} 9970Use @var{format} to output all input lines in if-then-else format. 9971@xref{Line formats}. 9972 9973@item --minimal 9974Change the algorithm to perhaps find a smaller set of changes. This 9975makes @code{diff} slower (sometimes much slower). 9976 9977@item -n 9978Output RCS-format diffs; like @samp{-f} except that each command 9979specifies the number of lines affected. 9980 9981@item -N 9982@itemx --new-file 9983In directory comparison, if a file is found in only one directory, 9984treat it as present but empty in the other directory. 9985 9986@item --new-group-format=@var{format} 9987Use @var{format} to output a group of lines taken from just the second 9988file in if-then-else format. @xref{Line group formats}. 9989 9990@item --new-line-format=@var{format} 9991Use @var{format} to output a line taken from just the second file in 9992if-then-else format. @xref{Line formats}. 9993 9994@item --old-group-format=@var{format} 9995Use @var{format} to output a group of lines taken from just the first 9996file in if-then-else format. @xref{Line group formats}. 9997 9998@item --old-line-format=@var{format} 9999Use @var{format} to output a line taken from just the first file in 10000if-then-else format. @xref{Line formats}. 10001 10002@item -p 10003Show which C function each change is in. 10004 10005@item --rcs 10006Output RCS-format diffs; like @samp{-f} except that each command 10007specifies the number of lines affected. 10008 10009@item --report-identical-files 10010@itemx -s 10011Report when two files are the same. 10012 10013@item --show-c-function 10014Show which C function each change is in. 10015 10016@item --show-function-line=@var{regexp} 10017In context and unified format, for each hunk of differences, show some 10018of the last preceding line that matches @var{regexp}. 10019 10020@item --side-by-side 10021Use the side by side output format. 10022 10023@item --speed-large-files 10024Use heuristics to speed handling of large files that have numerous 10025scattered small changes. 10026 10027@item --suppress-common-lines 10028Do not print common lines in side by side format. 10029 10030@item -t 10031Expand tabs to spaces in the output, to preserve the alignment of tabs 10032in the input files. 10033 10034@item -T 10035Output a tab rather than a space before the text of a line in normal or 10036context format. This causes the alignment of tabs in the line to look 10037normal. 10038 10039@item --text 10040Treat all files as text and compare them line-by-line, even if they 10041do not appear to be text. 10042 10043@item -u 10044Use the unified output format. 10045 10046@item --unchanged-group-format=@var{format} 10047Use @var{format} to output a group of common lines taken from both files 10048in if-then-else format. @xref{Line group formats}. 10049 10050@item --unchanged-line-format=@var{format} 10051Use @var{format} to output a line common to both files in if-then-else 10052format. @xref{Line formats}. 10053 10054@item -U @var{lines} 10055@itemx --unified@r{[}=@var{lines}@r{]} 10056Use the unified output format, showing @var{lines} (an integer) lines of 10057context, or three if @var{lines} is not given. 10058For proper operation, @code{patch} typically needs at least two lines of 10059context. 10060 10061@item -w 10062Ignore white space when comparing lines. 10063 10064@item -W @var{columns} 10065@itemx --width=@var{columns} 10066Use an output width of @var{columns} in side by side format. 10067 10068@item -y 10069Use the side by side output format. 10070@end table 10071 10072@menu 10073* Line group formats:: Line group formats 10074* Line formats:: Line formats 10075@end menu 10076 10077@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10078@node Line group formats 10079@appendixsubsubsec Line group formats 10080 10081Line group formats let you specify formats suitable for many 10082applications that allow if-then-else input, including programming 10083languages and text formatting languages. A line group format specifies 10084the output format for a contiguous group of similar lines. 10085 10086For example, the following command compares the TeX file @file{myfile} 10087with the original version from the repository, 10088and outputs a merged file in which old regions are 10089surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 10090regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 10091 10092@example 10093cvs diff \ 10094 --old-group-format='\begin@{em@} 10095%<\end@{em@} 10096' \ 10097 --new-group-format='\begin@{bf@} 10098%>\end@{bf@} 10099' \ 10100 myfile 10101@end example 10102 10103The following command is equivalent to the above example, but it is a 10104little more verbose, because it spells out the default line group formats. 10105 10106@example 10107cvs diff \ 10108 --old-group-format='\begin@{em@} 10109%<\end@{em@} 10110' \ 10111 --new-group-format='\begin@{bf@} 10112%>\end@{bf@} 10113' \ 10114 --unchanged-group-format='%=' \ 10115 --changed-group-format='\begin@{em@} 10116%<\end@{em@} 10117\begin@{bf@} 10118%>\end@{bf@} 10119' \ 10120 myfile 10121@end example 10122 10123Here is a more advanced example, which outputs a diff listing with 10124headers containing line numbers in a ``plain English'' style. 10125 10126@example 10127cvs diff \ 10128 --unchanged-group-format='' \ 10129 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 10130%<' \ 10131 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 10132%>' \ 10133 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 10134%<-------- to: 10135%>' \ 10136 myfile 10137@end example 10138 10139To specify a line group format, use one of the options 10140listed below. You can specify up to four line group formats, one for 10141each kind of line group. You should quote @var{format}, because it 10142typically contains shell metacharacters. 10143 10144@table @samp 10145@item --old-group-format=@var{format} 10146These line groups are hunks containing only lines from the first file. 10147The default old group format is the same as the changed group format if 10148it is specified; otherwise it is a format that outputs the line group as-is. 10149 10150@item --new-group-format=@var{format} 10151These line groups are hunks containing only lines from the second 10152file. The default new group format is same as the changed group 10153format if it is specified; otherwise it is a format that outputs the 10154line group as-is. 10155 10156@item --changed-group-format=@var{format} 10157These line groups are hunks containing lines from both files. The 10158default changed group format is the concatenation of the old and new 10159group formats. 10160 10161@item --unchanged-group-format=@var{format} 10162These line groups contain lines common to both files. The default 10163unchanged group format is a format that outputs the line group as-is. 10164@end table 10165 10166In a line group format, ordinary characters represent themselves; 10167conversion specifications start with @samp{%} and have one of the 10168following forms. 10169 10170@table @samp 10171@item %< 10172stands for the lines from the first file, including the trailing newline. 10173Each line is formatted according to the old line format (@pxref{Line formats}). 10174 10175@item %> 10176stands for the lines from the second file, including the trailing newline. 10177Each line is formatted according to the new line format. 10178 10179@item %= 10180stands for the lines common to both files, including the trailing newline. 10181Each line is formatted according to the unchanged line format. 10182 10183@item %% 10184stands for @samp{%}. 10185 10186@item %c'@var{C}' 10187where @var{C} is a single character, stands for @var{C}. 10188@var{C} may not be a backslash or an apostrophe. 10189For example, @samp{%c':'} stands for a colon, even inside 10190the then-part of an if-then-else format, which a colon would 10191normally terminate. 10192 10193@item %c'\@var{O}' 10194where @var{O} is a string of 1, 2, or 3 octal digits, 10195stands for the character with octal code @var{O}. 10196For example, @samp{%c'\0'} stands for a null character. 10197 10198@item @var{F}@var{n} 10199where @var{F} is a @code{printf} conversion specification and @var{n} is one 10200of the following letters, stands for @var{n}'s value formatted with @var{F}. 10201 10202@table @samp 10203@item e 10204The line number of the line just before the group in the old file. 10205 10206@item f 10207The line number of the first line in the group in the old file; 10208equals @var{e} + 1. 10209 10210@item l 10211The line number of the last line in the group in the old file. 10212 10213@item m 10214The line number of the line just after the group in the old file; 10215equals @var{l} + 1. 10216 10217@item n 10218The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 10219 10220@item E, F, L, M, N 10221Likewise, for lines in the new file. 10222 10223@end table 10224 10225The @code{printf} conversion specification can be @samp{%d}, 10226@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 10227lower case hexadecimal, or upper case hexadecimal output 10228respectively. After the @samp{%} the following options can appear in 10229sequence: a @samp{-} specifying left-justification; an integer 10230specifying the minimum field width; and a period followed by an 10231optional integer specifying the minimum number of digits. 10232For example, @samp{%5dN} prints the number of new lines in the group 10233in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 10234 10235@item (@var{A}=@var{B}?@var{T}:@var{E}) 10236If @var{A} equals @var{B} then @var{T} else @var{E}. 10237@var{A} and @var{B} are each either a decimal constant 10238or a single letter interpreted as above. 10239This format spec is equivalent to @var{T} if 10240@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 10241 10242For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 10243@samp{no lines} if @var{N} (the number of lines in the group in the 10244new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 10245otherwise. 10246@end table 10247 10248@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10249@node Line formats 10250@appendixsubsubsec Line formats 10251 10252Line formats control how each line taken from an input file is 10253output as part of a line group in if-then-else format. 10254 10255For example, the following command outputs text with a one-column 10256change indicator to the left of the text. The first column of output 10257is @samp{-} for deleted lines, @samp{|} for added lines, and a space 10258for unchanged lines. The formats contain newline characters where 10259newlines are desired on output. 10260 10261@example 10262cvs diff \ 10263 --old-line-format='-%l 10264' \ 10265 --new-line-format='|%l 10266' \ 10267 --unchanged-line-format=' %l 10268' \ 10269 myfile 10270@end example 10271 10272To specify a line format, use one of the following options. You should 10273quote @var{format}, since it often contains shell metacharacters. 10274 10275@table @samp 10276@item --old-line-format=@var{format} 10277formats lines just from the first file. 10278 10279@item --new-line-format=@var{format} 10280formats lines just from the second file. 10281 10282@item --unchanged-line-format=@var{format} 10283formats lines common to both files. 10284 10285@item --line-format=@var{format} 10286formats all lines; in effect, it sets all three above options simultaneously. 10287@end table 10288 10289In a line format, ordinary characters represent themselves; 10290conversion specifications start with @samp{%} and have one of the 10291following forms. 10292 10293@table @samp 10294@item %l 10295stands for the contents of the line, not counting its trailing 10296newline (if any). This format ignores whether the line is incomplete. 10297 10298@item %L 10299stands for the contents of the line, including its trailing newline 10300(if any). If a line is incomplete, this format preserves its 10301incompleteness. 10302 10303@item %% 10304stands for @samp{%}. 10305 10306@item %c'@var{C}' 10307where @var{C} is a single character, stands for @var{C}. 10308@var{C} may not be a backslash or an apostrophe. 10309For example, @samp{%c':'} stands for a colon. 10310 10311@item %c'\@var{O}' 10312where @var{O} is a string of 1, 2, or 3 octal digits, 10313stands for the character with octal code @var{O}. 10314For example, @samp{%c'\0'} stands for a null character. 10315 10316@item @var{F}n 10317where @var{F} is a @code{printf} conversion specification, 10318stands for the line number formatted with @var{F}. 10319For example, @samp{%.5dn} prints the line number using the 10320@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 10321more about printf conversion specifications. 10322 10323@end table 10324 10325The default line format is @samp{%l} followed by a newline character. 10326 10327If the input contains tab characters and it is important that they line 10328up on output, you should ensure that @samp{%l} or @samp{%L} in a line 10329format is just after a tab stop (e.g.@: by preceding @samp{%l} or 10330@samp{%L} with a tab character), or you should use the @samp{-t} or 10331@samp{--expand-tabs} option. 10332 10333Taken together, the line and line group formats let you specify many 10334different formats. For example, the following command uses a format 10335similar to @code{diff}'s normal format. You can tailor this command 10336to get fine control over @code{diff}'s output. 10337 10338@example 10339cvs diff \ 10340 --old-line-format='< %l 10341' \ 10342 --new-line-format='> %l 10343' \ 10344 --old-group-format='%df%(f=l?:,%dl)d%dE 10345%<' \ 10346 --new-group-format='%dea%dF%(F=L?:,%dL) 10347%>' \ 10348 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 10349%<--- 10350%>' \ 10351 --unchanged-group-format='' \ 10352 myfile 10353@end example 10354 10355@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10356@node diff examples 10357@appendixsubsec diff examples 10358 10359The following line produces a Unidiff (@samp{-u} flag) 10360between revision 1.14 and 1.19 of 10361@file{backend.c}. Due to the @samp{-kk} flag no 10362keywords are substituted, so differences that only depend 10363on keyword substitution are ignored. 10364 10365@example 10366$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 10367@end example 10368 10369Suppose the experimental branch EXPR1 was based on a 10370set of files tagged RELEASE_1_0. To see what has 10371happened on that branch, the following can be used: 10372 10373@example 10374$ cvs diff -r RELEASE_1_0 -r EXPR1 10375@end example 10376 10377A command like this can be used to produce a context 10378diff between two releases: 10379 10380@example 10381$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 10382@end example 10383 10384If you are maintaining ChangeLogs, a command like the following 10385just before you commit your changes may help you write 10386the ChangeLog entry. All local modifications that have 10387not yet been committed will be printed. 10388 10389@example 10390$ cvs diff -u | less 10391@end example 10392 10393@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10394@node export 10395@appendixsec export---Export sources from CVS, similar to checkout 10396@cindex export (subcommand) 10397 10398@itemize @bullet 10399@item 10400Synopsis: export [-flNnR] (-r rev[:date] | -D date) [-k subst] [-d dir] module@dots{} 10401@item 10402Requires: repository. 10403@item 10404Changes: current directory. 10405@end itemize 10406 10407This command is a variant of @code{checkout}; use it 10408when you want a copy of the source for module without 10409the @sc{cvs} administrative directories. For example, you 10410might use @code{export} to prepare source for shipment 10411off-site. This command requires that you specify a 10412date or tag (with @samp{-D} or @samp{-r}), so that you 10413can count on reproducing the source you ship to others 10414(and thus it always prunes empty directories). 10415 10416One often would like to use @samp{-kv} with @code{cvs 10417export}. This causes any keywords to be 10418expanded such that an import done at some other site 10419will not lose the keyword revision information. But be 10420aware that doesn't handle an export containing binary 10421files correctly. Also be aware that after having used 10422@samp{-kv}, one can no longer use the @code{ident} 10423command (which is part of the @sc{rcs} suite---see 10424ident(1)) which looks for keyword strings. If 10425you want to be able to use @code{ident} you must not 10426use @samp{-kv}. 10427 10428@menu 10429* export options:: export options 10430@end menu 10431 10432@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10433@node export options 10434@appendixsubsec export options 10435 10436These standard options are supported by @code{export} 10437(@pxref{Common options}, for a complete description of 10438them): 10439 10440@table @code 10441@item -D @var{date} 10442Use the most recent revision no later than @var{date}. 10443 10444@item -f 10445If no matching revision is found, retrieve the most 10446recent revision (instead of ignoring the file). 10447 10448@item -l 10449Local; run only in current working directory. 10450 10451@item -n 10452Do not run any checkout program. 10453 10454@item -R 10455Export directories recursively. This is on by default. 10456 10457@item -r @var{tag}[:@var{date}] 10458Export the revision specified by @var{tag} or, when @var{date} is specified 10459and @var{tag} is a branch tag, the version from the branch @var{tag} as it 10460existed on @var{date}. See @ref{Common options}. 10461@end table 10462 10463In addition, these options (that are common to 10464@code{checkout} and @code{export}) are also supported: 10465 10466@table @code 10467@item -d @var{dir} 10468Create a directory called @var{dir} for the working 10469files, instead of using the module name. 10470@xref{checkout options}, for complete details on how 10471@sc{cvs} handles this flag. 10472 10473@item -k @var{subst} 10474Set keyword expansion mode (@pxref{Substitution modes}). 10475 10476@item -N 10477Only useful together with @samp{-d @var{dir}}. 10478@xref{checkout options}, for complete details on how 10479@sc{cvs} handles this flag. 10480@end table 10481 10482@ignore 10483@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10484@c @node export examples 10485@appendixsubsec export examples 10486 10487Contributed examples are gratefully accepted. 10488@c -- Examples here!! 10489@end ignore 10490 10491@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10492@node history 10493@appendixsec history---Show status of files and users 10494@cindex history (subcommand) 10495 10496@itemize @bullet 10497@item 10498Synopsis: history [-report] [-flags] [-options args] [files@dots{}] 10499@item 10500Requires: the file @file{$CVSROOT/CVSROOT/history} 10501@item 10502Changes: nothing. 10503@end itemize 10504 10505@sc{cvs} can keep a history log that tracks each use of most @sc{cvs} 10506commands. You can use @code{history} to display this information in 10507various formats. 10508 10509To enable logging, the @samp{LogHistory} config option must be set to 10510some value other than the empty string and the history file specified by 10511the @samp{HistoryLogPath} option must be writable by all users who may run 10512the @sc{cvs} executable (@pxref{config}). 10513 10514To enable the @code{history} command, logging must be enabled as above and 10515the @samp{HistorySearchPath} config option (@pxref{config}) must be set to 10516specify some number of the history logs created thereby and these files must 10517be readable by each user who might run the @code{history} command. 10518 10519Creating a repository via the @code{cvs init} command will enable logging of 10520all possible events to a single history log file 10521(@file{$CVSROOT/CVSROOT/history}) with read and write permissions for all 10522users (@pxref{Creating a repository}). 10523 10524@strong{Note: @code{history} uses @samp{-f}, @samp{-l}, 10525@samp{-n}, and @samp{-p} in ways that conflict with the 10526normal use inside @sc{cvs} (@pxref{Common options}).} 10527 10528@menu 10529* history options:: history options 10530@end menu 10531 10532@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10533@node history options 10534@appendixsubsec history options 10535 10536Several options (shown above as @samp{-report}) control what 10537kind of report is generated: 10538 10539@table @code 10540@item -c 10541Report on each time commit was used (i.e., each time 10542the repository was modified). 10543 10544@item -e 10545Everything (all record types). Equivalent to 10546specifying @samp{-x} with all record types. Of course, 10547@samp{-e} will also include record types which are 10548added in a future version of @sc{cvs}; if you are 10549writing a script which can only handle certain record 10550types, you'll want to specify @samp{-x}. 10551 10552@item -m @var{module} 10553Report on a particular module. (You can meaningfully 10554use @samp{-m} more than once on the command line.) 10555 10556@item -o 10557Report on checked-out modules. This is the default report type. 10558 10559@item -T 10560Report on all tags. 10561 10562@item -x @var{type} 10563Extract a particular set of record types @var{type} from the @sc{cvs} 10564history. The types are indicated by single letters, 10565which you may specify in combination. 10566 10567Certain commands have a single record type: 10568 10569@table @code 10570@item F 10571release 10572@item O 10573checkout 10574@item E 10575export 10576@item T 10577rtag 10578@end table 10579 10580@noindent 10581One of five record types may result from an update: 10582 10583@table @code 10584@item C 10585A merge was necessary but collisions were 10586detected (requiring manual merging). 10587@item G 10588A merge was necessary and it succeeded. 10589@item U 10590A working file was copied from the repository. 10591@item P 10592A working file was patched to match the repository. 10593@item W 10594The working copy of a file was deleted during 10595update (because it was gone from the repository). 10596@end table 10597 10598@noindent 10599One of three record types results from commit: 10600 10601@table @code 10602@item A 10603A file was added for the first time. 10604@item M 10605A file was modified. 10606@item R 10607A file was removed. 10608@end table 10609@end table 10610 10611The options shown as @samp{-flags} constrain or expand 10612the report without requiring option arguments: 10613 10614@table @code 10615@item -a 10616Show data for all users (the default is to show data 10617only for the user executing @code{history}). 10618 10619@item -l 10620Show last modification only. 10621 10622@item -w 10623Show only the records for modifications done from the 10624same working directory where @code{history} is 10625executing. 10626@end table 10627 10628The options shown as @samp{-options @var{args}} constrain the report 10629based on an argument: 10630 10631@table @code 10632@item -b @var{str} 10633Show data back to a record containing the string 10634@var{str} in either the module name, the file name, or 10635the repository path. 10636 10637@item -D @var{date} 10638Show data since @var{date}. This is slightly different 10639from the normal use of @samp{-D @var{date}}, which 10640selects the newest revision older than @var{date}. 10641 10642@item -f @var{file} 10643Show data for a particular file 10644(you can specify several @samp{-f} options on the same command line). 10645This is equivalent to specifying the file on the command line. 10646 10647@item -n @var{module} 10648Show data for a particular module 10649(you can specify several @samp{-n} options on the same command line). 10650 10651@item -p @var{repository} 10652Show data for a particular source repository (you 10653can specify several @samp{-p} options on the same command 10654line). 10655 10656@item -r @var{rev} 10657Show records referring to revisions since the revision 10658or tag named @var{rev} appears in individual @sc{rcs} 10659files. Each @sc{rcs} file is searched for the revision or 10660tag. 10661 10662@item -t @var{tag} 10663Show records since tag @var{tag} was last added to the 10664history file. This differs from the @samp{-r} flag 10665above in that it reads only the history file, not the 10666@sc{rcs} files, and is much faster. 10667 10668@item -u @var{name} 10669Show records for user @var{name}. 10670 10671@item -z @var{timezone} 10672Show times in the selected records using the specified 10673time zone instead of UTC. 10674@end table 10675 10676@ignore 10677@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10678@c @node history examples 10679@appendixsubsec history examples 10680 10681Contributed examples will gratefully be accepted. 10682@c -- Examples here! 10683@end ignore 10684 10685@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10686@node import 10687@appendixsec import---Import sources into CVS, using vendor branches 10688@cindex import (subcommand) 10689 10690@c FIXME: This node is way too long for one which has subnodes. 10691 10692@itemize @bullet 10693@item 10694Synopsis: import [-options] repository vendortag releasetag@dots{} 10695@item 10696Requires: Repository, source distribution directory. 10697@item 10698Changes: repository. 10699@end itemize 10700 10701Use @code{import} to incorporate an entire source 10702distribution from an outside source (e.g., a source 10703vendor) into your source repository directory. You can 10704use this command both for initial creation of a 10705repository, and for wholesale updates to the module 10706from the outside source. @xref{Tracking sources}, for 10707a discussion on this subject. 10708 10709The @var{repository} argument gives a directory name 10710(or a path to a directory) under the @sc{cvs} root directory 10711for repositories; if the directory did not exist, 10712import creates it. 10713 10714When you use import for updates to source that has been 10715modified in your source repository (since a prior 10716import), it will notify you of any files that conflict 10717in the two branches of development; use @samp{checkout 10718-j} to reconcile the differences, as import instructs 10719you to do. 10720 10721If @sc{cvs} decides a file should be ignored 10722(@pxref{cvsignore}), it does not import it and prints 10723@samp{I } followed by the filename (@pxref{import output}, for a 10724complete description of the output). 10725 10726If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 10727any file whose names match the specifications in that 10728file will be treated as packages and the appropriate 10729filtering will be performed on the file/directory 10730before being imported. @xref{Wrappers}. 10731 10732The outside source is saved in a first-level 10733branch, by default 1.1.1. Updates are leaves of this 10734branch; for example, files from the first imported 10735collection of source will be revision 1.1.1.1, then 10736files from the first imported update will be revision 107371.1.1.2, and so on. 10738 10739At least three arguments are required. 10740@var{repository} is needed to identify the collection 10741of source. @var{vendortag} is a tag for the entire 10742branch (e.g., for 1.1.1). You must also specify at 10743least one @var{releasetag} to uniquely identify the files at 10744the leaves created each time you execute @code{import}. The 10745@var{releasetag} should be new, not previously existing in the 10746repository file, and uniquely identify the imported release, 10747 10748@c I'm not completely sure this belongs here. But 10749@c we need to say it _somewhere_ reasonably obvious; it 10750@c is a common misconception among people first learning CVS 10751Note that @code{import} does @emph{not} change the 10752directory in which you invoke it. In particular, it 10753does not set up that directory as a @sc{cvs} working 10754directory; if you want to work with the sources import 10755them first and then check them out into a different 10756directory (@pxref{Getting the source}). 10757 10758@menu 10759* import options:: import options 10760* import output:: import output 10761* import examples:: import examples 10762@end menu 10763 10764@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10765@node import options 10766@appendixsubsec import options 10767 10768This standard option is supported by @code{import} 10769(@pxref{Common options}, for a complete description): 10770 10771@table @code 10772@item -m @var{message} 10773Use @var{message} as log information, instead of 10774invoking an editor. 10775@end table 10776 10777There are the following additional special options. 10778 10779@table @code 10780@item -b @var{branch} 10781See @ref{Multiple vendor branches}. 10782 10783@item -k @var{subst} 10784Indicate the keyword expansion mode desired. This 10785setting will apply to all files created during the 10786import, but not to any files that previously existed in 10787the repository. See @ref{Substitution modes}, for a 10788list of valid @samp{-k} settings. 10789 10790@item -I @var{name} 10791Specify file names that should be ignored during 10792import. You can use this option repeatedly. To avoid 10793ignoring any files at all (even those ignored by 10794default), specify `-I !'. 10795 10796@var{name} can be a file name pattern of the same type 10797that you can specify in the @file{.cvsignore} file. 10798@xref{cvsignore}. 10799@c -- Is this really true? 10800 10801@item -W @var{spec} 10802Specify file names that should be filtered during 10803import. You can use this option repeatedly. 10804 10805@var{spec} can be a file name pattern of the same type 10806that you can specify in the @file{.cvswrappers} 10807file. @xref{Wrappers}. 10808 10809@item -X 10810Modify the algorithm used by @sc{cvs} when importing new files 10811so that new files do not immediately appear on the main trunk. 10812 10813Specifically, this flag causes @sc{cvs} to mark new files as 10814if they were deleted on the main trunk, by taking the following 10815steps for each file in addition to those normally taken on import: 10816creating a new revision on the main trunk indicating that 10817the new file is @code{dead}, resetting the new file's default branch, 10818and placing the file in the Attic (@pxref{Attic}) directory. 10819 10820Use of this option can be forced on a repository-wide basis 10821by setting the @samp{ImportNewFilesToVendorBranchOnly} option in 10822CVSROOT/config (@pxref{config}). 10823@end table 10824 10825@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10826@node import output 10827@appendixsubsec import output 10828 10829@code{import} keeps you informed of its progress by printing a line 10830for each file, preceded by one character indicating the status of the file: 10831 10832@table @code 10833@item U @var{file} 10834The file already exists in the repository and has not been locally 10835modified; a new revision has been created (if necessary). 10836 10837@item N @var{file} 10838The file is a new file which has been added to the repository. 10839 10840@item C @var{file} 10841The file already exists in the repository but has been locally modified; 10842you will have to merge the changes. 10843 10844@item I @var{file} 10845The file is being ignored (@pxref{cvsignore}). 10846 10847@cindex Symbolic link, importing 10848@cindex Link, symbolic, importing 10849@c FIXME: also (somewhere else) probably 10850@c should be documenting what happens if you "cvs add" 10851@c a symbolic link. Also maybe what happens if 10852@c you manually create symbolic links within the 10853@c repository (? - not sure why we'd want to suggest 10854@c doing that). 10855@item L @var{file} 10856The file is a symbolic link; @code{cvs import} ignores symbolic links. 10857People periodically suggest that this behavior should 10858be changed, but if there is a consensus on what it 10859should be changed to, it is not apparent. 10860(Various options in the @file{modules} file can be used 10861to recreate symbolic links on checkout, update, etc.; 10862@pxref{modules}.) 10863@end table 10864 10865@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10866@node import examples 10867@appendixsubsec import examples 10868 10869See @ref{Tracking sources}, and @ref{From files}. 10870 10871@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10872@node init 10873@appendixsec init---Initialize a repository 10874@cindex init (subcommand) 10875 10876@itemize @bullet 10877@item 10878init 10879@item 10880Requires: working directory. 10881@item 10882Changes: repository, working directory. 10883@end itemize 10884 10885The @code{init} command initializes a repository by adding the 10886@file{CVSROOT} subdirectory and some default control files. You must 10887use this command or initialize the repository in some other way before 10888you can use it. Specify the root of the repository with the general 10889@code{-d} option. 10890 10891Note @code{init} will enable history logging; if you don't want that, 10892remove the history file after running @code{init}. 10893 10894@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10895@node init examples 10896@appendixsubsec init examples 10897 10898@example 10899$ cvs -d /usr/local/cvsroot init 10900@end example 10901 10902@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10903@node log 10904@appendixsec log---Print out log information for files 10905@cindex log (subcommand) 10906 10907@itemize @bullet 10908@item 10909Synopsis: log [options] [files@dots{}] 10910@item 10911Requires: repository, working directory. 10912@item 10913Changes: nothing. 10914@end itemize 10915 10916Display log information for files. @code{log} used to 10917call the @sc{rcs} utility @code{rlog}. Although this 10918is no longer true in the current sources, this history 10919determines the format of the output and the options, 10920which are not quite in the style of the other @sc{cvs} 10921commands. 10922 10923@cindex Timezone, in output 10924@cindex Zone, time, in output 10925The output includes the location of the @sc{rcs} file, 10926the @dfn{head} revision (the latest revision on the 10927trunk), all symbolic names (tags) and some other 10928things. For each revision, the revision number, the 10929date, the author, the number of lines added/deleted, the commitid 10930and the log message are printed. All dates are displayed 10931in local time at the client. This is typically specified in 10932the @code{$TZ} environment variable, which can be set to 10933govern how @code{log} displays dates. 10934 10935@strong{Note: @code{log} uses @samp{-R} in a way that conflicts 10936with the normal use inside @sc{cvs} (@pxref{Common options}).} 10937 10938@menu 10939* log options:: log options 10940* log examples:: log examples 10941@end menu 10942 10943@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10944@node log options 10945@appendixsubsec log options 10946 10947By default, @code{log} prints all information that is 10948available. All other options restrict the output. Note that the revision 10949selection options (@code{-d}, @code{-r}, @code{-s}, and @code{-w}) have no 10950effect, other than possibly causing a search for files in Attic directories, 10951when used in conjunction with the options that restrict the output to only 10952@code{log} header fields (@code{-b}, @code{-h}, @code{-R}, and @code{-t}) 10953unless the @code{-S} option is also specified. 10954 10955@table @code 10956@item -b 10957Print information about the revisions on the default 10958branch, normally the highest branch on the trunk. 10959 10960@item -d @var{dates} 10961Print information about revisions with a checkin 10962date/time in the range given by the 10963semicolon-separated list of dates. The date formats 10964accepted are those accepted by the @samp{-D} option to 10965many other @sc{cvs} commands (@pxref{Common options}). 10966Dates can be combined into ranges as follows: 10967 10968@c Should we be thinking about accepting ISO8601 10969@c ranges? For example "1972-09-10/1972-09-12". 10970@table @code 10971@item @var{d1}<@var{d2} 10972@itemx @var{d2}>@var{d1} 10973Select the revisions that were deposited between 10974@var{d1} and @var{d2}. 10975 10976@item <@var{d} 10977@itemx @var{d}> 10978Select all revisions dated @var{d} or earlier. 10979 10980@item @var{d}< 10981@itemx >@var{d} 10982Select all revisions dated @var{d} or later. 10983 10984@item @var{d} 10985Select the single, latest revision dated @var{d} or 10986earlier. 10987@end table 10988 10989The @samp{>} or @samp{<} characters may be followed by 10990@samp{=} to indicate an inclusive range rather than an 10991exclusive one. 10992 10993Note that the separator is a semicolon (;). 10994 10995@item -h 10996Print only the name of the @sc{rcs} file, name 10997of the file in the working directory, head, 10998default branch, access list, locks, symbolic names, and 10999suffix. 11000 11001@item -l 11002Local; run only in current working directory. (Default 11003is to run recursively). 11004 11005@item -N 11006Do not print the list of tags for this file. This 11007option can be very useful when your site uses a lot of 11008tags, so rather than "more"'ing over 3 pages of tag 11009information, the log information is presented without 11010tags at all. 11011 11012@item -R 11013Print only the name of the @sc{rcs} file. 11014 11015@c Note that using a bare revision (in addition to not 11016@c being explicitly documented here) is potentially 11017@c confusing; it shows the log message to get from the 11018@c previous revision to that revision. "-r1.3 -r1.6" 11019@c (equivalent to "-r1.3,1.6") is even worse; it 11020@c prints the messages to get from 1.2 to 1.3 and 1.5 11021@c to 1.6. By analogy with "cvs diff", users might 11022@c expect that it is more like specifying a range. 11023@c It is not 100% clear to me how much of this should 11024@c be documented (for example, multiple -r options 11025@c perhaps could/should be deprecated given the false 11026@c analogy with "cvs diff"). 11027@c In general, this section should be rewritten to talk 11028@c about messages to get from revision rev1 to rev2, 11029@c rather than messages for revision rev2 (that is, the 11030@c messages are associated with a change not a static 11031@c revision and failing to make this distinction causes 11032@c much confusion). 11033@item -r@var{revisions} 11034Print information about revisions given in the 11035comma-separated list @var{revisions} of revisions and 11036ranges. The following table explains the available 11037range formats: 11038 11039@table @code 11040@item @var{rev1}:@var{rev2} 11041Revisions @var{rev1} to @var{rev2} (which must be on 11042the same branch). 11043 11044@item @var{rev1}::@var{rev2} 11045The same, but excluding @var{rev1}. 11046 11047@item :@var{rev} 11048@itemx ::@var{rev} 11049Revisions from the beginning of the branch up to 11050and including @var{rev}. 11051 11052@item @var{rev}: 11053Revisions starting with @var{rev} to the end of the 11054branch containing @var{rev}. 11055 11056@item @var{rev}:: 11057Revisions starting just after @var{rev} to the end of the 11058branch containing @var{rev}. 11059 11060@item @var{branch} 11061An argument that is a branch means all revisions on 11062that branch. 11063 11064@item @var{branch1}:@var{branch2} 11065@itemx @var{branch1}::@var{branch2} 11066A range of branches means all revisions 11067on the branches in that range. 11068 11069@item @var{branch}. 11070The latest revision in @var{branch}. 11071@end table 11072 11073A bare @samp{-r} with no revisions means the latest 11074revision on the default branch, normally the trunk. 11075There can be no space between the @samp{-r} option and 11076its argument. 11077 11078@item -S 11079Suppress the header if no revisions are selected. 11080 11081@item -s @var{states} 11082Print information about revisions whose state 11083attributes match one of the states given in the 11084comma-separated list @var{states}. Individual states may 11085be any text string, though @sc{cvs} commonly only uses two 11086states, @samp{Exp} and @samp{dead}. See @ref{admin options} 11087for more information. 11088 11089@item -t 11090Print the same as @samp{-h}, plus the descriptive text. 11091 11092@item -w@var{logins} 11093Print information about revisions checked in by users 11094with login names appearing in the comma-separated list 11095@var{logins}. If @var{logins} is omitted, the user's 11096login is assumed. There can be no space between the 11097@samp{-w} option and its argument. 11098@end table 11099 11100@code{log} prints the intersection of the revisions 11101selected with the options @samp{-d}, @samp{-s}, and 11102@samp{-w}, intersected with the union of the revisions 11103selected by @samp{-b} and @samp{-r}. 11104 11105@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11106@node log examples 11107@appendixsubsec log examples 11108 11109@cindex Timezone, in output 11110@cindex Zone, time, in output 11111Since @code{log} shows dates in local time, 11112you might want to see them in Coordinated Universal Time (UTC) or 11113some other timezone. 11114To do this you can set your @code{$TZ} environment 11115variable before invoking @sc{cvs}: 11116 11117@example 11118$ TZ=UTC cvs log foo.c 11119$ TZ=EST cvs log bar.c 11120@end example 11121 11122(If you are using a @code{csh}-style shell, like @code{tcsh}, 11123you would need to prefix the examples above with @code{env}.) 11124 11125@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11126@node ls & rls 11127@appendixsec ls & rls 11128@cindex ls (subcommand) 11129@cindex rls (subcommand) 11130 11131@itemize @bullet 11132@item 11133ls [-e | -l] [-RP] [-r tag[:date]] [-D date] [path@dots{}] 11134@item 11135Requires: repository for @code{rls}, repository & working directory for 11136@code{ls}. 11137@item 11138Changes: nothing. 11139@item 11140Synonym: @code{dir} & @code{list} are synonyms for @code{ls} and @code{rdir} 11141& @code{rlist} are synonyms for @code{rls}. 11142@end itemize 11143 11144The @code{ls} and @code{rls} commands are used to list 11145files and directories in the repository. 11146 11147By default @code{ls} lists the files and directories 11148that belong in your working directory, what would be 11149there after an @code{update}. 11150 11151By default @code{rls} lists the files and directories 11152on the tip of the trunk in the topmost directory of the 11153repository. 11154 11155Both commands accept an optional list of file and 11156directory names, relative to the working directory for 11157@code{ls} and the topmost directory of the repository 11158for @code{rls}. Neither is recursive by default. 11159 11160@menu 11161* ls & rls options:: ls & rls options 11162* rls examples: rls examples 11163@end menu 11164 11165@node ls & rls options 11166@appendixsubsec ls & rls options 11167 11168These standard options are supported by @code{ls} & @code{rls}: 11169 11170@table @code 11171@item -d 11172Show dead revisions (with tag when specified). 11173 11174@item -e 11175Display in CVS/Entries format. This format is meant to remain easily parsable 11176by automation. 11177 11178@item -l 11179Display all details. 11180 11181@item -P 11182Don't list contents of empty directories when recursing. 11183 11184@item -R 11185List recursively. 11186 11187@item -r @var{tag}[:@var{date}] 11188Show files specified by @var{tag} or, when @var{date} is specified 11189and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11190existed on @var{date}. See @ref{Common options}. 11191 11192@item -D @var{date} 11193Show files from date. 11194@end table 11195 11196@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11197@node rls examples 11198@appendixsubsec rls examples 11199 11200@example 11201$ cvs rls 11202cvs rls: Listing module: `.' 11203CVSROOT 11204first-dir 11205@end example 11206 11207@example 11208$ cvs rls CVSROOT 11209cvs rls: Listing module: `CVSROOT' 11210checkoutlist 11211commitinfo 11212config 11213cvswrappers 11214loginfo 11215modules 11216notify 11217rcsinfo 11218taginfo 11219verifymsg 11220 11221@end example 11222 11223@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11224@node rdiff 11225@appendixsec rdiff---'patch' format diffs between releases 11226@cindex rdiff (subcommand) 11227 11228@itemize @bullet 11229@item 11230rdiff [-flags] [-V vn] (-r tag1[:date1] | -D date1) [-r tag2[:date2] | -D date2] modules@dots{} 11231@item 11232Requires: repository. 11233@item 11234Changes: nothing. 11235@item 11236Synonym: patch 11237@end itemize 11238 11239Builds a Larry Wall format patch(1) file between two 11240releases, that can be fed directly into the @code{patch} 11241program to bring an old release up-to-date with the new 11242release. (This is one of the few @sc{cvs} commands that 11243operates directly from the repository, and doesn't 11244require a prior checkout.) The diff output is sent to 11245the standard output device. 11246 11247You can specify (using the standard @samp{-r} and 11248@samp{-D} options) any combination of one or two 11249revisions or dates. If only one revision or date is 11250specified, the patch file reflects differences between 11251that revision or date and the current head revisions in 11252the @sc{rcs} file. 11253 11254Note that if the software release affected is contained 11255in more than one directory, then it may be necessary to 11256specify the @samp{-p} option to the @code{patch} command when 11257patching the old sources, so that @code{patch} is able to find 11258the files that are located in other directories. 11259 11260@menu 11261* rdiff options:: rdiff options 11262* rdiff examples:: rdiff examples 11263@end menu 11264 11265@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11266@node rdiff options 11267@appendixsubsec rdiff options 11268 11269These standard options are supported by @code{rdiff} 11270(@pxref{Common options}, for a complete description of 11271them): 11272 11273@table @code 11274@item -D @var{date} 11275Use the most recent revision no later than @var{date}. 11276 11277@item -f 11278If no matching revision is found, retrieve the most 11279recent revision (instead of ignoring the file). 11280 11281@item -k @var{kflag} 11282Process keywords according to @var{kflag}. See 11283@ref{Keyword substitution}. 11284 11285@item -l 11286Local; don't descend subdirectories. 11287 11288@item -p 11289Show which C function each change is in. 11290 11291@item -R 11292Examine directories recursively. This option is on by default. 11293 11294@item -r @var{tag} 11295Use the revision specified by @var{tag}, or when @var{date} is specified 11296and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11297existed on @var{date}. See @ref{Common options}. 11298@end table 11299 11300In addition to the above, these options are available: 11301 11302@table @code 11303@item -c 11304Use the context diff format. This is the default format. 11305 11306@item -s 11307Create a summary change report instead of a patch. The 11308summary includes information about files that were 11309changed or added between the releases. It is sent to 11310the standard output device. This is useful for finding 11311out, for example, which files have changed between two 11312dates or revisions. 11313 11314@item -t 11315A diff of the top two revisions is sent to the standard 11316output device. This is most useful for seeing what the 11317last change to a file was. 11318 11319@item -u 11320Use the unidiff format for the context diffs. 11321Remember that old versions 11322of the @code{patch} program can't handle the unidiff 11323format, so if you plan to post this patch to the net 11324you should probably not use @samp{-u}. 11325 11326@item -V @var{vn} 11327Expand keywords according to the rules current in 11328@sc{rcs} version @var{vn} (the expansion format changed with 11329@sc{rcs} version 5). Note that this option is no 11330longer accepted. @sc{cvs} will always expand keywords the 11331way that @sc{rcs} version 5 does. 11332@end table 11333 11334@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11335@node rdiff examples 11336@appendixsubsec rdiff examples 11337 11338Suppose you receive mail from @t{foo@@example.net} asking for an 11339update from release 1.2 to 1.4 of the tc compiler. You 11340have no such patches on hand, but with @sc{cvs} that can 11341easily be fixed with a command such as this: 11342 11343@example 11344$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 11345$$ Mail -s 'The patches you asked for' foo@@example.net 11346@end example 11347 11348Suppose you have made release 1.3, and forked a branch 11349called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1} 11350corresponds to release 1.3.1, which was made some time 11351ago. Now, you want to see how much development has been 11352done on the branch. This command can be used: 11353 11354@example 11355$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 11356cvs rdiff: Diffing module-name 11357File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 11358File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 11359File bar.h,v changed from revision 1.29.2.1 to 1.2 11360@end example 11361 11362@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11363@node release 11364@appendixsec release---Indicate that a Module is no longer in use 11365@cindex release (subcommand) 11366 11367@itemize @bullet 11368@item 11369release [-d] directories@dots{} 11370@item 11371Requires: Working directory. 11372@item 11373Changes: Working directory, history log. 11374@end itemize 11375 11376This command is meant to safely cancel the effect of 11377@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it 11378isn't strictly necessary to use this command. You can 11379always simply delete your working directory, if you 11380like; but you risk losing changes you may have 11381forgotten, and you leave no trace in the @sc{cvs} history 11382file (@pxref{history file}) that you've abandoned your 11383checkout. 11384 11385Use @samp{cvs release} to avoid these problems. This 11386command checks that no uncommitted changes are 11387present; that you are executing it from immediately 11388above a @sc{cvs} working directory; and that the repository 11389recorded for your files is the same as the repository 11390defined in the module database. 11391 11392If all these conditions are true, @samp{cvs release} 11393leaves a record of its execution (attesting to your 11394intentionally abandoning your checkout) in the @sc{cvs} 11395history log. 11396 11397@menu 11398* release options:: release options 11399* release output:: release output 11400* release examples:: release examples 11401@end menu 11402 11403@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11404@node release options 11405@appendixsubsec release options 11406 11407The @code{release} command supports one command option: 11408 11409@table @code 11410@item -d 11411Delete your working copy of the file if the release 11412succeeds. If this flag is not given your files will 11413remain in your working directory. 11414 11415@strong{WARNING: The @code{release} command deletes 11416all directories and files recursively. This 11417has the very serious side-effect that any directory 11418that you have created inside your checked-out sources, 11419and not added to the repository (using the @code{add} 11420command; @pxref{Adding files}) will be silently deleted---even 11421if it is non-empty!} 11422@end table 11423 11424@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11425@node release output 11426@appendixsubsec release output 11427 11428Before @code{release} releases your sources it will 11429print a one-line message for any file that is not 11430up-to-date. 11431 11432@table @code 11433@item U @var{file} 11434@itemx P @var{file} 11435There exists a newer revision of this file in the 11436repository, and you have not modified your local copy 11437of the file (@samp{U} and @samp{P} mean the same thing). 11438 11439@item A @var{file} 11440The file has been added to your private copy of the 11441sources, but has not yet been committed to the 11442repository. If you delete your copy of the sources 11443this file will be lost. 11444 11445@item R @var{file} 11446The file has been removed from your private copy of the 11447sources, but has not yet been removed from the 11448repository, since you have not yet committed the 11449removal. @xref{commit}. 11450 11451@item M @var{file} 11452The file is modified in your working directory. There 11453might also be a newer revision inside the repository. 11454 11455@item ? @var{file} 11456@var{file} is in your working directory, but does not 11457correspond to anything in the source repository, and is 11458not in the list of files for @sc{cvs} to ignore (see the 11459description of the @samp{-I} option, and 11460@pxref{cvsignore}). If you remove your working 11461sources, this file will be lost. 11462@end table 11463 11464@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11465@node release examples 11466@appendixsubsec release examples 11467 11468Release the @file{tc} directory, and delete your local working copy 11469of the files. 11470 11471@example 11472$ cd .. # @r{You must stand immediately above the} 11473 # @r{sources when you issue @samp{cvs release}.} 11474$ cvs release -d tc 11475You have [0] altered files in this repository. 11476Are you sure you want to release (and delete) directory `tc': y 11477$ 11478@end example 11479 11480@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11481@node remove 11482@appendixsec remove---Remove files from active use 11483@cindex remove (subcommand) 11484 11485@itemize @bullet 11486@item 11487Synopsis: remove [-flR] [files...] 11488@item 11489Requires: repository, working directory. 11490@item 11491Changes: working directory. 11492@end itemize 11493 11494The @code{remove} command is used to remove unwanted 11495files from active use. The user normally deletes the 11496files from the working directory prior to invocation 11497of the @code{remove} command. Only the working 11498directory is updated. Changes to the repository are 11499not made until the @code{commit} command is run. 11500 11501The @code{remove} command does not delete files from 11502from the repository. @sc{cvs} keeps all historical 11503data in the repository so that it is possible to 11504reconstruct previous states of the projects under 11505revision control. 11506 11507To undo @sc{cvs} @code{remove} or to resurrect files 11508that were previously removed, @xref{add}. 11509 11510@menu 11511* remove options:: remove options 11512* remove examples:: remove examples 11513@end menu 11514 11515@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11516@node remove options 11517@appendixsubsec remove options 11518 11519These standard options are supported by @code{remove} 11520(@pxref{Common options} for a complete description of 11521them): 11522 11523@table @code 11524@item -l 11525Local; run only in current working directory. See @ref{Recursive behavior}. 11526 11527@item -R 11528Process directories recursively. See @ref{Recursive behavior}. 11529 11530@end table 11531 11532In addition, these options are also supported: 11533 11534@table @code 11535@item -f 11536Note that this is not the standard behavior of 11537the @samp{-f} option as defined in @ref{Common options}. 11538 11539Delete files before removing them. 11540 11541Entire directory hierarchies are easily removed 11542using @samp{-f}, but take note that it is not as 11543easy to resurrect directory hierarchies as it is 11544to remove them. 11545 11546@end table 11547 11548@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11549@node remove examples 11550@appendixsubsec remove examples 11551 11552@appendixsubsubsec Removing a file 11553 11554@example 11555$ cvs remove remove.me 11556cvs remove: file `remove.me' still in working directory 11557cvs remove: 1 file exists; remove it first 11558$ rm -f remove.me 11559$ cvs remove remove.me 11560cvs remove: scheduling `remove.me' for removal 11561cvs remove: use 'cvs commit' to remove this file permanently 11562 11563$ ls remove.it 11564remove.it 11565$ cvs remove -f remove.it 11566cvs remove: scheduling `remove.it' for removal 11567cvs remove: use 'cvs commit' to remove this file permanently 11568@end example 11569 11570@appendixsubsubsec Removing entire directories 11571@example 11572$ tree -d a 11573a 11574|-- CVS 11575`-- b 11576 `-- CVS 11577 115783 directories 11579$ cvs remove -f a 11580cvs remove: Removing a 11581cvs remove: Removing a/b 11582cvs remove: scheduling `a/b/c' for removal 11583cvs remove: use 'cvs commit' to remove this file permanently 11584@end example 11585 11586@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11587@node server & pserver 11588@appendixsec server & pserver---Act as a server for a client on stdin/stdout 11589@cindex pserver (subcommand) 11590@cindex server (subcommand) 11591 11592@itemize @bullet 11593@item 11594pserver [-c path] 11595 11596server [-c path] 11597@item 11598Requires: repository, client conversation on stdin/stdout 11599@item 11600Changes: Repository or, indirectly, client working directory. 11601@end itemize 11602 11603The @sc{cvs} @code{server} and @code{pserver} commands are used to provide 11604repository access to remote clients and expect a client conversation on 11605stdin & stdout. Typically these commands are launched from @code{inetd} or 11606via @code{ssh} (@pxref{Remote repositories}). 11607 11608@code{server} expects that the client has already been authenticated somehow, 11609typically via @sc{ssh}, and @code{pserver} attempts to authenticate the client 11610itself. 11611 11612Only one option is available with the @code{server} and @code{pserver} 11613commands: 11614 11615@cindex configuration file 11616@table @code 11617@item -c path 11618Load configuration from @var{path} rather than the default location 11619@file{$CVSROOT/CVSROOT/config} (@pxref{config}). @var{path} must be 11620@file{/etc/cvs.conf} or prefixed by @file{/etc/cvs/}. This option is 11621supported beginning with @sc{cvs} release 1.12.13. 11622@end table 11623 11624@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11625@node update 11626@appendixsec update---Bring work tree in sync with repository 11627@cindex update (subcommand) 11628 11629@itemize @bullet 11630@item 11631update [-ACdflPpRt] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag[:date] | -D date] [-W spec] files@dots{} 11632@item 11633Requires: repository, working directory. 11634@item 11635Changes: working directory. 11636@end itemize 11637 11638After you've run @code{checkout} to create your private copy 11639of source from the common repository, other developers 11640will continue changing the central source. From time 11641to time, when it is convenient in your development 11642process, you can use the @code{update} command from 11643within your working directory to reconcile your work 11644with any revisions applied to the source repository 11645since your last checkout or update. Without the @code{-C} 11646option, @code{update} will also merge any differences 11647between the local copy of files and their base revisions 11648into any destination revisions specified with @code{-r}, 11649@code{-D}, or @code{-A}. 11650 11651@menu 11652* update options:: update options 11653* update output:: update output 11654@end menu 11655 11656@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11657@node update options 11658@appendixsubsec update options 11659 11660These standard options are available with @code{update} 11661(@pxref{Common options}, for a complete description of 11662them): 11663 11664@table @code 11665@item -D date 11666Use the most recent revision no later than @var{date}. 11667This option is sticky, and implies @samp{-P}. 11668See @ref{Sticky tags}, for more information on sticky tags/dates. 11669 11670@item -f 11671Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision 11672is found, retrieve the most recent revision (instead of ignoring the file). 11673 11674@item -k @var{kflag} 11675Process keywords according to @var{kflag}. See 11676@ref{Keyword substitution}. 11677This option is sticky; future updates of 11678this file in this working directory will use the same 11679@var{kflag}. The @code{status} command can be viewed 11680to see the sticky options. See @ref{Invoking CVS}, for 11681more information on the @code{status} command. 11682 11683@item -l 11684Local; run only in current working directory. @xref{Recursive behavior}. 11685 11686@item -P 11687Prune empty directories. See @ref{Moving directories}. 11688 11689@item -p 11690Pipe files to the standard output. 11691 11692@item -R 11693Update directories recursively (default). @xref{Recursive 11694behavior}. 11695 11696@item -r @var{tag}[:@var{date}] 11697Retrieve the revisions specified by @var{tag} or, when @var{date} is specified 11698and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11699existed on @var{date}. This option is sticky, and implies @samp{-P}. 11700See @ref{Sticky tags}, for more information on sticky tags/dates. Also 11701see @ref{Common options}. 11702 11703@item -t 11704Preserve source timestamps. Unlike @code{checkout}, where files are created 11705using the original timestamp of the file in the repository, @code{update} 11706updates files using the current time of the machine. This is convenient 11707because updated files appear newer than any other files on the system so 11708@code{make(1)} knows that their corresponding built artifacts are out of date 11709and they will get rebuilt. The @samp{-t} flag instead preserves the timestamps 11710of the original repository files, behaving exactly like @code{checkout}. 11711This is useful for maintaining a tree in the original checked-out state. 11712@end table 11713 11714@need 800 11715These special options are also available with 11716@code{update}. 11717 11718@table @code 11719@item -A 11720Reset any sticky tags, dates, or @samp{-k} options. 11721See @ref{Sticky tags}, for more information on sticky tags/dates. 11722 11723@item -C 11724Overwrite locally modified files with clean copies from 11725the repository (the modified file is saved in 11726@file{.#@var{file}.@var{revision}}, however). 11727 11728@item -d 11729Create any directories that exist in the repository if 11730they're missing from the working directory. Normally, 11731@code{update} acts only on directories and files that 11732were already enrolled in your working directory. 11733 11734This is useful for updating directories that were 11735created in the repository since the initial checkout; 11736but it has an unfortunate side effect. If you 11737deliberately avoided certain directories in the 11738repository when you created your working directory 11739(either through use of a module name or by listing 11740explicitly the files and directories you wanted on the 11741command line), then updating with @samp{-d} will create 11742those directories, which may not be what you want. 11743 11744@item -I @var{name} 11745Ignore files whose names match @var{name} (in your 11746working directory) during the update. You can specify 11747@samp{-I} more than once on the command line to specify 11748several files to ignore. Use @samp{-I !} to avoid 11749ignoring any files at all. @xref{cvsignore}, for other 11750ways to make @sc{cvs} ignore some files. 11751 11752@item -W@var{spec} 11753Specify file names that should be filtered during 11754update. You can use this option repeatedly. 11755 11756@var{spec} can be a file name pattern of the same type 11757that you can specify in the @file{.cvswrappers} 11758file. @xref{Wrappers}. 11759 11760@item -j@var{revision} 11761With two @samp{-j} options, merge changes from the 11762revision specified with the first @samp{-j} option to 11763the revision specified with the second @samp{j} option, 11764into the working directory. 11765 11766With one @samp{-j} option, merge changes from the 11767ancestor revision to the revision specified with the 11768@samp{-j} option, into the working directory. The 11769ancestor revision is the common ancestor of the 11770revision which the working directory is based on, and 11771the revision specified in the @samp{-j} option. 11772 11773Note that using a single @samp{-j @var{tagname}} option rather than 11774@samp{-j @var{branchname}} to merge changes from a branch will 11775often not remove files which were removed on the branch. 11776@xref{Merging adds and removals}, for more. 11777 11778In addition, each @samp{-j} option can contain an optional 11779date specification which, when used with branches, can 11780limit the chosen revision to one within a specific 11781date. An optional date is specified by adding a colon 11782(:) to the tag: 11783@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 11784 11785@xref{Branching and merging}. 11786 11787@end table 11788 11789@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11790@node update output 11791@appendixsubsec update output 11792 11793@code{update} and @code{checkout} keep you informed of 11794their progress by printing a line for each file, preceded 11795by one character indicating the status of the file: 11796 11797@table @code 11798@item U @var{file} 11799The file was brought up to date with respect to the 11800repository. This is done for any file that exists in 11801the repository but not in your working directory, and for files 11802that you haven't changed but are not the most recent 11803versions available in the repository. 11804 11805@item P @var{file} 11806Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 11807file. This accomplishes the same thing as @samp{U} using less bandwidth. 11808 11809@item A @var{file} 11810The file has been added to your private copy of the 11811sources, and will be added to the source repository 11812when you run @code{commit} on the file. This is a 11813reminder to you that the file needs to be committed. 11814 11815@item R @var{file} 11816The file has been removed from your private copy of the 11817sources, and will be removed from the source repository 11818when you run @code{commit} on the file. This is a 11819reminder to you that the file needs to be committed. 11820 11821@item M @var{file} 11822The file is modified in your working directory. 11823 11824@samp{M} can indicate one of two states for a file 11825you're working on: either there were no modifications 11826to the same file in the repository, so that your file 11827remains as you last saw it; or there were modifications 11828in the repository as well as in your copy, but they 11829were merged successfully, without conflict, in your 11830working directory. 11831 11832@sc{cvs} will print some messages if it merges your work, 11833and a backup copy of your working file (as it looked 11834before you ran @code{update}) will be made. The exact 11835name of that file is printed while @code{update} runs. 11836 11837@item C @var{file} 11838@cindex .# files 11839@cindex __ files (VMS) 11840A conflict was detected while trying to merge your 11841changes to @var{file} with changes from the source 11842repository. @var{file} (the copy in your working 11843directory) is now the result of attempting to merge 11844the two revisions; an unmodified copy of your file 11845is also in your working directory, with the name 11846@file{.#@var{file}.@var{revision}} where @var{revision} 11847is the revision that your modified file started 11848from. Resolve the conflict as described in 11849@ref{Conflicts example}. 11850@c "some systems" as in out-of-the-box OSes? Not as 11851@c far as I know. We need to advise sysadmins as well 11852@c as users how to set up this kind of purge, if that is 11853@c what they want. 11854@c We also might want to think about cleaner solutions, 11855@c like having CVS remove the .# file once the conflict 11856@c has been resolved or something like that. 11857(Note that some systems automatically purge 11858files that begin with @file{.#} if they have not been 11859accessed for a few days. If you intend to keep a copy 11860of your original file, it is a very good idea to rename 11861it.) Under @sc{vms}, the file name starts with 11862@file{__} rather than @file{.#}. 11863 11864@item ? @var{file} 11865@var{file} is in your working directory, but does not 11866correspond to anything in the source repository, and is 11867not in the list of files for @sc{cvs} to ignore (see the 11868description of the @samp{-I} option, and 11869@pxref{cvsignore}). 11870@end table 11871 11872@c ----- END MAN 1 ----- 11873@c --------------------------------------------------------------------- 11874@node Invoking CVS 11875@appendix Quick reference to CVS commands 11876@cindex Command reference 11877@cindex Reference, commands 11878@cindex Invoking CVS 11879 11880This appendix describes how to invoke @sc{cvs}, with 11881references to where each command or feature is 11882described in detail. For other references run the 11883@code{cvs --help} command, or see @ref{Index}. 11884 11885A @sc{cvs} command looks like: 11886 11887@example 11888cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 11889@end example 11890 11891Global options: 11892 11893@table @code 11894@item --allow-root=@var{rootdir} 11895Specify legal @sc{cvsroot} directory (server only) (not 11896in @sc{cvs} 1.9 and older). See @ref{Password 11897authentication server}. 11898 11899@item -a 11900Authenticate all communication (client only) (not in @sc{cvs} 119011.9 and older). See @ref{Global options}. 11902 11903@item -b 11904Specify RCS location (@sc{cvs} 1.9 and older). See 11905@ref{Global options}. 11906 11907@item -d @var{root} 11908Specify the @sc{cvsroot}. See @ref{Repository}. 11909 11910@item -e @var{editor} 11911Edit messages with @var{editor}. See @ref{Committing 11912your changes}. 11913 11914@item -f 11915Do not read the @file{~/.cvsrc} file. See @ref{Global 11916options}. 11917 11918@item -H 11919@itemx --help 11920Print a help message. See @ref{Global options}. 11921 11922@item -n 11923Do not change any files. See @ref{Global options}. 11924 11925@item -Q 11926Be really quiet. See @ref{Global options}. 11927 11928@item -q 11929Be somewhat quiet. See @ref{Global options}. 11930 11931@item -r 11932Make new working files read-only. See @ref{Global options}. 11933 11934@item -s @var{variable}=@var{value} 11935Set a user variable. See @ref{Variables}. 11936 11937@item -T @var{tempdir} 11938Put temporary files in @var{tempdir}. See @ref{Global 11939options}. 11940 11941@item -t 11942Trace @sc{cvs} execution. See @ref{Global options}. 11943 11944@item -v 11945@item --version 11946Display version and copyright information for @sc{cvs}. 11947 11948@item -w 11949Make new working files read-write. See @ref{Global 11950options}. 11951 11952@item -x 11953Encrypt all communication (client only). 11954See @ref{Global options}. 11955 11956@item -z @var{gzip-level} 11957@cindex Compression 11958@cindex Gzip 11959Set the compression level (client only). 11960See @ref{Global options}. 11961@end table 11962 11963Keyword expansion modes (@pxref{Substitution modes}): 11964 11965@example 11966-kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 11967-kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11968-kk $@splitrcskeyword{Id}$ 11969-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 11970-ko @i{no expansion} 11971-kb @i{no expansion, file is binary} 11972@end example 11973 11974Keywords (@pxref{Keyword list}): 11975 11976@example 11977$@splitrcskeyword{Author}: joe $ 11978$@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ 11979$@splitrcskeyword{CVSHeader}: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11980$@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11981$@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11982$@splitrcskeyword{Locker}: harry $ 11983$@splitrcskeyword{Name}: snapshot_1_14 $ 11984$@splitrcskeyword{RCSfile}: file1,v $ 11985$@splitrcskeyword{Revision}: 1.1 $ 11986$@splitrcskeyword{Source}: /home/files/file1,v $ 11987$@splitrcskeyword{State}: Exp $ 11988$@splitrcskeyword{Log}: file1,v $ 11989Revision 1.1 1993/12/09 03:30:17 joe 11990Initial revision 11991 11992@end example 11993 11994@c The idea behind this table is that we want each item 11995@c to be a sentence or two at most. Preferably a 11996@c single line. 11997@c 11998@c In some cases refs to "foo options" are just to get 11999@c this thing written quickly, not because the "foo 12000@c options" node is really the best place to point. 12001Commands, command options, and command arguments: 12002 12003@table @code 12004@c ------------------------------------------------------------ 12005@item add [@var{options}] [@var{files}@dots{}] 12006Add a new file/directory. See @ref{Adding files}. 12007 12008@table @code 12009@item -k @var{kflag} 12010Set keyword expansion. 12011 12012@item -m @var{msg} 12013Set file description. 12014@end table 12015 12016@c ------------------------------------------------------------ 12017@item admin [@var{options}] [@var{files}@dots{}] 12018Administration of history files in the repository. See 12019@ref{admin}. 12020@c This list omits those options which are not 12021@c documented as being useful with CVS. That might be 12022@c a mistake... 12023 12024@table @code 12025@item -b[@var{rev}] 12026Set default branch. See @ref{Reverting local changes}. 12027 12028@item -c@var{string} 12029Set comment leader. 12030 12031@item -k@var{subst} 12032Set keyword substitution. See @ref{Keyword 12033substitution}. 12034 12035@item -l[@var{rev}] 12036Lock revision @var{rev}, or latest revision. 12037 12038@item -m@var{rev}:@var{msg} 12039Replace the log message of revision @var{rev} with 12040@var{msg}. 12041 12042@item -o@var{range} 12043Delete revisions from the repository. See 12044@ref{admin options}. 12045 12046@item -q 12047Run quietly; do not print diagnostics. 12048 12049@item -s@var{state}[:@var{rev}] 12050Set the state. See @ref{admin options} for more information on possible 12051states. 12052 12053@c Does not work for client/server CVS 12054@item -t 12055Set file description from standard input. 12056 12057@item -t@var{file} 12058Set file description from @var{file}. 12059 12060@item -t-@var{string} 12061Set file description to @var{string}. 12062 12063@item -u[@var{rev}] 12064Unlock revision @var{rev}, or latest revision. 12065@end table 12066 12067@c ------------------------------------------------------------ 12068@item annotate [@var{options}] [@var{files}@dots{}] 12069Show last revision where each line was modified. See 12070@ref{annotate}. 12071 12072@table @code 12073@item -D @var{date} 12074Annotate the most recent revision no later than 12075@var{date}. See @ref{Common options}. 12076 12077@item -F 12078Force annotation of binary files. (Without this option, 12079binary files are skipped with a message.) 12080 12081@item -f 12082Use head revision if tag/date not found. See 12083@ref{Common options}. 12084 12085@item -l 12086Local; run only in current working directory. @xref{Recursive behavior}. 12087 12088@item -R 12089Operate recursively (default). @xref{Recursive 12090behavior}. 12091 12092@item -r @var{tag}[:@var{date}] 12093Annotate revisions specified by @var{tag} or, when @var{date} is specified 12094and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12095existed on @var{date}. See @ref{Common options}. 12096@end table 12097 12098@c ------------------------------------------------------------ 12099@item checkout [@var{options}] @var{modules}@dots{} 12100Get a copy of the sources. See @ref{checkout}. 12101 12102@table @code 12103@item -A 12104Reset any sticky tags/date/options. See @ref{Sticky 12105tags} and @ref{Keyword substitution}. 12106 12107@item -c 12108Output the module database. See @ref{checkout options}. 12109 12110@item -D @var{date} 12111Check out revisions as of @var{date} (is sticky). See 12112@ref{Common options}. 12113 12114@item -d @var{dir} 12115Check out into @var{dir}. See @ref{checkout options}. 12116 12117@item -f 12118Use head revision if tag/date not found. See 12119@ref{Common options}. 12120 12121@c Probably want to use rev1/rev2 style like for diff 12122@c -r. Here and in on-line help. 12123@item -j @var{tag}[:@var{date}] 12124Merge in the change specified by @var{tag}, or when @var{date} is specified 12125and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12126existed on @var{date}. See @ref{checkout options}. 12127 12128@item -k @var{kflag} 12129Use @var{kflag} keyword expansion. See 12130@ref{Substitution modes}. 12131 12132@item -l 12133Local; run only in current working directory. @xref{Recursive behavior}. 12134 12135@item -N 12136Don't ``shorten'' module paths if -d specified. See 12137@ref{checkout options}. 12138 12139@item -n 12140Do not run module program (if any). See @ref{checkout options}. 12141 12142@item -P 12143Prune empty directories. See @ref{Moving directories}. 12144 12145@item -p 12146Check out files to standard output (avoids 12147stickiness). See @ref{checkout options}. 12148 12149@item -R 12150Operate recursively (default). @xref{Recursive 12151behavior}. 12152 12153@item -r @var{tag}[:@var{date}] 12154Checkout the revision already tagged with @var{tag} or, when @var{date} is 12155specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12156as it existed on @var{date}. This . See @ref{Common options}. 12157 12158@item -s 12159Like -c, but include module status. See @ref{checkout options}. 12160@end table 12161 12162@c ------------------------------------------------------------ 12163@item commit [@var{options}] [@var{files}@dots{}] 12164Check changes into the repository. See @ref{commit}. 12165 12166@table @code 12167@item -c 12168Check for valid edits before committing. Requires a @sc{cvs} client and server 12169both version 1.12.10 or greater. 12170 12171@item -F @var{file} 12172Read log message from @var{file}. See @ref{commit options}. 12173 12174@item -f 12175@c What is this "disables recursion"? It is from the 12176@c on-line help; is it documented in this manual? 12177Force the file to be committed; disables recursion. 12178See @ref{commit options}. 12179 12180@item -l 12181Local; run only in current working directory. See @ref{Recursive behavior}. 12182 12183@item -m @var{msg} 12184Use @var{msg} as log message. See @ref{commit options}. 12185 12186@item -n 12187Do not run module program (if any). See @ref{commit options}. 12188 12189@item -R 12190Operate recursively (default). @xref{Recursive 12191behavior}. 12192 12193@item -r @var{rev} 12194Commit to @var{rev}. See @ref{commit options}. 12195@c FIXME: should be dragging over text from 12196@c commit options, especially if it can be cleaned up 12197@c and made concise enough. 12198@end table 12199 12200@c ------------------------------------------------------------ 12201@item diff [@var{options}] [@var{files}@dots{}] 12202Show differences between revisions. See @ref{diff}. 12203In addition to the options shown below, accepts a wide 12204variety of options to control output style, for example 12205@samp{-c} for context diffs. 12206 12207@table @code 12208@item -D @var{date1} 12209Diff revision for date against working file. See 12210@ref{diff options}. 12211 12212@item -D @var{date2} 12213Diff @var{rev1}/@var{date1} against @var{date2}. See 12214@ref{diff options}. 12215 12216@item -l 12217Local; run only in current working directory. See @ref{Recursive behavior}. 12218 12219@item -N 12220Include diffs for added and removed files. See 12221@ref{diff options}. 12222 12223@item -R 12224Operate recursively (default). @xref{Recursive 12225behavior}. 12226 12227@item -r @var{tag1}[:@var{date1}] 12228Diff the revisions specified by @var{tag1} or, when @var{date1} is specified 12229and @var{tag1} is a branch tag, the version from the branch @var{tag1} as it 12230existed on @var{date1}, against the working file. See @ref{diff options} 12231and @ref{Common options}. 12232 12233@item -r @var{tag2}[:@var{date2}] 12234Diff the revisions specified by @var{tag2} or, when @var{date2} is specified 12235and @var{tag2} is a branch tag, the version from the branch @var{tag2} as it 12236existed on @var{date2}, against @var{rev1}/@var{date1}. See @ref{diff options} 12237and @ref{Common options}. 12238@end table 12239 12240@c ------------------------------------------------------------ 12241@item edit [@var{options}] [@var{files}@dots{}] 12242Get ready to edit a watched file. See @ref{Editing files}. 12243 12244@table @code 12245@item -a @var{actions} 12246Specify actions for temporary watch, where 12247@var{actions} is @code{edit}, @code{unedit}, 12248@code{commit}, @code{all}, or @code{none}. See 12249@ref{Editing files}. 12250 12251@item -c 12252Check edits: Edit fails if someone else is already editting the file. 12253Requires a @sc{cvs} client and server both of version 1.12.10 or greater. 12254 12255@item -f 12256Force edit; ignore other edits. Added in CVS 1.12.10. 12257 12258@item -l 12259Local; run only in current working directory. See @ref{Recursive behavior}. 12260 12261@item -R 12262Operate recursively (default). @xref{Recursive 12263behavior}. 12264@end table 12265 12266@c ------------------------------------------------------------ 12267@item editors [@var{options}] [@var{files}@dots{}] 12268See who is editing a watched file. See @ref{Watch information}. 12269 12270@table @code 12271@item -l 12272Local; run only in current working directory. See @ref{Recursive behavior}. 12273 12274@item -R 12275Operate recursively (default). @xref{Recursive 12276behavior}. 12277@end table 12278 12279@c ------------------------------------------------------------ 12280@item export [@var{options}] @var{modules}@dots{} 12281Export files from @sc{cvs}. See @ref{export}. 12282 12283@table @code 12284@item -D @var{date} 12285Check out revisions as of @var{date}. See 12286@ref{Common options}. 12287 12288@item -d @var{dir} 12289Check out into @var{dir}. See @ref{export options}. 12290 12291@item -f 12292Use head revision if tag/date not found. See 12293@ref{Common options}. 12294 12295@item -k @var{kflag} 12296Use @var{kflag} keyword expansion. See 12297@ref{Substitution modes}. 12298 12299@item -l 12300Local; run only in current working directory. @xref{Recursive behavior}. 12301 12302@item -N 12303Don't ``shorten'' module paths if -d specified. See 12304@ref{export options}. 12305 12306@item -n 12307Do not run module program (if any). See @ref{export options}. 12308 12309@item -R 12310Operate recursively (default). @xref{Recursive 12311behavior}. 12312 12313@item -r @var{tag}[:@var{date}] 12314Export the revisions specified by @var{tag} or, when @var{date} is specified 12315and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12316existed on @var{date}. See @ref{Common options}. 12317@end table 12318 12319@c ------------------------------------------------------------ 12320@item history [@var{options}] [@var{files}@dots{}] 12321Show repository access history. See @ref{history}. 12322 12323@table @code 12324@item -a 12325All users (default is self). See @ref{history options}. 12326 12327@item -b @var{str} 12328Back to record with @var{str} in module/file/repos 12329field. See @ref{history options}. 12330 12331@item -c 12332Report on committed (modified) files. See @ref{history options}. 12333 12334@item -D @var{date} 12335Since @var{date}. See @ref{history options}. 12336 12337@item -e 12338Report on all record types. See @ref{history options}. 12339 12340@item -l 12341Last modified (committed or modified report). See @ref{history options}. 12342 12343@item -m @var{module} 12344Report on @var{module} (repeatable). See @ref{history options}. 12345 12346@item -n @var{module} 12347In @var{module}. See @ref{history options}. 12348 12349@item -o 12350Report on checked out modules. See @ref{history options}. 12351 12352@item -p @var{repository} 12353In @var{repository}. See @ref{history options}. 12354 12355@item -r @var{rev} 12356Since revision @var{rev}. See @ref{history options}. 12357 12358@item -T 12359@c What the @#$@# is a TAG? Same as a tag? This 12360@c wording is also in the online-line help. 12361Produce report on all TAGs. See @ref{history options}. 12362 12363@item -t @var{tag} 12364Since tag record placed in history file (by anyone). 12365See @ref{history options}. 12366 12367@item -u @var{user} 12368For user @var{user} (repeatable). See @ref{history options}. 12369 12370@item -w 12371Working directory must match. See @ref{history options}. 12372 12373@item -x @var{types} 12374Report on @var{types}, one or more of 12375@code{TOEFWUPCGMAR}. See @ref{history options}. 12376 12377@item -z @var{zone} 12378Output for time zone @var{zone}. See @ref{history options}. 12379@end table 12380 12381@c ------------------------------------------------------------ 12382@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 12383Import files into @sc{cvs}, using vendor branches. See 12384@ref{import}. 12385 12386@table @code 12387@item -b @var{bra} 12388Import to vendor branch @var{bra}. See 12389@ref{Multiple vendor branches}. 12390 12391@item -d 12392Use the file's modification time as the time of 12393import. See @ref{import options}. 12394 12395@item -k @var{kflag} 12396Set default keyword substitution mode. See 12397@ref{import options}. 12398 12399@item -m @var{msg} 12400Use @var{msg} for log message. See 12401@ref{import options}. 12402 12403@item -I @var{ign} 12404More files to ignore (! to reset). See 12405@ref{import options}. 12406 12407@item -W @var{spec} 12408More wrappers. See @ref{import options}. 12409@end table 12410 12411@c ------------------------------------------------------------ 12412@item init 12413Create a @sc{cvs} repository if it doesn't exist. See 12414@ref{Creating a repository}. 12415 12416@c ------------------------------------------------------------ 12417@item kserver 12418Kerberos authenticated server. 12419See @ref{Kerberos authenticated}. 12420 12421@c ------------------------------------------------------------ 12422@item log [@var{options}] [@var{files}@dots{}] 12423Print out history information for files. See @ref{log}. 12424 12425@table @code 12426@item -b 12427Only list revisions on the default branch. See @ref{log options}. 12428 12429@item -d @var{dates} 12430Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12431latest before). See @ref{log options}. 12432 12433@item -h 12434Only print header. See @ref{log options}. 12435 12436@item -l 12437Local; run only in current working directory. See @ref{Recursive behavior}. 12438 12439@item -N 12440Do not list tags. See @ref{log options}. 12441 12442@item -R 12443Only print name of RCS file. See @ref{log options}. 12444 12445@item -r@var{revs} 12446Only list revisions @var{revs}. See @ref{log options}. 12447 12448@item -s @var{states} 12449Only list revisions with specified states. See @ref{log options}. 12450 12451@item -t 12452Only print header and descriptive text. See @ref{log 12453options}. 12454 12455@item -w@var{logins} 12456Only list revisions checked in by specified logins. See @ref{log options}. 12457@end table 12458 12459@c ------------------------------------------------------------ 12460@item login 12461Prompt for password for authenticating server. See 12462@ref{Password authentication client}. 12463 12464@c ------------------------------------------------------------ 12465@item logout 12466Remove stored password for authenticating server. See 12467@ref{Password authentication client}. 12468 12469@c ------------------------------------------------------------ 12470@item pserver 12471Password authenticated server. 12472See @ref{Password authentication server}. 12473 12474@c ------------------------------------------------------------ 12475@item rannotate [@var{options}] [@var{modules}@dots{}] 12476Show last revision where each line was modified. See 12477@ref{annotate}. 12478 12479@table @code 12480@item -D @var{date} 12481Annotate the most recent revision no later than 12482@var{date}. See @ref{Common options}. 12483 12484@item -F 12485Force annotation of binary files. (Without this option, 12486binary files are skipped with a message.) 12487 12488@item -f 12489Use head revision if tag/date not found. See 12490@ref{Common options}. 12491 12492@item -l 12493Local; run only in current working directory. @xref{Recursive behavior}. 12494 12495@item -R 12496Operate recursively (default). @xref{Recursive behavior}. 12497 12498@item -r @var{tag}[:@var{date}] 12499Annotate the revision specified by @var{tag} or, when @var{date} is specified 12500and @var{tag} is a branch tag, the version from the branch @var{tag} 12501as it existed on @var{date}. See @ref{Common options}. 12502@end table 12503 12504@c ------------------------------------------------------------ 12505@item rdiff [@var{options}] @var{modules}@dots{} 12506Show differences between releases. See @ref{rdiff}. 12507 12508@table @code 12509@item -c 12510Context diff output format (default). See @ref{rdiff options}. 12511 12512@item -D @var{date} 12513Select revisions based on @var{date}. See @ref{Common options}. 12514 12515@item -f 12516Use head revision if tag/date not found. See 12517@ref{Common options}. 12518 12519@item -l 12520Local; run only in current working directory. See @ref{Recursive behavior}. 12521 12522@item -R 12523Operate recursively (default). @xref{Recursive 12524behavior}. 12525 12526@item -r @var{tag}[:@var{date}] 12527Select the revisions specified by @var{tag} or, when @var{date} is specified 12528and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12529existed on @var{date}. See @ref{diff options} and @ref{Common options}. 12530 12531@item -s 12532Short patch - one liner per file. See @ref{rdiff options}. 12533 12534@item -t 12535Top two diffs - last change made to the file. See 12536@ref{diff options}. 12537 12538@item -u 12539Unidiff output format. See @ref{rdiff options}. 12540 12541@item -V @var{vers} 12542Use RCS Version @var{vers} for keyword expansion (obsolete). See 12543@ref{rdiff options}. 12544@end table 12545 12546@c ------------------------------------------------------------ 12547@item release [@var{options}] @var{directory} 12548Indicate that a directory is no longer in use. See 12549@ref{release}. 12550 12551@table @code 12552@item -d 12553Delete the given directory. See @ref{release options}. 12554@end table 12555 12556@c ------------------------------------------------------------ 12557@item remove [@var{options}] [@var{files}@dots{}] 12558Remove an entry from the repository. See @ref{Removing files}. 12559 12560@table @code 12561@item -f 12562Delete the file before removing it. See @ref{Removing files}. 12563 12564@item -l 12565Local; run only in current working directory. See @ref{Recursive behavior}. 12566 12567@item -R 12568Operate recursively (default). @xref{Recursive 12569behavior}. 12570@end table 12571 12572@c ------------------------------------------------------------ 12573@item rlog [@var{options}] [@var{files}@dots{}] 12574Print out history information for modules. See @ref{log}. 12575 12576@table @code 12577@item -b 12578Only list revisions on the default branch. See @ref{log options}. 12579 12580@item -d @var{dates} 12581Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12582latest before). See @ref{log options}. 12583 12584@item -h 12585Only print header. See @ref{log options}. 12586 12587@item -l 12588Local; run only in current working directory. See @ref{Recursive behavior}. 12589 12590@item -N 12591Do not list tags. See @ref{log options}. 12592 12593@item -R 12594Only print name of RCS file. See @ref{log options}. 12595 12596@item -r@var{revs} 12597Only list revisions @var{revs}. See @ref{log options}. 12598 12599@item -s @var{states} 12600Only list revisions with specified states. See @ref{log options}. 12601 12602@item -t 12603Only print header and descriptive text. See @ref{log options}. 12604 12605@item -w@var{logins} 12606Only list revisions checked in by specified logins. See @ref{log options}. 12607@end table 12608 12609@c ------------------------------------------------------------ 12610@item rtag [@var{options}] @var{tag} @var{modules}@dots{} 12611Add a symbolic tag to a module. 12612See @ref{Revisions} and @ref{Branching and merging}. 12613 12614@table @code 12615@item -a 12616Clear tag from removed files that would not otherwise 12617be tagged. See @ref{Tagging add/remove}. 12618 12619@item -b 12620Create a branch named @var{tag}. See @ref{Branching and merging}. 12621 12622@item -B 12623Used in conjunction with -F or -d, enables movement and deletion of 12624branch tags. Use with extreme caution. 12625 12626@item -D @var{date} 12627Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12628 12629@item -d 12630Delete @var{tag}. See @ref{Modifying tags}. 12631 12632@item -F 12633Move @var{tag} if it already exists. See @ref{Modifying tags}. 12634 12635@item -f 12636Force a head revision match if tag/date not found. 12637See @ref{Tagging by date/tag}. 12638 12639@item -l 12640Local; run only in current working directory. See @ref{Recursive behavior}. 12641 12642@item -n 12643No execution of tag program. See @ref{Common options}. 12644 12645@item -R 12646Operate recursively (default). @xref{Recursive 12647behavior}. 12648 12649@item -r @var{tag}[:@var{date}] 12650Tag the revision already tagged with @var{tag} or, when @var{date} is specified 12651and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12652existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12653@end table 12654 12655@c ------------------------------------------------------------ 12656@item server 12657Rsh server. See @ref{Connecting via rsh}. 12658 12659@c ------------------------------------------------------------ 12660@item status [@var{options}] @var{files}@dots{} 12661Display status information in a working directory. See 12662@ref{File status}. 12663 12664@table @code 12665@item -l 12666Local; run only in current working directory. See @ref{Recursive behavior}. 12667 12668@item -R 12669Operate recursively (default). @xref{Recursive behavior}. 12670 12671@item -v 12672Include tag information for file. See @ref{Tags}. 12673@end table 12674 12675@c ------------------------------------------------------------ 12676@item tag [@var{options}] @var{tag} [@var{files}@dots{}] 12677Add a symbolic tag to checked out version of files. 12678See @ref{Revisions} and @ref{Branching and merging}. 12679 12680@table @code 12681@item -b 12682Create a branch named @var{tag}. See @ref{Branching and merging}. 12683 12684@item -c 12685Check that working files are unmodified. See 12686@ref{Tagging the working directory}. 12687 12688@item -D @var{date} 12689Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12690 12691@item -d 12692Delete @var{tag}. See @ref{Modifying tags}. 12693 12694@item -F 12695Move @var{tag} if it already exists. See @ref{Modifying tags}. 12696 12697@item -f 12698Force a head revision match if tag/date not found. 12699See @ref{Tagging by date/tag}. 12700 12701@item -l 12702Local; run only in current working directory. See @ref{Recursive behavior}. 12703 12704@item -R 12705Operate recursively (default). @xref{Recursive behavior}. 12706 12707@item -r @var{tag}[:@var{date}] 12708Tag the revision already tagged with @var{tag}, or when @var{date} is specified 12709and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12710existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12711@end table 12712 12713@c ------------------------------------------------------------ 12714@item unedit [@var{options}] [@var{files}@dots{}] 12715Undo an edit command. See @ref{Editing files}. 12716 12717@table @code 12718@item -l 12719Local; run only in current working directory. See @ref{Recursive behavior}. 12720 12721@item -R 12722Operate recursively (default). @xref{Recursive behavior}. 12723@end table 12724 12725@c ------------------------------------------------------------ 12726@item update [@var{options}] [@var{files}@dots{}] 12727Bring work tree in sync with repository. See 12728@ref{update}. 12729 12730@table @code 12731@item -A 12732Reset any sticky tags/date/options. See @ref{Sticky 12733tags} and @ref{Keyword substitution}. 12734 12735@item -C 12736Overwrite locally modified files with clean copies from 12737the repository (the modified file is saved in 12738@file{.#@var{file}.@var{revision}}, however). 12739 12740@item -D @var{date} 12741Check out revisions as of @var{date} (is sticky). See 12742@ref{Common options}. 12743 12744@item -d 12745Create directories. See @ref{update options}. 12746 12747@item -f 12748Use head revision if tag/date not found. See 12749@ref{Common options}. 12750 12751@item -I @var{ign} 12752More files to ignore (! to reset). See 12753@ref{import options}. 12754 12755@c Probably want to use rev1/rev2 style like for diff 12756@c -r. Here and in on-line help. 12757@item -j @var{tag}[:@var{date}] 12758Merge in changes from revisions specified by @var{tag} or, when @var{date} is 12759specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12760as it existed on @var{date}. See @ref{update options}. 12761 12762@item -k @var{kflag} 12763Use @var{kflag} keyword expansion. See 12764@ref{Substitution modes}. 12765 12766@item -l 12767Local; run only in current working directory. @xref{Recursive behavior}. 12768 12769@item -P 12770Prune empty directories. See @ref{Moving directories}. 12771 12772@item -p 12773Check out files to standard output (avoids 12774stickiness). See @ref{update options}. 12775 12776@item -R 12777Operate recursively (default). @xref{Recursive 12778behavior}. 12779 12780@item -r @var{tag}[:@var{date}] 12781Checkout the revisions specified by @var{tag} or, when @var{date} is specified 12782and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12783existed on @var{date}. See @ref{Common options}. 12784 12785@item -W @var{spec} 12786More wrappers. See @ref{import options}. 12787@end table 12788 12789@c ------------------------------------------------------------ 12790@item version 12791@cindex version (subcommand) 12792 12793Display the version of @sc{cvs} being used. If the repository 12794is remote, display both the client and server versions. 12795 12796@c ------------------------------------------------------------ 12797@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 12798 12799on/off: turn on/off read-only checkouts of files. See 12800@ref{Setting a watch}. 12801 12802add/remove: add or remove notification on actions. See 12803@ref{Getting Notified}. 12804 12805@table @code 12806@item -a @var{actions} 12807Specify actions for temporary watch, where 12808@var{actions} is @code{edit}, @code{unedit}, 12809@code{commit}, @code{all}, or @code{none}. See 12810@ref{Editing files}. 12811 12812@item -l 12813Local; run only in current working directory. See @ref{Recursive behavior}. 12814 12815@item -R 12816Operate recursively (default). @xref{Recursive 12817behavior}. 12818@end table 12819 12820@c ------------------------------------------------------------ 12821@item watchers [@var{options}] [@var{files}@dots{}] 12822See who is watching a file. See @ref{Watch information}. 12823 12824@table @code 12825@item -l 12826Local; run only in current working directory. See @ref{Recursive behavior}. 12827 12828@item -R 12829Operate recursively (default). @xref{Recursive 12830behavior}. 12831@end table 12832 12833@end table 12834 12835@c --------------------------------------------------------------------- 12836@node Administrative files 12837@appendix Reference manual for Administrative files 12838@cindex Administrative files (reference) 12839@cindex Files, reference manual 12840@cindex Reference manual (files) 12841@cindex CVSROOT (file) 12842 12843Inside the repository, in the directory 12844@file{$CVSROOT/CVSROOT}, there are a number of 12845supportive files for @sc{cvs}. You can use @sc{cvs} in a limited 12846fashion without any of them, but if they are set up 12847properly they can help make life easier. For a 12848discussion of how to edit them, see @ref{Intro 12849administrative files}. 12850 12851The most important of these files is the @file{modules} 12852file, which defines the modules inside the repository. 12853 12854@menu 12855* modules:: Defining modules 12856* Wrappers:: Specify binary-ness based on file name 12857* Trigger Scripts:: Launch scripts in response to server events 12858* rcsinfo:: Templates for the log messages 12859* cvsignore:: Ignoring files via cvsignore 12860* checkoutlist:: Adding your own administrative files 12861* history file:: History information 12862* Variables:: Various variables are expanded 12863* config:: Miscellaneous CVS configuration 12864@end menu 12865 12866@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12867@node modules 12868@appendixsec The modules file 12869@cindex Modules (admin file) 12870@cindex Defining modules (reference manual) 12871 12872The @file{modules} file records your definitions of 12873names for collections of source code. @sc{cvs} will 12874use these definitions if you use @sc{cvs} to update the 12875modules file (use normal commands like @code{add}, 12876@code{commit}, etc). 12877 12878The @file{modules} file may contain blank lines and 12879comments (lines beginning with @samp{#}) as well as 12880module definitions. Long lines can be continued on the 12881next line by specifying a backslash (@samp{\}) as the 12882last character on the line. 12883 12884There are three basic types of modules: alias modules, 12885regular modules, and ampersand modules. The difference 12886between them is the way that they map files in the 12887repository to files in the working directory. In all 12888of the following examples, the top-level repository 12889contains a directory called @file{first-dir}, which 12890contains two files, @file{file1} and @file{file2}, and a 12891directory @file{sdir}. @file{first-dir/sdir} contains 12892a file @file{sfile}. 12893 12894@c FIXME: should test all the examples in this section. 12895 12896@menu 12897* Alias modules:: The simplest kind of module 12898* Regular modules:: 12899* Ampersand modules:: 12900* Excluding directories:: Excluding directories from a module 12901* Module options:: Regular and ampersand modules can take options 12902* Module program options:: How the modules ``program options'' programs 12903 are run. 12904@end menu 12905 12906@node Alias modules 12907@appendixsubsec Alias modules 12908@cindex Alias modules 12909@cindex -a, in modules file 12910 12911Alias modules are the simplest kind of module: 12912 12913@table @code 12914@item @var{mname} -a @var{aliases}@dots{} 12915This represents the simplest way of defining a module 12916@var{mname}. The @samp{-a} flags the definition as a 12917simple alias: @sc{cvs} will treat any use of @var{mname} (as 12918a command argument) as if the list of names 12919@var{aliases} had been specified instead. 12920@var{aliases} may contain either other module names or 12921paths. When you use paths in aliases, @code{checkout} 12922creates all intermediate directories in the working 12923directory, just as if the path had been specified 12924explicitly in the @sc{cvs} arguments. 12925@end table 12926 12927For example, if the modules file contains: 12928 12929@example 12930amodule -a first-dir 12931@end example 12932 12933@noindent 12934then the following two commands are equivalent: 12935 12936@example 12937$ cvs co amodule 12938$ cvs co first-dir 12939@end example 12940 12941@noindent 12942and they each would provide output such as: 12943 12944@example 12945cvs checkout: Updating first-dir 12946U first-dir/file1 12947U first-dir/file2 12948cvs checkout: Updating first-dir/sdir 12949U first-dir/sdir/sfile 12950@end example 12951 12952@node Regular modules 12953@appendixsubsec Regular modules 12954@cindex Regular modules 12955 12956@table @code 12957@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 12958In the simplest case, this form of module definition 12959reduces to @samp{@var{mname} @var{dir}}. This defines 12960all the files in directory @var{dir} as module mname. 12961@var{dir} is a relative path (from @code{$CVSROOT}) to a 12962directory of source in the source repository. In this 12963case, on checkout, a single directory called 12964@var{mname} is created as a working directory; no 12965intermediate directory levels are used by default, even 12966if @var{dir} was a path involving several directory 12967levels. 12968@end table 12969 12970For example, if a module is defined by: 12971 12972@example 12973regmodule first-dir 12974@end example 12975 12976@noindent 12977then regmodule will contain the files from first-dir: 12978 12979@example 12980$ cvs co regmodule 12981cvs checkout: Updating regmodule 12982U regmodule/file1 12983U regmodule/file2 12984cvs checkout: Updating regmodule/sdir 12985U regmodule/sdir/sfile 12986$ 12987@end example 12988 12989By explicitly specifying files in the module definition 12990after @var{dir}, you can select particular files from 12991directory @var{dir}. Here is 12992an example: 12993 12994@example 12995regfiles first-dir/sdir sfile 12996@end example 12997 12998@noindent 12999With this definition, getting the regfiles module 13000will create a single working directory 13001@file{regfiles} containing the file listed, which 13002comes from a directory deeper 13003in the @sc{cvs} source repository: 13004 13005@example 13006$ cvs co regfiles 13007U regfiles/sfile 13008$ 13009@end example 13010 13011@node Ampersand modules 13012@appendixsubsec Ampersand modules 13013@cindex Ampersand modules 13014@cindex &, in modules file 13015 13016A module definition can refer to other modules by 13017including @samp{&@var{module}} in its definition. 13018@example 13019@var{mname} [ options ] @var{&module}@dots{} 13020@end example 13021 13022Then getting the module creates a subdirectory for each such 13023module, in the directory containing the module. For 13024example, if modules contains 13025 13026@example 13027ampermod &first-dir 13028@end example 13029 13030@noindent 13031then a checkout will create an @code{ampermod} directory 13032which contains a directory called @code{first-dir}, 13033which in turns contains all the directories and files 13034which live there. For example, the command 13035 13036@example 13037$ cvs co ampermod 13038@end example 13039 13040@noindent 13041will create the following files: 13042 13043@example 13044ampermod/first-dir/file1 13045ampermod/first-dir/file2 13046ampermod/first-dir/sdir/sfile 13047@end example 13048 13049There is one quirk/bug: the messages that @sc{cvs} 13050prints omit the @file{ampermod}, and thus do not 13051correctly display the location to which it is checking 13052out the files: 13053 13054@example 13055$ cvs co ampermod 13056cvs checkout: Updating first-dir 13057U first-dir/file1 13058U first-dir/file2 13059cvs checkout: Updating first-dir/sdir 13060U first-dir/sdir/sfile 13061$ 13062@end example 13063 13064Do not rely on this buggy behavior; it may get fixed in 13065a future release of @sc{cvs}. 13066 13067@c FIXCVS: What happens if regular and & modules are 13068@c combined, as in "ampermodule first-dir &second-dir"? 13069@c When I tried it, it seemed to just ignore the 13070@c "first-dir". I think perhaps it should be an error 13071@c (but this needs further investigation). 13072@c In addition to discussing what each one does, we 13073@c should put in a few words about why you would use one or 13074@c the other in various situations. 13075 13076@node Excluding directories 13077@appendixsubsec Excluding directories 13078@cindex Excluding directories, in modules file 13079@cindex !, in modules file 13080 13081An alias module may exclude particular directories from 13082other modules by using an exclamation mark (@samp{!}) 13083before the name of each directory to be excluded. 13084 13085For example, if the modules file contains: 13086 13087@example 13088exmodule -a !first-dir/sdir first-dir 13089@end example 13090 13091@noindent 13092then checking out the module @samp{exmodule} will check 13093out everything in @samp{first-dir} except any files in 13094the subdirectory @samp{first-dir/sdir}. 13095@c Note that the "!first-dir/sdir" sometimes must be listed 13096@c before "first-dir". That seems like a probable bug, in which 13097@c case perhaps it should be fixed (to allow either 13098@c order) rather than documented. See modules4 in testsuite. 13099 13100@node Module options 13101@appendixsubsec Module options 13102@cindex Options, in modules file 13103 13104Either regular modules or ampersand modules can contain 13105options, which supply additional information concerning 13106the module. 13107 13108@table @code 13109@cindex -d, in modules file 13110@item -d @var{name} 13111Name the working directory something other than the 13112module name. 13113@c FIXME: Needs a bunch of examples, analogous to the 13114@c examples for alias, regular, and ampersand modules 13115@c which show where the files go without -d. 13116 13117@cindex Export program 13118@cindex -e, in modules file 13119@item -e @var{prog} 13120Specify a program @var{prog} to run whenever files in a 13121module are exported. @var{prog} runs with a single 13122argument, the module name. 13123@c FIXME: Is it run on server? client? 13124 13125@cindex Checkout program 13126@cindex -o, in modules file 13127@item -o @var{prog} 13128Specify a program @var{prog} to run whenever files in a 13129module are checked out. @var{prog} runs with a single 13130argument, the module name. See @ref{Module program options} for 13131information on how @var{prog} is called. 13132@c FIXME: Is it run on server? client? 13133 13134@cindex Status of a module 13135@cindex Module status 13136@cindex -s, in modules file 13137@item -s @var{status} 13138Assign a status to the module. When the module file is 13139printed with @samp{cvs checkout -s} the modules are 13140sorted according to primarily module status, and 13141secondarily according to the module name. This option 13142has no other meaning. You can use this option for 13143several things besides status: for instance, list the 13144person that is responsible for this module. 13145 13146@cindex Tag program 13147@cindex -t, in modules file 13148@item -t @var{prog} 13149Specify a program @var{prog} to run whenever files in a 13150module are tagged with @code{rtag}. @var{prog} runs 13151with two arguments: the module name and the symbolic 13152tag specified to @code{rtag}. It is not run 13153when @code{tag} is executed. Generally you will find 13154that the @file{taginfo} file is a better solution (@pxref{taginfo}). 13155@c FIXME: Is it run on server? client? 13156@c Problems with -t include: 13157@c * It is run after the tag not before 13158@c * It doesn't get passed all the information that 13159@c taginfo does ("mov", &c). 13160@c * It only is run for rtag, not tag. 13161@end table 13162 13163You should also see @pxref{Module program options} about how the 13164``program options'' programs are run. 13165 13166@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13167 13168@node Module program options 13169@appendixsubsec How the modules file ``program options'' programs are run 13170@cindex Modules file program options 13171@cindex -t, in modules file 13172@cindex -o, in modules file 13173@cindex -e, in modules file 13174 13175@noindent 13176For checkout, rtag, and export, the program is server-based, and as such the 13177following applies:- 13178 13179If using remote access methods (pserver, ext, etc.), 13180@sc{cvs} will execute this program on the server from a temporary 13181directory. The path is searched for this program. 13182 13183If using ``local access'' (on a local or remote NFS file system, i.e. 13184repository set just to a path), 13185the program will be executed from the newly checked-out tree, if 13186found there, or alternatively searched for in the path if not. 13187 13188The programs are all run after the operation has effectively 13189completed. 13190 13191 13192@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13193@node Wrappers 13194@appendixsec The cvswrappers file 13195@cindex cvswrappers (admin file) 13196@cindex CVSWRAPPERS, environment variable 13197@cindex Wrappers 13198 13199@c FIXME: need some better way of separating this out 13200@c by functionality. -m is 13201@c one feature, and -k is a another. And this discussion 13202@c should be better motivated (e.g. start with the 13203@c problems, then explain how the feature solves it). 13204 13205Wrappers refers to a @sc{cvs} feature which lets you 13206control certain settings based on the name of the file 13207which is being operated on. The settings are @samp{-k} 13208for binary files, and @samp{-m} for nonmergeable text 13209files. 13210 13211The @samp{-m} option 13212specifies the merge methodology that should be used when 13213a non-binary file is updated. @code{MERGE} means the usual 13214@sc{cvs} behavior: try to merge the files. @code{COPY} 13215means that @code{cvs update} will refuse to merge 13216files, as it also does for files specified as binary 13217with @samp{-kb} (but if the file is specified as 13218binary, there is no need to specify @samp{-m 'COPY'}). 13219@sc{cvs} will provide the user with the 13220two versions of the files, and require the user using 13221mechanisms outside @sc{cvs}, to insert any necessary 13222changes. 13223 13224@strong{WARNING: do not use @code{COPY} with 13225@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 13226copy one version of your file over the other, wiping 13227out the previous contents.} 13228@c Ordinarily we don't document the behavior of old 13229@c versions. But this one is so dangerous, I think we 13230@c must. I almost renamed it to -m 'NOMERGE' so we 13231@c could say "never use -m 'COPY'". 13232The @samp{-m} wrapper option only affects behavior when 13233merging is done on update; it does not affect how files 13234are stored. See @ref{Binary files}, for more on 13235binary files. 13236 13237The basic format of the file @file{cvswrappers} is: 13238 13239@c FIXME: @example is all wrong for this. Use @deffn or 13240@c something more sensible. 13241@example 13242wildcard [option value][option value]... 13243 13244where option is one of 13245-m update methodology value: MERGE or COPY 13246-k keyword expansion value: expansion mode 13247 13248and value is a single-quote delimited value. 13249@end example 13250 13251@ignore 13252@example 13253*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' 13254*.c -t 'indent %s %s' 13255@end example 13256@c When does the filter need to be an absolute pathname 13257@c and when will something like the above work? I 13258@c suspect it relates to the PATH of the server (which 13259@c in turn depends on all kinds of stuff, e.g. inetd 13260@c for pserver). I'm not sure whether/where to discuss 13261@c this. 13262@c FIXME: What do the %s's stand for? 13263 13264@noindent 13265The above example of a @file{cvswrappers} file 13266states that all files/directories that end with a @code{.nib} 13267should be filtered with the @file{wrap} program before 13268checking the file into the repository. The file should 13269be filtered though the @file{unwrap} program when the 13270file is checked out of the repository. The 13271@file{cvswrappers} file also states that a @code{COPY} 13272methodology should be used when updating the files in 13273the repository (that is, no merging should be performed). 13274 13275@c What pitfalls arise when using indent this way? Is 13276@c it a winning thing to do? Would be nice to at least 13277@c hint at those issues; we want our examples to tell 13278@c how to solve problems, not just to say that cvs can 13279@c do certain things. 13280The last example line says that all files that end with 13281@code{.c} should be filtered with @file{indent} 13282before being checked into the repository. Unlike the previous 13283example, no filtering of the @code{.c} file is done when 13284it is checked out of the repository. 13285@noindent 13286The @code{-t} filter is called with two arguments, 13287the first is the name of the file/directory to filter 13288and the second is the pathname to where the resulting 13289filtered file should be placed. 13290 13291@noindent 13292The @code{-f} filter is called with one argument, 13293which is the name of the file to filter from. The end 13294result of this filter will be a file in the users directory 13295that they can work on as they normally would. 13296 13297Note that the @samp{-t}/@samp{-f} features do not 13298conveniently handle one portion of @sc{cvs}'s operation: 13299determining when files are modified. @sc{cvs} will still 13300want a file (or directory) to exist, and it will use 13301its modification time to determine whether a file is 13302modified. If @sc{cvs} erroneously thinks a file is 13303unmodified (for example, a directory is unchanged but 13304one of the files within it is changed), you can force 13305it to check in the file anyway by specifying the 13306@samp{-f} option to @code{cvs commit} (@pxref{commit 13307options}). 13308@c This is, of course, a serious design flaw in -t/-f. 13309@c Probably the whole functionality needs to be 13310@c redesigned (starting from requirements) to fix this. 13311@end ignore 13312 13313@c FIXME: We don't document -W or point to where it is 13314@c documented. Or .cvswrappers. 13315For example, the following command imports a 13316directory, treating files whose name ends in 13317@samp{.exe} as binary: 13318 13319@example 13320cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 13321@end example 13322 13323@c Another good example, would be storing files 13324@c (e.g. binary files) compressed in the repository. 13325@c :::::::::::::::::: 13326@c cvswrappers 13327@c :::::::::::::::::: 13328@c *.t12 -m 'COPY' 13329@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 13330@c 13331@c :::::::::::::::::: 13332@c gunzipcp 13333@c :::::::::::::::::: 13334@c : 13335@c [ -f $1 ] || exit 1 13336@c zcat $1 > /tmp/.#$1.$$ 13337@c mv /tmp/.#$1.$$ $1 13338@c 13339@c :::::::::::::::::: 13340@c gzipcp 13341@c :::::::::::::::::: 13342@c : 13343@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 13344@c if [ ! -d $DIRNAME ] ; then 13345@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 13346@c fi 13347@c gzip -c $DIRNAME > $2 13348@c One catch--"cvs diff" will not invoke the wrappers 13349@c (probably a CVS bug, although I haven't thought it out). 13350 13351@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13352@node Trigger Scripts 13353@appendixsec The Trigger Scripts 13354@cindex info files 13355@cindex trigger scripts 13356@cindex script hooks 13357 13358@c FIXME 13359@c Somewhere there needs to be a more "how-to" guide to writing these. 13360@c One particular issue that people sometimes are worried about is performance, 13361@c and the impact of writing in perl or sh or ____. Performance comparisons 13362@c should probably remain outside the scope of this document, but at least 13363@c _that_ much could be referenced, perhaps with links to other sources. 13364 13365Several of the administrative files support triggers, or the launching external 13366scripts or programs at specific times before or after particular events, during 13367the execution of @sc{cvs} commands. These hooks can be used to prevent certain 13368actions, log them, and/or maintain anything else you deem practical. 13369 13370All the trigger scripts are launched in a copy of the user sandbox being 13371committed, on the server, in client-server mode. In local mode, the scripts 13372are actually launched directly from the user sandbox directory being committed. 13373For most intents and purposes, the same scripts can be run in both locations 13374without alteration. 13375 13376@menu 13377* syntax:: The common syntax 13378* Trigger Script Security:: Trigger script security 13379 13380* commit files:: The commit support files (commitinfo, 13381 verifymsg, loginfo) 13382* commitinfo:: Pre-commit checking 13383* verifymsg:: How are log messages evaluated? 13384* loginfo:: Where should log messages be sent? 13385 13386* postadmin:: Logging admin commands 13387* taginfo:: Verifying/Logging tags 13388* posttag:: Logging tags 13389* postwatch:: Logging watch commands 13390 13391* preproxy:: Launch a script on a secondary server prior 13392 to becoming a write proxy 13393* postproxy:: Launch a script on a secondary server after 13394 completing proxy operations 13395@end menu 13396 13397@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13398@node syntax 13399@appendixsubsec The common syntax 13400@cindex info files, common syntax 13401@cindex script hooks, common syntax 13402@cindex trigger script hooks, common syntax 13403@cindex syntax of trigger script hooks 13404 13405@c FIXME: having this so totally separate from the 13406@c Variables node is rather bogus. 13407 13408The administrative files such as @file{commitinfo}, 13409@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 13410all have a common format. The purpose of the files are 13411described later on. The common syntax is described 13412here. 13413 13414@cindex Regular expression syntax 13415Each line contains the following: 13416 13417@itemize @bullet 13418@cindex @samp{ALL} keyword, in lieu of regular expressions in script hooks 13419@cindex @samp{DEFAULT} keyword, in lieu of regular expressions in script hooks 13420@item 13421A regular expression or the literal string @samp{DEFAULT}. Some script hooks 13422also support the literal string @samp{ALL}. Other than the @samp{ALL} and 13423@samp{DEFAULT} keywords, this is a basic regular expression in the syntax used 13424by GNU emacs. See the descriptions of the individual script hooks for 13425information on whether the @samp{ALL} keyword is supported 13426(@pxref{Trigger Scripts}). 13427@c FIXME: What we probably should be saying is "POSIX Basic 13428@c Regular Expression with the following extensions (`\(' 13429@c `\|' '+' etc)" 13430@c rather than define it with reference to emacs. 13431@c The reference to emacs is not strictly speaking 13432@c true, as we don't support \=, \s, or \S. Also it isn't 13433@c clear we should document and/or promise to continue to 13434@c support all the obscure emacs extensions like \<. 13435@c Also need to better cite (or include) full 13436@c documentation for the syntax. 13437@c Also see comment in configure.in about what happens to the 13438@c syntax if we pick up a system-supplied regexp matcher. 13439 13440@item 13441A whitespace separator---one or more spaces and/or tabs. 13442 13443@item 13444A file name or command-line template. 13445@end itemize 13446 13447@noindent 13448Blank lines are ignored. Lines that start with the 13449character @samp{#} are treated as comments. Long lines 13450unfortunately can @emph{not} be broken in two parts in 13451any way. 13452 13453The first regular expression that matches the current 13454directory name in the repository or the first line containing @samp{DEFAULT} 13455in lieu of a regular expression is used and all lines containing @samp{ALL} is 13456used for the hooks which support the @samp{ALL} keyword. The rest of the line 13457is used as a file name or command-line template as appropriate. See the 13458descriptions of the individual script hooks for information on whether the 13459@samp{ALL} keyword is supported (@pxref{Trigger Scripts}). 13460 13461@cindex format strings 13462@cindex format strings, common syntax 13463@cindex info files, common syntax, format strings 13464@cindex Common syntax of info files, format strings 13465@noindent 13466@emph{Note: The following information on format strings is valid 13467as long as the line @code{UseNewInfoFmtStrings=yes} appears in 13468your repository's config file (@pxref{config}). Otherwise, 13469default format strings may be appended to the command line and 13470the @samp{loginfo} file, especially, can exhibit slightly 13471different behavior. For more information, 13472@xref{Updating Commit Files}.} 13473 13474In the cases where the second segment of the matched line is a 13475command line template (e.g. @file{commitinfo}, @file{loginfo}, 13476& @file{verifymsg}), the command line template may contain format 13477strings which will be replaced with specific values before the 13478script is run. 13479@c FIXCVS then FIXME - it really would make sense to allow %r & maybe even %p 13480@c to be used in rcsinfo to construct a path, but I haven't 13481@c coded this yet. 13482 13483Format strings can represent a single variable or one or more 13484attributes of a list variable. An example of a list variable 13485would be the list available to scripts hung on the loginfo hooks 13486- the list of files which were just committed. In the case of 13487loginfo, three attributes are available for each list item: file 13488name, precommit version, and postcommit version. 13489 13490Format strings consist of a @samp{%} character followed by an optional 13491@samp{@{} (required in the multiple list attribute case), a 13492single format character representing a variable or a single attribute of 13493list elements or multiple format characters representing attributes of 13494list elements, and a closing @samp{@}} when the open bracket was present. 13495 13496@emph{Flat format strings}, or single format characters which get replaced 13497with a single value, will generate a single argument 13498to the called script, regardless of whether the replacement variable contains 13499white space or other special characters. 13500 13501@emph{List attributes} will generate an argument for each attribute 13502requested for each list item. For example, @samp{%@{sVv@}} 13503in a @file{loginfo} command template will generate three 13504arguments (file name, precommit version, postcommit version, 13505...) for each file committed. As in the flat format string 13506case, each attribute will be passed in as a single argument 13507regardless of whether it contains white space or other 13508special characters. 13509 13510@samp{%%} will be replaced with a literal @samp{%}. 13511 13512The format strings available to all script hooks are: 13513 13514@table @t 13515@item c 13516The canonical name of the command being executed. For instance, in the case of 13517a hook run from @code{cvs up}, @sc{cvs} would replace @samp{%c} with the string 13518@samp{update} and, in the case of a hook run from @code{cvs ci}, @sc{cvs} would 13519replace @samp{%c} with the string @samp{commit}. 13520@item n 13521The null, or empty, string. 13522@item p 13523The name of the directory being operated on within the repository. 13524@item r 13525The name of the repository (the path portion of @code{$CVSROOT}). 13526@item R 13527On a server, the name of the referrer, if any. The referrer is the CVSROOT the 13528client reports it used to contact a server which then referred it to this 13529server. Should usually be set on a primary server with a write proxy setup. 13530@end table 13531 13532Other format strings are file specific. See the docs on the 13533particular script hooks for more information 13534(@pxref{Trigger Scripts}). 13535 13536As an example, the following line in a @file{loginfo} file would 13537match only the directory @file{module} and any subdirectories of 13538@file{module}: 13539 13540@example 13541^module\(/\|$\) (echo; echo %p; echo %@{sVv@}; cat) >>$CVSROOT/CVSROOT/commitlog 13542@end example 13543 13544Using this same line and assuming a commit of new revisions 135451.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27, 13546respectively, of file1 and file2 in module, something like the 13547following log message should be appended to commitlog: 13548 13549@example 13550 13551module 13552file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1 13553Update of /cvsroot/module 13554In directory localhost.localdomain:/home/jrandom/work/module 13555 13556Modified Files: 13557 file1 file2 13558Log Message: 13559A log message. 13560@end example 13561 13562@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13563@node Trigger Script Security 13564@appendixsubsec Security and the Trigger Scripts 13565@cindex info files, security 13566@cindex script hooks, security 13567@cindex trigger scripts, security 13568 13569Security is a huge subject, and implementing a secure system is a non-trivial 13570task. This section will barely touch on all the issues involved, but it is 13571well to note that, as with any script you will be allowing an untrusted 13572user to run on your server, there are measures you can take to help prevent 13573your trigger scripts from being abused. 13574 13575For instance, since the CVS trigger scripts all run in a copy of the user's 13576sandbox on the server, a naively coded Perl trigger script which attempts to 13577use a Perl module that is not installed on the system can be hijacked by any 13578user with commit access who is checking in a file with the correct name. Other 13579scripting languages may be vulnerable to similar hacks. 13580 13581One way to make a script more secure, at least with Perl, is to use scripts 13582which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. 13583In the most basic terms, this causes Perl to avoid running code that may have 13584come from an external source. Please run the @code{perldoc perlsec} command 13585for more on Perl security. Again, other languages may implement other security 13586verification hooks which look more or less like Perl's "taint-check" mechanism. 13587 13588@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13589@node commit files 13590@appendixsubsec The commit support files 13591@cindex Commits, administrative support files 13592@cindex commit files, see Info files 13593 13594The @samp{-i} flag in the @file{modules} file can be 13595used to run a certain program whenever files are 13596committed (@pxref{modules}). The files described in 13597this section provide other, more flexible, ways to run 13598programs whenever something is committed. 13599 13600There are three kinds of programs that can be run on 13601commit. They are specified in files in the repository, 13602as described below. The following table summarizes the 13603file names and the purpose of the corresponding 13604programs. 13605 13606@table @file 13607@item commitinfo 13608The program is responsible for checking that the commit 13609is allowed. If it exits with a non-zero exit status 13610the commit will be aborted. @xref{commitinfo}. 13611 13612@item verifymsg 13613The specified program is used to evaluate the log message, 13614and possibly verify that it contains all required 13615fields. This is most useful in combination with the 13616@file{rcsinfo} file, which can hold a log message 13617template (@pxref{rcsinfo}). @xref{verifymsg}. 13618 13619@item loginfo 13620The specified program is called when the commit is 13621complete. It receives the log message and some 13622additional information and can store the log message in 13623a file, or mail it to appropriate persons, or maybe 13624post it to a local newsgroup, or@dots{} Your 13625imagination is the limit! @xref{loginfo}. 13626@end table 13627 13628@menu 13629* Updating Commit Files:: Updating legacy repositories to stop using 13630 deprecated command line template formats 13631@end menu 13632 13633@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13634@node Updating Commit Files 13635@appendixsubsubsec Updating legacy repositories to stop using deprecated command line template formats 13636@cindex info files, common syntax, updating legacy repositories 13637@cindex Syntax of info files, updating legacy repositories 13638@cindex Common syntax of info files, updating legacy repositories 13639New repositories are created set to use the new format strings by default, so 13640if you are creating a new repository, you shouldn't have to worry about this 13641section. 13642 13643If you are attempting to maintain a legacy repository which was 13644making use of the @file{commitinfo}, @file{editinfo}, @file{verifymsg}, 13645@file{loginfo}, and/or @file{taginfo} script hooks, you should have no 13646immediate problems with using the current @sc{cvs} executable, but your users 13647will probably start to see deprecation warnings. 13648 13649The reason for this is that all of the script hooks have been updated to 13650use a new command line parser that extensibly supports multiple 13651@file{loginfo} & @file{notify} style format strings (@pxref{syntax}) 13652and this support is not completely compatible with the old style format 13653strings. 13654 13655The quick upgrade method is to stick a @samp{1} after each format string 13656in your old @file{loginfo} file. For example: 13657 13658@example 13659DEFAULT (echo ""; id; echo %@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13660@end example 13661 13662would become: 13663 13664@example 13665DEFAULT (echo ""; id; echo %1@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13666@end example 13667 13668If you were counting on the fact that only the first @samp{%} in the line was 13669replaced as a format string, you may also have to double up any further 13670percent signs on the line. 13671 13672If you did this all at once and checked it in, everything should still be 13673running properly. 13674 13675Now add the following line to your config file (@pxref{config}): 13676@example 13677UseNewInfoFmtStrings=yes 13678@end example 13679 13680Everything should still be running properly, but your users will probably 13681start seeing new deprecation warnings. 13682 13683Dealing with the deprecation warnings now generated by @file{commitinfo}, 13684@file{editinfo}, @file{verifymsg}, and @file{taginfo} should be easy. Simply 13685specify what are currently implicit arguments explicitly. This means appending 13686the following strings to each active command line template in each file: 13687@table @code 13688@item commitinfo 13689@samp{ %r/%p %s} 13690@item editinfo 13691@samp{ %l} 13692@item taginfo 13693@samp{ %t %o %p %@{sv@}} 13694@item verifymsg 13695@samp{ %l} 13696@end table 13697 13698If you don't desire that any of the newly available information be passed to 13699the scripts hanging off of these hooks, no further modifications to these 13700files should be necessary to insure current and future compatibility with 13701@sc{cvs}'s format strings. 13702 13703Fixing @file{loginfo} could be a little tougher. The old style 13704@file{loginfo} format strings caused a single space and comma separated 13705argument to be passed in in place of the format string. This is what will 13706continue to be generated due to the deprecated @samp{1} you inserted into 13707the format strings. 13708 13709Since the new format separates each individual item and passes it into the 13710script as a separate argument (for a good reason - arguments containing commas 13711and/or white space are now parsable), to remove the deprecated @samp{1} from 13712your @file{loginfo} command line templates, you will most likely have to 13713rewrite any scripts called by the hook to handle the new argument format. 13714 13715Also note that the way @samp{%} followed by unrecognized characters and by 13716@samp{@{@}} was treated in past versions of CVS is not strictly adhered to as 13717there were bugs in the old versions. Specifically, @samp{%@{@}} would eat the 13718next character and unrecognized strings resolved only to the empty string, 13719which was counter to what was stated in the documentation. This version will 13720do what the documentation said it should have (if you were using only some 13721combination of @samp{%@{sVv@}}, e.g. @samp{%@{sVv@}}, @samp{%@{sV@}}, or 13722@samp{%v}, you should have no troubles). 13723 13724On the bright side, you should have plenty of time to do this before all 13725support for the old format strings is removed from @sc{cvs}, so you can just 13726put up with the deprecation warnings for awhile if you like. 13727 13728@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13729@node commitinfo 13730@appendixsubsec Commitinfo 13731@cindex @file{commitinfo} 13732@cindex Commits, precommit verification of 13733@cindex commitinfo (admin file) 13734@cindex info files, commitinfo 13735@cindex script hooks, commitinfo 13736@cindex trigger scripts, commitinfo 13737@cindex info files, precommit verification of commits 13738@cindex script hooks, precommit verification of commits 13739@cindex trigger scripts, precommit verification of commits 13740 13741The @file{commitinfo} file defines programs to execute 13742whenever @samp{cvs commit} is about to execute. These 13743programs are used for pre-commit checking to verify 13744that the modified, added and removed files are really 13745ready to be committed. This could be used, for 13746instance, to verify that the changed files conform to 13747to your site's standards for coding practice. 13748 13749The @file{commitinfo} file has the standard form for script hooks 13750(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13751a command to execute. It supports only the DEFAULT keywords. 13752 13753@cindex format strings, commitinfo admin file 13754In addition to the common format strings (@pxref{syntax}), 13755@file{commitinfo} supports: 13756 13757@table @t 13758@item @{s@} 13759a list of the names of files to be committed 13760@end table 13761 13762@cindex commitinfo (admin file), updating legacy repositories 13763@cindex compatibility notes, commitinfo admin file 13764Currently, if no format strings are specified, a default 13765string of @samp{ %r/%p %@{s@}} will be appended to the command 13766line template before replacement is performed, but this 13767feature is deprecated. It is simply in place so that legacy 13768repositories will remain compatible with the new @sc{cvs} application. 13769For information on updating, @pxref{Updating Commit Files}. 13770 13771@cindex Exit status, of commitinfo 13772@cindex commitinfo (admin file), exit status 13773The first line with a regular expression matching the 13774directory within the repository will be used. If the 13775command returns a non-zero exit status the commit will 13776be aborted. 13777@c FIXME: need example(s) of what "directory within the 13778@c repository" means. 13779 13780@cindex @file{commitinfo}, working directory 13781@cindex @file{commitinfo}, command environment 13782The command will be run in the root of the workspace 13783containing the new versions of any files the user would like 13784to modify (commit), @emph{or in a copy of the workspace on 13785the server (@pxref{Remote repositories})}. If a file is 13786being removed, there will be no copy of the file under the 13787current directory. If a file is being added, there will be 13788no corresponding archive file in the repository unless the 13789file is being resurrected. 13790 13791Note that both the repository directory and the corresponding 13792Attic (@pxref{Attic}) directory may need to be checked to 13793locate the archive file corresponding to any given file being 13794committed. Much of the information about the specific commit 13795request being made, including the destination branch, commit 13796message, and command line options specified, is not available 13797to the command. 13798 13799@c FIXME: should discuss using commitinfo to control 13800@c who has checkin access to what (e.g. Joe can check into 13801@c directories a, b, and c, and Mary can check into 13802@c directories b, c, and d--note this case cannot be 13803@c conveniently handled with unix groups). Of course, 13804@c adding a new set of features to CVS might be a more 13805@c natural way to fix this problem than telling people to 13806@c use commitinfo. 13807@c FIXME: Should make some reference, especially in 13808@c the context of controlling who has access, to the fact 13809@c that commitinfo can be circumvented. Perhaps 13810@c mention SETXID (but has it been carefully examined 13811@c for holes?). This fits in with the discussion of 13812@c general CVS security in "Password authentication 13813@c security" (the bit which is not pserver-specific). 13814 13815@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13816@node verifymsg 13817@appendixsubsec Verifying log messages 13818@cindex @file{verifymsg} (admin file) 13819@cindex Log message, verifying 13820@cindex logging, commits 13821 13822Once you have entered a log message, you can evaluate 13823that message to check for specific content, such as 13824a bug ID. Use the @file{verifymsg} file to 13825specify a program that is used to verify the log message. 13826This program could be a simple script that checks 13827that the entered message contains the required fields. 13828 13829The @file{verifymsg} file is often most useful together 13830with the @file{rcsinfo} file, which can be used to 13831specify a log message template (@pxref{rcsinfo}). 13832 13833The @file{verifymsg} file has the standard form for script hooks 13834(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13835a command to execute. It supports only the DEFAULT keywords. 13836 13837@cindex format strings, verifymsg admin file 13838In addition to the common format strings (@pxref{syntax}), 13839@file{verifymsg} supports: 13840 13841@table @t 13842@item l 13843the full path to the file containing the log message to be verified 13844@item @{sV@} 13845File attributes, where: 13846@table @t 13847@item s 13848file name 13849@item V 13850old version number (pre-checkin) 13851@end table 13852@end table 13853 13854@cindex verifymsg (admin/commit file), updating legacy repositories 13855@cindex compatibility notes, verifymsg admin file 13856Currently, if no format strings are specified, a default 13857string of @samp{ %l} will be appended to the command 13858line template before replacement is performed, but this 13859feature is deprecated. It is simply in place so that legacy 13860repositories will remain compatible with the new @sc{cvs} application. 13861For information on updating, @pxref{Updating Commit Files}. 13862 13863One thing that should be noted is that the @samp{ALL} 13864keyword is not supported. If more than one matching 13865line is found, the first one is used. This can be 13866useful for specifying a default verification script in a 13867directory, and then overriding it in a subdirectory. 13868 13869@cindex Exit status, of @file{verifymsg} 13870If the verification script exits with a non-zero exit status, 13871the commit is aborted. 13872 13873@cindex @file{verifymsg}, changing the log message 13874In the default configuration, CVS allows the 13875verification script to change the log message. This is 13876controlled via the RereadLogAfterVerify CVSROOT/config 13877option. 13878 13879When @samp{RereadLogAfterVerify=always} or 13880@samp{RereadLogAfterVerify=stat}, the log message will 13881either always be reread after the verification script 13882is run or reread only if the log message file status 13883has changed. 13884 13885@xref{config}, for more on CVSROOT/config options. 13886 13887It is NOT a good idea for a @file{verifymsg} script to 13888interact directly with the user in the various 13889client/server methods. For the @code{pserver} method, 13890there is no protocol support for communicating between 13891@file{verifymsg} and the client on the remote end. For the 13892@code{ext} and @code{server} methods, it is possible 13893for CVS to become confused by the characters going 13894along the same channel as the CVS protocol 13895messages. See @ref{Remote repositories}, for more 13896information on client/server setups. In addition, at the time 13897the @file{verifymsg} script runs, the CVS 13898server has locks in place in the repository. If control is 13899returned to the user here then other users may be stuck waiting 13900for access to the repository. 13901 13902This option can be useful if you find yourself using an 13903rcstemplate that needs to be modified to remove empty 13904elements or to fill in default values. It can also be 13905useful if the rcstemplate has changed in the repository 13906and the CVS/Template was not updated, but is able to be 13907adapted to the new format by the verification script 13908that is run by @file{verifymsg}. 13909 13910An example of an update might be to change all 13911occurrences of 'BugId:' to be 'DefectId:' (which can be 13912useful if the rcstemplate has recently been changed and 13913there are still checked-out user trees with cached 13914copies in the CVS/Template file of the older version). 13915 13916Another example of an update might be to delete a line 13917that contains 'BugID: none' from the log message after 13918validation of that value as being allowed is made. 13919 13920@menu 13921* verifymsg example:: Verifymsg example 13922@end menu 13923 13924@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13925@node verifymsg example 13926@appendixsubsubsec Verifying log messages 13927@cindex verifymsg, example 13928The following is a little silly example of a 13929@file{verifymsg} file, together with the corresponding 13930@file{rcsinfo} file, the log message template and a 13931verification script. We begin with the log message template. 13932We want to always record a bug-id number on the first 13933line of the log message. The rest of log message is 13934free text. The following template is found in the file 13935@file{/usr/cvssupport/tc.template}. 13936 13937@example 13938BugId: 13939@end example 13940 13941The script @file{/usr/cvssupport/bugid.verify} is used to 13942evaluate the log message. 13943 13944@example 13945#!/bin/sh 13946# 13947# bugid.verify filename 13948# 13949# Verify that the log message contains a valid bugid 13950# on the first line. 13951# 13952if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 13953 exit 0 13954elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 13955 # It is okay to allow commits with 'BugId: none', 13956 # but do not put that text into the real log message. 13957 grep -v '^BugId:[ ]*none$' > $1.rewrite 13958 mv $1.rewrite $1 13959 exit 0 13960else 13961 echo "No BugId found." 13962 exit 1 13963fi 13964@end example 13965 13966The @file{verifymsg} file contains this line: 13967 13968@example 13969^tc /usr/cvssupport/bugid.verify %l 13970@end example 13971 13972The @file{rcsinfo} file contains this line: 13973 13974@example 13975^tc /usr/cvssupport/tc.template 13976@end example 13977 13978The @file{config} file contains this line: 13979 13980@example 13981RereadLogAfterVerify=always 13982@end example 13983 13984 13985 13986@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13987@node loginfo 13988@appendixsubsec Loginfo 13989@cindex loginfo (admin file) 13990@cindex logging, commits 13991@cindex Storing log messages 13992@cindex Mailing log messages 13993@cindex Distributing log messages 13994@cindex Log messages 13995 13996The @file{loginfo} file is used to control where log information is sent after 13997versioned changes are made to repository archive files and after directories 13998are added ot the repository. @ref{posttag} for how to log tagging 13999information and @ref{postadmin} for how to log changes due to the @code{admin} 14000command. 14001 14002The @file{loginfo} file has the standard form for script hooks 14003(@pxref{Trigger Scripts}), where each line is a regular expression followed by 14004a command to execute. It supports the ALL and DEFAULT keywords. 14005 14006Any specified scripts are called: 14007 14008@table @code 14009@item commit 14010Once per directory, immediately after a successfully completing the commit of 14011all files within that directory. 14012@item import 14013Once per import, immediately after completion of all write operations. 14014@item add 14015Immediately after the successful @code{add} of a directory. 14016@end table 14017 14018Any script called via @file{loginfo} will be fed the log information on its 14019standard input. Note that the filter program @strong{must} read @strong{all} 14020of the log information from its standard input or @sc{cvs} may fail with a 14021broken pipe signal. 14022 14023@cindex format strings, loginfo admin file 14024In addition to the common format strings (@pxref{syntax}), 14025@file{loginfo} supports: 14026 14027@table @t 14028@item @{stVv@} 14029File attributes, where: 14030@table @t 14031@item s 14032file name 14033@item T 14034tag name of destination, or the empty string when there is no associated 14035tag name (this usually means the trunk) 14036@item V 14037old version number (pre-checkin) 14038@item v 14039new version number (post-checkin) 14040@end table 14041@end table 14042 14043For example, some valid format strings are @samp{%%}, 14044@samp{%s}, @samp{%@{s@}}, and @samp{%@{stVv@}}. 14045 14046@cindex loginfo (admin file), updating legacy repositories 14047@cindex compatibility notes, loginfo admin file 14048Currently, if @samp{UseNewInfoFmtStrings} is not set in the @file{config} 14049administration file (@pxref{config}), the format strings will be substituted 14050as they were in past versions of @sc{cvs}, but this feature is deprecated. 14051It is simply in place so that legacy repositories will remain compatible with 14052the new @sc{cvs} application. For information on updating, 14053please see @ref{Updating Commit Files}. 14054 14055As an example, if @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%p} 14056and @samp{%@{sVv@}} are the format strings, and three files (@t{ChangeLog}, 14057@t{Makefile}, @t{foo.c}) were modified, the output might be: 14058 14059@example 14060yoyodyne/tc ChangeLog 1.1 1.2 Makefile 1.3 1.4 foo.c 1.12 1.13 14061@end example 14062 14063Note: when @sc{cvs} is accessing a remote repository, 14064@file{loginfo} will be run on the @emph{remote} 14065(i.e., server) side, not the client side (@pxref{Remote 14066repositories}). 14067 14068@menu 14069* loginfo example:: Loginfo example 14070* Keeping a checked out copy:: Updating a tree on every checkin 14071@end menu 14072 14073@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14074@node loginfo example 14075@appendixsubsubsec Loginfo example 14076 14077The following @file{loginfo} file, together with the 14078tiny shell-script below, appends all log messages 14079to the file @file{$CVSROOT/CVSROOT/commitlog}, 14080and any commits to the administrative files (inside 14081the @file{CVSROOT} directory) are also logged in 14082@file{/usr/adm/cvsroot-log}. 14083Commits to the @file{prog1} directory are mailed to @t{ceder}. 14084 14085@c FIXME: is it a CVS feature or bug that only the 14086@c first matching line is used? It is documented 14087@c above, but is it useful? For example, if we wanted 14088@c to run both "cvs-log" and "Mail" for the CVSROOT 14089@c directory, it is kind of awkward if 14090@c only the first matching line is used. 14091@example 14092ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 14093^CVSROOT\(/\|$\) /usr/local/bin/cvs-log /usr/adm/cvsroot-log $USER 14094^prog1\(/\|$\) Mail -s "%p %s" ceder 14095@end example 14096 14097The shell-script @file{/usr/local/bin/cvs-log} looks 14098like this: 14099 14100@example 14101#!/bin/sh 14102(echo "------------------------------------------------------"; 14103 echo -n "$2 "; 14104 date; 14105 echo; 14106 cat) >> $1 14107@end example 14108 14109 14110 14111@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14112@node Keeping a checked out copy 14113@appendixsubsubsec Keeping a checked out copy 14114 14115@c What other index entries? It seems like 14116@c people might want to use a lot of different 14117@c words for this functionality. 14118@cindex Keeping a checked out copy 14119@cindex Checked out copy, keeping 14120@cindex Web pages, maintaining with CVS 14121 14122It is often useful to maintain a directory tree which 14123contains files which correspond to the latest version 14124in the repository. For example, other developers might 14125want to refer to the latest sources without having to 14126check them out, or you might be maintaining a web site 14127with @sc{cvs} and want every checkin to cause the files 14128used by the web server to be updated. 14129@c Can we offer more details on the web example? Or 14130@c point the user at how to figure it out? This text 14131@c strikes me as sufficient for someone who already has 14132@c some idea of what we mean but not enough for the naive 14133@c user/sysadmin to understand it and set it up. 14134 14135The way to do this is by having loginfo invoke 14136@code{cvs update}. Doing so in the naive way will 14137cause a problem with locks, so the @code{cvs update} 14138must be run in the background. 14139@c Should we try to describe the problem with locks? 14140@c It seems like a digression for someone who just 14141@c wants to know how to make it work. 14142@c Another choice which might work for a single file 14143@c is to use "cvs -n update -p" which doesn't take 14144@c out locks (I think) but I don't see many advantages 14145@c of that and we might as well document something which 14146@c works for multiple files. 14147Here is an example for unix (this should all be on one line): 14148 14149@example 14150^cyclic-pages\(/\|$\) (date; cat; (sleep 2; cd /u/www/local-docs; 14151 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 14152@end example 14153 14154This will cause checkins to repository directory @code{cyclic-pages} 14155and its subdirectories to update the checked 14156out tree in @file{/u/www/local-docs}. 14157@c More info on some of the details? The "sleep 2" is 14158@c so if we are lucky the lock will be gone by the time 14159@c we start and we can wait 2 seconds instead of 30. 14160 14161 14162 14163@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14164@node postadmin 14165@appendixsubsec Logging admin commands 14166@cindex postadmin (admin file) 14167@cindex script hook, postadmin 14168@cindex Admin commands, logging 14169 14170The @file{postadmin} file defines programs to execute after an @code{admin} 14171command modifies files. The @file{postadmin} file has the standard form 14172for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14173expression followed by a command to execute. It supports the ALL and DEFAULT 14174keywords. 14175 14176@cindex format strings, postadmin admin file 14177The @file{postadmin} file supports no format strings other than the common 14178ones (@pxref{syntax}), 14179 14180 14181 14182@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14183@node taginfo 14184@appendixsubsec Taginfo 14185@cindex taginfo (admin file) 14186@cindex script hook, taginfo 14187@cindex Tags, logging 14188@cindex Tags, verifying 14189The @file{taginfo} file defines programs to execute 14190when someone executes a @code{tag} or @code{rtag} 14191command. The @file{taginfo} file has the standard form 14192for script hooks (@pxref{Trigger Scripts}), where each line 14193is a regular expression followed by a command to execute. 14194It supports the ALL and DEFAULT keywords. 14195 14196@cindex format strings, taginfo admin file 14197In addition to the common format strings (@pxref{syntax}), 14198@file{taginfo} supports: 14199 14200@table @t 14201@item b 14202tag type (@code{T} for branch, @code{N} for not-branch, or @code{?} for 14203unknown, as during delete operations) 14204@item o 14205operation (@code{add} for @code{tag}, @code{mov} for @code{tag -F}, or 14206@code{del} for @code{tag -d}) 14207@item t 14208new tag name 14209@item @{sTVv@} 14210file attributes, where: 14211@table @t 14212@item s 14213file name 14214@item T 14215tag name of destination, or the empty string when there is no associated 14216tag name (this usually means the trunk) 14217@item V 14218old version number (for a move or delete operation) 14219@item v 14220new version number (for an add or move operation) 14221@end table 14222@end table 14223 14224For example, some valid format strings are @samp{%%}, @samp{%p}, @samp{%t}, 14225@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 14226 14227@cindex taginfo (admin file), updating legacy repositories 14228@cindex compatibility notes, taginfo admin file 14229Currently, if no format strings are specified, a default 14230string of @samp{ %t %o %p %@{sv@}} will be appended to the command 14231line template before replacement is performed, but this 14232feature is deprecated. It is simply in place so that legacy 14233repositories will remain compatible with the new @sc{cvs} application. 14234For information on updating, @pxref{Updating Commit Files}. 14235 14236@cindex Exit status, of taginfo admin file 14237@cindex taginfo (admin file), exit status 14238A non-zero exit of the filter program will cause the tag to be 14239aborted. 14240 14241Here is an example of using @file{taginfo} to log @code{tag} and @code{rtag} 14242commands. In the @file{taginfo} file put: 14243 14244@example 14245ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %@{sVv@} 14246@end example 14247 14248@noindent 14249Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 14250following script: 14251 14252@example 14253#!/bin/sh 14254echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 14255@end example 14256 14257 14258 14259@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14260@node posttag 14261@appendixsubsec Logging tags 14262@cindex posttag (admin file) 14263@cindex script hook, posttag 14264@cindex Tags, logging 14265 14266The @file{posttag} file defines programs to execute after a @code{tag} or 14267@code{rtag} command modifies files. The @file{posttag} file has the standard 14268form for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14269expression followed by a command to execute. It supports the ALL and DEFAULT 14270keywords. 14271 14272@cindex format strings, posttag admin file 14273The @file{posttag} admin file supports the same format strings as the 14274@file{taginfo} file (@pxref{taginfo}), 14275 14276 14277 14278@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14279@node postwatch 14280@appendixsubsec Logging watch commands 14281@cindex postwatch (admin file) 14282@cindex script hook, postwatch 14283@cindex Watch family of commands, logging 14284 14285The @file{postwatch} file defines programs to execute after any command (for 14286instance, @code{watch}, @code{edit}, @code{unedit}, or @code{commit}) modifies 14287any @file{CVS/fileattr} file in the repository (@pxref{Watches}). The 14288@file{postwatch} file has the standard form for script hooks 14289(@pxref{Trigger Scripts}), where each line is a regular expression followed by 14290a command to execute. It supports the ALL and DEFAULT keywords. 14291 14292@cindex format strings, postwatch admin file 14293The @file{postwatch} file supports no format strings other than the common 14294ones (@pxref{syntax}), but it is worth noting that the @code{%c} format string 14295may not be replaced as you might expect. Client runs of @code{edit} and 14296@code{unedit} can sometimes skip contacting the @sc{cvs} server and cache the 14297notification of the file attribute change to be sent the next time the client 14298contacts the server for whatever other reason, 14299 14300 14301 14302@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14303@node preproxy 14304@appendixsubsec Launch a Script before Proxying 14305@cindex preproxy (admin file) 14306@cindex script hook, preproxy 14307@cindex Write proxy, verifying 14308@cindex Write proxy, logging 14309 14310The @file{preproxy} file defines programs to execute after a secondary 14311server receives a write request from a client, just before it starts up the 14312primary server and becomes a write proxy. This hook could be used to 14313dial a modem, launch an SSH tunnel, establish a VPN, or anything else that 14314might be necessary to do before contacting the primary server. 14315 14316@file{preproxy} scripts are called once, at the time of the write request, with 14317the repository argument (if requested) set from the topmost directory sent by 14318the client. 14319 14320The @file{preproxy} file has the standard form 14321for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14322expression followed by a command to execute. It supports the ALL and DEFAULT 14323keywords. 14324 14325@cindex format strings, preproxy admin file 14326In addition to the common format strings, the @file{preproxy} file supports the 14327following format string: 14328 14329@table @t 14330@item P 14331the CVSROOT string which specifies the primary server 14332@end table 14333 14334 14335 14336@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14337@node postproxy 14338@appendixsubsec Launch a Script after Proxying 14339@cindex postproxy (admin file) 14340@cindex script hook, postproxy 14341@cindex Write proxy, logging 14342@cindex Write proxy, pull updates 14343@cindex secondary server, pull updates 14344 14345The @file{postproxy} file defines programs to execute after a secondary 14346server notes that the connection to the primary server has shut down and before 14347it releases the client by shutting down the connection to the client. 14348This could hook could be used to 14349disconnect a modem, an SSH tunnel, a VPN, or anything else that 14350might be necessary to do after contacting the primary server. This hook should 14351also be used to pull updates from the primary server before allowing the client 14352which did the write to disconnect since otherwise the client's next read 14353request may generate error messages and fail upon encountering an out of date 14354repository on the secondary server. 14355 14356@file{postproxy} scripts are called once per directory. 14357 14358The @file{postproxy} file has the standard form 14359for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14360expression followed by a command to execute. It supports the ALL and DEFAULT 14361keywords. 14362 14363@cindex format strings, postproxy admin file 14364In addition to the common format strings, the @file{postproxy} file supports 14365the following format string: 14366 14367@table @t 14368@item P 14369the CVSROOT string which specifies the primary server 14370@end table 14371 14372 14373 14374@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14375@node rcsinfo 14376@appendixsec Rcsinfo 14377@cindex rcsinfo (admin file) 14378@cindex Form for log message 14379@cindex Log message template 14380@cindex Template for log message 14381@cindex logging, commits 14382 14383The @file{rcsinfo} file can be used to specify a form to 14384edit when filling out the commit log. The 14385@file{rcsinfo} file has a syntax similar to the 14386@file{verifymsg}, @file{commitinfo} and @file{loginfo} 14387files. @xref{syntax}. Unlike the other files the second 14388part is @emph{not} a command-line template. Instead, 14389the part after the regular expression should be a full pathname to 14390a file containing the log message template. 14391 14392If the repository name does not match any of the 14393regular expressions in this file, the @samp{DEFAULT} 14394line is used, if it is specified. 14395 14396All occurrences of the name @samp{ALL} appearing as a 14397regular expression are used in addition to the first 14398matching regular expression or @samp{DEFAULT}. 14399 14400@c FIXME: should be offering advice, somewhere around 14401@c here, about where to put the template file. The 14402@c verifymsg example uses /usr/cvssupport but doesn't 14403@c say anything about what that directory is for or 14404@c whether it is hardwired into CVS or who creates 14405@c it or anything. In particular we should say 14406@c how to version control the template file. A 14407@c probably better answer than the /usr/cvssupport 14408@c stuff is to use checkoutlist (with xref to the 14409@c checkoutlist doc). 14410@c Also I am starting to see a connection between 14411@c this and the Keeping a checked out copy node. 14412@c Probably want to say something about that. 14413The log message template will be used as a default log 14414message. If you specify a log message with @samp{cvs 14415commit -m @var{message}} or @samp{cvs commit -f 14416@var{file}} that log message will override the 14417template. 14418 14419@xref{verifymsg}, for an example @file{rcsinfo} 14420file. 14421 14422When @sc{cvs} is accessing a remote repository, 14423the contents of @file{rcsinfo} at the time a directory 14424is first checked out will specify a template. This 14425template will be updated on all @samp{cvs update} 14426commands. It will also be added to new directories 14427added with a @samp{cvs add new-directory} command. 14428In versions of @sc{cvs} prior to version 1.12, the 14429@file{CVS/Template} file was not updated. If the 14430@sc{cvs} server is at version 1.12 or higher an older 14431client may be used and the @file{CVS/Template} will 14432be updated from the server. 14433 14434@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14435@node cvsignore 14436@appendixsec Ignoring files via cvsignore 14437@cindex cvsignore (admin file), global 14438@cindex Global cvsignore 14439@cindex Ignoring files 14440@c -- This chapter should maybe be moved to the 14441@c tutorial part of the manual? 14442 14443There are certain file names that frequently occur 14444inside your working copy, but that you don't want to 14445put under @sc{cvs} control. Examples are all the object 14446files that you get while you compile your sources. 14447Normally, when you run @samp{cvs update}, it prints a 14448line for each file it encounters that it doesn't know 14449about (@pxref{update output}). 14450 14451@sc{cvs} has a list of files (or sh(1) file name patterns) 14452that it should ignore while running @code{update}, 14453@code{import} and @code{release}. 14454@c -- Are those the only three commands affected? 14455This list is constructed in the following way. 14456 14457@itemize @bullet 14458@item 14459The list is initialized to include certain file name 14460patterns: names associated with @sc{cvs} 14461administration, or with other common source control 14462systems; common names for patch files, object files, 14463archive files, and editor backup files; and other names 14464that are usually artifacts of assorted utilities. 14465Currently, the default list of ignored file name 14466patterns is: 14467 14468@cindex Ignored files 14469@cindex Automatically ignored files 14470@example 14471 RCS SCCS CVS CVS.adm 14472 RCSLOG cvslog.* 14473 tags TAGS 14474 .make.state .nse_depinfo 14475 *~ #* .#* ,* _$* *$ 14476 *.old *.bak *.BAK *.orig *.rej .del-* 14477 *.a *.olb *.o *.obj *.so *.exe 14478 *.Z *.elc *.ln 14479 core 14480@end example 14481 14482@item 14483The per-repository list in 14484@file{$CVSROOT/CVSROOT/cvsignore} is appended to 14485the list, if that file exists. 14486 14487@item 14488The per-user list in @file{.cvsignore} in your home 14489directory is appended to the list, if it exists. 14490 14491@item 14492Any entries in the environment variable 14493@code{$CVSIGNORE} is appended to the list. 14494 14495@item 14496Any @samp{-I} options given to @sc{cvs} is appended. 14497 14498@item 14499As @sc{cvs} traverses through your directories, the contents 14500of any @file{.cvsignore} will be appended to the list. 14501The patterns found in @file{.cvsignore} are only valid 14502for the directory that contains them, not for 14503any sub-directories. 14504@end itemize 14505 14506In any of the 5 places listed above, a single 14507exclamation mark (@samp{!}) clears the ignore list. 14508This can be used if you want to store any file which 14509normally is ignored by @sc{cvs}. 14510 14511Specifying @samp{-I !} to @code{cvs import} will import 14512everything, which is generally what you want to do if 14513you are importing files from a pristine distribution or 14514any other source which is known to not contain any 14515extraneous files. However, looking at the rules above 14516you will see there is a fly in the ointment; if the 14517distribution contains any @file{.cvsignore} files, then 14518the patterns from those files will be processed even if 14519@samp{-I !} is specified. The only workaround is to 14520remove the @file{.cvsignore} files in order to do the 14521import. Because this is awkward, in the future 14522@samp{-I !} might be modified to override 14523@file{.cvsignore} files in each directory. 14524 14525Note that the syntax of the ignore files consists of a 14526series of lines, each of which contains a space 14527separated list of filenames. This offers no clean way 14528to specify filenames which contain spaces, but you can 14529use a workaround like @file{foo?bar} to match a file 14530named @file{foo bar} (it also matches @file{fooxbar} 14531and the like). Also note that there is currently no 14532way to specify comments. 14533@c FIXCVS? I don't _like_ this syntax at all, but 14534@c changing it raises all the usual compatibility 14535@c issues and I'm also not sure what to change it to. 14536 14537@node checkoutlist 14538@appendixsec The checkoutlist file 14539@cindex checkoutlist 14540 14541It may be helpful to use @sc{cvs} to maintain your own 14542files in the @file{CVSROOT} directory. For example, 14543suppose that you have a script @file{logcommit.pl} 14544which you run by including the following line in the 14545@file{commitinfo} administrative file: 14546 14547@example 14548ALL $CVSROOT/CVSROOT/logcommit.pl %r/%p %s 14549@end example 14550 14551To maintain @file{logcommit.pl} with @sc{cvs} you would 14552add the following line to the @file{checkoutlist} 14553administrative file: 14554 14555@example 14556logcommit.pl 14557@end example 14558 14559The format of @file{checkoutlist} is one line for each 14560file that you want to maintain using @sc{cvs}, giving 14561the name of the file, followed optionally by more whitespace 14562and any error message that should print if the file cannot be 14563checked out into CVSROOT after a commit: 14564 14565@example 14566logcommit.pl Could not update CVSROOT/logcommit.pl. 14567@end example 14568 14569After setting up @file{checkoutlist} in this fashion, 14570the files listed there will function just like 14571@sc{cvs}'s built-in administrative files. For example, 14572when checking in one of the files you should get a 14573message such as: 14574 14575@example 14576cvs commit: Rebuilding administrative file database 14577@end example 14578 14579@noindent 14580and the checked out copy in the @file{CVSROOT} 14581directory should be updated. 14582 14583Note that listing @file{passwd} (@pxref{Password 14584authentication server}) in @file{checkoutlist} is not 14585recommended for security reasons. 14586 14587For information about keeping a checkout out copy in a 14588more general context than the one provided by 14589@file{checkoutlist}, see @ref{Keeping a checked out 14590copy}. 14591 14592@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14593@node history file 14594@appendixsec The history file 14595@cindex History file 14596@cindex Log information, saving 14597 14598By default, the file @file{$CVSROOT/CVSROOT/history} is used 14599to log information for the @code{history} command (@pxref{history}). 14600This file name may be changed with the @samp{HistoryLogPath} and 14601@samp{HistorySearchPath} config options (@pxref{config}). 14602 14603The file format of the @file{history} file is 14604documented only in comments in the @sc{cvs} source 14605code, but generally programs should use the @code{cvs 14606history} command to access it anyway, in case the 14607format changes with future releases of @sc{cvs}. 14608 14609@node Variables 14610@appendixsec Expansions in administrative files 14611@cindex Internal variables 14612@cindex Variables 14613 14614Sometimes in writing an administrative file, you might 14615want the file to be able to know various things based 14616on environment @sc{cvs} is running in. There are 14617several mechanisms to do that. 14618 14619To find the home directory of the user running @sc{cvs} 14620(from the @code{HOME} environment variable), use 14621@samp{~} followed by @samp{/} or the end of the line. 14622Likewise for the home directory of @var{user}, use 14623@samp{~@var{user}}. These variables are expanded on 14624the server machine, and don't get any reasonable 14625expansion if pserver (@pxref{Password authenticated}) 14626is in use; therefore user variables (see below) may be 14627a better choice to customize behavior based on the user 14628running @sc{cvs}. 14629@c Based on these limitations, should we deprecate ~? 14630@c What is it good for? Are people using it? 14631 14632One may want to know about various pieces of 14633information internal to @sc{cvs}. A @sc{cvs} internal 14634variable has the syntax @code{$@{@var{variable}@}}, 14635where @var{variable} starts with a letter and consists 14636of alphanumeric characters and @samp{_}. If the 14637character following @var{variable} is a 14638non-alphanumeric character other than @samp{_}, the 14639@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 14640internal variables are: 14641 14642@table @code 14643@item CVSROOT 14644@cindex CVSROOT, internal variable 14645This is the absolute path to the current @sc{cvs} root directory. 14646@xref{Repository}, for a description of the various 14647ways to specify this, but note that the internal 14648variable contains just the directory and not any 14649of the access method information. 14650 14651@item RCSBIN 14652@cindex RCSBIN, internal variable 14653In @sc{cvs} 1.9.18 and older, this specified the 14654directory where @sc{cvs} was looking for @sc{rcs} 14655programs. Because @sc{cvs} no longer runs @sc{rcs} 14656programs, specifying this internal variable is now an 14657error. 14658 14659@item CVSEDITOR 14660@cindex CVSEDITOR, internal variable 14661@itemx EDITOR 14662@cindex EDITOR, internal variable 14663@itemx VISUAL 14664@cindex VISUAL, internal variable 14665These all expand to the same value, which is the editor 14666that @sc{cvs} is using. @xref{Global options}, for how 14667to specify this. 14668 14669@item USER 14670@cindex USER, internal variable 14671Username of the user running @sc{cvs} (on the @sc{cvs} 14672server machine). 14673When using pserver, this is the user specified in the repository 14674specification which need not be the same as the username the 14675server is running as (@pxref{Password authentication server}). 14676Do not confuse this with the environment variable of the same name. 14677 14678@item SESSIONID 14679@cindex COMMITID, internal variable 14680Unique Session ID of the @sc{cvs} process. This is a 14681random string of printable characters of at least 16 14682characters length. Users should assume that it may 14683someday grow to at most 256 characters in length. 14684 14685@item COMMITID 14686@cindex COMMITID, internal variable 14687Unique Session ID of the @sc{cvs} process. This is a 14688random string of printable characters of at least 16 14689characters length. Users should assume that it may 14690someday grow to at most 256 characters in length. 14691@end table 14692 14693If you want to pass a value to the administrative files 14694which the user who is running @sc{cvs} can specify, 14695use a user variable. 14696@cindex User variables 14697To expand a user variable, the 14698administrative file contains 14699@code{$@{=@var{variable}@}}. To set a user variable, 14700specify the global option @samp{-s} to @sc{cvs}, with 14701argument @code{@var{variable}=@var{value}}. It may be 14702particularly useful to specify this option via 14703@file{.cvsrc} (@pxref{~/.cvsrc}). 14704 14705For example, if you want the administrative file to 14706refer to a test directory you might create a user 14707variable @code{TESTDIR}. Then if @sc{cvs} is invoked 14708as 14709 14710@example 14711cvs -s TESTDIR=/work/local/tests 14712@end example 14713 14714@noindent 14715and the 14716administrative file contains @code{sh 14717$@{=TESTDIR@}/runtests}, then that string is expanded 14718to @code{sh /work/local/tests/runtests}. 14719 14720All other strings containing @samp{$} are reserved; 14721there is no way to quote a @samp{$} character so that 14722@samp{$} represents itself. 14723 14724Environment variables passed to administrative files are: 14725 14726@table @code 14727@cindex environment variables, passed to administrative files 14728 14729@item CVS_USER 14730@cindex CVS_USER, environment variable 14731The @sc{cvs}-specific username provided by the user, if it 14732can be provided (currently just for the pserver access 14733method), and to the empty string otherwise. (@code{CVS_USER} 14734and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 14735is used to map @sc{cvs} usernames to system usernames.) 14736 14737@item LOGNAME 14738@cindex LOGNAME, environment variable 14739The username of the system user. 14740 14741@item USER 14742@cindex USER, environment variable 14743Same as @code{LOGNAME}. 14744Do not confuse this with the internal variable of the same name. 14745@end table 14746 14747@node config 14748@appendixsec The CVSROOT/config configuration file 14749 14750@cindex configuration file 14751@cindex config, in CVSROOT 14752@cindex CVSROOT/config 14753 14754Usually, the @file{config} file is found at @file{$CVSROOT/CVSROOT/config}, 14755but this may be overridden on the @code{pserver} and @code{server} command 14756lines (@pxref{server & pserver}). 14757 14758The administrative file @file{config} contains various 14759miscellaneous settings which affect the behavior of 14760@sc{cvs}. The syntax is slightly different from the 14761other administrative files. 14762 14763Leading white space on any line is ignored, though the syntax is very strict 14764and will reject spaces and tabs almost anywhere else. 14765 14766Empty lines, lines containing nothing but white space, and lines which start 14767with @samp{#} (discounting any leading white space) are ignored. 14768 14769@c FIXME: where do we define comments for the other 14770@c administrative files. 14771Other lines consist of the optional leading white space, a keyword, @samp{=}, 14772and a value. Please note again that this syntax is very strict. 14773Extraneous spaces or tabs, other than the leading white space, are not 14774permitted on these lines. 14775@c See comments in parseinfo.c:parse_config for more 14776@c discussion of this strictness. 14777 14778As of CVS 1.12.13, lines of the form @samp{[@var{CVSROOT}]} mark the subsequent 14779section of the config file as applying only to certain repositories. Multiple 14780@samp{[@var{CVSROOT}]} lines without intervening 14781@samp{@var{KEYWORD}=@var{VALUE}} pairs cause processing to fall through, 14782processing subsequent keywords for any root in the list. Finally, keywords 14783and values which appear before any @samp{[@var{CVSROOT}]} lines are defaults, 14784and may to apply to any repository. For example, consider the following file: 14785 14786@example 14787# Defaults 14788LogHistory=TMAR 14789 14790[/cvsroots/team1] 14791 LockDir=/locks/team1 14792 14793[/cvsroots/team2] 14794 LockDir=/locks/team2 14795 14796[/cvsroots/team3] 14797 LockDir=/locks/team3 14798 14799[/cvsroots/team4] 14800 LockDir=/locks/team4 14801 14802[/cvsroots/team3] 14803[/cvsroots/team4] 14804 # Override logged commands for teams 3 & 4. 14805 LogHistory=all 14806@end example 14807 14808This example file sets up separate lock directories for each project, as well 14809as a default set of logged commands overridden for the example's team 3 & 14810team 4. This syntax could be useful, for instance, if you wished to share a 14811single config file, for instance @file{/etc/cvs.conf}, among several 14812repositories. 14813 14814Currently defined keywords are: 14815 14816@table @code 14817@cindex HistoryLogPath, in CVSROOT/config 14818@item HistorySearchPath=@var{pattern} 14819Request that @sc{cvs} look for its history information in files matching 14820@var{pattern}, which is a standard UNIX file glob. If @var{pattern} matches 14821multiple files, all will be searched in lexicographically sorted order. 14822@xref{history}, and @ref{history file}, for more. 14823 14824If no value is supplied for this option, it defaults to 14825@file{$CVSROOT/CVSROOT/history}. 14826 14827@cindex HistorySearchPath, in CVSROOT/config 14828@item HistoryLogPath=@var{path} 14829Control where @sc{cvs} logs its history. If the file does not exist, @sc{cvs} 14830will attempt to create it. Format strings, as available to the GNU C 14831@code{strftime} function and often the UNIX date command, and the string 14832@var{$CVSROOT} will be substituted in this path. For example, consider the 14833line: 14834 14835@example 14836HistoryLogPath=$CVSROOT/CVSROOT/history/%Y-%m-%d 14837@end example 14838 14839This line would cause @sc{cvs} to attempt to create its history file in a 14840subdirectory (@file{history}) of the configuration directory (@file{CVSROOT}) 14841with a name equal to the current date representation in the ISO8601 format (for 14842example, on May 11, 2005, @sc{cvs} would attempt to log its history under the 14843repository root directory in a file named @file{CVSROOT/history/2005-05-11}). 14844@xref{history}, and @ref{history file}, for more. 14845 14846If no value is supplied for this option, it defaults to 14847@file{$CVSROOT/CVSROOT/history}. 14848 14849@cindex ImportNewFilesToVendorBranchOnly, in CVSROOT/config 14850@cindex import, config admin file 14851@cindex config (admin file), import 14852@item ImportNewFilesToVendorBranchOnly=@var{value} 14853Specify whether @code{cvs import} should always behave as if the 14854@samp{-X} flag was specified on the command line. 14855@var{value} may be either @samp{yes} or @samp{no}. If set to @samp{yes}, 14856all uses of @code{cvs import} on the repository will behave as if the 14857@samp{-X} flag was set. The default value is @samp{no}. 14858 14859@cindex KeywordExpand, in CVSROOT/config 14860@item KeywordExpand=@var{value} 14861Specify @samp{i} followed by a list of keywords to be expanded 14862(for example, @samp{KeywordExpand=iMYCVS,Name,Date}), 14863or @samp{e} followed by a list of keywords not to be expanded 14864(for example, @samp{KeywordExpand=eCVSHeader}). 14865For more on keyword expansion, see @ref{Configuring keyword expansion}. 14866 14867@cindex LocalKeyword, in CVSROOT/config 14868@item LocalKeyword=@var{value} 14869Specify a local alias for a standard keyword. 14870For example, @samp{LocalKeyword=MYCVS=CVSHeader}. 14871For more on local keywords, see @ref{Keyword substitution}. 14872 14873@cindex LockDir, in CVSROOT/config 14874@item LockDir=@var{directory} 14875Put @sc{cvs} lock files in @var{directory} rather than 14876directly in the repository. This is useful if you want 14877to let users read from the repository while giving them 14878write access only to @var{directory}, not to the 14879repository. 14880It can also be used to put the locks on a very fast 14881in-memory file system to speed up locking and unlocking 14882the repository. 14883You need to create @var{directory}, but 14884@sc{cvs} will create subdirectories of @var{directory} as it 14885needs them. For information on @sc{cvs} locks, see 14886@ref{Concurrency}. 14887 14888@c Mention this in Compatibility section? 14889Before enabling the LockDir option, make sure that you 14890have tracked down and removed any copies of @sc{cvs} 1.9 or 14891older. Such versions neither support LockDir, nor will 14892give an error indicating that they don't support it. 14893The result, if this is allowed to happen, is that some 14894@sc{cvs} users will put the locks one place, and others will 14895put them another place, and therefore the repository 14896could become corrupted. @sc{cvs} 1.10 does not support 14897LockDir but it will print a warning if run on a 14898repository with LockDir enabled. 14899 14900@cindex LogHistory, in CVSROOT/config 14901@item LogHistory=@var{value} 14902Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). 14903Default of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log 14904all transactions. Any subset of the default is 14905legal. (For example, to only log transactions that modify the 14906@file{*,v} files, use @samp{LogHistory=TMAR}.) To disable history logging 14907completely, use @samp{LogHistory=}. 14908 14909@cindex MaxCommentLeaderLength, in CVSROOT/config 14910@cindex Log keyword, configuring substitution behavior 14911@item MaxCommentLeaderLength=@var{length} 14912Set to some length, in bytes, where a trailing @samp{k}, @samp{M}, @samp{G}, 14913or @samp{T} causes the preceding nubmer to be interpreted as kilobytes, 14914megabytes, gigabytes, or terrabytes, respectively, will cause 14915@code{$@splitrcskeyword{Log}$} keywords (@pxref{Keyword substitution}), with 14916more than @var{length} bytes preceding it on a line to be ignored (or to fall 14917back on the comment leader set in the RCS archive file - see 14918@code{UseArchiveCommentLeader} below). Defaults to 20 bytes to allow checkouts 14919to proceed normally when they include binary files containing 14920@code{$@splitrcskeyword{Log}$} keywords and which users have neglected to mark 14921as binary. 14922 14923@cindex MinCompressionLevel, in CVSROOT/config 14924@cindex MaxCompressionLevel, in CVSROOT/config 14925@cindex Compression levels, restricting on server 14926@item MinCompressionLevel=@var{value} 14927@itemx MaxCompressionLevel=@var{value} 14928Restricts the level of compression used by the @sc{cvs} server to a @var{value} 14929between 0 and 9. @var{value}s 1 through 9 are the same @sc{zlib} compression 14930levels accepted by the @samp{-z} option (@pxref{Global options}), and 0 means 14931no compression. When one or both of these keys are set and a client requests a 14932level outside the specified range, the server will simply use the closest 14933permissable level. Clients will continue compressing at the level requested by 14934the user. 14935 14936The exception is when level 0 (no compression) is not available and the client 14937fails to request any compression. The @sc{cvs} server will then exit with an 14938error message when it becomes apparent that the client is not going to request 14939compression. This will not happen with clients version 1.12.13 and later since 14940these client versions allow the server to notify them that they must request 14941some level of compression. 14942 14943@ignore 14944@cindex PreservePermissions, in CVSROOT/config 14945@item PreservePermissions=@var{value} 14946Enable support for saving special device files, 14947symbolic links, file permissions and ownerships in the 14948repository. The default value is @samp{no}. 14949@xref{Special Files}, for the full implications of using 14950this keyword. 14951@end ignore 14952 14953@cindex PrimaryServer, in CVSROOT/config 14954@cindex Primary server 14955@cindex Secondary server 14956@cindex proxy, write 14957@cindex write proxy 14958@item PrimaryServer=@var{CVSROOT} 14959When specified, and the repository specified by @var{CVSROOT} is not the one 14960currently being accessed, then the server will turn itself into a transparent 14961proxy to @var{CVSROOT} for write requests. The @var{hostname} configured as 14962part of @var{CVSROOT} must resolve to the same string returned by the 14963@command{uname} command on the primary server for this to work. Host name 14964resolution is performed via some combination of @command{named}, a broken out 14965line from @file{/etc/hosts}, and the Network Information Service (NIS or YP), 14966depending on the configuration of the particular system. 14967 14968Only the @samp{:ext:} method is 14969currently supported for primaries (actually, @samp{:fork:} is supported as 14970well, but only for testing - if you find another use for accessing a primary 14971via the @samp{:fork:} method, please send a note to @email{bug-cvs@@nongnu.org} 14972about it). See @ref{Write proxies} for more on configuring and using write 14973proxies. 14974 14975@cindex RCSBIN, in CVSROOT/config 14976@item RCSBIN=@var{bindir} 14977For @sc{cvs} 1.9.12 through 1.9.18, this setting told 14978@sc{cvs} to look for @sc{rcs} programs in the 14979@var{bindir} directory. Current versions of @sc{cvs} 14980do not run @sc{rcs} programs; for compatibility this 14981setting is accepted, but it does nothing. 14982 14983@cindex RereadLogAfterVerify, in CVSROOT/config 14984@cindex @file{verifymsg}, changing the log message 14985@item RereadLogAfterVerify=@var{value} 14986Modify the @samp{commit} command such that CVS will reread the 14987log message after running the program specified by @file{verifymsg}. 14988@var{value} may be one of @samp{yes} or @samp{always}, indicating that 14989the log message should always be reread; @samp{no} 14990or @samp{never}, indicating that it should never be 14991reread; or @var{value} may be @samp{stat}, indicating 14992that the file should be checked with the file system 14993@samp{stat()} function to see if it has changed (see warning below) 14994before rereading. The default value is @samp{always}. 14995 14996@strong{Note: the `stat' mode can cause CVS to pause for up to 14997one extra second per directory committed. This can be less IO and 14998CPU intensive but is not recommended for use with large repositories} 14999 15000@xref{verifymsg}, for more information on how verifymsg 15001may be used. 15002 15003@cindex SystemAuth, in CVSROOT/config 15004@item SystemAuth=@var{value} 15005If @var{value} is @samp{yes}, then pserver should check 15006for users in the system's user database if not found in 15007@file{CVSROOT/passwd}. If it is @samp{no}, then all 15008pserver users must exist in @file{CVSROOT/passwd}. 15009The default is @samp{yes}. For more on pserver, see 15010@ref{Password authenticated}. 15011 15012@cindex TmpDir, in config 15013@cindex temporary files, location of 15014@cindex temporary directory, set in config 15015@item TmpDir=@var{path} 15016Specify @var{path} as the directory to create temporary files in. 15017@xref{Global options}, for more on setting the path to the temporary 15018directory. This option first appeared with @sc{cvs} release 1.12.13. 15019 15020@cindex TopLevelAdmin, in CVSROOT/config 15021@item TopLevelAdmin=@var{value} 15022Modify the @samp{checkout} command to create a 15023@samp{CVS} directory at the top level of the new 15024working directory, in addition to @samp{CVS} 15025directories created within checked-out directories. 15026The default value is @samp{no}. 15027 15028This option is useful if you find yourself performing 15029many commands at the top level of your working 15030directory, rather than in one of the checked out 15031subdirectories. The @file{CVS} directory created there 15032will mean you don't have to specify @code{CVSROOT} for 15033each command. It also provides a place for the 15034@file{CVS/Template} file (@pxref{Working directory 15035storage}). 15036 15037@cindex UseArchiveCommentLeader, in CVSROOT/config 15038@cindex Log keyword, configuring substitution behavior 15039@item UseArchiveCommentLeader=@var{value} 15040Set to @code{true}, if the text preceding a @code{$@splitrcskeyword{Log}$} 15041keyword is found to exceed @code{MaxCommentLeaderLength} (above) bytes, then 15042the comment leader set in the RCS archive file (@pxref{admin}), if any, will 15043be used instead. If there is no comment leader set in the archive file or 15044@var{value} is set to @samp{false}, then the keyword will not be expanded 15045(@pxref{Keyword list}). To force the comment leader in the RCS archive file to 15046be used exclusively (and @code{$@splitrcskeyword{Log}$} expansion skipped in 15047files where the comment leader has not been set in the archive file), set 15048@var{value} and set @code{MaxCommentLeaderLength} to @code{0}. 15049 15050@cindex UseNewInfoFmtStrings, in CVSROOT/config 15051@cindex format strings, config admin file 15052@cindex config (admin file), updating legacy repositories 15053@cindex compatibility notes, config admin file 15054@item UseNewInfoFmtStrings=@var{value} 15055Specify whether @sc{cvs} should support the new or old command line 15056template model for the commit support files (@pxref{commit files}). 15057This configuration variable began life in deprecation and is only here 15058in order to give people time to update legacy repositories to use the new 15059format string syntax before support for the old syntax is removed. For 15060information on updating your repository to support the new model, 15061please see @ref{Updating Commit Files}. 15062 15063@emph{Note that new repositories (created with the @code{cvs init} command) 15064will have this value set to @samp{yes}, but the default value is @samp{no}.} 15065 15066@cindex UserAdminOptions, in CVSROOT/config 15067@item UserAdminOptions=@var{value} 15068Control what options will be allowed with the @code{cvs admin} 15069command (@pxref{admin}) for users not in the @code{cvsadmin} group. 15070The @var{value} string is a list of single character options 15071which should be allowed. If a user who is not a member of the 15072@code{cvsadmin} group tries to execute any @code{cvs admin} 15073option which is not listed they will will receive an error message 15074reporting that the option is restricted. 15075 15076If no @code{cvsadmin} group exists on the server, @sc{cvs} will 15077ignore the @code{UserAdminOptions} keyword (@pxref{admin}). 15078 15079When not specified, @code{UserAdminOptions} defaults to 15080@samp{k}. In other words, it defaults to allowing 15081users outside of the @code{cvsadmin} group to use the 15082@code{cvs admin} command only to change the default keyword 15083expansion mode for files. 15084 15085As an example, to restrict users not in the @code{cvsadmin} 15086group to using @code{cvs admin} to change the default keyword 15087substitution mode, lock revisions, unlock revisions, and 15088replace the log message, use @samp{UserAdminOptions=klum}. 15089@end table 15090 15091 15092 15093@c --------------------------------------------------------------------- 15094@node Environment variables 15095@appendix All environment variables which affect CVS 15096@cindex Environment variables 15097@cindex Reference manual for variables 15098 15099This is a complete list of all environment variables 15100that affect @sc{cvs} (Windows users, please bear with this list; 15101$VAR is equivalent to %VAR% at the Windows command prompt). 15102 15103@table @code 15104@cindex CVSIGNORE, environment variable 15105@item $CVSIGNORE 15106A whitespace-separated list of file name patterns that 15107@sc{cvs} should ignore. @xref{cvsignore}. 15108 15109@cindex CVSWRAPPERS, environment variable 15110@item $CVSWRAPPERS 15111A whitespace-separated list of file name patterns that 15112@sc{cvs} should treat as wrappers. @xref{Wrappers}. 15113 15114@cindex CVSREAD, environment variable 15115@cindex Read-only files, and CVSREAD 15116@item $CVSREAD 15117If this is set, @code{checkout} and @code{update} will 15118try hard to make the files in your working directory 15119read-only. When this is not set, the default behavior 15120is to permit modification of your working files. 15121 15122@cindex CVSREADONLYFS, environment variable 15123@item $CVSREADONLYFS 15124Turns on read-only repository mode. This allows one to 15125check out from a read-only repository, such as within 15126an anoncvs server, or from a @sc{cd-rom} repository. 15127 15128It has the same effect as if the @samp{-R} command-line 15129option is used. This can also allow the use of 15130read-only NFS repositories. 15131 15132@item $CVSUMASK 15133Controls permissions of files in the repository. See 15134@ref{File permissions}. 15135 15136@item $CVSROOT 15137Should contain the full pathname to the root of the @sc{cvs} 15138source repository (where the @sc{rcs} files are 15139kept). This information must be available to @sc{cvs} for 15140most commands to execute; if @code{$CVSROOT} is not set, 15141or if you wish to override it for one invocation, you 15142can supply it on the command line: @samp{cvs -d cvsroot 15143cvs_command@dots{}} Once you have checked out a working 15144directory, @sc{cvs} stores the appropriate root (in 15145the file @file{CVS/Root}), so normally you only need to 15146worry about this when initially checking out a working 15147directory. 15148 15149@item $CVSEDITOR 15150@cindex CVSEDITOR, environment variable 15151@itemx $EDITOR 15152@cindex EDITOR, environment variable 15153@itemx $VISUAL 15154@cindex VISUAL, environment variable 15155Specifies the program to use for recording log messages 15156during commit. @code{$CVSEDITOR} overrides 15157@code{$EDITOR}, which overrides @code{$VISUAL}. 15158See @ref{Committing your changes} for more or 15159@ref{Global options} for alternative ways of specifying a 15160log editor. 15161 15162@cindex PATH, environment variable 15163@item $PATH 15164If @code{$RCSBIN} is not set, and no path is compiled 15165into @sc{cvs}, it will use @code{$PATH} to try to find all 15166programs it uses. 15167 15168@cindex HOME, environment variable 15169@item $HOME 15170@cindex HOMEPATH, environment variable 15171@item $HOMEPATH 15172@cindex HOMEDRIVE, environment variable 15173@item $HOMEDRIVE 15174Used to locate the directory where the @file{.cvsrc} 15175file, and other such files, are searched. On Unix, @sc{cvs} 15176just checks for @code{HOME}. On Windows NT, the system will 15177set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 15178for example to @file{\joe}. On Windows 95, you'll 15179probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 15180@c We are being vague about whether HOME works on 15181@c Windows; see long comment in windows-NT/filesubr.c. 15182 15183@cindex CVS_RSH, environment variable 15184@item $CVS_RSH 15185Specifies the external program which @sc{cvs} connects with, 15186when @code{:ext:} access method is specified. 15187@pxref{Connecting via rsh}. 15188 15189@item $CVS_SERVER 15190Used in client-server mode when accessing a remote 15191repository using @sc{rsh}. It specifies the name of 15192the program to start on the server side (and any 15193necessary arguments) when accessing a remote repository 15194using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 15195The default value for @code{:ext:} and @code{:server:} is @code{cvs}; 15196the default value for @code{:fork:} is the name used to run the client. 15197@pxref{Connecting via rsh} 15198 15199@item $CVS_PASSFILE 15200Used in client-server mode when accessing the @code{cvs 15201login server}. Default value is @file{$HOME/.cvspass}. 15202@pxref{Password authentication client} 15203 15204@cindex CVS_CLIENT_PORT 15205@item $CVS_CLIENT_PORT 15206Used in client-server mode to set the port to use when accessing the server 15207via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 15208if the port is not specified in the CVSROOT. 15209@pxref{Remote repositories} 15210 15211@cindex CVS_PROXY_PORT 15212@item $CVS_PROXY_PORT 15213Used in client-server mode to set the port to use when accessing a server 15214via a web proxy, if the port is not specified in the CVSROOT. Works with 15215GSSAPI, and the password authentication protocol. 15216@pxref{Remote repositories} 15217 15218@cindex CVS_RCMD_PORT, environment variable 15219@item $CVS_RCMD_PORT 15220Used in client-server mode. If set, specifies the port 15221number to be used when accessing the @sc{rcmd} demon on 15222the server side. (Currently not used for Unix clients). 15223 15224@cindex CVS_CLIENT_LOG, environment variable 15225@item $CVS_CLIENT_LOG 15226Used for debugging only in client-server 15227mode. If set, everything sent to the server is logged 15228into @file{@code{$CVS_CLIENT_LOG}.in} and everything 15229sent from the server is logged into 15230@file{@code{$CVS_CLIENT_LOG}.out}. 15231 15232@cindex CVS_SERVER_SLEEP, environment variable 15233@item $CVS_SERVER_SLEEP 15234Used only for debugging the server side in 15235client-server mode. If set, delays the start of the 15236server child process the specified amount of 15237seconds so that you can attach to it with a debugger. 15238 15239@cindex CVS_IGNORE_REMOTE_ROOT, environment variable 15240@item $CVS_IGNORE_REMOTE_ROOT 15241For @sc{cvs} 1.10 and older, setting this variable 15242prevents @sc{cvs} from overwriting the @file{CVS/Root} 15243file when the @samp{-d} global option is specified. 15244Later versions of @sc{cvs} do not rewrite 15245@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 15246effect. 15247 15248@cindex CVS_LOCAL_BRANCH_NUM, environment variable 15249@item $CVS_LOCAL_BRANCH_NUM 15250Setting this variable allows some control over the 15251branch number that is assigned. This is specifically to 15252support the local commit feature of CVSup. If one sets 15253@code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches 15254the local repository, the revision numbers will look 15255like 1.66.1000.xx. There is almost a dead-set certainty 15256that there will be no conflicts with version numbers. 15257 15258@cindex COMSPEC, environment variable 15259@item $COMSPEC 15260Used under OS/2 only. It specifies the name of the 15261command interpreter and defaults to @sc{cmd.exe}. 15262 15263@cindex TMPDIR, environment variable 15264@cindex temporary file directory, set via environment variable 15265@cindex temporary files, location of 15266@item $TMPDIR 15267Directory in which temporary files are located. 15268@xref{Global options}, for more on setting the temporary directory. 15269 15270@cindex CVS_PID, environment variable 15271@item $CVS_PID 15272This is the process identification (aka pid) number of 15273the @sc{cvs} process. It is often useful in the 15274programs and/or scripts specified by the 15275@file{commitinfo}, @file{verifymsg}, @file{loginfo} 15276files. 15277@end table 15278 15279@node Compatibility 15280@appendix Compatibility between CVS Versions 15281 15282@cindex CVS, versions of 15283@cindex Versions, of CVS 15284@cindex Compatibility, between CVS versions 15285@c We don't mention versions older than CVS 1.3 15286@c on the theory that it would clutter it up for the vast 15287@c majority of people, who don't have anything that old. 15288@c 15289The repository format is compatible going back to 15290@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 15291you have copies of @sc{cvs} 1.6 or older and you want 15292to use the optional developer communication features. 15293@c If you "cvs rm" and commit using 1.3, then you'll 15294@c want to run "rcs -sdead <file,v>" on each of the 15295@c files in the Attic if you then want 1.5 and 15296@c later to recognize those files as dead (I think the 15297@c symptom if this is not done is that files reappear 15298@c in joins). (Wait: the above will work but really to 15299@c be strictly correct we should suggest checking 15300@c in a new revision rather than just changing the 15301@c state of the head revision, shouldn't we?). 15302@c The old convert.sh script was for this, but it never 15303@c did get updated to reflect use of the RCS "dead" 15304@c state. 15305@c Note: this is tricky to document without confusing 15306@c people--need to carefully say what CVS version we 15307@c are talking about and keep in mind the distinction 15308@c between a 15309@c repository created with 1.3 and on which one now 15310@c uses 1.5+, and a repository on which one wants to 15311@c use both versions side by side (e.g. during a 15312@c transition period). 15313@c Wait, can't CVS just detect the case in which a file 15314@c is in the Attic but the head revision is not dead? 15315@c Not sure whether this should produce a warning or 15316@c something, and probably needs further thought, but 15317@c it would appear that the situation can be detected. 15318@c 15319@c We might want to separate out the 1.3 compatibility 15320@c section (for repository & working directory) from the 15321@c rest--that might help avoid confusing people who 15322@c are upgrading (for example) from 1.6 to 1.8. 15323@c 15324@c A minor incompatibility is if a current version of CVS 15325@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 15326@c see this as if there is no tag. Seems to me this is 15327@c too obscure to mention. 15328 15329The working directory format is compatible going back 15330to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 15331and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 15332a working directory checked out with @sc{cvs} 1.3, 15333@sc{cvs} will convert it, but to go back to @sc{cvs} 153341.3 you need to check out a new working directory with 15335@sc{cvs} 1.3. 15336 15337The remote protocol is interoperable going back to @sc{cvs} 1.5, but no 15338further (1.5 was the first official release with the remote protocol, 15339but some older versions might still be floating around). In many 15340cases you need to upgrade both the client and the server to take 15341advantage of new features and bug fixes, however. 15342 15343@c Perhaps should be saying something here about the 15344@c "D" lines in Entries (written by CVS 1.9; 1.8 and 15345@c older don't use them). These are supposed to be 15346@c compatible in both directions, but I'm not sure 15347@c they quite are 100%. One common gripe is if you 15348@c "rm -r" a directory and 1.9 gets confused, as it 15349@c still sees it in Entries. That one is fixed in 15350@c (say) 1.9.6. Someone else reported problems with 15351@c starting with a directory which was checked out with 15352@c an old version, and then using a new version, and 15353@c some "D" lines appeared, but not for every 15354@c directory, causing some directories to be skipped. 15355@c They weren't sure how to reproduce this, though. 15356 15357@c --------------------------------------------------------------------- 15358@node Troubleshooting 15359@appendix Troubleshooting 15360 15361If you are having trouble with @sc{cvs}, this appendix 15362may help. If there is a particular error message which 15363you are seeing, then you can look up the message 15364alphabetically. If not, you can look through the 15365section on other problems to see if your problem is 15366mentioned there. 15367 15368@menu 15369* Error messages:: Partial list of CVS errors 15370* Connection:: Trouble making a connection to a CVS server 15371* Other problems:: Problems not readily listed by error message 15372@end menu 15373 15374@ignore 15375@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 15376@c @node Bad administrative files 15377@appendixsec Bad administrative files 15378 15379@c -- Give hints on how to fix them 15380@end ignore 15381 15382@node Error messages 15383@appendixsec Partial list of error messages 15384 15385Here is a partial list of error messages that you may 15386see from @sc{cvs}. It is not a complete list---@sc{cvs} 15387is capable of printing many, many error messages, often 15388with parts of them supplied by the operating system, 15389but the intention is to list the common and/or 15390potentially confusing error messages. 15391 15392The messages are alphabetical, but introductory text 15393such as @samp{cvs update: } is not considered in 15394ordering them. 15395 15396In some cases the list includes messages printed by old 15397versions of @sc{cvs} (partly because users may not be 15398sure which version of @sc{cvs} they are using at any 15399particular moment). 15400@c If we want to start retiring messages, perhaps we 15401@c should pick a cutoff version (for example, no more 15402@c messages which are specific to versions before 1.9) 15403@c and then move the old messages to an "old messages" 15404@c node rather than deleting them completely. 15405 15406@table @code 15407@c FIXME: What is the correct way to format a multiline 15408@c error message here? Maybe @table is the wrong 15409@c choice? Texinfo gurus? 15410@item @var{file}:@var{line}: Assertion '@var{text}' failed 15411The exact format of this message may vary depending on 15412your system. It indicates a bug in @sc{cvs}, which can 15413be handled as described in @ref{BUGS}. 15414 15415@item cvs @var{command}: authorization failed: server @var{host} rejected access 15416This is a generic response when trying to connect to a 15417pserver server which chooses not to provide a 15418specific reason for denying authorization. Check that 15419the username and password specified are correct and 15420that the @code{CVSROOT} specified is allowed by @samp{--allow-root} 15421in @file{inetd.conf}. See @ref{Password authenticated}. 15422 15423@item cvs @var{command}: conflict: removed @var{file} was modified by second party 15424This message indicates that you removed a file, and 15425someone else modified it. To resolve the conflict, 15426first run @samp{cvs add @var{file}}. If desired, look 15427at the other party's modification to decide whether you 15428still want to remove it. If you don't want to remove 15429it, stop here. If you do want to remove it, proceed 15430with @samp{cvs remove @var{file}} and commit your 15431removal. 15432@c Tests conflicts2-142b* in sanity.sh test for this. 15433 15434@item cannot change permissions on temporary directory 15435@example 15436Operation not permitted 15437@end example 15438This message has been happening in a non-reproducible, 15439occasional way when we run the client/server testsuite, 15440both on Red Hat Linux 3.0.3 and 4.1. We haven't been 15441able to figure out what causes it, nor is it known 15442whether it is specific to Linux (or even to this 15443particular machine!). If the problem does occur on 15444other unices, @samp{Operation not permitted} would be 15445likely to read @samp{Not owner} or whatever the system 15446in question uses for the unix @code{EPERM} error. If 15447you have any information to add, please let us know as 15448described in @ref{BUGS}. If you experience this error 15449while using @sc{cvs}, retrying the operation which 15450produced it should work fine. 15451@c This has been seen in a variety of tests, including 15452@c multibranch-2, multibranch-5, and basic1-24-rm-rm, 15453@c so it doesn't seem particularly specific to any one 15454@c test. 15455 15456@item cvs [server aborted]: Cannot check out files into the repository itself 15457The obvious cause for this message (especially for 15458non-client/server @sc{cvs}) is that the @sc{cvs} root 15459is, for example, @file{/usr/local/cvsroot} and you try 15460to check out files when you are in a subdirectory, such 15461as @file{/usr/local/cvsroot/test}. However, there is a 15462more subtle cause, which is that the temporary 15463directory on the server is set to a subdirectory of the 15464root (which is also not allowed). If this is the 15465problem, set the temporary directory to somewhere else, 15466for example @file{/var/tmp}; see @code{TMPDIR} in 15467@ref{Environment variables}, for how to set the 15468temporary directory. 15469 15470@item cannot commit files as 'root' 15471See @samp{'root' is not allowed to commit files}. 15472 15473@c For one example see basica-1a10 in the testsuite 15474@c For another example, "cvs co ." on NT; see comment 15475@c at windows-NT/filesubr.c (expand_wild). 15476@c For another example, "cvs co foo/bar" where foo exists. 15477@item cannot open CVS/Entries for reading: No such file or directory 15478This generally indicates a @sc{cvs} internal error, and 15479can be handled as with other @sc{cvs} bugs 15480(@pxref{BUGS}). Usually there is a workaround---the 15481exact nature of which would depend on the situation but 15482which hopefully could be figured out. 15483 15484@c This is more obscure than it might sound; it only 15485@c happens if you run "cvs init" from a directory which 15486@c contains a CVS/Root file at the start. 15487@item cvs [init aborted]: cannot open CVS/Root: No such file or directory 15488This message is harmless. Provided it is not 15489accompanied by other errors, the operation has 15490completed successfully. This message should not occur 15491with current versions of @sc{cvs}, but it is documented 15492here for the benefit of @sc{cvs} 1.9 and older. 15493 15494@item cvs server: cannot open /root/.cvsignore: Permission denied 15495@itemx cvs [server aborted]: can't chdir(/root): Permission denied 15496See @ref{Connection}. 15497 15498@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 15499This message has been reported as intermittently 15500happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 15501unknown; if you know more about what causes it, let us 15502know as described in @ref{BUGS}. 15503 15504@item cvs [@var{command} aborted]: cannot start server via rcmd 15505This, unfortunately, is a rather nonspecific error 15506message which @sc{cvs} 1.9 will print if you are 15507running the @sc{cvs} client and it is having trouble 15508connecting to the server. Current versions of @sc{cvs} 15509should print a much more specific error message. If 15510you get this message when you didn't mean to run the 15511client at all, you probably forgot to specify 15512@code{:local:}, as described in @ref{Repository}. 15513 15514@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 15515@sc{cvs} 1.9 and older will print this message 15516when trying to check in a binary file if 15517@sc{rcs} is not correctly installed. Re-read the 15518instructions that came with your @sc{rcs} distribution 15519and the @sc{install} file in the @sc{cvs} 15520distribution. Alternately, upgrade to a current 15521version of @sc{cvs}, which checks in files itself 15522rather than via @sc{rcs}. 15523 15524@item cvs checkout: could not check out @var{file} 15525With @sc{cvs} 1.9, this can mean that the @code{co} program 15526(part of @sc{rcs}) returned a failure. It should be 15527preceded by another error message, however it has been 15528observed without another error message and the cause is 15529not well-understood. With the current version of @sc{cvs}, 15530which does not run @code{co}, if this message occurs 15531without another error message, it is definitely a @sc{cvs} 15532bug (@pxref{BUGS}). 15533@c My current suspicion is that the RCS in the rcs (not 15534@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 15535@c CD is bad (remains to be confirmed). 15536@c There is also a report of something which looks 15537@c very similar on SGI, Irix 5.2, so I dunno. 15538 15539@item cvs [login aborted]: could not find out home directory 15540This means that you need to set the environment 15541variables that @sc{cvs} uses to locate your home directory. 15542See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 15543@ref{Environment variables}. 15544 15545@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 15546@sc{cvs} 1.9 and older will print this message if there was 15547a problem finding the @code{rcsmerge} program. Make 15548sure that it is in your @code{PATH}, or upgrade to a 15549current version of @sc{cvs}, which does not require 15550an external @code{rcsmerge} program. 15551 15552@item cvs [update aborted]: could not patch @var{file}: No such file or directory 15553This means that there was a problem finding the 15554@code{patch} program. Make sure that it is in your 15555@code{PATH}. Note that despite appearances the message 15556is @emph{not} referring to whether it can find @var{file}. 15557If both the client and the server are running a current 15558version of @sc{cvs}, then there is no need for an 15559external patch program and you should not see this 15560message. But if either client or server is running 15561@sc{cvs} 1.9, then you need @code{patch}. 15562 15563@item cvs update: could not patch @var{file}; will refetch 15564This means that for whatever reason the client was 15565unable to apply a patch that the server sent. The 15566message is nothing to be concerned about, because 15567inability to apply the patch only slows things down and 15568has no effect on what @sc{cvs} does. 15569@c xref to update output. Or File status? 15570@c Or some place else that 15571@c explains this whole "patch"/P/Needs Patch thing? 15572 15573@item dying gasps from @var{server} unexpected 15574There is a known bug in the server for @sc{cvs} 1.9.18 15575and older which can cause this. For me, this was 15576reproducible if I used the @samp{-t} global option. It 15577was fixed by Andy Piper's 14 Nov 1997 change to 15578src/filesubr.c, if anyone is curious. 15579If you see the message, 15580you probably can just retry the operation which failed, 15581or if you have discovered information concerning its 15582cause, please let us know as described in @ref{BUGS}. 15583 15584@item end of file from server (consult above messages if any) 15585The most common cause for this message is if you are 15586using an external @code{rsh} program and it exited with 15587an error. In this case the @code{rsh} program should 15588have printed a message, which will appear before the 15589above message. For more information on setting up a 15590@sc{cvs} client and server, see @ref{Remote repositories}. 15591 15592@item cvs [update aborted]: EOF in key in RCS file @var{file},v 15593@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 15594This means that there is a syntax error in the given 15595@sc{rcs} file. Note that this might be true even if @sc{rcs} can 15596read the file OK; @sc{cvs} does more error checking of 15597errors in the RCS file. That is why you may see this 15598message when upgrading from @sc{cvs} 1.9 to @sc{cvs} 155991.10. The likely cause for the original corruption is 15600hardware, the operating system, or the like. Of 15601course, if you find a case in which @sc{cvs} seems to 15602corrupting the file, by all means report it, 15603(@pxref{BUGS}). 15604There are quite a few variations of this error message, 15605depending on exactly where in the @sc{rcs} file @sc{cvs} 15606finds the syntax error. 15607 15608@cindex mkmodules 15609@item cvs commit: Executing 'mkmodules' 15610This means that your repository is set up for a version 15611of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 156121.8 or later, the above message will be preceded by 15613 15614@example 15615cvs commit: Rebuilding administrative file database 15616@end example 15617 15618If you see both messages, the database is being rebuilt 15619twice, which is unnecessary but harmless. If you wish 15620to avoid the duplication, and you have no versions of 15621@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 15622every place it appears in your @code{modules} 15623file. For more information on the @code{modules} file, 15624see @ref{modules}. 15625 15626@c This message comes from "co", and I believe is 15627@c possible only with older versions of CVS which call 15628@c co. The problem with being able to create the bogus 15629@c RCS file still exists, though (and I think maybe 15630@c there is a different symptom(s) now). 15631@c FIXME: Would be nice to have a more exact wording 15632@c for this message. 15633@item missing author 15634Typically this can happen if you created an RCS file 15635with your username set to empty. @sc{cvs} will, bogusly, 15636create an illegal RCS file with no value for the author 15637field. The solution is to make sure your username is 15638set to a non-empty value and re-create the RCS file. 15639@c "make sure your username is set" is complicated in 15640@c and of itself, as there are the environment 15641@c variables the system login name, &c, and it depends 15642@c on the version of CVS. 15643 15644@item cvs [checkout aborted]: no such tag @var{tag} 15645This message means that @sc{cvs} isn't familiar with 15646the tag @var{tag}. Usually the root cause is that you have 15647mistyped a tag name. Ocassionally this can also occur because the 15648users creating tags do not have permissions to write to the 15649@file{CVSROOT/val-tags} file (@pxref{File permissions}, for more). 15650 15651Prior to @sc{cvs} version 1.12.10, there were a few relatively 15652obscure cases where a given tag could be created in an archive 15653file in the repository but @sc{cvs} would require the user to 15654@c Search sanity.sh for "no such tag" to see some of 15655@c the relatively obscure cases. 15656try a few other @sc{cvs} commands involving that tag 15657until one was found whch caused @sc{cvs} to update 15658@cindex CVSROOT/val-tags file, forcing tags into 15659@cindex val-tags file, forcing tags into 15660the @file{val-tags} file, at which point the originally failing command 15661would begin to work. This same method can be used to repair a @file{val-tags} 15662file that becomes out of date due to the permissions problem mentioned above. 15663This updating is only required once per tag - once a tag is listed in 15664@file{val-tags}, it stays there. 15665 15666Note that using @samp{tag -f} to not require tag matches did not and 15667does not override this check (@pxref{Common options}). 15668 15669@item *PANIC* administration files missing 15670This typically means that there is a directory named 15671@sc{cvs} but it does not contain the administrative files 15672which @sc{cvs} puts in a CVS directory. If the problem is 15673that you created a CVS directory via some mechanism 15674other than @sc{cvs}, then the answer is simple, use a name 15675other than @sc{cvs}. If not, it indicates a @sc{cvs} bug 15676(@pxref{BUGS}). 15677 15678@item rcs error: Unknown option: -x,v/ 15679This message will be followed by a usage message for 15680@sc{rcs}. It means that you have an old version of 15681@sc{rcs} (probably supplied with your operating 15682system), as well as an old version of @sc{cvs}. 15683@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 15684later; current versions of @sc{cvs} do not run @sc{rcs} programs. 15685@c For more information on installing @sc{cvs}, see 15686@c (FIXME: where? it depends on whether you are 15687@c getting binaries or sources or what). 15688@c The message can also say "ci error" or something 15689@c instead of "rcs error", I suspect. 15690 15691@item cvs [server aborted]: received broken pipe signal 15692This message can be caused by a loginfo program that fails to 15693read all of the log information from its standard input. 15694If you find it happening in any other circumstances, 15695please let us know as described in @ref{BUGS}. 15696 15697@item 'root' is not allowed to commit files 15698When committing a permanent change, @sc{cvs} makes a log entry of 15699who committed the change. If you are committing the change logged 15700in as "root" (not under "su" or other root-priv giving program), 15701@sc{cvs} cannot determine who is actually making the change. 15702As such, by default, @sc{cvs} disallows changes to be committed by users 15703logged in as "root". (You can disable this option by passing the 15704@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 15705On some systems this means editing the appropriate @file{config.h} file 15706before building @sc{cvs}.) 15707 15708@item cvs [server aborted]: Secondary out of sync with primary! 15709 15710This usually means that the version of @sc{cvs} running on a secondary 15711server is incompatible with the version running on the primary server 15712(@pxref{Write proxies}). 15713This will not occur if the client supports redirection. 15714 15715It is not the version number that is significant here, but the list of 15716supported requests that the servers provide to the client. 15717For example, even if both servers were the same version, 15718if the secondary was compiled with GSSAPI support and the primary was not, 15719the list of supported requests provided by the two servers 15720would be different and the secondary would not work as a transparent 15721proxy to the primary. 15722Conversely, even if the two servers were radically different versions 15723but both provided the same list of valid requests to the client, 15724the transparent proxy would succeed. 15725 15726@item Terminated with fatal signal 11 15727This message usually indicates that @sc{cvs} (the server, if you're 15728using client/server mode) has run out of (virtual) memory. 15729Although @sc{cvs} tries to catch the error and issue a more meaningful 15730message, there are many circumstances where that is not possible. 15731If you appear to have lots of memory available to the system, 15732the problem is most likely that you're running into a system-wide 15733limit on the amount of memory a single process can use or a 15734similar process-specific limit. 15735The mechanisms for displaying and setting such limits vary from 15736system to system, so you'll have to consult an expert for your 15737particular system if you don't know how to do that. 15738 15739@item Too many arguments! 15740This message is typically printed by the @file{log.pl} 15741script which is in the @file{contrib} directory in the 15742@sc{cvs} source distribution. In some versions of 15743@sc{cvs}, @file{log.pl} has been part of the default 15744@sc{cvs} installation. The @file{log.pl} script gets 15745called from the @file{loginfo} administrative file. 15746Check that the arguments passed in @file{loginfo} match 15747what your version of @file{log.pl} expects. In 15748particular, the @file{log.pl} from @sc{cvs} 1.3 and 15749older expects the log file as an argument whereas the 15750@file{log.pl} from @sc{cvs} 1.5 and newer expects the 15751log file to be specified with a @samp{-f} option. Of 15752course, if you don't need @file{log.pl} you can just 15753comment it out of @file{loginfo}. 15754 15755@item cvs [update aborted]: unexpected EOF reading @var{file},v 15756See @samp{EOF in key in RCS file}. 15757 15758@item cvs [login aborted]: unrecognized auth response from @var{server} 15759This message typically means that the server is not set 15760up properly. For example, if @file{inetd.conf} points 15761to a nonexistent cvs executable. To debug it further, 15762find the log file which inetd writes 15763(@file{/var/log/messages} or whatever inetd uses on 15764your system). For details, see @ref{Connection}, and 15765@ref{Password authentication server}. 15766 15767@item cvs commit: Up-to-date check failed for `@var{file}' 15768This means that someone else has committed a change to 15769that file since the last time that you did a @code{cvs 15770update}. So before proceeding with your @code{cvs 15771commit} you need to @code{cvs update}. @sc{cvs} will merge 15772the changes that you made and the changes that the 15773other person made. If it does not detect any conflicts 15774it will report @samp{M @var{file}} and you are ready 15775to @code{cvs commit}. If it detects conflicts it will 15776print a message saying so, will report @samp{C @var{file}}, 15777and you need to manually resolve the 15778conflict. For more details on this process see 15779@ref{Conflicts example}. 15780 15781@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 15782@example 15783Only one of [exEX3] allowed 15784@end example 15785This indicates a problem with the installation of 15786@code{diff3} and @code{rcsmerge}. Specifically 15787@code{rcsmerge} was compiled to look for GNU diff3, but 15788it is finding unix diff3 instead. The exact text of 15789the message will vary depending on the system. The 15790simplest solution is to upgrade to a current version of 15791@sc{cvs}, which does not rely on external 15792@code{rcsmerge} or @code{diff3} programs. 15793 15794@item warning: unrecognized response `@var{text}' from cvs server 15795If @var{text} contains a valid response (such as 15796@samp{ok}) followed by an extra carriage return 15797character (on many systems this will cause the second 15798part of the message to overwrite the first part), then 15799it probably means that you are using the @samp{:ext:} 15800access method with a version of rsh, such as most 15801non-unix rsh versions, which does not by default 15802provide a transparent data stream. In such cases you 15803probably want to try @samp{:server:} instead of 15804@samp{:ext:}. If @var{text} is something else, this 15805may signify a problem with your @sc{cvs} server. 15806Double-check your installation against the instructions 15807for setting up the @sc{cvs} server. 15808@c FIXCVS: should be printing CR as \r or \015 or some 15809@c such, probably. 15810 15811@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 15812This is a normal message, not an error. See 15813@ref{Concurrency}, for more details. 15814 15815@item cvs commit: warning: editor session failed 15816@cindex Exit status, of editor 15817This means that the editor which @sc{cvs} is using exits with a nonzero 15818exit status. Some versions of vi will do this even when there was not 15819a problem editing the file. If so, point the 15820@code{CVSEDITOR} environment variable to a small script 15821such as: 15822 15823@example 15824#!/bin/sh 15825vi $* 15826exit 0 15827@end example 15828 15829@item cvs update: warning: @var{file} was lost 15830This means that the working copy of @var{file} has been deleted 15831but it has not been removed from @sc{cvs}. 15832This is nothing to be concerned about, 15833the update will just recreate the local file from the repository. 15834(This is a convenient way to discard local changes to a file: 15835just delete it and then run @code{cvs update}.) 15836 15837@item cvs update: warning: @var{file} is not (any longer) pertinent 15838This means that the working copy of @var{file} has been deleted, 15839it has not been removed from @sc{cvs} in the current working directory, 15840but it has been removed from @sc{cvs} in some other working directory. 15841This is nothing to be concerned about, 15842the update would have removed the local file anyway. 15843 15844@end table 15845 15846@node Connection 15847@appendixsec Trouble making a connection to a CVS server 15848 15849This section concerns what to do if you are having 15850trouble making a connection to a @sc{cvs} server. If 15851you are running the @sc{cvs} command line client 15852running on Windows, first upgrade the client to 15853@sc{cvs} 1.9.12 or later. The error reporting in 15854earlier versions provided much less information about 15855what the problem was. If the client is non-Windows, 15856@sc{cvs} 1.9 should be fine. 15857 15858If the error messages are not sufficient to track down 15859the problem, the next steps depend largely on which 15860access method you are using. 15861 15862@table @code 15863@cindex :ext:, troubleshooting 15864@item :ext: 15865Try running the rsh program from the command line. For 15866example: "rsh servername cvs -v" should print @sc{cvs} 15867version information. If this doesn't work, you need to 15868fix it before you can worry about @sc{cvs} problems. 15869 15870@cindex :server:, troubleshooting 15871@item :server: 15872You don't need a command line rsh program to use this 15873access method, but if you have an rsh program around, 15874it may be useful as a debugging tool. Follow the 15875directions given for :ext:. 15876 15877@cindex :pserver:, troubleshooting 15878@item :pserver: 15879Errors along the lines of "connection refused" typically indicate 15880that inetd isn't even listening for connections on port 2401 15881whereas errors like "connection reset by peer", 15882"received broken pipe signal", "recv() from server: EOF", 15883or "end of file from server" 15884typically indicate that inetd is listening for 15885connections but is unable to start @sc{cvs} (this is frequently 15886caused by having an incorrect path in @file{inetd.conf} 15887or by firewall software rejecting the connection). 15888"unrecognized auth response" errors are caused by a bad command 15889line in @file{inetd.conf}, typically an invalid option or forgetting 15890to put the @samp{pserver} command at the end of the line. 15891Another less common problem is invisible control characters that 15892your editor "helpfully" added without you noticing. 15893 15894One good debugging tool is to "telnet servername 158952401". After connecting, send any text (for example 15896"foo" followed by return). If @sc{cvs} is working 15897correctly, it will respond with 15898 15899@example 15900cvs [pserver aborted]: bad auth protocol start: foo 15901@end example 15902 15903If instead you get: 15904 15905@example 15906Usage: cvs [cvs-options] command [command-options-and-arguments] 15907... 15908@end example 15909 15910@noindent 15911then you're missing the @samp{pserver} command at the end of the 15912line in @file{inetd.conf}; check to make sure that the entire command 15913is on one line and that it's complete. 15914 15915Likewise, if you get something like: 15916 15917@example 15918Unknown command: `pserved' 15919 15920CVS commands are: 15921 add Add a new file/directory to the repository 15922... 15923@end example 15924 15925@noindent 15926then you've misspelled @samp{pserver} in some way. If it isn't 15927obvious, check for invisible control characters (particularly 15928carriage returns) in @file{inetd.conf}. 15929 15930If it fails to work at all, then make sure inetd is working 15931right. Change the invocation in @file{inetd.conf} to run the 15932echo program instead of cvs. For example: 15933 15934@example 159352401 stream tcp nowait root /bin/echo echo hello 15936@end example 15937 15938After making that change and instructing inetd to 15939re-read its configuration file, "telnet servername 159402401" should show you the text hello and then the 15941server should close the connection. If this doesn't 15942work, you need to fix it before you can worry about 15943@sc{cvs} problems. 15944 15945On AIX systems, the system will often have its own 15946program trying to use port 2401. This is AIX's problem 15947in the sense that port 2401 is registered for use with 15948@sc{cvs}. I hear that there is an AIX patch available 15949to address this problem. 15950 15951Another good debugging tool is the @samp{-d} 15952(debugging) option to inetd. Consult your system 15953documentation for more information. 15954 15955If you seem to be connecting but get errors like: 15956 15957@example 15958cvs server: cannot open /root/.cvsignore: Permission denied 15959cvs [server aborted]: can't chdir(/root): Permission denied 15960@end example 15961 15962@noindent 15963then you probably haven't specified @samp{-f} in @file{inetd.conf}. 15964(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 15965your system setting the @code{$HOME} environment variable 15966for programs being run by inetd. In this case, you can either 15967have inetd run a shell script that unsets @code{$HOME} and then runs 15968@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 15969environment.) 15970 15971If you can connect successfully for a while but then can't, 15972you've probably hit inetd's rate limit. 15973(If inetd receives too many requests for the same service 15974in a short period of time, it assumes that something is wrong 15975and temporarily disables the service.) 15976Check your inetd documentation to find out how to adjust the 15977rate limit (some versions of inetd have a single rate limit, 15978others allow you to set the limit for each service separately.) 15979@end table 15980 15981@node Other problems 15982@appendixsec Other common problems 15983 15984Here is a list of problems which do not fit into the 15985above categories. They are in no particular order. 15986 15987@itemize @bullet 15988@item 15989On Windows, if there is a 30 second or so delay when 15990you run a @sc{cvs} command, it may mean that you have 15991your home directory set to @file{C:/}, for example (see 15992@code{HOMEDRIVE} and @code{HOMEPATH} in 15993@ref{Environment variables}). @sc{cvs} expects the home 15994directory to not end in a slash, for example @file{C:} 15995or @file{C:\cvs}. 15996@c FIXCVS: CVS should at least detect this and print an 15997@c error, presumably. 15998 15999@item 16000If you are running @sc{cvs} 1.9.18 or older, and 16001@code{cvs update} finds a conflict and tries to 16002merge, as described in @ref{Conflicts example}, but 16003doesn't tell you there were conflicts, then you may 16004have an old version of @sc{rcs}. The easiest solution 16005probably is to upgrade to a current version of 16006@sc{cvs}, which does not rely on external @sc{rcs} 16007programs. 16008@end itemize 16009 16010@c --------------------------------------------------------------------- 16011@node Credits 16012@appendix Credits 16013 16014@cindex Contributors (manual) 16015@cindex Credits (manual) 16016Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 16017wrote the manual pages which were distributed with 16018@sc{cvs} 1.3. Much of their text was copied into this 16019manual. He also read an early draft 16020of this manual and contributed many ideas and 16021corrections. 16022 16023The mailing-list @code{info-cvs} is sometimes 16024informative. I have included information from postings 16025made by the following persons: 16026David G. Grubbs <@t{dgg@@think.com}>. 16027 16028Some text has been extracted from the man pages for 16029@sc{rcs}. 16030 16031The @sc{cvs} @sc{faq} by David G. Grubbs has provided 16032useful material. The @sc{faq} is no longer maintained, 16033however, and this manual is about the closest thing there 16034is to a successor (with respect to documenting how to 16035use @sc{cvs}, at least). 16036 16037In addition, the following persons have helped by 16038telling me about mistakes I've made: 16039 16040@display 16041Roxanne Brunskill <@t{rbrunski@@datap.ca}>, 16042Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 16043Karl Pingle <@t{pingle@@acuson.com}>, 16044Thomas A Peterson <@t{tap@@src.honeywell.com}>, 16045Inge Wallin <@t{ingwa@@signum.se}>, 16046Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 16047and Michael Brown <@t{brown@@wi.extrel.com}>. 16048@end display 16049 16050The list of contributors here is not comprehensive; for a more 16051complete list of who has contributed to this manual see 16052the file @file{doc/ChangeLog} in the @sc{cvs} source 16053distribution. 16054 16055@c --------------------------------------------------------------------- 16056@node BUGS 16057@appendix Dealing with bugs in CVS or this manual 16058 16059@cindex Bugs in this manual or CVS 16060Neither @sc{cvs} nor this manual is perfect, and they 16061probably never will be. If you are having trouble 16062using @sc{cvs}, or think you have found a bug, there 16063are a number of things you can do about it. Note that 16064if the manual is unclear, that can be considered a bug 16065in the manual, so these problems are often worth doing 16066something about as well as problems with @sc{cvs} itself. 16067 16068@cindex Reporting bugs 16069@cindex Bugs, reporting 16070@cindex Errors, reporting 16071@itemize @bullet 16072@item 16073If you want someone to help you and fix bugs that you 16074report, there are companies which will do that for a 16075fee. One such company is: 16076 16077@cindex Ximbiot 16078@cindex Support, getting CVS support 16079@example 16080Ximbiot 16081319 S. River St. 16082Harrisburg, PA 17104-1657 16083USA 16084Email: info@@ximbiot.com 16085Phone: (717) 579-6168 16086Fax: (717) 234-3125 16087@url{http://ximbiot.com/} 16088 16089@end example 16090 16091@item 16092If you got @sc{cvs} through a distributor, such as an 16093operating system vendor or a vendor of freeware 16094@sc{cd-rom}s, you may wish to see whether the 16095distributor provides support. Often, they will provide 16096no support or minimal support, but this may vary from 16097distributor to distributor. 16098 16099@item 16100If you have the skills and time to do so, you may wish 16101to fix the bug yourself. If you wish to submit your 16102fix for inclusion in future releases of @sc{cvs}, see 16103the file @sc{hacking} in the @sc{cvs} source 16104distribution. It contains much more information on the 16105process of submitting fixes. 16106 16107@item 16108There may be resources on the net which can help. A 16109good place to start is: 16110 16111@example 16112@url{http://cvs.nongnu.org/} 16113@end example 16114 16115If you are so inspired, increasing the information 16116available on the net is likely to be appreciated. For 16117example, before the standard @sc{cvs} distribution 16118worked on Windows 95, there was a web page with some 16119explanation and patches for running @sc{cvs} on Windows 1612095, and various people helped out by mentioning this 16121page on mailing lists or newsgroups when the subject 16122came up. 16123 16124@item 16125It is also possible to report bugs to @email{bug-cvs@@nongnu.org}. 16126Note that someone may or may not want to do anything 16127with your bug report---if you need a solution consider 16128one of the options mentioned above. People probably do 16129want to hear about bugs which are particularly severe 16130in consequences and/or easy to fix, however. You can 16131also increase your odds by being as clear as possible 16132about the exact nature of the bug and any other 16133relevant information. The way to report bugs is to 16134send email to @email{bug-cvs@@nongnu.org}. Note 16135that submissions to @email{bug-cvs@@nongnu.org} may be distributed 16136under the terms of the @sc{gnu} Public License, so if 16137you don't like this, don't submit them. There is 16138usually no justification for sending mail directly to 16139one of the @sc{cvs} maintainers rather than to 16140@email{bug-cvs@@nongnu.org}; those maintainers who want to hear 16141about such bug reports read @email{bug-cvs@@nongnu.org}. Also note 16142that sending a bug report to other mailing lists or 16143newsgroups is @emph{not} a substitute for sending it to 16144@email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on 16145whatever forum you prefer, but there are not 16146necessarily any maintainers reading bug reports sent 16147anywhere except @email{bug-cvs@@nongnu.org}. 16148@end itemize 16149 16150@cindex Known bugs in this manual or CVS 16151People often ask if there is a list of known bugs or 16152whether a particular bug is a known one. The file 16153@sc{bugs} in the @sc{cvs} source distribution is one 16154list of known bugs, but it doesn't necessarily try to 16155be comprehensive. Perhaps there will never be a 16156comprehensive, detailed list of known bugs. 16157 16158@c --------------------------------------------------------------------- 16159@node Index 16160@unnumbered Index 16161@cindex Index 16162 16163@printindex cp 16164 16165@bye 16166 16167Local Variables: 16168fill-column: 55 16169End: 16170