cvs.texinfo revision 1.13
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 1 115@center @titlefont{with} 116@sp 1 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 1942To create a repository, run the @code{cvs init} 1943command (@pxref{init}). 1944 1945@node Backing up 1946@section Backing up a repository 1947@cindex Repository, backing up 1948@cindex Backing up, repository 1949 1950There is nothing particularly magical about the files 1951in the repository; for the most part it is possible to 1952back them up just like any other files. However, there 1953are a few issues to consider. 1954 1955@cindex Locks, cvs, and backups 1956@cindex #cvs.rfl, and backups 1957The first is that to be paranoid, one should either not 1958use @sc{cvs} during the backup, or have the backup 1959program lock @sc{cvs} while doing the backup. To not 1960use @sc{cvs}, you might forbid logins to machines which 1961can access the repository, turn off your @sc{cvs} 1962server, or similar mechanisms. The details would 1963depend on your operating system and how you have 1964@sc{cvs} set up. To lock @sc{cvs}, you would create 1965@file{#cvs.rfl} locks in each repository directory. 1966See @ref{Concurrency}, for more on @sc{cvs} locks. 1967Having said all this, if you just back up without any 1968of these precautions, the results are unlikely to be 1969particularly dire. Restoring from backup, the 1970repository might be in an inconsistent state, but this 1971would not be particularly hard to fix manually. 1972 1973When you restore a repository from backup, assuming 1974that changes in the repository were made after the time 1975of the backup, working directories which were not 1976affected by the failure may refer to revisions which no 1977longer exist in the repository. Trying to run @sc{cvs} 1978in such directories will typically produce an error 1979message. One way to get those changes back into the 1980repository is as follows: 1981 1982@itemize @bullet 1983@item 1984Get a new working directory. 1985 1986@item 1987Copy the files from the working directory from before 1988the failure over to the new working directory (do not 1989copy the contents of the @file{CVS} directories, of 1990course). 1991 1992@item 1993Working in the new working directory, use commands such 1994as @code{cvs update} and @code{cvs diff} to figure out 1995what has changed, and then when you are ready, commit 1996the changes into the repository. 1997@end itemize 1998 1999@node Moving a repository 2000@section Moving a repository 2001@cindex Repository, moving 2002@cindex Moving a repository 2003@cindex Copying a repository 2004 2005Just as backing up the files in the repository is 2006pretty much like backing up any other files, if you 2007need to move a repository from one place to another it 2008is also pretty much like just moving any other 2009collection of files. 2010 2011The main thing to consider is that working directories 2012point to the repository. The simplest way to deal with 2013a moved repository is to just get a fresh working 2014directory after the move. Of course, you'll want to 2015make sure that the old working directory had been 2016checked in before the move, or you figured out some 2017other way to make sure that you don't lose any 2018changes. If you really do want to reuse the existing 2019working directory, it should be possible with manual 2020surgery on the @file{CVS/Repository} files. You can 2021see @ref{Working directory storage}, for information on 2022the @file{CVS/Repository} and @file{CVS/Root} files, but 2023unless you are sure you want to bother, it probably 2024isn't worth it. 2025@c FIXME: Surgery on CVS/Repository should be avoided 2026@c by making RELATIVE_REPOS the default. 2027@c FIXME-maybe: might want some documented way to 2028@c change the CVS/Root files in some particular tree. 2029@c But then again, I don't know, maybe just having 2030@c people do this in perl/shell/&c isn't so bad... 2031 2032@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2033@node Remote repositories 2034@section Remote repositories 2035@cindex Repositories, remote 2036@cindex Remote repositories 2037@cindex Client/Server Operation 2038@cindex Server, CVS 2039@cindex Remote repositories, port specification 2040@cindex Repositories, remote, port specification 2041@cindex Client/Server Operation, port specification 2042@cindex pserver (client/server connection method), port specification 2043@cindex kserver (client/server connection method), port specification 2044@cindex gserver (client/server connection method), port specification 2045@cindex port, specifying for remote repositories 2046 2047 Your working copy of the sources can be on a 2048different machine than the repository. Using @sc{cvs} 2049in this manner is known as @dfn{client/server} 2050operation. You run @sc{cvs} on a machine which can 2051mount your working directory, known as the 2052@dfn{client}, and tell it to communicate to a machine 2053which can mount the repository, known as the 2054@dfn{server}. Generally, using a remote 2055repository is just like using a local one, except that 2056the format of the repository name is: 2057 2058@example 2059[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 2060@end example 2061 2062Specifying a password in the repository name is not recommended during 2063checkout, since this will cause @sc{cvs} to store a cleartext copy of the 2064password in each created directory. @code{cvs login} first instead 2065(@pxref{Password authentication client}). 2066 2067The details of exactly what needs to be set up depend 2068on how you are connecting to the server. 2069 2070@c Should we try to explain which platforms are which? 2071@c Platforms like unix and VMS, which only allow 2072@c privileged programs to bind to sockets <1024 lose on 2073@c :server: 2074@c Platforms like Mac and VMS, whose rsh program is 2075@c unusable or nonexistent, lose on :ext: 2076@c Platforms like OS/2 and NT probably could plausibly 2077@c default either way (modulo -b troubles). 2078 2079@menu 2080* Server requirements:: Memory and other resources for servers 2081* The connection method:: Connection methods and method options 2082* Connecting via rsh:: Using the @code{rsh} program to connect 2083* Password authenticated:: Direct connections using passwords 2084* GSSAPI authenticated:: Direct connections using GSSAPI 2085* Kerberos authenticated:: Direct connections with Kerberos 2086* Connecting via fork:: Using a forked @code{cvs server} to connect 2087* Write proxies:: Distributing load across several CVS servers 2088@end menu 2089 2090@node Server requirements 2091@subsection Server requirements 2092 2093The quick answer to what sort of machine is suitable as 2094a server is that requirements are modest---a server 2095with 32M of memory or even less can handle a fairly 2096large source tree with a fair amount of activity. 2097@c Say something about CPU speed too? I'm even less sure 2098@c what to say on that subject... 2099 2100The real answer, of course, is more complicated. 2101Estimating the known areas of large memory consumption 2102should be sufficient to estimate memory requirements. 2103There are two such areas documented here; other memory 2104consumption should be small by comparison (if you find 2105that is not the case, let us know, as described in 2106@ref{BUGS}, so we can update this documentation). 2107 2108The first area of big memory consumption is large 2109checkouts, when using the @sc{cvs} server. The server 2110consists of two processes for each client that it is 2111serving. Memory consumption on the child process 2112should remain fairly small. Memory consumption on the 2113parent process, particularly if the network connection 2114to the client is slow, can be expected to grow to 2115slightly more than the size of the sources in a single 2116directory, or two megabytes, whichever is larger. 2117@c "two megabytes" of course is SERVER_HI_WATER. But 2118@c we don't mention that here because we are 2119@c documenting the default configuration of CVS. If it 2120@c is a "standard" thing to change that value, it 2121@c should be some kind of run-time configuration. 2122@c 2123@c See cvsclient.texi for more on the design decision 2124@c to not have locks in place while waiting for the 2125@c client, which is what results in memory consumption 2126@c as high as this. 2127 2128Multiplying the size of each @sc{cvs} server by the 2129number of servers which you expect to have active at 2130one time should give an idea of memory requirements for 2131the server. For the most part, the memory consumed by 2132the parent process probably can be swap space rather 2133than physical memory. 2134@c Has anyone verified that notion about swap space? 2135@c I say it based pretty much on guessing that the 2136@c ->text of the struct buffer_data only gets accessed 2137@c in a first in, first out fashion, but I haven't 2138@c looked very closely. 2139 2140@c What about disk usage in /tmp on the server? I think that 2141@c it can be substantial, but I haven't looked at this 2142@c again and tried to figure it out ("cvs import" is 2143@c probably the worst case...). 2144 2145The second area of large memory consumption is 2146@code{diff}, when checking in large files. This is 2147required even for binary files. The rule of thumb is 2148to allow about ten times the size of the largest file 2149you will want to check in, although five times may be 2150adequate. For example, if you want to check in a file 2151which is 10 megabytes, you should have 100 megabytes of 2152memory on the machine doing the checkin (the server 2153machine for client/server, or the machine running 2154@sc{cvs} for non-client/server). This can be swap 2155space rather than physical memory. Because the memory 2156is only required briefly, there is no particular need 2157to allow memory for more than one such checkin at a 2158time. 2159@c The 5-10 times rule of thumb is from Paul Eggert for 2160@c GNU diff. I don't think it is in the GNU diff 2161@c manual or anyplace like that. 2162@c 2163@c Probably we could be saying more about 2164@c non-client/server CVS. 2165@c I would guess for non-client/server CVS in an NFS 2166@c environment the biggest issues are the network and 2167@c the NFS server. 2168 2169Resource consumption for the client is even more 2170modest---any machine with enough capacity to run the 2171operating system in question should have little 2172trouble. 2173@c Is that true? I think the client still wants to 2174@c (bogusly) store entire files in memory at times. 2175 2176For information on disk space requirements, see 2177@ref{Creating a repository}. 2178 2179@node The connection method 2180@subsection The connection method 2181 2182In its simplest form, the @var{method} portion of the repository string 2183(@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork}, 2184@samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some 2185platforms, @samp{server}. 2186 2187If @var{method} is not specified, and the repository 2188name starts with a @samp{/}, then the default is @code{local}. 2189If @var{method} is not specified, and the repository 2190name does not start with a @samp{/}, then the default is @code{ext} 2191or @code{server}, depending on your platform; both the @samp{ext} 2192and @samp{server} methods are described in @ref{Connecting via rsh}. 2193 2194@cindex connection method options 2195@cindex options, connection method 2196The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection 2197methods all accept optional method options, specified as part of the 2198@var{method} string, like so: 2199 2200@example 2201:@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data} 2202@end example 2203 2204@sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though 2205it may sometimes be sensitive to the case of @var{arg}. The possible method 2206options are as follows: 2207 2208@table @code 2209@cindex CVS_PROXY_PORT 2210@cindex proxy, method option 2211@cindex proxyport, method option 2212@cindex proxies, web, connecting via 2213@cindex web proxies, connecting via 2214@cindex proxies, HTTP, connecting via 2215@cindex HTTP proxies, connecting via 2216@item proxy=@var{hostname} 2217@itemx proxyport=@var{port} 2218These two method options can be used to connect via an HTTP tunnel style web 2219proxy. @var{hostname} should be the name of the HTTP proxy server to connect 2220through and @var{port} is the port number on the HTTP proxy server to connect 2221via. @var{port} defaults to 8080. 2222 2223@strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy 2224server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.} 2225 2226For example, to connect pserver via a web proxy listening on port 8000 of 2227www.myproxy.net, you would use a method of: 2228 2229@example 2230:pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string} 2231@end example 2232 2233@strong{NOTE: In the above example, @var{pserver_connection_string} is still 2234required to connect and authenticate to the CVS server, as noted in the 2235upcoming sections on password authentication, @code{gserver}, and 2236@code{kserver}. The example above only demonstrates a modification to the 2237@var{method} portion of the repository name.} 2238 2239These options first appeared in @sc{cvs} version 1.12.7 and are valid as 2240modifcations to the @code{gserver} and @code{pserver} connection methods. 2241 2242@cindex CVS_RSH method option 2243@item CVS_RSH=@var{path} 2244This method option can be used with the @code{ext} method to specify the path 2245the @sc{cvs} client will use to find the remote shell used to contact the 2246@sc{cvs} server and takes precedence over any path specified in the 2247@code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}). For 2248example, to connect to a @sc{cvs} server via the local 2249@file{/path/to/ssh/command} command, you could choose to specify the following 2250@var{path} via the @code{CVS_RSH} method option: 2251 2252@example 2253:ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string} 2254@end example 2255 2256This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2257as a modifcation to the @code{ext} connection method. 2258 2259@cindex CVS_SERVER method option 2260@item CVS_SERVER=@var{path} 2261This method option can be used with the @code{ext} and @code{fork} methods to 2262specify the path @sc{cvs} will use to find the @sc{cvs} executable on the 2263@sc{cvs} server and takes precedence over any path specified in the 2264@code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}). For 2265example, to select the remote @file{/path/to/cvs/command} executable as your 2266@sc{cvs} server application on the @sc{cvs} server machine, you could choose to 2267specify the following @var{path} via the @code{CVS_SERVER} method option: 2268 2269@example 2270:ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string} 2271@end example 2272 2273@noindent 2274or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your 2275@code{$PATH} on the @sc{cvs} server: 2276 2277@example 2278:ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string} 2279@end example 2280 2281This method option first appeared in @sc{cvs} version 1.12.11 and is valid 2282as a modifcation to both the @code{ext} and @code{fork} connection methods. 2283 2284@cindex Redirect, method option 2285@item Redirect=@var{boolean-state} 2286The @code{Redirect} method option determines whether the @sc{cvs} client will 2287allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually 2288for write requests, as in a write proxy setup. 2289 2290A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config} 2291file options is acceptable here (@pxref{config}). For example, @samp{on}, 2292@samp{off}, @samp{true}, and @samp{false} are all valid values for 2293@var{boolean-state}. @var{boolean-state} for the @code{Redirect} method option 2294defaults to @samp{on}. 2295 2296This option will have no effect when talking to any non-secondary @sc{cvs} 2297server. For more on write proxies and secondary servers, please see 2298@ref{Write proxies}. 2299 2300This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2301as a modifcation to the @code{ext} connection method. 2302@end table 2303 2304As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER} 2305options, a method specification like the following would work: 2306 2307@example 2308:ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command: 2309@end example 2310 2311This means that you would not need to have 2312the @code{CVS_SERVER} or @code{CVS_RSH} environment 2313variables set correctly. See @ref{Connecting via rsh}, for more details on 2314these environment variables. 2315 2316@node Connecting via rsh 2317@subsection Connecting with rsh 2318 2319@cindex rsh 2320@sc{cvs} uses the @samp{rsh} protocol to perform these 2321operations, so the remote user host needs to have a 2322@file{.rhosts} file which grants access to the local 2323user. Note that the program that @sc{cvs} uses for this 2324purpose may be specified using the @file{--with-rsh} 2325flag to configure. 2326 2327For example, suppose you are the user @samp{mozart} on 2328the local machine @samp{toe.example.com}, and the 2329server machine is @samp{faun.example.org}. On 2330faun, put the following line into the file 2331@file{.rhosts} in @samp{bach}'s home directory: 2332 2333@example 2334toe.example.com mozart 2335@end example 2336 2337@noindent 2338Then test that @samp{rsh} is working with 2339 2340@example 2341rsh -l bach faun.example.org 'echo $PATH' 2342@end example 2343 2344@cindex CVS_SERVER, environment variable 2345Next you have to make sure that @code{rsh} will be able 2346to find the server. Make sure that the path which 2347@code{rsh} printed in the above example includes the 2348directory containing a program named @code{cvs} which 2349is the server. You need to set the path in 2350@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 2351or @file{.profile}. Alternately, you can set the 2352environment variable @code{CVS_SERVER} on the client 2353machine to the filename of the server you want to use, 2354for example @file{/usr/local/bin/cvs-1.6}. 2355For the @code{ext} and @code{fork} methods, you may 2356also specify @var{CVS_SERVER} as an otpion in the 2357@var{CVSROOT} so that you may use different servers for 2358differnt roots. See @ref{Remote repositories} for more 2359details. 2360 2361There is no need to edit @file{inetd.conf} or start a 2362@sc{cvs} server daemon. 2363 2364@cindex :server:, setting up 2365@cindex :ext:, setting up 2366@cindex Kerberos, using kerberized rsh 2367@cindex SSH (rsh replacement) 2368@cindex rsh replacements (Kerberized, SSH, &c) 2369There are two access methods that you use in @code{CVSROOT} 2370for rsh. @code{:server:} specifies an internal rsh 2371client, which is supported only by some @sc{cvs} ports. 2372@code{:ext:} specifies an external rsh program. By 2373default this is @code{rsh} (unless otherwise specified 2374by the @file{--with-rsh} flag to configure) but you may set the 2375@code{CVS_RSH} environment variable to invoke another 2376program which can access the remote server (for 2377example, @code{remsh} on HP-UX 9 because @code{rsh} is 2378something different). It must be a program which can 2379transmit data to and from the server without modifying 2380it; for example the Windows NT @code{rsh} is not 2381suitable since it by default translates between CRLF 2382and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 2383to @code{rsh} to get around this, but since this could 2384potentially cause problems for programs other than the 2385standard @code{rsh}, it may change in the future. If 2386you set @code{CVS_RSH} to @code{SSH} or some other rsh 2387replacement, the instructions in the rest of this 2388section concerning @file{.rhosts} and so on are likely 2389to be inapplicable; consult the documentation for your rsh 2390replacement. 2391 2392You may choose to specify the @var{CVS_RSH} option as a method option 2393in the @var{CVSROOT} string to allow you to use different connection tools 2394for different roots (@pxref{The connection method}). For example, allowing 2395some roots to use @code{CVS_RSH=remsh} and some to use 2396@code{CVS_RSH=ssh} for the @code{ext} method. See also 2397the @ref{Remote repositories} for more details. 2398@c See also the comment in src/client.c for rationale 2399@c concerning "rsh" being the default and never 2400@c "remsh". 2401 2402Continuing our example, supposing you want to access 2403the module @file{foo} in the repository 2404@file{/usr/local/cvsroot/}, on machine 2405@file{faun.example.org}, you are ready to go: 2406 2407@example 2408cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2409@end example 2410 2411@noindent 2412(The @file{bach@@} can be omitted if the username is 2413the same on both the local and remote hosts.) 2414 2415@c Should we mention "rsh host echo hi" and "rsh host 2416@c cat" (the latter followed by typing text and ^D) 2417@c as troubleshooting techniques? Probably yes 2418@c (people tend to have trouble setting this up), 2419@c but this kind of thing can be hard to spell out. 2420 2421@node Password authenticated 2422@subsection Direct connection with password authentication 2423 2424The @sc{cvs} client can also connect to the server 2425using a password protocol. This is particularly useful 2426if using @code{rsh} is not feasible (for example, 2427the server is behind a firewall), and Kerberos also is 2428not available. 2429 2430 To use this method, it is necessary to make 2431some adjustments on both the server and client sides. 2432 2433@menu 2434* Password authentication server:: Setting up the server 2435* Password authentication client:: Using the client 2436* Password authentication security:: What this method does and does not do 2437@end menu 2438 2439@node Password authentication server 2440@subsubsection Setting up the server for password authentication 2441 2442First of all, you probably want to tighten the 2443permissions on the @file{$CVSROOT} and 2444@file{$CVSROOT/CVSROOT} directories. See @ref{Password 2445authentication security}, for more details. 2446 2447@cindex pserver (subcommand) 2448@cindex Remote repositories, port specification 2449@cindex Repositories, remote, port specification 2450@cindex Client/Server Operation, port specification 2451@cindex pserver (client/server connection method), port specification 2452@cindex kserver (client/server connection method), port specification 2453@cindex gserver (client/server connection method), port specification 2454@cindex port, specifying for remote repositories 2455@cindex Password server, setting up 2456@cindex Authenticating server, setting up 2457@cindex inetd, configuring for pserver 2458@cindex xinetd, configuring for pserver 2459@c FIXME: this isn't quite right regarding port 2460@c numbers; CVS looks up "cvspserver" in 2461@c /etc/services (on unix, but what about non-unix?). 2462On the server side, the file @file{/etc/inetd.conf} 2463needs to be edited so @code{inetd} knows to run the 2464command @code{cvs pserver} when it receives a 2465connection on the right port. By default, the port 2466number is 2401; it would be different if your client 2467were compiled with @code{CVS_AUTH_PORT} defined to 2468something else, though. This can also be specified in the CVSROOT variable 2469(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 2470environment variable (@pxref{Environment variables}). 2471 2472 If your @code{inetd} allows raw port numbers in 2473@file{/etc/inetd.conf}, then the following (all on a 2474single line in @file{inetd.conf}) should be sufficient: 2475 2476@example 24772401 stream tcp nowait root /usr/local/bin/cvs 2478cvs -f --allow-root=/usr/cvsroot pserver 2479@end example 2480 2481@noindent 2482(You could also use the 2483@samp{-T} option to specify a temporary directory.) 2484 2485The @samp{--allow-root} option specifies the allowable 2486@sc{cvsroot} directory. Clients which attempt to use a 2487different @sc{cvsroot} directory will not be allowed to 2488connect. If there is more than one @sc{cvsroot} 2489directory which you want to allow, repeat the option. 2490(Unfortunately, many versions of @code{inetd} have very small 2491limits on the number of arguments and/or the total length 2492of the command. The usual solution to this problem is 2493to have @code{inetd} run a shell script which then invokes 2494@sc{cvs} with the necessary arguments.) 2495 2496 If your @code{inetd} wants a symbolic service 2497name instead of a raw port number, then put this in 2498@file{/etc/services}: 2499 2500@example 2501cvspserver 2401/tcp 2502@end example 2503 2504@noindent 2505and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 2506 2507If your system uses @code{xinetd} instead of @code{inetd}, 2508the procedure is slightly different. 2509Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2510 2511@example 2512service cvspserver 2513@{ 2514 port = 2401 2515 socket_type = stream 2516 protocol = tcp 2517 wait = no 2518 user = root 2519 passenv = PATH 2520 server = /usr/local/bin/cvs 2521 server_args = -f --allow-root=/usr/cvsroot pserver 2522@} 2523@end example 2524 2525@noindent 2526(If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2527the @code{port} line.) 2528 2529 Once the above is taken care of, restart your 2530@code{inetd}, or do whatever is necessary to force it 2531to reread its initialization files. 2532 2533If you are having trouble setting this up, see 2534@ref{Connection}. 2535 2536@cindex CVS passwd file 2537@cindex passwd (admin file) 2538Because the client stores and transmits passwords in 2539cleartext (almost---see @ref{Password authentication 2540security}, for details), a separate @sc{cvs} password 2541file is generally used, so people don't compromise 2542their regular passwords when they access the 2543repository. This file is 2544@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 2545administrative files}). It uses a colon-separated 2546format, similar to @file{/etc/passwd} on Unix systems, 2547except that it has fewer fields: @sc{cvs} username, 2548optional password, and an optional system username for 2549@sc{cvs} to run as if authentication succeeds. Here is 2550an example @file{passwd} file with five entries: 2551 2552@example 2553anonymous: 2554bach:ULtgRLXo7NRxs 2555spwang:1sOp854gDF3DY 2556melissa:tGX1fS8sun6rY:pubcvs 2557qproj:XR4EZcEs0szik:pubcvs 2558@end example 2559 2560@noindent 2561(The passwords are encrypted according to the standard 2562Unix @code{crypt()} function, so it is possible to 2563paste in passwords directly from regular Unix 2564@file{/etc/passwd} files.) 2565 2566The first line in the example will grant access to any 2567@sc{cvs} client attempting to authenticate as user 2568@code{anonymous}, no matter what password they use, 2569including an empty password. (This is typical for 2570sites granting anonymous read-only access; for 2571information on how to do the "read-only" part, see 2572@ref{Read-only access}.) 2573 2574The second and third lines will grant access to 2575@code{bach} and @code{spwang} if they supply their 2576respective plaintext passwords. 2577 2578@cindex User aliases 2579The fourth line will grant access to @code{melissa}, if 2580she supplies the correct password, but her @sc{cvs} 2581operations will actually run on the server side under 2582the system user @code{pubcvs}. Thus, there need not be 2583any system user named @code{melissa}, but there 2584@emph{must} be one named @code{pubcvs}. 2585 2586The fifth line shows that system user identities can be 2587shared: any client who successfully authenticates as 2588@code{qproj} will actually run as @code{pubcvs}, just 2589as @code{melissa} does. That way you could create a 2590single, shared system user for each project in your 2591repository, and give each developer their own line in 2592the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 2593username on each line would be different, but the 2594system username would be the same. The reason to have 2595different @sc{cvs} usernames is that @sc{cvs} will log their 2596actions under those names: when @code{melissa} commits 2597a change to a project, the checkin is recorded in the 2598project's history under the name @code{melissa}, not 2599@code{pubcvs}. And the reason to have them share a 2600system username is so that you can arrange permissions 2601in the relevant area of the repository such that only 2602that account has write-permission there. 2603 2604If the system-user field is present, all 2605password-authenticated @sc{cvs} commands run as that 2606user; if no system user is specified, @sc{cvs} simply 2607takes the @sc{cvs} username as the system username and 2608runs commands as that user. In either case, if there 2609is no such user on the system, then the @sc{cvs} 2610operation will fail (regardless of whether the client 2611supplied a valid password). 2612 2613The password and system-user fields can both be omitted 2614(and if the system-user field is omitted, then also 2615omit the colon that would have separated it from the 2616encrypted password). For example, this would be a 2617valid @file{$CVSROOT/CVSROOT/passwd} file: 2618 2619@example 2620anonymous::pubcvs 2621fish:rKa5jzULzmhOo:kfogel 2622sussman:1sOp854gDF3DY 2623@end example 2624 2625@noindent 2626When the password field is omitted or empty, then the 2627client's authentication attempt will succeed with any 2628password, including the empty string. However, the 2629colon after the @sc{cvs} username is always necessary, 2630even if the password is empty. 2631 2632@sc{cvs} can also fall back to use system authentication. 2633When authenticating a password, the server first checks 2634for the user in the @file{$CVSROOT/CVSROOT/passwd} 2635file. If it finds the user, it will use that entry for 2636authentication as described above. But if it does not 2637find the user, or if the @sc{cvs} @file{passwd} file 2638does not exist, then the server can try to authenticate 2639the username and password using the operating system's 2640user-lookup routines (this "fallback" behavior can be 2641disabled by setting @code{SystemAuth=no} in the 2642@sc{cvs} @file{config} file, @pxref{config}). 2643 2644The default fallback behavior is to look in 2645@file{/etc/passwd} for this system user unless your 2646system has PAM (Pluggable Authentication Modules) 2647and your @sc{cvs} server executable was configured to 2648use it at compile time (using @code{./configure --enable-pam} - see the 2649INSTALL file for more). In this case, PAM will be consulted instead. 2650This means that @sc{cvs} can be configured to use any password 2651authentication source PAM can be configured to use (possibilities 2652include a simple UNIX password, NIS, LDAP, and others) in its 2653global configuration file (usually @file{/etc/pam.conf} 2654or possibly @file{/etc/pam.d/cvs}). See your PAM documentation 2655for more details on PAM configuration. 2656 2657Note that PAM is an experimental feature in @sc{cvs} and feedback is 2658encouraged. Please send a mail to one of the @sc{cvs} mailing lists 2659(@code{info-cvs@@nongnu.org} or @code{bug-cvs@@nongnu.org}) if you use the 2660@sc{cvs} PAM support. 2661 2662@strong{WARNING: Using PAM gives the system administrator much more 2663flexibility about how @sc{cvs} users are authenticated but 2664no more security than other methods. See below for more.} 2665 2666CVS needs an "auth", "account" and "session" module in the 2667PAM configuration file. A typical PAM configuration 2668would therefore have the following lines 2669in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 2670system @file{/etc/passwd} authentication: 2671 2672@example 2673cvs auth required pam_unix.so 2674cvs account required pam_unix.so 2675cvs session required pam_unix.so 2676@end example 2677 2678The the equivalent @file{/etc/pam.d/cvs} would contain 2679 2680@example 2681auth required pam_unix.so 2682account required pam_unix.so 2683session required pam_unix.so 2684@end example 2685 2686Some systems require a full path to the module so that 2687@file{pam_unix.so} (Linux) would become something like 2688@file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris). 2689See the @file{contrib/pam} subdirectory of the @sc{cvs} 2690source distribution for further example configurations. 2691 2692The PAM service name given above as "cvs" is just 2693the service name in the default configuration and can be 2694set using 2695@code{./configure --with-hardcoded-pam-service-name=<pam-service-name>} 2696before compiling. @sc{cvs} can also be configured to use whatever 2697name it is invoked as as its PAM service name using 2698@code{./configure --without-hardcoded-pam-service-name}, but this 2699feature should not be used if you may not have control of the name 2700@sc{cvs} will be invoked as. 2701 2702Be aware, also, that falling back to system 2703authentication might be a security risk: @sc{cvs} 2704operations would then be authenticated with that user's 2705regular login password, and the password flies across 2706the network in plaintext. See @ref{Password 2707authentication security} for more on this. 2708This may be more of a problem with PAM authentication 2709because it is likely that the source of the system 2710password is some central authentication service like 2711LDAP which is also used to authenticate other services. 2712 2713On the other hand, PAM makes it very easy to change your password 2714regularly. If they are given the option of a one-password system for 2715all of their activities, users are often more willing to change their 2716password on a regular basis. 2717 2718In the non-PAM configuration where the password is stored in the 2719@file{CVSROOT/passwd} file, it is difficult to change passwords on a 2720regular basis since only administrative users (or in some cases 2721processes that act as an administrative user) are typically given 2722access to modify this file. Either there needs to be some 2723hand-crafted web page or set-uid program to update the file, or the 2724update needs to be done by submitting a request to an administrator to 2725perform the duty by hand. In the first case, having to remember to 2726update a separate password on a periodic basis can be difficult. In 2727the second case, the manual nature of the change will typically mean 2728that the password will not be changed unless it is absolutely 2729necessary. 2730 2731Note that PAM administrators should probably avoid configuring 2732one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If 2733OTPs are desired, the administrator may wish to encourage the use of 2734one of the other Client/Server access methods. See the section on 2735@pxref{Remote repositories} for a list of other methods. 2736 2737Right now, the only way to put a password in the 2738@sc{cvs} @file{passwd} file is to paste it there from 2739somewhere else. Someday, there may be a @code{cvs 2740passwd} command. 2741 2742Unlike many of the files in @file{$CVSROOT/CVSROOT}, it 2743is normal to edit the @file{passwd} file in-place, 2744rather than via @sc{cvs}. This is because of the 2745possible security risks of having the @file{passwd} 2746file checked out to people's working copies. If you do 2747want to include the @file{passwd} file in checkouts of 2748@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 2749 2750@c We might also suggest using the @code{htpasswd} command 2751@c from freely available web servers as well, but that 2752@c would open up a can of worms in that the users next 2753@c questions are likely to be "where do I get it?" and 2754@c "how do I use it?" 2755@c Also note that htpasswd, at least the version I had, 2756@c likes to clobber the third field. 2757 2758@node Password authentication client 2759@subsubsection Using the client with password authentication 2760@cindex Login (subcommand) 2761@cindex Password client, using 2762@cindex Authenticated client, using 2763@cindex :pserver:, setting up 2764To run a @sc{cvs} command on a remote repository via 2765the password-authenticating server, one specifies the 2766@code{pserver} protocol, optional username, repository host, an 2767optional port number, and path to the repository. For example: 2768 2769@example 2770cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 2771@end example 2772 2773@noindent 2774or 2775 2776@example 2777CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 2778cvs checkout someproj 2779@end example 2780 2781However, unless you're connecting to a public-access 2782repository (i.e., one where that username doesn't 2783require a password), you'll need to supply a password or @dfn{log in} first. 2784Logging in verifies your password with the repository and stores it in a file. 2785It's done with the @code{login} command, which will 2786prompt you interactively for the password if you didn't supply one as part of 2787@var{$CVSROOT}: 2788 2789@example 2790cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 2791CVS password: 2792@end example 2793 2794@noindent 2795or 2796 2797@example 2798cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 2799@end example 2800 2801After you enter the password, @sc{cvs} verifies it with 2802the server. If the verification succeeds, then that 2803combination of username, host, repository, and password 2804is permanently recorded, so future transactions with 2805that repository won't require you to run @code{cvs 2806login}. (If verification fails, @sc{cvs} will exit 2807complaining that the password was incorrect, and 2808nothing will be recorded.) 2809 2810The records are stored, by default, in the file 2811@file{$HOME/.cvspass}. That file's format is 2812human-readable, and to a degree human-editable, but 2813note that the passwords are not stored in 2814cleartext---they are trivially encoded to protect them 2815from "innocent" compromise (i.e., inadvertent viewing 2816by a system administrator or other non-malicious 2817person). 2818 2819@cindex CVS_PASSFILE, environment variable 2820You can change the default location of this file by 2821setting the @code{CVS_PASSFILE} environment variable. 2822If you use this variable, make sure you set it 2823@emph{before} @code{cvs login} is run. If you were to 2824set it after running @code{cvs login}, then later 2825@sc{cvs} commands would be unable to look up the 2826password for transmission to the server. 2827 2828Once you have logged in, all @sc{cvs} commands using 2829that remote repository and username will authenticate 2830with the stored password. So, for example 2831 2832@example 2833cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2834@end example 2835 2836@noindent 2837should just work (unless the password changes on the 2838server side, in which case you'll have to re-run 2839@code{cvs login}). 2840 2841Note that if the @samp{:pserver:} were not present in 2842the repository specification, @sc{cvs} would assume it 2843should use @code{rsh} to connect with the server 2844instead (@pxref{Connecting via rsh}). 2845 2846Of course, once you have a working copy checked out and 2847are running @sc{cvs} commands from within it, there is 2848no longer any need to specify the repository 2849explicitly, because @sc{cvs} can deduce the repository 2850from the working copy's @file{CVS} subdirectory. 2851 2852@c FIXME: seems to me this needs somewhat more 2853@c explanation. 2854@cindex Logout (subcommand) 2855The password for a given remote repository can be 2856removed from the @code{CVS_PASSFILE} by using the 2857@code{cvs logout} command. 2858 2859@node Password authentication security 2860@subsubsection Security considerations with password authentication 2861 2862@cindex Security, of pserver 2863The passwords are stored on the client side in a 2864trivial encoding of the cleartext, and transmitted in 2865the same encoding. The encoding is done only to 2866prevent inadvertent password compromises (i.e., a 2867system administrator accidentally looking at the file), 2868and will not prevent even a naive attacker from gaining 2869the password. 2870 2871@c FIXME: The bit about "access to the repository 2872@c implies general access to the system is *not* specific 2873@c to pserver; it applies to kerberos and SSH and 2874@c everything else too. Should reorganize the 2875@c documentation to make this clear. 2876The separate @sc{cvs} password file (@pxref{Password 2877authentication server}) allows people 2878to use a different password for repository access than 2879for login access. On the other hand, once a user has 2880non-read-only 2881access to the repository, she can execute programs on 2882the server system through a variety of means. Thus, repository 2883access implies fairly broad system access as well. It 2884might be possible to modify @sc{cvs} to prevent that, 2885but no one has done so as of this writing. 2886@c OpenBSD uses chroot() and copies the repository to 2887@c provide anonymous read-only access (for details see 2888@c http://www.openbsd.org/anoncvs.shar). While this 2889@c closes the most obvious holes, I'm not sure it 2890@c closes enough holes to recommend it (plus it is 2891@c *very* easy to accidentally screw up a setup of this 2892@c type). 2893 2894Note that because the @file{$CVSROOT/CVSROOT} directory 2895contains @file{passwd} and other files which are used 2896to check security, you must control the permissions on 2897this directory as tightly as the permissions on 2898@file{/etc}. The same applies to the @file{$CVSROOT} 2899directory itself and any directory 2900above it in the tree. Anyone who has write access to 2901such a directory will have the ability to become any 2902user on the system. Note that these permissions are 2903typically tighter than you would use if you are not 2904using pserver. 2905@c TODO: Would be really nice to document/implement a 2906@c scheme where the CVS server can run as some non-root 2907@c user, e.g. "cvs". CVSROOT/passwd would contain a 2908@c bunch of entries of the form foo:xxx:cvs (or the "cvs" 2909@c would be implicit). This would greatly reduce 2910@c security risks such as those hinted at in the 2911@c previous paragraph. I think minor changes to CVS 2912@c might be required but mostly this would just need 2913@c someone who wants to play with it, document it, &c. 2914 2915In summary, anyone who gets the password gets 2916repository access (which may imply some measure of general system 2917access as well). The password is available to anyone 2918who can sniff network packets or read a protected 2919(i.e., user read-only) file. If you want real 2920security, get Kerberos. 2921 2922@node GSSAPI authenticated 2923@subsection Direct connection with GSSAPI 2924 2925@cindex GSSAPI 2926@cindex Security, GSSAPI 2927@cindex :gserver:, setting up 2928@cindex Kerberos, using :gserver: 2929GSSAPI is a generic interface to network security 2930systems such as Kerberos 5. 2931If you have a working GSSAPI library, you can have 2932@sc{cvs} connect via a direct @sc{tcp} connection, 2933authenticating with GSSAPI. 2934 2935To do this, @sc{cvs} needs to be compiled with GSSAPI 2936support; when configuring @sc{cvs} it tries to detect 2937whether GSSAPI libraries using Kerberos version 5 are 2938present. You can also use the @file{--with-gssapi} 2939flag to configure. 2940 2941The connection is authenticated using GSSAPI, but the 2942message stream is @emph{not} authenticated by default. 2943You must use the @code{-a} global option to request 2944stream authentication. 2945 2946The data transmitted is @emph{not} encrypted by 2947default. Encryption support must be compiled into both 2948the client and the server; use the 2949@file{--enable-encrypt} configure option to turn it on. 2950You must then use the @code{-x} global option to 2951request encryption. 2952 2953GSSAPI connections are handled on the server side by 2954the same server which handles the password 2955authentication server; see @ref{Password authentication 2956server}. If you are using a GSSAPI mechanism such as 2957Kerberos which provides for strong authentication, you 2958will probably want to disable the ability to 2959authenticate via cleartext passwords. To do so, create 2960an empty @file{CVSROOT/passwd} password file, and set 2961@code{SystemAuth=no} in the config file 2962(@pxref{config}). 2963 2964The GSSAPI server uses a principal name of 2965cvs/@var{hostname}, where @var{hostname} is the 2966canonical name of the server host. You will have to 2967set this up as required by your GSSAPI mechanism. 2968 2969To connect using GSSAPI, use the @samp{:gserver:} method. For 2970example, 2971 2972@example 2973cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 2974@end example 2975 2976@node Kerberos authenticated 2977@subsection Direct connection with Kerberos 2978 2979@cindex Kerberos, using :kserver: 2980@cindex Security, Kerberos 2981@cindex :kserver:, setting up 2982The easiest way to use Kerberos is to use the Kerberos 2983@code{rsh}, as described in @ref{Connecting via rsh}. 2984The main disadvantage of using rsh is that all the data 2985needs to pass through additional programs, so it may be 2986slower. So if you have Kerberos installed you can 2987connect via a direct @sc{tcp} connection, 2988authenticating with Kerberos. 2989 2990This section concerns the Kerberos network security 2991system, version 4. Kerberos version 5 is supported via 2992the GSSAPI generic network security interface, as 2993described in the previous section. 2994 2995To do this, @sc{cvs} needs to be compiled with Kerberos 2996support; when configuring @sc{cvs} it tries to detect 2997whether Kerberos is present or you can use the 2998@file{--with-krb4} flag to configure. 2999 3000The data transmitted is @emph{not} encrypted by 3001default. Encryption support must be compiled into both 3002the client and server; use the 3003@file{--enable-encryption} configure option to turn it 3004on. You must then use the @code{-x} global option to 3005request encryption. 3006 3007The CVS client will attempt to connect to port 1999 by default. 3008 3009@cindex kinit 3010When you want to use @sc{cvs}, get a ticket in the 3011usual way (generally @code{kinit}); it must be a ticket 3012which allows you to log into the server machine. Then 3013you are ready to go: 3014 3015@example 3016cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 3017@end example 3018 3019Previous versions of @sc{cvs} would fall back to a 3020connection via rsh; this version will not do so. 3021 3022@node Connecting via fork 3023@subsection Connecting with fork 3024 3025@cindex fork, access method 3026@cindex :fork:, setting up 3027This access method allows you to connect to a 3028repository on your local disk via the remote protocol. 3029In other words it does pretty much the same thing as 3030@code{:local:}, but various quirks, bugs and the like are 3031those of the remote @sc{cvs} rather than the local 3032@sc{cvs}. 3033 3034For day-to-day operations you might prefer either 3035@code{:local:} or @code{:fork:}, depending on your 3036preferences. Of course @code{:fork:} comes in 3037particularly handy in testing or 3038debugging @code{cvs} and the remote protocol. 3039Specifically, we avoid all of the network-related 3040setup/configuration, timeouts, and authentication 3041inherent in the other remote access methods but still 3042create a connection which uses the remote protocol. 3043 3044To connect using the @code{fork} method, use 3045@samp{:fork:} and the pathname to your local 3046repository. For example: 3047 3048@example 3049cvs -d :fork:/usr/local/cvsroot checkout foo 3050@end example 3051 3052@cindex CVS_SERVER, and :fork: 3053As with @code{:ext:}, the server is called @samp{cvs} 3054by default, or the value of the @code{CVS_SERVER} 3055environment variable. 3056 3057 3058@node Write proxies 3059@subsection Distributing load across several CVS servers 3060 3061@cindex PrimaryServer, in CVSROOT/config 3062@cindex Primary server 3063@cindex Secondary server 3064@cindex proxy, write 3065@cindex write proxy 3066@sc{cvs} can be configured to distribute usage across several @sc{cvs} 3067servers. This is accomplished by means of one or more @dfn{write proxies}, or 3068@dfn{secondary servers}, for a single @dfn{primary server}. 3069 3070When a @sc{cvs} client accesses a secondary server and only sends read 3071requests, then the secondary server handles the entire request. If the client 3072sends any write requests, however, the secondary server asks the client to 3073redirect its write request to the primary server, if the client supports 3074redirect requests, and otherwise becomes a transparent proxy for the primary 3075server, which actually handles the write request. 3076 3077In this manner, any number of read-only secondary servers may be configured as 3078write proxies for the primary server, effectively distributing the load from 3079all read operations between the secondary servers and restricting the load on 3080the primary server to write operations and pushing changes to the secondaries. 3081 3082Primary servers will not automatically push changes to secondaries. This must 3083be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, & 3084@file{postwatch} scripts (@pxref{Trigger Scripts}) like the following: 3085 3086@example 3087ALL rsync -gopr -essh ./ secondary:/cvsroot/%p & 3088@end example 3089 3090You would probably actually want to lock directories for write on the secondary 3091and for read on the primary before running the @samp{rsync} in the above 3092example, but describing such a setup is beyond the scope of this document. 3093 3094A secondary advantage of a write proxy setup is that users pointing at the 3095secondary server can still execute fast read operations while on a network that 3096connects to the primary over a slow link or even one where the link to the 3097primary is periodically broken. Only write operations will require the network 3098link to the primary. 3099 3100To configure write proxies, the primary must be specified with the 3101@samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}). For the 3102transparent proxy mode to work, all secondary servers must also be running the 3103same version of the @sc{cvs} server, or at least one that provides the same 3104list of supported requests to the client as the primary server. This is not 3105necessary for redirection. 3106 3107Once a primary server is configured, secondary servers may be configured by: 3108 3109@enumerate 3110@item 3111Duplicating the primary repository at the new location. 3112@item 3113Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and 3114@file{postwatch} files on the primary to propagate writes to the new secondary. 3115@item 3116Configure remote access to the secondary(ies) as you would configure access 3117to any other CVS server (@pxref{Remote repositories}). 3118@item 3119Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to 3120@strong{all} incovations of the secondary server if the path to the @sc{cvs} 3121repository directory is different on the two servers and you wish to support 3122clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier 3123clients do not handle the @samp{Redirect} response). 3124 3125Please note, again, that writethrough proxy suport requires 3126@code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all} 3127incovations of the secondary server, not just @samp{pserver} invocations. 3128This may require a wrapper script for the @sc{cvs} executable 3129on your server machine. 3130@end enumerate 3131 3132 3133@c --------------------------------------------------------------------- 3134@node Read-only access 3135@section Read-only repository access 3136@cindex Read-only repository access 3137@cindex readers (admin file) 3138@cindex writers (admin file) 3139 3140 It is possible to grant read-only repository 3141access to people using the password-authenticated 3142server (@pxref{Password authenticated}). (The 3143other access methods do not have explicit support for 3144read-only users because those methods all assume login 3145access to the repository machine anyway, and therefore 3146the user can do whatever local file permissions allow 3147her to do.) 3148 3149 A user who has read-only access can do only 3150those @sc{cvs} operations which do not modify the 3151repository, except for certain ``administrative'' files 3152(such as lock files and the history file). It may be 3153desirable to use this feature in conjunction with 3154user-aliasing (@pxref{Password authentication server}). 3155 3156Unlike with previous versions of @sc{cvs}, read-only 3157users should be able merely to read the repository, and 3158not to execute programs on the server or otherwise gain 3159unexpected levels of access. Or to be more accurate, 3160the @emph{known} holes have been plugged. Because this 3161feature is new and has not received a comprehensive 3162security audit, you should use whatever level of 3163caution seems warranted given your attitude concerning 3164security. 3165 3166 There are two ways to specify read-only access 3167for a user: by inclusion, and by exclusion. 3168 3169 "Inclusion" means listing that user 3170specifically in the @file{$CVSROOT/CVSROOT/readers} 3171file, which is simply a newline-separated list of 3172users. Here is a sample @file{readers} file: 3173 3174@example 3175melissa 3176splotnik 3177jrandom 3178@end example 3179 3180@noindent 3181 (Don't forget the newline after the last user.) 3182 3183 "Exclusion" means explicitly listing everyone 3184who has @emph{write} access---if the file 3185 3186@example 3187$CVSROOT/CVSROOT/writers 3188@end example 3189 3190@noindent 3191exists, then only 3192those users listed in it have write access, and 3193everyone else has read-only access (of course, even the 3194read-only users still need to be listed in the 3195@sc{cvs} @file{passwd} file). The 3196@file{writers} file has the same format as the 3197@file{readers} file. 3198 3199 Note: if your @sc{cvs} @file{passwd} 3200file maps cvs users onto system users (@pxref{Password 3201authentication server}), make sure you deny or grant 3202read-only access using the @emph{cvs} usernames, not 3203the system usernames. That is, the @file{readers} and 3204@file{writers} files contain cvs usernames, which may 3205or may not be the same as system usernames. 3206 3207 Here is a complete description of the server's 3208behavior in deciding whether to grant read-only or 3209read-write access: 3210 3211 If @file{readers} exists, and this user is 3212listed in it, then she gets read-only access. Or if 3213@file{writers} exists, and this user is NOT listed in 3214it, then she also gets read-only access (this is true 3215even if @file{readers} exists but she is not listed 3216there). Otherwise, she gets full read-write access. 3217 3218 Of course there is a conflict if the user is 3219listed in both files. This is resolved in the more 3220conservative way, it being better to protect the 3221repository too much than too little: such a user gets 3222read-only access. 3223 3224@node Server temporary directory 3225@section Temporary directories for the server 3226@cindex Temporary directories, and server 3227@cindex Server, temporary directories 3228 3229While running, the @sc{cvs} server creates temporary 3230directories. They are named 3231 3232@example 3233cvs-serv@var{pid} 3234@end example 3235 3236@noindent 3237where @var{pid} is the process identification number of 3238the server. 3239They are located in the directory specified by 3240the @samp{-T} global option (@pxref{Global options}), 3241the @code{TMPDIR} environment variable (@pxref{Environment variables}), 3242or, failing that, @file{/tmp}. 3243 3244In most cases the server will remove the temporary 3245directory when it is done, whether it finishes normally 3246or abnormally. However, there are a few cases in which 3247the server does not or cannot remove the temporary 3248directory, for example: 3249 3250@itemize @bullet 3251@item 3252If the server aborts due to an internal server error, 3253it may preserve the directory to aid in debugging 3254 3255@item 3256If the server is killed in a way that it has no way of 3257cleaning up (most notably, @samp{kill -KILL} on unix). 3258 3259@item 3260If the system shuts down without an orderly shutdown, 3261which tells the server to clean up. 3262@end itemize 3263 3264In cases such as this, you will need to manually remove 3265the @file{cvs-serv@var{pid}} directories. As long as 3266there is no server running with process identification 3267number @var{pid}, it is safe to do so. 3268 3269@c --------------------------------------------------------------------- 3270@node Starting a new project 3271@chapter Starting a project with CVS 3272@cindex Starting a project with CVS 3273@cindex Creating a project 3274 3275@comment --moduledb-- 3276Because renaming files and moving them between 3277directories is somewhat inconvenient, the first thing 3278you do when you start a new project should be to think 3279through your file organization. It is not impossible 3280to rename or move files, but it does increase the 3281potential for confusion and @sc{cvs} does have some 3282quirks particularly in the area of renaming 3283directories. @xref{Moving files}. 3284 3285What to do next depends on the situation at hand. 3286 3287@menu 3288* Setting up the files:: Getting the files into the repository 3289* Defining the module:: How to make a module of the files 3290@end menu 3291@c -- File permissions! 3292 3293@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3294@node Setting up the files 3295@section Setting up the files 3296 3297The first step is to create the files inside the repository. This can 3298be done in a couple of different ways. 3299 3300@c -- The contributed scripts 3301@menu 3302* From files:: This method is useful with old projects 3303 where files already exist. 3304* From other version control systems:: Old projects where you want to 3305 preserve history from another system. 3306* From scratch:: Creating a directory tree from scratch. 3307@end menu 3308 3309@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3310@node From files 3311@subsection Creating a directory tree from a number of files 3312@cindex Importing files 3313 3314When you begin using @sc{cvs}, you will probably already have several 3315projects that can be 3316put under @sc{cvs} control. In these cases the easiest way is to use the 3317@code{import} command. An example is probably the easiest way to 3318explain how to use it. If the files you want to install in 3319@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 3320repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 3321 3322@example 3323$ cd @var{wdir} 3324$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 3325@end example 3326 3327Unless you supply a log message with the @samp{-m} 3328flag, @sc{cvs} starts an editor and prompts for a 3329message. The string @samp{yoyo} is a @dfn{vendor tag}, 3330and @samp{start} is a @dfn{release tag}. They may fill 3331no purpose in this context, but since @sc{cvs} requires 3332them they must be present. @xref{Tracking sources}, for 3333more information about them. 3334 3335You can now verify that it worked, and remove your 3336original source directory. 3337@c FIXME: Need to say more about "verify that it 3338@c worked". What should the user look for in the output 3339@c from "diff -r"? 3340 3341@example 3342$ cd .. 3343$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 3344$ diff -r @var{wdir} yoyodyne/@var{rdir} 3345$ rm -r @var{wdir} 3346@end example 3347 3348@noindent 3349Erasing the original sources is a good idea, to make sure that you do 3350not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 3351Of course, it would be wise to make sure that you have 3352a backup of the sources before you remove them. 3353 3354The @code{checkout} command can either take a module 3355name as argument (as it has done in all previous 3356examples) or a path name relative to @code{$CVSROOT}, 3357as it did in the example above. 3358 3359It is a good idea to check that the permissions 3360@sc{cvs} sets on the directories inside @code{$CVSROOT} 3361are reasonable, and that they belong to the proper 3362groups. @xref{File permissions}. 3363 3364If some of the files you want to import are binary, you 3365may want to use the wrappers features to specify which 3366files are binary and which are not. @xref{Wrappers}. 3367 3368@c The node name is too long, but I am having trouble 3369@c thinking of something more concise. 3370@node From other version control systems 3371@subsection Creating Files From Other Version Control Systems 3372@cindex Importing files, from other version control systems 3373 3374If you have a project which you are maintaining with 3375another version control system, such as @sc{rcs}, you 3376may wish to put the files from that project into 3377@sc{cvs}, and preserve the revision history of the 3378files. 3379 3380@table @asis 3381@cindex RCS, importing files from 3382@item From RCS 3383If you have been using @sc{rcs}, find the @sc{rcs} 3384files---usually a file named @file{foo.c} will have its 3385@sc{rcs} file in @file{RCS/foo.c,v} (but it could be 3386other places; consult the @sc{rcs} documentation for 3387details). Then create the appropriate directories in 3388@sc{cvs} if they do not already exist. Then copy the 3389files into the appropriate directories in the @sc{cvs} 3390repository (the name in the repository must be the name 3391of the source file with @samp{,v} added; the files go 3392directly in the appropriate directory of the repository, 3393not in an @file{RCS} subdirectory). This is one of the 3394few times when it is a good idea to access the @sc{cvs} 3395repository directly, rather than using @sc{cvs} 3396commands. Then you are ready to check out a new 3397working directory. 3398@c Someday there probably should be a "cvs import -t 3399@c rcs" or some such. It could even create magic 3400@c branches. It could also do something about the case 3401@c where the RCS file had a (non-magic) "0" branch. 3402 3403The @sc{rcs} file should not be locked when you move it 3404into @sc{cvs}; if it is, @sc{cvs} will have trouble 3405letting you operate on it. 3406@c What is the easiest way to unlock your files if you 3407@c have them locked? Especially if you have a lot of them? 3408@c This is a CVS bug/misfeature; importing RCS files 3409@c should ignore whether they are locked and leave them in 3410@c an unlocked state. Yet another reason for a separate 3411@c "import RCS file" command. 3412 3413@c How many is "many"? Or do they just import RCS files? 3414@item From another version control system 3415Many version control systems have the ability to export 3416@sc{rcs} files in the standard format. If yours does, 3417export the @sc{rcs} files and then follow the above 3418instructions. 3419 3420Failing that, probably your best bet is to write a 3421script that will check out the files one revision at a 3422time using the command line interface to the other 3423system, and then check the revisions into @sc{cvs}. 3424The @file{sccs2rcs} script mentioned below may be a 3425useful example to follow. 3426 3427@cindex SCCS, importing files from 3428@item From SCCS 3429There is a script in the @file{contrib} directory of 3430the @sc{cvs} source distribution called @file{sccs2rcs} 3431which converts @sc{sccs} files to @sc{rcs} files. 3432Note: you must run it on a machine which has both 3433@sc{sccs} and @sc{rcs} installed, and like everything 3434else in contrib it is unsupported (your mileage may 3435vary). 3436 3437@cindex PVCS, importing files from 3438@item From PVCS 3439There is a script in the @file{contrib} directory of 3440the @sc{cvs} source distribution called @file{pvcs_to_rcs} 3441which converts @sc{pvcs} archives to @sc{rcs} files. 3442You must run it on a machine which has both 3443@sc{pvcs} and @sc{rcs} installed, and like everything 3444else in contrib it is unsupported (your mileage may 3445vary). See the comments in the script for details. 3446@end table 3447@c CMZ and/or PATCHY were systems that were used in the 3448@c high energy physics community (especially for 3449@c CERNLIB). CERN has replaced them with CVS, but the 3450@c CAR format seems to live on as a way to submit 3451@c changes. There is a program car2cvs which converts 3452@c but I'm not sure where one gets a copy. 3453@c Not sure it is worth mentioning here, since it would 3454@c appear to affect only one particular community. 3455@c Best page for more information is: 3456@c http://wwwcn1.cern.ch/asd/cvs/index.html 3457@c See also: 3458@c http://ecponion.cern.ch/ecpsa/cernlib.html 3459 3460@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3461@node From scratch 3462@subsection Creating a directory tree from scratch 3463 3464@c Also/instead should be documenting 3465@c $ cvs co -l . 3466@c $ mkdir tc 3467@c $ cvs add tc 3468@c $ cd tc 3469@c $ mkdir man 3470@c $ cvs add man 3471@c etc. 3472@c Using import to create the directories only is 3473@c probably a somewhat confusing concept. 3474For a new project, the easiest thing to do is probably 3475to create an empty directory structure, like this: 3476 3477@example 3478$ mkdir tc 3479$ mkdir tc/man 3480$ mkdir tc/testing 3481@end example 3482 3483After that, you use the @code{import} command to create 3484the corresponding (empty) directory structure inside 3485the repository: 3486 3487@example 3488$ cd tc 3489$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 3490@end example 3491 3492This will add yoyodyne/@var{dir} as a directory under 3493@code{$CVSROOT}. 3494 3495Use @code{checkout} to get the new project. Then, use @code{add} 3496to add files (and new directories) as needed. 3497 3498@example 3499$ cd .. 3500$ cvs co yoyodyne/@var{dir} 3501@end example 3502 3503Check that the permissions @sc{cvs} sets on the 3504directories inside @code{$CVSROOT} are reasonable. 3505 3506@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3507@node Defining the module 3508@section Defining the module 3509@cindex Defining a module 3510@cindex Editing the modules file 3511@cindex Module, defining 3512@cindex Modules file, changing 3513 3514The next step is to define the module in the 3515@file{modules} file. This is not strictly necessary, 3516but modules can be convenient in grouping together 3517related files and directories. 3518 3519In simple cases these steps are sufficient to define a module. 3520 3521@enumerate 3522@item 3523Get a working copy of the modules file. 3524 3525@example 3526$ cvs checkout CVSROOT/modules 3527$ cd CVSROOT 3528@end example 3529 3530@item 3531Edit the file and insert a line that defines the module. @xref{Intro 3532administrative files}, for an introduction. @xref{modules}, for a full 3533description of the modules file. You can use the 3534following line to define the module @samp{tc}: 3535 3536@example 3537tc yoyodyne/tc 3538@end example 3539 3540@item 3541Commit your changes to the modules file. 3542 3543@example 3544$ cvs commit -m "Added the tc module." modules 3545@end example 3546 3547@item 3548Release the modules module. 3549 3550@example 3551$ cd .. 3552$ cvs release -d CVSROOT 3553@end example 3554@end enumerate 3555 3556@c --------------------------------------------------------------------- 3557@node Revisions 3558@chapter Revisions 3559 3560For many uses of @sc{cvs}, one doesn't need to worry 3561too much about revision numbers; @sc{cvs} assigns 3562numbers such as @code{1.1}, @code{1.2}, and so on, and 3563that is all one needs to know. However, some people 3564prefer to have more knowledge and control concerning 3565how @sc{cvs} assigns revision numbers. 3566 3567If one wants to keep track of a set of revisions 3568involving more than one file, such as which revisions 3569went into a particular release, one uses a @dfn{tag}, 3570which is a symbolic revision which can be assigned to a 3571numeric revision in each file. 3572 3573@menu 3574* Revision numbers:: The meaning of a revision number 3575* Versions revisions releases:: Terminology used in this manual 3576* Assigning revisions:: Assigning revisions 3577* Tags:: Tags--Symbolic revisions 3578* Tagging the working directory:: The cvs tag command 3579* Tagging by date/tag:: The cvs rtag command 3580* Modifying tags:: Adding, renaming, and deleting tags 3581* Tagging add/remove:: Tags with adding and removing files 3582* Sticky tags:: Certain tags are persistent 3583@end menu 3584 3585@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3586@node Revision numbers 3587@section Revision numbers 3588@cindex Revision numbers 3589@cindex Revision tree 3590@cindex Linear development 3591@cindex Number, revision- 3592@cindex Decimal revision number 3593@cindex Branch number 3594@cindex Number, branch 3595 3596Each version of a file has a unique @dfn{revision 3597number}. Revision numbers look like @samp{1.1}, 3598@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 3599A revision number always has an even number of 3600period-separated decimal integers. By default revision 36011.1 is the first revision of a file. Each successive 3602revision is given a new number by increasing the 3603rightmost number by one. The following figure displays 3604a few revisions, with newer revisions to the right. 3605 3606@example 3607 +-----+ +-----+ +-----+ +-----+ +-----+ 3608 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 3609 +-----+ +-----+ +-----+ +-----+ +-----+ 3610@end example 3611 3612It is also possible to end up with numbers containing 3613more than one period, for example @samp{1.3.2.2}. Such 3614revisions represent revisions on branches 3615(@pxref{Branching and merging}); such revision numbers 3616are explained in detail in @ref{Branches and 3617revisions}. 3618 3619@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3620@node Versions revisions releases 3621@section Versions, revisions and releases 3622@cindex Revisions, versions and releases 3623@cindex Versions, revisions and releases 3624@cindex Releases, revisions and versions 3625 3626A file can have several versions, as described above. 3627Likewise, a software product can have several versions. 3628A software product is often given a version number such 3629as @samp{4.1.1}. 3630 3631Versions in the first sense are called @dfn{revisions} 3632in this document, and versions in the second sense are 3633called @dfn{releases}. To avoid confusion, the word 3634@dfn{version} is almost never used in this document. 3635 3636@node Assigning revisions 3637@section Assigning revisions 3638 3639@c We avoid the "major revision" terminology. It seems 3640@c like jargon. Hopefully "first number" is clear enough. 3641@c 3642@c Well, in the context of software release numbers, 3643@c "major" and "minor" release or version numbers are 3644@c documented in at least the GNU Coding Standards, but I'm 3645@c still not sure I find that a valid reason to apply the 3646@c terminology to RCS revision numbers. "First", "Second", 3647@c "subsequent", and so on is almost surely clearer, 3648@c especially to a novice reader. -DRP 3649By default, @sc{cvs} will assign numeric revisions by 3650leaving the first number the same and incrementing the 3651second number. For example, @code{1.1}, @code{1.2}, 3652@code{1.3}, etc. 3653 3654When adding a new file, the second number will always 3655be one and the first number will equal the highest 3656first number of any file in that directory. For 3657example, the current directory contains files whose 3658highest numbered revisions are @code{1.7}, @code{3.1}, 3659and @code{4.12}, then an added file will be given the 3660numeric revision @code{4.1}. 3661(When using client/server @sc{cvs}, 3662only files that are actually sent to the server are considered.) 3663 3664@c This is sort of redundant with something we said a 3665@c while ago. Somewhere we need a better way of 3666@c introducing how the first number can be anything 3667@c except "1", perhaps. Also I don't think this 3668@c presentation is clear on why we are discussing releases 3669@c and first numbers of numeric revisions in the same 3670@c breath. 3671Normally there is no reason to care 3672about the revision numbers---it is easier to treat them 3673as internal numbers that @sc{cvs} maintains, and tags 3674provide a better way to distinguish between things like 3675release 1 versus release 2 of your product 3676(@pxref{Tags}). However, if you want to set the 3677numeric revisions, the @samp{-r} option to @code{cvs 3678commit} can do that. The @samp{-r} option implies the 3679@samp{-f} option, in the sense that it causes the 3680files to be committed even if they are not modified. 3681 3682For example, to bring all your files up to 3683revision 3.0 (including those that haven't changed), 3684you might invoke: 3685 3686@example 3687$ cvs commit -r 3.0 3688@end example 3689 3690Note that the number you specify with @samp{-r} must be 3691larger than any existing revision number. That is, if 3692revision 3.0 exists, you cannot @samp{cvs commit 3693-r 1.3}. If you want to maintain several releases in 3694parallel, you need to use a branch (@pxref{Branching and merging}). 3695 3696@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3697@node Tags 3698@section Tags--Symbolic revisions 3699@cindex Tags 3700 3701The revision numbers live a life of their own. They 3702need not have anything at all to do with the release 3703numbers of your software product. Depending 3704on how you use @sc{cvs} the revision numbers might change several times 3705between two releases. As an example, some of the 3706source files that make up @sc{rcs} 5.6 have the following 3707revision numbers: 3708@cindex RCS revision numbers 3709 3710@example 3711ci.c 5.21 3712co.c 5.9 3713ident.c 5.3 3714rcs.c 5.12 3715rcsbase.h 5.11 3716rcsdiff.c 5.10 3717rcsedit.c 5.11 3718rcsfcmp.c 5.9 3719rcsgen.c 5.10 3720rcslex.c 5.11 3721rcsmap.c 5.2 3722rcsutil.c 5.10 3723@end example 3724 3725@cindex tag (subcommand), introduction 3726@cindex Tags, symbolic name 3727@cindex Symbolic name (tag) 3728@cindex Name, symbolic (tag) 3729@cindex HEAD, as reserved tag name 3730@cindex BASE, as reserved tag name 3731You can use the @code{tag} command to give a symbolic name to a 3732certain revision of a file. You can use the @samp{-v} flag to the 3733@code{status} command to see all tags that a file has, and 3734which revision numbers they represent. Tag names must 3735start with an uppercase or lowercase letter and can 3736contain uppercase and lowercase letters, digits, 3737@samp{-}, and @samp{_}. The two tag names @code{BASE} 3738and @code{HEAD} are reserved for use by @sc{cvs}. It 3739is expected that future names which are special to 3740@sc{cvs} will be specially named, for example by 3741starting with @samp{.}, rather than being named analogously to 3742@code{BASE} and @code{HEAD}, to avoid conflicts with 3743actual tag names. 3744@c Including a character such as % or = has also been 3745@c suggested as the naming convention for future 3746@c special tag names. Starting with . is nice because 3747@c that is not a legal tag name as far as RCS is concerned. 3748@c FIXME: CVS actually accepts quite a few characters 3749@c in tag names, not just the ones documented above 3750@c (see RCS_check_tag). RCS 3751@c defines legitimate tag names by listing illegal 3752@c characters rather than legal ones. CVS is said to lose its 3753@c mind if you try to use "/" (try making such a tag sticky 3754@c and using "cvs status" client/server--see remote 3755@c protocol format for entries line for probable cause). 3756@c TODO: The testsuite 3757@c should test for whatever are documented above as 3758@c officially-OK tag names, and CVS should at least reject 3759@c characters that won't work, like "/". 3760 3761You'll want to choose some convention for naming tags, 3762based on information such as the name of the program 3763and the version number of the release. For example, 3764one might take the name of the program, immediately 3765followed by the version number with @samp{.} changed to 3766@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 3767@code{cvs1-9}. If you choose a consistent convention, 3768then you won't constantly be guessing whether a tag is 3769@code{cvs-1-9} or @code{cvs1_9} or what. You might 3770even want to consider enforcing your convention in the 3771@file{taginfo} file (@pxref{taginfo}). 3772@c Might be nice to say more about using taginfo this 3773@c way, like giving an example, or pointing out any particular 3774@c issues which arise. 3775 3776@cindex Adding a tag 3777@cindex Tags, example 3778The following example shows how you can add a tag to a 3779file. The commands must be issued inside your working 3780directory. That is, you should issue the 3781command in the directory where @file{backend.c} 3782resides. 3783 3784@example 3785$ cvs tag rel-0-4 backend.c 3786T backend.c 3787$ cvs status -v backend.c 3788=================================================================== 3789File: backend.c Status: Up-to-date 3790 3791 Version: 1.4 Tue Dec 1 14:39:01 1992 3792 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 3793 Sticky Tag: (none) 3794 Sticky Date: (none) 3795 Sticky Options: (none) 3796 3797 Existing Tags: 3798 rel-0-4 (revision: 1.4) 3799 3800@end example 3801 3802For a complete summary of the syntax of @code{cvs tag}, 3803including the various options, see @ref{Invoking CVS}. 3804 3805There is seldom reason to tag a file in isolation. A more common use is 3806to tag all the files that constitute a module with the same tag at 3807strategic points in the development life-cycle, such as when a release 3808is made. 3809 3810@example 3811$ cvs tag rel-1-0 . 3812cvs tag: Tagging . 3813T Makefile 3814T backend.c 3815T driver.c 3816T frontend.c 3817T parser.c 3818@end example 3819 3820@noindent 3821(When you give @sc{cvs} a directory as argument, it generally applies the 3822operation to all the files in that directory, and (recursively), to any 3823subdirectories that it may contain. @xref{Recursive behavior}.) 3824 3825@cindex Retrieving an old revision using tags 3826@cindex Tags, retrieving old revisions 3827The @code{checkout} command has a flag, @samp{-r}, that lets you check out 3828a certain revision of a module. This flag makes it easy to 3829retrieve the sources that make up release 1.0 of the module @samp{tc} at 3830any time in the future: 3831 3832@example 3833$ cvs checkout -r rel-1-0 tc 3834@end example 3835 3836@noindent 3837This is useful, for instance, if someone claims that there is a bug in 3838that release, but you cannot find the bug in the current working copy. 3839 3840You can also check out a module as it was on any branch at any given date. 3841@xref{checkout options}. When specifying @samp{-r} or @samp{-D} to 3842any of these commands, you will need beware of sticky 3843tags; see @ref{Sticky tags}. 3844 3845When you tag more than one file with the same tag you 3846can think about the tag as "a curve drawn through a 3847matrix of filename vs. revision number." Say we have 5 3848files with the following revisions: 3849 3850@example 3851@group 3852 file1 file2 file3 file4 file5 3853 3854 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 3855 1.2*- 1.2 1.2 -1.2*- 3856 1.3 \- 1.3*- 1.3 / 1.3 3857 1.4 \ 1.4 / 1.4 3858 \-1.5*- 1.5 3859 1.6 3860@end group 3861@end example 3862 3863At some time in the past, the @code{*} versions were tagged. 3864You can think of the tag as a handle attached to the curve 3865drawn through the tagged revisions. When you pull on 3866the handle, you get all the tagged revisions. Another 3867way to look at it is that you "sight" through a set of 3868revisions that is "flat" along the tagged revisions, 3869like this: 3870 3871@example 3872@group 3873 file1 file2 file3 file4 file5 3874 3875 1.1 3876 1.2 3877 1.1 1.3 _ 3878 1.1 1.2 1.4 1.1 / 3879 1.2*----1.3*----1.5*----1.2*----1.1* (--- <--- Look here 3880 1.3 1.6 1.3 \_ 3881 1.4 1.4 3882 1.5 3883@end group 3884@end example 3885 3886@node Tagging the working directory 3887@section Specifying what to tag from the working directory 3888 3889@cindex tag (subcommand) 3890The example in the previous section demonstrates one of 3891the most common ways to choose which revisions to tag. 3892Namely, running the @code{cvs tag} command without 3893arguments causes @sc{cvs} to select the revisions which 3894are checked out in the current working directory. For 3895example, if the copy of @file{backend.c} in working 3896directory was checked out from revision 1.4, then 3897@sc{cvs} will tag revision 1.4. Note that the tag is 3898applied immediately to revision 1.4 in the repository; 3899tagging is not like modifying a file, or other 3900operations in which one first modifies the working 3901directory and then runs @code{cvs commit} to transfer 3902that modification to the repository. 3903 3904One potentially surprising aspect of the fact that 3905@code{cvs tag} operates on the repository is that you 3906are tagging the checked-in revisions, which may differ 3907from locally modified files in your working directory. 3908If you want to avoid doing this by mistake, specify the 3909@samp{-c} option to @code{cvs tag}. If there are any 3910locally modified files, @sc{cvs} will abort with an 3911error before it tags any files: 3912 3913@example 3914$ cvs tag -c rel-0-4 3915cvs tag: backend.c is locally modified 3916cvs [tag aborted]: correct the above errors first! 3917@end example 3918 3919@node Tagging by date/tag 3920@section Specifying what to tag by date or revision 3921@cindex rtag (subcommand) 3922 3923The @code{cvs rtag} command tags the repository as of a 3924certain date or time (or can be used to tag the latest 3925revision). @code{rtag} works directly on the 3926repository contents (it requires no prior checkout and 3927does not look for a working directory). 3928 3929The following options specify which date or revision to 3930tag. See @ref{Common options}, for a complete 3931description of them. 3932 3933@table @code 3934@item -D @var{date} 3935Tag the most recent revision no later than @var{date}. 3936 3937@item -f 3938Only useful with the @samp{-D} or @samp{-r} 3939flags. If no matching revision is found, use the most 3940recent revision (instead of ignoring the file). 3941 3942@item -r @var{tag}[:@var{date}] 3943Tag the revision already tagged with @var{tag} or, when @var{date} is specified 3944and @var{tag} is a branch tag, the version from the branch @var{tag} as it 3945existed on @var{date}. See @ref{Common options}. 3946@end table 3947 3948The @code{cvs tag} command also allows one to specify 3949files by revision or date, using the same @samp{-r}, 3950@samp{-D}, and @samp{-f} options. However, this 3951feature is probably not what you want. The reason is 3952that @code{cvs tag} chooses which files to tag based on 3953the files that exist in the working directory, rather 3954than the files which existed as of the given tag/date. 3955Therefore, you are generally better off using @code{cvs 3956rtag}. The exceptions might be cases like: 3957 3958@example 3959cvs tag -r 1.4 stable backend.c 3960@end example 3961 3962@node Modifying tags 3963@section Deleting, moving, and renaming tags 3964 3965@c Also see: 3966@c "How do I move or rename a magic branch tag?" 3967@c in the FAQ (I think the issues it talks about still 3968@c apply, but this could use some sanity.sh work). 3969 3970Normally one does not modify tags. They exist in order 3971to record the history of the repository and so deleting 3972them or changing their meaning would, generally, not be 3973what you want. 3974 3975However, there might be cases in which one uses a tag 3976temporarily or accidentally puts one in the wrong 3977place. Therefore, one might delete, move, or rename a 3978tag. 3979 3980@noindent 3981@strong{WARNING: the commands in this section are 3982dangerous; they permanently discard historical 3983information and it can be difficult or impossible to 3984recover from errors. If you are a @sc{cvs} 3985administrator, you may consider restricting these 3986commands with the @file{taginfo} file (@pxref{taginfo}).} 3987 3988@cindex Deleting tags 3989@cindex Deleting branch tags 3990@cindex Removing tags 3991@cindex Removing branch tags 3992@cindex Tags, deleting 3993@cindex Branch tags, deleting 3994To delete a tag, specify the @samp{-d} option to either 3995@code{cvs tag} or @code{cvs rtag}. For example: 3996 3997@example 3998cvs rtag -d rel-0-4 tc 3999@end example 4000 4001@noindent 4002deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 4003In the event that branch tags are encountered within the repository 4004with the given name, a warning message will be issued and the branch 4005tag will not be deleted. If you are absolutely certain you know what 4006you are doing, the @code{-B} option may be specified to allow deletion 4007of branch tags. In that case, any non-branch tags encountered will 4008trigger warnings and will not be deleted. 4009 4010@noindent 4011@strong{WARNING: Moving branch tags is very dangerous! If you think 4012you need the @code{-B} option, think again and ask your @sc{cvs} 4013administrator about it (if that isn't you). There is almost certainly 4014another way to accomplish what you want to accomplish.} 4015 4016@cindex Moving tags 4017@cindex Moving branch tags 4018@cindex Tags, moving 4019@cindex Branch tags, moving 4020When we say @dfn{move} a tag, we mean to make the same 4021name point to different revisions. For example, the 4022@code{stable} tag may currently point to revision 1.4 4023of @file{backend.c} and perhaps we want to make it 4024point to revision 1.6. To move a non-branch tag, specify the 4025@samp{-F} option to either @code{cvs tag} or @code{cvs 4026rtag}. For example, the task just mentioned might be 4027accomplished as: 4028 4029@example 4030cvs tag -r 1.6 -F stable backend.c 4031@end example 4032 4033@noindent 4034If any branch tags are encountered in the repository 4035with the given name, a warning is issued and the branch 4036tag is not disturbed. If you are absolutely certain you 4037wish to move the branch tag, the @code{-B} option may be specified. 4038In that case, non-branch tags encountered with the given 4039name are ignored with a warning message. 4040 4041@noindent 4042@strong{WARNING: Moving branch tags is very dangerous! If you think you 4043need the @code{-B} option, think again and ask your @sc{cvs} 4044administrator about it (if that isn't you). There is almost certainly 4045another way to accomplish what you want to accomplish.} 4046 4047@cindex Renaming tags 4048@cindex Tags, renaming 4049When we say @dfn{rename} a tag, we mean to make a 4050different name point to the same revisions as the old 4051tag. For example, one may have misspelled the tag name 4052and want to correct it (hopefully before others are 4053relying on the old spelling). To rename a tag, first 4054create a new tag using the @samp{-r} option to 4055@code{cvs rtag}, and then delete the old name. (Caution: 4056this method will not work with branch tags.) 4057This leaves the new tag on exactly the 4058same files as the old tag. For example: 4059 4060@example 4061cvs rtag -r old-name-0-4 rel-0-4 tc 4062cvs rtag -d old-name-0-4 tc 4063@end example 4064 4065@node Tagging add/remove 4066@section Tagging and adding and removing files 4067 4068The subject of exactly how tagging interacts with 4069adding and removing files is somewhat obscure; for the 4070most part @sc{cvs} will keep track of whether files 4071exist or not without too much fussing. By default, 4072tags are applied to only files which have a revision 4073corresponding to what is being tagged. Files which did 4074not exist yet, or which were already removed, simply 4075omit the tag, and @sc{cvs} knows to treat the absence 4076of a tag as meaning that the file didn't exist as of 4077that tag. 4078 4079However, this can lose a small amount of information. 4080For example, suppose a file was added and then removed. 4081Then, if the tag is missing for that file, there is no 4082way to know whether the tag refers to the time before 4083the file was added, or the time after it was removed. 4084If you specify the @samp{-r} option to @code{cvs rtag}, 4085then @sc{cvs} tags the files which have been removed, 4086and thereby avoids this problem. For example, one 4087might specify @code{-r HEAD} to tag the head. 4088 4089On the subject of adding and removing files, the 4090@code{cvs rtag} command has a @samp{-a} option which 4091means to clear the tag from removed files that would 4092not otherwise be tagged. For example, one might 4093specify this option in conjunction with @samp{-F} when 4094moving a tag. If one moved a tag without @samp{-a}, 4095then the tag in the removed files might still refer to 4096the old revision, rather than reflecting the fact that 4097the file had been removed. I don't think this is 4098necessary if @samp{-r} is specified, as noted above. 4099 4100@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4101@node Sticky tags 4102@section Sticky tags 4103@cindex Sticky tags 4104@cindex Tags, sticky 4105 4106@c A somewhat related issue is per-directory sticky 4107@c tags (see comment at CVS/Tag in node Working 4108@c directory storage); we probably want to say 4109@c something like "you can set a sticky tag for only 4110@c some files, but you don't want to" or some such. 4111 4112Sometimes a working copy's revision has extra data 4113associated with it, for example it might be on a branch 4114(@pxref{Branching and merging}), or restricted to 4115versions prior to a certain date by @samp{checkout -D} 4116or @samp{update -D}. Because this data persists -- 4117that is, it applies to subsequent commands in the 4118working copy -- we refer to it as @dfn{sticky}. 4119 4120Most of the time, stickiness is an obscure aspect of 4121@sc{cvs} that you don't need to think about. However, 4122even if you don't want to use the feature, you may need 4123to know @emph{something} about sticky tags (for 4124example, how to avoid them!). 4125 4126You can use the @code{status} command to see if any 4127sticky tags or dates are set: 4128 4129@example 4130$ cvs status driver.c 4131=================================================================== 4132File: driver.c Status: Up-to-date 4133 4134 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 4135 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 4136 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4137 Sticky Date: (none) 4138 Sticky Options: (none) 4139 4140@end example 4141 4142@cindex Resetting sticky tags 4143@cindex Sticky tags, resetting 4144@cindex Deleting sticky tags 4145The sticky tags will remain on your working files until 4146you delete them with @samp{cvs update -A}. The 4147@samp{-A} option merges local changes into the version of the 4148file from the head of the trunk, removing any sticky tags, 4149dates, or options. See @ref{update} for more on the operation 4150of @code{cvs update}. 4151 4152@cindex Sticky date 4153The most common use of sticky tags is to identify which 4154branch one is working on, as described in 4155@ref{Accessing branches}. However, non-branch 4156sticky tags have uses as well. For example, 4157suppose that you want to avoid updating your working 4158directory, to isolate yourself from possibly 4159destabilizing changes other people are making. You 4160can, of course, just refrain from running @code{cvs 4161update}. But if you want to avoid updating only a 4162portion of a larger tree, then sticky tags can help. 4163If you check out a certain revision (such as 1.4) it 4164will become sticky. Subsequent @code{cvs update} 4165commands will 4166not retrieve the latest revision until you reset the 4167tag with @code{cvs update -A}. Likewise, use of the 4168@samp{-D} option to @code{update} or @code{checkout} 4169sets a @dfn{sticky date}, which, similarly, causes that 4170date to be used for future retrievals. 4171 4172People often want to retrieve an old version of 4173a file without setting a sticky tag. This can 4174be done with the @samp{-p} option to @code{checkout} or 4175@code{update}, which sends the contents of the file to 4176standard output. For example: 4177@example 4178$ cvs update -p -r 1.1 file1 >file1 4179=================================================================== 4180Checking out file1 4181RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 4182VERS: 1.1 4183*************** 4184$ 4185@end example 4186 4187However, this isn't the easiest way, if you are asking 4188how to undo a previous checkin (in this example, put 4189@file{file1} back to the way it was as of revision 41901.1). In that case you are better off using the 4191@samp{-j} option to @code{update}; for further 4192discussion see @ref{Merging two revisions}. 4193 4194@c --------------------------------------------------------------------- 4195@node Branching and merging 4196@chapter Branching and merging 4197@cindex Branching 4198@cindex Merging 4199@cindex Copying changes 4200@cindex Main trunk and branches 4201@cindex Revision tree, making branches 4202@cindex Branches, copying changes between 4203@cindex Changes, copying between branches 4204@cindex Modifications, copying between branches 4205 4206@sc{cvs} allows you to isolate changes onto a separate 4207line of development, known as a @dfn{branch}. When you 4208change files on a branch, those changes do not appear 4209on the main trunk or other branches. 4210 4211Later you can move changes from one branch to another 4212branch (or the main trunk) by @dfn{merging}. Merging 4213involves first running @code{cvs update -j}, to merge 4214the changes into the working directory. 4215You can then commit that revision, and thus effectively 4216copy the changes onto another branch. 4217 4218@menu 4219* Branches motivation:: What branches are good for 4220* Creating a branch:: Creating a branch 4221* Accessing branches:: Checking out and updating branches 4222* Branches and revisions:: Branches are reflected in revision numbers 4223* Magic branch numbers:: Magic branch numbers 4224* Merging a branch:: Merging an entire branch 4225* Merging more than once:: Merging from a branch several times 4226* Merging two revisions:: Merging differences between two revisions 4227* Merging adds and removals:: What if files are added or removed? 4228* Merging and keywords:: Avoiding conflicts due to keyword substitution 4229@end menu 4230 4231@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4232@node Branches motivation 4233@section What branches are good for 4234@cindex Branches motivation 4235@cindex What branches are good for 4236@cindex Motivation for branches 4237 4238@c FIXME: this node mentions one way to use branches, 4239@c but it is by no means the only way. For example, 4240@c the technique of committing a new feature on a branch, 4241@c until it is ready for the main trunk. The whole 4242@c thing is generally speaking more akin to the 4243@c "Revision management" node although it isn't clear to 4244@c me whether policy matters should be centralized or 4245@c distributed throughout the relevant sections. 4246Suppose that release 1.0 of tc has been made. You are continuing to 4247develop tc, planning to create release 1.1 in a couple of months. After a 4248while your customers start to complain about a fatal bug. You check 4249out release 1.0 (@pxref{Tags}) and find the bug 4250(which turns out to have a trivial fix). However, the current revision 4251of the sources are in a state of flux and are not expected to be stable 4252for at least another month. There is no way to make a 4253bug fix release based on the newest sources. 4254 4255The thing to do in a situation like this is to create a @dfn{branch} on 4256the revision trees for all the files that make up 4257release 1.0 of tc. You can then make 4258modifications to the branch without disturbing the main trunk. When the 4259modifications are finished you can elect to either incorporate them on 4260the main trunk, or leave them on the branch. 4261 4262@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4263@node Creating a branch 4264@section Creating a branch 4265@cindex Creating a branch 4266@cindex Branch, creating a 4267@cindex tag (subcommand), creating a branch using 4268@cindex rtag (subcommand), creating a branch using 4269 4270You can create a branch with @code{tag -b}; for 4271example, assuming you're in a working copy: 4272 4273@example 4274$ cvs tag -b rel-1-0-patches 4275@end example 4276 4277@c FIXME: we should be more explicit about the value of 4278@c having a tag on the branchpoint. For example 4279@c "cvs tag rel-1-0-patches-branchpoint" before 4280@c the "cvs tag -b". This points out that 4281@c rel-1-0-patches is a pretty awkward name for 4282@c this example (more so than for the rtag example 4283@c below). 4284 4285This splits off a branch based on the current revisions 4286in the working copy, assigning that branch the name 4287@samp{rel-1-0-patches}. 4288 4289It is important to understand that branches get created 4290in the repository, not in the working copy. Creating a 4291branch based on current revisions, as the above example 4292does, will @emph{not} automatically switch the working 4293copy to be on the new branch. For information on how 4294to do that, see @ref{Accessing branches}. 4295 4296You can also create a branch without reference to any 4297working copy, by using @code{rtag}: 4298 4299@example 4300$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 4301@end example 4302 4303@samp{-r rel-1-0} says that this branch should be 4304rooted at the revision that 4305corresponds to the tag @samp{rel-1-0}. It need not 4306be the most recent revision -- it's often useful to 4307split a branch off an old revision (for example, when 4308fixing a bug in a past release otherwise known to be 4309stable). 4310 4311As with @samp{tag}, the @samp{-b} flag tells 4312@code{rtag} to create a branch (rather than just a 4313symbolic revision name). Note that the numeric 4314revision number that matches @samp{rel-1-0} will 4315probably be different from file to file. 4316 4317So, the full effect of the command is to create a new 4318branch -- named @samp{rel-1-0-patches} -- in module 4319@samp{tc}, rooted in the revision tree at the point tagged 4320by @samp{rel-1-0}. 4321 4322@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4323@node Accessing branches 4324@section Accessing branches 4325@cindex Check out a branch 4326@cindex Retrieve a branch 4327@cindex Access a branch 4328@cindex Identifying a branch 4329@cindex Branch, check out 4330@cindex Branch, retrieving 4331@cindex Branch, accessing 4332@cindex Branch, identifying 4333 4334You can retrieve a branch in one of two ways: by 4335checking it out fresh from the repository, or by 4336switching an existing working copy over to the branch. 4337 4338To check out a branch from the repository, invoke 4339@samp{checkout} with the @samp{-r} flag, followed by 4340the tag name of the branch (@pxref{Creating a branch}): 4341 4342@example 4343$ cvs checkout -r rel-1-0-patches tc 4344@end example 4345 4346Or, if you already have a working copy, you can switch 4347it to a given branch with @samp{update -r}: 4348 4349@example 4350$ cvs update -r rel-1-0-patches tc 4351@end example 4352 4353@noindent 4354or equivalently: 4355 4356@example 4357$ cd tc 4358$ cvs update -r rel-1-0-patches 4359@end example 4360 4361It does not matter if the working copy was originally 4362on the main trunk or on some other branch -- the above 4363command will switch it to the named branch. And 4364similarly to a regular @samp{update} command, 4365@samp{update -r} merges any changes you have made, 4366notifying you of conflicts where they occur. 4367 4368Once you have a working copy tied to a particular 4369branch, it remains there until you tell it otherwise. 4370This means that changes checked in from the working 4371copy will add new revisions on that branch, while 4372leaving the main trunk and other branches unaffected. 4373 4374@cindex Branches, sticky 4375To find out what branch a working copy is on, you can 4376use the @samp{status} command. In its output, look for 4377the field named @samp{Sticky tag} (@pxref{Sticky tags}) 4378-- that's @sc{cvs}'s way of telling you the branch, if 4379any, of the current working files: 4380 4381@example 4382$ cvs status -v driver.c backend.c 4383=================================================================== 4384File: driver.c Status: Up-to-date 4385 4386 Version: 1.7 Sat Dec 5 18:25:54 1992 4387 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 4388 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4389 Sticky Date: (none) 4390 Sticky Options: (none) 4391 4392 Existing Tags: 4393 rel-1-0-patches (branch: 1.7.2) 4394 rel-1-0 (revision: 1.7) 4395 4396=================================================================== 4397File: backend.c Status: Up-to-date 4398 4399 Version: 1.4 Tue Dec 1 14:39:01 1992 4400 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 4401 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 4402 Sticky Date: (none) 4403 Sticky Options: (none) 4404 4405 Existing Tags: 4406 rel-1-0-patches (branch: 1.4.2) 4407 rel-1-0 (revision: 1.4) 4408 rel-0-4 (revision: 1.4) 4409 4410@end example 4411 4412Don't be confused by the fact that the branch numbers 4413for each file are different (@samp{1.7.2} and 4414@samp{1.4.2} respectively). The branch tag is the 4415same, @samp{rel-1-0-patches}, and the files are 4416indeed on the same branch. The numbers simply reflect 4417the point in each file's revision history at which the 4418branch was made. In the above example, one can deduce 4419that @samp{driver.c} had been through more changes than 4420@samp{backend.c} before this branch was created. 4421 4422See @ref{Branches and revisions} for details about how 4423branch numbers are constructed. 4424 4425@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4426@node Branches and revisions 4427@section Branches and revisions 4428@cindex Branch number 4429@cindex Number, branch 4430@cindex Revision numbers (branches) 4431 4432Ordinarily, a file's revision history is a linear 4433series of increments (@pxref{Revision numbers}): 4434 4435@example 4436 +-----+ +-----+ +-----+ +-----+ +-----+ 4437 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 4438 +-----+ +-----+ +-----+ +-----+ +-----+ 4439@end example 4440 4441However, @sc{cvs} is not limited to linear development. The 4442@dfn{revision tree} can be split into @dfn{branches}, 4443where each branch is a self-maintained line of 4444development. Changes made on one branch can easily be 4445moved back to the main trunk. 4446 4447Each branch has a @dfn{branch number}, consisting of an 4448odd number of period-separated decimal integers. The 4449branch number is created by appending an integer to the 4450revision number where the corresponding branch forked 4451off. Having branch numbers allows more than one branch 4452to be forked off from a certain revision. 4453 4454@need 3500 4455All revisions on a branch have revision numbers formed 4456by appending an ordinal number to the branch number. 4457The following figure illustrates branching with an 4458example. 4459 4460@example 4461@c This example used to have a 1.2.2.4 revision, which 4462@c might help clarify that development can continue on 4463@c 1.2.2. Might be worth reinstating if it can be done 4464@c without overfull hboxes. 4465@group 4466 +-------------+ 4467 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 4468 / +-------------+ 4469 / 4470 / 4471 +---------+ +---------+ +---------+ 4472Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4473 / +---------+ +---------+ +---------+ 4474 / 4475 / 4476+-----+ +-----+ +-----+ +-----+ +-----+ 4477! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4478+-----+ +-----+ +-----+ +-----+ +-----+ 4479 ! 4480 ! 4481 ! +---------+ +---------+ +---------+ 4482Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 4483 +---------+ +---------+ +---------+ 4484 4485@end group 4486@end example 4487 4488@c -- However, at least for me the figure is not enough. I suggest more 4489@c -- text to accompany it. "A picture is worth a thousand words", so you 4490@c -- have to make sure the reader notices the couple of hundred words 4491@c -- *you* had in mind more than the others! 4492 4493@c -- Why an even number of segments? This section implies that this is 4494@c -- how the main trunk is distinguished from branch roots, but you never 4495@c -- explicitly say that this is the purpose of the [by itself rather 4496@c -- surprising] restriction to an even number of segments. 4497 4498The exact details of how the branch number is 4499constructed is not something you normally need to be 4500concerned about, but here is how it works: When 4501@sc{cvs} creates a branch number it picks the first 4502unused even integer, starting with 2. So when you want 4503to create a branch from revision 6.4 it will be 4504numbered 6.4.2. All branch numbers ending in a zero 4505(such as 6.4.0) are used internally by @sc{cvs} 4506(@pxref{Magic branch numbers}). The branch 1.1.1 has a 4507special meaning. @xref{Tracking sources}. 4508 4509@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4510@node Magic branch numbers 4511@section Magic branch numbers 4512 4513@c Want xref to here from "log"? 4514 4515This section describes a @sc{cvs} feature called 4516@dfn{magic branches}. For most purposes, you need not 4517worry about magic branches; @sc{cvs} handles them for 4518you. However, they are visible to you in certain 4519circumstances, so it may be useful to have some idea of 4520how it works. 4521 4522Externally, branch numbers consist of an odd number of 4523dot-separated decimal integers. @xref{Revision 4524numbers}. That is not the whole truth, however. For 4525efficiency reasons @sc{cvs} sometimes inserts an extra 0 4526in the second rightmost position (1.2.4 becomes 45271.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 4528on). 4529 4530@sc{cvs} does a pretty good job at hiding these so 4531called magic branches, but in a few places the hiding 4532is incomplete: 4533 4534@itemize @bullet 4535@ignore 4536@c This is in ignore as I'm taking their word for it, 4537@c that this was fixed 4538@c a long time ago. But before deleting this 4539@c entirely, I'd rather verify it (and add a test 4540@c case to the testsuite). 4541@item 4542The magic branch can appear in the output from 4543@code{cvs status} in vanilla @sc{cvs} 1.3. This is 4544fixed in @sc{cvs} 1.3-s2. 4545 4546@end ignore 4547@item 4548The magic branch number appears in the output from 4549@code{cvs log}. 4550@c What output should appear instead? 4551 4552@item 4553You cannot specify a symbolic branch name to @code{cvs 4554admin}. 4555 4556@end itemize 4557 4558@c Can CVS do this automatically the first time 4559@c you check something in to that branch? Should 4560@c it? 4561You can use the @code{admin} command to reassign a 4562symbolic name to a branch the way @sc{rcs} expects it 4563to be. If @code{R4patches} is assigned to the branch 45641.4.2 (magic branch number 1.4.0.2) in file 4565@file{numbers.c} you can do this: 4566 4567@example 4568$ cvs admin -NR4patches:1.4.2 numbers.c 4569@end example 4570 4571It only works if at least one revision is already 4572committed on the branch. Be very careful so that you 4573do not assign the tag to the wrong number. (There is 4574no way to see how the tag was assigned yesterday). 4575 4576@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4577@node Merging a branch 4578@section Merging an entire branch 4579@cindex Merging a branch 4580@cindex -j (merging branches) 4581 4582You can merge changes made on a branch into your working copy by giving 4583the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 4584@samp{-j @var{branchname}} option it merges the changes made between the 4585greatest common ancestor (GCA) of the branch and the destination revision (in 4586the simple case below the GCA is the point where the branch forked) and the 4587newest revision on that branch into your working copy. 4588 4589@cindex Join 4590The @samp{-j} stands for ``join''. 4591 4592@cindex Branch merge example 4593@cindex Example, branch merge 4594@cindex Merge, branch example 4595Consider this revision tree: 4596 4597@example 4598+-----+ +-----+ +-----+ +-----+ 4599! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 4600+-----+ +-----+ +-----+ +-----+ 4601 ! 4602 ! 4603 ! +---------+ +---------+ 4604Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4605 +---------+ +---------+ 4606@end example 4607 4608@noindent 4609The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 4610following example assumes that the module @samp{mod} contains only one 4611file, @file{m.c}. 4612 4613@example 4614$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 4615 4616$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 4617 # @r{i.e. the changes between revision 1.2} 4618 # @r{and 1.2.2.2, into your working copy} 4619 # @r{of the file.} 4620 4621$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 4622@end example 4623 4624A conflict can result from a merge operation. If that 4625happens, you should resolve it before committing the 4626new revision. @xref{Conflicts example}. 4627 4628If your source files contain keywords (@pxref{Keyword substitution}), 4629you might be getting more conflicts than strictly necessary. See 4630@ref{Merging and keywords}, for information on how to avoid this. 4631 4632The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 4633same effect as above could be achieved with this: 4634 4635@example 4636$ cvs checkout -j R1fix mod 4637$ cvs commit -m "Included R1fix" 4638@end example 4639 4640It should be noted that @code{update -j @var{tagname}} will also work but may 4641not produce the desired result. @xref{Merging adds and removals}, for more. 4642 4643@node Merging more than once 4644@section Merging from a branch several times 4645 4646Continuing our example, the revision tree now looks 4647like this: 4648 4649@example 4650+-----+ +-----+ +-----+ +-----+ +-----+ 4651! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4652+-----+ +-----+ +-----+ +-----+ +-----+ 4653 ! * 4654 ! * 4655 ! +---------+ +---------+ 4656Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4657 +---------+ +---------+ 4658@end example 4659 4660@noindent 4661where the starred line represents the merge from the 4662@samp{R1fix} branch to the main trunk, as just 4663discussed. 4664 4665Now suppose that development continues on the 4666@samp{R1fix} branch: 4667 4668@example 4669+-----+ +-----+ +-----+ +-----+ +-----+ 4670! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4671+-----+ +-----+ +-----+ +-----+ +-----+ 4672 ! * 4673 ! * 4674 ! +---------+ +---------+ +---------+ 4675Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4676 +---------+ +---------+ +---------+ 4677@end example 4678 4679@noindent 4680and then you want to merge those new changes onto the 4681main trunk. If you just use the @code{cvs update -j 4682R1fix m.c} command again, @sc{cvs} will attempt to 4683merge again the changes which you have already merged, 4684which can have undesirable side effects. 4685 4686So instead you need to specify that you only want to 4687merge the changes on the branch which have not yet been 4688merged into the trunk. To do that you specify two 4689@samp{-j} options, and @sc{cvs} merges the changes from 4690the first revision to the second revision. For 4691example, in this case the simplest way would be 4692 4693@example 4694cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 4695 # @r{head of the R1fix branch} 4696@end example 4697 4698The problem with this is that you need to specify the 46991.2.2.2 revision manually. A slightly better approach 4700might be to use the date the last merge was done: 4701 4702@example 4703cvs update -j R1fix:yesterday -j R1fix m.c 4704@end example 4705 4706Better yet, tag the R1fix branch after every merge into 4707the trunk, and then use that tag for subsequent merges: 4708 4709@example 4710cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 4711@end example 4712 4713@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4714@node Merging two revisions 4715@section Merging differences between any two revisions 4716@cindex Merging two revisions 4717@cindex Revisions, merging differences between 4718@cindex Differences, merging 4719 4720With two @samp{-j @var{revision}} flags, the @code{update} 4721(and @code{checkout}) command can merge the differences 4722between any two revisions into your working file. 4723 4724@cindex Undoing a change 4725@cindex Removing a change 4726@example 4727$ cvs update -j 1.5 -j 1.3 backend.c 4728@end example 4729 4730@noindent 4731will undo all changes made between revision 47321.3 and 1.5. Note the order of the revisions! 4733 4734If you try to use this option when operating on 4735multiple files, remember that the numeric revisions will 4736probably be very different between the various files. 4737You almost always use symbolic 4738tags rather than revision numbers when operating on 4739multiple files. 4740 4741@cindex Restoring old version of removed file 4742@cindex Resurrecting old version of dead file 4743Specifying two @samp{-j} options can also undo file 4744removals or additions. For example, suppose you have 4745a file 4746named @file{file1} which existed as revision 1.1, and 4747you then removed it (thus adding a dead revision 1.2). 4748Now suppose you want to add it again, with the same 4749contents it had previously. Here is how to do it: 4750 4751@example 4752$ cvs update -j 1.2 -j 1.1 file1 4753U file1 4754$ cvs commit -m test 4755Checking in file1; 4756/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 4757new revision: 1.3; previous revision: 1.2 4758done 4759$ 4760@end example 4761 4762@node Merging adds and removals 4763@section Merging can add or remove files 4764 4765If the changes which you are merging involve removing 4766or adding some files, @code{update -j} will reflect 4767such additions or removals. 4768 4769@c FIXME: This example needs a lot more explanation. 4770@c We also need other examples for some of the other 4771@c cases (not all--there are too many--as long as we present a 4772@c coherent general principle). 4773For example: 4774@example 4775cvs update -A 4776touch a b c 4777cvs add a b c ; cvs ci -m "added" a b c 4778cvs tag -b branchtag 4779cvs update -r branchtag 4780touch d ; cvs add d 4781rm a ; cvs rm a 4782cvs ci -m "added d, removed a" 4783cvs update -A 4784cvs update -jbranchtag 4785@end example 4786 4787After these commands are executed and a @samp{cvs commit} is done, 4788file @file{a} will be removed and file @file{d} added in the main branch. 4789@c (which was determined by trying it) 4790 4791Note that using a single static tag (@samp{-j @var{tagname}}) 4792rather than a dynamic tag (@samp{-j @var{branchname}}) to merge 4793changes from a branch will usually not remove files which were removed on the 4794branch since @sc{cvs} does not automatically add static tags to dead revisions. 4795The exception to this rule occurs when 4796a static tag has been attached to a dead revision manually. Use the branch tag 4797to merge all changes from the branch or use two static tags as merge endpoints 4798to be sure that all intended changes are propagated in the merge. 4799 4800@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4801@node Merging and keywords 4802@section Merging and keywords 4803@cindex Merging, and keyword substitution 4804@cindex Keyword substitution, and merging 4805@cindex -j (merging branches), and keyword substitution 4806@cindex -kk, to avoid conflicts during a merge 4807 4808If you merge files containing keywords (@pxref{Keyword 4809substitution}), you will normally get numerous 4810conflicts during the merge, because the keywords are 4811expanded differently in the revisions which you are 4812merging. 4813 4814Therefore, you will often want to specify the 4815@samp{-kk} (@pxref{Substitution modes}) switch to the 4816merge command line. By substituting just the name of 4817the keyword, not the expanded value of that keyword, 4818this option ensures that the revisions which you are 4819merging will be the same as each other, and avoid 4820spurious conflicts. 4821 4822For example, suppose you have a file like this: 4823 4824@example 4825 +---------+ 4826 _! 1.1.2.1 ! <- br1 4827 / +---------+ 4828 / 4829 / 4830+-----+ +-----+ 4831! 1.1 !----! 1.2 ! 4832+-----+ +-----+ 4833@end example 4834 4835@noindent 4836and your working directory is currently on the trunk 4837(revision 1.2). Then you might get the following 4838results from a merge: 4839 4840@example 4841$ cat file1 4842key $@splitrcskeyword{Revision}: 1.2 $ 4843. . . 4844$ cvs update -j br1 4845U file1 4846RCS file: /cvsroot/first-dir/file1,v 4847retrieving revision 1.1 4848retrieving revision 1.1.2.1 4849Merging differences between 1.1 and 1.1.2.1 into file1 4850rcsmerge: warning: conflicts during merge 4851$ cat file1 4852@asis{}<<<<<<< file1 4853key $@splitrcskeyword{Revision}: 1.2 $ 4854@asis{}======= 4855key $@splitrcskeyword{Revision}: 1.1.2.1 $ 4856@asis{}>>>>>>> 1.1.2.1 4857. . . 4858@end example 4859 4860What happened was that the merge tried to merge the 4861differences between 1.1 and 1.1.2.1 into your working 4862directory. So, since the keyword changed from 4863@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 4864@sc{cvs} tried to merge that change into your working 4865directory, which conflicted with the fact that your 4866working directory had contained @code{Revision: 1.2}. 4867 4868Here is what happens if you had used @samp{-kk}: 4869 4870@example 4871$ cat file1 4872key $@splitrcskeyword{Revision}: 1.2 $ 4873. . . 4874$ cvs update -kk -j br1 4875U file1 4876RCS file: /cvsroot/first-dir/file1,v 4877retrieving revision 1.1 4878retrieving revision 1.1.2.1 4879Merging differences between 1.1 and 1.1.2.1 into file1 4880$ cat file1 4881key $@splitrcskeyword{Revision}$ 4882. . . 4883@end example 4884 4885What is going on here is that revision 1.1 and 1.1.2.1 4886both expand as plain @code{Revision}, and therefore 4887merging the changes between them into the working 4888directory need not change anything. Therefore, there 4889is no conflict. 4890 4891@strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a 4892major problem with using @samp{-kk} on merges. Namely, @samp{-kk} 4893overrode any default keyword expansion mode set in the archive file in 4894the repository. This could, unfortunately for some users, cause data 4895corruption in binary files (with a default keyword expansion mode set 4896to @samp{-kb}). Therefore, when a repository contained binary files, 4897conflicts had to be dealt with manually rather than using @samp{-kk} in 4898a merge command.} 4899 4900In @sc{cvs} version 1.12.2 and later, the keyword expansion mode 4901provided on the command line to any @sc{cvs} command no longer 4902overrides the @samp{-kb} keyword expansion mode setting for binary 4903files, though it will still override other default keyword expansion 4904modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts 4905on lines containing RCS keywords, even when your repository contains 4906binary files. 4907 4908@c --------------------------------------------------------------------- 4909@node Recursive behavior 4910@chapter Recursive behavior 4911@cindex Recursive (directory descending) 4912@cindex Directory, descending 4913@cindex Descending directories 4914@cindex Subdirectories 4915 4916Almost all of the subcommands of @sc{cvs} work 4917recursively when you specify a directory as an 4918argument. For instance, consider this directory 4919structure: 4920 4921@example 4922 @code{$HOME} 4923 | 4924 +--@t{tc} 4925 | | 4926 +--@t{CVS} 4927 | (internal @sc{cvs} files) 4928 +--@t{Makefile} 4929 +--@t{backend.c} 4930 +--@t{driver.c} 4931 +--@t{frontend.c} 4932 +--@t{parser.c} 4933 +--@t{man} 4934 | | 4935 | +--@t{CVS} 4936 | | (internal @sc{cvs} files) 4937 | +--@t{tc.1} 4938 | 4939 +--@t{testing} 4940 | 4941 +--@t{CVS} 4942 | (internal @sc{cvs} files) 4943 +--@t{testpgm.t} 4944 +--@t{test2.t} 4945@end example 4946 4947@noindent 4948If @file{tc} is the current working directory, the 4949following is true: 4950 4951@itemize @bullet 4952@item 4953@samp{cvs update testing} is equivalent to 4954 4955@example 4956cvs update testing/testpgm.t testing/test2.t 4957@end example 4958 4959@item 4960@samp{cvs update testing man} updates all files in the 4961subdirectories 4962 4963@item 4964@samp{cvs update .} or just @samp{cvs update} updates 4965all files in the @code{tc} directory 4966@end itemize 4967 4968If no arguments are given to @code{update} it will 4969update all files in the current working directory and 4970all its subdirectories. In other words, @file{.} is a 4971default argument to @code{update}. This is also true 4972for most of the @sc{cvs} subcommands, not only the 4973@code{update} command. 4974 4975The recursive behavior of the @sc{cvs} subcommands can be 4976turned off with the @samp{-l} option. 4977Conversely, the @samp{-R} option can be used to force recursion if 4978@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 4979 4980@example 4981$ cvs update -l # @r{Don't update files in subdirectories} 4982@end example 4983 4984@c --------------------------------------------------------------------- 4985@node Adding and removing 4986@chapter Adding, removing, and renaming files and directories 4987 4988In the course of a project, one will often add new 4989files. Likewise with removing or renaming, or with 4990directories. The general concept to keep in mind in 4991all these cases is that instead of making an 4992irreversible change you want @sc{cvs} to record the 4993fact that a change has taken place, just as with 4994modifying an existing file. The exact mechanisms to do 4995this in @sc{cvs} vary depending on the situation. 4996 4997@menu 4998* Adding files:: Adding files 4999* Removing files:: Removing files 5000* Removing directories:: Removing directories 5001* Moving files:: Moving and renaming files 5002* Moving directories:: Moving and renaming directories 5003@end menu 5004 5005@node Adding files 5006@section Adding files to a directory 5007@cindex Adding files 5008 5009To add a new file to a directory, follow these steps. 5010 5011@itemize @bullet 5012@item 5013You must have a working copy of the directory. 5014@xref{Getting the source}. 5015 5016@item 5017Create the new file inside your working copy of the directory. 5018 5019@item 5020Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you 5021want to version control the file. If the file contains 5022binary data, specify @samp{-kb} (@pxref{Binary files}). 5023 5024@item 5025Use @samp{cvs commit @var{filename}} to actually check 5026in the file into the repository. Other developers 5027cannot see the file until you perform this step. 5028@end itemize 5029 5030You can also use the @code{add} command to add a new 5031directory. 5032@c FIXCVS and/or FIXME: Adding a directory doesn't 5033@c require the commit step. This probably can be 5034@c considered a CVS bug, but it is possible we should 5035@c warn people since this behavior probably won't be 5036@c changing right away. 5037 5038Unlike most other commands, the @code{add} command is 5039not recursive. You have to explicitly name files and 5040directories that you wish to add to the repository. 5041However, each directory will need to be added 5042separately before you will be able to add new files 5043to those directories. 5044 5045@example 5046$ mkdir -p foo/bar 5047$ cp ~/myfile foo/bar/myfile 5048$ cvs add foo foo/bar 5049$ cvs add foo/bar/myfile 5050@end example 5051 5052@cindex add (subcommand) 5053@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 5054 5055Schedule @var{files} to be added to the repository. 5056The files or directories specified with @code{add} must 5057already exist in the current directory. To add a whole 5058new directory hierarchy to the source repository (for 5059example, files received from a third-party vendor), use 5060the @code{import} command instead. @xref{import}. 5061 5062The added files are not placed in the source repository 5063until you use @code{commit} to make the change 5064permanent. Doing an @code{add} on a file that was 5065removed with the @code{remove} command will undo the 5066effect of the @code{remove}, unless a @code{commit} 5067command intervened. @xref{Removing files}, for an 5068example. 5069 5070The @samp{-k} option specifies the default way that 5071this file will be checked out; for more information see 5072@ref{Substitution modes}. 5073 5074@c As noted in BUGS, -m is broken client/server (Nov 5075@c 96). Also see testsuite log2-* tests. 5076The @samp{-m} option specifies a description for the 5077file. This description appears in the history log (if 5078it is enabled, @pxref{history file}). It will also be 5079saved in the version history inside the repository when 5080the file is committed. The @code{log} command displays 5081this description. The description can be changed using 5082@samp{admin -t}. @xref{admin}. If you omit the 5083@samp{-m @var{description}} flag, an empty string will 5084be used. You will not be prompted for a description. 5085@end deffn 5086 5087For example, the following commands add the file 5088@file{backend.c} to the repository: 5089 5090@c This example used to specify 5091@c -m "Optimizer and code generation passes." 5092@c to the cvs add command, but that doesn't work 5093@c client/server (see log2 in sanity.sh). Should fix CVS, 5094@c but also seems strange to document things which 5095@c don't work... 5096@example 5097$ cvs add backend.c 5098$ cvs commit -m "Early version. Not yet compilable." backend.c 5099@end example 5100 5101When you add a file it is added only on the branch 5102which you are working on (@pxref{Branching and merging}). You can 5103later merge the additions to another branch if you want 5104(@pxref{Merging adds and removals}). 5105@c Should we mention that earlier versions of CVS 5106@c lacked this feature (1.3) or implemented it in a buggy 5107@c way (well, 1.8 had many bugs in cvs update -j)? 5108@c Should we mention the bug/limitation regarding a 5109@c file being a regular file on one branch and a directory 5110@c on another? 5111@c FIXME: This needs an example, or several, here or 5112@c elsewhere, for it to make much sense. 5113@c Somewhere we need to discuss the aspects of death 5114@c support which don't involve branching, I guess. 5115@c Like the ability to re-create a release from a tag. 5116 5117@c --------------------------------------------------------------------- 5118@node Removing files 5119@section Removing files 5120@cindex Removing files 5121@cindex Deleting files 5122 5123@c FIXME: this node wants to be split into several 5124@c smaller nodes. Could make these children of 5125@c "Adding and removing", probably (death support could 5126@c be its own section, for example, as could the 5127@c various bits about undoing mistakes in adding and 5128@c removing). 5129Directories change. New files are added, and old files 5130disappear. Still, you want to be able to retrieve an 5131exact copy of old releases. 5132 5133Here is what you can do to remove a file, 5134but remain able to retrieve old revisions: 5135 5136@itemize @bullet 5137@c FIXME: should probably be saying something about 5138@c having a working directory in the first place. 5139@item 5140Make sure that you have not made any uncommitted 5141modifications to the file. @xref{Viewing differences}, 5142for one way to do that. You can also use the 5143@code{status} or @code{update} command. If you remove 5144the file without committing your changes, you will of 5145course not be able to retrieve the file as it was 5146immediately before you deleted it. 5147 5148@item 5149Remove the file from your working copy of the directory. 5150You can for instance use @code{rm}. 5151 5152@item 5153Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that 5154you really want to delete the file. 5155 5156@item 5157Use @samp{cvs commit @var{filename}} to actually 5158perform the removal of the file from the repository. 5159@end itemize 5160 5161@c FIXME: Somehow this should be linked in with a more 5162@c general discussion of death support. I don't know 5163@c whether we want to use the term "death support" or 5164@c not (we can perhaps get by without it), but we do 5165@c need to discuss the "dead" state in "cvs log" and 5166@c related subjects. The current discussion is 5167@c scattered around, and not xref'd to each other. 5168@c FIXME: I think this paragraph wants to be moved 5169@c later down, at least after the first example. 5170When you commit the removal of the file, @sc{cvs} 5171records the fact that the file no longer exists. It is 5172possible for a file to exist on only some branches and 5173not on others, or to re-add another file with the same 5174name later. @sc{cvs} will correctly create or not create 5175the file, based on the @samp{-r} and @samp{-D} options 5176specified to @code{checkout} or @code{update}. 5177 5178@c FIXME: This style seems to clash with how we 5179@c document things in general. 5180@cindex Remove (subcommand) 5181@deffn Command {cvs remove} [options] files @dots{} 5182 5183Schedule file(s) to be removed from the repository 5184(files which have not already been removed from the 5185working directory are not processed). This command 5186does not actually remove the file from the repository 5187until you commit the removal. For a full list of 5188options, see @ref{Invoking CVS}. 5189@end deffn 5190 5191Here is an example of removing several files: 5192 5193@example 5194$ cd test 5195$ rm *.c 5196$ cvs remove 5197cvs remove: Removing . 5198cvs remove: scheduling a.c for removal 5199cvs remove: scheduling b.c for removal 5200cvs remove: use 'cvs commit' to remove these files permanently 5201$ cvs ci -m "Removed unneeded files" 5202cvs commit: Examining . 5203cvs commit: Committing . 5204@end example 5205 5206As a convenience you can remove the file and @code{cvs 5207remove} it in one step, by specifying the @samp{-f} 5208option. For example, the above example could also be 5209done like this: 5210 5211@example 5212$ cd test 5213$ cvs remove -f *.c 5214cvs remove: scheduling a.c for removal 5215cvs remove: scheduling b.c for removal 5216cvs remove: use 'cvs commit' to remove these files permanently 5217$ cvs ci -m "Removed unneeded files" 5218cvs commit: Examining . 5219cvs commit: Committing . 5220@end example 5221 5222If you execute @code{remove} for a file, and then 5223change your mind before you commit, you can undo the 5224@code{remove} with an @code{add} command. 5225@ignore 5226@c is this worth saying or not? Somehow it seems 5227@c confusing to me. 5228Of course, 5229since you have removed your copy of file in the working 5230directory, @sc{cvs} does not necessarily bring back the 5231contents of the file from right before you executed 5232@code{remove}; instead it gets the file from the 5233repository again. 5234@end ignore 5235 5236@c FIXME: what if you change your mind after you commit 5237@c it? (answer is also "cvs add" but we don't say that...). 5238@c We need some index entries for thinks like "undoing 5239@c removal" too. 5240 5241@example 5242$ ls 5243CVS ja.h oj.c 5244$ rm oj.c 5245$ cvs remove oj.c 5246cvs remove: scheduling oj.c for removal 5247cvs remove: use 'cvs commit' to remove this file permanently 5248$ cvs add oj.c 5249U oj.c 5250cvs add: oj.c, version 1.1.1.1, resurrected 5251@end example 5252 5253If you realize your mistake before you run the 5254@code{remove} command you can use @code{update} to 5255resurrect the file: 5256 5257@example 5258$ rm oj.c 5259$ cvs update oj.c 5260cvs update: warning: oj.c was lost 5261U oj.c 5262@end example 5263 5264When you remove a file it is removed only on the branch 5265which you are working on (@pxref{Branching and merging}). You can 5266later merge the removals to another branch if you want 5267(@pxref{Merging adds and removals}). 5268 5269@node Removing directories 5270@section Removing directories 5271@cindex Removing directories 5272@cindex Directories, removing 5273 5274In concept, removing directories is somewhat similar to 5275removing files---you want the directory to not exist in 5276your current working directories, but you also want to 5277be able to retrieve old releases in which the directory 5278existed. 5279 5280The way that you remove a directory is to remove all 5281the files in it. You don't remove the directory 5282itself; there is no way to do that. 5283Instead you specify the @samp{-P} option to 5284@code{cvs update} or @code{cvs checkout}, 5285which will cause @sc{cvs} to remove empty 5286directories from working directories. 5287(Note that @code{cvs export} always removes empty directories.) 5288Probably the 5289best way to do this is to always specify @samp{-P}; if 5290you want an empty directory then put a dummy file (for 5291example @file{.keepme}) in it to prevent @samp{-P} from 5292removing it. 5293 5294@c I'd try to give a rationale for this, but I'm not 5295@c sure there is a particularly convincing one. What 5296@c we would _like_ is for CVS to do a better job of version 5297@c controlling whether directories exist, to eliminate the 5298@c need for -P and so that a file can be a directory in 5299@c one revision and a regular file in another. 5300Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5301options of @code{checkout}. This way, 5302@sc{cvs} will be able to correctly create the directory 5303or not depending on whether the particular version you 5304are checking out contains any files in that directory. 5305 5306@c --------------------------------------------------------------------- 5307@node Moving files 5308@section Moving and renaming files 5309@cindex Moving files 5310@cindex Renaming files 5311@cindex Files, moving 5312 5313Moving files to a different directory or renaming them 5314is not difficult, but some of the ways in which this 5315works may be non-obvious. (Moving or renaming a 5316directory is even harder. @xref{Moving directories}.). 5317 5318The examples below assume that the file @var{old} is renamed to 5319@var{new}. 5320 5321@menu 5322* Outside:: The normal way to Rename 5323* Inside:: A tricky, alternative way 5324* Rename by copying:: Another tricky, alternative way 5325@end menu 5326 5327@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5328@node Outside 5329@subsection The Normal way to Rename 5330 5331@c More rename issues. Not sure whether these are 5332@c worth documenting; I'm putting them here because 5333@c it seems to be as good a place as any to try to 5334@c set down the issues. 5335@c * "cvs annotate" will annotate either the new 5336@c file or the old file; it cannot annotate _each 5337@c line_ based on whether it was last changed in the 5338@c new or old file. Unlike "cvs log", where the 5339@c consequences of having to select either the new 5340@c or old name seem fairly benign, this may be a 5341@c real advantage to having CVS know about renames 5342@c other than as a deletion and an addition. 5343 5344The normal way to move a file is to copy @var{old} to 5345@var{new}, and then issue the normal @sc{cvs} commands 5346to remove @var{old} from the repository, and add 5347@var{new} to it. 5348@c The following sentence is not true: one must cd into 5349@c the directory to run "cvs add". 5350@c (Both @var{old} and @var{new} could 5351@c contain relative paths, for example @file{foo/bar.c}). 5352 5353@example 5354$ mv @var{old} @var{new} 5355$ cvs remove @var{old} 5356$ cvs add @var{new} 5357$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 5358@end example 5359 5360This is the simplest way to move a file, it is not 5361error-prone, and it preserves the history of what was 5362done. Note that to access the history of the file you 5363must specify the old or the new name, depending on what 5364portion of the history you are accessing. For example, 5365@code{cvs log @var{old}} will give the log up until the 5366time of the rename. 5367 5368When @var{new} is committed its revision numbers will 5369start again, usually at 1.1, so if that bothers you, 5370use the @samp{-r @var{tag}} option to commit. For more 5371information see @ref{Assigning revisions}. 5372 5373@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5374@node Inside 5375@subsection Moving the history file 5376 5377This method is more dangerous, since it involves moving 5378files inside the repository. Read this entire section 5379before trying it out! 5380 5381@example 5382$ cd $CVSROOT/@var{dir} 5383$ mv @var{old},v @var{new},v 5384@end example 5385 5386@noindent 5387Advantages: 5388 5389@itemize @bullet 5390@item 5391The log of changes is maintained intact. 5392 5393@item 5394The revision numbers are not affected. 5395@end itemize 5396 5397@noindent 5398Disadvantages: 5399 5400@itemize @bullet 5401@item 5402Old releases cannot easily be fetched from the 5403repository. (The file will show up as @var{new} even 5404in revisions from the time before it was renamed). 5405 5406@item 5407There is no log information of when the file was renamed. 5408 5409@item 5410Nasty things might happen if someone accesses the history file 5411while you are moving it. Make sure no one else runs any of the @sc{cvs} 5412commands while you move it. 5413@end itemize 5414 5415@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5416@node Rename by copying 5417@subsection Copying the history file 5418 5419This way also involves direct modifications to the 5420repository. It is safe, but not without drawbacks. 5421 5422@example 5423# @r{Copy the @sc{rcs} file inside the repository} 5424$ cd $CVSROOT/@var{dir} 5425$ cp @var{old},v @var{new},v 5426# @r{Remove the old file} 5427$ cd ~/@var{dir} 5428$ rm @var{old} 5429$ cvs remove @var{old} 5430$ cvs commit @var{old} 5431# @r{Remove all tags from @var{new}} 5432$ cvs update @var{new} 5433$ cvs log @var{new} # @r{Remember the non-branch tag names} 5434$ cvs tag -d @var{tag1} @var{new} 5435$ cvs tag -d @var{tag2} @var{new} 5436@dots{} 5437@end example 5438 5439By removing the tags you will be able to check out old 5440revisions. 5441 5442@noindent 5443Advantages: 5444 5445@itemize @bullet 5446@item 5447@c FIXME: Is this true about -D now that we have death 5448@c support? See 5B.3 in the FAQ. 5449Checking out old revisions works correctly, as long as 5450you use @samp{-r @var{tag}} and not @samp{-D @var{date}} 5451to retrieve the revisions. 5452 5453@item 5454The log of changes is maintained intact. 5455 5456@item 5457The revision numbers are not affected. 5458@end itemize 5459 5460@noindent 5461Disadvantages: 5462 5463@itemize @bullet 5464@item 5465You cannot easily see the history of the file across the rename. 5466 5467@ignore 5468@c Is this true? I don't see how the revision numbers 5469@c _could_ start over, when new,v is just old,v with 5470@c the tags deleted. 5471@c If there is some need to reinstate this text, 5472@c it is "usually 1.1", not "1.0" and it needs an 5473@c xref to Assigning revisions 5474@item 5475Unless you use the @samp{-r @var{tag}} (@pxref{commit 5476options}) flag when @var{new} is committed its revision 5477numbers will start at 1.0 again. 5478@end ignore 5479@end itemize 5480 5481@c --------------------------------------------------------------------- 5482@node Moving directories 5483@section Moving and renaming directories 5484@cindex Moving directories 5485@cindex Renaming directories 5486@cindex Directories, moving 5487 5488The normal way to rename or move a directory is to 5489rename or move each file within it as described in 5490@ref{Outside}. Then check out with the @samp{-P} 5491option, as described in @ref{Removing directories}. 5492 5493If you really want to hack the repository to rename or 5494delete a directory in the repository, you can do it 5495like this: 5496 5497@enumerate 5498@item 5499Inform everyone who has a checked out copy of the directory that the 5500directory will be renamed. They should commit all their changes in all their 5501copies of the project containing the directory to be removed, and remove 5502all their working copies of said project, before you take the steps below. 5503 5504@item 5505Rename the directory inside the repository. 5506 5507@example 5508$ cd $CVSROOT/@var{parent-dir} 5509$ mv @var{old-dir} @var{new-dir} 5510@end example 5511 5512@item 5513Fix the @sc{cvs} administrative files, if necessary (for 5514instance if you renamed an entire module). 5515 5516@item 5517Tell everyone that they can check out again and continue 5518working. 5519 5520@end enumerate 5521 5522If someone had a working copy the @sc{cvs} commands will 5523cease to work for him, until he removes the directory 5524that disappeared inside the repository. 5525 5526It is almost always better to move the files in the 5527directory instead of moving the directory. If you move the 5528directory you are unlikely to be able to retrieve old 5529releases correctly, since they probably depend on the 5530name of the directories. 5531 5532@c --------------------------------------------------------------------- 5533@node History browsing 5534@chapter History browsing 5535@cindex History browsing 5536@cindex Traceability 5537@cindex Isolation 5538 5539@ignore 5540@c This is too long for an introduction (goal is 5541@c one 20x80 character screen), and also mixes up a 5542@c variety of issues (parallel development, history, 5543@c maybe even touches on process control). 5544 5545@c -- @quote{To lose ones history is to lose ones soul.} 5546@c -- /// 5547@c -- ///Those who cannot remember the past are condemned to repeat it. 5548@c -- /// -- George Santayana 5549@c -- /// 5550 5551@sc{cvs} tries to make it easy for a group of people to work 5552together. This is done in two ways: 5553 5554@itemize @bullet 5555@item 5556Isolation---You have your own working copy of the 5557source. You are not affected by modifications made by 5558others until you decide to incorporate those changes 5559(via the @code{update} command---@pxref{update}). 5560 5561@item 5562Traceability---When something has changed, you can 5563always see @emph{exactly} what changed. 5564@end itemize 5565 5566There are several features of @sc{cvs} that together lead 5567to traceability: 5568 5569@itemize @bullet 5570@item 5571Each revision of a file has an accompanying log 5572message. 5573 5574@item 5575All commits are optionally logged to a central history 5576database. 5577 5578@item 5579Logging information can be sent to a user-defined 5580program (@pxref{loginfo}). 5581@end itemize 5582 5583@c -- More text here. 5584 5585This chapter should talk about the history file, the 5586@code{log} command, the usefulness of ChangeLogs 5587even when you run @sc{cvs}, and things like that. 5588 5589@end ignore 5590 5591@c kind of lame, in a lot of ways the above text inside 5592@c the @ignore motivates this chapter better 5593Once you have used @sc{cvs} to store a version control 5594history---what files have changed when, how, and by 5595whom, there are a variety of mechanisms for looking 5596through the history. 5597 5598@c FIXME: should also be talking about how you look at 5599@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 5600@menu 5601* log messages:: Log messages 5602* history database:: The history database 5603* user-defined logging:: User-defined logging 5604@end menu 5605 5606@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5607@node log messages 5608@section Log messages 5609 5610@c FIXME: @xref to place where we talk about how to 5611@c specify message to commit. 5612Whenever you commit a file you specify a log message. 5613 5614@c FIXME: bring the information here, and get rid of or 5615@c greatly shrink the "log" node. 5616To look through the log messages which have been 5617specified for every revision which has been committed, 5618use the @code{cvs log} command (@pxref{log & rlog}). 5619 5620@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5621@node history database 5622@section The history database 5623 5624@c FIXME: bring the information from the history file 5625@c and history nodes here. Rewrite it to be motivated 5626@c better (start out by clearly explaining what gets 5627@c logged in history, for example). 5628You can use the history file (@pxref{history file}) to 5629log various @sc{cvs} actions. To retrieve the 5630information from the history file, use the @code{cvs 5631history} command (@pxref{history}). 5632 5633Note: you can control what is logged to this file by using the 5634@samp{LogHistory} keyword in the @file{CVSROOT/config} file 5635(@pxref{config}). 5636 5637@c 5638@c The history database has many problems: 5639@c * It is very unclear what field means what. This 5640@c could be improved greatly by better documentation, 5641@c but there are still non-orthogonalities (for 5642@c example, tag does not record the "repository" 5643@c field but most records do). 5644@c * Confusion about files, directories, and modules. 5645@c Some commands record one, some record others. 5646@c * File removal is not logged. There is an 'R' 5647@c record type documented, but CVS never uses it. 5648@c * Tags are only logged for the "cvs rtag" command, 5649@c not "cvs tag". The fix for this is not completely 5650@c clear (see above about modules vs. files). 5651@c * Are there other cases of operations that are not 5652@c logged? One would hope for all changes to the 5653@c repository to be logged somehow (particularly 5654@c operations like tagging, "cvs admin -k", and other 5655@c operations which do not record a history that one 5656@c can get with "cvs log"). Operations on the working 5657@c directory, like export, get, and release, are a 5658@c second category also covered by the current "cvs 5659@c history". 5660@c * The history file does not record the options given 5661@c to a command. The most serious manifestation of 5662@c this is perhaps that it doesn't record whether a command 5663@c was recursive. It is not clear to me whether one 5664@c wants to log at a level very close to the command 5665@c line, as a sort of way of logging each command 5666@c (more or less), or whether one wants 5667@c to log more at the level of what was changed (or 5668@c something in between), but either way the current 5669@c information has pretty big gaps. 5670@c * Further details about a tag--like whether it is a 5671@c branch tag or, if a non-branch tag, which branch it 5672@c is on. One can find out this information about the 5673@c tag as it exists _now_, but if the tag has been 5674@c moved, one doesn't know what it was like at the time 5675@c the history record was written. 5676@c * Whether operating on a particular tag, date, or 5677@c options was implicit (sticky) or explicit. 5678@c 5679@c Another item, only somewhat related to the above, is a 5680@c way to control what is logged in the history file. 5681@c This is probably the only good way to handle 5682@c different people having different ideas about 5683@c information/space tradeoffs. 5684@c 5685@c It isn't really clear that it makes sense to try to 5686@c patch up the history file format as it exists now to 5687@c include all that stuff. It might be better to 5688@c design a whole new CVSROOT/nhistory file and "cvs 5689@c nhistory" command, or some such, or in some other 5690@c way trying to come up with a clean break from the 5691@c past, which can address the above concerns. Another 5692@c open question is how/whether this relates to 5693@c taginfo/loginfo/etc. 5694 5695@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5696@node user-defined logging 5697@section User-defined logging 5698 5699@c FIXME: probably should centralize this information 5700@c here, at least to some extent. Maybe by moving the 5701@c loginfo, etc., nodes here and replacing 5702@c the "user-defined logging" node with one node for 5703@c each method. 5704You can customize @sc{cvs} to log various kinds of 5705actions, in whatever manner you choose. These 5706mechanisms operate by executing a script at various 5707times. The script might append a message to a file 5708listing the information and the programmer who created 5709it, or send mail to a group of developers, or, perhaps, 5710post a message to a particular newsgroup. To log 5711commits, use the @file{loginfo} file (@pxref{loginfo}), and 5712to log tagging operations, use the @file{taginfo} file 5713(@pxref{taginfo}). 5714 5715@c FIXME: What is difference between doing it in the 5716@c modules file and using loginfo/taginfo? Why should 5717@c user use one or the other? 5718To log commits, checkouts, exports, and tags, 5719respectively, you can also use the @samp{-i}, 5720@samp{-o}, @samp{-e}, and @samp{-t} options in the 5721modules file. For a more flexible way of giving 5722notifications to various users, which requires less in 5723the way of keeping centralized scripts up to date, use 5724the @code{cvs watch add} command (@pxref{Getting 5725Notified}); this command is useful even if you are not 5726using @code{cvs watch on}. 5727 5728@c --------------------------------------------------------------------- 5729@node Binary files 5730@chapter Handling binary files 5731@cindex Binary files 5732 5733The most common use for @sc{cvs} is to store text 5734files. With text files, @sc{cvs} can merge revisions, 5735display the differences between revisions in a 5736human-visible fashion, and other such operations. 5737However, if you are willing to give up a few of these 5738abilities, @sc{cvs} can store binary files. For 5739example, one might store a web site in @sc{cvs} 5740including both text files and binary images. 5741 5742@menu 5743* Binary why:: More details on issues with binary files 5744* Binary howto:: How to store them 5745@end menu 5746 5747@node Binary why 5748@section The issues with binary files 5749 5750While the need to manage binary files may seem obvious 5751if the files that you customarily work with are binary, 5752putting them into version control does present some 5753additional issues. 5754 5755One basic function of version control is to show the 5756differences between two revisions. For example, if 5757someone else checked in a new version of a file, you 5758may wish to look at what they changed and determine 5759whether their changes are good. For text files, 5760@sc{cvs} provides this functionality via the @code{cvs 5761diff} command. For binary files, it may be possible to 5762extract the two revisions and then compare them with a 5763tool external to @sc{cvs} (for example, word processing 5764software often has such a feature). If there is no 5765such tool, one must track changes via other mechanisms, 5766such as urging people to write good log messages, and 5767hoping that the changes they actually made were the 5768changes that they intended to make. 5769 5770Another ability of a version control system is the 5771ability to merge two revisions. For @sc{cvs} this 5772happens in two contexts. The first is when users make 5773changes in separate working directories 5774(@pxref{Multiple developers}). The second is when one 5775merges explicitly with the @samp{update -j} command 5776(@pxref{Branching and merging}). 5777 5778In the case of text 5779files, @sc{cvs} can merge changes made independently, 5780and signal a conflict if the changes conflict. With 5781binary files, the best that @sc{cvs} can do is present 5782the two different copies of the file, and leave it to 5783the user to resolve the conflict. The user may choose 5784one copy or the other, or may run an external merge 5785tool which knows about that particular file format, if 5786one exists. 5787Note that having the user merge relies primarily on the 5788user to not accidentally omit some changes, and thus is 5789potentially error prone. 5790 5791If this process is thought to be undesirable, the best 5792choice may be to avoid merging. To avoid the merges 5793that result from separate working directories, see the 5794discussion of reserved checkouts (file locking) in 5795@ref{Multiple developers}. To avoid the merges 5796resulting from branches, restrict use of branches. 5797 5798@node Binary howto 5799@section How to store binary files 5800 5801There are two issues with using @sc{cvs} to store 5802binary files. The first is that @sc{cvs} by default 5803converts line endings between the canonical form in 5804which they are stored in the repository (linefeed 5805only), and the form appropriate to the operating system 5806in use on the client (for example, carriage return 5807followed by line feed for Windows NT). 5808 5809The second is that a binary file might happen to 5810contain data which looks like a keyword (@pxref{Keyword 5811substitution}), so keyword expansion must be turned 5812off. 5813 5814@c FIXME: the third is that one can't do merges with 5815@c binary files. xref to Multiple Developers and the 5816@c reserved checkout issues. 5817 5818The @samp{-kb} option available with some @sc{cvs} 5819commands insures that neither line ending conversion 5820nor keyword expansion will be done. 5821 5822Here is an example of how you can create a new file 5823using the @samp{-kb} flag: 5824 5825@example 5826$ echo '$@splitrcskeyword{Id}$' > kotest 5827$ cvs add -kb -m"A test file" kotest 5828$ cvs ci -m"First checkin; contains a keyword" kotest 5829@end example 5830 5831If a file accidentally gets added without @samp{-kb}, 5832one can use the @code{cvs admin} command to recover. 5833For example: 5834 5835@example 5836$ echo '$@splitrcskeyword{Id}$' > kotest 5837$ cvs add -m"A test file" kotest 5838$ cvs ci -m"First checkin; contains a keyword" kotest 5839$ cvs admin -kb kotest 5840$ cvs update -A kotest 5841# @r{For non-unix systems:} 5842# @r{Copy in a good copy of the file from outside CVS} 5843$ cvs commit -m "make it binary" kotest 5844@end example 5845 5846@c Trying to describe this for both unix and non-unix 5847@c in the same description is very confusing. Might 5848@c want to split the two, or just ditch the unix "shortcut" 5849@c (unixheads don't do much with binary files, anyway). 5850@c This used to say "(Try the above example, and do a 5851@c @code{cat kotest} after every command)". But that 5852@c only really makes sense for the unix case. 5853When you check in the file @file{kotest} the file is 5854not preserved as a binary file, because you did not 5855check it in as a binary file. The @code{cvs 5856admin -kb} command sets the default keyword 5857substitution method for this file, but it does not 5858alter the working copy of the file that you have. If you need to 5859cope with line endings (that is, you are using 5860@sc{cvs} on a non-unix system), then you need to 5861check in a new copy of the file, as shown by the 5862@code{cvs commit} command above. 5863On unix, the @code{cvs update -A} command suffices. 5864@c FIXME: should also describe what the *other users* 5865@c need to do, if they have checked out copies which 5866@c have been corrupted by lack of -kb. I think maybe 5867@c "cvs update -kb" or "cvs 5868@c update -A" would suffice, although the user who 5869@c reported this suggested removing the file, manually 5870@c removing it from CVS/Entries, and then "cvs update" 5871(Note that you can use @code{cvs log} to determine the default keyword 5872substitution method for a file and @code{cvs status} to determine 5873the keyword substitution method for a working copy.) 5874 5875However, in using @code{cvs admin -k} to change the 5876keyword expansion, be aware that the keyword expansion 5877mode is not version controlled. This means that, for 5878example, that if you have a text file in old releases, 5879and a binary file with the same name in new releases, 5880@sc{cvs} provides no way to check out the file in text 5881or binary mode depending on what version you are 5882checking out. There is no good workaround for this 5883problem. 5884 5885You can also set a default for whether @code{cvs add} 5886and @code{cvs import} treat a file as binary based on 5887its name; for example you could say that files who 5888names end in @samp{.exe} are binary. @xref{Wrappers}. 5889There is currently no way to have @sc{cvs} detect 5890whether a file is binary based on its contents. The 5891main difficulty with designing such a feature is that 5892it is not clear how to distinguish between binary and 5893non-binary files, and the rules to apply would vary 5894considerably with the operating system. 5895@c For example, it would be good on MS-DOS-family OSes 5896@c for anything containing ^Z to be binary. Having 5897@c characters with the 8th bit set imply binary is almost 5898@c surely a bad idea in the context of ISO-8859-* and 5899@c other such character sets. On VMS or the Mac, we 5900@c could use the OS's file typing. This is a 5901@c commonly-desired feature, and something of this sort 5902@c may make sense. But there are a lot of pitfalls here. 5903@c 5904@c Another, probably better, way to tell is to read the 5905@c file in text mode, write it to a temp file in text 5906@c mode, and then do a binary mode compare of the two 5907@c files. If they differ, it is a binary file. This 5908@c might have problems on VMS (or some other system 5909@c with several different text modes), but in general 5910@c should be relatively portable. The only other 5911@c downside I can think of is that it would be fairly 5912@c slow, but that is perhaps a small price to pay for 5913@c not having your files corrupted. Another issue is 5914@c what happens if you import a text file with bare 5915@c linefeeds on Windows. Such files will show up on 5916@c Windows sometimes (I think some native windows 5917@c programs even write them, on occasion). Perhaps it 5918@c is reasonable to treat such files as binary; after 5919@c all it is something of a presumption to assume that 5920@c the user would want the linefeeds converted to CRLF. 5921 5922@c --------------------------------------------------------------------- 5923@node Multiple developers 5924@chapter Multiple developers 5925@cindex Multiple developers 5926@cindex Team of developers 5927@cindex File locking 5928@cindex Locking files 5929@cindex Working copy 5930@cindex Reserved checkouts 5931@cindex Unreserved checkouts 5932@cindex RCS-style locking 5933 5934When more than one person works on a software project 5935things often get complicated. Often, two people try to 5936edit the same file simultaneously. One solution, known 5937as @dfn{file locking} or @dfn{reserved checkouts}, is 5938to allow only one person to edit each file at a time. 5939This is the only solution with some version control 5940systems, including @sc{rcs} and @sc{sccs}. Currently 5941the usual way to get reserved checkouts with @sc{cvs} 5942is the @code{cvs admin -l} command (@pxref{admin 5943options}). This is not as nicely integrated into 5944@sc{cvs} as the watch features, described below, but it 5945seems that most people with a need for reserved 5946checkouts find it adequate. 5947@c Or "find it better than worrying about implementing 5948@c nicely integrated reserved checkouts" or ...? 5949 5950As of @sc{cvs} version 1.12.10, another technique for getting most of the 5951effect of reserved checkouts is to enable advisory locks. To enable advisory 5952locks, have all developers put "edit -c", "commit -c" in their 5953.cvsrc file, and turn on watches in the repository. This 5954prevents them from doing a @code{cvs edit} if anyone is 5955already editting the file. It also may 5956be possible to use plain watches together with suitable 5957procedures (not enforced by software), to avoid having 5958two people edit at the same time. 5959 5960@c Our unreserved checkout model might not 5961@c be quite the same as others. For example, I 5962@c think that some systems will tend to create a branch 5963@c in the case where CVS prints "up-to-date check failed". 5964@c It isn't clear to me whether we should try to 5965@c explore these subtleties; it could easily just 5966@c confuse people. 5967The default model with @sc{cvs} is known as 5968@dfn{unreserved checkouts}. In this model, developers 5969can edit their own @dfn{working copy} of a file 5970simultaneously. The first person that commits his 5971changes has no automatic way of knowing that another 5972has started to edit it. Others will get an error 5973message when they try to commit the file. They must 5974then use @sc{cvs} commands to bring their working copy 5975up to date with the repository revision. This process 5976is almost automatic. 5977 5978@c FIXME? should probably use the word "watch" here, to 5979@c tie this into the text below and above. 5980@sc{cvs} also supports mechanisms which facilitate 5981various kinds of communication, without actually 5982enforcing rules like reserved checkouts do. 5983 5984The rest of this chapter describes how these various 5985models work, and some of the issues involved in 5986choosing between them. 5987 5988@ignore 5989Here is a draft reserved checkout design or discussion 5990of the issues. This seems like as good a place as any 5991for this. 5992 5993Might want a cvs lock/cvs unlock--in which the names 5994differ from edit/unedit because the network must be up 5995for these to work. unedit gives an error if there is a 5996reserved checkout in place (so that people don't 5997accidentally leave locks around); unlock gives an error 5998if one is not in place (this is more arguable; perhaps 5999it should act like unedit in that case). 6000 6001On the other hand, might want it so that emacs, 6002scripts, etc., can get ready to edit a file without 6003having to know which model is in use. In that case we 6004would have a "cvs watch lock" (or .cvsrc?) (that is, 6005three settings, "on", "off", and "lock"). Having cvs 6006watch lock set would cause a get to record in the CVS 6007directory which model is in use, and cause "cvs edit" 6008to change behaviors. We'd want a way to query which 6009setting is in effect (this would be handy even if it is 6010only "on" or "off" as presently). If lock is in 6011effect, then commit would require a lock before 6012allowing a checkin; chmod wouldn't suffice (might be 6013debatable--see chmod comment below, in watches--but it 6014is the way people expect RCS to work and I can't think 6015of any significant downside. On the other hand, maybe 6016it isn't worth bothering, because people who are used 6017to RCS wouldn't think to use chmod anyway). 6018 6019Implementation: use file attributes or use RCS 6020locking. The former avoids more dependence on RCS 6021behaviors we will need to re-implement as we librarify 6022RCS, and makes it easier to import/export RCS files (in 6023that context, want to ignore the locker field). But 6024note that RCS locks are per-branch, which is the 6025correct behavior (this is also an issue for the "watch 6026on" features; they should be per-branch too). 6027 6028Here are a few more random notes about implementation 6029details, assuming "cvs watch lock" and 6030 6031CVS/Watched file? Or try to fit this into CVS/Entries somehow? 6032Cases: (1) file is checked out (unreserved or with watch on) by old 6033version of @sc{cvs}, now we do something with new one, (2) file is checked 6034out by new version, now we do something with old one. 6035 6036Remote protocol would have a "Watched" analogous to "Mode". Of course 6037it would apply to all Updated-like requests. How do we keep this 6038setting up to date? I guess that there wants to be a Watched request, 6039and the server would send a new one if it isn't up to date? (Ugh--hard 6040to implement and slows down "cvs -q update"--is there an easier way?) 6041 6042"cvs edit"--checks CVS/Watched, and if watch lock, then sends 6043"edit-lock" request. Which comes back with a Checked-in with 6044appropriate Watched (off, on, lock, locked, or some such?), or error 6045message if already locked. 6046 6047"cvs commit"--only will commit if off/on/locked. lock is not OK. 6048 6049Doc: 6050note that "cvs edit" must be connected to network if watch lock is in 6051effect. 6052 6053Talk about what to do if someone has locked a file and you want to 6054edit that file. (breaking locks, or lack thereof). 6055 6056 6057One other idea (which could work along with the 6058existing "cvs admin -l" reserved checkouts, as well as 6059the above): 6060 6061"cvs editors" could show who has the file locked, if 6062someone does. 6063 6064@end ignore 6065 6066@menu 6067* File status:: A file can be in several states 6068* Updating a file:: Bringing a file up-to-date 6069* Conflicts example:: An informative example 6070* Informing others:: To cooperate you must inform 6071* Concurrency:: Simultaneous repository access 6072* Watches:: Mechanisms to track who is editing files 6073* Choosing a model:: Reserved or unreserved checkouts? 6074@end menu 6075 6076@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6077@node File status 6078@section File status 6079@cindex File status 6080@cindex Status of a file 6081 6082@c Shouldn't this start with an example or something, 6083@c introducing the unreserved checkout model? Before we 6084@c dive into listing states? 6085Based on what operations you have performed on a 6086checked out file, and what operations others have 6087performed to that file in the repository, one can 6088classify a file in a number of states. The states, as 6089reported by the @code{status} command, are: 6090 6091@c The order of items is chosen to group logically 6092@c similar outputs together. 6093@c People who want alphabetical can use the index... 6094@table @asis 6095@cindex Up-to-date 6096@item Up-to-date 6097The file is identical with the latest revision in the 6098repository for the branch in use. 6099@c FIXME: should we clarify "in use"? The answer is 6100@c sticky tags, and trying to distinguish branch sticky 6101@c tags from non-branch sticky tags seems rather awkward 6102@c here. 6103@c FIXME: What happens with non-branch sticky tags? Is 6104@c a stuck file "Up-to-date" or "Needs checkout" or what? 6105 6106@item Locally Modified 6107@cindex Locally Modified 6108You have edited the file, and not yet committed your changes. 6109 6110@item Locally Added 6111@cindex Locally Added 6112You have added the file with @code{add}, and not yet 6113committed your changes. 6114@c There are many cases involving the file being 6115@c added/removed/modified in the working directory, and 6116@c added/removed/modified in the repository, which we 6117@c don't try to describe here. I'm not sure that "cvs 6118@c status" produces a non-confusing output in most of 6119@c those cases. 6120 6121@item Locally Removed 6122@cindex Locally Removed 6123You have removed the file with @code{remove}, and not yet 6124committed your changes. 6125 6126@item Needs Checkout 6127@cindex Needs Checkout 6128Someone else has committed a newer revision to the 6129repository. The name is slightly misleading; you will 6130ordinarily use @code{update} rather than 6131@code{checkout} to get that newer revision. 6132 6133@item Needs Patch 6134@cindex Needs Patch 6135@c See also newb-123j0 in sanity.sh (although that case 6136@c should probably be changed rather than documented). 6137Like Needs Checkout, but the @sc{cvs} server will send 6138a patch rather than the entire file. Sending a patch or 6139sending an entire file accomplishes the same thing. 6140 6141@item Needs Merge 6142@cindex Needs Merge 6143Someone else has committed a newer revision to the repository, and you 6144have also made modifications to the file. 6145 6146@item Unresolved Conflict 6147@cindex Unresolved Conflict 6148@c FIXCVS - This file status needs to be changed to some more informative 6149@c text that distinguishes it more clearly from each of the Locally Added, 6150@c File had conflicts on merge, and Unknown status types, but an exact and 6151@c succinct wording escapes me at the moment. 6152A file with the same name as this new file has been added to the repository 6153from a second workspace. This file will need to be moved out of the way 6154to allow an @code{update} to complete. 6155 6156@item File had conflicts on merge 6157@cindex File had conflicts on merge 6158@c is it worth saying that this message was "Unresolved 6159@c Conflict" in CVS 1.9 and earlier? I'm inclined to 6160@c think that is unnecessarily confusing to new users. 6161This is like Locally Modified, except that a previous 6162@code{update} command gave a conflict. If you have not 6163already done so, you need to 6164resolve the conflict as described in @ref{Conflicts example}. 6165 6166@item Unknown 6167@cindex Unknown 6168@sc{cvs} doesn't know anything about this file. For 6169example, you have created a new file and have not run 6170@code{add}. 6171@c 6172@c "Entry Invalid" and "Classify Error" are also in the 6173@c status.c. The latter definitely indicates a CVS bug 6174@c (should it be worded more like "internal error" so 6175@c people submit bug reports if they see it?). The former 6176@c I'm not as sure; I haven't tracked down whether/when it 6177@c appears in "cvs status" output. 6178 6179@end table 6180 6181To help clarify the file status, @code{status} also 6182reports the @code{Working revision} which is the 6183revision that the file in the working directory derives 6184from, and the @code{Repository revision} which is the 6185latest revision in the repository for the branch in 6186use. 6187The @samp{Commit Identifier} reflects the unique commitid 6188of the @code{commit}. 6189@c FIXME: should we clarify "in use"? The answer is 6190@c sticky tags, and trying to distinguish branch sticky 6191@c tags from non-branch sticky tags seems rather awkward 6192@c here. 6193@c FIXME: What happens with non-branch sticky tags? 6194@c What is the Repository Revision there? See the 6195@c comment at vn_rcs in cvs.h, which is kind of 6196@c confused--we really need to document better what this 6197@c field contains. 6198@c Q: Should we document "New file!" and other such 6199@c outputs or are they self-explanatory? 6200@c FIXME: what about the date to the right of "Working 6201@c revision"? It doesn't appear with client/server and 6202@c seems unnecessary (redundant with "ls -l") so 6203@c perhaps it should be removed for non-client/server too? 6204@c FIXME: Need some examples. 6205@c FIXME: Working revision can also be something like 6206@c "-1.3" for a locally removed file. Not at all 6207@c self-explanatory (and it is possible that CVS should 6208@c be changed rather than documenting this). 6209 6210@c Would be nice to have an @example showing output 6211@c from cvs status, with comments showing the xref 6212@c where each part of the output is described. This 6213@c might fit in nicely if it is desirable to split this 6214@c node in two; one to introduce "cvs status" and one 6215@c to list each of the states. 6216The options to @code{status} are listed in 6217@ref{Invoking CVS}. For information on its @code{Sticky tag} 6218and @code{Sticky date} output, see @ref{Sticky tags}. 6219For information on its @code{Sticky options} output, 6220see the @samp{-k} option in @ref{update options}. 6221 6222You can think of the @code{status} and @code{update} 6223commands as somewhat complementary. You use 6224@code{update} to bring your files up to date, and you 6225can use @code{status} to give you some idea of what an 6226@code{update} would do (of course, the state of the 6227repository might change before you actually run 6228@code{update}). In fact, if you want a command to 6229display file status in a more brief format than is 6230displayed by the @code{status} command, you can invoke 6231 6232@cindex update, to display file status 6233@example 6234$ cvs -n -q update 6235@end example 6236 6237The @samp{-n} option means to not actually do the 6238update, but merely to display statuses; the @samp{-q} 6239option avoids printing the name of each directory. For 6240more information on the @code{update} command, and 6241these options, see @ref{Invoking CVS}. 6242 6243@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6244@node Updating a file 6245@section Bringing a file up to date 6246@cindex Bringing a file up to date 6247@cindex Updating a file 6248@cindex Merging a file 6249@cindex Update, introduction 6250 6251When you want to update or merge a file, use the @code{cvs update -d} 6252command. For files that are not up to date this is roughly equivalent 6253to a @code{checkout} command: the newest revision of the file is 6254extracted from the repository and put in your working directory. The 6255@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} 6256that you wish it to create directories added by other developers. 6257 6258Your modifications to a file are never lost when you 6259use @code{update}. If no newer revision exists, 6260running @code{update} has no effect. If you have 6261edited the file, and a newer revision is available, 6262@sc{cvs} will merge all changes into your working copy. 6263 6264For instance, imagine that you checked out revision 1.4 and started 6265editing it. In the meantime someone else committed revision 1.5, and 6266shortly after that revision 1.6. If you run @code{update} on the file 6267now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 6268your file. 6269 6270@cindex Overlap 6271If any of the changes between 1.4 and 1.6 were made too 6272close to any of the changes you have made, an 6273@dfn{overlap} occurs. In such cases a warning is 6274printed, and the resulting file includes both 6275versions of the lines that overlap, delimited by 6276special markers. 6277@xref{update}, for a complete description of the 6278@code{update} command. 6279 6280@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6281@node Conflicts example 6282@section Conflicts example 6283@cindex Merge, an example 6284@cindex Example of merge 6285@cindex driver.c (merge example) 6286 6287Suppose revision 1.4 of @file{driver.c} contains this: 6288 6289@example 6290#include <stdio.h> 6291 6292void main() 6293@{ 6294 parse(); 6295 if (nerr == 0) 6296 gencode(); 6297 else 6298 fprintf(stderr, "No code generated.\n"); 6299 exit(nerr == 0 ? 0 : 1); 6300@} 6301@end example 6302 6303@noindent 6304Revision 1.6 of @file{driver.c} contains this: 6305 6306@example 6307#include <stdio.h> 6308 6309int main(int argc, 6310 char **argv) 6311@{ 6312 parse(); 6313 if (argc != 1) 6314 @{ 6315 fprintf(stderr, "tc: No args expected.\n"); 6316 exit(1); 6317 @} 6318 if (nerr == 0) 6319 gencode(); 6320 else 6321 fprintf(stderr, "No code generated.\n"); 6322 exit(!!nerr); 6323@} 6324@end example 6325 6326@noindent 6327Your working copy of @file{driver.c}, based on revision 63281.4, contains this before you run @samp{cvs update}: 6329@c -- Really include "cvs"? 6330 6331@example 6332#include <stdlib.h> 6333#include <stdio.h> 6334 6335void main() 6336@{ 6337 init_scanner(); 6338 parse(); 6339 if (nerr == 0) 6340 gencode(); 6341 else 6342 fprintf(stderr, "No code generated.\n"); 6343 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6344@} 6345@end example 6346 6347@noindent 6348You run @samp{cvs update}: 6349@c -- Really include "cvs"? 6350 6351@example 6352$ cvs update driver.c 6353RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 6354retrieving revision 1.4 6355retrieving revision 1.6 6356Merging differences between 1.4 and 1.6 into driver.c 6357rcsmerge warning: overlaps during merge 6358cvs update: conflicts found in driver.c 6359C driver.c 6360@end example 6361 6362@noindent 6363@cindex Conflicts (merge example) 6364@sc{cvs} tells you that there were some conflicts. 6365Your original working file is saved unmodified in 6366@file{.#driver.c.1.4}. The new version of 6367@file{driver.c} contains this: 6368 6369@example 6370#include <stdlib.h> 6371#include <stdio.h> 6372 6373int main(int argc, 6374 char **argv) 6375@{ 6376 init_scanner(); 6377 parse(); 6378 if (argc != 1) 6379 @{ 6380 fprintf(stderr, "tc: No args expected.\n"); 6381 exit(1); 6382 @} 6383 if (nerr == 0) 6384 gencode(); 6385 else 6386 fprintf(stderr, "No code generated.\n"); 6387@asis{}<<<<<<< driver.c 6388 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6389@asis{}======= 6390 exit(!!nerr); 6391@asis{}>>>>>>> 1.6 6392@} 6393@end example 6394 6395@noindent 6396@cindex Markers, conflict 6397@cindex Conflict markers 6398@cindex <<<<<<< 6399@cindex >>>>>>> 6400@cindex ======= 6401 6402Note how all non-overlapping modifications are incorporated in your working 6403copy, and that the overlapping section is clearly marked with 6404@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 6405 6406@cindex Resolving a conflict 6407@cindex Conflict resolution 6408You resolve the conflict by editing the file, removing the markers and 6409the erroneous line. Suppose you end up with this file: 6410@c -- Add xref to the pcl-cvs manual when it talks 6411@c -- about this. 6412@example 6413#include <stdlib.h> 6414#include <stdio.h> 6415 6416int main(int argc, 6417 char **argv) 6418@{ 6419 init_scanner(); 6420 parse(); 6421 if (argc != 1) 6422 @{ 6423 fprintf(stderr, "tc: No args expected.\n"); 6424 exit(1); 6425 @} 6426 if (nerr == 0) 6427 gencode(); 6428 else 6429 fprintf(stderr, "No code generated.\n"); 6430 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6431@} 6432@end example 6433 6434@noindent 6435You can now go ahead and commit this as revision 1.7. 6436 6437@example 6438$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 6439Checking in driver.c; 6440/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 6441new revision: 1.7; previous revision: 1.6 6442done 6443@end example 6444 6445For your protection, @sc{cvs} will refuse to check in a 6446file if a conflict occurred and you have not resolved 6447the conflict. Currently to resolve a conflict, you 6448must change the timestamp on the file. In previous 6449versions of @sc{cvs}, you also needed to 6450insure that the file contains no conflict markers. 6451Because 6452your file may legitimately contain conflict markers (that 6453is, occurrences of @samp{>>>>>>> } at the start of a 6454line that don't mark a conflict), the current 6455version of @sc{cvs} will print a warning and proceed to 6456check in the file. 6457@c The old behavior was really icky; the only way out 6458@c was to start hacking on 6459@c the @code{CVS/Entries} file or other such workarounds. 6460@c 6461@c If the timestamp thing isn't considered nice enough, 6462@c maybe there should be a "cvs resolved" command 6463@c which clears the conflict indication. For a nice user 6464@c interface, this should be invoked by an interactive 6465@c merge tool like emerge rather than by the user 6466@c directly--such a tool can verify that the user has 6467@c really dealt with each conflict. 6468 6469@cindex emerge 6470If you use release 1.04 or later of pcl-cvs (a @sc{gnu} 6471Emacs front-end for @sc{cvs}) you can use an Emacs 6472package called emerge to help you resolve conflicts. 6473See the documentation for pcl-cvs. 6474 6475@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6476@node Informing others 6477@section Informing others about commits 6478@cindex Informing others 6479@cindex Spreading information 6480@cindex Mail, automatic mail on commit 6481 6482It is often useful to inform others when you commit a 6483new revision of a file. The @samp{-i} option of the 6484@file{modules} file, or the @file{loginfo} file, can be 6485used to automate this process. @xref{modules}. 6486@xref{loginfo}. You can use these features of @sc{cvs} 6487to, for instance, instruct @sc{cvs} to mail a 6488message to all developers, or post a message to a local 6489newsgroup. 6490@c -- More text would be nice here. 6491 6492@node Concurrency 6493@section Several developers simultaneously attempting to run CVS 6494 6495@cindex Locks, cvs, introduction 6496@c For a discussion of *why* CVS creates locks, see 6497@c the comment at the start of src/lock.c 6498If several developers try to run @sc{cvs} at the same 6499time, one may get the following message: 6500 6501@example 6502[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 6503@end example 6504 6505@cindex #cvs.rfl, removing 6506@cindex #cvs.wfl, removing 6507@cindex #cvs.lock, removing 6508@sc{cvs} will try again every 30 seconds, and either 6509continue with the operation or print the message again, 6510if it still needs to wait. If a lock seems to stick 6511around for an undue amount of time, find the person 6512holding the lock and ask them about the cvs command 6513they are running. If they aren't running a cvs 6514command, look in the repository directory mentioned in 6515the message and remove files which they own whose names 6516start with @file{#cvs.rfl}, 6517@file{#cvs.wfl}, or @file{#cvs.lock}. 6518 6519Note that these locks are to protect @sc{cvs}'s 6520internal data structures and have no relationship to 6521the word @dfn{lock} in the sense used by 6522@sc{rcs}---which refers to reserved checkouts 6523(@pxref{Multiple developers}). 6524 6525Any number of people can be reading from a given 6526repository at a time; only when someone is writing do 6527the locks prevent other people from reading or writing. 6528 6529@cindex Atomic transactions, lack of 6530@cindex Transactions, atomic, lack of 6531@c the following talks about what one might call commit/update 6532@c atomicity. 6533@c Probably also should say something about 6534@c commit/commit atomicity, that is, "An update will 6535@c not get partial versions of more than one commit". 6536@c CVS currently has this property and I guess we can 6537@c make it a documented feature. 6538@c For example one person commits 6539@c a/one.c and b/four.c and another commits a/two.c and 6540@c b/three.c. Then an update cannot get the new a/one.c 6541@c and a/two.c and the old b/four.c and b/three.c. 6542One might hope for the following property: 6543 6544@quotation 6545If someone commits some changes in one cvs command, 6546then an update by someone else will either get all the 6547changes, or none of them. 6548@end quotation 6549 6550@noindent 6551but @sc{cvs} does @emph{not} have this property. For 6552example, given the files 6553 6554@example 6555a/one.c 6556a/two.c 6557b/three.c 6558b/four.c 6559@end example 6560 6561@noindent 6562if someone runs 6563 6564@example 6565cvs ci a/two.c b/three.c 6566@end example 6567 6568@noindent 6569and someone else runs @code{cvs update} at the same 6570time, the person running @code{update} might get only 6571the change to @file{b/three.c} and not the change to 6572@file{a/two.c}. 6573 6574@node Watches 6575@section Mechanisms to track who is editing files 6576@cindex Watches 6577 6578For many groups, use of @sc{cvs} in its default mode is 6579perfectly satisfactory. Users may sometimes go to 6580check in a modification only to find that another 6581modification has intervened, but they deal with it and 6582proceed with their check in. Other groups prefer to be 6583able to know who is editing what files, so that if two 6584people try to edit the same file they can choose to 6585talk about who is doing what when rather than be 6586surprised at check in time. The features in this 6587section allow such coordination, while retaining the 6588ability of two developers to edit the same file at the 6589same time. 6590 6591@c Some people might ask why CVS does not enforce the 6592@c rule on chmod, by requiring a cvs edit before a cvs 6593@c commit. The main reason is that it could always be 6594@c circumvented--one could edit the file, and 6595@c then when ready to check it in, do the cvs edit and put 6596@c in the new contents and do the cvs commit. One 6597@c implementation note: if we _do_ want to have cvs commit 6598@c require a cvs edit, we should store the state on 6599@c whether the cvs edit has occurred in the working 6600@c directory, rather than having the server try to keep 6601@c track of what working directories exist. 6602@c FIXME: should the above discussion be part of the 6603@c manual proper, somewhere, not just in a comment? 6604For maximum benefit developers should use @code{cvs 6605edit} (not @code{chmod}) to make files read-write to 6606edit them, and @code{cvs release} (not @code{rm}) to 6607discard a working directory which is no longer in use, 6608but @sc{cvs} is not able to enforce this behavior. 6609 6610If a development team wants stronger enforcement of 6611watches and all team members are using a @sc{cvs} client version 1.12.10 or 6612greater to access a @sc{cvs} server version 1.12.10 or greater, they can 6613enable advisory locks. To enable advisory locks, have all developers 6614put "edit -c" and "commit -c" into all .cvsrc files, 6615and make files default to read only by turning on watches 6616or putting "cvs -r" into all .cvsrc files. 6617This prevents multiple people from editting a file at 6618the same time (unless explicitly overriden with @samp{-f}). 6619 6620@c I'm a little dissatisfied with this presentation, 6621@c because "watch on"/"edit"/"editors" are one set of 6622@c functionality, and "watch add"/"watchers" is another 6623@c which is somewhat orthogonal even though they interact in 6624@c various ways. But I think it might be 6625@c confusing to describe them separately (e.g. "watch 6626@c add" with loginfo). I don't know. 6627 6628@menu 6629* Setting a watch:: Telling CVS to watch certain files 6630* Getting Notified:: Telling CVS to notify you 6631* Editing files:: How to edit a file which is being watched 6632* Watch information:: Information about who is watching and editing 6633* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 6634@end menu 6635 6636@node Setting a watch 6637@subsection Telling CVS to watch certain files 6638 6639To enable the watch features, you first specify that 6640certain files are to be watched. 6641 6642@cindex watch on (subcommand) 6643@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 6644 6645@cindex Read-only files, and watches 6646Specify that developers should run @code{cvs edit} 6647before editing @var{files}. @sc{cvs} will create working 6648copies of @var{files} read-only, to remind developers 6649to run the @code{cvs edit} command before working on 6650them. 6651 6652If @var{files} includes the name of a directory, @sc{cvs} 6653arranges to watch all files added to the corresponding 6654repository directory, and sets a default for files 6655added in the future; this allows the user to set 6656notification policies on a per-directory basis. The 6657contents of the directory are processed recursively, 6658unless the @code{-l} option is given. 6659The @code{-R} option can be used to force recursion if the @code{-l} 6660option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 6661 6662If @var{files} is omitted, it defaults to the current directory. 6663 6664@cindex watch off (subcommand) 6665@end deffn 6666 6667@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 6668 6669Do not create @var{files} read-only on checkout; thus, 6670developers will not be reminded to use @code{cvs edit} 6671and @code{cvs unedit}. 6672@ignore 6673@sc{cvs} will check out @var{files} 6674read-write as usual, unless other permissions override 6675due to the @code{PreservePermissions} option being 6676enabled in the @file{config} administrative file 6677(@pxref{Special Files}, @pxref{config}) 6678@end ignore 6679 6680The @var{files} and options are processed as for @code{cvs 6681watch on}. 6682 6683@end deffn 6684 6685@node Getting Notified 6686@subsection Telling CVS to notify you 6687 6688You can tell @sc{cvs} that you want to receive 6689notifications about various actions taken on a file. 6690You can do this without using @code{cvs watch on} for 6691the file, but generally you will want to use @code{cvs 6692watch on}, to remind developers to use the @code{cvs edit} 6693command. 6694 6695@cindex watch add (subcommand) 6696@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6697 6698Add the current user to the list of people to receive notification of 6699work done on @var{files}. 6700 6701The @code{-a} option specifies what kinds of events @sc{cvs} should notify 6702the user about. @var{action} is one of the following: 6703 6704@table @code 6705 6706@item edit 6707Another user has applied the @code{cvs edit} command (described 6708below) to a watched file. 6709 6710@item commit 6711Another user has committed changes to one of the named @var{files}. 6712 6713@item unedit 6714Another user has abandoned editing a file (other than by committing changes). 6715They can do this in several ways, by: 6716 6717@itemize @bullet 6718 6719@item 6720applying the @code{cvs unedit} command (described below) to the file 6721 6722@item 6723applying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6724(or recursively to a directory more than one level up) 6725 6726@item 6727deleting the file and allowing @code{cvs update} to recreate it 6728 6729@end itemize 6730 6731@item all 6732All of the above. 6733 6734@item none 6735None of the above. (This is useful with @code{cvs edit}, 6736described below.) 6737 6738@end table 6739 6740The @code{-a} option may appear more than once, or not at all. If 6741omitted, the action defaults to @code{all}. 6742 6743The @var{files} and options are processed as for 6744@code{cvs watch on}. 6745 6746@end deffn 6747 6748 6749@cindex watch remove (subcommand) 6750@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6751 6752Remove a notification request established using @code{cvs watch add}; 6753the arguments are the same. If the @code{-a} option is present, only 6754watches for the specified actions are removed. 6755 6756@end deffn 6757 6758@cindex notify (admin file) 6759When the conditions exist for notification, @sc{cvs} 6760calls the @file{notify} administrative file. Edit 6761@file{notify} as one edits the other administrative 6762files (@pxref{Intro administrative files}). This 6763file follows the usual conventions for administrative 6764files (@pxref{syntax}), where each line is a regular 6765expression followed by a command to execute. The 6766command should contain a single occurrence of @samp{%s} 6767which will be replaced by the user to notify; the rest 6768of the information regarding the notification will be 6769supplied to the command on standard input. The 6770standard thing to put in the @code{notify} file is the 6771single line: 6772 6773@example 6774ALL mail %s -s "CVS notification" 6775@end example 6776 6777@noindent 6778This causes users to be notified by electronic mail. 6779@c FIXME: should it be this hard to set up this 6780@c behavior (and the result when one fails to do so, 6781@c silent failure to notify, so non-obvious)? Should 6782@c CVS give a warning if no line in notify matches (and 6783@c document the use of "DEFAULT :" for the case where 6784@c skipping the notification is indeed desired)? 6785 6786@cindex users (admin file) 6787Note that if you set this up in the straightforward 6788way, users receive notifications on the server machine. 6789One could of course write a @file{notify} script which 6790directed notifications elsewhere, but to make this 6791easy, @sc{cvs} allows you to associate a notification 6792address for each user. To do so create a file 6793@file{users} in @file{CVSROOT} with a line for each 6794user in the format @var{user}:@var{value}. Then 6795instead of passing the name of the user to be notified 6796to @file{notify}, @sc{cvs} will pass the @var{value} 6797(normally an email address on some other machine). 6798 6799@sc{cvs} does not notify you for your own changes. 6800Currently this check is done based on whether the user 6801name of the person taking the action which triggers 6802notification matches the user name of the person 6803getting notification. In fact, in general, the watches 6804features only track one edit by each user. It probably 6805would be more useful if watches tracked each working 6806directory separately, so this behavior might be worth 6807changing. 6808@c "behavior might be worth changing" is an effort to 6809@c point to future directions while also not promising 6810@c that "they" (as in "why don't they fix CVS to....") 6811@c will do this. 6812@c one implementation issue is identifying whether a 6813@c working directory is same or different. Comparing 6814@c pathnames/hostnames is hopeless, but having the server 6815@c supply a serial number which the client stores in the 6816@c CVS directory as a magic cookie should work. 6817 6818@node Editing files 6819@subsection How to edit a file which is being watched 6820 6821@cindex Checkout, as term for getting ready to edit 6822Since a file which is being watched is checked out 6823read-only, you cannot simply edit it. To make it 6824read-write, and inform others that you are planning to 6825edit it, use the @code{cvs edit} command. Some systems 6826call this a @dfn{checkout}, but @sc{cvs} uses that term 6827for obtaining a copy of the sources (@pxref{Getting the 6828source}), an operation which those systems call a 6829@dfn{get} or a @dfn{fetch}. 6830@c Issue to think about: should we transition CVS 6831@c towards the "get" terminology? "cvs get" is already a 6832@c synonym for "cvs checkout" and that section of the 6833@c manual refers to "Getting the source". If this is 6834@c done, needs to be done gingerly (for example, we should 6835@c still accept "checkout" in .cvsrc files indefinitely 6836@c even if the CVS's messages are changed from "cvs checkout: " 6837@c to "cvs get: "). 6838@c There is a concern about whether "get" is not as 6839@c good for novices because it is a more general term 6840@c than "checkout" (and thus arguably harder to assign 6841@c a technical meaning for). 6842 6843@cindex edit (subcommand) 6844@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6845 6846Prepare to edit the working files @var{files}. @sc{cvs} makes the 6847@var{files} read-write, and notifies users who have requested 6848@code{edit} notification for any of @var{files}. 6849 6850The @code{cvs edit} command accepts the same options as the 6851@code{cvs watch add} command, and establishes a temporary watch for the 6852user on @var{files}; @sc{cvs} will remove the watch when @var{files} are 6853@code{unedit}ed or @code{commit}ted. If the user does not wish to 6854receive notifications, she should specify @code{-a none}. 6855 6856The @var{files} and the options are processed as for the @code{cvs 6857watch} commands. 6858 6859There are two additional options that @code{cvs edit} understands as of 6860@sc{cvs} client and server versions 1.12.10 but @code{cvs watch} does not. 6861The first is @code{-c}, which causes @code{cvs edit} to fail if anyone else 6862is editting the file. This is probably only useful when @samp{edit -c} and 6863@samp{commit -c} are specified in all developers' @file{.cvsrc} files. This 6864behavior may be overriden this via the @code{-f} option, which overrides 6865@code{-c} and allows multiple edits to succeed. 6866 6867@ignore 6868@strong{Caution: If the @code{PreservePermissions} 6869option is enabled in the repository (@pxref{config}), 6870@sc{cvs} will not change the permissions on any of the 6871@var{files}. The reason for this change is to ensure 6872that using @samp{cvs edit} does not interfere with the 6873ability to store file permissions in the @sc{cvs} 6874repository.} 6875@end ignore 6876 6877@end deffn 6878 6879Normally when you are done with a set of changes, you 6880use the @code{cvs commit} command, which checks in your 6881changes and returns the watched files to their usual 6882read-only state. But if you instead decide to abandon 6883your changes, or not to make any changes, you can use 6884the @code{cvs unedit} command. 6885 6886@cindex unedit (subcommand) 6887@cindex Abandoning work 6888@cindex Reverting to repository version 6889@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 6890 6891Abandon work on the working files @var{files}, and revert them to the 6892repository versions on which they are based. @sc{cvs} makes those 6893@var{files} read-only for which users have requested notification using 6894@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 6895notification for any of @var{files}. 6896 6897The @var{files} and options are processed as for the 6898@code{cvs watch} commands. 6899 6900If watches are not in use, the @code{unedit} command 6901probably does not work, and the way to revert to the 6902repository version is with the command @code{cvs update -C file} 6903(@pxref{update}). 6904The meaning is 6905not precisely the same; the latter may also 6906bring in some changes which have been made in the 6907repository since the last time you updated. 6908@c It would be a useful enhancement to CVS to make 6909@c unedit work in the non-watch case as well. 6910@end deffn 6911 6912When using client/server @sc{cvs}, you can use the 6913@code{cvs edit} and @code{cvs unedit} commands even if 6914@sc{cvs} is unable to successfully communicate with the 6915server; the notifications will be sent upon the next 6916successful @sc{cvs} command. 6917 6918@node Watch information 6919@subsection Information about who is watching and editing 6920 6921@cindex watchers (subcommand) 6922@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 6923 6924List the users currently watching changes to @var{files}. The report 6925includes the files being watched, and the mail address of each watcher. 6926 6927The @var{files} and options are processed as for the 6928@code{cvs watch} commands. 6929 6930@end deffn 6931 6932 6933@cindex editors (subcommand) 6934@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 6935 6936List the users currently working on @var{files}. The report 6937includes the mail address of each user, the time when the user began 6938working with the file, and the host and path of the working directory 6939containing the file. 6940 6941The @var{files} and options are processed as for the 6942@code{cvs watch} commands. 6943 6944@end deffn 6945 6946@node Watches Compatibility 6947@subsection Using watches with old versions of CVS 6948 6949@cindex CVS 1.6, and watches 6950If you use the watch features on a repository, it 6951creates @file{CVS} directories in the repository and 6952stores the information about watches in that directory. 6953If you attempt to use @sc{cvs} 1.6 or earlier with the 6954repository, you get an error message such as the 6955following (all on one line): 6956 6957@example 6958cvs update: cannot open CVS/Entries for reading: 6959No such file or directory 6960@end example 6961 6962@noindent 6963and your operation will likely be aborted. To use the 6964watch features, you must upgrade all copies of @sc{cvs} 6965which use that repository in local or server mode. If 6966you cannot upgrade, use the @code{watch off} and 6967@code{watch remove} commands to remove all watches, and 6968that will restore the repository to a state which 6969@sc{cvs} 1.6 can cope with. 6970 6971@node Choosing a model 6972@section Choosing between reserved or unreserved checkouts 6973@cindex Choosing, reserved or unreserved checkouts 6974 6975Reserved and unreserved checkouts each have pros and 6976cons. Let it be said that a lot of this is a matter of 6977opinion or what works given different groups' working 6978styles, but here is a brief description of some of the 6979issues. There are many ways to organize a team of 6980developers. @sc{cvs} does not try to enforce a certain 6981organization. It is a tool that can be used in several 6982ways. 6983 6984Reserved checkouts can be very counter-productive. If 6985two persons want to edit different parts of a file, 6986there may be no reason to prevent either of them from 6987doing so. Also, it is common for someone to take out a 6988lock on a file, because they are planning to edit it, 6989but then forget to release the lock. 6990 6991@c "many groups"? specifics? cites to papers on this? 6992@c some way to weasel-word it a bit more so we don't 6993@c need facts :-)? 6994People, especially people who are familiar with 6995reserved checkouts, often wonder how often conflicts 6996occur if unreserved checkouts are used, and how 6997difficult they are to resolve. The experience with 6998many groups is that they occur rarely and usually are 6999relatively straightforward to resolve. 7000 7001The rarity of serious conflicts may be surprising, until one realizes 7002that they occur only when two developers disagree on the proper design 7003for a given section of code; such a disagreement suggests that the 7004team has not been communicating properly in the first place. In order 7005to collaborate under @emph{any} source management regimen, developers 7006must agree on the general design of the system; given this agreement, 7007overlapping changes are usually straightforward to merge. 7008 7009In some cases unreserved checkouts are clearly 7010inappropriate. If no merge tool exists for the kind of 7011file you are managing (for example word processor files 7012or files edited by Computer Aided Design programs), and 7013it is not desirable to change to a program which uses a 7014mergeable data format, then resolving conflicts is 7015going to be unpleasant enough that you generally will 7016be better off to simply avoid the conflicts instead, by 7017using reserved checkouts. 7018 7019The watches features described above in @ref{Watches} 7020can be considered to be an intermediate model between 7021reserved checkouts and unreserved checkouts. When you 7022go to edit a file, it is possible to find out who else 7023is editing it. And rather than having the system 7024simply forbid both people editing the file, it can tell 7025you what the situation is and let you figure out 7026whether it is a problem in that particular case or not. 7027Therefore, for some groups watches can be 7028considered the best of both the reserved checkout and unreserved 7029checkout worlds. 7030 7031As of @sc{cvs} client and server versions 1.12.10, you may also enable 7032advisory locks by putting @samp{edit -c} and @samp{commit -c} in all 7033developers' @file{.cvsrc} files. After this is done, @code{cvs edit} 7034will fail if there are any other editors, and @code{cvs commit} will 7035fail if the committer has not registered to edit the file via @code{cvs edit}. 7036This is most effective in conjunction with files checked out read-only by 7037default, which may be enabled by turning on watches in the repository or by 7038putting @samp{cvs -r} in all @file{.cvsrc} files. 7039 7040 7041@c --------------------------------------------------------------------- 7042@node Revision management 7043@chapter Revision management 7044@cindex Revision management 7045 7046@c -- This chapter could be expanded a lot. 7047@c -- Experiences are very welcome! 7048 7049If you have read this far, you probably have a pretty 7050good grasp on what @sc{cvs} can do for you. This 7051chapter talks a little about things that you still have 7052to decide. 7053 7054If you are doing development on your own using @sc{cvs} 7055you could probably skip this chapter. The questions 7056this chapter takes up become more important when more 7057than one person is working in a repository. 7058 7059@menu 7060* When to commit:: Some discussion on the subject 7061@end menu 7062 7063@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7064@node When to commit 7065@section When to commit? 7066@cindex When to commit 7067@cindex Committing, when to 7068@cindex Policy 7069 7070Your group should decide which policy to use regarding 7071commits. Several policies are possible, and as your 7072experience with @sc{cvs} grows you will probably find 7073out what works for you. 7074 7075If you commit files too quickly you might commit files 7076that do not even compile. If your partner updates his 7077working sources to include your buggy file, he will be 7078unable to compile the code. On the other hand, other 7079persons will not be able to benefit from the 7080improvements you make to the code if you commit very 7081seldom, and conflicts will probably be more common. 7082 7083It is common to only commit files after making sure 7084that they can be compiled. Some sites require that the 7085files pass a test suite. Policies like this can be 7086enforced using the commitinfo file 7087(@pxref{commitinfo}), but you should think twice before 7088you enforce such a convention. By making the 7089development environment too controlled it might become 7090too regimented and thus counter-productive to the real 7091goal, which is to get software written. 7092 7093@c --------------------------------------------------------------------- 7094@node Keyword substitution 7095@chapter Keyword substitution 7096@cindex Keyword substitution 7097@cindex Keyword expansion 7098@cindex Identifying files 7099 7100@comment Be careful when editing this chapter. 7101@comment Remember that this file is kept under 7102@comment version control, so we must not accidentally 7103@comment include a valid keyword in the running text. 7104 7105As long as you edit source files inside a working 7106directory you can always find out the state of 7107your files via @samp{cvs status} and @samp{cvs log}. 7108But as soon as you export the files from your 7109development environment it becomes harder to identify 7110which revisions they are. 7111 7112@sc{cvs} can use a mechanism known as @dfn{keyword 7113substitution} (or @dfn{keyword expansion}) to help 7114identifying the files. Embedded strings of the form 7115@code{$@var{keyword}$} and 7116@code{$@var{keyword}:@dots{}$} in a file are replaced 7117with strings of the form 7118@code{$@var{keyword}:@var{value}$} whenever you obtain 7119a new revision of the file. 7120 7121@menu 7122* Keyword list:: Keywords 7123* Using keywords:: Using keywords 7124* Avoiding substitution:: Avoiding substitution 7125* Substitution modes:: Substitution modes 7126* Configuring keyword expansion:: Configuring keyword expansion 7127* Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. 7128@end menu 7129 7130@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7131@node Keyword list 7132@section Keyword List 7133@cindex Keyword List 7134 7135@c FIXME: need some kind of example here I think, 7136@c perhaps in a 7137@c "Keyword intro" node. The intro in the "Keyword 7138@c substitution" node itself seems OK, but to launch 7139@c into a list of the keywords somehow seems too abrupt. 7140 7141This is a list of the keywords: 7142 7143@table @code 7144@cindex Author keyword 7145@item $@splitrcskeyword{Author}$ 7146The login name of the user who checked in the revision. 7147 7148@cindex CVSHeader keyword 7149@item $@splitrcskeyword{CVSHeader}$ 7150A standard header (similar to $@splitrcskeyword{Header}$, but with 7151the CVS root stripped off). It contains the relative 7152pathname of the @sc{rcs} file to the CVS root, the 7153revision number, the date (UTC), the author, the state, 7154and the locker (if locked). Files will normally never 7155be locked when you use @sc{cvs}. 7156 7157Note that this keyword has only been recently 7158introduced to @sc{cvs} and may cause problems with 7159existing installations if $@splitrcskeyword{CVSHeader}$ is already 7160in the files for a different purpose. This keyword may 7161be excluded using the @code{KeywordExpand=eCVSHeader} 7162in the @file{CVSROOT/config} file. 7163See @ref{Configuring keyword expansion} for more details. 7164 7165@cindex Date keyword 7166@item $@splitrcskeyword{Date}$ 7167The date and time (UTC) the revision was checked in. 7168 7169@cindex Header keyword 7170@item $@splitrcskeyword{Header}$ 7171A standard header containing the full pathname of the 7172@sc{rcs} file, the revision number, the date (UTC), the 7173author, the state, and the locker (if locked). Files 7174will normally never be locked when you use @sc{cvs}. 7175 7176@cindex Id keyword 7177@item $@splitrcskeyword{Id}$ 7178Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} 7179filename is without a path. 7180 7181@cindex Name keyword 7182@item $@splitrcskeyword{Name}$ 7183Tag name used to check out this file. The keyword is 7184expanded only if one checks out with an explicit tag 7185name. For example, when running the command @code{cvs 7186co -r first}, the keyword expands to @samp{Name: first}. 7187 7188@cindex Locker keyword 7189@item $@splitrcskeyword{Locker}$ 7190The login name of the user who locked the revision 7191(empty if not locked, which is the normal case unless 7192@code{cvs admin -l} is in use). 7193 7194@cindex Log keyword 7195@cindex MaxCommentLeaderLength 7196@cindex UseArchiveCommentLeader 7197@cindex Log keyword, configuring substitution behavior 7198@item $@splitrcskeyword{Log}$ 7199The log message supplied during commit, preceded by a 7200header containing the @sc{rcs} filename, the revision 7201number, the author, and the date (UTC). Existing log 7202messages are @emph{not} replaced. Instead, the new log 7203message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}. 7204By default, each new line is prefixed with the same string which 7205precedes the @code{$@splitrcskeyword{Log}$} keyword, unless it exceeds the 7206@code{MaxCommentLeaderLength} set in @file{CVSROOT/config}. 7207 7208For example, if the file contains: 7209 7210@example 7211 /* Here is what people have been up to: 7212 * 7213 * $@splitrcskeyword{Log}: frob.c,v $ 7214 * Revision 1.1 1997/01/03 14:23:51 joe 7215 * Add the superfrobnicate option 7216 * 7217 */ 7218@end example 7219 7220@noindent 7221then additional lines which are added when expanding 7222the @code{$@splitrcskeyword{Log}$} keyword will be preceded by @samp{ * }. 7223Unlike previous versions of @sc{cvs} and @sc{rcs}, the 7224@dfn{comment leader} from the @sc{rcs} file is not used. 7225The @code{$@splitrcskeyword{Log}$} keyword is useful for 7226accumulating a complete change log in a source file, 7227but for several reasons it can be problematic. 7228 7229If the prefix of the @code{$@splitrcskeyword{Log}$} keyword turns out to be 7230longer than @code{MaxCommentLeaderLength}, CVS will skip expansion of this 7231keyword unless @code{UseArchiveCommentLeader} is also set in 7232@file{CVSROOT/config} and a @samp{comment leader} is set in the RCS archive 7233file, in which case the comment leader will be used instead. For more on 7234setting the comment leader in the RCS archive file, @xref{admin}. For more 7235on configuring the default @code{$@splitrcskeyword{Log}$} substitution 7236behavior, @xref{config}. 7237 7238@xref{Log keyword}. 7239 7240@cindex RCSfile keyword 7241@item $@splitrcskeyword{RCSfile}$ 7242The name of the RCS file without a path. 7243 7244@cindex Revision keyword 7245@item $@splitrcskeyword{Revision}$ 7246The revision number assigned to the revision. 7247 7248@cindex Source keyword 7249@item $@splitrcskeyword{Source}$ 7250The full pathname of the RCS file. 7251 7252@cindex State keyword 7253@item $@splitrcskeyword{State}$ 7254The state assigned to the revision. States can be 7255assigned with @code{cvs admin -s}---see @ref{admin options}. 7256 7257@cindex Local keyword 7258@item Local keyword 7259The @code{LocalKeyword} option in the @file{CVSROOT/config} file 7260may be used to specify a local keyword which is to be 7261used as an alias for one of the keywords: $@splitrcskeyword{Id}$, 7262$@splitrcskeyword{Header}$, or $@splitrcskeyword{CVSHeader}$. For 7263example, if the @file{CVSROOT/config} file contains 7264a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a 7265file with the local keyword $@splitrcskeyword{MYBSD}$ will be 7266expanded as if it were a $@splitrcskeyword{CVSHeader}$ keyword. If 7267the src/frob.c file contained this keyword, it might 7268look something like this: 7269 7270@example 7271 /* 7272 * $@splitrcskeyword{MYBSD}: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 7273 */ 7274@end example 7275 7276Many repositories make use of a such a ``local 7277keyword'' feature. An old patch to @sc{cvs} provided 7278the @code{LocalKeyword} feature using a @code{tag=} 7279option and called this the ``custom tag'' or ``local 7280tag'' feature. It was used in conjunction with the 7281what they called the @code{tagexpand=} option. In 7282@sc{cvs} this other option is known as the 7283@code{KeywordExpand} option. 7284See @ref{Configuring keyword expansion} for more 7285details. 7286 7287Examples from popular projects include: 7288$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7289$@splitrcskeyword{OpenBSD}$, $@splitrcskeyword{XFree86}$, 7290$@splitrcskeyword{Xorg}$. 7291 7292The advantage of this is that you can include your 7293local version information in a file using this local 7294keyword without disrupting the upstream version 7295information (which may be a different local keyword or 7296a standard keyword). Allowing bug reports and the like 7297to more properly identify the source of the original 7298bug to the third-party and reducing the number of 7299conflicts that arise during an import of a new version. 7300 7301All keyword expansion except the local keyword may be 7302disabled using the @code{KeywordExpand} option in 7303the @file{CVSROOT/config} file---see 7304@ref{Configuring keyword expansion} for more details. 7305 7306@end table 7307 7308@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7309@node Using keywords 7310@section Using keywords 7311 7312To include a keyword string you simply include the 7313relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the 7314file, and commit the file. @sc{cvs} will automatically (Or, 7315more accurately, as part of the update run that 7316automatically happens after a commit.) 7317expand the string as part of the commit operation. 7318 7319It is common to embed the @code{$@splitrcskeyword{Id}$} string in 7320the source files so that it gets passed through to 7321generated files. For example, if you are managing 7322computer program source code, you might include a 7323variable which is initialized to contain that string. 7324Or some C compilers may provide a @code{#pragma ident} 7325directive. Or a document management system might 7326provide a way to pass a string through to generated 7327files. 7328 7329@c Would be nice to give an example, but doing this in 7330@c portable C is not possible and the problem with 7331@c picking any one language (VMS HELP files, Ada, 7332@c troff, whatever) is that people use CVS for all 7333@c kinds of files. 7334 7335@cindex Ident (shell command) 7336The @code{ident} command (which is part of the @sc{rcs} 7337package) can be used to extract keywords and their 7338values from a file. This can be handy for text files, 7339but it is even more useful for extracting keywords from 7340binary files. 7341 7342@example 7343$ ident samp.c 7344samp.c: 7345 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7346$ gcc samp.c 7347$ ident a.out 7348a.out: 7349 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7350@end example 7351 7352@cindex What (shell command) 7353S@sc{ccs} is another popular revision control system. 7354It has a command, @code{what}, which is very similar to 7355@code{ident} and used for the same purpose. Many sites 7356without @sc{rcs} have @sc{sccs}. Since @code{what} 7357looks for the character sequence @code{@@(#)} it is 7358easy to include keywords that are detected by either 7359command. Simply prefix the keyword with the 7360magic @sc{sccs} phrase, like this: 7361 7362@example 7363static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 7364@end example 7365 7366@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7367@node Avoiding substitution 7368@section Avoiding substitution 7369 7370Keyword substitution has its disadvantages. Sometimes 7371you might want the literal text string 7372@samp{$@splitrcskeyword{Author}$} to appear inside a file without 7373@sc{cvs} interpreting it as a keyword and expanding it 7374into something like @samp{$@splitrcskeyword{Author}: ceder $}. 7375 7376There is unfortunately no way to selectively turn off 7377keyword substitution. You can use @samp{-ko} 7378(@pxref{Substitution modes}) to turn off keyword 7379substitution entirely. 7380 7381In many cases you can avoid using keywords in 7382the source, even though they appear in the final 7383product. For example, the source for this manual 7384contains @samp{$@@asis@{@}Author$} whenever the text 7385@samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff} 7386and @code{troff} you can embed the null-character 7387@code{\&} inside the keyword for a similar effect. 7388 7389It is also possible to specify an explicit list of 7390keywords to include or exclude using the 7391@code{KeywordExpand} option in the 7392@file{CVSROOT/config} file--see @ref{Configuring keyword expansion} 7393for more details. This feature is intended primarily 7394for use with the @code{LocalKeyword} option--see 7395@ref{Keyword list}. 7396 7397@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7398@node Substitution modes 7399@section Substitution modes 7400@cindex Keyword substitution, changing modes 7401@cindex -k (keyword substitution) 7402@cindex Kflag 7403 7404@c FIXME: This could be made more coherent, by expanding it 7405@c with more examples or something. 7406Each file has a stored default substitution mode, and 7407each working directory copy of a file also has a 7408substitution mode. The former is set by the @samp{-k} 7409option to @code{cvs add} and @code{cvs admin}; the 7410latter is set by the @samp{-k} or @samp{-A} options to @code{cvs 7411checkout} or @code{cvs update}. 7412@code{cvs diff} and @code{cvs rdiff} also 7413have @samp{-k} options. 7414For some examples, 7415see @ref{Binary files}, and @ref{Merging and keywords}. 7416@c The fact that -A is overloaded to mean both reset 7417@c sticky options and reset sticky tags/dates is 7418@c somewhat questionable. Perhaps there should be 7419@c separate options to reset sticky options (e.g. -k 7420@c A") and tags/dates (someone suggested -r HEAD could 7421@c do this instead of setting a sticky tag of "HEAD" 7422@c as in the status quo but I haven't thought much 7423@c about that idea. Of course -r .reset or something 7424@c could be coined if this needs to be a new option). 7425@c On the other hand, having -A mean "get things back 7426@c into the state after a fresh checkout" has a certain 7427@c appeal, and maybe there is no sufficient reason for 7428@c creeping featurism in this area. 7429 7430The modes available are: 7431 7432@table @samp 7433@item -kkv 7434Generate keyword strings using the default form, e.g. 7435@code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision} 7436keyword. 7437 7438@item -kkvl 7439Like @samp{-kkv}, except that a locker's name is always 7440inserted if the given revision is currently locked. 7441The locker's name is only relevant if @code{cvs admin 7442-l} is in use. 7443 7444@item -kk 7445Generate only keyword names in keyword strings; omit 7446their values. For example, for the @code{Revision} 7447keyword, generate the string @code{$@splitrcskeyword{Revision}$} 7448instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option 7449is useful to ignore differences due to keyword 7450substitution when comparing different revisions of a 7451file (@pxref{Merging and keywords}). 7452 7453@item -ko 7454Generate the old keyword string, present in the working 7455file just before it was checked in. For example, for 7456the @code{Revision} keyword, generate the string 7457@code{$@splitrcskeyword{Revision}: 1.1 $} instead of 7458@code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the 7459string appeared when the file was checked in. 7460 7461@item -kb 7462Like @samp{-ko}, but also inhibit conversion of line 7463endings between the canonical form in which they are 7464stored in the repository (linefeed only), and the form 7465appropriate to the operating system in use on the 7466client. For systems, like unix, which use linefeed 7467only to terminate lines, this is very similar to 7468@samp{-ko}. For more information on binary files, see 7469@ref{Binary files}. In @sc{cvs} version 1.12.2 and later 7470@samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or 7471@code{cvs import} may not be overridden by a @samp{-k} option 7472specified on the command line. 7473 7474@item -kv 7475Generate only keyword values for keyword strings. For 7476example, for the @code{Revision} keyword, generate the string 7477@code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. 7478This can help generate files in programming languages 7479where it is hard to strip keyword delimiters like 7480@code{$@splitrcskeyword{Revision}: $} from a string. However, 7481further keyword substitution cannot be performed once 7482the keyword names are removed, so this option should be 7483used with care. 7484 7485One often would like to use @samp{-kv} with @code{cvs 7486export}---@pxref{export}. But be aware that doesn't 7487handle an export containing binary files correctly. 7488 7489@end table 7490 7491@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7492@node Configuring keyword expansion 7493@section Configuring Keyword Expansion 7494@cindex Configuring keyword expansion 7495 7496In a repository that includes third-party software on 7497vendor branches, it is sometimes helpful to configure 7498CVS to use a local keyword instead of the standard 7499$@splitrcskeyword{Id}$ or $@splitrcskeyword{Header}$ keywords. Examples from 7500real projects include $@splitrcskeyword{Xorg}$, $@splitrcskeyword{XFree86}$, 7501$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7502$@splitrcskeyword{OpenBSD}$, and even $@splitrcskeyword{dotat}$. 7503The advantage of this is that 7504you can include your local version information in a 7505file using this local keyword (sometimes called a 7506``custom tag'' or a ``local tag'') without disrupting 7507the upstream version information (which may be a 7508different local keyword or a standard keyword). In 7509these cases, it is typically desirable to disable the 7510expansion of all keywords except the configured local 7511keyword. 7512 7513The @code{KeywordExpand} option in the 7514@file{CVSROOT/config} file is intended to allow for the 7515either the explicit exclusion of a keyword or list of 7516keywords, or for the explicit inclusion of a keyword or 7517a list of keywords. This list may include the 7518@code{LocalKeyword} that has been configured. 7519 7520The @code{KeywordExpand} option is followed by 7521@code{=} and the next character may either be @code{i} 7522to start an inclusion list or @code{e} to start an 7523exclusion list. If the following lines were added to 7524the @file{CVSROOT/config} file: 7525 7526@example 7527 # Add a "MyBSD" keyword and restrict keyword 7528 # expansion 7529 LocalKeyword=MyBSD=CVSHeader 7530 KeywordExpand=iMyBSD 7531@end example 7532 7533then only the $@splitrcskeyword{MyBSD}$ keyword would be expanded. 7534A list may be used. The this example: 7535 7536@example 7537 # Add a "MyBSD" keyword and restrict keyword 7538 # expansion to the MyBSD, Name and Date keywords. 7539 LocalKeyword=MyBSD=CVSHeader 7540 KeywordExpand=iMyBSD,Name,Date 7541@end example 7542 7543would allow $@splitrcskeyword{MyBSD}$, $@splitrcskeyword{Name}$, and 7544$@splitrcskeyword{Date}$ to be expanded. 7545 7546It is also possible to configure an exclusion list 7547using the following: 7548 7549@example 7550 # Do not expand the non-RCS keyword CVSHeader 7551 KeywordExpand=eCVSHeader 7552@end example 7553 7554This allows @sc{cvs} to ignore the recently introduced 7555$@splitrcskeyword{CVSHeader}$ keyword and retain all of the 7556others. The exclusion entry could also contain the 7557standard RCS keyword list, but this could be confusing 7558to users that expect RCS keywords to be expanded, so 7559care should be taken to properly set user expectations 7560for a repository that is configured in that manner. 7561 7562If there is a desire to not have any RCS keywords 7563expanded and not use the @code{-ko} flags everywhere, 7564an administrator may disable all keyword expansion 7565using the @file{CVSROOT/config} line: 7566 7567@example 7568 # Do not expand any RCS keywords 7569 KeywordExpand=i 7570@end example 7571 7572this could be confusing to users that expect RCS 7573keywords like $@splitrcskeyword{Id}$ to be expanded properly, 7574so care should be taken to properly set user 7575expectations for a repository so configured. 7576 7577It should be noted that a patch to provide both the 7578@code{KeywordExpand} and @code{LocalKeyword} features 7579has been around a long time. However, that patch 7580implemented these features using @code{tag=} and 7581@code{tagexpand=} keywords and those keywords are NOT 7582recognized. 7583 7584@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7585@node Log keyword 7586@section Problems with the $@splitrcskeyword{Log}$ keyword. 7587 7588The @code{$@splitrcskeyword{Log}$} keyword is somewhat 7589controversial. As long as you are working on your 7590development system the information is easily accessible 7591even if you do not use the @code{$@splitrcskeyword{Log}$} 7592keyword---just do a @code{cvs log}. Once you export 7593the file the history information might be useless 7594anyhow. 7595 7596A more serious concern is that @sc{cvs} is not good at 7597handling @code{$@splitrcskeyword{Log}$} entries when a branch is 7598merged onto the main trunk. Conflicts often result 7599from the merging operation. 7600@c Might want to check whether the CVS implementation 7601@c of RCS_merge has this problem the same way rcsmerge 7602@c does. I would assume so.... 7603 7604People also tend to "fix" the log entries in the file 7605(correcting spelling mistakes and maybe even factual 7606errors). If that is done the information from 7607@code{cvs log} will not be consistent with the 7608information inside the file. This may or may not be a 7609problem in real life. 7610 7611It has been suggested that the @code{$@splitrcskeyword{Log}$} 7612keyword should be inserted @emph{last} in the file, and 7613not in the files header, if it is to be used at all. 7614That way the long list of change messages will not 7615interfere with everyday source file browsing. 7616 7617@c --------------------------------------------------------------------- 7618@node Tracking sources 7619@chapter Tracking third-party sources 7620@cindex Third-party sources 7621@cindex Tracking sources 7622 7623@c FIXME: Need discussion of added and removed files. 7624@c FIXME: This doesn't really adequately introduce the 7625@c concepts of "vendor" and "you". They don't *have* 7626@c to be separate organizations or separate people. 7627@c We want a description which is somewhat more based on 7628@c the technical issues of which sources go where, but 7629@c also with enough examples of how this relates to 7630@c relationships like customer-supplier, developer-QA, 7631@c maintainer-contributor, or whatever, to make it 7632@c seem concrete. 7633If you modify a program to better fit your site, you 7634probably want to include your modifications when the next 7635release of the program arrives. @sc{cvs} can help you with 7636this task. 7637 7638@cindex Vendor 7639@cindex Vendor branch 7640@cindex Branch, vendor- 7641In the terminology used in @sc{cvs}, the supplier of the 7642program is called a @dfn{vendor}. The unmodified 7643distribution from the vendor is checked in on its own 7644branch, the @dfn{vendor branch}. @sc{cvs} reserves branch 76451.1.1 for this use. 7646 7647When you modify the source and commit it, your revision 7648will end up on the main trunk. When a new release is 7649made by the vendor, you commit it on the vendor branch 7650and copy the modifications onto the main trunk. 7651 7652Use the @code{import} command to create and update 7653the vendor branch. When you import a new file, 7654(usually) the vendor branch is made the `head' revision, so 7655anyone that checks out a copy of the file gets that 7656revision. When a local modification is committed it is 7657placed on the main trunk, and made the `head' 7658revision. 7659 7660@menu 7661* First import:: Importing for the first time 7662* Update imports:: Updating with the import command 7663* Reverting local changes:: Reverting to the latest vendor release 7664* Binary files in imports:: Binary files require special handling 7665* Keywords in imports:: Keyword substitution might be undesirable 7666* Multiple vendor branches:: What if you get sources from several places? 7667@end menu 7668 7669@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7670@node First import 7671@section Importing for the first time 7672@cindex Importing modules 7673 7674@c Should mention naming conventions for vendor tags, 7675@c release tags, and perhaps directory names. 7676Use the @code{import} command to check in the sources 7677for the first time. When you use the @code{import} 7678command to track third-party sources, the @dfn{vendor 7679tag} and @dfn{release tags} are useful. The 7680@dfn{vendor tag} is a symbolic name for the branch 7681(which is always 1.1.1, unless you use the @samp{-b 7682@var{branch}} flag---see @ref{Multiple vendor branches}.). The 7683@dfn{release tags} are symbolic names for a particular 7684release, such as @samp{FSF_0_04}. 7685 7686@c I'm not completely sure this belongs here. But 7687@c we need to say it _somewhere_ reasonably obvious; it 7688@c is a common misconception among people first learning CVS 7689Note that @code{import} does @emph{not} change the 7690directory in which you invoke it. In particular, it 7691does not set up that directory as a @sc{cvs} working 7692directory; if you want to work with the sources import 7693them first and then check them out into a different 7694directory (@pxref{Getting the source}). 7695 7696@cindex wdiff (import example) 7697Suppose you have the sources to a program called 7698@code{wdiff} in a directory @file{wdiff-0.04}, 7699and are going to make private modifications that you 7700want to be able to use even when new releases are made 7701in the future. You start by importing the source to 7702your repository: 7703 7704@example 7705$ cd wdiff-0.04 7706$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 7707@end example 7708 7709The vendor tag is named @samp{FSF_DIST} in the above 7710example, and the only release tag assigned is 7711@samp{WDIFF_0_04}. 7712@c FIXME: Need to say where fsf/wdiff comes from. 7713 7714@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7715@node Update imports 7716@section Updating with the import command 7717 7718When a new release of the source arrives, you import it into the 7719repository with the same @code{import} command that you used to set up 7720the repository in the first place. The only difference is that you 7721specify a different release tag this time: 7722 7723@example 7724$ tar xfz wdiff-0.05.tar.gz 7725$ cd wdiff-0.05 7726$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 7727@end example 7728 7729@strong{WARNING: If you use a release tag that already exists in one of the 7730repository archives, files removed by an import may not be detected.} 7731 7732For files that have not been modified locally, the newly created 7733revision becomes the head revision. If you have made local 7734changes, @code{import} will warn you that you must merge the changes 7735into the main trunk, and tell you to use @samp{checkout -j} to do so: 7736 7737@c FIXME: why "wdiff" here and "fsf/wdiff" in the 7738@c "import"? I think the assumption is that one has 7739@c "wdiff fsf/wdiff" or some such in modules, but it 7740@c would be better to not use modules in this example. 7741@example 7742$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 7743@end example 7744 7745@noindent 7746The above command will check out the latest revision of 7747@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 7748since yesterday into the working copy. If any conflicts arise during 7749the merge they should be resolved in the normal way (@pxref{Conflicts 7750example}). Then, the modified files may be committed. 7751 7752However, it is much better to use the two release tags rather than using 7753a date on the branch as suggested above: 7754 7755@example 7756$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 7757@end example 7758 7759@noindent 7760The reason this is better is that 7761using a date, as suggested above, assumes that you do 7762not import more than one release of a product per day. 7763More importantly, using the release tags allows @sc{cvs} to detect files 7764that were removed between the two vendor releases and mark them for 7765removal. Since @code{import} has no way to detect removed files, you 7766should do a merge like this even if @code{import} doesn't tell you to. 7767 7768@node Reverting local changes 7769@section Reverting to the latest vendor release 7770 7771You can also revert local changes completely and return 7772to the latest vendor release by changing the `head' 7773revision back to the vendor branch on all files. For 7774example, if you have a checked-out copy of the sources 7775in @file{~/work.d/wdiff}, and you want to revert to the 7776vendor's version for all the files in that directory, 7777you would type: 7778 7779@example 7780$ cd ~/work.d/wdiff 7781$ cvs admin -bFSF_DIST . 7782@end example 7783 7784@noindent 7785You must specify the @samp{-bFSF_DIST} without any space 7786after the @samp{-b}. @xref{admin options}. 7787 7788@node Binary files in imports 7789@section How to handle binary files with cvs import 7790 7791Use the @samp{-k} wrapper option to tell import which 7792files are binary. @xref{Wrappers}. 7793 7794@node Keywords in imports 7795@section How to handle keyword substitution with cvs import 7796 7797The sources which you are importing may contain 7798keywords (@pxref{Keyword substitution}). For example, 7799the vendor may use @sc{cvs} or some other system 7800which uses similar keyword expansion syntax. If you 7801just import the files in the default fashion, then 7802the keyword expansions supplied by the vendor will 7803be replaced by keyword expansions supplied by your 7804own copy of @sc{cvs}. It may be more convenient to 7805maintain the expansions supplied by the vendor, so 7806that this information can supply information about 7807the sources that you imported from the vendor. 7808 7809To maintain the keyword expansions supplied by the 7810vendor, supply the @samp{-ko} option to @code{cvs 7811import} the first time you import the file. 7812This will turn off keyword expansion 7813for that file entirely, so if you want to be more 7814selective you'll have to think about what you want 7815and use the @samp{-k} option to @code{cvs update} or 7816@code{cvs admin} as appropriate. 7817@c Supplying -ko to import if the file already existed 7818@c has no effect. Not clear to me whether it should 7819@c or not. 7820 7821@node Multiple vendor branches 7822@section Multiple vendor branches 7823 7824All the examples so far assume that there is only one 7825vendor from which you are getting sources. In some 7826situations you might get sources from a variety of 7827places. For example, suppose that you are dealing with 7828a project where many different people and teams are 7829modifying the software. There are a variety of ways to 7830handle this, but in some cases you have a bunch of 7831source trees lying around and what you want to do more 7832than anything else is just to all put them in @sc{cvs} so 7833that you at least have them in one place. 7834 7835For handling situations in which there may be more than 7836one vendor, you may specify the @samp{-b} option to 7837@code{cvs import}. It takes as an argument the vendor 7838branch to import to. The default is @samp{-b 1.1.1}. 7839 7840For example, suppose that there are two teams, the red 7841team and the blue team, that are sending you sources. 7842You want to import the red team's efforts to branch 78431.1.1 and use the vendor tag RED. You want to import 7844the blue team's efforts to branch 1.1.3 and use the 7845vendor tag BLUE. So the commands you might use are: 7846 7847@example 7848$ cvs import dir RED RED_1-0 7849$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 7850@end example 7851 7852Note that if your vendor tag does not match your 7853@samp{-b} option, @sc{cvs} will not detect this case! For 7854example, 7855 7856@example 7857$ cvs import -b 1.1.3 dir RED RED_1-0 7858@end example 7859 7860@noindent 7861Be careful; this kind of mismatch is sure to sow 7862confusion or worse. I can't think of a useful purpose 7863for the ability to specify a mismatch here, but if you 7864discover such a use, don't. @sc{cvs} is likely to make this 7865an error in some future release. 7866 7867@c Probably should say more about the semantics of 7868@c multiple branches. What about the default branch? 7869@c What about joining (perhaps not as useful with 7870@c multiple branches, or perhaps it is. Either way 7871@c should be mentioned). 7872 7873@c I'm not sure about the best location for this. In 7874@c one sense, it might belong right after we've introduced 7875@c CVS's basic version control model, because people need 7876@c to figure out builds right away. The current location 7877@c is based on the theory that it kind of akin to the 7878@c "Revision management" section. 7879@node Builds 7880@chapter How your build system interacts with CVS 7881@cindex Builds 7882@cindex make 7883 7884As mentioned in the introduction, @sc{cvs} does not 7885contain software for building your software from source 7886code. This section describes how various aspects of 7887your build system might interact with @sc{cvs}. 7888 7889@c Is there a way to discuss this without reference to 7890@c tools other than CVS? I'm not sure there is; I 7891@c wouldn't think that people who learn CVS first would 7892@c even have this concern. 7893One common question, especially from people who are 7894accustomed to @sc{rcs}, is how to make their build get 7895an up to date copy of the sources. The answer to this 7896with @sc{cvs} is two-fold. First of all, since 7897@sc{cvs} itself can recurse through directories, there 7898is no need to modify your @file{Makefile} (or whatever 7899configuration file your build tool uses) to make sure 7900each file is up to date. Instead, just use two 7901commands, first @code{cvs -q update} and then 7902@code{make} or whatever the command is to invoke your 7903build tool. Secondly, you do not necessarily 7904@emph{want} to get a copy of a change someone else made 7905until you have finished your own work. One suggested 7906approach is to first update your sources, then 7907implement, build and 7908test the change you were thinking of, and then commit 7909your sources (updating first if necessary). By 7910periodically (in between changes, using the approach 7911just described) updating your entire tree, you ensure 7912that your sources are sufficiently up to date. 7913 7914@cindex Bill of materials 7915One common need is to record which versions of which 7916source files went into a particular build. This kind 7917of functionality is sometimes called @dfn{bill of 7918materials} or something similar. The best way to do 7919this with @sc{cvs} is to use the @code{tag} command to 7920record which versions went into a given build 7921(@pxref{Tags}). 7922 7923Using @sc{cvs} in the most straightforward manner 7924possible, each developer will have a copy of the entire 7925source tree which is used in a particular build. If 7926the source tree is small, or if developers are 7927geographically dispersed, this is the preferred 7928solution. In fact one approach for larger projects is 7929to break a project down into smaller 7930@c I say subsystem instead of module because they may or 7931@c may not use the modules file. 7932separately-compiled subsystems, and arrange a way of 7933releasing them internally so that each developer need 7934check out only those subsystems which they are 7935actively working on. 7936 7937Another approach is to set up a structure which allows 7938developers to have their own copies of some files, and 7939for other files to access source files from a central 7940location. Many people have come up with some such a 7941@c two such people are paul@sander.cupertino.ca.us (for 7942@c a previous employer) 7943@c and gunnar.tornblom@se.abb.com (spicm and related tools), 7944@c but as far as I know 7945@c no one has nicely packaged or released such a system (or 7946@c instructions for constructing one). 7947system using features such as the symbolic link feature 7948found in many operating systems, or the @code{VPATH} 7949feature found in many versions of @code{make}. One build 7950tool which is designed to help with this kind of thing 7951is Odin (see 7952@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 7953@c Should we be saying more about Odin? Or how you use 7954@c it with CVS? Also, the Prime Time Freeware for Unix 7955@c disk (see http://www.ptf.com/) has Odin (with a nice 7956@c paragraph summarizing it on the web), so that might be a 7957@c semi-"official" place to point people. 7958@c 7959@c Of course, many non-CVS systems have this kind of 7960@c functionality, for example OSF's ODE 7961@c (http://www.osf.org/ode/) or mk 7962@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 7963@c He has changed providers in the past; a search engine search 7964@c for "Peter Ziobrzynski" probably won't get too many 7965@c spurious hits :-). A more stable URL might be 7966@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 7967@c there is any point in mentioning them here unless they 7968@c can work with CVS. 7969 7970@c --------------------------------------------------------------------- 7971@node Special Files 7972@chapter Special Files 7973 7974@cindex Special files 7975@cindex Device nodes 7976@cindex Ownership, saving in CVS 7977@cindex Permissions, saving in CVS 7978@cindex Hard links 7979@cindex Symbolic links 7980 7981In normal circumstances, @sc{cvs} works only with regular 7982files. Every file in a project is assumed to be 7983persistent; it must be possible to open, read and close 7984them; and so on. @sc{cvs} also ignores file permissions and 7985ownerships, leaving such issues to be resolved by the 7986developer at installation time. In other words, it is 7987not possible to "check in" a device into a repository; 7988if the device file cannot be opened, @sc{cvs} will refuse to 7989handle it. Files also lose their ownerships and 7990permissions during repository transactions. 7991 7992@ignore 7993If the configuration variable @code{PreservePermissions} 7994(@pxref{config}) is set in the repository, @sc{cvs} will 7995save the following file characteristics in the 7996repository: 7997 7998@itemize @bullet 7999@item user and group ownership 8000@item permissions 8001@item major and minor device numbers 8002@item symbolic links 8003@item hard link structure 8004@end itemize 8005 8006Using the @code{PreservePermissions} option affects the 8007behavior of @sc{cvs} in several ways. First, some of the 8008new operations supported by @sc{cvs} are not accessible to 8009all users. In particular, file ownership and special 8010file characteristics may only be changed by the 8011superuser. When the @code{PreservePermissions} 8012configuration variable is set, therefore, users will 8013have to be `root' in order to perform @sc{cvs} operations. 8014 8015When @code{PreservePermissions} is in use, some @sc{cvs} 8016operations (such as @samp{cvs status}) will not 8017recognize a file's hard link structure, and so will 8018emit spurious warnings about mismatching hard links. 8019The reason is that @sc{cvs}'s internal structure does not 8020make it easy for these operations to collect all the 8021necessary data about hard links, so they check for file 8022conflicts with inaccurate data. 8023 8024A more subtle difference is that @sc{cvs} considers a file 8025to have changed only if its contents have changed 8026(specifically, if the modification time of the working 8027file does not match that of the repository's file). 8028Therefore, if only the permissions, ownership or hard 8029linkage have changed, or if a device's major or minor 8030numbers have changed, @sc{cvs} will not notice. In order to 8031commit such a change to the repository, you must force 8032the commit with @samp{cvs commit -f}. This also means 8033that if a file's permissions have changed and the 8034repository file is newer than the working copy, 8035performing @samp{cvs update} will silently change the 8036permissions on the working copy. 8037 8038Changing hard links in a @sc{cvs} repository is particularly 8039delicate. Suppose that file @file{foo} is linked to 8040file @file{old}, but is later relinked to file 8041@file{new}. You can wind up in the unusual situation 8042where, although @file{foo}, @file{old} and @file{new} 8043have all had their underlying link patterns changed, 8044only @file{foo} and @file{new} have been modified, so 8045@file{old} is not considered a candidate for checking 8046in. It can be very easy to produce inconsistent 8047results this way. Therefore, we recommend that when it 8048is important to save hard links in a repository, the 8049prudent course of action is to @code{touch} any file 8050whose linkage or status has changed since the last 8051checkin. Indeed, it may be wise to @code{touch *} 8052before each commit in a directory with complex hard 8053link structures. 8054 8055It is worth noting that only regular files may 8056be merged, for reasons that hopefully are obvious. If 8057@samp{cvs update} or @samp{cvs checkout -j} attempts to 8058merge a symbolic link with a regular file, or two 8059device files for different kinds of devices, @sc{cvs} will 8060report a conflict and refuse to perform the merge. At 8061the same time, @samp{cvs diff} will not report any 8062differences between these files, since no meaningful 8063textual comparisons can be made on files which contain 8064no text. 8065 8066The @code{PreservePermissions} features do not work 8067with client/server @sc{cvs}. Another limitation is 8068that hard links must be to other files within the same 8069directory; hard links across directories are not 8070supported. 8071@end ignore 8072 8073@c --------------------------------------------------------------------- 8074@c ----- START MAN 1 ----- 8075@node CVS commands 8076@appendix Guide to CVS commands 8077 8078This appendix describes the overall structure of 8079@sc{cvs} commands, and describes some commands in 8080detail (others are described elsewhere; for a quick 8081reference to @sc{cvs} commands, @pxref{Invoking CVS}). 8082@c The idea is that we want to move the commands which 8083@c are described here into the main body of the manual, 8084@c in the process reorganizing the manual to be 8085@c organized around what the user wants to do, not 8086@c organized around CVS commands. 8087@c 8088@c Note that many users do expect a manual which is 8089@c organized by command. At least some users do. 8090@c One good addition to the "organized by command" 8091@c section (if any) would be "see also" links. 8092@c The awk manual might be a good example; it has a 8093@c reference manual which is more verbose than Invoking 8094@c CVS but probably somewhat less verbose than CVS 8095@c Commands. 8096 8097@menu 8098* Structure:: Overall structure of CVS commands 8099* Exit status:: Indicating CVS's success or failure 8100* ~/.cvsrc:: Default options with the ~/.cvsrc file 8101* Global options:: Options you give to the left of cvs_command 8102* Common options:: Options you give to the right of cvs_command 8103* Date input formats:: Acceptable formats for date specifications 8104* add:: Add files and directories to the repository 8105* admin:: Administration 8106* annotate & rannotate:: What revision modified each line of a file? 8107* checkout:: Checkout sources for editing 8108* commit:: Check files into the repository 8109* diff:: Show differences between revisions 8110* export:: Export sources from CVS, similar to checkout 8111* history:: Show status of files and users 8112* import:: Import sources into CVS, using vendor branches 8113* init:: Initialize a repository 8114* log & rlog:: Show log messages for files 8115* ls & rls:: List files in the repository 8116* rdiff:: 'patch' format diffs between releases 8117* release:: Indicate that a directory is no longer in use 8118* remove:: Remove files from active development 8119* server & pserver:: Act as a server for a client on stdin/stdout 8120* tag & rtag:: Mark project snapshot for later retrieval 8121* update:: Bring work tree in sync with repository 8122@end menu 8123 8124@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8125@node Structure 8126@appendixsec Overall structure of CVS commands 8127@cindex Structure 8128@cindex CVS command structure 8129@cindex Command structure 8130@cindex Format of CVS commands 8131 8132The overall format of all @sc{cvs} commands is: 8133 8134@example 8135cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 8136@end example 8137 8138@table @code 8139@item cvs 8140The name of the @sc{cvs} program. 8141 8142@item cvs_options 8143Some options that affect all sub-commands of @sc{cvs}. These are 8144described below. 8145 8146@item cvs_command 8147One of several different sub-commands. Some of the commands have 8148aliases that can be used instead; those aliases are noted in the 8149reference manual for that command. There are only two situations 8150where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 8151list of available commands, and @samp{cvs -v} displays version 8152information on @sc{cvs} itself. 8153 8154@item command_options 8155Options that are specific for the command. 8156 8157@item command_args 8158Arguments to the commands. 8159@end table 8160 8161There is unfortunately some confusion between 8162@code{cvs_options} and @code{command_options}. 8163When given as a @code{cvs_option}, some options only 8164affect some of the commands. When given as a 8165@code{command_option} it may have a different meaning, and 8166be accepted by more commands. In other words, do not 8167take the above categorization too seriously. Look at 8168the documentation instead. 8169 8170@node Exit status 8171@appendixsec CVS's exit status 8172@cindex Exit status, of CVS 8173 8174@sc{cvs} can indicate to the calling environment whether it 8175succeeded or failed by setting its @dfn{exit status}. 8176The exact way of testing the exit status will vary from 8177one operating system to another. For example in a unix 8178shell script the @samp{$?} variable will be 0 if the 8179last command returned a successful exit status, or 8180greater than 0 if the exit status indicated failure. 8181 8182If @sc{cvs} is successful, it returns a successful status; 8183if there is an error, it prints an error message and 8184returns a failure status. The one exception to this is 8185the @code{cvs diff} command. It will return a 8186successful status if it found no differences, or a 8187failure status if there were differences or if there 8188was an error. Because this behavior provides no good 8189way to detect errors, in the future it is possible that 8190@code{cvs diff} will be changed to behave like the 8191other @sc{cvs} commands. 8192@c It might seem like checking whether cvs -q diff 8193@c produces empty or non-empty output can tell whether 8194@c there were differences or not. But it seems like 8195@c there are cases with output but no differences 8196@c (testsuite basica-8b). It is not clear to me how 8197@c useful it is for a script to be able to check 8198@c whether there were differences. 8199@c FIXCVS? In previous versions of CVS, cvs diff 8200@c returned 0 for no differences, 1 for differences, or 8201@c 2 for errors. Is this behavior worth trying to 8202@c bring back (but what does it mean for VMS?)? 8203 8204@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8205@node ~/.cvsrc 8206@appendixsec Default options and the ~/.cvsrc file 8207@cindex .cvsrc file 8208@cindex Option defaults 8209 8210There are some @code{command_options} that are used so 8211often that you might have set up an alias or some other 8212means to make sure you always specify that option. One 8213example (the one that drove the implementation of the 8214@file{.cvsrc} support, actually) is that many people find the 8215default output of the @samp{diff} command to be very 8216hard to read, and that either context diffs or unidiffs 8217are much easier to understand. 8218 8219The @file{~/.cvsrc} file is a way that you can add 8220default options to @code{cvs_commands} within cvs, 8221instead of relying on aliases or other shell scripts. 8222 8223The format of the @file{~/.cvsrc} file is simple. The 8224file is searched for a line that begins with the same 8225name as the @code{cvs_command} being executed. If a 8226match is found, then the remainder of the line is split 8227up (at whitespace characters) into separate options and 8228added to the command arguments @emph{before} any 8229options from the command line. 8230 8231If a command has two names (e.g., @code{checkout} and 8232@code{co}), the official name, not necessarily the one 8233used on the command line, will be used to match against 8234the file. So if this is the contents of the user's 8235@file{~/.cvsrc} file: 8236 8237@example 8238log -N 8239diff -uN 8240rdiff -u 8241update -Pd 8242checkout -P 8243release -d 8244@end example 8245 8246@noindent 8247the command @samp{cvs checkout foo} would have the 8248@samp{-P} option added to the arguments, as well as 8249@samp{cvs co foo}. 8250 8251With the example file above, the output from @samp{cvs 8252diff foobar} will be in unidiff format. @samp{cvs diff 8253-c foobar} will provide context diffs, as usual. 8254Getting "old" format diffs would be slightly more 8255complicated, because @code{diff} doesn't have an option 8256to specify use of the "old" format, so you would need 8257@samp{cvs -f diff foobar}. 8258 8259In place of the command name you can use @code{cvs} to 8260specify global options (@pxref{Global options}). For 8261example the following line in @file{.cvsrc} 8262 8263@example 8264cvs -z6 8265@end example 8266 8267@noindent 8268causes @sc{cvs} to use compression level 6. 8269 8270@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8271@node Global options 8272@appendixsec Global options 8273@cindex Options, global 8274@cindex Global options 8275@cindex Left-hand options 8276 8277The available @samp{cvs_options} (that are given to the 8278left of @samp{cvs_command}) are: 8279 8280@table @code 8281@item --allow-root=@var{rootdir} 8282May be invoked multiple times to specify one legal @sc{cvsroot} directory with 8283each invocation. Also causes CVS to preparse the configuration file for each 8284specified root, which can be useful when configuring write proxies, See 8285@ref{Password authentication server} & @ref{Write proxies}. 8286 8287@cindex Authentication, stream 8288@cindex Stream authentication 8289@item -a 8290Authenticate all communication between the client and 8291the server. Only has an effect on the @sc{cvs} client. 8292As of this writing, this is only implemented when using 8293a GSSAPI connection (@pxref{GSSAPI authenticated}). 8294Authentication prevents certain sorts of attacks 8295involving hijacking the active @sc{tcp} connection. 8296Enabling authentication does not enable encryption. 8297 8298@cindex RCSBIN, overriding 8299@cindex Overriding RCSBIN 8300@item -b @var{bindir} 8301In @sc{cvs} 1.9.18 and older, this specified that 8302@sc{rcs} programs are in the @var{bindir} directory. 8303Current versions of @sc{cvs} do not run @sc{rcs} 8304programs; for compatibility this option is accepted, 8305but it does nothing. 8306 8307@cindex TMPDIR, environment variable 8308@cindex temporary file directory, set via command line 8309@cindex temporary file directory, set via environment variable 8310@cindex temporary file directory, set via config 8311@cindex temporary files, location of 8312@item -T @var{tempdir} 8313Use @var{tempdir} as the directory where temporary files are 8314located. 8315 8316The @sc{cvs} client and server store temporary files in a temporary directory. 8317The path to this temporary directory is set via, in order of precedence: 8318 8319@itemize @bullet 8320@item 8321The argument to the global @samp{-T} option. 8322 8323@item 8324The value set for @code{TmpDir} in the config file (server only - 8325@pxref{config}). 8326 8327@item 8328The contents of the @code{$TMPDIR} environment variable (@code{%TMPDIR%} on 8329Windows - @pxref{Environment variables}). 8330 8331@item 8332/tmp 8333 8334@end itemize 8335 8336Temporary directories should always be specified as an absolute pathname. 8337When running a CVS client, @samp{-T} affects only the local process; 8338specifying @samp{-T} for the client has no effect on the server and 8339vice versa. 8340 8341@cindex CVS directory, overriding 8342@cindex Overriding CVS directory 8343@item -D @var{cvs_directory} 8344Use @var{cvs_directory} as the location of the CVS internal files, instead 8345of the default @file{CVS}. 8346 8347@cindex CVSROOT, overriding 8348@cindex Overriding CVSROOT 8349@item -d @var{cvs_root_directory} 8350Use @var{cvs_root_directory} as the root directory 8351pathname of the repository. Overrides the setting of 8352the @code{$CVSROOT} environment variable. @xref{Repository}. 8353 8354@cindex EDITOR, overriding 8355@cindex Overriding EDITOR 8356@item -e @var{editor} 8357Use @var{editor} to enter revision log information. Overrides the 8358setting of the @code{$CVSEDITOR} and @code{$EDITOR} 8359environment variables. For more information, see 8360@ref{Committing your changes}. 8361 8362@item -f 8363Do not read the @file{~/.cvsrc} file. This 8364option is most often used because of the 8365non-orthogonality of the @sc{cvs} option set. For 8366example, the @samp{cvs log} option @samp{-N} (turn off 8367display of tag names) does not have a corresponding 8368option to turn the display on. So if you have 8369@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 8370you may need to use @samp{-f} to show the tag names. 8371 8372@item -H 8373@itemx --help 8374Display usage information about the specified @samp{cvs_command} 8375(but do not actually execute the command). If you don't specify 8376a command name, @samp{cvs -H} displays overall help for 8377@sc{cvs}, including a list of other help options. 8378@c It seems to me it is better to document it this way 8379@c rather than trying to update this documentation 8380@c every time that we add a --help-foo option. But 8381@c perhaps that is confusing... 8382 8383@cindex Read-only repository mode 8384@item -R 8385Turns on read-only repository mode. This allows one to check out from a 8386read-only repository, such as within an anoncvs server, or from a @sc{cd-rom} 8387repository. 8388 8389Same effect as if the @code{CVSREADONLYFS} environment 8390variable is set. Using @samp{-R} can also considerably 8391speed up checkouts over NFS. 8392 8393@cindex Read-only mode 8394@item -n 8395Do not change any files. Attempt to execute the 8396@samp{cvs_command}, but only to issue reports; do not remove, 8397update, or merge any existing files, or create any new files. 8398 8399Note that @sc{cvs} will not necessarily produce exactly 8400the same output as without @samp{-n}. In some cases 8401the output will be the same, but in other cases 8402@sc{cvs} will skip some of the processing that would 8403have been required to produce the exact same output. 8404 8405@item -Q 8406Cause the command to be really quiet; the command will only 8407generate output for serious problems. 8408 8409@item -q 8410Cause the command to be somewhat quiet; informational messages, 8411such as reports of recursion through subdirectories, are 8412suppressed. 8413 8414@cindex Read-only files, and -r 8415@item -r 8416Make new working files read-only. Same effect 8417as if the @code{$CVSREAD} environment variable is set 8418(@pxref{Environment variables}). The default is to 8419make working files writable, unless watches are on 8420(@pxref{Watches}). 8421 8422@item -s @var{variable}=@var{value} 8423Set a user variable (@pxref{Variables}). 8424 8425@cindex Trace 8426@item -t 8427Trace program execution; display messages showing the steps of 8428@sc{cvs} activity. Particularly useful with @samp{-n} to explore the 8429potential impact of an unfamiliar command. 8430 8431@item -v 8432@item --version 8433Display version and copyright information for @sc{cvs}. 8434 8435@cindex CVSREAD, overriding 8436@cindex Overriding CVSREAD 8437@item -w 8438Make new working files read-write. Overrides the 8439setting of the @code{$CVSREAD} environment variable. 8440Files are created read-write by default, unless @code{$CVSREAD} is 8441set or @samp{-r} is given. 8442@c Note that -w only overrides -r and CVSREAD; it has 8443@c no effect on files which are readonly because of 8444@c "cvs watch on". My guess is that is the way it 8445@c should be (or should "cvs -w get" on a watched file 8446@c be the same as a get and a cvs edit?), but I'm not 8447@c completely sure whether to document it this way. 8448 8449@item -x 8450@cindex Encryption 8451Encrypt all communication between the client and the 8452server. Only has an effect on the @sc{cvs} client. As 8453of this writing, this is only implemented when using a 8454GSSAPI connection (@pxref{GSSAPI authenticated}) or a 8455Kerberos connection (@pxref{Kerberos authenticated}). 8456Enabling encryption implies that message traffic is 8457also authenticated. Encryption support is not 8458available by default; it must be enabled using a 8459special configure option, @file{--enable-encryption}, 8460when you build @sc{cvs}. 8461 8462@item -z @var{level} 8463@cindex Compression 8464@cindex Gzip 8465Request compression @var{level} for network traffic. 8466@sc{cvs} interprets @var{level} identically to the @code{gzip} program. 8467Valid levels are 1 (high speed, low compression) to 84689 (low speed, high compression), or 0 to disable 8469compression (the default). Data sent to the server will 8470be compressed at the requested level and the client will request 8471the server use the same compression level for data returned. The 8472server will use the closest level allowed by the server administrator to 8473compress returned data. This option only has an effect when passed to 8474the @sc{cvs} client. 8475@end table 8476 8477@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8478@node Common options 8479@appendixsec Common command options 8480@cindex Common options 8481@cindex Right-hand options 8482 8483This section describes the @samp{command_options} that 8484are available across several @sc{cvs} commands. These 8485options are always given to the right of 8486@samp{cvs_command}. Not all 8487commands support all of these options; each option is 8488only supported for commands where it makes sense. 8489However, when a command has one of these options you 8490can almost always count on the same behavior of the 8491option as in other commands. (Other command options, 8492which are listed with the individual commands, may have 8493different behavior from one @sc{cvs} command to the other). 8494 8495@strong{Note: the @samp{history} command is an exception; it supports 8496many options that conflict even with these standard options.} 8497 8498@table @code 8499@cindex Dates 8500@cindex Time 8501@cindex Specifying dates 8502@item -D @var{date_spec} 8503Use the most recent revision no later than @var{date_spec}. 8504@var{date_spec} is a single argument, a date description 8505specifying a date in the past. 8506 8507The specification is @dfn{sticky} when you use it to make a 8508private copy of a source file; that is, when you get a working 8509file using @samp{-D}, @sc{cvs} records the date you specified, so that 8510further updates in the same directory will use the same date 8511(for more information on sticky tags/dates, @pxref{Sticky tags}). 8512 8513@samp{-D} is available with the @code{annotate}, @code{checkout}, 8514@code{diff}, @code{export}, @code{history}, @code{ls}, 8515@code{rdiff}, @code{rls}, @code{rtag}, @code{tag}, and @code{update} commands. 8516(The @code{history} command uses this option in a 8517slightly different way; @pxref{history options}). 8518 8519For a complete description of the date formats accepted by @sc{cvs}, 8520@ref{Date input formats}. 8521@c What other formats should we accept? I don't want 8522@c to start accepting a whole mess of non-standard 8523@c new formats (there are a lot which are in wide use in 8524@c one context or another), but practicality does 8525@c dictate some level of flexibility. 8526@c * POSIX.2 (e.g. touch, ls output, date) and other 8527@c POSIX and/or de facto unix standards (e.g. at). The 8528@c practice here is too inconsistent to be of any use. 8529@c * VMS dates. This is not a formal standard, but 8530@c there is a published specification (see SYS$ASCTIM 8531@c and SYS$BINTIM in the _VMS System Services Reference 8532@c Manual_), it is implemented consistently in VMS 8533@c utilities, and VMS users will expect CVS running on 8534@c VMS to support this format (and if we're going to do 8535@c that, better to make CVS support it on all 8536@c platforms. Maybe). 8537@c 8538@c One more note: In output, CVS should consistently 8539@c use one date format, and that format should be one that 8540@c it accepts in input as well. The former isn't 8541@c really true (see survey below), and I'm not 8542@c sure that either of those formats is accepted in 8543@c input. 8544@c 8545@c cvs log 8546@c current 1996/01/02 13:45:31 8547@c Internet 02 Jan 1996 13:45:31 UT 8548@c ISO 1996-01-02 13:45:31 8549@c cvs ann 8550@c current 02-Jan-96 8551@c Internet-like 02 Jan 96 8552@c ISO 96-01-02 8553@c cvs status 8554@c current Tue Jun 11 02:54:53 1996 8555@c Internet [Tue,] 11 Jun 1996 02:54:53 8556@c ISO 1996-06-11 02:54:53 8557@c note: date possibly should be omitted entirely for 8558@c other reasons. 8559@c cvs editors 8560@c current Tue Jun 11 02:54:53 1996 GMT 8561@c cvs history 8562@c current 06/11 02:54 +0000 8563@c any others? 8564@c There is a good chance the proper solution has to 8565@c involve at least some level of letting the user 8566@c decide which format (with the default being the 8567@c formats CVS has always used; changing these might be 8568@c _very_ disruptive since scripts may very well be 8569@c parsing them). 8570@c 8571@c Another random bit of prior art concerning dates is 8572@c the strptime function which takes templates such as 8573@c "%m/%d/%y", and apparent a variant of getdate() 8574@c which also honors them. See 8575@c X/Open CAE Specification, System Interfaces and 8576@c Headers Issue 4, Version 2 (September 1994), in the 8577@c entry for getdate() on page 231 8578 8579Remember to quote the argument to the @samp{-D} 8580flag so that your shell doesn't interpret spaces as 8581argument separators. A command using the @samp{-D} 8582flag can look like this: 8583 8584@example 8585$ cvs diff -D "1 hour ago" cvs.texinfo 8586@end example 8587 8588@cindex Forcing a tag match 8589@item -f 8590When you specify a particular date or tag to @sc{cvs} commands, they 8591normally ignore files that do not contain the tag (or did not 8592exist prior to the date) that you specified. Use the @samp{-f} option 8593if you want files retrieved even when there is no match for the 8594tag or date. (The most recent revision of the file 8595will be used). 8596 8597Note that even with @samp{-f}, a tag that you specify 8598must exist (that is, in some file, not necessary in 8599every file). This is so that @sc{cvs} will continue to 8600give an error if you mistype a tag name. 8601 8602@need 800 8603@samp{-f} is available with these commands: 8604@code{annotate}, @code{checkout}, @code{export}, 8605@code{rdiff}, @code{rtag}, and @code{update}. 8606 8607@strong{WARNING: The @code{commit} and @code{remove} 8608commands also have a 8609@samp{-f} option, but it has a different behavior for 8610those commands. See @ref{commit options}, and 8611@ref{Removing files}.} 8612 8613@item -k @var{kflag} 8614Override the default processing of RCS keywords other than 8615@samp{-kb}. @xref{Keyword substitution}, for the meaning of 8616@var{kflag}. Used with the @code{checkout} and @code{update} 8617commands, your @var{kflag} specification is 8618@dfn{sticky}; that is, when you use this option 8619with a @code{checkout} or @code{update} command, 8620@sc{cvs} associates your selected @var{kflag} with any files 8621it operates on, and continues to use that @var{kflag} with future 8622commands on the same files until you specify otherwise. 8623 8624The @samp{-k} option is available with the @code{add}, 8625@code{checkout}, @code{diff}, @code{export}, @code{import}, 8626@code{rdiff}, and @code{update} commands. 8627 8628@strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag 8629overrode the @samp{-kb} indication for a binary file. This could 8630sometimes corrupt binary files. @xref{Merging and keywords}, for 8631more.} 8632 8633@item -l 8634Local; run only in current working directory, rather than 8635recursing through subdirectories. 8636 8637Available with the following commands: @code{annotate}, @code{checkout}, 8638@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8639@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, 8640@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8641and @code{watchers}. 8642 8643@cindex Editor, avoiding invocation of 8644@cindex Avoiding editor invocation 8645@item -m @var{message} 8646Use @var{message} as log information, instead of 8647invoking an editor. 8648 8649Available with the following commands: @code{add}, 8650@code{commit} and @code{import}. 8651 8652@item -n 8653Do not run any tag program. (A program can be 8654specified to run in the modules 8655database (@pxref{modules}); this option bypasses it). 8656 8657@strong{Note: this is not the same as the @samp{cvs -n} 8658program option, which you can specify to the left of a cvs command!} 8659 8660Available with the @code{checkout}, @code{commit}, @code{export}, 8661and @code{rtag} commands. 8662 8663@item -P 8664Prune empty directories. See @ref{Removing directories}. 8665 8666@item -p 8667Pipe the files retrieved from the repository to standard output, 8668rather than writing them in the current directory. Available 8669with the @code{checkout} and @code{update} commands. 8670 8671@item -R 8672Process directories recursively. This is the default for all @sc{cvs} 8673commands, with the exception of @code{ls} & @code{rls}. 8674 8675Available with the following commands: @code{annotate}, @code{checkout}, 8676@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8677@code{ls}, @code{rdiff}, @code{remove}, @code{rls}, @code{rtag}, 8678@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8679and @code{watchers}. 8680 8681@item -r @var{tag} 8682@item -r @var{tag}[:@var{date}] 8683@cindex HEAD, special tag 8684@cindex BASE, special tag 8685Use the revision specified by the @var{tag} argument (and the @var{date} 8686argument for the commands which accept it) instead of the 8687default @dfn{head} revision. As well as arbitrary tags defined 8688with the @code{tag} or @code{rtag} command, two special tags are 8689always available: @samp{HEAD} refers to the most recent version 8690available in the repository, and @samp{BASE} refers to the 8691revision you last checked out into the current working directory. 8692 8693@c FIXME: What does HEAD really mean? I believe that 8694@c the current answer is the head of the default branch 8695@c for all cvs commands except diff. For diff, it 8696@c seems to be (a) the head of the trunk (or the default 8697@c branch?) if there is no sticky tag, (b) the head of the 8698@c branch for the sticky tag, if there is a sticky tag. 8699@c (b) is ugly as it differs 8700@c from what HEAD means for other commands, but people 8701@c and/or scripts are quite possibly used to it. 8702@c See "head" tests in sanity.sh. 8703@c Probably the best fix is to introduce two new 8704@c special tags, ".thead" for the head of the trunk, 8705@c and ".bhead" for the head of the current branch. 8706@c Then deprecate HEAD. This has the advantage of 8707@c not surprising people with a change to HEAD, and a 8708@c side benefit of also phasing out the poorly-named 8709@c HEAD (see discussion of reserved tag names in node 8710@c "Tags"). Of course, .thead and .bhead should be 8711@c carefully implemented (with the implementation the 8712@c same for "diff" as for everyone else), test cases 8713@c written (similar to the ones in "head"), new tests 8714@c cases written for things like default branches, &c. 8715 8716The tag specification is sticky when you use this 8717with @code{checkout} or @code{update} to make your own 8718copy of a file: @sc{cvs} remembers the tag and continues to use it on 8719future update commands, until you specify otherwise (for more information 8720on sticky tags/dates, @pxref{Sticky tags}). 8721 8722The tag can be either a symbolic or numeric tag, as 8723described in @ref{Tags}, or the name of a branch, as 8724described in @ref{Branching and merging}. 8725When @var{tag} is the name of a 8726branch, some commands accept the optional @var{date} argument to specify 8727the revision as of the given date on the branch. 8728When a command expects a specific revision, 8729the name of a branch is interpreted as the most recent 8730revision on that branch. 8731 8732Specifying the @samp{-q} global option along with the 8733@samp{-r} command option is often useful, to suppress 8734the warning messages when the @sc{rcs} file 8735does not contain the specified tag. 8736 8737@strong{Note: this is not the same as the overall @samp{cvs -r} option, 8738which you can specify to the left of a @sc{cvs} command!} 8739 8740@samp{-r @var{tag}} is available with the @code{commit} and @code{history} 8741commands. 8742 8743@samp{-r @var{tag}[:@var{date}]} is available with the @code{annotate}, 8744@code{checkout}, @code{diff}, @code{export}, @code{rdiff}, @code{rtag}, 8745and @code{update} commands. 8746 8747@item -W 8748Specify file names that should be filtered. You can 8749use this option repeatedly. The spec can be a file 8750name pattern of the same type that you can specify in 8751the @file{.cvswrappers} file. 8752Available with the following commands: @code{import}, 8753and @code{update}. 8754 8755@end table 8756 8757@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8758@include getdate-cvs.texi 8759 8760@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8761@node add 8762@appendixsec add---Add files and directories to the repository 8763@cindex add (subcommand) 8764 8765@itemize @bullet 8766@item 8767Synopsis: add [-k rcs-kflag] [-m message] files... 8768@item 8769Requires: repository, working directory. 8770@item 8771Changes: repository, working directory. 8772@end itemize 8773 8774The @code{add} command is used to present new files 8775and directories for addition into the @sc{cvs} 8776repository. When @code{add} is used on a directory, 8777a new directory is created in the repository 8778immediately. When used on a file, only the working 8779directory is updated. Changes to the repository are 8780not made until the @code{commit} command is used on 8781the newly added file. 8782 8783The @code{add} command also resurrects files that 8784have been previously removed. This can be done 8785before or after the @code{commit} command is used 8786to finalize the removal of files. Resurrected files 8787are restored into the working directory at the time 8788the @code{add} command is executed. 8789 8790@menu 8791* add options:: add options 8792* add examples:: add examples 8793@end menu 8794 8795@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8796@node add options 8797@appendixsubsec add options 8798 8799These standard options are supported by @code{add} 8800(@pxref{Common options}, for a complete description of 8801them): 8802 8803@table @code 8804@item -k @var{kflag} 8805Process keywords according to @var{kflag}. See 8806@ref{Keyword substitution}. 8807This option is sticky; future updates of 8808this file in this working directory will use the same 8809@var{kflag}. The @code{status} command can be viewed 8810to see the sticky options. For more information on 8811the @code{status} command, @xref{Invoking CVS}. 8812 8813@item -m @var{message} 8814Use @var{message} as the log message, instead of 8815invoking an editor. 8816@end table 8817 8818@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8819@node add examples 8820@appendixsubsec add examples 8821 8822@appendixsubsubsec Adding a directory 8823 8824@example 8825$ mkdir doc 8826$ cvs add doc 8827Directory /path/to/repository/doc added to the repository 8828@end example 8829 8830@appendixsubsubsec Adding a file 8831 8832@example 8833 8834$ >TODO 8835$ cvs add TODO 8836cvs add: scheduling file `TODO' for addition 8837cvs add: use 'cvs commit' to add this file permanently 8838@end example 8839 8840@appendixsubsubsec Undoing a @code{remove} command 8841 8842@example 8843$ rm -f makefile 8844$ cvs remove makefile 8845cvs remove: scheduling `makefile' for removal 8846cvs remove: use 'cvs commit' to remove this file permanently 8847$ cvs add makefile 8848U makefile 8849cvs add: makefile, version 1.2, resurrected 8850@end example 8851 8852@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8853@node admin 8854@appendixsec admin---Administration 8855@cindex Admin (subcommand) 8856 8857@itemize @bullet 8858@item 8859Requires: repository, working directory. 8860@item 8861Changes: repository. 8862@item 8863Synonym: rcs 8864@end itemize 8865 8866This is the @sc{cvs} interface to assorted 8867administrative facilities. Some of them have 8868questionable usefulness for @sc{cvs} but exist for 8869historical purposes. Some of the questionable options 8870are likely to disappear in the future. This command 8871@emph{does} work recursively, so extreme care should be 8872used. 8873 8874@cindex cvsadmin 8875@cindex UserAdminOptions, in CVSROOT/config 8876On unix, if there is a group named @code{cvsadmin}, 8877only members of that group can run @code{cvs admin} 8878commands, except for those specified using the 8879@code{UserAdminOptions} configuration option in the 8880@file{CVSROOT/config} file. Options specified using 8881@code{UserAdminOptions} can be run by any user. See 8882@ref{config} for more on @code{UserAdminOptions}. 8883 8884The @code{cvsadmin} group should exist on the server, 8885or any system running the non-client/server @sc{cvs}. 8886To disallow @code{cvs admin} for all users, create a 8887group with no users in it. On NT, the @code{cvsadmin} 8888feature does not exist and all users 8889can run @code{cvs admin}. 8890 8891@menu 8892* admin options:: admin options 8893@end menu 8894 8895@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8896@node admin options 8897@appendixsubsec admin options 8898 8899Some of these options have questionable usefulness for 8900@sc{cvs} but exist for historical purposes. Some even 8901make it impossible to use @sc{cvs} until you undo the 8902effect! 8903 8904@table @code 8905@item -A@var{oldfile} 8906Might not work together with @sc{cvs}. Append the 8907access list of @var{oldfile} to the access list of the 8908@sc{rcs} file. 8909 8910@item -a@var{logins} 8911Might not work together with @sc{cvs}. Append the 8912login names appearing in the comma-separated list 8913@var{logins} to the access list of the @sc{rcs} file. 8914 8915@item -b[@var{rev}] 8916Set the default branch to @var{rev}. In @sc{cvs}, you 8917normally do not manipulate default branches; sticky 8918tags (@pxref{Sticky tags}) are a better way to decide 8919which branch you want to work on. There is one reason 8920to run @code{cvs admin -b}: to revert to the vendor's 8921version when using vendor branches (@pxref{Reverting 8922local changes}). 8923There can be no space between @samp{-b} and its argument. 8924@c Hmm, we don't document the usage where rev is 8925@c omitted. Maybe that usage can/should be deprecated 8926@c (and replaced with -bHEAD or something?) (so we can toss 8927@c the optional argument). Note that -bHEAD does not 8928@c work, as of 17 Sep 1997, but probably will once "cvs 8929@c admin" is internal to CVS. 8930 8931@cindex Comment leader 8932@item -c@var{string} 8933Sets the comment leader to @var{string}. The comment 8934leader is not used by current versions of @sc{cvs} or 8935@sc{rcs} 5.7. Therefore, you can almost surely not 8936worry about it. @xref{Keyword substitution}. 8937 8938@item -e[@var{logins}] 8939Might not work together with @sc{cvs}. Erase the login 8940names appearing in the comma-separated list 8941@var{logins} from the access list of the RCS file. If 8942@var{logins} is omitted, erase the entire access list. 8943There can be no space between @samp{-e} and its argument. 8944 8945@item -I 8946Run interactively, even if the standard input is not a 8947terminal. This option does not work with the 8948client/server @sc{cvs} and is likely to disappear in 8949a future release of @sc{cvs}. 8950 8951@item -i 8952Useless with @sc{cvs}. This creates and initializes a 8953new @sc{rcs} file, without depositing a revision. With 8954@sc{cvs}, add files with the @code{cvs add} command 8955(@pxref{Adding files}). 8956 8957@item -k@var{subst} 8958Set the default keyword 8959substitution to @var{subst}. @xref{Keyword 8960substitution}. Giving an explicit @samp{-k} option to 8961@code{cvs update}, @code{cvs export}, or @code{cvs 8962checkout} overrides this default. 8963 8964@item -l[@var{rev}] 8965Lock the revision with number @var{rev}. If a branch 8966is given, lock the latest revision on that branch. If 8967@var{rev} is omitted, lock the latest revision on the 8968default branch. There can be no space between 8969@samp{-l} and its argument. 8970 8971This can be used in conjunction with the 8972@file{rcslock.pl} script in the @file{contrib} 8973directory of the @sc{cvs} source distribution to 8974provide reserved checkouts (where only one user can be 8975editing a given file at a time). See the comments in 8976that file for details (and see the @file{README} file 8977in that directory for disclaimers about the unsupported 8978nature of contrib). According to comments in that 8979file, locking must be set to strict (which is the default). 8980 8981@item -L 8982Set locking to strict. Strict locking means that the 8983owner of an RCS file is not exempt from locking for 8984checkin. For use with @sc{cvs}, strict locking must be 8985set; see the discussion under the @samp{-l} option above. 8986 8987@cindex Changing a log message 8988@cindex Replacing a log message 8989@cindex Correcting a log message 8990@cindex Fixing a log message 8991@cindex Log message, correcting 8992@item -m@var{rev}:@var{msg} 8993Replace the log message of revision @var{rev} with 8994@var{msg}. 8995 8996@c The rcs -M option, to suppress sending mail, has never been 8997@c documented as a cvs admin option. 8998 8999@item -N@var{name}[:[@var{rev}]] 9000Act like @samp{-n}, except override any previous 9001assignment of @var{name}. For use with magic branches, 9002see @ref{Magic branch numbers}. 9003 9004@item -n@var{name}[:[@var{rev}]] 9005Associate the symbolic name @var{name} with the branch 9006or revision @var{rev}. It is normally better to use 9007@samp{cvs tag} or @samp{cvs rtag} instead. Delete the 9008symbolic name if both @samp{:} and @var{rev} are 9009omitted; otherwise, print an error message if 9010@var{name} is already associated with another number. 9011If @var{rev} is symbolic, it is expanded before 9012association. A @var{rev} consisting of a branch number 9013followed by a @samp{.} stands for the current latest 9014revision in the branch. A @samp{:} with an empty 9015@var{rev} stands for the current latest revision on the 9016default branch, normally the trunk. For example, 9017@samp{cvs admin -n@var{name}:} associates @var{name} with the 9018current latest revision of all the RCS files; 9019this contrasts with @samp{cvs admin -n@var{name}:$} which 9020associates @var{name} with the revision numbers 9021extracted from keyword strings in the corresponding 9022working files. 9023 9024@cindex Deleting revisions 9025@cindex Outdating revisions 9026@cindex Saving space 9027@item -o@var{range} 9028Deletes (@dfn{outdates}) the revisions given by 9029@var{range}. 9030 9031Note that this command can be quite dangerous unless 9032you know @emph{exactly} what you are doing (for example 9033see the warnings below about how the 9034@var{rev1}:@var{rev2} syntax is confusing). 9035 9036If you are short on disc this option might help you. 9037But think twice before using it---there is no way short 9038of restoring the latest backup to undo this command! 9039If you delete different revisions than you planned, 9040either due to carelessness or (heaven forbid) a @sc{cvs} 9041bug, there is no opportunity to correct the error 9042before the revisions are deleted. It probably would be 9043a good idea to experiment on a copy of the repository 9044first. 9045 9046Specify @var{range} in one of the following ways: 9047 9048@table @code 9049@item @var{rev1}::@var{rev2} 9050Collapse all revisions between rev1 and rev2, so that 9051@sc{cvs} only stores the differences associated with going 9052from rev1 to rev2, not intermediate steps. For 9053example, after @samp{-o 1.3::1.5} one can retrieve 9054revision 1.3, revision 1.5, or the differences to get 9055from 1.3 to 1.5, but not the revision 1.4, or the 9056differences between 1.3 and 1.4. Other examples: 9057@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 9058effect, because there are no intermediate revisions to 9059remove. 9060 9061@item ::@var{rev} 9062Collapse revisions between the beginning of the branch 9063containing @var{rev} and @var{rev} itself. The 9064branchpoint and @var{rev} are left intact. For 9065example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 9066revision 1.3.2.5, and everything in between, but leaves 90671.3 and 1.3.2.6 intact. 9068 9069@item @var{rev}:: 9070Collapse revisions between @var{rev} and the end of the 9071branch containing @var{rev}. Revision @var{rev} is 9072left intact but the head revision is deleted. 9073 9074@item @var{rev} 9075Delete the revision @var{rev}. For example, @samp{-o 90761.3} is equivalent to @samp{-o 1.2::1.4}. 9077 9078@item @var{rev1}:@var{rev2} 9079Delete the revisions from @var{rev1} to @var{rev2}, 9080inclusive, on the same branch. One will not be able to 9081retrieve @var{rev1} or @var{rev2} or any of the 9082revisions in between. For example, the command 9083@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 9084It means to delete revisions up to, and including, the 9085tag R_1_02. But beware! If there are files that have not 9086changed between R_1_02 and R_1_03 the file will have 9087@emph{the same} numerical revision number assigned to 9088the tags R_1_02 and R_1_03. So not only will it be 9089impossible to retrieve R_1_02; R_1_03 will also have to 9090be restored from the tapes! In most cases you want to 9091specify @var{rev1}::@var{rev2} instead. 9092 9093@item :@var{rev} 9094Delete revisions from the beginning of the 9095branch containing @var{rev} up to and including 9096@var{rev}. 9097 9098@item @var{rev}: 9099Delete revisions from revision @var{rev}, including 9100@var{rev} itself, to the end of the branch containing 9101@var{rev}. 9102@end table 9103 9104None of the revisions to be deleted may have 9105branches or locks. 9106 9107If any of the revisions to be deleted have symbolic 9108names, and one specifies one of the @samp{::} syntaxes, 9109then @sc{cvs} will give an error and not delete any 9110revisions. If you really want to delete both the 9111symbolic names and the revisions, first delete the 9112symbolic names with @code{cvs tag -d}, then run 9113@code{cvs admin -o}. If one specifies the 9114non-@samp{::} syntaxes, then @sc{cvs} will delete the 9115revisions but leave the symbolic names pointing to 9116nonexistent revisions. This behavior is preserved for 9117compatibility with previous versions of @sc{cvs}, but 9118because it isn't very useful, in the future it may 9119change to be like the @samp{::} case. 9120 9121Due to the way @sc{cvs} handles branches @var{rev} 9122cannot be specified symbolically if it is a branch. 9123@xref{Magic branch numbers}, for an explanation. 9124@c FIXME: is this still true? I suspect not. 9125 9126Make sure that no-one has checked out a copy of the 9127revision you outdate. Strange things will happen if he 9128starts to edit it and tries to check it back in. For 9129this reason, this option is not a good way to take back 9130a bogus commit; commit a new revision undoing the bogus 9131change instead (@pxref{Merging two revisions}). 9132 9133@item -q 9134Run quietly; do not print diagnostics. 9135 9136@item -s@var{state}[:@var{rev}] 9137Useful with @sc{cvs}. Set the state attribute of the 9138revision @var{rev} to @var{state}. If @var{rev} is a 9139branch number, assume the latest revision on that 9140branch. If @var{rev} is omitted, assume the latest 9141revision on the default branch. Any identifier is 9142acceptable for @var{state}. A useful set of states is 9143@samp{Exp} (for experimental), @samp{Stab} (for 9144stable), and @samp{Rel} (for released). By default, 9145the state of a new revision is set to @samp{Exp} when 9146it is created. The state is visible in the output from 9147@var{cvs log} (@pxref{log & rlog}), and in the 9148@samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords 9149(@pxref{Keyword substitution}). Note that @sc{cvs} 9150uses the @code{dead} state for its own purposes (@pxref{Attic}); to 9151take a file to or from the @code{dead} state use 9152commands like @code{cvs remove} and @code{cvs add} 9153(@pxref{Adding and removing}), not @code{cvs admin -s}. 9154 9155@item -t[@var{file}] 9156Useful with @sc{cvs}. Write descriptive text from the 9157contents of the named @var{file} into the RCS file, 9158deleting the existing text. The @var{file} pathname 9159may not begin with @samp{-}. The descriptive text can be seen in the 9160output from @samp{cvs log} (@pxref{log & rlog}). 9161There can be no space between @samp{-t} and its argument. 9162 9163If @var{file} is omitted, 9164obtain the text from standard input, terminated by 9165end-of-file or by a line containing @samp{.} by itself. 9166Prompt for the text if interaction is possible; see 9167@samp{-I}. 9168 9169@item -t-@var{string} 9170Similar to @samp{-t@var{file}}. Write descriptive text 9171from the @var{string} into the @sc{rcs} file, deleting 9172the existing text. 9173There can be no space between @samp{-t} and its argument. 9174 9175@c The rcs -T option, do not update last-mod time for 9176@c minor changes, has never been documented as a 9177@c cvs admin option. 9178 9179@item -U 9180Set locking to non-strict. Non-strict locking means 9181that the owner of a file need not lock a revision for 9182checkin. For use with @sc{cvs}, strict locking must be 9183set; see the discussion under the @samp{-l} option 9184above. 9185 9186@item -u[@var{rev}] 9187See the option @samp{-l} above, for a discussion of 9188using this option with @sc{cvs}. Unlock the revision 9189with number @var{rev}. If a branch is given, unlock 9190the latest revision on that branch. If @var{rev} is 9191omitted, remove the latest lock held by the caller. 9192Normally, only the locker of a revision may unlock it; 9193somebody else unlocking a revision breaks the lock. 9194This causes the original locker to be sent a @code{commit} 9195notification (@pxref{Getting Notified}). 9196There can be no space between @samp{-u} and its argument. 9197 9198@item -V@var{n} 9199In previous versions of @sc{cvs}, this option meant to 9200write an @sc{rcs} file which would be acceptable to 9201@sc{rcs} version @var{n}, but it is now obsolete and 9202specifying it will produce an error. 9203@c Note that -V without an argument has never been 9204@c documented as a cvs admin option. 9205 9206@item -x@var{suffixes} 9207In previous versions of @sc{cvs}, this was documented 9208as a way of specifying the names of the @sc{rcs} 9209files. However, @sc{cvs} has always required that the 9210@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 9211this option has never done anything useful. 9212 9213@c The rcs -z option, to specify the timezone, has 9214@c never been documented as a cvs admin option. 9215@end table 9216 9217@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9218@node annotate & rannotate 9219@appendixsec annotate & rannotate---What revision modified each line of a file? 9220@cindex annotate (subcommand) 9221@cindex rannotate (subcommand) 9222 9223@itemize @bullet 9224@item 9225Synopsis: annotate [options] files@dots{} 9226@item 9227Requires: repository. 9228@item 9229Changes: nothing. 9230@end itemize 9231 9232For each file in @var{files}, print the head revision 9233of the trunk, together with information on the last 9234modification for each line. 9235 9236@menu 9237* annotate options:: annotate options 9238* annotate example:: annotate example 9239@end menu 9240 9241@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9242@node annotate options 9243@appendixsubsec annotate options 9244 9245These standard options are supported by @code{annotate} 9246(@pxref{Common options}, for a complete description of 9247them): 9248 9249@table @code 9250@item -l 9251Local directory only, no recursion. 9252 9253@item -R 9254Process directories recursively. 9255 9256@item -f 9257Use head revision if tag/date not found. 9258 9259@item -F 9260Annotate binary files. 9261 9262@item -r @var{tag}[:@var{date}] 9263Annotate file as of specified revision/tag or, when @var{date} is specified 9264and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9265existed on @var{date}. See @ref{Common options}. 9266 9267@item -D @var{date} 9268Annotate file as of specified date. 9269@end table 9270 9271@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9272@node annotate example 9273@appendixsubsec annotate example 9274@cindex annotate (subcommand) 9275@cindex rannotate (subcommand) 9276 9277For example: 9278 9279@example 9280$ cvs annotate ssfile 9281Annotations for ssfile 9282*************** 92831.1 (mary 27-Mar-96): ssfile line 1 92841.2 (joe 28-Mar-96): ssfile line 2 9285@end example 9286 9287The file @file{ssfile} currently contains two lines. 9288The @code{ssfile line 1} line was checked in by 9289@code{mary} on March 27. Then, on March 28, @code{joe} 9290added a line @code{ssfile line 2}, without modifying 9291the @code{ssfile line 1} line. This report doesn't 9292tell you anything about lines which have been deleted 9293or replaced; you need to use @code{cvs diff} for that 9294(@pxref{diff}). 9295 9296The options to @code{cvs annotate} are listed in 9297@ref{Invoking CVS}, and can be used to select the files 9298and revisions to annotate. The options are described 9299in more detail there and in @ref{Common options}. 9300 9301@c FIXME: maybe an example using the options? Just 9302@c what it means to select a revision might be worth a 9303@c few words of explanation ("you want to see who 9304@c changed this line *before* 1.4"...). 9305 9306@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9307@node checkout 9308@appendixsec checkout---Check out sources for editing 9309@cindex checkout (subcommand) 9310@cindex co (subcommand) 9311 9312@itemize @bullet 9313@item 9314Synopsis: checkout [options] modules@dots{} 9315@item 9316Requires: repository. 9317@item 9318Changes: working directory. 9319@item 9320Synonyms: co, get 9321@end itemize 9322 9323Create or update a working directory containing copies of the 9324source files specified by @var{modules}. You must execute 9325@code{checkout} before using most of the other @sc{cvs} 9326commands, since most of them operate on your working 9327directory. 9328 9329The @var{modules} are either 9330symbolic names for some 9331collection of source directories and files, or paths to 9332directories or files in the repository. The symbolic 9333names are defined in the @samp{modules} file. 9334@xref{modules}. 9335@c Needs an example, particularly of the non-"modules" 9336@c case but probably of both. 9337 9338@c FIXME: this seems like a very odd place to introduce 9339@c people to how CVS works. The bit about unreserved 9340@c checkouts is also misleading as it depends on how 9341@c things are set up. 9342Depending on the modules you specify, @code{checkout} may 9343recursively create directories and populate them with 9344the appropriate source files. You can then edit these 9345source files at any time (regardless of whether other 9346software developers are editing their own copies of the 9347sources); update them to include new changes applied by 9348others to the source repository; or commit your work as 9349a permanent change to the source repository. 9350 9351Note that @code{checkout} is used to create 9352directories. The top-level directory created is always 9353added to the directory where @code{checkout} is 9354invoked, and usually has the same name as the specified 9355module. In the case of a module alias, the created 9356sub-directory may have a different name, but you can be 9357sure that it will be a sub-directory, and that 9358@code{checkout} will show the relative path leading to 9359each file as it is extracted into your private work 9360area (unless you specify the @samp{-Q} global option). 9361 9362The files created by @code{checkout} are created 9363read-write, unless the @samp{-r} option to @sc{cvs} 9364(@pxref{Global options}) is specified, the 9365@code{CVSREAD} environment variable is specified 9366(@pxref{Environment variables}), or a watch is in 9367effect for that file (@pxref{Watches}). 9368 9369Note that running @code{checkout} on a directory that was already 9370built by a prior @code{checkout} is also permitted. 9371This is similar to specifying the @samp{-d} option 9372to the @code{update} command in the sense that new 9373directories that have been created in the repository 9374will appear in your work area. 9375However, @code{checkout} takes a module name whereas 9376@code{update} takes a directory name. Also 9377to use @code{checkout} this way it must be run from the 9378top level directory (where you originally ran 9379@code{checkout} from), so before you run 9380@code{checkout} to update an existing directory, don't 9381forget to change your directory to the top level 9382directory. 9383 9384For the output produced by the @code{checkout} command 9385see @ref{update output}. 9386 9387@menu 9388* checkout options:: checkout options 9389* checkout examples:: checkout examples 9390@end menu 9391 9392@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9393@node checkout options 9394@appendixsubsec checkout options 9395 9396These standard options are supported by @code{checkout} 9397(@pxref{Common options}, for a complete description of 9398them): 9399 9400@table @code 9401@item -D @var{date} 9402Use the most recent revision no later than @var{date}. 9403This option is sticky, and implies @samp{-P}. See 9404@ref{Sticky tags}, for more information on sticky tags/dates. 9405 9406@item -f 9407Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision is 9408found, retrieve the most recent revision (instead of ignoring the file). 9409 9410@item -k @var{kflag} 9411Process keywords according to @var{kflag}. See 9412@ref{Keyword substitution}. 9413This option is sticky; future updates of 9414this file in this working directory will use the same 9415@var{kflag}. The @code{status} command can be viewed 9416to see the sticky options. See @ref{Invoking CVS}, for 9417more information on the @code{status} command. 9418 9419@item -l 9420Local; run only in current working directory. 9421 9422@item -n 9423Do not run any checkout program (as specified 9424with the @samp{-o} option in the modules file; 9425@pxref{modules}). 9426 9427@item -P 9428Prune empty directories. See @ref{Moving directories}. 9429 9430@item -p 9431Pipe files to the standard output. 9432 9433@item -R 9434Checkout directories recursively. This option is on by default. 9435 9436@item -r @var{tag}[:@var{date}] 9437Checkout the revision specified by @var{tag} or, when @var{date} is specified 9438and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9439existed on @var{date}. This option is sticky, and implies @samp{-P}. 9440See @ref{Sticky tags}, for more information on sticky tags/dates. Also, 9441see @ref{Common options}. 9442@end table 9443 9444In addition to those, you can use these special command 9445options with @code{checkout}: 9446 9447@table @code 9448@item -A 9449Reset any sticky tags, dates, or @samp{-k} options. 9450See @ref{Sticky tags}, for more information on sticky tags/dates. 9451 9452@item -c 9453Copy the module file, sorted, to the standard output, 9454instead of creating or modifying any files or 9455directories in your working directory. 9456 9457@item -d @var{dir} 9458Create a directory called @var{dir} for the working 9459files, instead of using the module name. In general, 9460using this flag is equivalent to using @samp{mkdir 9461@var{dir}; cd @var{dir}} followed by the checkout 9462command without the @samp{-d} flag. 9463 9464There is an important exception, however. It is very 9465convenient when checking out a single item to have the 9466output appear in a directory that doesn't contain empty 9467intermediate directories. In this case @emph{only}, 9468@sc{cvs} tries to ``shorten'' pathnames to avoid those empty 9469directories. 9470 9471For example, given a module @samp{foo} that contains 9472the file @samp{bar.c}, the command @samp{cvs co -d dir 9473foo} will create directory @samp{dir} and place 9474@samp{bar.c} inside. Similarly, given a module 9475@samp{bar} which has subdirectory @samp{baz} wherein 9476there is a file @samp{quux.c}, the command @samp{cvs co 9477-d dir bar/baz} will create directory @samp{dir} and 9478place @samp{quux.c} inside. 9479 9480Using the @samp{-N} flag will defeat this behavior. 9481Given the same module definitions above, @samp{cvs co 9482-N -d dir foo} will create directories @samp{dir/foo} 9483and place @samp{bar.c} inside, while @samp{cvs co -N -d 9484dir bar/baz} will create directories @samp{dir/bar/baz} 9485and place @samp{quux.c} inside. 9486 9487@item -j @var{tag} 9488With two @samp{-j} options, merge changes from the 9489revision specified with the first @samp{-j} option to 9490the revision specified with the second @samp{j} option, 9491into the working directory. 9492 9493With one @samp{-j} option, merge changes from the 9494ancestor revision to the revision specified with the 9495@samp{-j} option, into the working directory. The 9496ancestor revision is the common ancestor of the 9497revision which the working directory is based on, and 9498the revision specified in the @samp{-j} option. 9499 9500In addition, each -j option can contain an optional 9501date specification which, when used with branches, can 9502limit the chosen revision to one within a specific 9503date. An optional date is specified by adding a colon 9504(:) to the tag: 9505@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 9506 9507@xref{Branching and merging}. 9508 9509@item -N 9510Only useful together with @samp{-d @var{dir}}. With 9511this option, @sc{cvs} will not ``shorten'' module paths 9512in your working directory when you check out a single 9513module. See the @samp{-d} flag for examples and a 9514discussion. 9515 9516@item -s 9517Like @samp{-c}, but include the status of all modules, 9518and sort it by the status string. @xref{modules}, for 9519info about the @samp{-s} option that is used inside the 9520modules file to set the module status. 9521@end table 9522 9523@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9524@node checkout examples 9525@appendixsubsec checkout examples 9526 9527Get a copy of the module @samp{tc}: 9528 9529@example 9530$ cvs checkout tc 9531@end example 9532 9533Get a copy of the module @samp{tc} as it looked one day 9534ago: 9535 9536@example 9537$ cvs checkout -D yesterday tc 9538@end example 9539 9540@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9541@node commit 9542@appendixsec commit---Check files into the repository 9543@cindex commit (subcommand) 9544@cindex ci (subcommand) 9545 9546@itemize @bullet 9547@item 9548Synopsis: commit [-lnRf] [-m 'log_message' | 9549-F file] [-r revision] [files@dots{}] 9550@item 9551Requires: working directory, repository. 9552@item 9553Changes: repository. 9554@item 9555Synonym: ci 9556@end itemize 9557 9558Use @code{commit} when you want to incorporate changes 9559from your working source files into the source 9560repository. 9561 9562If you don't specify particular files to commit, all of 9563the files in your working current directory are 9564examined. @code{commit} is careful to change in the 9565repository only those files that you have really 9566changed. By default (or if you explicitly specify the 9567@samp{-R} option), files in subdirectories are also 9568examined and committed if they have changed; you can 9569use the @samp{-l} option to limit @code{commit} to the 9570current directory only. 9571 9572@code{commit} verifies that the selected files are up 9573to date with the current revisions in the source 9574repository; it will notify you, and exit without 9575committing, if any of the specified files must be made 9576current first with @code{update} (@pxref{update}). 9577@code{commit} does not call the @code{update} command 9578for you, but rather leaves that for you to do when the 9579time is right. 9580 9581When all is well, an editor is invoked to allow you to 9582enter a log message that will be written to one or more 9583logging programs (@pxref{modules}, and @pxref{loginfo}) 9584and placed in the @sc{rcs} file inside the 9585repository. This log message can be retrieved with the 9586@code{log} command (@pxref{log & rlog}). You can specify the 9587log message on the command line with the @samp{-m 9588@var{message}} option, and thus avoid the editor invocation, 9589or use the @samp{-F @var{file}} option to specify 9590that the argument file contains the log message. 9591 9592At @code{commit}, a unique commitid is placed in the @sc{rcs} 9593file inside the repository. All files committed at once 9594get the same commitid. The commitid can be retrieved with 9595the @code{log} and @code{status} command (@pxref{log & rlog}, 9596@pxref{File status}). 9597 9598@menu 9599* commit options:: commit options 9600* commit examples:: commit examples 9601@end menu 9602 9603@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9604@node commit options 9605@appendixsubsec commit options 9606 9607These standard options are supported by @code{commit} 9608(@pxref{Common options}, for a complete description of 9609them): 9610 9611@table @code 9612@item -l 9613Local; run only in current working directory. 9614 9615@item -R 9616Commit directories recursively. This is on by default. 9617 9618@item -r @var{revision} 9619Commit to @var{revision}. @var{revision} must be 9620either a branch, or a revision on the main trunk that 9621is higher than any existing revision number 9622(@pxref{Assigning revisions}). You 9623cannot commit to a specific revision on a branch. 9624@c FIXME: Need xref for branch case. 9625@end table 9626 9627@code{commit} also supports these options: 9628 9629@table @code 9630@item -c 9631Refuse to commit files unless the user has registered a valid edit on the 9632file via @code{cvs edit}. This is most useful when @samp{commit -c} 9633and @samp{edit -c} have been placed in all @file{.cvsrc} files. 9634A commit can be forced anyways by either registering an edit retroactively 9635via @code{cvs edit} (no changes to the file will be lost) or using the 9636@code{-f} option to commit. Support for @code{commit -c} requires both 9637client and a server versions 1.12.10 or greater. 9638 9639@item -F @var{file} 9640Read the log message from @var{file}, instead 9641of invoking an editor. 9642 9643@item -f 9644Note that this is not the standard behavior of 9645the @samp{-f} option as defined in @ref{Common options}. 9646 9647Force @sc{cvs} to commit a new revision even if you haven't 9648made any changes to the file. As of @sc{cvs} version 1.12.10, 9649it also causes the @code{-c} option to be ignored. If the current revision 9650of @var{file} is 1.7, then the following two commands 9651are equivalent: 9652 9653@example 9654$ cvs commit -f @var{file} 9655$ cvs commit -r 1.8 @var{file} 9656@end example 9657 9658@c This is odd, but it's how CVS has worked for some 9659@c time. 9660The @samp{-f} option disables recursion (i.e., it 9661implies @samp{-l}). To force @sc{cvs} to commit a new 9662revision for all files in all subdirectories, you must 9663use @samp{-f -R}. 9664 9665@item -m @var{message} 9666Use @var{message} as the log message, instead of 9667invoking an editor. 9668@end table 9669 9670@need 2000 9671@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9672@node commit examples 9673@appendixsubsec commit examples 9674 9675@c FIXME: this material wants to be somewhere 9676@c in "Branching and merging". 9677 9678@appendixsubsubsec Committing to a branch 9679 9680You can commit to a branch revision (one that has an 9681even number of dots) with the @samp{-r} option. To 9682create a branch revision, use the @samp{-b} option 9683of the @code{rtag} or @code{tag} commands 9684(@pxref{Branching and merging}). Then, either @code{checkout} or 9685@code{update} can be used to base your sources on the 9686newly created branch. From that point on, all 9687@code{commit} changes made within these working sources 9688will be automatically added to a branch revision, 9689thereby not disturbing main-line development in any 9690way. For example, if you had to create a patch to the 96911.2 version of the product, even though the 2.0 version 9692is already under development, you might do: 9693 9694@example 9695$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 9696$ cvs checkout -r FCS1_2_Patch product_module 9697$ cd product_module 9698[[ hack away ]] 9699$ cvs commit 9700@end example 9701 9702@noindent 9703This works automatically since the @samp{-r} option is 9704sticky. 9705 9706@appendixsubsubsec Creating the branch after editing 9707 9708Say you have been working on some extremely 9709experimental software, based on whatever revision you 9710happened to checkout last week. If others in your 9711group would like to work on this software with you, but 9712without disturbing main-line development, you could 9713commit your change to a new branch. Others can then 9714checkout your experimental stuff and utilize the full 9715benefit of @sc{cvs} conflict resolution. The scenario might 9716look like: 9717 9718@c FIXME: Should we be recommending tagging the branchpoint? 9719@example 9720[[ hacked sources are present ]] 9721$ cvs tag -b EXPR1 9722$ cvs update -r EXPR1 9723$ cvs commit 9724@end example 9725 9726The @code{update} command will make the @samp{-r 9727EXPR1} option sticky on all files. Note that your 9728changes to the files will never be removed by the 9729@code{update} command. The @code{commit} will 9730automatically commit to the correct branch, because the 9731@samp{-r} is sticky. You could also do like this: 9732 9733@c FIXME: Should we be recommending tagging the branchpoint? 9734@example 9735[[ hacked sources are present ]] 9736$ cvs tag -b EXPR1 9737$ cvs commit -r EXPR1 9738@end example 9739 9740@noindent 9741but then, only those files that were changed by you 9742will have the @samp{-r EXPR1} sticky flag. If you hack 9743away, and commit without specifying the @samp{-r EXPR1} 9744flag, some files may accidentally end up on the main 9745trunk. 9746 9747To work with you on the experimental change, others 9748would simply do 9749 9750@example 9751$ cvs checkout -r EXPR1 whatever_module 9752@end example 9753 9754@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9755@node diff 9756@appendixsec diff---Show differences between revisions 9757@cindex diff (subcommand) 9758 9759@itemize @bullet 9760@item 9761Synopsis: diff [-lR] [-k kflag] [format_options] [(-r rev1[:date1] | -D date1) [-r rev2[:date2] | -D date2]] [files@dots{}] 9762@item 9763Requires: working directory, repository. 9764@item 9765Changes: nothing. 9766@end itemize 9767 9768The @code{diff} command is used to compare different 9769revisions of files. The default action is to compare 9770your working files with the revisions they were based 9771on, and report any differences that are found. 9772 9773If any file names are given, only those files are 9774compared. If any directories are given, all files 9775under them will be compared. 9776 9777The exit status for diff is different than for other 9778@sc{cvs} commands; for details @ref{Exit status}. 9779 9780@menu 9781* diff options:: diff options 9782* diff examples:: diff examples 9783@end menu 9784 9785@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9786@node diff options 9787@appendixsubsec diff options 9788 9789These standard options are supported by @code{diff} 9790(@pxref{Common options}, for a complete description of 9791them): 9792 9793@table @code 9794@item -D @var{date} 9795Use the most recent revision no later than @var{date}. 9796See @samp{-r} for how this affects the comparison. 9797 9798@item -k @var{kflag} 9799Process keywords according to @var{kflag}. See 9800@ref{Keyword substitution}. 9801 9802@item -l 9803Local; run only in current working directory. 9804 9805@item -R 9806Examine directories recursively. This option is on by 9807default. 9808 9809@item -r @var{tag}[:@var{date}] 9810Compare with revision specified by @var{tag} or, when @var{date} is specified 9811and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9812existed on @var{date}. Zero, one or two 9813@samp{-r} options can be present. With no @samp{-r} 9814option, the working file will be compared with the 9815revision it was based on. With one @samp{-r}, that 9816revision will be compared to your current working file. 9817With two @samp{-r} options those two revisions will be 9818compared (and your working file will not affect the 9819outcome in any way). 9820@c We should be a lot more explicit, with examples, 9821@c about the difference between "cvs diff" and "cvs 9822@c diff -r HEAD". This often confuses new users. 9823 9824One or both @samp{-r} options can be replaced by a 9825@samp{-D @var{date}} option, described above. 9826@end table 9827 9828@c Conceptually, this is a disaster. There are 3 9829@c zillion diff formats that we support via the diff 9830@c library. It is not obvious to me that we should 9831@c document them all. Maybe just the most common ones 9832@c like -c and -u, and think about phasing out the 9833@c obscure ones. 9834@c FIXCVS: also should be a way to specify an external 9835@c diff program (which can be different for different 9836@c file types) and pass through 9837@c arbitrary options, so that the user can do 9838@c "--pass=-Z --pass=foo" or something even if CVS 9839@c doesn't know about the "-Z foo" option to diff. 9840@c This would fit nicely with deprecating/eliminating 9841@c the obscure options of the diff library, because it 9842@c would let people specify an external GNU diff if 9843@c they are into that sort of thing. 9844The following options specify the format of the 9845output. They have the same meaning as in GNU diff. 9846Most options have two equivalent names, one of which is a single letter 9847preceded by @samp{-}, and the other of which is a long name preceded by 9848@samp{--}. 9849 9850@table @samp 9851@item -@var{lines} 9852Show @var{lines} (an integer) lines of context. This option does not 9853specify an output format by itself; it has no effect unless it is 9854combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9855operation, @code{patch} typically needs at least two lines of context. 9856 9857@item -a 9858Treat all files as text and compare them line-by-line, even if they 9859do not seem to be text. 9860 9861@item -b 9862Ignore trailing white space and consider all other sequences of one or 9863more white space characters to be equivalent. 9864 9865@item -B 9866Ignore changes that just insert or delete blank lines. 9867 9868@item --binary 9869Read and write data in binary mode. 9870 9871@item --brief 9872Report only whether the files differ, not the details of the 9873differences. 9874 9875@item -c 9876Use the context output format. 9877 9878@item -C @var{lines} 9879@itemx --context@r{[}=@var{lines}@r{]} 9880Use the context output format, showing @var{lines} (an integer) lines of 9881context, or three if @var{lines} is not given. 9882For proper operation, @code{patch} typically needs at least two lines of 9883context. 9884 9885@item --changed-group-format=@var{format} 9886Use @var{format} to output a line group containing differing lines from 9887both files in if-then-else format. @xref{Line group formats}. 9888 9889@item -d 9890Change the algorithm to perhaps find a smaller set of changes. This makes 9891@code{diff} slower (sometimes much slower). 9892 9893@item -e 9894@itemx --ed 9895Make output that is a valid @code{ed} script. 9896 9897@item --expand-tabs 9898Expand tabs to spaces in the output, to preserve the alignment of tabs 9899in the input files. 9900 9901@item -f 9902Make output that looks vaguely like an @code{ed} script but has changes 9903in the order they appear in the file. 9904 9905@item -F @var{regexp} 9906In context and unified format, for each hunk of differences, show some 9907of the last preceding line that matches @var{regexp}. 9908 9909@item --forward-ed 9910Make output that looks vaguely like an @code{ed} script but has changes 9911in the order they appear in the file. 9912 9913@item -H 9914Use heuristics to speed handling of large files that have numerous 9915scattered small changes. 9916 9917@item --horizon-lines=@var{lines} 9918Do not discard the last @var{lines} lines of the common prefix 9919and the first @var{lines} lines of the common suffix. 9920 9921@item -i 9922Ignore changes in case; consider upper- and lower-case letters 9923equivalent. 9924 9925@item -I @var{regexp} 9926Ignore changes that just insert or delete lines that match @var{regexp}. 9927 9928@item --ifdef=@var{name} 9929Make merged if-then-else output using @var{name}. 9930 9931@item --ignore-all-space 9932Ignore white space when comparing lines. 9933 9934@item --ignore-blank-lines 9935Ignore changes that just insert or delete blank lines. 9936 9937@item --ignore-case 9938Ignore changes in case; consider upper- and lower-case to be the same. 9939 9940@item --ignore-matching-lines=@var{regexp} 9941Ignore changes that just insert or delete lines that match @var{regexp}. 9942 9943@item --ignore-space-change 9944Ignore trailing white space and consider all other sequences of one or 9945more white space characters to be equivalent. 9946 9947@item --initial-tab 9948Output a tab rather than a space before the text of a line in normal or 9949context format. This causes the alignment of tabs in the line to look 9950normal. 9951 9952@item -L @var{label} 9953Use @var{label} instead of the file name in the context format 9954and unified format headers. 9955 9956@item --label=@var{label} 9957Use @var{label} instead of the file name in the context format 9958and unified format headers. 9959 9960@item --left-column 9961Print only the left column of two common lines in side by side format. 9962 9963@item --line-format=@var{format} 9964Use @var{format} to output all input lines in if-then-else format. 9965@xref{Line formats}. 9966 9967@item --minimal 9968Change the algorithm to perhaps find a smaller set of changes. This 9969makes @code{diff} slower (sometimes much slower). 9970 9971@item -n 9972Output RCS-format diffs; like @samp{-f} except that each command 9973specifies the number of lines affected. 9974 9975@item -N 9976@itemx --new-file 9977In directory comparison, if a file is found in only one directory, 9978treat it as present but empty in the other directory. 9979 9980@item --new-group-format=@var{format} 9981Use @var{format} to output a group of lines taken from just the second 9982file in if-then-else format. @xref{Line group formats}. 9983 9984@item --new-line-format=@var{format} 9985Use @var{format} to output a line taken from just the second file in 9986if-then-else format. @xref{Line formats}. 9987 9988@item --old-group-format=@var{format} 9989Use @var{format} to output a group of lines taken from just the first 9990file in if-then-else format. @xref{Line group formats}. 9991 9992@item --old-line-format=@var{format} 9993Use @var{format} to output a line taken from just the first file in 9994if-then-else format. @xref{Line formats}. 9995 9996@item -p 9997Show which C function each change is in. 9998 9999@item --rcs 10000Output RCS-format diffs; like @samp{-f} except that each command 10001specifies the number of lines affected. 10002 10003@item --report-identical-files 10004@itemx -s 10005Report when two files are the same. 10006 10007@item --show-c-function 10008Show which C function each change is in. 10009 10010@item --show-function-line=@var{regexp} 10011In context and unified format, for each hunk of differences, show some 10012of the last preceding line that matches @var{regexp}. 10013 10014@item --side-by-side 10015Use the side by side output format. 10016 10017@item --speed-large-files 10018Use heuristics to speed handling of large files that have numerous 10019scattered small changes. 10020 10021@item --suppress-common-lines 10022Do not print common lines in side by side format. 10023 10024@item -t 10025Expand tabs to spaces in the output, to preserve the alignment of tabs 10026in the input files. 10027 10028@item -T 10029Output a tab rather than a space before the text of a line in normal or 10030context format. This causes the alignment of tabs in the line to look 10031normal. 10032 10033@item --text 10034Treat all files as text and compare them line-by-line, even if they 10035do not appear to be text. 10036 10037@item -u 10038Use the unified output format. 10039 10040@item --unchanged-group-format=@var{format} 10041Use @var{format} to output a group of common lines taken from both files 10042in if-then-else format. @xref{Line group formats}. 10043 10044@item --unchanged-line-format=@var{format} 10045Use @var{format} to output a line common to both files in if-then-else 10046format. @xref{Line formats}. 10047 10048@item -U @var{lines} 10049@itemx --unified@r{[}=@var{lines}@r{]} 10050Use the unified output format, showing @var{lines} (an integer) lines of 10051context, or three if @var{lines} is not given. 10052For proper operation, @code{patch} typically needs at least two lines of 10053context. 10054 10055@item -w 10056Ignore white space when comparing lines. 10057 10058@item -W @var{columns} 10059@itemx --width=@var{columns} 10060Use an output width of @var{columns} in side by side format. 10061 10062@item -y 10063Use the side by side output format. 10064@end table 10065 10066@menu 10067* Line group formats:: Line group formats 10068* Line formats:: Line formats 10069@end menu 10070 10071@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10072@node Line group formats 10073@appendixsubsubsec Line group formats 10074 10075Line group formats let you specify formats suitable for many 10076applications that allow if-then-else input, including programming 10077languages and text formatting languages. A line group format specifies 10078the output format for a contiguous group of similar lines. 10079 10080For example, the following command compares the TeX file @file{myfile} 10081with the original version from the repository, 10082and outputs a merged file in which old regions are 10083surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 10084regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 10085 10086@example 10087cvs diff \ 10088 --old-group-format='\begin@{em@} 10089%<\end@{em@} 10090' \ 10091 --new-group-format='\begin@{bf@} 10092%>\end@{bf@} 10093' \ 10094 myfile 10095@end example 10096 10097The following command is equivalent to the above example, but it is a 10098little more verbose, because it spells out the default line group formats. 10099 10100@example 10101cvs diff \ 10102 --old-group-format='\begin@{em@} 10103%<\end@{em@} 10104' \ 10105 --new-group-format='\begin@{bf@} 10106%>\end@{bf@} 10107' \ 10108 --unchanged-group-format='%=' \ 10109 --changed-group-format='\begin@{em@} 10110%<\end@{em@} 10111\begin@{bf@} 10112%>\end@{bf@} 10113' \ 10114 myfile 10115@end example 10116 10117Here is a more advanced example, which outputs a diff listing with 10118headers containing line numbers in a ``plain English'' style. 10119 10120@example 10121cvs diff \ 10122 --unchanged-group-format='' \ 10123 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 10124%<' \ 10125 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 10126%>' \ 10127 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 10128%<-------- to: 10129%>' \ 10130 myfile 10131@end example 10132 10133To specify a line group format, use one of the options 10134listed below. You can specify up to four line group formats, one for 10135each kind of line group. You should quote @var{format}, because it 10136typically contains shell metacharacters. 10137 10138@table @samp 10139@item --old-group-format=@var{format} 10140These line groups are hunks containing only lines from the first file. 10141The default old group format is the same as the changed group format if 10142it is specified; otherwise it is a format that outputs the line group as-is. 10143 10144@item --new-group-format=@var{format} 10145These line groups are hunks containing only lines from the second 10146file. The default new group format is same as the changed group 10147format if it is specified; otherwise it is a format that outputs the 10148line group as-is. 10149 10150@item --changed-group-format=@var{format} 10151These line groups are hunks containing lines from both files. The 10152default changed group format is the concatenation of the old and new 10153group formats. 10154 10155@item --unchanged-group-format=@var{format} 10156These line groups contain lines common to both files. The default 10157unchanged group format is a format that outputs the line group as-is. 10158@end table 10159 10160In a line group format, ordinary characters represent themselves; 10161conversion specifications start with @samp{%} and have one of the 10162following forms. 10163 10164@table @samp 10165@item %< 10166stands for the lines from the first file, including the trailing newline. 10167Each line is formatted according to the old line format (@pxref{Line formats}). 10168 10169@item %> 10170stands for the lines from the second file, including the trailing newline. 10171Each line is formatted according to the new line format. 10172 10173@item %= 10174stands for the lines common to both files, including the trailing newline. 10175Each line is formatted according to the unchanged line format. 10176 10177@item %% 10178stands for @samp{%}. 10179 10180@item %c'@var{C}' 10181where @var{C} is a single character, stands for @var{C}. 10182@var{C} may not be a backslash or an apostrophe. 10183For example, @samp{%c':'} stands for a colon, even inside 10184the then-part of an if-then-else format, which a colon would 10185normally terminate. 10186 10187@item %c'\@var{O}' 10188where @var{O} is a string of 1, 2, or 3 octal digits, 10189stands for the character with octal code @var{O}. 10190For example, @samp{%c'\0'} stands for a null character. 10191 10192@item @var{F}@var{n} 10193where @var{F} is a @code{printf} conversion specification and @var{n} is one 10194of the following letters, stands for @var{n}'s value formatted with @var{F}. 10195 10196@table @samp 10197@item e 10198The line number of the line just before the group in the old file. 10199 10200@item f 10201The line number of the first line in the group in the old file; 10202equals @var{e} + 1. 10203 10204@item l 10205The line number of the last line in the group in the old file. 10206 10207@item m 10208The line number of the line just after the group in the old file; 10209equals @var{l} + 1. 10210 10211@item n 10212The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 10213 10214@item E, F, L, M, N 10215Likewise, for lines in the new file. 10216 10217@end table 10218 10219The @code{printf} conversion specification can be @samp{%d}, 10220@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 10221lower case hexadecimal, or upper case hexadecimal output 10222respectively. After the @samp{%} the following options can appear in 10223sequence: a @samp{-} specifying left-justification; an integer 10224specifying the minimum field width; and a period followed by an 10225optional integer specifying the minimum number of digits. 10226For example, @samp{%5dN} prints the number of new lines in the group 10227in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 10228 10229@item (@var{A}=@var{B}?@var{T}:@var{E}) 10230If @var{A} equals @var{B} then @var{T} else @var{E}. 10231@var{A} and @var{B} are each either a decimal constant 10232or a single letter interpreted as above. 10233This format spec is equivalent to @var{T} if 10234@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 10235 10236For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 10237@samp{no lines} if @var{N} (the number of lines in the group in the 10238new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 10239otherwise. 10240@end table 10241 10242@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10243@node Line formats 10244@appendixsubsubsec Line formats 10245 10246Line formats control how each line taken from an input file is 10247output as part of a line group in if-then-else format. 10248 10249For example, the following command outputs text with a one-column 10250change indicator to the left of the text. The first column of output 10251is @samp{-} for deleted lines, @samp{|} for added lines, and a space 10252for unchanged lines. The formats contain newline characters where 10253newlines are desired on output. 10254 10255@example 10256cvs diff \ 10257 --old-line-format='-%l 10258' \ 10259 --new-line-format='|%l 10260' \ 10261 --unchanged-line-format=' %l 10262' \ 10263 myfile 10264@end example 10265 10266To specify a line format, use one of the following options. You should 10267quote @var{format}, since it often contains shell metacharacters. 10268 10269@table @samp 10270@item --old-line-format=@var{format} 10271formats lines just from the first file. 10272 10273@item --new-line-format=@var{format} 10274formats lines just from the second file. 10275 10276@item --unchanged-line-format=@var{format} 10277formats lines common to both files. 10278 10279@item --line-format=@var{format} 10280formats all lines; in effect, it sets all three above options simultaneously. 10281@end table 10282 10283In a line format, ordinary characters represent themselves; 10284conversion specifications start with @samp{%} and have one of the 10285following forms. 10286 10287@table @samp 10288@item %l 10289stands for the contents of the line, not counting its trailing 10290newline (if any). This format ignores whether the line is incomplete. 10291 10292@item %L 10293stands for the contents of the line, including its trailing newline 10294(if any). If a line is incomplete, this format preserves its 10295incompleteness. 10296 10297@item %% 10298stands for @samp{%}. 10299 10300@item %c'@var{C}' 10301where @var{C} is a single character, stands for @var{C}. 10302@var{C} may not be a backslash or an apostrophe. 10303For example, @samp{%c':'} stands for a colon. 10304 10305@item %c'\@var{O}' 10306where @var{O} is a string of 1, 2, or 3 octal digits, 10307stands for the character with octal code @var{O}. 10308For example, @samp{%c'\0'} stands for a null character. 10309 10310@item @var{F}n 10311where @var{F} is a @code{printf} conversion specification, 10312stands for the line number formatted with @var{F}. 10313For example, @samp{%.5dn} prints the line number using the 10314@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 10315more about printf conversion specifications. 10316 10317@end table 10318 10319The default line format is @samp{%l} followed by a newline character. 10320 10321If the input contains tab characters and it is important that they line 10322up on output, you should ensure that @samp{%l} or @samp{%L} in a line 10323format is just after a tab stop (e.g.@: by preceding @samp{%l} or 10324@samp{%L} with a tab character), or you should use the @samp{-t} or 10325@samp{--expand-tabs} option. 10326 10327Taken together, the line and line group formats let you specify many 10328different formats. For example, the following command uses a format 10329similar to @code{diff}'s normal format. You can tailor this command 10330to get fine control over @code{diff}'s output. 10331 10332@example 10333cvs diff \ 10334 --old-line-format='< %l 10335' \ 10336 --new-line-format='> %l 10337' \ 10338 --old-group-format='%df%(f=l?:,%dl)d%dE 10339%<' \ 10340 --new-group-format='%dea%dF%(F=L?:,%dL) 10341%>' \ 10342 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 10343%<--- 10344%>' \ 10345 --unchanged-group-format='' \ 10346 myfile 10347@end example 10348 10349@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10350@node diff examples 10351@appendixsubsec diff examples 10352 10353The following line produces a Unidiff (@samp{-u} flag) 10354between revision 1.14 and 1.19 of 10355@file{backend.c}. Due to the @samp{-kk} flag no 10356keywords are substituted, so differences that only depend 10357on keyword substitution are ignored. 10358 10359@example 10360$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 10361@end example 10362 10363Suppose the experimental branch EXPR1 was based on a 10364set of files tagged RELEASE_1_0. To see what has 10365happened on that branch, the following can be used: 10366 10367@example 10368$ cvs diff -r RELEASE_1_0 -r EXPR1 10369@end example 10370 10371A command like this can be used to produce a context 10372diff between two releases: 10373 10374@example 10375$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 10376@end example 10377 10378If you are maintaining ChangeLogs, a command like the following 10379just before you commit your changes may help you write 10380the ChangeLog entry. All local modifications that have 10381not yet been committed will be printed. 10382 10383@example 10384$ cvs diff -u | less 10385@end example 10386 10387@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10388@node export 10389@appendixsec export---Export sources from CVS, similar to checkout 10390@cindex export (subcommand) 10391 10392@itemize @bullet 10393@item 10394Synopsis: export [-flNnR] (-r rev[:date] | -D date) [-k subst] [-d dir] module@dots{} 10395@item 10396Requires: repository. 10397@item 10398Changes: current directory. 10399@end itemize 10400 10401This command is a variant of @code{checkout}; use it 10402when you want a copy of the source for module without 10403the @sc{cvs} administrative directories. For example, you 10404might use @code{export} to prepare source for shipment 10405off-site. This command requires that you specify a 10406date or tag (with @samp{-D} or @samp{-r}), so that you 10407can count on reproducing the source you ship to others 10408(and thus it always prunes empty directories). 10409 10410One often would like to use @samp{-kv} with @code{cvs 10411export}. This causes any keywords to be 10412expanded such that an import done at some other site 10413will not lose the keyword revision information. But be 10414aware that doesn't handle an export containing binary 10415files correctly. Also be aware that after having used 10416@samp{-kv}, one can no longer use the @code{ident} 10417command (which is part of the @sc{rcs} suite---see 10418ident(1)) which looks for keyword strings. If 10419you want to be able to use @code{ident} you must not 10420use @samp{-kv}. 10421 10422@menu 10423* export options:: export options 10424@end menu 10425 10426@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10427@node export options 10428@appendixsubsec export options 10429 10430These standard options are supported by @code{export} 10431(@pxref{Common options}, for a complete description of 10432them): 10433 10434@table @code 10435@item -D @var{date} 10436Use the most recent revision no later than @var{date}. 10437 10438@item -f 10439If no matching revision is found, retrieve the most 10440recent revision (instead of ignoring the file). 10441 10442@item -l 10443Local; run only in current working directory. 10444 10445@item -n 10446Do not run any checkout program. 10447 10448@item -R 10449Export directories recursively. This is on by default. 10450 10451@item -r @var{tag}[:@var{date}] 10452Export the revision specified by @var{tag} or, when @var{date} is specified 10453and @var{tag} is a branch tag, the version from the branch @var{tag} as it 10454existed on @var{date}. See @ref{Common options}. 10455@end table 10456 10457In addition, these options (that are common to 10458@code{checkout} and @code{export}) are also supported: 10459 10460@table @code 10461@item -d @var{dir} 10462Create a directory called @var{dir} for the working 10463files, instead of using the module name. 10464@xref{checkout options}, for complete details on how 10465@sc{cvs} handles this flag. 10466 10467@item -k @var{subst} 10468Set keyword expansion mode (@pxref{Substitution modes}). 10469 10470@item -N 10471Only useful together with @samp{-d @var{dir}}. 10472@xref{checkout options}, for complete details on how 10473@sc{cvs} handles this flag. 10474@end table 10475 10476@ignore 10477@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10478@c @node export examples 10479@appendixsubsec export examples 10480 10481Contributed examples are gratefully accepted. 10482@c -- Examples here!! 10483@end ignore 10484 10485@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10486@node history 10487@appendixsec history---Show status of files and users 10488@cindex history (subcommand) 10489 10490@itemize @bullet 10491@item 10492Synopsis: history [-report] [-flags] [-options args] [files@dots{}] 10493@item 10494Requires: the file @file{$CVSROOT/CVSROOT/history} 10495@item 10496Changes: nothing. 10497@end itemize 10498 10499@sc{cvs} can keep a history log that tracks each use of most @sc{cvs} 10500commands. You can use @code{history} to display this information in 10501various formats. 10502 10503To enable logging, the @samp{LogHistory} config option must be set to 10504some value other than the empty string and the history file specified by 10505the @samp{HistoryLogPath} option must be writable by all users who may run 10506the @sc{cvs} executable (@pxref{config}). 10507 10508To enable the @code{history} command, logging must be enabled as above and 10509the @samp{HistorySearchPath} config option (@pxref{config}) must be set to 10510specify some number of the history logs created thereby and these files must 10511be readable by each user who might run the @code{history} command. 10512 10513Creating a repository via the @code{cvs init} command will enable logging of 10514all possible events to a single history log file 10515(@file{$CVSROOT/CVSROOT/history}) with read and write permissions for all 10516users (@pxref{Creating a repository}). 10517 10518@strong{Note: @code{history} uses @samp{-f}, @samp{-l}, 10519@samp{-n}, and @samp{-p} in ways that conflict with the 10520normal use inside @sc{cvs} (@pxref{Common options}).} 10521 10522@menu 10523* history options:: history options 10524@end menu 10525 10526@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10527@node history options 10528@appendixsubsec history options 10529 10530Several options (shown above as @samp{-report}) control what 10531kind of report is generated: 10532 10533@table @code 10534@item -c 10535Report on each time commit was used (i.e., each time 10536the repository was modified). 10537 10538@item -e 10539Everything (all record types). Equivalent to 10540specifying @samp{-x} with all record types. Of course, 10541@samp{-e} will also include record types which are 10542added in a future version of @sc{cvs}; if you are 10543writing a script which can only handle certain record 10544types, you'll want to specify @samp{-x}. 10545 10546@item -m @var{module} 10547Report on a particular module. (You can meaningfully 10548use @samp{-m} more than once on the command line.) 10549 10550@item -o 10551Report on checked-out modules. This is the default report type. 10552 10553@item -T 10554Report on all tags. 10555 10556@item -x @var{type} 10557Extract a particular set of record types @var{type} from the @sc{cvs} 10558history. The types are indicated by single letters, 10559which you may specify in combination. 10560 10561Certain commands have a single record type: 10562 10563@table @code 10564@item F 10565release 10566@item O 10567checkout 10568@item E 10569export 10570@item T 10571tag and rtag 10572@end table 10573 10574@noindent 10575One of five record types may result from an update: 10576 10577@table @code 10578@item C 10579A merge was necessary but collisions were 10580detected (requiring manual merging). 10581@item G 10582A merge was necessary and it succeeded. 10583@item U 10584A working file was copied from the repository. 10585@item P 10586A working file was patched to match the repository. 10587@item W 10588The working copy of a file was deleted during 10589update (because it was gone from the repository). 10590@end table 10591 10592@noindent 10593One of three record types results from commit: 10594 10595@table @code 10596@item A 10597A file was added for the first time. 10598@item M 10599A file was modified. 10600@item R 10601A file was removed. 10602@end table 10603 10604@noindent 10605One record type results from the admin command: 10606@table @code 10607@item X 10608The admin command. 10609@end table 10610@end table 10611 10612The options shown as @samp{-flags} constrain or expand 10613the report without requiring option arguments: 10614 10615@table @code 10616@item -a 10617Show data for all users (the default is to show data 10618only for the user executing @code{history}). 10619 10620@item -l 10621Show last modification only. 10622 10623@item -w 10624Show only the records for modifications done from the 10625same working directory where @code{history} is 10626executing. 10627@end table 10628 10629The options shown as @samp{-options @var{args}} constrain the report 10630based on an argument: 10631 10632@table @code 10633@item -b @var{str} 10634Show data back to a record containing the string 10635@var{str} in either the module name, the file name, or 10636the repository path. 10637 10638@item -D @var{date} 10639Show data since @var{date}. This is slightly different 10640from the normal use of @samp{-D @var{date}}, which 10641selects the newest revision older than @var{date}. 10642 10643@item -f @var{file} 10644Show data for a particular file 10645(you can specify several @samp{-f} options on the same command line). 10646This is equivalent to specifying the file on the command line. 10647 10648@item -n @var{module} 10649Show data for a particular module 10650(you can specify several @samp{-n} options on the same command line). 10651 10652@item -p @var{repository} 10653Show data for a particular source repository (you 10654can specify several @samp{-p} options on the same command 10655line). 10656 10657@item -r @var{rev} 10658Show records referring to revisions since the revision 10659or tag named @var{rev} appears in individual @sc{rcs} 10660files. Each @sc{rcs} file is searched for the revision or 10661tag. 10662 10663@item -t @var{tag} 10664Show records since tag @var{tag} was last added to the 10665history file. This differs from the @samp{-r} flag 10666above in that it reads only the history file, not the 10667@sc{rcs} files, and is much faster. 10668 10669@item -u @var{name} 10670Show records for user @var{name}. 10671 10672@item -z @var{timezone} 10673Show times in the selected records using the specified 10674time zone instead of UTC. 10675@end table 10676 10677@ignore 10678@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10679@c @node history examples 10680@appendixsubsec history examples 10681 10682Contributed examples will gratefully be accepted. 10683@c -- Examples here! 10684@end ignore 10685 10686@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10687@node import 10688@appendixsec import---Import sources into CVS, using vendor branches 10689@cindex import (subcommand) 10690 10691@c FIXME: This node is way too long for one which has subnodes. 10692 10693@itemize @bullet 10694@item 10695Synopsis: import [-options] repository vendortag releasetag@dots{} 10696@item 10697Requires: Repository, source distribution directory. 10698@item 10699Changes: repository. 10700@end itemize 10701 10702Use @code{import} to incorporate an entire source 10703distribution from an outside source (e.g., a source 10704vendor) into your source repository directory. You can 10705use this command both for initial creation of a 10706repository, and for wholesale updates to the module 10707from the outside source. @xref{Tracking sources}, for 10708a discussion on this subject. 10709 10710The @var{repository} argument gives a directory name 10711(or a path to a directory) under the @sc{cvs} root directory 10712for repositories; if the directory did not exist, 10713import creates it. 10714 10715When you use import for updates to source that has been 10716modified in your source repository (since a prior 10717import), it will notify you of any files that conflict 10718in the two branches of development; use @samp{checkout 10719-j} to reconcile the differences, as import instructs 10720you to do. 10721 10722If @sc{cvs} decides a file should be ignored 10723(@pxref{cvsignore}), it does not import it and prints 10724@samp{I } followed by the filename (@pxref{import output}, for a 10725complete description of the output). 10726 10727If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 10728any file whose names match the specifications in that 10729file will be treated as packages and the appropriate 10730filtering will be performed on the file/directory 10731before being imported. @xref{Wrappers}. 10732 10733The outside source is saved in a first-level 10734branch, by default 1.1.1. Updates are leaves of this 10735branch; for example, files from the first imported 10736collection of source will be revision 1.1.1.1, then 10737files from the first imported update will be revision 107381.1.1.2, and so on. 10739 10740At least three arguments are required. 10741@var{repository} is needed to identify the collection 10742of source. @var{vendortag} is a tag for the entire 10743branch (e.g., for 1.1.1). You must also specify at 10744least one @var{releasetag} to uniquely identify the files at 10745the leaves created each time you execute @code{import}. The 10746@var{releasetag} should be new, not previously existing in the 10747repository file, and uniquely identify the imported release, 10748 10749@c I'm not completely sure this belongs here. But 10750@c we need to say it _somewhere_ reasonably obvious; it 10751@c is a common misconception among people first learning CVS 10752Note that @code{import} does @emph{not} change the 10753directory in which you invoke it. In particular, it 10754does not set up that directory as a @sc{cvs} working 10755directory; if you want to work with the sources import 10756them first and then check them out into a different 10757directory (@pxref{Getting the source}). 10758 10759@menu 10760* import options:: import options 10761* import output:: import output 10762* import examples:: import examples 10763@end menu 10764 10765@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10766@node import options 10767@appendixsubsec import options 10768 10769This standard option is supported by @code{import} 10770(@pxref{Common options}, for a complete description): 10771 10772@table @code 10773@item -m @var{message} 10774Use @var{message} as log information, instead of 10775invoking an editor. 10776@end table 10777 10778There are the following additional special options. 10779 10780@table @code 10781@item -b @var{branch} 10782See @ref{Multiple vendor branches}. 10783 10784@item -k @var{subst} 10785Indicate the keyword expansion mode desired. This 10786setting will apply to all files created during the 10787import, but not to any files that previously existed in 10788the repository. See @ref{Substitution modes}, for a 10789list of valid @samp{-k} settings. 10790 10791@item -I @var{name} 10792Specify file names that should be ignored during 10793import. You can use this option repeatedly. To avoid 10794ignoring any files at all (even those ignored by 10795default), specify `-I !'. 10796 10797@var{name} can be a file name pattern of the same type 10798that you can specify in the @file{.cvsignore} file. 10799@xref{cvsignore}. 10800@c -- Is this really true? 10801 10802@item -W @var{spec} 10803Specify file names that should be filtered during 10804import. You can use this option repeatedly. 10805 10806@var{spec} can be a file name pattern of the same type 10807that you can specify in the @file{.cvswrappers} 10808file. @xref{Wrappers}. 10809 10810@item -X 10811Modify the algorithm used by @sc{cvs} when importing new files 10812so that new files do not immediately appear on the main trunk. 10813 10814Specifically, this flag causes @sc{cvs} to mark new files as 10815if they were deleted on the main trunk, by taking the following 10816steps for each file in addition to those normally taken on import: 10817creating a new revision on the main trunk indicating that 10818the new file is @code{dead}, resetting the new file's default branch, 10819and placing the file in the Attic (@pxref{Attic}) directory. 10820 10821Use of this option can be forced on a repository-wide basis 10822by setting the @samp{ImportNewFilesToVendorBranchOnly} option in 10823CVSROOT/config (@pxref{config}). 10824@end table 10825 10826@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10827@node import output 10828@appendixsubsec import output 10829 10830@code{import} keeps you informed of its progress by printing a line 10831for each file, preceded by one character indicating the status of the file: 10832 10833@table @code 10834@item U @var{file} 10835The file already exists in the repository and has not been locally 10836modified; a new revision has been created (if necessary). 10837 10838@item N @var{file} 10839The file is a new file which has been added to the repository. 10840 10841@item C @var{file} 10842The file already exists in the repository but has been locally modified; 10843you will have to merge the changes. 10844 10845@item I @var{file} 10846The file is being ignored (@pxref{cvsignore}). 10847 10848@cindex Symbolic link, importing 10849@cindex Link, symbolic, importing 10850@c FIXME: also (somewhere else) probably 10851@c should be documenting what happens if you "cvs add" 10852@c a symbolic link. Also maybe what happens if 10853@c you manually create symbolic links within the 10854@c repository (? - not sure why we'd want to suggest 10855@c doing that). 10856@item L @var{file} 10857The file is a symbolic link; @code{cvs import} ignores symbolic links. 10858People periodically suggest that this behavior should 10859be changed, but if there is a consensus on what it 10860should be changed to, it is not apparent. 10861(Various options in the @file{modules} file can be used 10862to recreate symbolic links on checkout, update, etc.; 10863@pxref{modules}.) 10864@end table 10865 10866@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10867@node import examples 10868@appendixsubsec import examples 10869 10870See @ref{Tracking sources}, and @ref{From files}. 10871 10872@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10873@node init 10874@appendixsec init---Initialize a repository 10875@cindex init (subcommand) 10876 10877@itemize @bullet 10878@item 10879Synopsis: init 10880@item 10881Requires: working directory. 10882@item 10883Changes: repository, working directory. 10884@end itemize 10885 10886The @code{init} command initializes a repository by adding the 10887@file{CVSROOT} subdirectory and some default control files. You must 10888use this command or initialize the repository in some other way before 10889you can use it. Specify the root of the repository with the general 10890@code{-d} option. This will set up an empty repository in the 10891@sc{cvs} root specified in the usual way (@pxref{Repository}). 10892 10893@code{init} is careful to never overwrite any existing files in the 10894repository, so no harm is done if you run @code{init} on an already 10895set-up repository. Note you may need to be a member of the group 10896@code{cvsadmin} to do this. 10897 10898Note @code{init} will enable history logging; if you don't want that, 10899remove the history file after running @code{init} (@pxref{history file}). 10900 10901@menu 10902* init examples: init examples 10903@end menu 10904 10905@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10906@node init examples 10907@appendixsubsec init examples 10908 10909@example 10910$ cvs -d /usr/local/cvsroot init 10911@end example 10912 10913@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10914@node log & rlog 10915@appendixsec log & rlog---Print out log information for files 10916@cindex log (subcommand) 10917@cindex rlog (subcommand) 10918 10919@itemize @bullet 10920@item 10921Synopsis: log [options] [files@dots{}] 10922@item 10923Requires: repository, working directory. 10924@item 10925Changes: nothing. 10926@end itemize 10927 10928Display log information for files. @code{log} used to 10929call the @sc{rcs} utility @code{rlog}. Although this 10930is no longer true in the current sources, this history 10931determines the format of the output and the options, 10932which are not quite in the style of the other @sc{cvs} 10933commands. 10934 10935@cindex Timezone, in output 10936@cindex Zone, time, in output 10937The output includes the location of the @sc{rcs} file, 10938the @dfn{head} revision (the latest revision on the 10939trunk), all symbolic names (tags) and some other 10940things. For each revision, the revision number, the 10941date, the author, the number of lines added/deleted, the commitid 10942and the log message are printed. All dates are displayed 10943in local time at the client. This is typically specified in 10944the @code{$TZ} environment variable, which can be set to 10945govern how @code{log} displays dates. 10946 10947@strong{Note: @code{log} uses @samp{-R} in a way that conflicts 10948with the normal use inside @sc{cvs} (@pxref{Common options}).} 10949 10950@menu 10951* log options:: log options 10952* log examples:: log examples 10953@end menu 10954 10955@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10956@node log options 10957@appendixsubsec log options 10958 10959By default, @code{log} prints all information that is 10960available. All other options restrict the output. Note that the revision 10961selection options (@code{-d}, @code{-r}, @code{-s}, and @code{-w}) have no 10962effect, other than possibly causing a search for files in Attic directories, 10963when used in conjunction with the options that restrict the output to only 10964@code{log} header fields (@code{-b}, @code{-h}, @code{-R}, and @code{-t}) 10965unless the @code{-S} option is also specified. 10966 10967@table @code 10968@item -b 10969Print information about the revisions on the default 10970branch, normally the highest branch on the trunk. 10971 10972@item -d @var{dates} 10973Print information about revisions with a checkin 10974date/time in the range given by the 10975semicolon-separated list of dates. The date formats 10976accepted are those accepted by the @samp{-D} option to 10977many other @sc{cvs} commands (@pxref{Common options}). 10978Dates can be combined into ranges as follows: 10979 10980@c Should we be thinking about accepting ISO8601 10981@c ranges? For example "1972-09-10/1972-09-12". 10982@table @code 10983@item @var{d1}<@var{d2} 10984@itemx @var{d2}>@var{d1} 10985Select the revisions that were deposited between 10986@var{d1} and @var{d2}. 10987 10988@item <@var{d} 10989@itemx @var{d}> 10990Select all revisions dated @var{d} or earlier. 10991 10992@item @var{d}< 10993@itemx >@var{d} 10994Select all revisions dated @var{d} or later. 10995 10996@item @var{d} 10997Select the single, latest revision dated @var{d} or 10998earlier. 10999@end table 11000 11001The @samp{>} or @samp{<} characters may be followed by 11002@samp{=} to indicate an inclusive range rather than an 11003exclusive one. 11004 11005Note that the separator is a semicolon (;). 11006 11007@item -h 11008Print only the name of the @sc{rcs} file, name 11009of the file in the working directory, head, 11010default branch, access list, locks, symbolic names, and 11011suffix. 11012 11013@item -l 11014Local; run only in current working directory. (Default 11015is to run recursively). 11016 11017@item -N 11018Do not print the list of tags for this file. This 11019option can be very useful when your site uses a lot of 11020tags, so rather than "more"'ing over 3 pages of tag 11021information, the log information is presented without 11022tags at all. 11023 11024@item -R 11025Print only the name of the @sc{rcs} file. 11026 11027@c Note that using a bare revision (in addition to not 11028@c being explicitly documented here) is potentially 11029@c confusing; it shows the log message to get from the 11030@c previous revision to that revision. "-r1.3 -r1.6" 11031@c (equivalent to "-r1.3,1.6") is even worse; it 11032@c prints the messages to get from 1.2 to 1.3 and 1.5 11033@c to 1.6. By analogy with "cvs diff", users might 11034@c expect that it is more like specifying a range. 11035@c It is not 100% clear to me how much of this should 11036@c be documented (for example, multiple -r options 11037@c perhaps could/should be deprecated given the false 11038@c analogy with "cvs diff"). 11039@c In general, this section should be rewritten to talk 11040@c about messages to get from revision rev1 to rev2, 11041@c rather than messages for revision rev2 (that is, the 11042@c messages are associated with a change not a static 11043@c revision and failing to make this distinction causes 11044@c much confusion). 11045@item -r@var{revisions} 11046Print information about revisions given in the 11047comma-separated list @var{revisions} of revisions and 11048ranges. The following table explains the available 11049range formats: 11050 11051@table @code 11052@item @var{rev1}:@var{rev2} 11053Revisions @var{rev1} to @var{rev2} (which must be on 11054the same branch). 11055 11056@item @var{rev1}::@var{rev2} 11057The same, but excluding @var{rev1}. 11058 11059@item :@var{rev} 11060@itemx ::@var{rev} 11061Revisions from the beginning of the branch up to 11062and including @var{rev}. 11063 11064@item @var{rev}: 11065Revisions starting with @var{rev} to the end of the 11066branch containing @var{rev}. 11067 11068@item @var{rev}:: 11069Revisions starting just after @var{rev} to the end of the 11070branch containing @var{rev}. 11071 11072@item @var{branch} 11073An argument that is a branch means all revisions on 11074that branch. 11075 11076@item @var{branch1}:@var{branch2} 11077@itemx @var{branch1}::@var{branch2} 11078A range of branches means all revisions 11079on the branches in that range. 11080 11081@item @var{branch}. 11082The latest revision in @var{branch}. 11083@end table 11084 11085A bare @samp{-r} with no revisions means the latest 11086revision on the default branch, normally the trunk. 11087There can be no space between the @samp{-r} option and 11088its argument. 11089 11090@item -S 11091Suppress the header if no revisions are selected. 11092 11093@item -s @var{states} 11094Print information about revisions whose state 11095attributes match one of the states given in the 11096comma-separated list @var{states}. Individual states may 11097be any text string, though @sc{cvs} commonly only uses two 11098states, @samp{Exp} and @samp{dead}. See @ref{admin options} 11099for more information. 11100 11101@item -t 11102Print the same as @samp{-h}, plus the descriptive text. 11103 11104@item -w@var{logins} 11105Print information about revisions checked in by users 11106with login names appearing in the comma-separated list 11107@var{logins}. If @var{logins} is omitted, the user's 11108login is assumed. There can be no space between the 11109@samp{-w} option and its argument. 11110@end table 11111 11112@code{log} prints the intersection of the revisions 11113selected with the options @samp{-d}, @samp{-s}, and 11114@samp{-w}, intersected with the union of the revisions 11115selected by @samp{-b} and @samp{-r}. 11116 11117@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11118@node log examples 11119@appendixsubsec log examples 11120 11121@cindex Timezone, in output 11122@cindex Zone, time, in output 11123Since @code{log} shows dates in local time, 11124you might want to see them in Coordinated Universal Time (UTC) or 11125some other timezone. 11126To do this you can set your @code{$TZ} environment 11127variable before invoking @sc{cvs}: 11128 11129@example 11130$ TZ=UTC cvs log foo.c 11131$ TZ=EST cvs log bar.c 11132@end example 11133 11134(If you are using a @code{csh}-style shell, like @code{tcsh}, 11135you would need to prefix the examples above with @code{env}.) 11136 11137@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11138@node ls & rls 11139@appendixsec ls & rls 11140@cindex ls (subcommand) 11141@cindex rls (subcommand) 11142 11143@itemize @bullet 11144@item 11145ls [-e | -l] [-RP] [-r tag[:date]] [-D date] [path@dots{}] 11146@item 11147Requires: repository for @code{rls}, repository & working directory for 11148@code{ls}. 11149@item 11150Changes: nothing. 11151@item 11152Synonym: @code{dir} & @code{list} are synonyms for @code{ls} and @code{rdir} 11153& @code{rlist} are synonyms for @code{rls}. 11154@end itemize 11155 11156The @code{ls} and @code{rls} commands are used to list 11157files and directories in the repository. 11158 11159By default @code{ls} lists the files and directories 11160that belong in your working directory, what would be 11161there after an @code{update}. 11162 11163By default @code{rls} lists the files and directories 11164on the tip of the trunk in the topmost directory of the 11165repository. 11166 11167Both commands accept an optional list of file and 11168directory names, relative to the working directory for 11169@code{ls} and the topmost directory of the repository 11170for @code{rls}. Neither is recursive by default. 11171 11172@menu 11173* ls & rls options:: ls & rls options 11174* rls examples: rls examples 11175@end menu 11176 11177@node ls & rls options 11178@appendixsubsec ls & rls options 11179 11180These standard options are supported by @code{ls} & @code{rls}: 11181 11182@table @code 11183@item -d 11184Show dead revisions (with tag when specified). 11185 11186@item -e 11187Display in CVS/Entries format. This format is meant to remain easily parsable 11188by automation. 11189 11190@item -l 11191Display all details. 11192 11193@item -P 11194Don't list contents of empty directories when recursing. 11195 11196@item -R 11197List recursively. 11198 11199@item -r @var{tag}[:@var{date}] 11200Show files specified by @var{tag} or, when @var{date} is specified 11201and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11202existed on @var{date}. See @ref{Common options}. 11203 11204@item -D @var{date} 11205Show files from date. 11206@end table 11207 11208@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11209@node rls examples 11210@appendixsubsec rls examples 11211 11212@example 11213$ cvs rls 11214cvs rls: Listing module: `.' 11215CVSROOT 11216first-dir 11217@end example 11218 11219@example 11220$ cvs rls CVSROOT 11221cvs rls: Listing module: `CVSROOT' 11222checkoutlist 11223commitinfo 11224config 11225cvswrappers 11226loginfo 11227modules 11228notify 11229rcsinfo 11230taginfo 11231verifymsg 11232 11233@end example 11234 11235@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11236@node rdiff 11237@appendixsec rdiff---'patch' format diffs between releases 11238@cindex rdiff (subcommand) 11239 11240@itemize @bullet 11241@item 11242rdiff [options] @{-r tag1[:date1] | -D date1@} [-r tag2[:date2] | -D date2] modules@dots{} 11243@item 11244Requires: repository. 11245@item 11246Changes: nothing. 11247@item 11248Synonym: patch 11249@end itemize 11250 11251Builds a Larry Wall format patch(1) file between two 11252releases, that can be fed directly into the @code{patch} 11253program to bring an old release up-to-date with the new 11254release. The diff output is sent to the standard output device. 11255 11256You can specify (using the standard @samp{-r} and 11257@samp{-D} options) any combination of one or two 11258revisions or dates. If only one revision or date is 11259specified, the patch file reflects differences between 11260that revision or date and the current head revisions in 11261the @sc{rcs} file. 11262 11263Note that if the patch created by rdiff spans multiple directories, 11264then it may be necessary to specify the @samp{-p} option when feeding 11265the patch back to the @code{patch} command, so that @code{patch} is able 11266to update files that are located in directories other than the one 11267patch is run in. 11268 11269@menu 11270* rdiff options:: rdiff options 11271* rdiff examples:: rdiff examples 11272@end menu 11273 11274@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11275@node rdiff options 11276@appendixsubsec rdiff options 11277 11278These standard options are supported by @code{rdiff} 11279(@pxref{Common options}, for a complete description of 11280them): 11281 11282@table @code 11283@item -D @var{date} 11284Use the most recent revision no later than @var{date}. 11285 11286@item -f 11287If no matching revision is found, retrieve the most 11288recent revision (instead of ignoring the file). 11289 11290@item -k @var{kflag} 11291Process keywords according to @var{kflag}. See 11292@ref{Keyword substitution}. 11293 11294@item -l 11295Local; don't descend subdirectories. 11296 11297@item -p 11298Show which C function each change is in. 11299 11300@item -R 11301Examine directories recursively. This option is on by default. 11302 11303@item -r @var{tag} 11304Use the revision specified by @var{tag}, or when @var{date} is specified 11305and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11306existed on @var{date}. See @ref{Common options}. 11307@end table 11308 11309In addition to the above, these options are available: 11310 11311@table @code 11312@item -c 11313Use the context diff format. This is the default format. 11314 11315@item -s 11316Create a summary change report instead of a patch. The 11317summary includes information about files that were 11318changed or added between the releases. It is sent to 11319the standard output device. This is useful for finding 11320out, for example, which files have changed between two 11321dates or revisions. 11322 11323@item -t 11324A diff of the top two revisions is sent to the standard 11325output device. This is most useful for seeing what the 11326last change to a file was. 11327 11328@item -u 11329Use the unidiff format for the context diffs. 11330Remember that old versions 11331of the @code{patch} program can't handle the unidiff 11332format, so if you plan to post this patch to the net 11333you should probably not use @samp{-u}. 11334@end table 11335 11336@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11337@node rdiff examples 11338@appendixsubsec rdiff examples 11339 11340Suppose you receive mail from @t{foo@@example.net} asking for an 11341update from release 1.2 to 1.4 of the tc compiler. You 11342have no such patches on hand, but with @sc{cvs} that can 11343easily be fixed with a command such as this: 11344 11345@example 11346$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 11347$$ Mail -s 'The patches you asked for' foo@@example.net 11348@end example 11349 11350Suppose you have made release 1.3, and forked a branch 11351called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1} 11352corresponds to release 1.3.1, which was made some time 11353ago. Now, you want to see how much development has been 11354done on the branch. This command can be used: 11355 11356@example 11357$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 11358cvs rdiff: Diffing module-name 11359File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 11360File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 11361File bar.h,v changed from revision 1.29.2.1 to 1.2 11362@end example 11363 11364@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11365@node release 11366@appendixsec release---Indicate that a Module is no longer in use 11367@cindex release (subcommand) 11368 11369@itemize @bullet 11370@item 11371release [-d] directories@dots{} 11372@item 11373Requires: Working directory. 11374@item 11375Changes: Working directory, history log. 11376@end itemize 11377 11378This command is meant to safely cancel the effect of 11379@samp{cvs checkout}. Since @sc{cvs} doesn't lock files 11380(except for the @code{cvs admin -l} command, @pxref{admin options}), 11381it isn't strictly necessary to use this command. You can 11382always simply delete your working directory, if you 11383like; but you risk losing changes you may have 11384forgotten, and you leave no trace in the @sc{cvs} history 11385file (@pxref{history file}) that you've abandoned your 11386checkout. 11387 11388Use @samp{cvs release} to avoid these problems. This 11389command checks that no uncommitted changes are 11390present; that you are executing it from immediately 11391above a @sc{cvs} working directory; and that the repository 11392recorded for your files is the same as the repository 11393defined in the module database. 11394 11395If all these conditions are true, @samp{cvs release} 11396leaves a record of its execution (attesting to your 11397intentionally abandoning your checkout) in the @sc{cvs} 11398history log. 11399 11400@menu 11401* release options:: release options 11402* release output:: release output 11403* release examples:: release examples 11404@end menu 11405 11406@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11407@node release options 11408@appendixsubsec release options 11409 11410The @code{release} command supports one command option: 11411 11412@table @code 11413@item -d 11414Delete your working copy of the file if the release 11415succeeds. If this flag is not given your files will 11416remain in your working directory. 11417 11418@strong{WARNING: The @code{release} command deletes 11419all directories and files recursively. This 11420has the very serious side-effect that any directory 11421that you have created inside your checked-out sources, 11422and not added to the repository (using the @code{add} 11423command; @pxref{Adding files}) will be silently deleted---even 11424if it is non-empty!} 11425@end table 11426 11427@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11428@node release output 11429@appendixsubsec release output 11430 11431Before @code{release} releases your sources it will 11432print a one-line message for any file that is not 11433up-to-date. 11434 11435@table @code 11436@item U @var{file} 11437@itemx P @var{file} 11438There exists a newer revision of this file in the 11439repository, and you have not modified your local copy 11440of the file (@samp{U} and @samp{P} mean the same thing). 11441 11442@item A @var{file} 11443The file has been added to your private copy of the 11444sources, but has not yet been committed to the 11445repository. If you delete your copy of the sources 11446this file will be lost. 11447 11448@item R @var{file} 11449The file has been removed from your private copy of the 11450sources, but has not yet been removed from the 11451repository, since you have not yet committed the 11452removal. @xref{commit}. 11453 11454@item M @var{file} 11455The file is modified in your working directory. There 11456might also be a newer revision inside the repository. 11457 11458@item ? @var{file} 11459@var{file} is in your working directory, but does not 11460correspond to anything in the source repository, and is 11461not in the list of files for @sc{cvs} to ignore (see the 11462description of the @samp{-I} option, and 11463@pxref{cvsignore}). If you remove your working 11464sources, this file will be lost. 11465@end table 11466 11467@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11468@node release examples 11469@appendixsubsec release examples 11470 11471Release the @file{tc} directory, and delete your local working copy 11472of the files. 11473 11474@example 11475$ cd .. # @r{You must stand immediately above the} 11476 # @r{sources when you issue @samp{cvs release}.} 11477$ cvs release -d tc 11478You have [0] altered files in this repository. 11479Are you sure you want to release (and delete) directory `tc': y 11480$ 11481@end example 11482 11483@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11484@node remove 11485@appendixsec remove---Remove files from active use 11486@cindex remove (subcommand) 11487 11488@itemize @bullet 11489@item 11490Synopsis: remove [-flR] [files...] 11491@item 11492Requires: repository, working directory. 11493@item 11494Changes: working directory. 11495@end itemize 11496 11497The @code{remove} command is used to remove unwanted 11498files from active use. The user normally deletes the 11499files from the working directory prior to invocation 11500of the @code{remove} command. Only the working 11501directory is updated. Changes to the repository are 11502not made until the @code{commit} command is run. 11503 11504The @code{remove} command does not delete files from 11505from the repository. @sc{cvs} keeps all historical 11506data in the repository so that it is possible to 11507reconstruct previous states of the projects under 11508revision control. 11509 11510To undo @sc{cvs} @code{remove} or to resurrect files 11511that were previously removed, @xref{add}. 11512 11513@menu 11514* remove options:: remove options 11515* remove examples:: remove examples 11516@end menu 11517 11518@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11519@node remove options 11520@appendixsubsec remove options 11521 11522These standard options are supported by @code{remove} 11523(@pxref{Common options} for a complete description of 11524them): 11525 11526@table @code 11527@item -l 11528Local; run only in current working directory. See @ref{Recursive behavior}. 11529 11530@item -R 11531Process directories recursively. See @ref{Recursive behavior}. 11532 11533@end table 11534 11535In addition, these options are also supported: 11536 11537@table @code 11538@item -f 11539Note that this is not the standard behavior of 11540the @samp{-f} option as defined in @ref{Common options}. 11541 11542Delete files before removing them. 11543 11544Entire directory hierarchies are easily removed 11545using @samp{-f}, but take note that it is not as 11546easy to resurrect directory hierarchies as it is 11547to remove them. 11548 11549@end table 11550 11551@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11552@node remove examples 11553@appendixsubsec remove examples 11554 11555@appendixsubsubsec Removing a file 11556 11557@example 11558$ cvs remove remove.me 11559cvs remove: file `remove.me' still in working directory 11560cvs remove: 1 file exists; remove it first 11561$ rm -f remove.me 11562$ cvs remove remove.me 11563cvs remove: scheduling `remove.me' for removal 11564cvs remove: use 'cvs commit' to remove this file permanently 11565 11566$ ls remove.it 11567remove.it 11568$ cvs remove -f remove.it 11569cvs remove: scheduling `remove.it' for removal 11570cvs remove: use 'cvs commit' to remove this file permanently 11571@end example 11572 11573@appendixsubsubsec Removing entire directories 11574@example 11575$ tree -d a 11576a 11577|-- CVS 11578`-- b 11579 `-- CVS 11580 115813 directories 11582$ cvs remove -f a 11583cvs remove: Removing a 11584cvs remove: Removing a/b 11585cvs remove: scheduling `a/b/c' for removal 11586cvs remove: use 'cvs commit' to remove this file permanently 11587@end example 11588 11589@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11590@node server & pserver 11591@appendixsec server & pserver---Act as a server for a client on stdin/stdout 11592@cindex pserver (subcommand) 11593@cindex server (subcommand) 11594 11595@itemize @bullet 11596@item 11597pserver [-c path] 11598 11599server [-c path] 11600@item 11601Requires: repository, client conversation on stdin/stdout 11602@item 11603Changes: Repository or, indirectly, client working directory. 11604@end itemize 11605 11606The @sc{cvs} @code{server} and @code{pserver} commands are used to provide 11607repository access to remote clients and expect a client conversation on 11608stdin & stdout. Typically these commands are launched from @code{inetd} or 11609via @code{ssh} (@pxref{Remote repositories}). 11610 11611@code{server} expects that the client has already been authenticated somehow, 11612typically via @sc{ssh}, and @code{pserver} attempts to authenticate the client 11613itself. 11614 11615Only one option is available with the @code{server} and @code{pserver} 11616commands: 11617 11618@cindex configuration file 11619@table @code 11620@item -c path 11621Load configuration from @var{path} rather than the default location 11622@file{$CVSROOT/CVSROOT/config} (@pxref{config}). @var{path} must be 11623@file{/etc/cvs.conf} or prefixed by @file{/etc/cvs/}. This option is 11624supported beginning with @sc{cvs} release 1.12.13. 11625@end table 11626 11627@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11628@node tag & rtag 11629@appendixsec tag & rtag---Mark project snapshot for later retrieval. 11630@cindex tag (subcommand) 11631@cindex freeze (subcommand) 11632@cindex rtag (subcommand) 11633@cindex rfreeze (subcommand) 11634 11635@itemize @bullet 11636@item 11637tag [-bBcdFflR] [-r tag] [-D date] new_tag [files@dots{}] 11638@item 11639Requires: working directory, repository. 11640@item 11641Changes: repository. 11642@item 11643Synonym: ta, freeze 11644@end itemize 11645 11646@noindent 11647and 11648 11649@itemize @bullet 11650@item 11651rtag [-abBdFflnR] [-r tag | -D date] new_tag module@dots{} 11652@item 11653Requires: repository. 11654@item 11655Changes: repository. 11656@item 11657Synonym: rt, rfreeze 11658@end itemize 11659 11660Use @code{tag} to assign symbolic tags to the revisions of files 11661checked out into your sandbox. The tags are applied immediately 11662to the repository, with the revision numbers to attach the tag 11663to supplied implicitly by the @sc{cvs} records of your working files. 11664 11665@code{rtag} works similarly, but does not need a sandbox to operate 11666in, requiring an explicitly supplied tag or date instead (or assuming 11667the tip of the trunk when one is not supplied explicitly). @sc{cvs} 11668uses this preexisting tag or date to determine which revisions of 11669files in the repository to attach the new symbolic tag to. 11670 11671The symbolic tags are meant to permanently record which 11672revisions of which files were used for some purpose. The @code{checkout} 11673and @code{update} commands allow you to extract an exact 11674copy of a tagged release at any time in the future, 11675regardless of whether files have been changed, added, 11676or removed on the trunk or other branches since the release was tagged. 11677For more, @xref{Branching and merging}. 11678 11679These commands may also be used to delete a symbolic tag, 11680or to create a branch. See the options section below. 11681 11682Note if you wish to run destructive commands such as tag deletion, you may 11683need to be a member of the group @code{cvsadmin} to do this. 11684 11685If you attempt to create a tag that already exists, 11686CVS will complain and not overwrite that tag. Use 11687the @samp{-F} option to move the tag to a new set of 11688revisions. 11689 11690These standard options are supported by @code{tag} or @code{rtag} 11691(@pxref{Common options}, for a complete description of them): 11692 11693@table @code 11694@item -D @var{date} 11695Tag the most recent revision no later than @var{date}. This option is 11696not valid when deleting tags (see @samp{-d} option, below). 11697 11698@item -l 11699Local; run only in current working directory. @xref{Recursive behavior}. 11700 11701@item -R 11702Update directories recursively (default). @xref{Recursive behavior}. 11703 11704@item -r @var{tag}[:@var{date}] 11705Tag the revisions specified by @var{tag} or, when @var{date} is specified 11706and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11707existed on @var{date}. This option is not valid when deleting tags 11708(see @samp{-d} option, below). 11709@end table 11710 11711Several tag specific options are also available. When an option is only 11712available with one of @code{tag} or @code{rtag}, it is noted below: 11713 11714@table @code 11715@item -a 11716Clear @var{new_tag} from removed files that would not otherwise be tagged 11717(@code{rtag} only). 11718 11719@item -B 11720Allows @code{-d} or @code{-F} to delete or move branch tags. 11721 11722@strong{WARNING: Recovering the information stored by branch tags is 11723a very hard problem, more so than regular tags. Be absolutely sure you 11724understand what you are doing before using this option.} 11725 11726@item -b 11727The @code{-b} option makes the new tag a branch tag (@pxref{Branching and 11728merging}), allowing concurrent, isolated development. This is commonly used 11729to create patches to a previously released software distribution. 11730 11731@item -c 11732Abort if any tagged files are locally modified (@code{tag} only). 11733 11734@item -d 11735Delete @var{new_tag}, instead of creating it. 11736 11737@strong{WARNING: Be very certain of your ground before you delete a tag; doing 11738this permanently discards some historical information, which could later turn 11739out to be valuable.} 11740 11741@item -F 11742When a tag already exists, move it to the new revision. When the tag 11743does not exist, create it as normal. This option is new in @sc{cvs} 1.4. 11744The pre-1.4 behavior is identical to @samp{cvs tag -F}. 11745 11746@strong{WARNING: Be very certain of your ground before you delete a tag; doing 11747this permanently discards some historical information, which could later turn 11748out to be valuable.} 11749 11750@item -f 11751With @code{-r @var{tag}} or @code{-d @var{date}}, force a head revision match 11752if @var{tag} and @var{date} are not found (in other words, attach @var{new_tag} 11753to the most recent trunk revision when @var{tag} and @var{date} do not 11754resolve to an existing revision). 11755 11756@item -n 11757Do not execute the tag program specified in the @file{modules} file 11758(@code{rtag} only). @xref{modules}, for more. 11759@end table 11760 11761@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11762@node update 11763@appendixsec update---Bring work tree in sync with repository 11764@cindex update (subcommand) 11765 11766@itemize @bullet 11767@item 11768update [-ACdflPpRt] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag[:date] | -D date] [-W spec] [files@dots{}] 11769@item 11770Requires: repository, working directory. 11771@item 11772Changes: working directory. 11773@end itemize 11774 11775After you've run @code{checkout} to create your private copy 11776of source from the common repository, other developers 11777will continue changing the central source. From time 11778to time, when it is convenient in your development 11779process, you can use the @code{update} command from 11780within your working directory to reconcile your work 11781with any revisions applied to the source repository 11782since your last checkout or update. Without the @code{-C} 11783option, @code{update} will also merge any differences 11784between the local copy of files and their base revisions 11785into any destination revisions specified with @code{-r}, 11786@code{-D}, or @code{-A}. 11787 11788@menu 11789* update options:: update options 11790* update output:: update output 11791@end menu 11792 11793@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11794@node update options 11795@appendixsubsec update options 11796 11797These standard options are available with @code{update} 11798(@pxref{Common options}, for a complete description of 11799them): 11800 11801@table @code 11802@item -D date 11803Use the most recent revision no later than @var{date}. 11804This option is sticky, and implies @samp{-P}. 11805See @ref{Sticky tags}, for more information on sticky tags/dates. 11806 11807@item -f 11808Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision 11809is found, retrieve the most recent revision (instead of ignoring the file). 11810 11811@item -k @var{kflag} 11812Process keywords according to @var{kflag}. See 11813@ref{Keyword substitution}. 11814This option is sticky; future updates of 11815this file in this working directory will use the same 11816@var{kflag}. The @code{status} command can be viewed 11817to see the sticky options. See @ref{Invoking CVS}, for 11818more information on the @code{status} command. 11819 11820@item -l 11821Local; run only in current working directory. @xref{Recursive behavior}. 11822 11823@item -P 11824Prune empty directories. See @ref{Moving directories}. 11825 11826@item -p 11827Pipe files to the standard output. 11828 11829@item -R 11830Update directories recursively (default). @xref{Recursive 11831behavior}. 11832 11833@item -r @var{tag}[:@var{date}] 11834Retrieve the revisions specified by @var{tag} or, when @var{date} is specified 11835and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11836existed on @var{date}. This option is sticky, and implies @samp{-P}. 11837See @ref{Sticky tags}, for more information on sticky tags/dates. Also 11838see @ref{Common options}. 11839 11840@item -t 11841Preserve source timestamps. Unlike @code{checkout}, where files are created 11842using the original timestamp of the file in the repository, @code{update} 11843updates files using the current time of the machine. This is convenient 11844because updated files appear newer than any other files on the system so 11845@code{make(1)} knows that their corresponding built artifacts are out of date 11846and they will get rebuilt. The @samp{-t} flag instead preserves the timestamps 11847of the original repository files, behaving exactly like @code{checkout}. 11848This is useful for maintaining a tree in the original checked-out state. 11849@end table 11850 11851@need 800 11852These special options are also available with 11853@code{update}. 11854 11855@table @code 11856@item -A 11857Reset any sticky tags, dates, or @samp{-k} options. 11858See @ref{Sticky tags}, for more information on sticky tags/dates. 11859 11860@item -C 11861Overwrite locally modified files with clean copies from 11862the repository (the modified file is saved in 11863@file{.#@var{file}.@var{revision}}, however). 11864 11865@item -d 11866Create any directories that exist in the repository if 11867they're missing from the working directory. Normally, 11868@code{update} acts only on directories and files that 11869were already enrolled in your working directory. 11870 11871This is useful for updating directories that were 11872created in the repository since the initial checkout; 11873but it has an unfortunate side effect. If you 11874deliberately avoided certain directories in the 11875repository when you created your working directory 11876(either through use of a module name or by listing 11877explicitly the files and directories you wanted on the 11878command line), then updating with @samp{-d} will create 11879those directories, which may not be what you want. 11880 11881@item -I @var{name} 11882Ignore files whose names match @var{name} (in your 11883working directory) during the update. You can specify 11884@samp{-I} more than once on the command line to specify 11885several files to ignore. Use @samp{-I !} to avoid 11886ignoring any files at all. @xref{cvsignore}, for other 11887ways to make @sc{cvs} ignore some files. 11888 11889@item -W@var{spec} 11890Specify file names that should be filtered during 11891update. You can use this option repeatedly. 11892 11893@var{spec} can be a file name pattern of the same type 11894that you can specify in the @file{.cvswrappers} 11895file. @xref{Wrappers}. 11896 11897@item -j@var{revision} 11898With two @samp{-j} options, merge changes from the 11899revision specified with the first @samp{-j} option to 11900the revision specified with the second @samp{j} option, 11901into the working directory. 11902 11903With one @samp{-j} option, merge changes from the 11904ancestor revision to the revision specified with the 11905@samp{-j} option, into the working directory. The 11906ancestor revision is the common ancestor of the 11907revision which the working directory is based on, and 11908the revision specified in the @samp{-j} option. 11909 11910Note that using a single @samp{-j @var{tagname}} option rather than 11911@samp{-j @var{branchname}} to merge changes from a branch will 11912often not remove files which were removed on the branch. 11913@xref{Merging adds and removals}, for more. 11914 11915In addition, each @samp{-j} option can contain an optional 11916date specification which, when used with branches, can 11917limit the chosen revision to one within a specific 11918date. An optional date is specified by adding a colon 11919(:) to the tag: 11920@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 11921 11922@xref{Branching and merging}. 11923 11924@end table 11925 11926@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11927@node update output 11928@appendixsubsec update output 11929 11930@code{update} and @code{checkout} keep you informed of 11931their progress by printing a line for each file, preceded 11932by one character indicating the status of the file: 11933 11934@table @code 11935@item U @var{file} 11936The file was brought up to date with respect to the 11937repository. This is done for any file that exists in 11938the repository but not in your working directory, and for files 11939that you haven't changed but are not the most recent 11940versions available in the repository. 11941 11942@item P @var{file} 11943Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 11944file. This accomplishes the same thing as @samp{U} using less bandwidth. 11945 11946@item A @var{file} 11947The file has been added to your private copy of the 11948sources, and will be added to the source repository 11949when you run @code{commit} on the file. This is a 11950reminder to you that the file needs to be committed. 11951 11952@item R @var{file} 11953The file has been removed from your private copy of the 11954sources, and will be removed from the source repository 11955when you run @code{commit} on the file. This is a 11956reminder to you that the file needs to be committed. 11957 11958@item M @var{file} 11959The file is modified in your working directory. 11960 11961@samp{M} can indicate one of two states for a file 11962you're working on: either there were no modifications 11963to the same file in the repository, so that your file 11964remains as you last saw it; or there were modifications 11965in the repository as well as in your copy, but they 11966were merged successfully, without conflict, in your 11967working directory. 11968 11969@sc{cvs} will print some messages if it merges your work, 11970and a backup copy of your working file (as it looked 11971before you ran @code{update}) will be made. The exact 11972name of that file is printed while @code{update} runs. 11973 11974@item C @var{file} 11975@cindex .# files 11976@cindex __ files (VMS) 11977A conflict was detected while trying to merge your 11978changes to @var{file} with changes from the source 11979repository. @var{file} (the copy in your working 11980directory) is now the result of attempting to merge 11981the two revisions; an unmodified copy of your file 11982is also in your working directory, with the name 11983@file{.#@var{file}.@var{revision}} where @var{revision} 11984is the revision that your modified file started 11985from. Resolve the conflict as described in 11986@ref{Conflicts example}. 11987@c "some systems" as in out-of-the-box OSes? Not as 11988@c far as I know. We need to advise sysadmins as well 11989@c as users how to set up this kind of purge, if that is 11990@c what they want. 11991@c We also might want to think about cleaner solutions, 11992@c like having CVS remove the .# file once the conflict 11993@c has been resolved or something like that. 11994(Note that some systems automatically purge 11995files that begin with @file{.#} if they have not been 11996accessed for a few days. If you intend to keep a copy 11997of your original file, it is a very good idea to rename 11998it.) Under @sc{vms}, the file name starts with 11999@file{__} rather than @file{.#}. 12000 12001@item ? @var{file} 12002@var{file} is in your working directory, but does not 12003correspond to anything in the source repository, and is 12004not in the list of files for @sc{cvs} to ignore (see the 12005description of the @samp{-I} option, and 12006@pxref{cvsignore}). 12007@end table 12008 12009@c ----- END MAN 1 ----- 12010@c --------------------------------------------------------------------- 12011@node Invoking CVS 12012@appendix Quick reference to CVS commands 12013@cindex Command reference 12014@cindex Reference, commands 12015@cindex Invoking CVS 12016 12017This appendix describes how to invoke @sc{cvs}, with 12018references to where each command or feature is 12019described in detail. For other references run the 12020@code{cvs --help} command, or see @ref{Index}. 12021 12022A @sc{cvs} command looks like: 12023 12024@example 12025cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 12026@end example 12027 12028Global options: 12029 12030@table @code 12031@item --allow-root=@var{rootdir} 12032Specify legal @sc{cvsroot} directory (server only) (not 12033in @sc{cvs} 1.9 and older). See @ref{Password 12034authentication server}. 12035 12036@item -a 12037Authenticate all communication (client only) (not in @sc{cvs} 120381.9 and older). See @ref{Global options}. 12039 12040@item -b 12041Specify RCS location (@sc{cvs} 1.9 and older). See 12042@ref{Global options}. 12043 12044@item -d @var{root} 12045Specify the @sc{cvsroot}. See @ref{Repository}. 12046 12047@item -e @var{editor} 12048Edit messages with @var{editor}. See @ref{Committing 12049your changes}. 12050 12051@item -f 12052Do not read the @file{~/.cvsrc} file. See @ref{Global 12053options}. 12054 12055@item -H 12056@itemx --help 12057Print a help message. See @ref{Global options}. 12058 12059@item -n 12060Do not change any files. See @ref{Global options}. 12061 12062@item -Q 12063Be really quiet. See @ref{Global options}. 12064 12065@item -q 12066Be somewhat quiet. See @ref{Global options}. 12067 12068@item -r 12069Make new working files read-only. See @ref{Global options}. 12070 12071@item -s @var{variable}=@var{value} 12072Set a user variable. See @ref{Variables}. 12073 12074@item -T @var{tempdir} 12075Put temporary files in @var{tempdir}. See @ref{Global 12076options}. 12077 12078@item -t 12079Trace @sc{cvs} execution. See @ref{Global options}. 12080 12081@item -v 12082@item --version 12083Display version and copyright information for @sc{cvs}. 12084 12085@item -w 12086Make new working files read-write. See @ref{Global 12087options}. 12088 12089@item -x 12090Encrypt all communication (client only). 12091See @ref{Global options}. 12092 12093@item -z @var{gzip-level} 12094@cindex Compression 12095@cindex Gzip 12096Set the compression level (client only). 12097See @ref{Global options}. 12098@end table 12099 12100Keyword expansion modes (@pxref{Substitution modes}): 12101 12102@example 12103-kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 12104-kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12105-kk $@splitrcskeyword{Id}$ 12106-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 12107-ko @i{no expansion} 12108-kb @i{no expansion, file is binary} 12109@end example 12110 12111Keywords (@pxref{Keyword list}): 12112 12113@example 12114$@splitrcskeyword{Author}: joe $ 12115$@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ 12116$@splitrcskeyword{CVSHeader}: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12117$@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12118$@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12119$@splitrcskeyword{Locker}: harry $ 12120$@splitrcskeyword{Name}: snapshot_1_14 $ 12121$@splitrcskeyword{RCSfile}: file1,v $ 12122$@splitrcskeyword{Revision}: 1.1 $ 12123$@splitrcskeyword{Source}: /home/files/file1,v $ 12124$@splitrcskeyword{State}: Exp $ 12125$@splitrcskeyword{Log}: file1,v $ 12126Revision 1.1 1993/12/09 03:30:17 joe 12127Initial revision 12128 12129@end example 12130 12131@c The idea behind this table is that we want each item 12132@c to be a sentence or two at most. Preferably a 12133@c single line. 12134@c 12135@c In some cases refs to "foo options" are just to get 12136@c this thing written quickly, not because the "foo 12137@c options" node is really the best place to point. 12138Commands, command options, and command arguments: 12139 12140@table @code 12141@c ------------------------------------------------------------ 12142@item add [@var{options}] [@var{files}@dots{}] 12143Add a new file/directory. See @ref{Adding files}. 12144 12145@table @code 12146@item -k @var{kflag} 12147Set keyword expansion. 12148 12149@item -m @var{msg} 12150Set file description. 12151@end table 12152 12153@c ------------------------------------------------------------ 12154@item admin [@var{options}] [@var{files}@dots{}] 12155Administration of history files in the repository. See 12156@ref{admin}. 12157@c This list omits those options which are not 12158@c documented as being useful with CVS. That might be 12159@c a mistake... 12160 12161@table @code 12162@item -b[@var{rev}] 12163Set default branch. See @ref{Reverting local changes}. 12164 12165@item -c@var{string} 12166Set comment leader. 12167 12168@item -k@var{subst} 12169Set keyword substitution. See @ref{Keyword 12170substitution}. 12171 12172@item -l[@var{rev}] 12173Lock revision @var{rev}, or latest revision. 12174 12175@item -m@var{rev}:@var{msg} 12176Replace the log message of revision @var{rev} with 12177@var{msg}. 12178 12179@item -o@var{range} 12180Delete revisions from the repository. See 12181@ref{admin options}. 12182 12183@item -q 12184Run quietly; do not print diagnostics. 12185 12186@item -s@var{state}[:@var{rev}] 12187Set the state. See @ref{admin options} for more information on possible 12188states. 12189 12190@c Does not work for client/server CVS 12191@item -t 12192Set file description from standard input. 12193 12194@item -t@var{file} 12195Set file description from @var{file}. 12196 12197@item -t-@var{string} 12198Set file description to @var{string}. 12199 12200@item -u[@var{rev}] 12201Unlock revision @var{rev}, or latest revision. 12202@end table 12203 12204@c ------------------------------------------------------------ 12205@item annotate [@var{options}] [@var{files}@dots{}] 12206Show last revision where each line was modified. See 12207@ref{annotate & rannotate}. 12208 12209@table @code 12210@item -D @var{date} 12211Annotate the most recent revision no later than 12212@var{date}. See @ref{Common options}. 12213 12214@item -F 12215Force annotation of binary files. (Without this option, 12216binary files are skipped with a message.) 12217 12218@item -f 12219Use head revision if tag/date not found. See 12220@ref{Common options}. 12221 12222@item -l 12223Local; run only in current working directory. @xref{Recursive behavior}. 12224 12225@item -R 12226Operate recursively (default). @xref{Recursive 12227behavior}. 12228 12229@item -r @var{tag}[:@var{date}] 12230Annotate revisions specified by @var{tag} or, when @var{date} is specified 12231and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12232existed on @var{date}. See @ref{Common options}. 12233@end table 12234 12235@c ------------------------------------------------------------ 12236@item checkout [@var{options}] @var{modules}@dots{} 12237Get a copy of the sources. See @ref{checkout}. 12238 12239@table @code 12240@item -A 12241Reset any sticky tags/date/options. See @ref{Sticky 12242tags} and @ref{Keyword substitution}. 12243 12244@item -c 12245Output the module database. See @ref{checkout options}. 12246 12247@item -D @var{date} 12248Check out revisions as of @var{date} (is sticky). See 12249@ref{Common options}. 12250 12251@item -d @var{dir} 12252Check out into @var{dir}. See @ref{checkout options}. 12253 12254@item -f 12255Use head revision if tag/date not found. See 12256@ref{Common options}. 12257 12258@c Probably want to use rev1/rev2 style like for diff 12259@c -r. Here and in on-line help. 12260@item -j @var{tag}[:@var{date}] 12261Merge in the change specified by @var{tag}, or when @var{date} is specified 12262and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12263existed on @var{date}. See @ref{checkout options}. 12264 12265@item -k @var{kflag} 12266Use @var{kflag} keyword expansion. See 12267@ref{Substitution modes}. 12268 12269@item -l 12270Local; run only in current working directory. @xref{Recursive behavior}. 12271 12272@item -N 12273Don't ``shorten'' module paths if -d specified. See 12274@ref{checkout options}. 12275 12276@item -n 12277Do not run module program (if any). See @ref{checkout options}. 12278 12279@item -P 12280Prune empty directories. See @ref{Moving directories}. 12281 12282@item -p 12283Check out files to standard output (avoids 12284stickiness). See @ref{checkout options}. 12285 12286@item -R 12287Operate recursively (default). @xref{Recursive 12288behavior}. 12289 12290@item -r @var{tag}[:@var{date}] 12291Checkout the revision already tagged with @var{tag} or, when @var{date} is 12292specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12293as it existed on @var{date}. This . See @ref{Common options}. 12294 12295@item -s 12296Like -c, but include module status. See @ref{checkout options}. 12297@end table 12298 12299@c ------------------------------------------------------------ 12300@item commit [@var{options}] [@var{files}@dots{}] 12301Check changes into the repository. See @ref{commit}. 12302 12303@table @code 12304@item -c 12305Check for valid edits before committing. Requires a @sc{cvs} client and server 12306both version 1.12.10 or greater. 12307 12308@item -F @var{file} 12309Read log message from @var{file}. See @ref{commit options}. 12310 12311@item -f 12312@c What is this "disables recursion"? It is from the 12313@c on-line help; is it documented in this manual? 12314Force the file to be committed; disables recursion. 12315See @ref{commit options}. 12316 12317@item -l 12318Local; run only in current working directory. See @ref{Recursive behavior}. 12319 12320@item -m @var{msg} 12321Use @var{msg} as log message. See @ref{commit options}. 12322 12323@item -n 12324Do not run module program (if any). See @ref{commit options}. 12325 12326@item -R 12327Operate recursively (default). @xref{Recursive 12328behavior}. 12329 12330@item -r @var{rev} 12331Commit to @var{rev}. See @ref{commit options}. 12332@c FIXME: should be dragging over text from 12333@c commit options, especially if it can be cleaned up 12334@c and made concise enough. 12335@end table 12336 12337@c ------------------------------------------------------------ 12338@item diff [@var{options}] [@var{files}@dots{}] 12339Show differences between revisions. See @ref{diff}. 12340In addition to the options shown below, accepts a wide 12341variety of options to control output style, for example 12342@samp{-c} for context diffs. 12343 12344@table @code 12345@item -D @var{date1} 12346Diff revision for date against working file. See 12347@ref{diff options}. 12348 12349@item -D @var{date2} 12350Diff @var{rev1}/@var{date1} against @var{date2}. See 12351@ref{diff options}. 12352 12353@item -l 12354Local; run only in current working directory. See @ref{Recursive behavior}. 12355 12356@item -N 12357Include diffs for added and removed files. See 12358@ref{diff options}. 12359 12360@item -R 12361Operate recursively (default). @xref{Recursive 12362behavior}. 12363 12364@item -r @var{tag1}[:@var{date1}] 12365Diff the revisions specified by @var{tag1} or, when @var{date1} is specified 12366and @var{tag1} is a branch tag, the version from the branch @var{tag1} as it 12367existed on @var{date1}, against the working file. See @ref{diff options} 12368and @ref{Common options}. 12369 12370@item -r @var{tag2}[:@var{date2}] 12371Diff the revisions specified by @var{tag2} or, when @var{date2} is specified 12372and @var{tag2} is a branch tag, the version from the branch @var{tag2} as it 12373existed on @var{date2}, against @var{rev1}/@var{date1}. See @ref{diff options} 12374and @ref{Common options}. 12375@end table 12376 12377@c ------------------------------------------------------------ 12378@item edit [@var{options}] [@var{files}@dots{}] 12379Get ready to edit a watched file. See @ref{Editing files}. 12380 12381@table @code 12382@item -a @var{actions} 12383Specify actions for temporary watch, where 12384@var{actions} is @code{edit}, @code{unedit}, 12385@code{commit}, @code{all}, or @code{none}. See 12386@ref{Editing files}. 12387 12388@item -c 12389Check edits: Edit fails if someone else is already editting the file. 12390Requires a @sc{cvs} client and server both of version 1.12.10 or greater. 12391 12392@item -f 12393Force edit; ignore other edits. Added in CVS 1.12.10. 12394 12395@item -l 12396Local; run only in current working directory. See @ref{Recursive behavior}. 12397 12398@item -R 12399Operate recursively (default). @xref{Recursive 12400behavior}. 12401@end table 12402 12403@c ------------------------------------------------------------ 12404@item editors [@var{options}] [@var{files}@dots{}] 12405See who is editing a watched file. See @ref{Watch information}. 12406 12407@table @code 12408@item -l 12409Local; run only in current working directory. See @ref{Recursive behavior}. 12410 12411@item -R 12412Operate recursively (default). @xref{Recursive 12413behavior}. 12414@end table 12415 12416@c ------------------------------------------------------------ 12417@item export [@var{options}] @var{modules}@dots{} 12418Export files from @sc{cvs}. See @ref{export}. 12419 12420@table @code 12421@item -D @var{date} 12422Check out revisions as of @var{date}. See 12423@ref{Common options}. 12424 12425@item -d @var{dir} 12426Check out into @var{dir}. See @ref{export options}. 12427 12428@item -f 12429Use head revision if tag/date not found. See 12430@ref{Common options}. 12431 12432@item -k @var{kflag} 12433Use @var{kflag} keyword expansion. See 12434@ref{Substitution modes}. 12435 12436@item -l 12437Local; run only in current working directory. @xref{Recursive behavior}. 12438 12439@item -N 12440Don't ``shorten'' module paths if -d specified. See 12441@ref{export options}. 12442 12443@item -n 12444Do not run module program (if any). See @ref{export options}. 12445 12446@item -R 12447Operate recursively (default). @xref{Recursive 12448behavior}. 12449 12450@item -r @var{tag}[:@var{date}] 12451Export the revisions specified by @var{tag} or, when @var{date} is specified 12452and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12453existed on @var{date}. See @ref{Common options}. 12454@end table 12455 12456@c ------------------------------------------------------------ 12457@item history [@var{options}] [@var{files}@dots{}] 12458Show repository access history. See @ref{history}. 12459 12460@table @code 12461@item -a 12462All users (default is self). See @ref{history options}. 12463 12464@item -b @var{str} 12465Back to record with @var{str} in module/file/repos 12466field. See @ref{history options}. 12467 12468@item -c 12469Report on committed (modified) files. See @ref{history options}. 12470 12471@item -D @var{date} 12472Since @var{date}. See @ref{history options}. 12473 12474@item -e 12475Report on all record types. See @ref{history options}. 12476 12477@item -l 12478Last modified (committed or modified report). See @ref{history options}. 12479 12480@item -m @var{module} 12481Report on @var{module} (repeatable). See @ref{history options}. 12482 12483@item -n @var{module} 12484In @var{module}. See @ref{history options}. 12485 12486@item -o 12487Report on checked out modules. See @ref{history options}. 12488 12489@item -p @var{repository} 12490In @var{repository}. See @ref{history options}. 12491 12492@item -r @var{rev} 12493Since revision @var{rev}. See @ref{history options}. 12494 12495@item -T 12496@c What the @#$@# is a TAG? Same as a tag? This 12497@c wording is also in the online-line help. 12498Produce report on all TAGs. See @ref{history options}. 12499 12500@item -t @var{tag} 12501Since tag record placed in history file (by anyone). 12502See @ref{history options}. 12503 12504@item -u @var{user} 12505For user @var{user} (repeatable). See @ref{history options}. 12506 12507@item -w 12508Working directory must match. See @ref{history options}. 12509 12510@item -x @var{types} 12511Report on @var{types}, one or more of 12512@code{TOEFWUPCGMAR}. See @ref{history options}. 12513 12514@item -z @var{zone} 12515Output for time zone @var{zone}. See @ref{history options}. 12516@end table 12517 12518@c ------------------------------------------------------------ 12519@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 12520Import files into @sc{cvs}, using vendor branches. See 12521@ref{import}. 12522 12523@table @code 12524@item -b @var{bra} 12525Import to vendor branch @var{bra}. See 12526@ref{Multiple vendor branches}. 12527 12528@item -d 12529Use the file's modification time as the time of 12530import. See @ref{import options}. 12531 12532@item -k @var{kflag} 12533Set default keyword substitution mode. See 12534@ref{import options}. 12535 12536@item -m @var{msg} 12537Use @var{msg} for log message. See 12538@ref{import options}. 12539 12540@item -I @var{ign} 12541More files to ignore (! to reset). See 12542@ref{import options}. 12543 12544@item -W @var{spec} 12545More wrappers. See @ref{import options}. 12546@end table 12547 12548@c ------------------------------------------------------------ 12549@item init 12550Create a @sc{cvs} repository if it doesn't exist. See 12551@ref{Creating a repository}. 12552 12553@c ------------------------------------------------------------ 12554@item kserver 12555Kerberos authenticated server. 12556See @ref{Kerberos authenticated}. 12557 12558@c ------------------------------------------------------------ 12559@item log [@var{options}] [@var{files}@dots{}] 12560Print out history information for files. See @ref{log & rlog}. 12561 12562@table @code 12563@item -b 12564Only list revisions on the default branch. See @ref{log options}. 12565 12566@item -d @var{dates} 12567Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12568latest before). See @ref{log options}. 12569 12570@item -h 12571Only print header. See @ref{log options}. 12572 12573@item -l 12574Local; run only in current working directory. See @ref{Recursive behavior}. 12575 12576@item -N 12577Do not list tags. See @ref{log options}. 12578 12579@item -R 12580Only print name of RCS file. See @ref{log options}. 12581 12582@item -r@var{revs} 12583Only list revisions @var{revs}. See @ref{log options}. 12584 12585@item -s @var{states} 12586Only list revisions with specified states. See @ref{log options}. 12587 12588@item -t 12589Only print header and descriptive text. See @ref{log 12590options}. 12591 12592@item -w@var{logins} 12593Only list revisions checked in by specified logins. See @ref{log options}. 12594@end table 12595 12596@c ------------------------------------------------------------ 12597@item login 12598Prompt for password for authenticating server. See 12599@ref{Password authentication client}. 12600 12601@c ------------------------------------------------------------ 12602@item logout 12603Remove stored password for authenticating server. See 12604@ref{Password authentication client}. 12605 12606@c ------------------------------------------------------------ 12607@item pserver 12608Password authenticated server. 12609See @ref{Password authentication server}. 12610 12611@c ------------------------------------------------------------ 12612@item rannotate [@var{options}] [@var{modules}@dots{}] 12613Show last revision where each line was modified. See 12614@ref{annotate & rannotate}. 12615 12616@table @code 12617@item -D @var{date} 12618Annotate the most recent revision no later than 12619@var{date}. See @ref{Common options}. 12620 12621@item -F 12622Force annotation of binary files. (Without this option, 12623binary files are skipped with a message.) 12624 12625@item -f 12626Use head revision if tag/date not found. See 12627@ref{Common options}. 12628 12629@item -l 12630Local; run only in current working directory. @xref{Recursive behavior}. 12631 12632@item -R 12633Operate recursively (default). @xref{Recursive behavior}. 12634 12635@item -r @var{tag}[:@var{date}] 12636Annotate the revision specified by @var{tag} or, when @var{date} is specified 12637and @var{tag} is a branch tag, the version from the branch @var{tag} 12638as it existed on @var{date}. See @ref{Common options}. 12639@end table 12640 12641@c ------------------------------------------------------------ 12642@item rdiff [@var{options}] @var{modules}@dots{} 12643Show differences between releases. See @ref{rdiff}. 12644 12645@table @code 12646@item -c 12647Context diff output format (default). See @ref{rdiff options}. 12648 12649@item -D @var{date} 12650Select revisions based on @var{date}. See @ref{Common options}. 12651 12652@item -f 12653Use head revision if tag/date not found. See 12654@ref{Common options}. 12655 12656@item -l 12657Local; run only in current working directory. See @ref{Recursive behavior}. 12658 12659@item -R 12660Operate recursively (default). @xref{Recursive 12661behavior}. 12662 12663@item -r @var{tag}[:@var{date}] 12664Select the revisions specified by @var{tag} or, when @var{date} is specified 12665and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12666existed on @var{date}. See @ref{diff options} and @ref{Common options}. 12667 12668@item -s 12669Short patch - one liner per file. See @ref{rdiff options}. 12670 12671@item -t 12672Top two diffs - last change made to the file. See 12673@ref{diff options}. 12674 12675@item -u 12676Unidiff output format. See @ref{rdiff options}. 12677 12678@item -V @var{vers} 12679Use RCS Version @var{vers} for keyword expansion (obsolete). See 12680@ref{rdiff options}. 12681@end table 12682 12683@c ------------------------------------------------------------ 12684@item release [@var{options}] @var{directory} 12685Indicate that a directory is no longer in use. See 12686@ref{release}. 12687 12688@table @code 12689@item -d 12690Delete the given directory. See @ref{release options}. 12691@end table 12692 12693@c ------------------------------------------------------------ 12694@item remove [@var{options}] [@var{files}@dots{}] 12695Remove an entry from the repository. See @ref{Removing files}. 12696 12697@table @code 12698@item -f 12699Delete the file before removing it. See @ref{Removing files}. 12700 12701@item -l 12702Local; run only in current working directory. See @ref{Recursive behavior}. 12703 12704@item -R 12705Operate recursively (default). @xref{Recursive 12706behavior}. 12707@end table 12708 12709@c ------------------------------------------------------------ 12710@item rlog [@var{options}] [@var{files}@dots{}] 12711Print out history information for modules. See @ref{log & rlog}. 12712 12713@table @code 12714@item -b 12715Only list revisions on the default branch. See @ref{log options}. 12716 12717@item -d @var{dates} 12718Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12719latest before). See @ref{log options}. 12720 12721@item -h 12722Only print header. See @ref{log options}. 12723 12724@item -l 12725Local; run only in current working directory. See @ref{Recursive behavior}. 12726 12727@item -N 12728Do not list tags. See @ref{log options}. 12729 12730@item -R 12731Only print name of RCS file. See @ref{log options}. 12732 12733@item -r@var{revs} 12734Only list revisions @var{revs}. See @ref{log options}. 12735 12736@item -s @var{states} 12737Only list revisions with specified states. See @ref{log options}. 12738 12739@item -t 12740Only print header and descriptive text. See @ref{log options}. 12741 12742@item -w@var{logins} 12743Only list revisions checked in by specified logins. See @ref{log options}. 12744@end table 12745 12746@c ------------------------------------------------------------ 12747@item rtag [@var{options}] @var{tag} @var{modules}@dots{} 12748Add a symbolic tag to a module. 12749See @ref{Revisions} and @ref{Branching and merging}. 12750 12751@table @code 12752@item -a 12753Clear tag from removed files that would not otherwise 12754be tagged. See @ref{Tagging add/remove}. 12755 12756@item -b 12757Create a branch named @var{tag}. See @ref{Branching and merging}. 12758 12759@item -B 12760Used in conjunction with -F or -d, enables movement and deletion of 12761branch tags. Use with extreme caution. 12762 12763@item -D @var{date} 12764Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12765 12766@item -d 12767Delete @var{tag}. See @ref{Modifying tags}. 12768 12769@item -F 12770Move @var{tag} if it already exists. See @ref{Modifying tags}. 12771 12772@item -f 12773Force a head revision match if tag/date not found. 12774See @ref{Tagging by date/tag}. 12775 12776@item -l 12777Local; run only in current working directory. See @ref{Recursive behavior}. 12778 12779@item -n 12780No execution of tag program. See @ref{Common options}. 12781 12782@item -R 12783Operate recursively (default). @xref{Recursive 12784behavior}. 12785 12786@item -r @var{tag}[:@var{date}] 12787Tag the revision already tagged with @var{tag} or, when @var{date} is specified 12788and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12789existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12790@end table 12791 12792@c ------------------------------------------------------------ 12793@item server 12794Rsh server. See @ref{Connecting via rsh}. 12795 12796@c ------------------------------------------------------------ 12797@item status [@var{options}] @var{files}@dots{} 12798Display status information in a working directory. See 12799@ref{File status}. 12800 12801@table @code 12802@item -l 12803Local; run only in current working directory. See @ref{Recursive behavior}. 12804 12805@item -R 12806Operate recursively (default). @xref{Recursive behavior}. 12807 12808@item -v 12809Include tag information for file. See @ref{Tags}. 12810@end table 12811 12812@c ------------------------------------------------------------ 12813@item tag [@var{options}] @var{tag} [@var{files}@dots{}] 12814Add a symbolic tag to checked out version of files. 12815See @ref{Revisions} and @ref{Branching and merging}. 12816 12817@table @code 12818@item -b 12819Create a branch named @var{tag}. See @ref{Branching and merging}. 12820 12821@item -c 12822Check that working files are unmodified. See 12823@ref{Tagging the working directory}. 12824 12825@item -D @var{date} 12826Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12827 12828@item -d 12829Delete @var{tag}. See @ref{Modifying tags}. 12830 12831@item -F 12832Move @var{tag} if it already exists. See @ref{Modifying tags}. 12833 12834@item -f 12835Force a head revision match if tag/date not found. 12836See @ref{Tagging by date/tag}. 12837 12838@item -l 12839Local; run only in current working directory. See @ref{Recursive behavior}. 12840 12841@item -R 12842Operate recursively (default). @xref{Recursive behavior}. 12843 12844@item -r @var{tag}[:@var{date}] 12845Tag the revision already tagged with @var{tag}, or when @var{date} is specified 12846and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12847existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12848@end table 12849 12850@c ------------------------------------------------------------ 12851@item unedit [@var{options}] [@var{files}@dots{}] 12852Undo an edit command. See @ref{Editing files}. 12853 12854@table @code 12855@item -l 12856Local; run only in current working directory. See @ref{Recursive behavior}. 12857 12858@item -R 12859Operate recursively (default). @xref{Recursive behavior}. 12860@end table 12861 12862@c ------------------------------------------------------------ 12863@item update [@var{options}] [@var{files}@dots{}] 12864Bring work tree in sync with repository. See 12865@ref{update}. 12866 12867@table @code 12868@item -A 12869Reset any sticky tags/date/options. See @ref{Sticky 12870tags} and @ref{Keyword substitution}. 12871 12872@item -C 12873Overwrite locally modified files with clean copies from 12874the repository (the modified file is saved in 12875@file{.#@var{file}.@var{revision}}, however). 12876 12877@item -D @var{date} 12878Check out revisions as of @var{date} (is sticky). See 12879@ref{Common options}. 12880 12881@item -d 12882Create directories. See @ref{update options}. 12883 12884@item -f 12885Use head revision if tag/date not found. See 12886@ref{Common options}. 12887 12888@item -I @var{ign} 12889More files to ignore (! to reset). See 12890@ref{import options}. 12891 12892@c Probably want to use rev1/rev2 style like for diff 12893@c -r. Here and in on-line help. 12894@item -j @var{tag}[:@var{date}] 12895Merge in changes from revisions specified by @var{tag} or, when @var{date} is 12896specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12897as it existed on @var{date}. See @ref{update options}. 12898 12899@item -k @var{kflag} 12900Use @var{kflag} keyword expansion. See 12901@ref{Substitution modes}. 12902 12903@item -l 12904Local; run only in current working directory. @xref{Recursive behavior}. 12905 12906@item -P 12907Prune empty directories. See @ref{Moving directories}. 12908 12909@item -p 12910Check out files to standard output (avoids 12911stickiness). See @ref{update options}. 12912 12913@item -R 12914Operate recursively (default). @xref{Recursive 12915behavior}. 12916 12917@item -r @var{tag}[:@var{date}] 12918Checkout the revisions specified by @var{tag} or, when @var{date} is specified 12919and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12920existed on @var{date}. See @ref{Common options}. 12921 12922@item -W @var{spec} 12923More wrappers. See @ref{import options}. 12924@end table 12925 12926@c ------------------------------------------------------------ 12927@item version 12928@cindex version (subcommand) 12929 12930Display the version of @sc{cvs} being used. If the repository 12931is remote, display both the client and server versions. 12932 12933@c ------------------------------------------------------------ 12934@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 12935 12936on/off: turn on/off read-only checkouts of files. See 12937@ref{Setting a watch}. 12938 12939add/remove: add or remove notification on actions. See 12940@ref{Getting Notified}. 12941 12942@table @code 12943@item -a @var{actions} 12944Specify actions for temporary watch, where 12945@var{actions} is @code{edit}, @code{unedit}, 12946@code{commit}, @code{all}, or @code{none}. See 12947@ref{Editing files}. 12948 12949@item -l 12950Local; run only in current working directory. See @ref{Recursive behavior}. 12951 12952@item -R 12953Operate recursively (default). @xref{Recursive 12954behavior}. 12955@end table 12956 12957@c ------------------------------------------------------------ 12958@item watchers [@var{options}] [@var{files}@dots{}] 12959See who is watching a file. See @ref{Watch information}. 12960 12961@table @code 12962@item -l 12963Local; run only in current working directory. See @ref{Recursive behavior}. 12964 12965@item -R 12966Operate recursively (default). @xref{Recursive 12967behavior}. 12968@end table 12969 12970@end table 12971 12972@c --------------------------------------------------------------------- 12973@node Administrative files 12974@appendix Reference manual for Administrative files 12975@cindex Administrative files (reference) 12976@cindex Files, reference manual 12977@cindex Reference manual (files) 12978@cindex CVSROOT (file) 12979 12980Inside the repository, in the directory 12981@file{$CVSROOT/CVSROOT}, there are a number of 12982supportive files for @sc{cvs}. You can use @sc{cvs} in a limited 12983fashion without any of them, but if they are set up 12984properly they can help make life easier. For a 12985discussion of how to edit them, see @ref{Intro 12986administrative files}. 12987 12988The most important of these files is the @file{modules} 12989file, which defines the modules inside the repository. 12990 12991@menu 12992* modules:: Defining modules 12993* Wrappers:: Specify binary-ness based on file name 12994* Trigger Scripts:: Launch scripts in response to server events 12995* rcsinfo:: Templates for the log messages 12996* cvsignore:: Ignoring files via cvsignore 12997* checkoutlist:: Adding your own administrative files 12998* history file:: History information 12999* Variables:: Various variables are expanded 13000* config:: Miscellaneous CVS configuration 13001@end menu 13002 13003@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13004@node modules 13005@appendixsec The modules file 13006@cindex Modules (admin file) 13007@cindex Defining modules (reference manual) 13008 13009The @file{modules} file records your definitions of 13010names for collections of source code. @sc{cvs} will 13011use these definitions if you use @sc{cvs} to update the 13012modules file (use normal commands like @code{add}, 13013@code{commit}, etc). 13014 13015The @file{modules} file may contain blank lines and 13016comments (lines beginning with @samp{#}) as well as 13017module definitions. Long lines can be continued on the 13018next line by specifying a backslash (@samp{\}) as the 13019last character on the line. 13020 13021There are three basic types of modules: alias modules, 13022regular modules, and ampersand modules. The difference 13023between them is the way that they map files in the 13024repository to files in the working directory. In all 13025of the following examples, the top-level repository 13026contains a directory called @file{first-dir}, which 13027contains two files, @file{file1} and @file{file2}, and a 13028directory @file{sdir}. @file{first-dir/sdir} contains 13029a file @file{sfile}. 13030 13031@c FIXME: should test all the examples in this section. 13032 13033@menu 13034* Alias modules:: The simplest kind of module 13035* Regular modules:: 13036* Ampersand modules:: 13037* Excluding directories:: Excluding directories from a module 13038* Module options:: Regular and ampersand modules can take options 13039* Module program options:: How the modules ``program options'' programs 13040 are run. 13041@end menu 13042 13043@node Alias modules 13044@appendixsubsec Alias modules 13045@cindex Alias modules 13046@cindex -a, in modules file 13047 13048Alias modules are the simplest kind of module: 13049 13050@table @code 13051@item @var{mname} -a @var{aliases}@dots{} 13052This represents the simplest way of defining a module 13053@var{mname}. The @samp{-a} flags the definition as a 13054simple alias: @sc{cvs} will treat any use of @var{mname} (as 13055a command argument) as if the list of names 13056@var{aliases} had been specified instead. 13057@var{aliases} may contain either other module names or 13058paths. When you use paths in aliases, @code{checkout} 13059creates all intermediate directories in the working 13060directory, just as if the path had been specified 13061explicitly in the @sc{cvs} arguments. 13062@end table 13063 13064For example, if the modules file contains: 13065 13066@example 13067amodule -a first-dir 13068@end example 13069 13070@noindent 13071then the following two commands are equivalent: 13072 13073@example 13074$ cvs co amodule 13075$ cvs co first-dir 13076@end example 13077 13078@noindent 13079and they each would provide output such as: 13080 13081@example 13082cvs checkout: Updating first-dir 13083U first-dir/file1 13084U first-dir/file2 13085cvs checkout: Updating first-dir/sdir 13086U first-dir/sdir/sfile 13087@end example 13088 13089@node Regular modules 13090@appendixsubsec Regular modules 13091@cindex Regular modules 13092 13093@table @code 13094@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 13095In the simplest case, this form of module definition 13096reduces to @samp{@var{mname} @var{dir}}. This defines 13097all the files in directory @var{dir} as module mname. 13098@var{dir} is a relative path (from @code{$CVSROOT}) to a 13099directory of source in the source repository. In this 13100case, on checkout, a single directory called 13101@var{mname} is created as a working directory; no 13102intermediate directory levels are used by default, even 13103if @var{dir} was a path involving several directory 13104levels. 13105@end table 13106 13107For example, if a module is defined by: 13108 13109@example 13110regmodule first-dir 13111@end example 13112 13113@noindent 13114then regmodule will contain the files from first-dir: 13115 13116@example 13117$ cvs co regmodule 13118cvs checkout: Updating regmodule 13119U regmodule/file1 13120U regmodule/file2 13121cvs checkout: Updating regmodule/sdir 13122U regmodule/sdir/sfile 13123$ 13124@end example 13125 13126By explicitly specifying files in the module definition 13127after @var{dir}, you can select particular files from 13128directory @var{dir}. Here is 13129an example: 13130 13131@example 13132regfiles first-dir/sdir sfile 13133@end example 13134 13135@noindent 13136With this definition, getting the regfiles module 13137will create a single working directory 13138@file{regfiles} containing the file listed, which 13139comes from a directory deeper 13140in the @sc{cvs} source repository: 13141 13142@example 13143$ cvs co regfiles 13144U regfiles/sfile 13145$ 13146@end example 13147 13148@node Ampersand modules 13149@appendixsubsec Ampersand modules 13150@cindex Ampersand modules 13151@cindex &, in modules file 13152 13153A module definition can refer to other modules by 13154including @samp{&@var{module}} in its definition. 13155@example 13156@var{mname} [ options ] @var{&module}@dots{} 13157@end example 13158 13159Then getting the module creates a subdirectory for each such 13160module, in the directory containing the module. For 13161example, if modules contains 13162 13163@example 13164ampermod &first-dir 13165@end example 13166 13167@noindent 13168then a checkout will create an @code{ampermod} directory 13169which contains a directory called @code{first-dir}, 13170which in turns contains all the directories and files 13171which live there. For example, the command 13172 13173@example 13174$ cvs co ampermod 13175@end example 13176 13177@noindent 13178will create the following files: 13179 13180@example 13181ampermod/first-dir/file1 13182ampermod/first-dir/file2 13183ampermod/first-dir/sdir/sfile 13184@end example 13185 13186There is one quirk/bug: the messages that @sc{cvs} 13187prints omit the @file{ampermod}, and thus do not 13188correctly display the location to which it is checking 13189out the files: 13190 13191@example 13192$ cvs co ampermod 13193cvs checkout: Updating first-dir 13194U first-dir/file1 13195U first-dir/file2 13196cvs checkout: Updating first-dir/sdir 13197U first-dir/sdir/sfile 13198$ 13199@end example 13200 13201Do not rely on this buggy behavior; it may get fixed in 13202a future release of @sc{cvs}. 13203 13204@c FIXCVS: What happens if regular and & modules are 13205@c combined, as in "ampermodule first-dir &second-dir"? 13206@c When I tried it, it seemed to just ignore the 13207@c "first-dir". I think perhaps it should be an error 13208@c (but this needs further investigation). 13209@c In addition to discussing what each one does, we 13210@c should put in a few words about why you would use one or 13211@c the other in various situations. 13212 13213@node Excluding directories 13214@appendixsubsec Excluding directories 13215@cindex Excluding directories, in modules file 13216@cindex !, in modules file 13217 13218An alias module may exclude particular directories from 13219other modules by using an exclamation mark (@samp{!}) 13220before the name of each directory to be excluded. 13221 13222For example, if the modules file contains: 13223 13224@example 13225exmodule -a !first-dir/sdir first-dir 13226@end example 13227 13228@noindent 13229then checking out the module @samp{exmodule} will check 13230out everything in @samp{first-dir} except any files in 13231the subdirectory @samp{first-dir/sdir}. 13232@c Note that the "!first-dir/sdir" sometimes must be listed 13233@c before "first-dir". That seems like a probable bug, in which 13234@c case perhaps it should be fixed (to allow either 13235@c order) rather than documented. See modules4 in testsuite. 13236 13237@node Module options 13238@appendixsubsec Module options 13239@cindex Options, in modules file 13240 13241Either regular modules or ampersand modules can contain 13242options, which supply additional information concerning 13243the module. 13244 13245@table @code 13246@cindex -d, in modules file 13247@item -d @var{name} 13248Name the working directory something other than the 13249module name. 13250@c FIXME: Needs a bunch of examples, analogous to the 13251@c examples for alias, regular, and ampersand modules 13252@c which show where the files go without -d. 13253 13254@cindex Export program 13255@cindex -e, in modules file 13256@item -e @var{prog} 13257Specify a program @var{prog} to run whenever files in a 13258module are exported. @var{prog} runs with a single 13259argument, the module name. 13260@c FIXME: Is it run on server? client? 13261 13262@cindex Checkout program 13263@cindex -o, in modules file 13264@item -o @var{prog} 13265Specify a program @var{prog} to run whenever files in a 13266module are checked out. @var{prog} runs with a single 13267argument, the module name. See @ref{Module program options} for 13268information on how @var{prog} is called. 13269@c FIXME: Is it run on server? client? 13270 13271@cindex Status of a module 13272@cindex Module status 13273@cindex -s, in modules file 13274@item -s @var{status} 13275Assign a status to the module. When the module file is 13276printed with @samp{cvs checkout -s} the modules are 13277sorted according to primarily module status, and 13278secondarily according to the module name. This option 13279has no other meaning. You can use this option for 13280several things besides status: for instance, list the 13281person that is responsible for this module. 13282 13283@cindex Tag program 13284@cindex -t, in modules file 13285@item -t @var{prog} 13286Specify a program @var{prog} to run whenever files in a 13287module are tagged with @code{rtag}. @var{prog} runs 13288with two arguments: the module name and the symbolic 13289tag specified to @code{rtag}. It is not run 13290when @code{tag} is executed. Generally you will find 13291that the @file{taginfo} file is a better solution (@pxref{taginfo}). 13292@c FIXME: Is it run on server? client? 13293@c Problems with -t include: 13294@c * It is run after the tag not before 13295@c * It doesn't get passed all the information that 13296@c taginfo does ("mov", &c). 13297@c * It only is run for rtag, not tag. 13298@end table 13299 13300You should also see @pxref{Module program options} about how the 13301``program options'' programs are run. 13302 13303@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13304 13305@node Module program options 13306@appendixsubsec How the modules file ``program options'' programs are run 13307@cindex Modules file program options 13308@cindex -t, in modules file 13309@cindex -o, in modules file 13310@cindex -e, in modules file 13311 13312@noindent 13313For checkout, rtag, and export, the program is server-based, and as such the 13314following applies:- 13315 13316If using remote access methods (pserver, ext, etc.), 13317@sc{cvs} will execute this program on the server from a temporary 13318directory. The path is searched for this program. 13319 13320If using ``local access'' (on a local or remote NFS file system, i.e. 13321repository set just to a path), 13322the program will be executed from the newly checked-out tree, if 13323found there, or alternatively searched for in the path if not. 13324 13325The programs are all run after the operation has effectively 13326completed. 13327 13328 13329@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13330@node Wrappers 13331@appendixsec The cvswrappers file 13332@cindex cvswrappers (admin file) 13333@cindex CVSWRAPPERS, environment variable 13334@cindex Wrappers 13335 13336@c FIXME: need some better way of separating this out 13337@c by functionality. -m is 13338@c one feature, and -k is a another. And this discussion 13339@c should be better motivated (e.g. start with the 13340@c problems, then explain how the feature solves it). 13341 13342Wrappers refers to a @sc{cvs} feature which lets you 13343control certain settings based on the name of the file 13344which is being operated on. The settings are @samp{-k} 13345for binary files, and @samp{-m} for nonmergeable text 13346files. 13347 13348The @samp{-m} option 13349specifies the merge methodology that should be used when 13350a non-binary file is updated. @code{MERGE} means the usual 13351@sc{cvs} behavior: try to merge the files. @code{COPY} 13352means that @code{cvs update} will refuse to merge 13353files, as it also does for files specified as binary 13354with @samp{-kb} (but if the file is specified as 13355binary, there is no need to specify @samp{-m 'COPY'}). 13356@sc{cvs} will provide the user with the 13357two versions of the files, and require the user using 13358mechanisms outside @sc{cvs}, to insert any necessary 13359changes. 13360 13361@strong{WARNING: do not use @code{COPY} with 13362@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 13363copy one version of your file over the other, wiping 13364out the previous contents.} 13365@c Ordinarily we don't document the behavior of old 13366@c versions. But this one is so dangerous, I think we 13367@c must. I almost renamed it to -m 'NOMERGE' so we 13368@c could say "never use -m 'COPY'". 13369The @samp{-m} wrapper option only affects behavior when 13370merging is done on update; it does not affect how files 13371are stored. See @ref{Binary files}, for more on 13372binary files. 13373 13374The basic format of the file @file{cvswrappers} is: 13375 13376@c FIXME: @example is all wrong for this. Use @deffn or 13377@c something more sensible. 13378@example 13379wildcard [option value][option value]... 13380 13381where option is one of 13382-m update methodology value: MERGE or COPY 13383-k keyword expansion value: expansion mode 13384 13385and value is a single-quote delimited value. 13386@end example 13387 13388@ignore 13389@example 13390*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' 13391*.c -t 'indent %s %s' 13392@end example 13393@c When does the filter need to be an absolute pathname 13394@c and when will something like the above work? I 13395@c suspect it relates to the PATH of the server (which 13396@c in turn depends on all kinds of stuff, e.g. inetd 13397@c for pserver). I'm not sure whether/where to discuss 13398@c this. 13399@c FIXME: What do the %s's stand for? 13400 13401@noindent 13402The above example of a @file{cvswrappers} file 13403states that all files/directories that end with a @code{.nib} 13404should be filtered with the @file{wrap} program before 13405checking the file into the repository. The file should 13406be filtered though the @file{unwrap} program when the 13407file is checked out of the repository. The 13408@file{cvswrappers} file also states that a @code{COPY} 13409methodology should be used when updating the files in 13410the repository (that is, no merging should be performed). 13411 13412@c What pitfalls arise when using indent this way? Is 13413@c it a winning thing to do? Would be nice to at least 13414@c hint at those issues; we want our examples to tell 13415@c how to solve problems, not just to say that cvs can 13416@c do certain things. 13417The last example line says that all files that end with 13418@code{.c} should be filtered with @file{indent} 13419before being checked into the repository. Unlike the previous 13420example, no filtering of the @code{.c} file is done when 13421it is checked out of the repository. 13422@noindent 13423The @code{-t} filter is called with two arguments, 13424the first is the name of the file/directory to filter 13425and the second is the pathname to where the resulting 13426filtered file should be placed. 13427 13428@noindent 13429The @code{-f} filter is called with one argument, 13430which is the name of the file to filter from. The end 13431result of this filter will be a file in the users directory 13432that they can work on as they normally would. 13433 13434Note that the @samp{-t}/@samp{-f} features do not 13435conveniently handle one portion of @sc{cvs}'s operation: 13436determining when files are modified. @sc{cvs} will still 13437want a file (or directory) to exist, and it will use 13438its modification time to determine whether a file is 13439modified. If @sc{cvs} erroneously thinks a file is 13440unmodified (for example, a directory is unchanged but 13441one of the files within it is changed), you can force 13442it to check in the file anyway by specifying the 13443@samp{-f} option to @code{cvs commit} (@pxref{commit 13444options}). 13445@c This is, of course, a serious design flaw in -t/-f. 13446@c Probably the whole functionality needs to be 13447@c redesigned (starting from requirements) to fix this. 13448@end ignore 13449 13450@c FIXME: We don't document -W or point to where it is 13451@c documented. Or .cvswrappers. 13452For example, the following command imports a 13453directory, treating files whose name ends in 13454@samp{.exe} as binary: 13455 13456@example 13457cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 13458@end example 13459 13460@c Another good example, would be storing files 13461@c (e.g. binary files) compressed in the repository. 13462@c :::::::::::::::::: 13463@c cvswrappers 13464@c :::::::::::::::::: 13465@c *.t12 -m 'COPY' 13466@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 13467@c 13468@c :::::::::::::::::: 13469@c gunzipcp 13470@c :::::::::::::::::: 13471@c : 13472@c [ -f $1 ] || exit 1 13473@c zcat $1 > /tmp/.#$1.$$ 13474@c mv /tmp/.#$1.$$ $1 13475@c 13476@c :::::::::::::::::: 13477@c gzipcp 13478@c :::::::::::::::::: 13479@c : 13480@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 13481@c if [ ! -d $DIRNAME ] ; then 13482@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 13483@c fi 13484@c gzip -c $DIRNAME > $2 13485@c One catch--"cvs diff" will not invoke the wrappers 13486@c (probably a CVS bug, although I haven't thought it out). 13487 13488@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13489@node Trigger Scripts 13490@appendixsec The Trigger Scripts 13491@cindex info files 13492@cindex trigger scripts 13493@cindex script hooks 13494 13495@c FIXME 13496@c Somewhere there needs to be a more "how-to" guide to writing these. 13497@c One particular issue that people sometimes are worried about is performance, 13498@c and the impact of writing in perl or sh or ____. Performance comparisons 13499@c should probably remain outside the scope of this document, but at least 13500@c _that_ much could be referenced, perhaps with links to other sources. 13501 13502Several of the administrative files support triggers, or the launching external 13503scripts or programs at specific times before or after particular events, during 13504the execution of @sc{cvs} commands. These hooks can be used to prevent certain 13505actions, log them, and/or maintain anything else you deem practical. 13506 13507All the trigger scripts are launched in a copy of the user sandbox being 13508committed, on the server, in client-server mode. In local mode, the scripts 13509are actually launched directly from the user sandbox directory being committed. 13510For most intents and purposes, the same scripts can be run in both locations 13511without alteration. 13512 13513@menu 13514* syntax:: The common syntax 13515* Trigger Script Security:: Trigger script security 13516 13517* commit files:: The commit support files (commitinfo, 13518 verifymsg, loginfo) 13519* commitinfo:: Pre-commit checking 13520* verifymsg:: How are log messages evaluated? 13521* loginfo:: Where should log messages be sent? 13522 13523* postadmin:: Logging admin commands 13524* taginfo:: Verifying/Logging tags 13525* posttag:: Logging tags 13526* postwatch:: Logging watch commands 13527 13528* preproxy:: Launch a script on a secondary server prior 13529 to becoming a write proxy 13530* postproxy:: Launch a script on a secondary server after 13531 completing proxy operations 13532@end menu 13533 13534@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13535@node syntax 13536@appendixsubsec The common syntax 13537@cindex info files, common syntax 13538@cindex script hooks, common syntax 13539@cindex trigger script hooks, common syntax 13540@cindex syntax of trigger script hooks 13541 13542@c FIXME: having this so totally separate from the 13543@c Variables node is rather bogus. 13544 13545The administrative files such as @file{commitinfo}, 13546@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 13547all have a common format. The purpose of the files are 13548described later on. The common syntax is described 13549here. 13550 13551@cindex Regular expression syntax 13552Each line contains the following: 13553 13554@itemize @bullet 13555@cindex @samp{ALL} keyword, in lieu of regular expressions in script hooks 13556@cindex @samp{DEFAULT} keyword, in lieu of regular expressions in script hooks 13557@item 13558A regular expression or the literal string @samp{DEFAULT}. Some script hooks 13559also support the literal string @samp{ALL}. Other than the @samp{ALL} and 13560@samp{DEFAULT} keywords, this is a basic regular expression in the syntax used 13561by GNU emacs. See the descriptions of the individual script hooks for 13562information on whether the @samp{ALL} keyword is supported 13563(@pxref{Trigger Scripts}). 13564@c FIXME: What we probably should be saying is "POSIX Basic 13565@c Regular Expression with the following extensions (`\(' 13566@c `\|' '+' etc)" 13567@c rather than define it with reference to emacs. 13568@c The reference to emacs is not strictly speaking 13569@c true, as we don't support \=, \s, or \S. Also it isn't 13570@c clear we should document and/or promise to continue to 13571@c support all the obscure emacs extensions like \<. 13572@c Also need to better cite (or include) full 13573@c documentation for the syntax. 13574@c Also see comment in configure.in about what happens to the 13575@c syntax if we pick up a system-supplied regexp matcher. 13576 13577@item 13578A whitespace separator---one or more spaces and/or tabs. 13579 13580@item 13581A file name or command-line template. 13582@end itemize 13583 13584@noindent 13585Blank lines are ignored. Lines that start with the 13586character @samp{#} are treated as comments. Long lines 13587unfortunately can @emph{not} be broken in two parts in 13588any way. 13589 13590The first regular expression that matches the current 13591directory name in the repository or the first line containing @samp{DEFAULT} 13592in lieu of a regular expression is used and all lines containing @samp{ALL} is 13593used for the hooks which support the @samp{ALL} keyword. The rest of the line 13594is used as a file name or command-line template as appropriate. See the 13595descriptions of the individual script hooks for information on whether the 13596@samp{ALL} keyword is supported (@pxref{Trigger Scripts}). 13597 13598@cindex format strings 13599@cindex format strings, common syntax 13600@cindex info files, common syntax, format strings 13601@cindex Common syntax of info files, format strings 13602@noindent 13603@emph{Note: The following information on format strings is valid 13604as long as the line @code{UseNewInfoFmtStrings=yes} appears in 13605your repository's config file (@pxref{config}). Otherwise, 13606default format strings may be appended to the command line and 13607the @samp{loginfo} file, especially, can exhibit slightly 13608different behavior. For more information, 13609@xref{Updating Commit Files}.} 13610 13611In the cases where the second segment of the matched line is a 13612command line template (e.g. @file{commitinfo}, @file{loginfo}, 13613& @file{verifymsg}), the command line template may contain format 13614strings which will be replaced with specific values before the 13615script is run. 13616@c FIXCVS then FIXME - it really would make sense to allow %r & maybe even %p 13617@c to be used in rcsinfo to construct a path, but I haven't 13618@c coded this yet. 13619 13620Format strings can represent a single variable or one or more 13621attributes of a list variable. An example of a list variable 13622would be the list available to scripts hung on the loginfo hooks 13623- the list of files which were just committed. In the case of 13624loginfo, three attributes are available for each list item: file 13625name, precommit version, and postcommit version. 13626 13627Format strings consist of a @samp{%} character followed by an optional 13628@samp{@{} (required in the multiple list attribute case), a 13629single format character representing a variable or a single attribute of 13630list elements or multiple format characters representing attributes of 13631list elements, and a closing @samp{@}} when the open bracket was present. 13632 13633@emph{Flat format strings}, or single format characters which get replaced 13634with a single value, will generate a single argument 13635to the called script, regardless of whether the replacement variable contains 13636white space or other special characters. 13637 13638@emph{List attributes} will generate an argument for each attribute 13639requested for each list item. For example, @samp{%@{sVv@}} 13640in a @file{loginfo} command template will generate three 13641arguments (file name, precommit version, postcommit version, 13642...) for each file committed. As in the flat format string 13643case, each attribute will be passed in as a single argument 13644regardless of whether it contains white space or other 13645special characters. 13646 13647@samp{%%} will be replaced with a literal @samp{%}. 13648 13649The format strings available to all script hooks are: 13650 13651@table @t 13652@item c 13653The canonical name of the command being executed. For instance, in the case of 13654a hook run from @code{cvs up}, @sc{cvs} would replace @samp{%c} with the string 13655@samp{update} and, in the case of a hook run from @code{cvs ci}, @sc{cvs} would 13656replace @samp{%c} with the string @samp{commit}. 13657@item n 13658The null, or empty, string. 13659@item p 13660The name of the directory being operated on within the repository. 13661@item r 13662The name of the repository (the path portion of @code{$CVSROOT}). 13663@item R 13664On a server, the name of the referrer, if any. The referrer is the CVSROOT the 13665client reports it used to contact a server which then referred it to this 13666server. Should usually be set on a primary server with a write proxy setup. 13667@end table 13668 13669Other format strings are file specific. See the docs on the 13670particular script hooks for more information 13671(@pxref{Trigger Scripts}). 13672 13673As an example, the following line in a @file{loginfo} file would 13674match only the directory @file{module} and any subdirectories of 13675@file{module}: 13676 13677@example 13678^module\(/\|$\) (echo; echo %p; echo %@{sVv@}; cat) >>$CVSROOT/CVSROOT/commitlog 13679@end example 13680 13681Using this same line and assuming a commit of new revisions 136821.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27, 13683respectively, of file1 and file2 in module, something like the 13684following log message should be appended to commitlog: 13685 13686@example 13687 13688module 13689file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1 13690Update of /cvsroot/module 13691In directory localhost.localdomain:/home/jrandom/work/module 13692 13693Modified Files: 13694 file1 file2 13695Log Message: 13696A log message. 13697@end example 13698 13699@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13700@node Trigger Script Security 13701@appendixsubsec Security and the Trigger Scripts 13702@cindex info files, security 13703@cindex script hooks, security 13704@cindex trigger scripts, security 13705 13706Security is a huge subject, and implementing a secure system is a non-trivial 13707task. This section will barely touch on all the issues involved, but it is 13708well to note that, as with any script you will be allowing an untrusted 13709user to run on your server, there are measures you can take to help prevent 13710your trigger scripts from being abused. 13711 13712For instance, since the CVS trigger scripts all run in a copy of the user's 13713sandbox on the server, a naively coded Perl trigger script which attempts to 13714use a Perl module that is not installed on the system can be hijacked by any 13715user with commit access who is checking in a file with the correct name. Other 13716scripting languages may be vulnerable to similar hacks. 13717 13718One way to make a script more secure, at least with Perl, is to use scripts 13719which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. 13720In the most basic terms, this causes Perl to avoid running code that may have 13721come from an external source. Please run the @code{perldoc perlsec} command 13722for more on Perl security. Again, other languages may implement other security 13723verification hooks which look more or less like Perl's "taint-check" mechanism. 13724 13725@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13726@node commit files 13727@appendixsubsec The commit support files 13728@cindex Commits, administrative support files 13729@cindex commit files, see Info files 13730 13731The @samp{-i} flag in the @file{modules} file can be 13732used to run a certain program whenever files are 13733committed (@pxref{modules}). The files described in 13734this section provide other, more flexible, ways to run 13735programs whenever something is committed. 13736 13737There are three kinds of programs that can be run on 13738commit. They are specified in files in the repository, 13739as described below. The following table summarizes the 13740file names and the purpose of the corresponding 13741programs. 13742 13743@table @file 13744@item commitinfo 13745The program is responsible for checking that the commit 13746is allowed. If it exits with a non-zero exit status 13747the commit will be aborted. @xref{commitinfo}. 13748 13749@item verifymsg 13750The specified program is used to evaluate the log message, 13751and possibly verify that it contains all required 13752fields. This is most useful in combination with the 13753@file{rcsinfo} file, which can hold a log message 13754template (@pxref{rcsinfo}). @xref{verifymsg}. 13755 13756@item loginfo 13757The specified program is called when the commit is 13758complete. It receives the log message and some 13759additional information and can store the log message in 13760a file, or mail it to appropriate persons, or maybe 13761post it to a local newsgroup, or@dots{} Your 13762imagination is the limit! @xref{loginfo}. 13763@end table 13764 13765@menu 13766* Updating Commit Files:: Updating legacy repositories to stop using 13767 deprecated command line template formats 13768@end menu 13769 13770@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13771@node Updating Commit Files 13772@appendixsubsubsec Updating legacy repositories to stop using deprecated command line template formats 13773@cindex info files, common syntax, updating legacy repositories 13774@cindex Syntax of info files, updating legacy repositories 13775@cindex Common syntax of info files, updating legacy repositories 13776New repositories are created set to use the new format strings by default, so 13777if you are creating a new repository, you shouldn't have to worry about this 13778section. 13779 13780If you are attempting to maintain a legacy repository which was 13781making use of the @file{commitinfo}, @file{editinfo}, @file{verifymsg}, 13782@file{loginfo}, and/or @file{taginfo} script hooks, you should have no 13783immediate problems with using the current @sc{cvs} executable, but your users 13784will probably start to see deprecation warnings. 13785 13786The reason for this is that all of the script hooks have been updated to 13787use a new command line parser that extensibly supports multiple 13788@file{loginfo} & @file{notify} style format strings (@pxref{syntax}) 13789and this support is not completely compatible with the old style format 13790strings. 13791 13792The quick upgrade method is to stick a @samp{1} after each format string 13793in your old @file{loginfo} file. For example: 13794 13795@example 13796DEFAULT (echo ""; id; echo %@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13797@end example 13798 13799would become: 13800 13801@example 13802DEFAULT (echo ""; id; echo %1@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13803@end example 13804 13805If you were counting on the fact that only the first @samp{%} in the line was 13806replaced as a format string, you may also have to double up any further 13807percent signs on the line. 13808 13809If you did this all at once and checked it in, everything should still be 13810running properly. 13811 13812Now add the following line to your config file (@pxref{config}): 13813@example 13814UseNewInfoFmtStrings=yes 13815@end example 13816 13817Everything should still be running properly, but your users will probably 13818start seeing new deprecation warnings. 13819 13820Dealing with the deprecation warnings now generated by @file{commitinfo}, 13821@file{editinfo}, @file{verifymsg}, and @file{taginfo} should be easy. Simply 13822specify what are currently implicit arguments explicitly. This means appending 13823the following strings to each active command line template in each file: 13824@table @code 13825@item commitinfo 13826@samp{ %r/%p %s} 13827@item editinfo 13828@samp{ %l} 13829@item taginfo 13830@samp{ %t %o %p %@{sv@}} 13831@item verifymsg 13832@samp{ %l} 13833@end table 13834 13835If you don't desire that any of the newly available information be passed to 13836the scripts hanging off of these hooks, no further modifications to these 13837files should be necessary to insure current and future compatibility with 13838@sc{cvs}'s format strings. 13839 13840Fixing @file{loginfo} could be a little tougher. The old style 13841@file{loginfo} format strings caused a single space and comma separated 13842argument to be passed in in place of the format string. This is what will 13843continue to be generated due to the deprecated @samp{1} you inserted into 13844the format strings. 13845 13846Since the new format separates each individual item and passes it into the 13847script as a separate argument (for a good reason - arguments containing commas 13848and/or white space are now parsable), to remove the deprecated @samp{1} from 13849your @file{loginfo} command line templates, you will most likely have to 13850rewrite any scripts called by the hook to handle the new argument format. 13851 13852Also note that the way @samp{%} followed by unrecognized characters and by 13853@samp{@{@}} was treated in past versions of CVS is not strictly adhered to as 13854there were bugs in the old versions. Specifically, @samp{%@{@}} would eat the 13855next character and unrecognized strings resolved only to the empty string, 13856which was counter to what was stated in the documentation. This version will 13857do what the documentation said it should have (if you were using only some 13858combination of @samp{%@{sVv@}}, e.g. @samp{%@{sVv@}}, @samp{%@{sV@}}, or 13859@samp{%v}, you should have no troubles). 13860 13861On the bright side, you should have plenty of time to do this before all 13862support for the old format strings is removed from @sc{cvs}, so you can just 13863put up with the deprecation warnings for awhile if you like. 13864 13865@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13866@node commitinfo 13867@appendixsubsec Commitinfo 13868@cindex @file{commitinfo} 13869@cindex Commits, precommit verification of 13870@cindex commitinfo (admin file) 13871@cindex info files, commitinfo 13872@cindex script hooks, commitinfo 13873@cindex trigger scripts, commitinfo 13874@cindex info files, precommit verification of commits 13875@cindex script hooks, precommit verification of commits 13876@cindex trigger scripts, precommit verification of commits 13877 13878The @file{commitinfo} file defines programs to execute 13879whenever @samp{cvs commit} is about to execute. These 13880programs are used for pre-commit checking to verify 13881that the modified, added and removed files are really 13882ready to be committed. This could be used, for 13883instance, to verify that the changed files conform to 13884to your site's standards for coding practice. 13885 13886The @file{commitinfo} file has the standard form for script hooks 13887(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13888a command to execute. It supports only the DEFAULT keywords. 13889 13890@cindex format strings, commitinfo admin file 13891In addition to the common format strings (@pxref{syntax}), 13892@file{commitinfo} supports: 13893 13894@table @t 13895@item @{s@} 13896a list of the names of files to be committed 13897@end table 13898 13899@cindex commitinfo (admin file), updating legacy repositories 13900@cindex compatibility notes, commitinfo admin file 13901Currently, if no format strings are specified, a default 13902string of @samp{ %r/%p %@{s@}} will be appended to the command 13903line template before replacement is performed, but this 13904feature is deprecated. It is simply in place so that legacy 13905repositories will remain compatible with the new @sc{cvs} application. 13906For information on updating, @pxref{Updating Commit Files}. 13907 13908@cindex Exit status, of commitinfo 13909@cindex commitinfo (admin file), exit status 13910The first line with a regular expression matching the 13911directory within the repository will be used. If the 13912command returns a non-zero exit status the commit will 13913be aborted. 13914@c FIXME: need example(s) of what "directory within the 13915@c repository" means. 13916 13917@cindex @file{commitinfo}, working directory 13918@cindex @file{commitinfo}, command environment 13919The command will be run in the root of the workspace 13920containing the new versions of any files the user would like 13921to modify (commit), @emph{or in a copy of the workspace on 13922the server (@pxref{Remote repositories})}. If a file is 13923being removed, there will be no copy of the file under the 13924current directory. If a file is being added, there will be 13925no corresponding archive file in the repository unless the 13926file is being resurrected. 13927 13928Note that both the repository directory and the corresponding 13929Attic (@pxref{Attic}) directory may need to be checked to 13930locate the archive file corresponding to any given file being 13931committed. Much of the information about the specific commit 13932request being made, including the destination branch, commit 13933message, and command line options specified, is not available 13934to the command. 13935 13936@c FIXME: should discuss using commitinfo to control 13937@c who has checkin access to what (e.g. Joe can check into 13938@c directories a, b, and c, and Mary can check into 13939@c directories b, c, and d--note this case cannot be 13940@c conveniently handled with unix groups). Of course, 13941@c adding a new set of features to CVS might be a more 13942@c natural way to fix this problem than telling people to 13943@c use commitinfo. 13944@c FIXME: Should make some reference, especially in 13945@c the context of controlling who has access, to the fact 13946@c that commitinfo can be circumvented. Perhaps 13947@c mention SETXID (but has it been carefully examined 13948@c for holes?). This fits in with the discussion of 13949@c general CVS security in "Password authentication 13950@c security" (the bit which is not pserver-specific). 13951 13952@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13953@node verifymsg 13954@appendixsubsec Verifying log messages 13955@cindex @file{verifymsg} (admin file) 13956@cindex Log message, verifying 13957@cindex logging, commits 13958 13959Once you have entered a log message, you can evaluate 13960that message to check for specific content, such as 13961a bug ID. Use the @file{verifymsg} file to 13962specify a program that is used to verify the log message. 13963This program could be a simple script that checks 13964that the entered message contains the required fields. 13965 13966The @file{verifymsg} file is often most useful together 13967with the @file{rcsinfo} file, which can be used to 13968specify a log message template (@pxref{rcsinfo}). 13969 13970The @file{verifymsg} file has the standard form for script hooks 13971(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13972a command to execute. It supports only the DEFAULT keywords. 13973 13974@cindex format strings, verifymsg admin file 13975In addition to the common format strings (@pxref{syntax}), 13976@file{verifymsg} supports: 13977 13978@table @t 13979@item l 13980the full path to the file containing the log message to be verified 13981@item @{sV@} 13982File attributes, where: 13983@table @t 13984@item s 13985file name 13986@item V 13987old version number (pre-checkin) 13988@end table 13989@end table 13990 13991@cindex verifymsg (admin/commit file), updating legacy repositories 13992@cindex compatibility notes, verifymsg admin file 13993Currently, if no format strings are specified, a default 13994string of @samp{ %l} will be appended to the command 13995line template before replacement is performed, but this 13996feature is deprecated. It is simply in place so that legacy 13997repositories will remain compatible with the new @sc{cvs} application. 13998For information on updating, @pxref{Updating Commit Files}. 13999 14000One thing that should be noted is that the @samp{ALL} 14001keyword is not supported. If more than one matching 14002line is found, the first one is used. This can be 14003useful for specifying a default verification script in a 14004directory, and then overriding it in a subdirectory. 14005 14006@cindex Exit status, of @file{verifymsg} 14007If the verification script exits with a non-zero exit status, 14008the commit is aborted. 14009 14010@cindex @file{verifymsg}, changing the log message 14011In the default configuration, CVS allows the 14012verification script to change the log message. This is 14013controlled via the RereadLogAfterVerify CVSROOT/config 14014option. 14015 14016When @samp{RereadLogAfterVerify=always} or 14017@samp{RereadLogAfterVerify=stat}, the log message will 14018either always be reread after the verification script 14019is run or reread only if the log message file status 14020has changed. 14021 14022@xref{config}, for more on CVSROOT/config options. 14023 14024It is NOT a good idea for a @file{verifymsg} script to 14025interact directly with the user in the various 14026client/server methods. For the @code{pserver} method, 14027there is no protocol support for communicating between 14028@file{verifymsg} and the client on the remote end. For the 14029@code{ext} and @code{server} methods, it is possible 14030for CVS to become confused by the characters going 14031along the same channel as the CVS protocol 14032messages. See @ref{Remote repositories}, for more 14033information on client/server setups. In addition, at the time 14034the @file{verifymsg} script runs, the CVS 14035server has locks in place in the repository. If control is 14036returned to the user here then other users may be stuck waiting 14037for access to the repository. 14038 14039This option can be useful if you find yourself using an 14040rcstemplate that needs to be modified to remove empty 14041elements or to fill in default values. It can also be 14042useful if the rcstemplate has changed in the repository 14043and the CVS/Template was not updated, but is able to be 14044adapted to the new format by the verification script 14045that is run by @file{verifymsg}. 14046 14047An example of an update might be to change all 14048occurrences of 'BugId:' to be 'DefectId:' (which can be 14049useful if the rcstemplate has recently been changed and 14050there are still checked-out user trees with cached 14051copies in the CVS/Template file of the older version). 14052 14053Another example of an update might be to delete a line 14054that contains 'BugID: none' from the log message after 14055validation of that value as being allowed is made. 14056 14057@menu 14058* verifymsg example:: Verifymsg example 14059@end menu 14060 14061@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14062@node verifymsg example 14063@appendixsubsubsec Verifying log messages 14064@cindex verifymsg, example 14065The following is a little silly example of a 14066@file{verifymsg} file, together with the corresponding 14067@file{rcsinfo} file, the log message template and a 14068verification script. We begin with the log message template. 14069We want to always record a bug-id number on the first 14070line of the log message. The rest of log message is 14071free text. The following template is found in the file 14072@file{/usr/cvssupport/tc.template}. 14073 14074@example 14075BugId: 14076@end example 14077 14078The script @file{/usr/cvssupport/bugid.verify} is used to 14079evaluate the log message. 14080 14081@example 14082#!/bin/sh 14083# 14084# bugid.verify filename 14085# 14086# Verify that the log message contains a valid bugid 14087# on the first line. 14088# 14089if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 14090 exit 0 14091elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 14092 # It is okay to allow commits with 'BugId: none', 14093 # but do not put that text into the real log message. 14094 grep -v '^BugId:[ ]*none$' > $1.rewrite 14095 mv $1.rewrite $1 14096 exit 0 14097else 14098 echo "No BugId found." 14099 exit 1 14100fi 14101@end example 14102 14103The @file{verifymsg} file contains this line: 14104 14105@example 14106^tc /usr/cvssupport/bugid.verify %l 14107@end example 14108 14109The @file{rcsinfo} file contains this line: 14110 14111@example 14112^tc /usr/cvssupport/tc.template 14113@end example 14114 14115The @file{config} file contains this line: 14116 14117@example 14118RereadLogAfterVerify=always 14119@end example 14120 14121 14122 14123@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14124@node loginfo 14125@appendixsubsec Loginfo 14126@cindex loginfo (admin file) 14127@cindex logging, commits 14128@cindex Storing log messages 14129@cindex Mailing log messages 14130@cindex Distributing log messages 14131@cindex Log messages 14132 14133The @file{loginfo} file is used to control where log information is sent after 14134versioned changes are made to repository archive files and after directories 14135are added ot the repository. @ref{posttag} for how to log tagging 14136information and @ref{postadmin} for how to log changes due to the @code{admin} 14137command. 14138 14139The @file{loginfo} file has the standard form for script hooks 14140(@pxref{Trigger Scripts}), where each line is a regular expression followed by 14141a command to execute. It supports the ALL and DEFAULT keywords. 14142 14143Any specified scripts are called: 14144 14145@table @code 14146@item commit 14147Once per directory, immediately after a successfully completing the commit of 14148all files within that directory. 14149@item import 14150Once per import, immediately after completion of all write operations. 14151@item add 14152Immediately after the successful @code{add} of a directory. 14153@end table 14154 14155Any script called via @file{loginfo} will be fed the log information on its 14156standard input. Note that the filter program @strong{must} read @strong{all} 14157of the log information from its standard input or @sc{cvs} may fail with a 14158broken pipe signal. 14159 14160@cindex format strings, loginfo admin file 14161In addition to the common format strings (@pxref{syntax}), 14162@file{loginfo} supports: 14163 14164@table @t 14165@item @{stVv@} 14166File attributes, where: 14167@table @t 14168@item s 14169file name 14170@item T 14171tag name of destination, or the empty string when there is no associated 14172tag name (this usually means the trunk) 14173@item V 14174old version number (pre-checkin) 14175@item v 14176new version number (post-checkin) 14177@end table 14178@end table 14179 14180For example, some valid format strings are @samp{%%}, 14181@samp{%s}, @samp{%@{s@}}, and @samp{%@{stVv@}}. 14182 14183@cindex loginfo (admin file), updating legacy repositories 14184@cindex compatibility notes, loginfo admin file 14185Currently, if @samp{UseNewInfoFmtStrings} is not set in the @file{config} 14186administration file (@pxref{config}), the format strings will be substituted 14187as they were in past versions of @sc{cvs}, but this feature is deprecated. 14188It is simply in place so that legacy repositories will remain compatible with 14189the new @sc{cvs} application. For information on updating, 14190please see @ref{Updating Commit Files}. 14191 14192As an example, if @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%p} 14193and @samp{%@{sVv@}} are the format strings, and three files (@t{ChangeLog}, 14194@t{Makefile}, @t{foo.c}) were modified, the output might be: 14195 14196@example 14197yoyodyne/tc ChangeLog 1.1 1.2 Makefile 1.3 1.4 foo.c 1.12 1.13 14198@end example 14199 14200Note: when @sc{cvs} is accessing a remote repository, 14201@file{loginfo} will be run on the @emph{remote} 14202(i.e., server) side, not the client side (@pxref{Remote 14203repositories}). 14204 14205@menu 14206* loginfo example:: Loginfo example 14207* Keeping a checked out copy:: Updating a tree on every checkin 14208@end menu 14209 14210@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14211@node loginfo example 14212@appendixsubsubsec Loginfo example 14213 14214The following @file{loginfo} file, together with the 14215tiny shell-script below, appends all log messages 14216to the file @file{$CVSROOT/CVSROOT/commitlog}, 14217and any commits to the administrative files (inside 14218the @file{CVSROOT} directory) are also logged in 14219@file{/usr/adm/cvsroot-log}. 14220Commits to the @file{prog1} directory are mailed to @t{ceder}. 14221 14222@c FIXME: is it a CVS feature or bug that only the 14223@c first matching line is used? It is documented 14224@c above, but is it useful? For example, if we wanted 14225@c to run both "cvs-log" and "Mail" for the CVSROOT 14226@c directory, it is kind of awkward if 14227@c only the first matching line is used. 14228@example 14229ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 14230^CVSROOT\(/\|$\) /usr/local/bin/cvs-log /usr/adm/cvsroot-log $USER 14231^prog1\(/\|$\) Mail -s "%p %s" ceder 14232@end example 14233 14234The shell-script @file{/usr/local/bin/cvs-log} looks 14235like this: 14236 14237@example 14238#!/bin/sh 14239(echo "------------------------------------------------------"; 14240 echo -n "$2 "; 14241 date; 14242 echo; 14243 cat) >> $1 14244@end example 14245 14246 14247 14248@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14249@node Keeping a checked out copy 14250@appendixsubsubsec Keeping a checked out copy 14251 14252@c What other index entries? It seems like 14253@c people might want to use a lot of different 14254@c words for this functionality. 14255@cindex Keeping a checked out copy 14256@cindex Checked out copy, keeping 14257@cindex Web pages, maintaining with CVS 14258 14259It is often useful to maintain a directory tree which 14260contains files which correspond to the latest version 14261in the repository. For example, other developers might 14262want to refer to the latest sources without having to 14263check them out, or you might be maintaining a web site 14264with @sc{cvs} and want every checkin to cause the files 14265used by the web server to be updated. 14266@c Can we offer more details on the web example? Or 14267@c point the user at how to figure it out? This text 14268@c strikes me as sufficient for someone who already has 14269@c some idea of what we mean but not enough for the naive 14270@c user/sysadmin to understand it and set it up. 14271 14272The way to do this is by having loginfo invoke 14273@code{cvs update}. Doing so in the naive way will 14274cause a problem with locks, so the @code{cvs update} 14275must be run in the background. 14276@c Should we try to describe the problem with locks? 14277@c It seems like a digression for someone who just 14278@c wants to know how to make it work. 14279@c Another choice which might work for a single file 14280@c is to use "cvs -n update -p" which doesn't take 14281@c out locks (I think) but I don't see many advantages 14282@c of that and we might as well document something which 14283@c works for multiple files. 14284Here is an example for unix (this should all be on one line): 14285 14286@example 14287^cyclic-pages\(/\|$\) (date; cat; (sleep 2; cd /u/www/local-docs; 14288 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 14289@end example 14290 14291This will cause checkins to repository directory @code{cyclic-pages} 14292and its subdirectories to update the checked 14293out tree in @file{/u/www/local-docs}. 14294@c More info on some of the details? The "sleep 2" is 14295@c so if we are lucky the lock will be gone by the time 14296@c we start and we can wait 2 seconds instead of 30. 14297 14298 14299 14300@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14301@node postadmin 14302@appendixsubsec Logging admin commands 14303@cindex postadmin (admin file) 14304@cindex script hook, postadmin 14305@cindex Admin commands, logging 14306 14307The @file{postadmin} file defines programs to execute after an @code{admin} 14308command modifies files. The @file{postadmin} file has the standard form 14309for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14310expression followed by a command to execute. It supports the ALL and DEFAULT 14311keywords. 14312 14313@cindex format strings, postadmin admin file 14314The @file{postadmin} file supports no format strings other than the common 14315ones (@pxref{syntax}), 14316 14317 14318 14319@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14320@node taginfo 14321@appendixsubsec Taginfo 14322@cindex taginfo (admin file) 14323@cindex script hook, taginfo 14324@cindex Tags, logging 14325@cindex Tags, verifying 14326The @file{taginfo} file defines programs to execute 14327when someone executes a @code{tag} or @code{rtag} 14328command. The @file{taginfo} file has the standard form 14329for script hooks (@pxref{Trigger Scripts}), where each line 14330is a regular expression followed by a command to execute. 14331It supports the ALL and DEFAULT keywords. 14332 14333@cindex format strings, taginfo admin file 14334In addition to the common format strings (@pxref{syntax}), 14335@file{taginfo} supports: 14336 14337@table @t 14338@item b 14339tag type (@code{T} for branch, @code{N} for not-branch, or @code{?} for 14340unknown, as during delete operations) 14341@item o 14342operation (@code{add} for @code{tag}, @code{mov} for @code{tag -F}, or 14343@code{del} for @code{tag -d}) 14344@item t 14345new tag name 14346@item @{sTVv@} 14347file attributes, where: 14348@table @t 14349@item s 14350file name 14351@item T 14352tag name of destination, or the empty string when there is no associated 14353tag name (this usually means the trunk) 14354@item V 14355old version number (for a move or delete operation) 14356@item v 14357new version number (for an add or move operation) 14358@end table 14359@end table 14360 14361For example, some valid format strings are @samp{%%}, @samp{%p}, @samp{%t}, 14362@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 14363 14364@cindex taginfo (admin file), updating legacy repositories 14365@cindex compatibility notes, taginfo admin file 14366Currently, if no format strings are specified, a default 14367string of @samp{ %t %o %p %@{sv@}} will be appended to the command 14368line template before replacement is performed, but this 14369feature is deprecated. It is simply in place so that legacy 14370repositories will remain compatible with the new @sc{cvs} application. 14371For information on updating, @pxref{Updating Commit Files}. 14372 14373@cindex Exit status, of taginfo admin file 14374@cindex taginfo (admin file), exit status 14375A non-zero exit of the filter program will cause the tag to be 14376aborted. 14377 14378Here is an example of using @file{taginfo} to log @code{tag} and @code{rtag} 14379commands. In the @file{taginfo} file put: 14380 14381@example 14382ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %@{sVv@} 14383@end example 14384 14385@noindent 14386Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 14387following script: 14388 14389@example 14390#!/bin/sh 14391echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 14392@end example 14393 14394 14395 14396@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14397@node posttag 14398@appendixsubsec Logging tags 14399@cindex posttag (admin file) 14400@cindex script hook, posttag 14401@cindex Tags, logging 14402 14403The @file{posttag} file defines programs to execute after a @code{tag} or 14404@code{rtag} command modifies files. The @file{posttag} file has the standard 14405form for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14406expression followed by a command to execute. It supports the ALL and DEFAULT 14407keywords. 14408 14409@cindex format strings, posttag admin file 14410The @file{posttag} admin file supports the same format strings as the 14411@file{taginfo} file (@pxref{taginfo}), 14412 14413 14414 14415@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14416@node postwatch 14417@appendixsubsec Logging watch commands 14418@cindex postwatch (admin file) 14419@cindex script hook, postwatch 14420@cindex Watch family of commands, logging 14421 14422The @file{postwatch} file defines programs to execute after any command (for 14423instance, @code{watch}, @code{edit}, @code{unedit}, or @code{commit}) modifies 14424any @file{CVS/fileattr} file in the repository (@pxref{Watches}). The 14425@file{postwatch} file has the standard form for script hooks 14426(@pxref{Trigger Scripts}), where each line is a regular expression followed by 14427a command to execute. It supports the ALL and DEFAULT keywords. 14428 14429@cindex format strings, postwatch admin file 14430The @file{postwatch} file supports no format strings other than the common 14431ones (@pxref{syntax}), but it is worth noting that the @code{%c} format string 14432may not be replaced as you might expect. Client runs of @code{edit} and 14433@code{unedit} can sometimes skip contacting the @sc{cvs} server and cache the 14434notification of the file attribute change to be sent the next time the client 14435contacts the server for whatever other reason, 14436 14437 14438 14439@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14440@node preproxy 14441@appendixsubsec Launch a Script before Proxying 14442@cindex preproxy (admin file) 14443@cindex script hook, preproxy 14444@cindex Write proxy, verifying 14445@cindex Write proxy, logging 14446 14447The @file{preproxy} file defines programs to execute after a secondary 14448server receives a write request from a client, just before it starts up the 14449primary server and becomes a write proxy. This hook could be used to 14450dial a modem, launch an SSH tunnel, establish a VPN, or anything else that 14451might be necessary to do before contacting the primary server. 14452 14453@file{preproxy} scripts are called once, at the time of the write request, with 14454the repository argument (if requested) set from the topmost directory sent by 14455the client. 14456 14457The @file{preproxy} file has the standard form 14458for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14459expression followed by a command to execute. It supports the ALL and DEFAULT 14460keywords. 14461 14462@cindex format strings, preproxy admin file 14463In addition to the common format strings, the @file{preproxy} file supports the 14464following format string: 14465 14466@table @t 14467@item P 14468the CVSROOT string which specifies the primary server 14469@end table 14470 14471 14472 14473@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14474@node postproxy 14475@appendixsubsec Launch a Script after Proxying 14476@cindex postproxy (admin file) 14477@cindex script hook, postproxy 14478@cindex Write proxy, logging 14479@cindex Write proxy, pull updates 14480@cindex secondary server, pull updates 14481 14482The @file{postproxy} file defines programs to execute after a secondary 14483server notes that the connection to the primary server has shut down and before 14484it releases the client by shutting down the connection to the client. 14485This could hook could be used to 14486disconnect a modem, an SSH tunnel, a VPN, or anything else that 14487might be necessary to do after contacting the primary server. This hook should 14488also be used to pull updates from the primary server before allowing the client 14489which did the write to disconnect since otherwise the client's next read 14490request may generate error messages and fail upon encountering an out of date 14491repository on the secondary server. 14492 14493@file{postproxy} scripts are called once per directory. 14494 14495The @file{postproxy} file has the standard form 14496for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14497expression followed by a command to execute. It supports the ALL and DEFAULT 14498keywords. 14499 14500@cindex format strings, postproxy admin file 14501In addition to the common format strings, the @file{postproxy} file supports 14502the following format string: 14503 14504@table @t 14505@item P 14506the CVSROOT string which specifies the primary server 14507@end table 14508 14509 14510 14511@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14512@node rcsinfo 14513@appendixsec Rcsinfo 14514@cindex rcsinfo (admin file) 14515@cindex Form for log message 14516@cindex Log message template 14517@cindex Template for log message 14518@cindex logging, commits 14519 14520The @file{rcsinfo} file can be used to specify a form to 14521edit when filling out the commit log. The 14522@file{rcsinfo} file has a syntax similar to the 14523@file{verifymsg}, @file{commitinfo} and @file{loginfo} 14524files. @xref{syntax}. Unlike the other files the second 14525part is @emph{not} a command-line template. Instead, 14526the part after the regular expression should be a full pathname to 14527a file containing the log message template. 14528 14529If the repository name does not match any of the 14530regular expressions in this file, the @samp{DEFAULT} 14531line is used, if it is specified. 14532 14533All occurrences of the name @samp{ALL} appearing as a 14534regular expression are used in addition to the first 14535matching regular expression or @samp{DEFAULT}. 14536 14537@c FIXME: should be offering advice, somewhere around 14538@c here, about where to put the template file. The 14539@c verifymsg example uses /usr/cvssupport but doesn't 14540@c say anything about what that directory is for or 14541@c whether it is hardwired into CVS or who creates 14542@c it or anything. In particular we should say 14543@c how to version control the template file. A 14544@c probably better answer than the /usr/cvssupport 14545@c stuff is to use checkoutlist (with xref to the 14546@c checkoutlist doc). 14547@c Also I am starting to see a connection between 14548@c this and the Keeping a checked out copy node. 14549@c Probably want to say something about that. 14550The log message template will be used as a default log 14551message. If you specify a log message with @samp{cvs 14552commit -m @var{message}} or @samp{cvs commit -f 14553@var{file}} that log message will override the 14554template. 14555 14556@xref{verifymsg}, for an example @file{rcsinfo} 14557file. 14558 14559When @sc{cvs} is accessing a remote repository, 14560the contents of @file{rcsinfo} at the time a directory 14561is first checked out will specify a template. This 14562template will be updated on all @samp{cvs update} 14563commands. It will also be added to new directories 14564added with a @samp{cvs add new-directory} command. 14565In versions of @sc{cvs} prior to version 1.12, the 14566@file{CVS/Template} file was not updated. If the 14567@sc{cvs} server is at version 1.12 or higher an older 14568client may be used and the @file{CVS/Template} will 14569be updated from the server. 14570 14571@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14572@node cvsignore 14573@appendixsec Ignoring files via cvsignore 14574@cindex cvsignore (admin file), global 14575@cindex Global cvsignore 14576@cindex Ignoring files 14577@c -- This chapter should maybe be moved to the 14578@c tutorial part of the manual? 14579 14580There are certain file names that frequently occur 14581inside your working copy, but that you don't want to 14582put under @sc{cvs} control. Examples are all the object 14583files that you get while you compile your sources. 14584Normally, when you run @samp{cvs update}, it prints a 14585line for each file it encounters that it doesn't know 14586about (@pxref{update output}). 14587 14588@sc{cvs} has a list of files (or sh(1) file name patterns) 14589that it should ignore while running @code{update}, 14590@code{import} and @code{release}. 14591@c -- Are those the only three commands affected? 14592This list is constructed in the following way. 14593 14594@itemize @bullet 14595@item 14596The list is initialized to include certain file name 14597patterns: names associated with @sc{cvs} 14598administration, or with other common source control 14599systems; common names for patch files, object files, 14600archive files, and editor backup files; and other names 14601that are usually artifacts of assorted utilities. 14602Currently, the default list of ignored file name 14603patterns is: 14604 14605@cindex Ignored files 14606@cindex Automatically ignored files 14607@example 14608 RCS SCCS CVS CVS.adm 14609 RCSLOG cvslog.* 14610 tags TAGS 14611 .make.state .nse_depinfo 14612 *~ #* .#* ,* _$* *$ 14613 *.old *.bak *.BAK *.orig *.rej .del-* 14614 *.a *.olb *.o *.obj *.so *.exe 14615 *.Z *.elc *.ln 14616 core 14617@end example 14618 14619@item 14620The per-repository list in 14621@file{$CVSROOT/CVSROOT/cvsignore} is appended to 14622the list, if that file exists. 14623 14624@item 14625The per-user list in @file{.cvsignore} in your home 14626directory is appended to the list, if it exists. 14627 14628@item 14629Any entries in the environment variable 14630@code{$CVSIGNORE} is appended to the list. 14631 14632@item 14633Any @samp{-I} options given to @sc{cvs} is appended. 14634 14635@item 14636As @sc{cvs} traverses through your directories, the contents 14637of any @file{.cvsignore} will be appended to the list. 14638The patterns found in @file{.cvsignore} are only valid 14639for the directory that contains them, not for 14640any sub-directories. 14641@end itemize 14642 14643In any of the 5 places listed above, a single 14644exclamation mark (@samp{!}) clears the ignore list. 14645This can be used if you want to store any file which 14646normally is ignored by @sc{cvs}. 14647 14648Specifying @samp{-I !} to @code{cvs import} will import 14649everything, which is generally what you want to do if 14650you are importing files from a pristine distribution or 14651any other source which is known to not contain any 14652extraneous files. However, looking at the rules above 14653you will see there is a fly in the ointment; if the 14654distribution contains any @file{.cvsignore} files, then 14655the patterns from those files will be processed even if 14656@samp{-I !} is specified. The only workaround is to 14657remove the @file{.cvsignore} files in order to do the 14658import. Because this is awkward, in the future 14659@samp{-I !} might be modified to override 14660@file{.cvsignore} files in each directory. 14661 14662Note that the syntax of the ignore files consists of a 14663series of lines, each of which contains a space 14664separated list of filenames. This offers no clean way 14665to specify filenames which contain spaces, but you can 14666use a workaround like @file{foo?bar} to match a file 14667named @file{foo bar} (it also matches @file{fooxbar} 14668and the like). Also note that there is currently no 14669way to specify comments. 14670@c FIXCVS? I don't _like_ this syntax at all, but 14671@c changing it raises all the usual compatibility 14672@c issues and I'm also not sure what to change it to. 14673 14674@node checkoutlist 14675@appendixsec The checkoutlist file 14676@cindex checkoutlist 14677 14678It may be helpful to use @sc{cvs} to maintain your own 14679files in the @file{CVSROOT} directory. For example, 14680suppose that you have a script @file{logcommit.pl} 14681which you run by including the following line in the 14682@file{commitinfo} administrative file: 14683 14684@example 14685ALL $CVSROOT/CVSROOT/logcommit.pl %r/%p %s 14686@end example 14687 14688To maintain @file{logcommit.pl} with @sc{cvs} you would 14689add the following line to the @file{checkoutlist} 14690administrative file: 14691 14692@example 14693logcommit.pl 14694@end example 14695 14696The format of @file{checkoutlist} is one line for each 14697file that you want to maintain using @sc{cvs}, giving 14698the name of the file, followed optionally by more whitespace 14699and any error message that should print if the file cannot be 14700checked out into CVSROOT after a commit: 14701 14702@example 14703logcommit.pl Could not update CVSROOT/logcommit.pl. 14704@end example 14705 14706After setting up @file{checkoutlist} in this fashion, 14707the files listed there will function just like 14708@sc{cvs}'s built-in administrative files. For example, 14709when checking in one of the files you should get a 14710message such as: 14711 14712@example 14713cvs commit: Rebuilding administrative file database 14714@end example 14715 14716@noindent 14717and the checked out copy in the @file{CVSROOT} 14718directory should be updated. 14719 14720Note that listing @file{passwd} (@pxref{Password 14721authentication server}) in @file{checkoutlist} is not 14722recommended for security reasons. 14723 14724For information about keeping a checkout out copy in a 14725more general context than the one provided by 14726@file{checkoutlist}, see @ref{Keeping a checked out 14727copy}. 14728 14729@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14730@node history file 14731@appendixsec The history file 14732@cindex History file 14733@cindex Log information, saving 14734 14735By default, the file @file{$CVSROOT/CVSROOT/history} is used 14736to log information for the @code{history} command (@pxref{history}). 14737This file name may be changed with the @samp{HistoryLogPath} and 14738@samp{HistorySearchPath} config options (@pxref{config}). 14739 14740The file format of the @file{history} file is 14741documented only in comments in the @sc{cvs} source 14742code, but generally programs should use the @code{cvs 14743history} command to access it anyway, in case the 14744format changes with future releases of @sc{cvs}. 14745 14746@node Variables 14747@appendixsec Expansions in administrative files 14748@cindex Internal variables 14749@cindex Variables 14750 14751Sometimes in writing an administrative file, you might 14752want the file to be able to know various things based 14753on environment @sc{cvs} is running in. There are 14754several mechanisms to do that. 14755 14756To find the home directory of the user running @sc{cvs} 14757(from the @code{HOME} environment variable), use 14758@samp{~} followed by @samp{/} or the end of the line. 14759Likewise for the home directory of @var{user}, use 14760@samp{~@var{user}}. These variables are expanded on 14761the server machine, and don't get any reasonable 14762expansion if pserver (@pxref{Password authenticated}) 14763is in use; therefore user variables (see below) may be 14764a better choice to customize behavior based on the user 14765running @sc{cvs}. 14766@c Based on these limitations, should we deprecate ~? 14767@c What is it good for? Are people using it? 14768 14769One may want to know about various pieces of 14770information internal to @sc{cvs}. A @sc{cvs} internal 14771variable has the syntax @code{$@{@var{variable}@}}, 14772where @var{variable} starts with a letter and consists 14773of alphanumeric characters and @samp{_}. If the 14774character following @var{variable} is a 14775non-alphanumeric character other than @samp{_}, the 14776@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 14777internal variables are: 14778 14779@table @code 14780@item CVSROOT 14781@cindex CVSROOT, internal variable 14782This is the absolute path to the current @sc{cvs} root directory. 14783@xref{Repository}, for a description of the various 14784ways to specify this, but note that the internal 14785variable contains just the directory and not any 14786of the access method information. 14787 14788@item RCSBIN 14789@cindex RCSBIN, internal variable 14790In @sc{cvs} 1.9.18 and older, this specified the 14791directory where @sc{cvs} was looking for @sc{rcs} 14792programs. Because @sc{cvs} no longer runs @sc{rcs} 14793programs, specifying this internal variable is now an 14794error. 14795 14796@item CVSEDITOR 14797@cindex CVSEDITOR, internal variable 14798@itemx EDITOR 14799@cindex EDITOR, internal variable 14800@itemx VISUAL 14801@cindex VISUAL, internal variable 14802These all expand to the same value, which is the editor 14803that @sc{cvs} is using. @xref{Global options}, for how 14804to specify this. 14805 14806@item USER 14807@cindex USER, internal variable 14808Username of the user running @sc{cvs} (on the @sc{cvs} 14809server machine). 14810When using pserver, this is the user specified in the repository 14811specification which need not be the same as the username the 14812server is running as (@pxref{Password authentication server}). 14813Do not confuse this with the environment variable of the same name. 14814 14815@item SESSIONID 14816@cindex COMMITID, internal variable 14817Unique Session ID of the @sc{cvs} process. This is a 14818random string of printable characters of at least 16 14819characters length. Users should assume that it may 14820someday grow to at most 256 characters in length. 14821 14822@item COMMITID 14823@cindex COMMITID, internal variable 14824Unique Session ID of the @sc{cvs} process. This is a 14825random string of printable characters of at least 16 14826characters length. Users should assume that it may 14827someday grow to at most 256 characters in length. 14828@end table 14829 14830If you want to pass a value to the administrative files 14831which the user who is running @sc{cvs} can specify, 14832use a user variable. 14833@cindex User variables 14834To expand a user variable, the 14835administrative file contains 14836@code{$@{=@var{variable}@}}. To set a user variable, 14837specify the global option @samp{-s} to @sc{cvs}, with 14838argument @code{@var{variable}=@var{value}}. It may be 14839particularly useful to specify this option via 14840@file{.cvsrc} (@pxref{~/.cvsrc}). 14841 14842For example, if you want the administrative file to 14843refer to a test directory you might create a user 14844variable @code{TESTDIR}. Then if @sc{cvs} is invoked 14845as 14846 14847@example 14848cvs -s TESTDIR=/work/local/tests 14849@end example 14850 14851@noindent 14852and the 14853administrative file contains @code{sh 14854$@{=TESTDIR@}/runtests}, then that string is expanded 14855to @code{sh /work/local/tests/runtests}. 14856 14857All other strings containing @samp{$} are reserved; 14858there is no way to quote a @samp{$} character so that 14859@samp{$} represents itself. 14860 14861Environment variables passed to administrative files are: 14862 14863@table @code 14864@cindex environment variables, passed to administrative files 14865 14866@item CVS_USER 14867@cindex CVS_USER, environment variable 14868The @sc{cvs}-specific username provided by the user, if it 14869can be provided (currently just for the pserver access 14870method), and to the empty string otherwise. (@code{CVS_USER} 14871and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 14872is used to map @sc{cvs} usernames to system usernames.) 14873 14874@item LOGNAME 14875@cindex LOGNAME, environment variable 14876The username of the system user. 14877 14878@item USER 14879@cindex USER, environment variable 14880Same as @code{LOGNAME}. 14881Do not confuse this with the internal variable of the same name. 14882@end table 14883 14884@node config 14885@appendixsec The CVSROOT/config configuration file 14886 14887@cindex configuration file 14888@cindex config, in CVSROOT 14889@cindex CVSROOT/config 14890 14891Usually, the @file{config} file is found at @file{$CVSROOT/CVSROOT/config}, 14892but this may be overridden on the @code{pserver} and @code{server} command 14893lines (@pxref{server & pserver}). 14894 14895The administrative file @file{config} contains various 14896miscellaneous settings which affect the behavior of 14897@sc{cvs}. The syntax is slightly different from the 14898other administrative files. 14899 14900Leading white space on any line is ignored, though the syntax is very strict 14901and will reject spaces and tabs almost anywhere else. 14902 14903Empty lines, lines containing nothing but white space, and lines which start 14904with @samp{#} (discounting any leading white space) are ignored. 14905 14906@c FIXME: where do we define comments for the other 14907@c administrative files. 14908Other lines consist of the optional leading white space, a keyword, @samp{=}, 14909and a value. Please note again that this syntax is very strict. 14910Extraneous spaces or tabs, other than the leading white space, are not 14911permitted on these lines. 14912@c See comments in parseinfo.c:parse_config for more 14913@c discussion of this strictness. 14914 14915As of CVS 1.12.13, lines of the form @samp{[@var{CVSROOT}]} mark the subsequent 14916section of the config file as applying only to certain repositories. Multiple 14917@samp{[@var{CVSROOT}]} lines without intervening 14918@samp{@var{KEYWORD}=@var{VALUE}} pairs cause processing to fall through, 14919processing subsequent keywords for any root in the list. Finally, keywords 14920and values which appear before any @samp{[@var{CVSROOT}]} lines are defaults, 14921and may to apply to any repository. For example, consider the following file: 14922 14923@example 14924# Defaults 14925LogHistory=TMAR 14926 14927[/cvsroots/team1] 14928 LockDir=/locks/team1 14929 14930[/cvsroots/team2] 14931 LockDir=/locks/team2 14932 14933[/cvsroots/team3] 14934 LockDir=/locks/team3 14935 14936[/cvsroots/team4] 14937 LockDir=/locks/team4 14938 14939[/cvsroots/team3] 14940[/cvsroots/team4] 14941 # Override logged commands for teams 3 & 4. 14942 LogHistory=all 14943@end example 14944 14945This example file sets up separate lock directories for each project, as well 14946as a default set of logged commands overridden for the example's team 3 & 14947team 4. This syntax could be useful, for instance, if you wished to share a 14948single config file, for instance @file{/etc/cvs.conf}, among several 14949repositories. 14950 14951Currently defined keywords are: 14952 14953@table @code 14954@cindex HistoryLogPath, in CVSROOT/config 14955@item HistorySearchPath=@var{pattern} 14956Request that @sc{cvs} look for its history information in files matching 14957@var{pattern}, which is a standard UNIX file glob. If @var{pattern} matches 14958multiple files, all will be searched in lexicographically sorted order. 14959@xref{history}, and @ref{history file}, for more. 14960 14961If no value is supplied for this option, it defaults to 14962@file{$CVSROOT/CVSROOT/history}. 14963 14964@cindex HistorySearchPath, in CVSROOT/config 14965@item HistoryLogPath=@var{path} 14966Control where @sc{cvs} logs its history. If the file does not exist, @sc{cvs} 14967will attempt to create it. Format strings, as available to the GNU C 14968@code{strftime} function and often the UNIX date command, and the string 14969@var{$CVSROOT} will be substituted in this path. For example, consider the 14970line: 14971 14972@example 14973HistoryLogPath=$CVSROOT/CVSROOT/history/%Y-%m-%d 14974@end example 14975 14976This line would cause @sc{cvs} to attempt to create its history file in a 14977subdirectory (@file{history}) of the configuration directory (@file{CVSROOT}) 14978with a name equal to the current date representation in the ISO8601 format (for 14979example, on May 11, 2005, @sc{cvs} would attempt to log its history under the 14980repository root directory in a file named @file{CVSROOT/history/2005-05-11}). 14981@xref{history}, and @ref{history file}, for more. 14982 14983If no value is supplied for this option, it defaults to 14984@file{$CVSROOT/CVSROOT/history}. 14985 14986@cindex ImportNewFilesToVendorBranchOnly, in CVSROOT/config 14987@cindex import, config admin file 14988@cindex config (admin file), import 14989@item ImportNewFilesToVendorBranchOnly=@var{value} 14990Specify whether @code{cvs import} should always behave as if the 14991@samp{-X} flag was specified on the command line. 14992@var{value} may be either @samp{yes} or @samp{no}. If set to @samp{yes}, 14993all uses of @code{cvs import} on the repository will behave as if the 14994@samp{-X} flag was set. The default value is @samp{no}. 14995 14996@cindex KeywordExpand, in CVSROOT/config 14997@item KeywordExpand=@var{value} 14998Specify @samp{i} followed by a list of keywords to be expanded 14999(for example, @samp{KeywordExpand=iMYCVS,Name,Date}), 15000or @samp{e} followed by a list of keywords not to be expanded 15001(for example, @samp{KeywordExpand=eCVSHeader}). 15002For more on keyword expansion, see @ref{Configuring keyword expansion}. 15003 15004@cindex LocalKeyword, in CVSROOT/config 15005@item LocalKeyword=@var{value} 15006Specify a local alias for a standard keyword. 15007For example, @samp{LocalKeyword=MYCVS=CVSHeader}. 15008For more on local keywords, see @ref{Keyword substitution}. 15009 15010@cindex LockDir, in CVSROOT/config 15011@item LockDir=@var{directory} 15012Put @sc{cvs} lock files in @var{directory} rather than 15013directly in the repository. This is useful if you want 15014to let users read from the repository while giving them 15015write access only to @var{directory}, not to the 15016repository. 15017It can also be used to put the locks on a very fast 15018in-memory file system to speed up locking and unlocking 15019the repository. 15020You need to create @var{directory}, but 15021@sc{cvs} will create subdirectories of @var{directory} as it 15022needs them. For information on @sc{cvs} locks, see 15023@ref{Concurrency}. 15024 15025@c Mention this in Compatibility section? 15026Before enabling the LockDir option, make sure that you 15027have tracked down and removed any copies of @sc{cvs} 1.9 or 15028older. Such versions neither support LockDir, nor will 15029give an error indicating that they don't support it. 15030The result, if this is allowed to happen, is that some 15031@sc{cvs} users will put the locks one place, and others will 15032put them another place, and therefore the repository 15033could become corrupted. @sc{cvs} 1.10 does not support 15034LockDir but it will print a warning if run on a 15035repository with LockDir enabled. 15036 15037@cindex LogHistory, in CVSROOT/config 15038@item LogHistory=@var{value} 15039Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). 15040Default of @samp{TOEFWUPCGMARX} (or simply @samp{all}) will log 15041all transactions. Any subset of the default is 15042legal. (For example, to only log transactions that modify the 15043@file{*,v} files, use @samp{LogHistory=TMAR}.) To disable history logging 15044completely, use @samp{LogHistory=}. 15045 15046@cindex MaxCommentLeaderLength, in CVSROOT/config 15047@cindex Log keyword, configuring substitution behavior 15048@item MaxCommentLeaderLength=@var{length} 15049Set to some length, in bytes, where a trailing @samp{k}, @samp{M}, @samp{G}, 15050or @samp{T} causes the preceding nubmer to be interpreted as kilobytes, 15051megabytes, gigabytes, or terrabytes, respectively, will cause 15052@code{$@splitrcskeyword{Log}$} keywords (@pxref{Keyword substitution}), with 15053more than @var{length} bytes preceding it on a line to be ignored (or to fall 15054back on the comment leader set in the RCS archive file - see 15055@code{UseArchiveCommentLeader} below). Defaults to 20 bytes to allow checkouts 15056to proceed normally when they include binary files containing 15057@code{$@splitrcskeyword{Log}$} keywords and which users have neglected to mark 15058as binary. 15059 15060@cindex MinCompressionLevel, in CVSROOT/config 15061@cindex MaxCompressionLevel, in CVSROOT/config 15062@cindex Compression levels, restricting on server 15063@item MinCompressionLevel=@var{value} 15064@itemx MaxCompressionLevel=@var{value} 15065Restricts the level of compression used by the @sc{cvs} server to a @var{value} 15066between 0 and 9. @var{value}s 1 through 9 are the same @sc{zlib} compression 15067levels accepted by the @samp{-z} option (@pxref{Global options}), and 0 means 15068no compression. When one or both of these keys are set and a client requests a 15069level outside the specified range, the server will simply use the closest 15070permissable level. Clients will continue compressing at the level requested by 15071the user. 15072 15073The exception is when level 0 (no compression) is not available and the client 15074fails to request any compression. The @sc{cvs} server will then exit with an 15075error message when it becomes apparent that the client is not going to request 15076compression. This will not happen with clients version 1.12.13 and later since 15077these client versions allow the server to notify them that they must request 15078some level of compression. 15079 15080@ignore 15081@cindex PreservePermissions, in CVSROOT/config 15082@item PreservePermissions=@var{value} 15083Enable support for saving special device files, 15084symbolic links, file permissions and ownerships in the 15085repository. The default value is @samp{no}. 15086@xref{Special Files}, for the full implications of using 15087this keyword. 15088@end ignore 15089 15090@cindex PrimaryServer, in CVSROOT/config 15091@cindex Primary server 15092@cindex Secondary server 15093@cindex proxy, write 15094@cindex write proxy 15095@item PrimaryServer=@var{CVSROOT} 15096When specified, and the repository specified by @var{CVSROOT} is not the one 15097currently being accessed, then the server will turn itself into a transparent 15098proxy to @var{CVSROOT} for write requests. The @var{hostname} configured as 15099part of @var{CVSROOT} must resolve to the same string returned by the 15100@command{uname} command on the primary server for this to work. Host name 15101resolution is performed via some combination of @command{named}, a broken out 15102line from @file{/etc/hosts}, and the Network Information Service (NIS or YP), 15103depending on the configuration of the particular system. 15104 15105Only the @samp{:ext:} method is 15106currently supported for primaries (actually, @samp{:fork:} is supported as 15107well, but only for testing - if you find another use for accessing a primary 15108via the @samp{:fork:} method, please send a note to @email{bug-cvs@@nongnu.org} 15109about it). See @ref{Write proxies} for more on configuring and using write 15110proxies. 15111 15112@cindex RCSBIN, in CVSROOT/config 15113@item RCSBIN=@var{bindir} 15114For @sc{cvs} 1.9.12 through 1.9.18, this setting told 15115@sc{cvs} to look for @sc{rcs} programs in the 15116@var{bindir} directory. Current versions of @sc{cvs} 15117do not run @sc{rcs} programs; for compatibility this 15118setting is accepted, but it does nothing. 15119 15120@cindex RereadLogAfterVerify, in CVSROOT/config 15121@cindex @file{verifymsg}, changing the log message 15122@item RereadLogAfterVerify=@var{value} 15123Modify the @samp{commit} command such that CVS will reread the 15124log message after running the program specified by @file{verifymsg}. 15125@var{value} may be one of @samp{yes} or @samp{always}, indicating that 15126the log message should always be reread; @samp{no} 15127or @samp{never}, indicating that it should never be 15128reread; or @var{value} may be @samp{stat}, indicating 15129that the file should be checked with the file system 15130@samp{stat()} function to see if it has changed (see warning below) 15131before rereading. The default value is @samp{always}. 15132 15133@strong{Note: the `stat' mode can cause CVS to pause for up to 15134one extra second per directory committed. This can be less IO and 15135CPU intensive but is not recommended for use with large repositories} 15136 15137@xref{verifymsg}, for more information on how verifymsg 15138may be used. 15139 15140@cindex SystemAuth, in CVSROOT/config 15141@item SystemAuth=@var{value} 15142If @var{value} is @samp{yes}, then pserver should check 15143for users in the system's user database if not found in 15144@file{CVSROOT/passwd}. If it is @samp{no}, then all 15145pserver users must exist in @file{CVSROOT/passwd}. 15146The default is @samp{yes}. For more on pserver, see 15147@ref{Password authenticated}. 15148 15149@cindex TmpDir, in config 15150@cindex temporary files, location of 15151@cindex temporary directory, set in config 15152@item TmpDir=@var{path} 15153Specify @var{path} as the directory to create temporary files in. 15154@xref{Global options}, for more on setting the path to the temporary 15155directory. This option first appeared with @sc{cvs} release 1.12.13. 15156 15157@cindex TopLevelAdmin, in CVSROOT/config 15158@item TopLevelAdmin=@var{value} 15159Modify the @samp{checkout} command to create a 15160@samp{CVS} directory at the top level of the new 15161working directory, in addition to @samp{CVS} 15162directories created within checked-out directories. 15163The default value is @samp{no}. 15164 15165This option is useful if you find yourself performing 15166many commands at the top level of your working 15167directory, rather than in one of the checked out 15168subdirectories. The @file{CVS} directory created there 15169will mean you don't have to specify @code{CVSROOT} for 15170each command. It also provides a place for the 15171@file{CVS/Template} file (@pxref{Working directory 15172storage}). 15173 15174@cindex UseArchiveCommentLeader, in CVSROOT/config 15175@cindex Log keyword, configuring substitution behavior 15176@item UseArchiveCommentLeader=@var{value} 15177Set to @code{true}, if the text preceding a @code{$@splitrcskeyword{Log}$} 15178keyword is found to exceed @code{MaxCommentLeaderLength} (above) bytes, then 15179the comment leader set in the RCS archive file (@pxref{admin}), if any, will 15180be used instead. If there is no comment leader set in the archive file or 15181@var{value} is set to @samp{false}, then the keyword will not be expanded 15182(@pxref{Keyword list}). To force the comment leader in the RCS archive file to 15183be used exclusively (and @code{$@splitrcskeyword{Log}$} expansion skipped in 15184files where the comment leader has not been set in the archive file), set 15185@var{value} and set @code{MaxCommentLeaderLength} to @code{0}. 15186 15187@cindex UseNewInfoFmtStrings, in CVSROOT/config 15188@cindex format strings, config admin file 15189@cindex config (admin file), updating legacy repositories 15190@cindex compatibility notes, config admin file 15191@item UseNewInfoFmtStrings=@var{value} 15192Specify whether @sc{cvs} should support the new or old command line 15193template model for the commit support files (@pxref{commit files}). 15194This configuration variable began life in deprecation and is only here 15195in order to give people time to update legacy repositories to use the new 15196format string syntax before support for the old syntax is removed. For 15197information on updating your repository to support the new model, 15198please see @ref{Updating Commit Files}. 15199 15200@emph{Note that new repositories (created with the @code{cvs init} command) 15201will have this value set to @samp{yes}, but the default value is @samp{no}.} 15202 15203@cindex UserAdminOptions, in CVSROOT/config 15204@item UserAdminOptions=@var{value} 15205Control what options will be allowed with the @code{cvs admin} 15206command (@pxref{admin}) for users not in the @code{cvsadmin} group. 15207The @var{value} string is a list of single character options 15208which should be allowed. If a user who is not a member of the 15209@code{cvsadmin} group tries to execute any @code{cvs admin} 15210option which is not listed they will will receive an error message 15211reporting that the option is restricted. 15212 15213If no @code{cvsadmin} group exists on the server, @sc{cvs} will 15214ignore the @code{UserAdminOptions} keyword (@pxref{admin}). 15215 15216When not specified, @code{UserAdminOptions} defaults to 15217@samp{k}. In other words, it defaults to allowing 15218users outside of the @code{cvsadmin} group to use the 15219@code{cvs admin} command only to change the default keyword 15220expansion mode for files. 15221 15222As an example, to restrict users not in the @code{cvsadmin} 15223group to using @code{cvs admin} to change the default keyword 15224substitution mode, lock revisions, unlock revisions, and 15225replace the log message, use @samp{UserAdminOptions=klum}. 15226@end table 15227 15228 15229 15230@c --------------------------------------------------------------------- 15231@node Environment variables 15232@appendix All environment variables which affect CVS 15233@cindex Environment variables 15234@cindex Reference manual for variables 15235 15236This is a complete list of all environment variables 15237that affect @sc{cvs} (Windows users, please bear with this list; 15238$VAR is equivalent to %VAR% at the Windows command prompt). 15239 15240@table @code 15241@cindex CVSIGNORE, environment variable 15242@item $CVSIGNORE 15243A whitespace-separated list of file name patterns that 15244@sc{cvs} should ignore. @xref{cvsignore}. 15245 15246@cindex CVSWRAPPERS, environment variable 15247@item $CVSWRAPPERS 15248A whitespace-separated list of file name patterns that 15249@sc{cvs} should treat as wrappers. @xref{Wrappers}. 15250 15251@cindex CVSREAD, environment variable 15252@cindex Read-only files, and CVSREAD 15253@item $CVSREAD 15254If this is set, @code{checkout} and @code{update} will 15255try hard to make the files in your working directory 15256read-only. When this is not set, the default behavior 15257is to permit modification of your working files. 15258 15259@cindex CVSREADONLYFS, environment variable 15260@item $CVSREADONLYFS 15261Turns on read-only repository mode. This allows one to 15262check out from a read-only repository, such as within 15263an anoncvs server, or from a @sc{cd-rom} repository. 15264 15265It has the same effect as if the @samp{-R} command-line 15266option is used. This can also allow the use of 15267read-only NFS repositories. 15268 15269@item $CVSUMASK 15270Controls permissions of files in the repository. See 15271@ref{File permissions}. 15272 15273@item $CVSROOT 15274Should contain the full pathname to the root of the @sc{cvs} 15275source repository (where the @sc{rcs} files are 15276kept). This information must be available to @sc{cvs} for 15277most commands to execute; if @code{$CVSROOT} is not set, 15278or if you wish to override it for one invocation, you 15279can supply it on the command line: @samp{cvs -d cvsroot 15280cvs_command@dots{}} Once you have checked out a working 15281directory, @sc{cvs} stores the appropriate root (in 15282the file @file{CVS/Root}), so normally you only need to 15283worry about this when initially checking out a working 15284directory. 15285 15286@item $CVSEDITOR 15287@cindex CVSEDITOR, environment variable 15288@itemx $EDITOR 15289@cindex EDITOR, environment variable 15290@itemx $VISUAL 15291@cindex VISUAL, environment variable 15292Specifies the program to use for recording log messages 15293during commit. @code{$CVSEDITOR} overrides 15294@code{$EDITOR}, which overrides @code{$VISUAL}. 15295See @ref{Committing your changes} for more or 15296@ref{Global options} for alternative ways of specifying a 15297log editor. 15298 15299@cindex PATH, environment variable 15300@item $PATH 15301If @code{$RCSBIN} is not set, and no path is compiled 15302into @sc{cvs}, it will use @code{$PATH} to try to find all 15303programs it uses. 15304 15305@cindex HOME, environment variable 15306@item $HOME 15307@cindex HOMEPATH, environment variable 15308@item $HOMEPATH 15309@cindex HOMEDRIVE, environment variable 15310@item $HOMEDRIVE 15311Used to locate the directory where the @file{.cvsrc} 15312file, and other such files, are searched. On Unix, @sc{cvs} 15313just checks for @code{HOME}. On Windows NT, the system will 15314set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 15315for example to @file{\joe}. On Windows 95, you'll 15316probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 15317@c We are being vague about whether HOME works on 15318@c Windows; see long comment in windows-NT/filesubr.c. 15319 15320@cindex CVS_RSH, environment variable 15321@item $CVS_RSH 15322Specifies the external program which @sc{cvs} connects with, 15323when @code{:ext:} access method is specified. 15324@pxref{Connecting via rsh}. 15325 15326@item $CVS_SERVER 15327Used in client-server mode when accessing a remote 15328repository using @sc{rsh}. It specifies the name of 15329the program to start on the server side (and any 15330necessary arguments) when accessing a remote repository 15331using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 15332The default value for @code{:ext:} and @code{:server:} is @code{cvs}; 15333the default value for @code{:fork:} is the name used to run the client. 15334@pxref{Connecting via rsh} 15335 15336@item $CVS_PASSFILE 15337Used in client-server mode when accessing the @code{cvs 15338login server}. Default value is @file{$HOME/.cvspass}. 15339@pxref{Password authentication client} 15340 15341@cindex CVS_CLIENT_PORT 15342@item $CVS_CLIENT_PORT 15343Used in client-server mode to set the port to use when accessing the server 15344via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 15345if the port is not specified in the CVSROOT. 15346@pxref{Remote repositories} 15347 15348@cindex CVS_PROXY_PORT 15349@item $CVS_PROXY_PORT 15350Used in client-server mode to set the port to use when accessing a server 15351via a web proxy, if the port is not specified in the CVSROOT. Works with 15352GSSAPI, and the password authentication protocol. 15353@pxref{Remote repositories} 15354 15355@cindex CVS_RCMD_PORT, environment variable 15356@item $CVS_RCMD_PORT 15357Used in client-server mode. If set, specifies the port 15358number to be used when accessing the @sc{rcmd} demon on 15359the server side. (Currently not used for Unix clients). 15360 15361@cindex CVS_CLIENT_LOG, environment variable 15362@item $CVS_CLIENT_LOG 15363Used for debugging only in client-server 15364mode. If set, everything sent to the server is logged 15365into @file{@code{$CVS_CLIENT_LOG}.in} and everything 15366sent from the server is logged into 15367@file{@code{$CVS_CLIENT_LOG}.out}. 15368 15369@cindex CVS_SERVER_SLEEP, environment variable 15370@item $CVS_SERVER_SLEEP 15371Used only for debugging the server side in 15372client-server mode. If set, delays the start of the 15373server child process the specified amount of 15374seconds so that you can attach to it with a debugger. 15375 15376@cindex CVS_IGNORE_REMOTE_ROOT, environment variable 15377@item $CVS_IGNORE_REMOTE_ROOT 15378For @sc{cvs} 1.10 and older, setting this variable 15379prevents @sc{cvs} from overwriting the @file{CVS/Root} 15380file when the @samp{-d} global option is specified. 15381Later versions of @sc{cvs} do not rewrite 15382@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 15383effect. 15384 15385@cindex CVS_LOCAL_BRANCH_NUM, environment variable 15386@item $CVS_LOCAL_BRANCH_NUM 15387Setting this variable allows some control over the 15388branch number that is assigned. This is specifically to 15389support the local commit feature of CVSup. If one sets 15390@code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches 15391the local repository, the revision numbers will look 15392like 1.66.1000.xx. There is almost a dead-set certainty 15393that there will be no conflicts with version numbers. 15394 15395@cindex COMSPEC, environment variable 15396@item $COMSPEC 15397Used under OS/2 only. It specifies the name of the 15398command interpreter and defaults to @sc{cmd.exe}. 15399 15400@cindex TMPDIR, environment variable 15401@cindex temporary file directory, set via environment variable 15402@cindex temporary files, location of 15403@item $TMPDIR 15404Directory in which temporary files are located. 15405@xref{Global options}, for more on setting the temporary directory. 15406 15407@cindex CVS_PID, environment variable 15408@item $CVS_PID 15409This is the process identification (aka pid) number of 15410the @sc{cvs} process. It is often useful in the 15411programs and/or scripts specified by the 15412@file{commitinfo}, @file{verifymsg}, @file{loginfo} 15413files. 15414@end table 15415 15416@node Compatibility 15417@appendix Compatibility between CVS Versions 15418 15419@cindex CVS, versions of 15420@cindex Versions, of CVS 15421@cindex Compatibility, between CVS versions 15422@c We don't mention versions older than CVS 1.3 15423@c on the theory that it would clutter it up for the vast 15424@c majority of people, who don't have anything that old. 15425@c 15426The repository format is compatible going back to 15427@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 15428you have copies of @sc{cvs} 1.6 or older and you want 15429to use the optional developer communication features. 15430@c If you "cvs rm" and commit using 1.3, then you'll 15431@c want to run "rcs -sdead <file,v>" on each of the 15432@c files in the Attic if you then want 1.5 and 15433@c later to recognize those files as dead (I think the 15434@c symptom if this is not done is that files reappear 15435@c in joins). (Wait: the above will work but really to 15436@c be strictly correct we should suggest checking 15437@c in a new revision rather than just changing the 15438@c state of the head revision, shouldn't we?). 15439@c The old convert.sh script was for this, but it never 15440@c did get updated to reflect use of the RCS "dead" 15441@c state. 15442@c Note: this is tricky to document without confusing 15443@c people--need to carefully say what CVS version we 15444@c are talking about and keep in mind the distinction 15445@c between a 15446@c repository created with 1.3 and on which one now 15447@c uses 1.5+, and a repository on which one wants to 15448@c use both versions side by side (e.g. during a 15449@c transition period). 15450@c Wait, can't CVS just detect the case in which a file 15451@c is in the Attic but the head revision is not dead? 15452@c Not sure whether this should produce a warning or 15453@c something, and probably needs further thought, but 15454@c it would appear that the situation can be detected. 15455@c 15456@c We might want to separate out the 1.3 compatibility 15457@c section (for repository & working directory) from the 15458@c rest--that might help avoid confusing people who 15459@c are upgrading (for example) from 1.6 to 1.8. 15460@c 15461@c A minor incompatibility is if a current version of CVS 15462@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 15463@c see this as if there is no tag. Seems to me this is 15464@c too obscure to mention. 15465 15466The working directory format is compatible going back 15467to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 15468and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 15469a working directory checked out with @sc{cvs} 1.3, 15470@sc{cvs} will convert it, but to go back to @sc{cvs} 154711.3 you need to check out a new working directory with 15472@sc{cvs} 1.3. 15473 15474The remote protocol is interoperable going back to @sc{cvs} 1.5, but no 15475further (1.5 was the first official release with the remote protocol, 15476but some older versions might still be floating around). In many 15477cases you need to upgrade both the client and the server to take 15478advantage of new features and bug fixes, however. 15479 15480@c Perhaps should be saying something here about the 15481@c "D" lines in Entries (written by CVS 1.9; 1.8 and 15482@c older don't use them). These are supposed to be 15483@c compatible in both directions, but I'm not sure 15484@c they quite are 100%. One common gripe is if you 15485@c "rm -r" a directory and 1.9 gets confused, as it 15486@c still sees it in Entries. That one is fixed in 15487@c (say) 1.9.6. Someone else reported problems with 15488@c starting with a directory which was checked out with 15489@c an old version, and then using a new version, and 15490@c some "D" lines appeared, but not for every 15491@c directory, causing some directories to be skipped. 15492@c They weren't sure how to reproduce this, though. 15493 15494@c --------------------------------------------------------------------- 15495@node Troubleshooting 15496@appendix Troubleshooting 15497 15498If you are having trouble with @sc{cvs}, this appendix 15499may help. If there is a particular error message which 15500you are seeing, then you can look up the message 15501alphabetically. If not, you can look through the 15502section on other problems to see if your problem is 15503mentioned there. 15504 15505@menu 15506* Error messages:: Partial list of CVS errors 15507* Connection:: Trouble making a connection to a CVS server 15508* Other problems:: Problems not readily listed by error message 15509@end menu 15510 15511@ignore 15512@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 15513@c @node Bad administrative files 15514@appendixsec Bad administrative files 15515 15516@c -- Give hints on how to fix them 15517@end ignore 15518 15519@node Error messages 15520@appendixsec Partial list of error messages 15521 15522Here is a partial list of error messages that you may 15523see from @sc{cvs}. It is not a complete list---@sc{cvs} 15524is capable of printing many, many error messages, often 15525with parts of them supplied by the operating system, 15526but the intention is to list the common and/or 15527potentially confusing error messages. 15528 15529The messages are alphabetical, but introductory text 15530such as @samp{cvs update: } is not considered in 15531ordering them. 15532 15533In some cases the list includes messages printed by old 15534versions of @sc{cvs} (partly because users may not be 15535sure which version of @sc{cvs} they are using at any 15536particular moment). 15537@c If we want to start retiring messages, perhaps we 15538@c should pick a cutoff version (for example, no more 15539@c messages which are specific to versions before 1.9) 15540@c and then move the old messages to an "old messages" 15541@c node rather than deleting them completely. 15542 15543@table @code 15544@c FIXME: What is the correct way to format a multiline 15545@c error message here? Maybe @table is the wrong 15546@c choice? Texinfo gurus? 15547@item @var{file}:@var{line}: Assertion '@var{text}' failed 15548The exact format of this message may vary depending on 15549your system. It indicates a bug in @sc{cvs}, which can 15550be handled as described in @ref{BUGS}. 15551 15552@item cvs @var{command}: authorization failed: server @var{host} rejected access 15553This is a generic response when trying to connect to a 15554pserver server which chooses not to provide a 15555specific reason for denying authorization. Check that 15556the username and password specified are correct and 15557that the @code{CVSROOT} specified is allowed by @samp{--allow-root} 15558in @file{inetd.conf}. See @ref{Password authenticated}. 15559 15560@item cvs @var{command}: conflict: removed @var{file} was modified by second party 15561This message indicates that you removed a file, and 15562someone else modified it. To resolve the conflict, 15563first run @samp{cvs add @var{file}}. If desired, look 15564at the other party's modification to decide whether you 15565still want to remove it. If you don't want to remove 15566it, stop here. If you do want to remove it, proceed 15567with @samp{cvs remove @var{file}} and commit your 15568removal. 15569@c Tests conflicts2-142b* in sanity.sh test for this. 15570 15571@item cannot change permissions on temporary directory 15572@example 15573Operation not permitted 15574@end example 15575This message has been happening in a non-reproducible, 15576occasional way when we run the client/server testsuite, 15577both on Red Hat Linux 3.0.3 and 4.1. We haven't been 15578able to figure out what causes it, nor is it known 15579whether it is specific to Linux (or even to this 15580particular machine!). If the problem does occur on 15581other unices, @samp{Operation not permitted} would be 15582likely to read @samp{Not owner} or whatever the system 15583in question uses for the unix @code{EPERM} error. If 15584you have any information to add, please let us know as 15585described in @ref{BUGS}. If you experience this error 15586while using @sc{cvs}, retrying the operation which 15587produced it should work fine. 15588@c This has been seen in a variety of tests, including 15589@c multibranch-2, multibranch-5, and basic1-24-rm-rm, 15590@c so it doesn't seem particularly specific to any one 15591@c test. 15592 15593@item cvs [server aborted]: Cannot check out files into the repository itself 15594The obvious cause for this message (especially for 15595non-client/server @sc{cvs}) is that the @sc{cvs} root 15596is, for example, @file{/usr/local/cvsroot} and you try 15597to check out files when you are in a subdirectory, such 15598as @file{/usr/local/cvsroot/test}. However, there is a 15599more subtle cause, which is that the temporary 15600directory on the server is set to a subdirectory of the 15601root (which is also not allowed). If this is the 15602problem, set the temporary directory to somewhere else, 15603for example @file{/var/tmp}; see @code{TMPDIR} in 15604@ref{Environment variables}, for how to set the 15605temporary directory. 15606 15607@item cannot commit files as 'root' 15608See @samp{'root' is not allowed to commit files}. 15609 15610@c For one example see basica-1a10 in the testsuite 15611@c For another example, "cvs co ." on NT; see comment 15612@c at windows-NT/filesubr.c (expand_wild). 15613@c For another example, "cvs co foo/bar" where foo exists. 15614@item cannot open CVS/Entries for reading: No such file or directory 15615This generally indicates a @sc{cvs} internal error, and 15616can be handled as with other @sc{cvs} bugs 15617(@pxref{BUGS}). Usually there is a workaround---the 15618exact nature of which would depend on the situation but 15619which hopefully could be figured out. 15620 15621@c This is more obscure than it might sound; it only 15622@c happens if you run "cvs init" from a directory which 15623@c contains a CVS/Root file at the start. 15624@item cvs [init aborted]: cannot open CVS/Root: No such file or directory 15625This message is harmless. Provided it is not 15626accompanied by other errors, the operation has 15627completed successfully. This message should not occur 15628with current versions of @sc{cvs}, but it is documented 15629here for the benefit of @sc{cvs} 1.9 and older. 15630 15631@item cvs server: cannot open /root/.cvsignore: Permission denied 15632@itemx cvs [server aborted]: can't chdir(/root): Permission denied 15633See @ref{Connection}. 15634 15635@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 15636This message has been reported as intermittently 15637happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 15638unknown; if you know more about what causes it, let us 15639know as described in @ref{BUGS}. 15640 15641@item cvs [@var{command} aborted]: cannot start server via rcmd 15642This, unfortunately, is a rather nonspecific error 15643message which @sc{cvs} 1.9 will print if you are 15644running the @sc{cvs} client and it is having trouble 15645connecting to the server. Current versions of @sc{cvs} 15646should print a much more specific error message. If 15647you get this message when you didn't mean to run the 15648client at all, you probably forgot to specify 15649@code{:local:}, as described in @ref{Repository}. 15650 15651@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 15652@sc{cvs} 1.9 and older will print this message 15653when trying to check in a binary file if 15654@sc{rcs} is not correctly installed. Re-read the 15655instructions that came with your @sc{rcs} distribution 15656and the @sc{install} file in the @sc{cvs} 15657distribution. Alternately, upgrade to a current 15658version of @sc{cvs}, which checks in files itself 15659rather than via @sc{rcs}. 15660 15661@item cvs checkout: could not check out @var{file} 15662With @sc{cvs} 1.9, this can mean that the @code{co} program 15663(part of @sc{rcs}) returned a failure. It should be 15664preceded by another error message, however it has been 15665observed without another error message and the cause is 15666not well-understood. With the current version of @sc{cvs}, 15667which does not run @code{co}, if this message occurs 15668without another error message, it is definitely a @sc{cvs} 15669bug (@pxref{BUGS}). 15670@c My current suspicion is that the RCS in the rcs (not 15671@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 15672@c CD is bad (remains to be confirmed). 15673@c There is also a report of something which looks 15674@c very similar on SGI, Irix 5.2, so I dunno. 15675 15676@item cvs [login aborted]: could not find out home directory 15677This means that you need to set the environment 15678variables that @sc{cvs} uses to locate your home directory. 15679See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 15680@ref{Environment variables}. 15681 15682@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 15683@sc{cvs} 1.9 and older will print this message if there was 15684a problem finding the @code{rcsmerge} program. Make 15685sure that it is in your @code{PATH}, or upgrade to a 15686current version of @sc{cvs}, which does not require 15687an external @code{rcsmerge} program. 15688 15689@item cvs [update aborted]: could not patch @var{file}: No such file or directory 15690This means that there was a problem finding the 15691@code{patch} program. Make sure that it is in your 15692@code{PATH}. Note that despite appearances the message 15693is @emph{not} referring to whether it can find @var{file}. 15694If both the client and the server are running a current 15695version of @sc{cvs}, then there is no need for an 15696external patch program and you should not see this 15697message. But if either client or server is running 15698@sc{cvs} 1.9, then you need @code{patch}. 15699 15700@item cvs update: could not patch @var{file}; will refetch 15701This means that for whatever reason the client was 15702unable to apply a patch that the server sent. The 15703message is nothing to be concerned about, because 15704inability to apply the patch only slows things down and 15705has no effect on what @sc{cvs} does. 15706@c xref to update output. Or File status? 15707@c Or some place else that 15708@c explains this whole "patch"/P/Needs Patch thing? 15709 15710@item dying gasps from @var{server} unexpected 15711There is a known bug in the server for @sc{cvs} 1.9.18 15712and older which can cause this. For me, this was 15713reproducible if I used the @samp{-t} global option. It 15714was fixed by Andy Piper's 14 Nov 1997 change to 15715src/filesubr.c, if anyone is curious. 15716If you see the message, 15717you probably can just retry the operation which failed, 15718or if you have discovered information concerning its 15719cause, please let us know as described in @ref{BUGS}. 15720 15721@item end of file from server (consult above messages if any) 15722The most common cause for this message is if you are 15723using an external @code{rsh} program and it exited with 15724an error. In this case the @code{rsh} program should 15725have printed a message, which will appear before the 15726above message. For more information on setting up a 15727@sc{cvs} client and server, see @ref{Remote repositories}. 15728 15729@item cvs [update aborted]: EOF in key in RCS file @var{file},v 15730@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 15731This means that there is a syntax error in the given 15732@sc{rcs} file. Note that this might be true even if @sc{rcs} can 15733read the file OK; @sc{cvs} does more error checking of 15734errors in the RCS file. That is why you may see this 15735message when upgrading from @sc{cvs} 1.9 to @sc{cvs} 157361.10. The likely cause for the original corruption is 15737hardware, the operating system, or the like. Of 15738course, if you find a case in which @sc{cvs} seems to 15739corrupting the file, by all means report it, 15740(@pxref{BUGS}). 15741There are quite a few variations of this error message, 15742depending on exactly where in the @sc{rcs} file @sc{cvs} 15743finds the syntax error. 15744 15745@cindex mkmodules 15746@item cvs commit: Executing 'mkmodules' 15747This means that your repository is set up for a version 15748of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 157491.8 or later, the above message will be preceded by 15750 15751@example 15752cvs commit: Rebuilding administrative file database 15753@end example 15754 15755If you see both messages, the database is being rebuilt 15756twice, which is unnecessary but harmless. If you wish 15757to avoid the duplication, and you have no versions of 15758@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 15759every place it appears in your @code{modules} 15760file. For more information on the @code{modules} file, 15761see @ref{modules}. 15762 15763@c This message comes from "co", and I believe is 15764@c possible only with older versions of CVS which call 15765@c co. The problem with being able to create the bogus 15766@c RCS file still exists, though (and I think maybe 15767@c there is a different symptom(s) now). 15768@c FIXME: Would be nice to have a more exact wording 15769@c for this message. 15770@item missing author 15771Typically this can happen if you created an RCS file 15772with your username set to empty. @sc{cvs} will, bogusly, 15773create an illegal RCS file with no value for the author 15774field. The solution is to make sure your username is 15775set to a non-empty value and re-create the RCS file. 15776@c "make sure your username is set" is complicated in 15777@c and of itself, as there are the environment 15778@c variables the system login name, &c, and it depends 15779@c on the version of CVS. 15780 15781@item cvs [checkout aborted]: no such tag @var{tag} 15782This message means that @sc{cvs} isn't familiar with 15783the tag @var{tag}. Usually the root cause is that you have 15784mistyped a tag name. Ocassionally this can also occur because the 15785users creating tags do not have permissions to write to the 15786@file{CVSROOT/val-tags} file (@pxref{File permissions}, for more). 15787 15788Prior to @sc{cvs} version 1.12.10, there were a few relatively 15789obscure cases where a given tag could be created in an archive 15790file in the repository but @sc{cvs} would require the user to 15791@c Search sanity.sh for "no such tag" to see some of 15792@c the relatively obscure cases. 15793try a few other @sc{cvs} commands involving that tag 15794until one was found whch caused @sc{cvs} to update 15795@cindex CVSROOT/val-tags file, forcing tags into 15796@cindex val-tags file, forcing tags into 15797the @file{val-tags} file, at which point the originally failing command 15798would begin to work. This same method can be used to repair a @file{val-tags} 15799file that becomes out of date due to the permissions problem mentioned above. 15800This updating is only required once per tag - once a tag is listed in 15801@file{val-tags}, it stays there. 15802 15803Note that using @samp{tag -f} to not require tag matches did not and 15804does not override this check (@pxref{Common options}). 15805 15806@item *PANIC* administration files missing 15807This typically means that there is a directory named 15808@sc{cvs} but it does not contain the administrative files 15809which @sc{cvs} puts in a CVS directory. If the problem is 15810that you created a CVS directory via some mechanism 15811other than @sc{cvs}, then the answer is simple, use a name 15812other than @sc{cvs}. If not, it indicates a @sc{cvs} bug 15813(@pxref{BUGS}). 15814 15815@item rcs error: Unknown option: -x,v/ 15816This message will be followed by a usage message for 15817@sc{rcs}. It means that you have an old version of 15818@sc{rcs} (probably supplied with your operating 15819system), as well as an old version of @sc{cvs}. 15820@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 15821later; current versions of @sc{cvs} do not run @sc{rcs} programs. 15822@c For more information on installing @sc{cvs}, see 15823@c (FIXME: where? it depends on whether you are 15824@c getting binaries or sources or what). 15825@c The message can also say "ci error" or something 15826@c instead of "rcs error", I suspect. 15827 15828@item cvs [server aborted]: received broken pipe signal 15829This message can be caused by a loginfo program that fails to 15830read all of the log information from its standard input. 15831If you find it happening in any other circumstances, 15832please let us know as described in @ref{BUGS}. 15833 15834@item 'root' is not allowed to commit files 15835When committing a permanent change, @sc{cvs} makes a log entry of 15836who committed the change. If you are committing the change logged 15837in as "root" (not under "su" or other root-priv giving program), 15838@sc{cvs} cannot determine who is actually making the change. 15839As such, by default, @sc{cvs} disallows changes to be committed by users 15840logged in as "root". (You can disable this option by passing the 15841@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 15842On some systems this means editing the appropriate @file{config.h} file 15843before building @sc{cvs}.) 15844 15845@item cvs [server aborted]: Secondary out of sync with primary! 15846 15847This usually means that the version of @sc{cvs} running on a secondary 15848server is incompatible with the version running on the primary server 15849(@pxref{Write proxies}). 15850This will not occur if the client supports redirection. 15851 15852It is not the version number that is significant here, but the list of 15853supported requests that the servers provide to the client. 15854For example, even if both servers were the same version, 15855if the secondary was compiled with GSSAPI support and the primary was not, 15856the list of supported requests provided by the two servers 15857would be different and the secondary would not work as a transparent 15858proxy to the primary. 15859Conversely, even if the two servers were radically different versions 15860but both provided the same list of valid requests to the client, 15861the transparent proxy would succeed. 15862 15863@item Terminated with fatal signal 11 15864This message usually indicates that @sc{cvs} (the server, if you're 15865using client/server mode) has run out of (virtual) memory. 15866Although @sc{cvs} tries to catch the error and issue a more meaningful 15867message, there are many circumstances where that is not possible. 15868If you appear to have lots of memory available to the system, 15869the problem is most likely that you're running into a system-wide 15870limit on the amount of memory a single process can use or a 15871similar process-specific limit. 15872The mechanisms for displaying and setting such limits vary from 15873system to system, so you'll have to consult an expert for your 15874particular system if you don't know how to do that. 15875 15876@item Too many arguments! 15877This message is typically printed by the @file{log.pl} 15878script which is in the @file{contrib} directory in the 15879@sc{cvs} source distribution. In some versions of 15880@sc{cvs}, @file{log.pl} has been part of the default 15881@sc{cvs} installation. The @file{log.pl} script gets 15882called from the @file{loginfo} administrative file. 15883Check that the arguments passed in @file{loginfo} match 15884what your version of @file{log.pl} expects. In 15885particular, the @file{log.pl} from @sc{cvs} 1.3 and 15886older expects the log file as an argument whereas the 15887@file{log.pl} from @sc{cvs} 1.5 and newer expects the 15888log file to be specified with a @samp{-f} option. Of 15889course, if you don't need @file{log.pl} you can just 15890comment it out of @file{loginfo}. 15891 15892@item cvs [update aborted]: unexpected EOF reading @var{file},v 15893See @samp{EOF in key in RCS file}. 15894 15895@item cvs [login aborted]: unrecognized auth response from @var{server} 15896This message typically means that the server is not set 15897up properly. For example, if @file{inetd.conf} points 15898to a nonexistent cvs executable. To debug it further, 15899find the log file which inetd writes 15900(@file{/var/log/messages} or whatever inetd uses on 15901your system). For details, see @ref{Connection}, and 15902@ref{Password authentication server}. 15903 15904@item cvs commit: Up-to-date check failed for `@var{file}' 15905This means that someone else has committed a change to 15906that file since the last time that you did a @code{cvs 15907update}. So before proceeding with your @code{cvs 15908commit} you need to @code{cvs update}. @sc{cvs} will merge 15909the changes that you made and the changes that the 15910other person made. If it does not detect any conflicts 15911it will report @samp{M @var{file}} and you are ready 15912to @code{cvs commit}. If it detects conflicts it will 15913print a message saying so, will report @samp{C @var{file}}, 15914and you need to manually resolve the 15915conflict. For more details on this process see 15916@ref{Conflicts example}. 15917 15918@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 15919@example 15920Only one of [exEX3] allowed 15921@end example 15922This indicates a problem with the installation of 15923@code{diff3} and @code{rcsmerge}. Specifically 15924@code{rcsmerge} was compiled to look for GNU diff3, but 15925it is finding unix diff3 instead. The exact text of 15926the message will vary depending on the system. The 15927simplest solution is to upgrade to a current version of 15928@sc{cvs}, which does not rely on external 15929@code{rcsmerge} or @code{diff3} programs. 15930 15931@item warning: unrecognized response `@var{text}' from cvs server 15932If @var{text} contains a valid response (such as 15933@samp{ok}) followed by an extra carriage return 15934character (on many systems this will cause the second 15935part of the message to overwrite the first part), then 15936it probably means that you are using the @samp{:ext:} 15937access method with a version of rsh, such as most 15938non-unix rsh versions, which does not by default 15939provide a transparent data stream. In such cases you 15940probably want to try @samp{:server:} instead of 15941@samp{:ext:}. If @var{text} is something else, this 15942may signify a problem with your @sc{cvs} server. 15943Double-check your installation against the instructions 15944for setting up the @sc{cvs} server. 15945@c FIXCVS: should be printing CR as \r or \015 or some 15946@c such, probably. 15947 15948@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 15949This is a normal message, not an error. See 15950@ref{Concurrency}, for more details. 15951 15952@item cvs commit: warning: editor session failed 15953@cindex Exit status, of editor 15954This means that the editor which @sc{cvs} is using exits with a nonzero 15955exit status. Some versions of vi will do this even when there was not 15956a problem editing the file. If so, point the 15957@code{CVSEDITOR} environment variable to a small script 15958such as: 15959 15960@example 15961#!/bin/sh 15962vi $* 15963exit 0 15964@end example 15965 15966@item cvs update: warning: @var{file} was lost 15967This means that the working copy of @var{file} has been deleted 15968but it has not been removed from @sc{cvs}. 15969This is nothing to be concerned about, 15970the update will just recreate the local file from the repository. 15971(This is a convenient way to discard local changes to a file: 15972just delete it and then run @code{cvs update}.) 15973 15974@item cvs update: warning: @var{file} is not (any longer) pertinent 15975This means that the working copy of @var{file} has been deleted, 15976it has not been removed from @sc{cvs} in the current working directory, 15977but it has been removed from @sc{cvs} in some other working directory. 15978This is nothing to be concerned about, 15979the update would have removed the local file anyway. 15980 15981@end table 15982 15983@node Connection 15984@appendixsec Trouble making a connection to a CVS server 15985 15986This section concerns what to do if you are having 15987trouble making a connection to a @sc{cvs} server. If 15988you are running the @sc{cvs} command line client 15989running on Windows, first upgrade the client to 15990@sc{cvs} 1.9.12 or later. The error reporting in 15991earlier versions provided much less information about 15992what the problem was. If the client is non-Windows, 15993@sc{cvs} 1.9 should be fine. 15994 15995If the error messages are not sufficient to track down 15996the problem, the next steps depend largely on which 15997access method you are using. 15998 15999@table @code 16000@cindex :ext:, troubleshooting 16001@item :ext: 16002Try running the rsh program from the command line. For 16003example: "rsh servername cvs -v" should print @sc{cvs} 16004version information. If this doesn't work, you need to 16005fix it before you can worry about @sc{cvs} problems. 16006 16007@cindex :server:, troubleshooting 16008@item :server: 16009You don't need a command line rsh program to use this 16010access method, but if you have an rsh program around, 16011it may be useful as a debugging tool. Follow the 16012directions given for :ext:. 16013 16014@cindex :pserver:, troubleshooting 16015@item :pserver: 16016Errors along the lines of "connection refused" typically indicate 16017that inetd isn't even listening for connections on port 2401 16018whereas errors like "connection reset by peer", 16019"received broken pipe signal", "recv() from server: EOF", 16020or "end of file from server" 16021typically indicate that inetd is listening for 16022connections but is unable to start @sc{cvs} (this is frequently 16023caused by having an incorrect path in @file{inetd.conf} 16024or by firewall software rejecting the connection). 16025"unrecognized auth response" errors are caused by a bad command 16026line in @file{inetd.conf}, typically an invalid option or forgetting 16027to put the @samp{pserver} command at the end of the line. 16028Another less common problem is invisible control characters that 16029your editor "helpfully" added without you noticing. 16030 16031One good debugging tool is to "telnet servername 160322401". After connecting, send any text (for example 16033"foo" followed by return). If @sc{cvs} is working 16034correctly, it will respond with 16035 16036@example 16037cvs [pserver aborted]: bad auth protocol start: foo 16038@end example 16039 16040If instead you get: 16041 16042@example 16043Usage: cvs [cvs-options] command [command-options-and-arguments] 16044... 16045@end example 16046 16047@noindent 16048then you're missing the @samp{pserver} command at the end of the 16049line in @file{inetd.conf}; check to make sure that the entire command 16050is on one line and that it's complete. 16051 16052Likewise, if you get something like: 16053 16054@example 16055Unknown command: `pserved' 16056 16057CVS commands are: 16058 add Add a new file/directory to the repository 16059... 16060@end example 16061 16062@noindent 16063then you've misspelled @samp{pserver} in some way. If it isn't 16064obvious, check for invisible control characters (particularly 16065carriage returns) in @file{inetd.conf}. 16066 16067If it fails to work at all, then make sure inetd is working 16068right. Change the invocation in @file{inetd.conf} to run the 16069echo program instead of cvs. For example: 16070 16071@example 160722401 stream tcp nowait root /bin/echo echo hello 16073@end example 16074 16075After making that change and instructing inetd to 16076re-read its configuration file, "telnet servername 160772401" should show you the text hello and then the 16078server should close the connection. If this doesn't 16079work, you need to fix it before you can worry about 16080@sc{cvs} problems. 16081 16082On AIX systems, the system will often have its own 16083program trying to use port 2401. This is AIX's problem 16084in the sense that port 2401 is registered for use with 16085@sc{cvs}. I hear that there is an AIX patch available 16086to address this problem. 16087 16088Another good debugging tool is the @samp{-d} 16089(debugging) option to inetd. Consult your system 16090documentation for more information. 16091 16092If you seem to be connecting but get errors like: 16093 16094@example 16095cvs server: cannot open /root/.cvsignore: Permission denied 16096cvs [server aborted]: can't chdir(/root): Permission denied 16097@end example 16098 16099@noindent 16100then you probably haven't specified @samp{-f} in @file{inetd.conf}. 16101(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 16102your system setting the @code{$HOME} environment variable 16103for programs being run by inetd. In this case, you can either 16104have inetd run a shell script that unsets @code{$HOME} and then runs 16105@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 16106environment.) 16107 16108If you can connect successfully for a while but then can't, 16109you've probably hit inetd's rate limit. 16110(If inetd receives too many requests for the same service 16111in a short period of time, it assumes that something is wrong 16112and temporarily disables the service.) 16113Check your inetd documentation to find out how to adjust the 16114rate limit (some versions of inetd have a single rate limit, 16115others allow you to set the limit for each service separately.) 16116@end table 16117 16118@node Other problems 16119@appendixsec Other common problems 16120 16121Here is a list of problems which do not fit into the 16122above categories. They are in no particular order. 16123 16124@itemize @bullet 16125@item 16126On Windows, if there is a 30 second or so delay when 16127you run a @sc{cvs} command, it may mean that you have 16128your home directory set to @file{C:/}, for example (see 16129@code{HOMEDRIVE} and @code{HOMEPATH} in 16130@ref{Environment variables}). @sc{cvs} expects the home 16131directory to not end in a slash, for example @file{C:} 16132or @file{C:\cvs}. 16133@c FIXCVS: CVS should at least detect this and print an 16134@c error, presumably. 16135 16136@item 16137If you are running @sc{cvs} 1.9.18 or older, and 16138@code{cvs update} finds a conflict and tries to 16139merge, as described in @ref{Conflicts example}, but 16140doesn't tell you there were conflicts, then you may 16141have an old version of @sc{rcs}. The easiest solution 16142probably is to upgrade to a current version of 16143@sc{cvs}, which does not rely on external @sc{rcs} 16144programs. 16145@end itemize 16146 16147@c --------------------------------------------------------------------- 16148@node Credits 16149@appendix Credits 16150 16151@cindex Contributors (manual) 16152@cindex Credits (manual) 16153Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 16154wrote the manual pages which were distributed with 16155@sc{cvs} 1.3. Much of their text was copied into this 16156manual. He also read an early draft 16157of this manual and contributed many ideas and 16158corrections. 16159 16160The mailing-list @code{info-cvs} is sometimes 16161informative. I have included information from postings 16162made by the following persons: 16163David G. Grubbs <@t{dgg@@think.com}>. 16164 16165Some text has been extracted from the man pages for 16166@sc{rcs}. 16167 16168The @sc{cvs} @sc{faq} by David G. Grubbs has provided 16169useful material. The @sc{faq} is no longer maintained, 16170however, and this manual is about the closest thing there 16171is to a successor (with respect to documenting how to 16172use @sc{cvs}, at least). 16173 16174In addition, the following persons have helped by 16175telling me about mistakes I've made: 16176 16177@display 16178Roxanne Brunskill <@t{rbrunski@@datap.ca}>, 16179Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 16180Karl Pingle <@t{pingle@@acuson.com}>, 16181Thomas A Peterson <@t{tap@@src.honeywell.com}>, 16182Inge Wallin <@t{ingwa@@signum.se}>, 16183Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 16184and Michael Brown <@t{brown@@wi.extrel.com}>. 16185@end display 16186 16187The list of contributors here is not comprehensive; for a more 16188complete list of who has contributed to this manual see 16189the file @file{doc/ChangeLog} in the @sc{cvs} source 16190distribution. 16191 16192@c --------------------------------------------------------------------- 16193@node BUGS 16194@appendix Dealing with bugs in CVS or this manual 16195 16196@cindex Bugs in this manual or CVS 16197Neither @sc{cvs} nor this manual is perfect, and they 16198probably never will be. If you are having trouble 16199using @sc{cvs}, or think you have found a bug, there 16200are a number of things you can do about it. Note that 16201if the manual is unclear, that can be considered a bug 16202in the manual, so these problems are often worth doing 16203something about as well as problems with @sc{cvs} itself. 16204 16205@cindex Reporting bugs 16206@cindex Bugs, reporting 16207@cindex Errors, reporting 16208@itemize @bullet 16209@item 16210If you want someone to help you and fix bugs that you 16211report, there are companies which will do that for a 16212fee. One such company is: 16213 16214@cindex Ximbiot 16215@cindex Support, getting CVS support 16216@example 16217Ximbiot 16218319 S. River St. 16219Harrisburg, PA 17104-1657 16220USA 16221Email: info@@ximbiot.com 16222Phone: (717) 579-6168 16223Fax: (717) 234-3125 16224@url{http://ximbiot.com/} 16225 16226@end example 16227 16228@item 16229If you got @sc{cvs} through a distributor, such as an 16230operating system vendor or a vendor of freeware 16231@sc{cd-rom}s, you may wish to see whether the 16232distributor provides support. Often, they will provide 16233no support or minimal support, but this may vary from 16234distributor to distributor. 16235 16236@item 16237If you have the skills and time to do so, you may wish 16238to fix the bug yourself. If you wish to submit your 16239fix for inclusion in future releases of @sc{cvs}, see 16240the file @sc{hacking} in the @sc{cvs} source 16241distribution. It contains much more information on the 16242process of submitting fixes. 16243 16244@item 16245There may be resources on the net which can help. A 16246good place to start is: 16247 16248@example 16249@url{http://cvs.nongnu.org/} 16250@end example 16251 16252If you are so inspired, increasing the information 16253available on the net is likely to be appreciated. For 16254example, before the standard @sc{cvs} distribution 16255worked on Windows 95, there was a web page with some 16256explanation and patches for running @sc{cvs} on Windows 1625795, and various people helped out by mentioning this 16258page on mailing lists or newsgroups when the subject 16259came up. 16260 16261@item 16262It is also possible to report bugs to @email{bug-cvs@@nongnu.org}. 16263Note that someone may or may not want to do anything 16264with your bug report---if you need a solution consider 16265one of the options mentioned above. People probably do 16266want to hear about bugs which are particularly severe 16267in consequences and/or easy to fix, however. You can 16268also increase your odds by being as clear as possible 16269about the exact nature of the bug and any other 16270relevant information. The way to report bugs is to 16271send email to @email{bug-cvs@@nongnu.org}. Note 16272that submissions to @email{bug-cvs@@nongnu.org} may be distributed 16273under the terms of the @sc{gnu} Public License, so if 16274you don't like this, don't submit them. There is 16275usually no justification for sending mail directly to 16276one of the @sc{cvs} maintainers rather than to 16277@email{bug-cvs@@nongnu.org}; those maintainers who want to hear 16278about such bug reports read @email{bug-cvs@@nongnu.org}. Also note 16279that sending a bug report to other mailing lists or 16280newsgroups is @emph{not} a substitute for sending it to 16281@email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on 16282whatever forum you prefer, but there are not 16283necessarily any maintainers reading bug reports sent 16284anywhere except @email{bug-cvs@@nongnu.org}. 16285@end itemize 16286 16287@cindex Known bugs in this manual or CVS 16288People often ask if there is a list of known bugs or 16289whether a particular bug is a known one. The file 16290@sc{bugs} in the @sc{cvs} source distribution is one 16291list of known bugs, but it doesn't necessarily try to 16292be comprehensive. Perhaps there will never be a 16293comprehensive, detailed list of known bugs. 16294 16295@c --------------------------------------------------------------------- 16296@node Index 16297@unnumbered Index 16298@cindex Index 16299 16300@printindex cp 16301 16302@bye 16303 16304Local Variables: 16305fill-column: 55 16306End: 16307