cvs.texinfo revision 1.3
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 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 Derek R. Price, 14@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005 15 Ximbiot @url{http://ximbiot.com}, 16@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 17@item @tab and Copyright @copyright{} others. 18@end multitable 19 20@ignore 21Permission is granted to process this file through Tex and print the 22results, provided the printed document carries copying permission 23notice identical to this one except for the removal of this paragraph 24(this paragraph not being relevant to the printed manual). 25 26@end ignore 27Permission is granted to make and distribute verbatim copies of 28this manual provided the copyright notice and this permission notice 29are preserved on all copies. 30 31Permission is granted to copy and distribute modified versions of this 32manual under the conditions for verbatim copying, provided also that the 33entire resulting derived work is distributed under the terms of a 34permission notice identical to this one. 35 36Permission is granted to copy and distribute translations of this manual 37into another language, under the above conditions for modified versions, 38except that this permission notice may be stated in a translation 39approved by the Free Software Foundation. 40@end macro 41 42@comment This file is part of the CVS distribution. 43 44@comment CVS is free software; you can redistribute it and/or modify 45@comment it under the terms of the GNU General Public License as published by 46@comment the Free Software Foundation; either version 2, or (at your option) 47@comment any later version. 48 49@comment CVS is distributed in the hope that it will be useful, 50@comment but WITHOUT ANY WARRANTY; without even the implied warranty of 51@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 52@comment GNU General Public License for more details. 53 54@c See ../README for A4 vs. US letter size. 55@c When we provided A4 postscript, and people tried to 56@c print it on US letter, the usual complaint was that the 57@c page numbers would get cut off. 58@c If one prints US letter on A4, reportedly there is 59@c some extra space at the top and/or bottom, and the side 60@c margins are a bit narrow, but no text is lost. 61@c 62@c See 63@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html 64@c for more on paper sizes. Insuring that margins are 65@c big enough to print on either A4 or US letter does 66@c indeed seem to be the usual approach (RFC2346). 67 68@c This document seems to get overfull hboxes with some 69@c frequency (probably because the tendency is to 70@c sanity-check it with "make info" and run TeX less 71@c often). The big ugly boxes just seem to add insult 72@c to injury, and I'm not aware of them helping to fix 73@c the overfull hboxes at all. 74@finalout 75 76@include version.texi 77@settitle CVS---Concurrent Versions System v@value{VERSION} 78@setchapternewpage odd 79 80@c -- TODO list: 81@c -- Fix all lines that match "^@c -- " 82@c -- Also places marked with FIXME should be manual 83@c problems (as opposed to FIXCVS for CVS problems). 84 85@c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by 86@c @asis when generating info and dvi, and by <i></i> in the generated html, 87@c such that keywords are not expanded in the generated html. 88@ifnothtml 89@macro splitrcskeyword {arg} 90@asis{}\arg\ 91@end macro 92@end ifnothtml 93 94@ifhtml 95@macro splitrcskeyword {arg} 96@i{}\arg\ 97@end macro 98@end ifhtml 99 100@dircategory GNU Packages 101@direntry 102* CVS: (cvs). Concurrent Versions System 103@end direntry 104@dircategory Individual utilities 105@direntry 106* cvs: (cvs)CVS commands. Concurrent Versions System 107@end direntry 108 109@comment The titlepage section does not appear in the Info file. 110@titlepage 111@sp 4 112@comment The title is printed in a large font. 113@center @titlefont{Version Management} 114@sp 115@center @titlefont{with} 116@sp 117@center @titlefont{CVS} 118@sp 2 119@center for @sc{cvs} @value{VERSION} 120@comment -release- 121@sp 3 122@center Per Cederqvist et al 123 124@comment The following two commands start the copyright page 125@comment for the printed manual. This will not appear in the Info file. 126@page 127@vskip 0pt plus 1filll 128@copyleftnotice 129@end titlepage 130 131@summarycontents 132 133@contents 134 135@comment ================================================================ 136@comment The real text starts here 137@comment ================================================================ 138 139@ifnottex 140@c --------------------------------------------------------------------- 141@node Top 142@top 143 144This info manual describes how to use and administer 145@sc{cvs} version @value{VERSION}. 146@end ifnottex 147 148@ifinfo 149@copyleftnotice 150@end ifinfo 151 152@c This menu is pretty long. Not sure how easily that 153@c can be fixed (no brilliant ideas right away)... 154@menu 155* Overview:: An introduction to CVS 156* Repository:: Where all your sources are stored 157* Starting a new project:: Starting a project with CVS 158* Revisions:: Numeric and symbolic names for revisions 159* Branching and merging:: Diverging/rejoining branches of development 160* Recursive behavior:: CVS descends directories 161* Adding and removing:: Adding/removing/renaming files/directories 162* History browsing:: Viewing the history of files in various ways 163 164CVS and the Real World. 165----------------------- 166* Binary files:: CVS can handle binary files 167* Multiple developers:: How CVS helps a group of developers 168* Revision management:: Policy questions for revision management 169* Keyword substitution:: CVS can include the revision inside the file 170* Tracking sources:: Tracking third-party sources 171* Builds:: Issues related to CVS and builds 172* Special Files:: Devices, links and other non-regular files 173 174References. 175----------- 176* CVS commands:: CVS commands share some things 177* Invoking CVS:: Quick reference to CVS commands 178* Administrative files:: Reference manual for the Administrative files 179* Environment variables:: All environment variables which affect CVS 180* Compatibility:: Upgrading CVS versions 181* Troubleshooting:: Some tips when nothing works 182* Credits:: Some of the contributors to this manual 183* BUGS:: Dealing with bugs in CVS or this manual 184* Index:: Index 185@end menu 186 187@c --------------------------------------------------------------------- 188@node Overview 189@chapter Overview 190@cindex Overview 191 192This chapter is for people who have never used 193@sc{cvs}, and perhaps have never used version control 194software before. 195 196If you are already familiar with @sc{cvs} and are just 197trying to learn a particular feature or remember a 198certain command, you can probably skip everything here. 199 200@menu 201* What is CVS?:: What you can do with @sc{cvs} 202* What is CVS not?:: Problems @sc{cvs} doesn't try to solve 203* A sample session:: A tour of basic @sc{cvs} usage 204@end menu 205 206@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 207@node What is CVS? 208@section What is CVS? 209@cindex What is CVS? 210@cindex Introduction to CVS 211@cindex CVS, introduction to 212 213@sc{cvs} is a version control system. Using it, you can 214record the history of your source files. 215 216@c -- /// 217@c -- ///Those who cannot remember the past are condemned to repeat it. 218@c -- /// -- George Santayana 219@c -- ////// 220 221@c -- Insert history quote here! 222For example, bugs sometimes creep in when 223software is modified, and you might not detect the bug 224until a long time after you make the modification. 225With @sc{cvs}, you can easily retrieve old versions to see 226exactly which change caused the bug. This can 227sometimes be a big help. 228 229You could of course save every version of every file 230you have ever created. This would 231however waste an enormous amount of disk space. @sc{cvs} 232stores all the versions of a file in a single file in a 233clever way that only stores the differences between 234versions. 235 236@sc{cvs} also helps you if you are part of a group of people working 237on the same project. It is all too easy to overwrite 238each others' changes unless you are extremely careful. 239Some editors, like @sc{gnu} Emacs, try to make sure that 240two people never modify the same file at the 241same time. Unfortunately, if someone is using another 242editor, that safeguard will not work. @sc{cvs} solves this problem 243by insulating the different developers from each other. Every 244developer works in his own directory, and @sc{cvs} merges 245the work when each developer is done. 246 247@cindex History of CVS 248@cindex CVS, history of 249@cindex Credits (CVS program) 250@cindex Contributors (CVS program) 251@sc{cvs} started out as a bunch of shell scripts written by 252Dick Grune, posted to the newsgroup 253@code{comp.sources.unix} in the volume 6 254release of July, 1986. While no actual code from 255these shell scripts is present in the current version 256of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms 257come from them. 258 259In April, 1989, Brian Berliner designed and coded @sc{cvs}. 260Jeff Polk later helped Brian with the design of the @sc{cvs} 261module and vendor branch support. 262 263@cindex Source, getting CVS source 264You can get @sc{cvs} in a variety of ways, including 265free download from the Internet. For more information 266on downloading @sc{cvs} and other @sc{cvs} topics, see: 267 268@example 269@url{http://cvs.nongnu.org/} 270@end example 271 272@cindex Mailing list 273@cindex List, mailing list 274@cindex Newsgroups 275There is a mailing list, known as @email{info-cvs@@nongnu.org}, 276devoted to @sc{cvs}. To subscribe or 277unsubscribe 278write to 279@email{info-cvs-request@@nongnu.org}. 280If you prefer a Usenet group, there is a one-way mirror (posts to the email 281list are usually sent to the news group, but not visa versa) of 282@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}. The right 283Usenet group for posts is @url{news:comp.software.config-mgmt} which is for 284@sc{cvs} discussions (along with other configuration 285management systems). In the future, it might be 286possible to create a 287@code{comp.software.config-mgmt.cvs}, but probably only 288if there is sufficient @sc{cvs} traffic on 289@url{news:comp.software.config-mgmt}. 290@c Other random data is that the tale was very 291@c skeptical of comp.software.config-mgmt.cvs when the 292@c subject came up around 1995 or so (for one 293@c thing, because creating it would be a "reorg" which 294@c would need to take a more comprehensive look at the 295@c whole comp.software.config-mgmt.* hierarchy). 296 297You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list, 298described in more detail in @ref{BUGS}. To subscribe 299send mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way 300Usenet mirror (posts to the Usenet group are usually sent to the email list and 301visa versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}. 302 303@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 304@node What is CVS not? 305@section What is CVS not? 306@cindex What is CVS not? 307 308@sc{cvs} can do a lot of things for you, but it does 309not try to be everything for everyone. 310 311@table @asis 312@item @sc{cvs} is not a build system. 313 314Though the structure of your repository and modules 315file interact with your build system 316(e.g. @file{Makefile}s), they are essentially 317independent. 318 319@sc{cvs} does not dictate how you build anything. It 320merely stores files for retrieval in a tree structure 321you devise. 322 323@sc{cvs} does not dictate how to use disk space in the 324checked out working directories. If you write your 325@file{Makefile}s or scripts in every directory so they 326have to know the relative positions of everything else, 327you wind up requiring the entire repository to be 328checked out. 329 330If you modularize your work, and construct a build 331system that will share files (via links, mounts, 332@code{VPATH} in @file{Makefile}s, etc.), you can 333arrange your disk usage however you like. 334 335But you have to remember that @emph{any} such system is 336a lot of work to construct and maintain. @sc{cvs} does 337not address the issues involved. 338 339Of course, you should place the tools created to 340support such a build system (scripts, @file{Makefile}s, 341etc) under @sc{cvs}. 342 343Figuring out what files need to be rebuilt when 344something changes is, again, something to be handled 345outside the scope of @sc{cvs}. One traditional 346approach is to use @code{make} for building, and use 347some automated tool for generating the dependencies which 348@code{make} uses. 349 350See @ref{Builds}, for more information on doing builds 351in conjunction with @sc{cvs}. 352 353@item @sc{cvs} is not a substitute for management. 354 355Your managers and project leaders are expected to talk 356to you frequently enough to make certain you are aware 357of schedules, merge points, branch names and release 358dates. If they don't, @sc{cvs} can't help. 359 360@sc{cvs} is an instrument for making sources dance to 361your tune. But you are the piper and the composer. No 362instrument plays itself or writes its own music. 363 364@item @sc{cvs} is not a substitute for developer communication. 365 366When faced with conflicts within a single file, most 367developers manage to resolve them without too much 368effort. But a more general definition of ``conflict'' 369includes problems too difficult to solve without 370communication between developers. 371 372@sc{cvs} cannot determine when simultaneous changes 373within a single file, or across a whole collection of 374files, will logically conflict with one another. Its 375concept of a @dfn{conflict} is purely textual, arising 376when two changes to the same base file are near enough 377to spook the merge (i.e. @code{diff3}) command. 378 379@sc{cvs} does not claim to help at all in figuring out 380non-textual or distributed conflicts in program logic. 381 382For example: Say you change the arguments to function 383@code{X} defined in file @file{A}. At the same time, 384someone edits file @file{B}, adding new calls to 385function @code{X} using the old arguments. You are 386outside the realm of @sc{cvs}'s competence. 387 388Acquire the habit of reading specs and talking to your 389peers. 390 391 392@item @sc{cvs} does not have change control 393 394Change control refers to a number of things. First of 395all it can mean @dfn{bug-tracking}, that is being able 396to keep a database of reported bugs and the status of 397each one (is it fixed? in what release? has the bug 398submitter agreed that it is fixed?). For interfacing 399@sc{cvs} to an external bug-tracking system, see the 400@file{rcsinfo} and @file{verifymsg} files 401(@pxref{Administrative files}). 402 403Another aspect of change control is keeping track of 404the fact that changes to several files were in fact 405changed together as one logical change. If you check 406in several files in a single @code{cvs commit} 407operation, @sc{cvs} then forgets that those files were 408checked in together, and the fact that they have the 409same log message is the only thing tying them 410together. Keeping a @sc{gnu} style @file{ChangeLog} 411can help somewhat. 412@c FIXME: should have an xref to a section which talks 413@c more about keeping ChangeLog's with CVS, but that 414@c section hasn't been written yet. 415 416Another aspect of change control, in some systems, is 417the ability to keep track of the status of each 418change. Some changes have been written by a developer, 419others have been reviewed by a second developer, and so 420on. Generally, the way to do this with @sc{cvs} is to 421generate a diff (using @code{cvs diff} or @code{diff}) 422and email it to someone who can then apply it using the 423@code{patch} utility. This is very flexible, but 424depends on mechanisms outside @sc{cvs} to make sure 425nothing falls through the cracks. 426 427@item @sc{cvs} is not an automated testing program 428 429It should be possible to enforce mandatory use of a 430test suite using the @code{commitinfo} file. I haven't 431heard a lot about projects trying to do that or whether 432there are subtle gotchas, however. 433 434@item @sc{cvs} does not have a built-in process model 435 436Some systems provide ways to ensure that changes or 437releases go through various steps, with various 438approvals as needed. Generally, one can accomplish 439this with @sc{cvs} but it might be a little more work. 440In some cases you'll want to use the @file{commitinfo}, 441@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} 442files, to require that certain steps be performed 443before cvs will allow a checkin. Also consider whether 444features such as branches and tags can be used to 445perform tasks such as doing work in a development tree 446and then merging certain changes over to a stable tree 447only once they have been proven. 448@end table 449 450@c --------------------------------------------------------------------- 451@node A sample session 452@section A sample session 453@cindex Example of a work-session 454@cindex Getting started 455@cindex Work-session, example of 456@cindex tc, Trivial Compiler (example) 457@cindex Trivial Compiler (example) 458 459@c I think an example is a pretty good way to start. But 460@c somewhere in here, maybe after the sample session, 461@c we need something which is kind of 462@c a "roadmap" which is more directed at sketching out 463@c the functionality of CVS and pointing people to 464@c various other parts of the manual. As it stands now 465@c people who read in order get dumped right into all 466@c manner of hair regarding remote repositories, 467@c creating a repository, etc. 468@c 469@c The following was in the old Basic concepts node. I don't 470@c know how good a job it does at introducing modules, 471@c or whether they need to be introduced so soon, but 472@c something of this sort might go into some 473@c introductory material somewhere. 474@ignore 475@cindex Modules (intro) 476The repository contains directories and files, in an 477arbitrary tree. The @dfn{modules} feature can be used 478to group together a set of directories or files into a 479single entity (@pxref{modules}). A typical usage is to 480define one module per project. 481@end ignore 482 483As a way of introducing @sc{cvs}, we'll go through a 484typical work-session using @sc{cvs}. The first thing 485to understand is that @sc{cvs} stores all files in a 486centralized @dfn{repository} (@pxref{Repository}); this 487section assumes that a repository is set up. 488@c I'm not sure that the sentence concerning the 489@c repository quite tells the user what they need to 490@c know at this point. Might need to expand on "centralized" 491@c slightly (maybe not here, maybe further down in the example?) 492 493Suppose you are working on a simple compiler. The source 494consists of a handful of C files and a @file{Makefile}. 495The compiler is called @samp{tc} (Trivial Compiler), 496and the repository is set up so that there is a module 497called @samp{tc}. 498 499@menu 500* Getting the source:: Creating a workspace 501* Committing your changes:: Making your work available to others 502* Cleaning up:: Cleaning up 503* Viewing differences:: Viewing differences 504@end menu 505 506@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 507@node Getting the source 508@subsection Getting the source 509@cindex Getting the source 510@cindex Checking out source 511@cindex Fetching source 512@cindex Source, getting from CVS 513@cindex Checkout, example 514 515The first thing you must do is to get your own working copy of the 516source for @samp{tc}. For this, you use the @code{checkout} command: 517 518@example 519$ cvs checkout tc 520@end example 521 522@noindent 523This will create a new directory called @file{tc} and populate it with 524the source files. 525 526@example 527$ cd tc 528$ ls 529CVS Makefile backend.c driver.c frontend.c parser.c 530@end example 531 532The @file{CVS} directory is used internally by 533@sc{cvs}. Normally, you should not modify or remove 534any of the files in it. 535 536You start your favorite editor, hack away at @file{backend.c}, and a couple 537of hours later you have added an optimization pass to the compiler. 538A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that 539you want to edit. @xref{Multiple developers}, for an explanation. 540 541@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 542@node Committing your changes 543@subsection Committing your changes 544@cindex Committing changes to files 545@cindex Log message entry 546 547When you have checked that the compiler is still compilable you decide 548to make a new version of @file{backend.c}. This will 549store your new @file{backend.c} in the repository and 550make it available to anyone else who is using that same 551repository. 552 553@example 554$ cvs commit backend.c 555@end example 556 557@noindent 558@sc{cvs} starts an editor, to allow you to enter a log 559message. You type in ``Added an optimization pass.'', 560save the temporary file, and exit the editor. 561 562@cindex CVSEDITOR, environment variable 563@cindex EDITOR, environment variable 564The environment variable @code{$CVSEDITOR} determines 565which editor is started. If @code{$CVSEDITOR} is not 566set, then if the environment variable @code{$EDITOR} is 567set, it will be used. If both @code{$CVSEDITOR} and 568@code{$EDITOR} are not set then there is a default 569which will vary with your operating system, for example 570@code{vi} for unix or @code{notepad} for Windows 571NT/95. 572 573@cindex VISUAL, environment variable 574In addition, @sc{cvs} checks the @code{$VISUAL} environment 575variable. Opinions vary on whether this behavior is desirable and 576whether future releases of @sc{cvs} should check @code{$VISUAL} or 577ignore it. You will be OK either way if you make sure that 578@code{$VISUAL} is either unset or set to the same thing as 579@code{$EDITOR}. 580 581@c This probably should go into some new node 582@c containing detailed info on the editor, rather than 583@c the intro. In fact, perhaps some of the stuff with 584@c CVSEDITOR and -m and so on should too. 585When @sc{cvs} starts the editor, it includes a list of 586files which are modified. For the @sc{cvs} client, 587this list is based on comparing the modification time 588of the file against the modification time that the file 589had when it was last gotten or updated. Therefore, if 590a file's modification time has changed but its contents 591have not, it will show up as modified. The simplest 592way to handle this is simply not to worry about it---if 593you proceed with the commit @sc{cvs} will detect that 594the contents are not modified and treat it as an 595unmodified file. The next @code{update} will clue 596@sc{cvs} in to the fact that the file is unmodified, 597and it will reset its stored timestamp so that the file 598will not show up in future editor sessions. 599@c FIXCVS: Might be nice if "commit" and other commands 600@c would reset that timestamp too, but currently commit 601@c doesn't. 602@c FIXME: Need to talk more about the process of 603@c prompting for the log message. Like show an example 604@c of what it pops up in the editor, for example. Also 605@c a discussion of how to get the "a)bort, c)ontinue, 606@c e)dit" prompt and what to do with it. Might also 607@c work in the suggestion that if you want a diff, you 608@c should make it before running commit (someone 609@c suggested that the diff pop up in the editor. I'm 610@c not sure that is better than telling people to run 611@c "cvs diff" first if that is what they want, but if 612@c we want to tell people that, the manual possibly 613@c should say it). 614 615If you want to avoid 616starting an editor you can specify the log message on 617the command line using the @samp{-m} flag instead, like 618this: 619 620@example 621$ cvs commit -m "Added an optimization pass" backend.c 622@end example 623 624@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 625@node Cleaning up 626@subsection Cleaning up 627@cindex Cleaning up 628@cindex Working copy, removing 629@cindex Removing your working copy 630@cindex Releasing your working copy 631 632Before you turn to other tasks you decide to remove your working copy of 633tc. One acceptable way to do that is of course 634 635@example 636$ cd .. 637$ rm -r tc 638@end example 639 640@noindent 641but a better way is to use the @code{release} command (@pxref{release}): 642 643@example 644$ cd .. 645$ cvs release -d tc 646M driver.c 647? tc 648You have [1] altered files in this repository. 649Are you sure you want to release (and delete) directory `tc': n 650** `release' aborted by user choice. 651@end example 652 653The @code{release} command checks that all your modifications have been 654committed. If history logging is enabled it also makes a note in the 655history file. @xref{history file}. 656 657When you use the @samp{-d} flag with @code{release}, it 658also removes your working copy. 659 660In the example above, the @code{release} command wrote a couple of lines 661of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. 662That is nothing to worry about: @file{tc} is the executable compiler, 663and it should not be stored in the repository. @xref{cvsignore}, 664for information about how to make that warning go away. 665@xref{release output}, for a complete explanation of 666all possible output from @code{release}. 667 668@samp{M driver.c} is more serious. It means that the 669file @file{driver.c} has been modified since it was 670checked out. 671 672The @code{release} command always finishes by telling 673you how many modified files you have in your working 674copy of the sources, and then asks you for confirmation 675before deleting any files or making any note in the 676history file. 677 678You decide to play it safe and answer @kbd{n @key{RET}} 679when @code{release} asks for confirmation. 680 681@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 682@node Viewing differences 683@subsection Viewing differences 684@cindex Viewing differences 685@cindex Diff 686 687You do not remember modifying @file{driver.c}, so you want to see what 688has happened to that file. 689 690@example 691$ cd tc 692$ cvs diff driver.c 693@end example 694 695This command runs @code{diff} to compare the version of @file{driver.c} 696that you checked out with your working copy. When you see the output 697you remember that you added a command line option that enabled the 698optimization pass. You check it in, and release the module. 699@c FIXME: we haven't yet defined the term "check in". 700 701@example 702$ cvs commit -m "Added an optimization pass" driver.c 703Checking in driver.c; 704/usr/local/cvsroot/tc/driver.c,v <-- driver.c 705new revision: 1.2; previous revision: 1.1 706done 707$ cd .. 708$ cvs release -d tc 709? tc 710You have [0] altered files in this repository. 711Are you sure you want to release (and delete) directory `tc': y 712@end example 713 714@c --------------------------------------------------------------------- 715@node Repository 716@chapter The Repository 717@cindex Repository (intro) 718@cindex Repository, example 719@cindex Layout of repository 720@cindex Typical repository 721@cindex /usr/local/cvsroot, as example repository 722@cindex cvsroot 723 724The @sc{cvs} @dfn{repository} stores a complete copy of 725all the files and directories which are under version 726control. 727 728Normally, you never access any of the files in the 729repository directly. Instead, you use @sc{cvs} 730commands to get your own copy of the files into a 731@dfn{working directory}, and then 732work on that copy. When you've finished a set of 733changes, you check (or @dfn{commit}) them back into the 734repository. The repository then contains the changes 735which you have made, as well as recording exactly what 736you changed, when you changed it, and other such 737information. Note that the repository is not a 738subdirectory of the working directory, or vice versa; 739they should be in separate locations. 740@c Need some example, e.g. repository 741@c /usr/local/cvsroot; working directory 742@c /home/joe/sources. But this node is too long 743@c as it is; need a little reorganization... 744 745@cindex :local:, setting up 746@sc{cvs} can access a repository by a variety of 747means. It might be on the local computer, or it might 748be on a computer across the room or across the world. 749To distinguish various ways to access a repository, the 750repository name can start with an @dfn{access method}. 751For example, the access method @code{:local:} means to 752access a repository directory, so the repository 753@code{:local:/usr/local/cvsroot} means that the 754repository is in @file{/usr/local/cvsroot} on the 755computer running @sc{cvs}. For information on other 756access methods, see @ref{Remote repositories}. 757 758@c Can se say this more concisely? Like by passing 759@c more of the buck to the Remote repositories node? 760If the access method is omitted, then if the repository 761starts with @samp{/}, then @code{:local:} is 762assumed. If it does not start with @samp{/} then either 763@code{:ext:} or @code{:server:} is assumed. For 764example, if you have a local repository in 765@file{/usr/local/cvsroot}, you can use 766@code{/usr/local/cvsroot} instead of 767@code{:local:/usr/local/cvsroot}. But if (under 768Windows NT, for example) your local repository is 769@file{c:\src\cvsroot}, then you must specify the access 770method, as in @code{:local:c:/src/cvsroot}. 771 772@c This might appear to go in Repository storage, but 773@c actually it is describing something which is quite 774@c user-visible, when you do a "cvs co CVSROOT". This 775@c isn't necessary the perfect place for that, though. 776The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains 777administrative files for @sc{cvs}. The other directories contain the actual 778user-defined modules. 779 780@menu 781* Specifying a repository:: Telling CVS where your repository is 782* Repository storage:: The structure of the repository 783* Working directory storage:: The structure of working directories 784* Intro administrative files:: Defining modules 785* Multiple repositories:: Multiple repositories 786* Creating a repository:: Creating a repository 787* Backing up:: Backing up a repository 788* Moving a repository:: Moving a repository 789* Remote repositories:: Accessing repositories on remote machines 790* Read-only access:: Granting read-only access to the repository 791* Server temporary directory:: The server creates temporary directories 792@end menu 793 794@node Specifying a repository 795@section Telling CVS where your repository is 796 797There are several ways to tell @sc{cvs} 798where to find the repository. You can name the 799repository on the command line explicitly, with the 800@code{-d} (for "directory") option: 801 802@example 803cvs -d /usr/local/cvsroot checkout yoyodyne/tc 804@end example 805 806@cindex .profile, setting CVSROOT in 807@cindex .cshrc, setting CVSROOT in 808@cindex .tcshrc, setting CVSROOT in 809@cindex .bashrc, setting CVSROOT in 810@cindex CVSROOT, environment variable 811 Or you can set the @code{$CVSROOT} environment 812variable to an absolute path to the root of the 813repository, @file{/usr/local/cvsroot} in this example. 814To set @code{$CVSROOT}, @code{csh} and @code{tcsh} 815users should have this line in their @file{.cshrc} or 816@file{.tcshrc} files: 817 818@example 819setenv CVSROOT /usr/local/cvsroot 820@end example 821 822@noindent 823@code{sh} and @code{bash} users should instead have these lines in their 824@file{.profile} or @file{.bashrc}: 825 826@example 827CVSROOT=/usr/local/cvsroot 828export CVSROOT 829@end example 830 831@cindex Root file, in CVS directory 832@cindex CVS/Root file 833 A repository specified with @code{-d} will 834override the @code{$CVSROOT} environment variable. 835Once you've checked a working copy out from the 836repository, it will remember where its repository is 837(the information is recorded in the 838@file{CVS/Root} file in the working copy). 839 840The @code{-d} option and the @file{CVS/Root} file both 841override the @code{$CVSROOT} environment variable. If 842@code{-d} option differs from @file{CVS/Root}, the 843former is used. Of course, for proper operation they 844should be two ways of referring to the same repository. 845 846@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 847@node Repository storage 848@section How data is stored in the repository 849@cindex Repository, how data is stored 850 851For most purposes it isn't important @emph{how} 852@sc{cvs} stores information in the repository. In 853fact, the format has changed in the past, and is likely 854to change in the future. Since in almost all cases one 855accesses the repository via @sc{cvs} commands, such 856changes need not be disruptive. 857 858However, in some cases it may be necessary to 859understand how @sc{cvs} stores data in the repository, 860for example you might need to track down @sc{cvs} locks 861(@pxref{Concurrency}) or you might need to deal with 862the file permissions appropriate for the repository. 863 864@menu 865* Repository files:: What files are stored in the repository 866* File permissions:: File permissions 867* Windows permissions:: Issues specific to Windows 868* Attic:: Some files are stored in the Attic 869* CVS in repository:: Additional information in CVS directory 870* Locks:: CVS locks control concurrent accesses 871* CVSROOT storage:: A few things about CVSROOT are different 872@end menu 873 874@node Repository files 875@subsection Where files are stored within the repository 876 877@c @cindex Filenames, legal 878@c @cindex Legal filenames 879@c Somewhere we need to say something about legitimate 880@c characters in filenames in working directory and 881@c repository. Not "/" (not even on non-unix). And 882@c here is a specific set of issues: 883@c Files starting with a - are handled inconsistently. They can not 884@c be added to a repository with an add command, because it they are 885@c interpreted as a switch. They can appear in a repository if they are 886@c part of a tree that is imported. They can not be removed from the tree 887@c once they are there. 888@c Note that "--" *is* supported (as a 889@c consequence of using GNU getopt). Should document 890@c this somewhere ("Common options"?). The other usual technique, 891@c "./-foo", isn't as effective, at least for "cvs add" 892@c which doesn't support pathnames containing "/". 893 894The overall structure of the repository is a directory 895tree corresponding to the directories in the working 896directory. For example, supposing the repository is in 897 898@example 899/usr/local/cvsroot 900@end example 901 902@noindent 903here is a possible directory tree (showing only the 904directories): 905 906@example 907@t{/usr} 908 | 909 +--@t{local} 910 | | 911 | +--@t{cvsroot} 912 | | | 913 | | +--@t{CVSROOT} 914 | (administrative files) 915 | 916 +--@t{gnu} 917 | | 918 | +--@t{diff} 919 | | (source code to @sc{gnu} diff) 920 | | 921 | +--@t{rcs} 922 | | (source code to @sc{rcs}) 923 | | 924 | +--@t{cvs} 925 | (source code to @sc{cvs}) 926 | 927 +--@t{yoyodyne} 928 | 929 +--@t{tc} 930 | | 931 | +--@t{man} 932 | | 933 | +--@t{testing} 934 | 935 +--(other Yoyodyne software) 936@end example 937 938With the directories are @dfn{history files} for each file 939under version control. The name of the history file is 940the name of the corresponding file with @samp{,v} 941appended to the end. Here is what the repository for 942the @file{yoyodyne/tc} directory might look like: 943@c FIXME: Should also mention CVS (CVSREP) 944@c FIXME? Should we introduce Attic with an xref to 945@c Attic? Not sure whether that is a good idea or not. 946@example 947 @code{$CVSROOT} 948 | 949 +--@t{yoyodyne} 950 | | 951 | +--@t{tc} 952 | | | 953 +--@t{Makefile,v} 954 +--@t{backend.c,v} 955 +--@t{driver.c,v} 956 +--@t{frontend.c,v} 957 +--@t{parser.c,v} 958 +--@t{man} 959 | | 960 | +--@t{tc.1,v} 961 | 962 +--@t{testing} 963 | 964 +--@t{testpgm.t,v} 965 +--@t{test2.t,v} 966@end example 967 968@cindex History files 969@cindex RCS history files 970@c The first sentence, about what history files 971@c contain, is kind of redundant with our intro to what the 972@c repository does in node Repository.... 973The history files contain, among other things, enough 974information to recreate any revision of the file, a log 975of all commit messages and the user-name of the person 976who committed the revision. The history files are 977known as @dfn{RCS files}, because the first program to 978store files in that format was a version control system 979known as @sc{rcs}. For a full 980description of the file format, see the @code{man} page 981@cite{rcsfile(5)}, distributed with @sc{rcs}, or the 982file @file{doc/RCSFILES} in the @sc{cvs} source 983distribution. This 984file format has become very common---many systems other 985than @sc{cvs} or @sc{rcs} can at least import history 986files in this format. 987@c FIXME: Think about including documentation for this 988@c rather than citing it? In the long run, getting 989@c this to be a standard (not sure if we can cope with 990@c a standards process as formal as IEEE/ANSI/ISO/etc, 991@c though...) is the way to go, so maybe citing is 992@c better. 993 994The @sc{rcs} files used in @sc{cvs} differ in a few 995ways from the standard format. The biggest difference 996is magic branches; for more information see @ref{Magic 997branch numbers}. Also in @sc{cvs} the valid tag names 998are a subset of what @sc{rcs} accepts; for @sc{cvs}'s 999rules see @ref{Tags}. 1000 1001@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002@node File permissions 1003@subsection File permissions 1004@c -- Move this to @node Creating a repository or similar 1005@cindex Security, file permissions in repository 1006@cindex File permissions, general 1007@cindex Permissions, general 1008@c FIXME: we need to somehow reflect "permissions in 1009@c repository" versus "permissions in working 1010@c directory" in the index entries. 1011@cindex Group, UNIX file permissions, in repository 1012@cindex Read-only files, in repository 1013All @samp{,v} files are created read-only, and you 1014should not change the permission of those files. The 1015directories inside the repository should be writable by 1016the persons that have permission to modify the files in 1017each directory. This normally means that you must 1018create a UNIX group (see group(5)) consisting of the 1019persons that are to edit the files in a project, and 1020set up the repository so that it is that group that 1021owns the directory. 1022(On some systems, you also need to set the set-group-ID-on-execution bit 1023on the repository directories (see chmod(1)) so that newly-created files 1024and directories get the group-ID of the parent directory rather than 1025that of the current process.) 1026 1027@c See also comment in commitinfo node regarding cases 1028@c which are really awkward with unix groups. 1029 1030This means that you can only control access to files on 1031a per-directory basis. 1032 1033Note that users must also have write access to check 1034out files, because @sc{cvs} needs to create lock files 1035(@pxref{Concurrency}). You can use LockDir in CVSROOT/config 1036to put the lock files somewhere other than in the repository 1037if you want to allow read-only access to some directories 1038(@pxref{config}). 1039 1040@c CVS seems to use CVSUMASK in picking permissions for 1041@c val-tags, but maybe we should say more about this. 1042@c Like val-tags gets created by someone who doesn't 1043@c have CVSUMASK set right? 1044@cindex CVSROOT/val-tags file, and read-only access to projects 1045@cindex val-tags file, and read-only access to projects 1046Also note that users must have write access to the 1047@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep 1048track of what tags are valid tag names (it is sometimes 1049updated when tags are used, as well as when they are 1050created). 1051 1052Each @sc{rcs} file will be owned by the user who last 1053checked it in. This has little significance; what 1054really matters is who owns the directories. 1055 1056@cindex CVSUMASK, environment variable 1057@cindex Umask, for repository files 1058@sc{cvs} tries to set up reasonable file permissions 1059for new directories that are added inside the tree, but 1060you must fix the permissions manually when a new 1061directory should have different permissions than its 1062parent directory. If you set the @code{CVSUMASK} 1063environment variable that will control the file 1064permissions which @sc{cvs} uses in creating directories 1065and/or files in the repository. @code{CVSUMASK} does 1066not affect the file permissions in the working 1067directory; such files have the permissions which are 1068typical for newly created files, except that sometimes 1069@sc{cvs} creates them read-only (see the sections on 1070watches, @ref{Setting a watch}; -r, @ref{Global 1071options}; or @code{CVSREAD}, @ref{Environment variables}). 1072@c FIXME: Need more discussion of which 1073@c group should own the file in the repository. 1074@c Include a somewhat detailed example of the usual 1075@c case where CVSUMASK is 007, the developers are all 1076@c in a group, and that group owns stuff in the 1077@c repository. Need to talk about group ownership of 1078@c newly-created directories/files (on some unices, 1079@c such as SunOS4, setting the setgid bit on the 1080@c directories will make files inherit the directory's 1081@c group. On other unices, your mileage may vary. I 1082@c can't remember what POSIX says about this, if 1083@c anything). 1084 1085Note that using the client/server @sc{cvs} 1086(@pxref{Remote repositories}), there is no good way to 1087set @code{CVSUMASK}; the setting on the client machine 1088has no effect. If you are connecting with @code{rsh}, you 1089can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as 1090described in the documentation for your operating 1091system. This behavior might change in future versions 1092of @sc{cvs}; do not rely on the setting of 1093@code{CVSUMASK} on the client having no effect. 1094@c FIXME: need to explain what a umask is or cite 1095@c someplace which does. 1096@c 1097@c There is also a larger (largely separate) issue 1098@c about the meaning of CVSUMASK in a non-unix context. 1099@c For example, whether there is 1100@c an equivalent which fits better into other 1101@c protection schemes like POSIX.6, VMS, &c. 1102@c 1103@c FIXME: Need one place which discusses this 1104@c read-only files thing. Why would one use -r or 1105@c CVSREAD? Why would one use watches? How do they 1106@c interact? 1107@c 1108@c FIXME: We need to state 1109@c whether using CVSUMASK removes the need for manually 1110@c fixing permissions (in fact, if we are going to mention 1111@c manually fixing permission, we better document a lot 1112@c better just what we mean by "fix"). 1113 1114Using pserver, you will generally need stricter 1115permissions on the @sc{cvsroot} directory and 1116directories above it in the tree; see @ref{Password 1117authentication security}. 1118 1119@cindex Setuid 1120@cindex Setgid 1121@cindex Security, setuid 1122@cindex Installed images (VMS) 1123Some operating systems have features which allow a 1124particular program to run with the ability to perform 1125operations which the caller of the program could not. 1126For example, the set user ID (setuid) or set group ID 1127(setgid) features of unix or the installed image 1128feature of VMS. @sc{cvs} was not written to use such 1129features and therefore attempting to install @sc{cvs} in 1130this fashion will provide protection against only 1131accidental lapses; anyone who is trying to circumvent 1132the measure will be able to do so, and depending on how 1133you have set it up may gain access to more than just 1134@sc{cvs}. You may wish to instead consider pserver. It 1135shares some of the same attributes, in terms of 1136possibly providing a false sense of security or opening 1137security holes wider than the ones you are trying to 1138fix, so read the documentation on pserver security 1139carefully if you are considering this option 1140(@ref{Password authentication security}). 1141 1142@node Windows permissions 1143@subsection File Permission issues specific to Windows 1144@cindex Windows, and permissions 1145@cindex File permissions, Windows-specific 1146@cindex Permissions, Windows-specific 1147 1148Some file permission issues are specific to Windows 1149operating systems (Windows 95, Windows NT, and 1150presumably future operating systems in this family. 1151Some of the following might apply to OS/2 but I'm not 1152sure). 1153 1154If you are using local @sc{cvs} and the repository is on a 1155networked file system which is served by the Samba SMB 1156server, some people have reported problems with 1157permissions. Enabling WRITE=YES in the samba 1158configuration is said to fix/workaround it. 1159Disclaimer: I haven't investigated enough to know the 1160implications of enabling that option, nor do I know 1161whether there is something which @sc{cvs} could be doing 1162differently in order to avoid the problem. If you find 1163something out, please let us know as described in 1164@ref{BUGS}. 1165 1166@node Attic 1167@subsection The attic 1168@cindex Attic 1169 1170You will notice that sometimes @sc{cvs} stores an 1171@sc{rcs} file in the @code{Attic}. For example, if the 1172@sc{cvsroot} is @file{/usr/local/cvsroot} and we are 1173talking about the file @file{backend.c} in the 1174directory @file{yoyodyne/tc}, then the file normally 1175would be in 1176 1177@example 1178/usr/local/cvsroot/yoyodyne/tc/backend.c,v 1179@end example 1180 1181@noindent 1182but if it goes in the attic, it would be in 1183 1184@example 1185/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v 1186@end example 1187 1188@noindent 1189@cindex Dead state 1190instead. It should not matter from a user point of 1191view whether a file is in the attic; @sc{cvs} keeps 1192track of this and looks in the attic when it needs to. 1193But in case you want to know, the rule is that the RCS 1194file is stored in the attic if and only if the head 1195revision on the trunk has state @code{dead}. A 1196@code{dead} state means that file has been removed, or 1197never added, for that revision. For example, if you 1198add a file on a branch, it will have a trunk revision 1199in @code{dead} state, and a branch revision in a 1200non-@code{dead} state. 1201@c Probably should have some more concrete examples 1202@c here, or somewhere (not sure exactly how we should 1203@c arrange the discussion of the dead state, versus 1204@c discussion of the attic). 1205 1206@node CVS in repository 1207@subsection The CVS directory in the repository 1208@cindex CVS directory, in repository 1209 1210The @file{CVS} directory in each repository directory 1211contains information such as file attributes (in a file 1212called @file{CVS/fileattr}. In the 1213future additional files may be added to this directory, 1214so implementations should silently ignore additional 1215files. 1216 1217This behavior is implemented only by @sc{cvs} 1.7 and 1218later; for details see @ref{Watches Compatibility}. 1219 1220The format of the @file{fileattr} file is a series of entries 1221of the following form (where @samp{@{} and @samp{@}} 1222means the text between the braces can be repeated zero 1223or more times): 1224 1225@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} 1226 @{; @var{attrname} = @var{attrval}@} <linefeed> 1227 1228@var{ent-type} is @samp{F} for a file, in which case the entry specifies the 1229attributes for that file. 1230 1231@var{ent-type} is @samp{D}, 1232and @var{filename} empty, to specify default attributes 1233to be used for newly added files. 1234 1235Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older 1236will delete them any time it writes file attributes. 1237@sc{cvs} 1.10 and later will preserve them. 1238 1239Note that the order of the lines is not significant; 1240a program writing the fileattr file may 1241rearrange them at its convenience. 1242 1243There is currently no way of quoting tabs or line feeds in the 1244filename, @samp{=} in @var{attrname}, 1245@samp{;} in @var{attrval}, etc. Note: some implementations also 1246don't handle a NUL character in any of the fields, but 1247implementations are encouraged to allow it. 1248 1249By convention, @var{attrname} starting with @samp{_} is for an attribute given 1250special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes 1251(or will be, once implementations start supporting user-defined attributes). 1252 1253Built-in attributes: 1254 1255@table @code 1256@item _watched 1257Present means the file is watched and should be checked out 1258read-only. 1259 1260@item _watchers 1261Users with watches for this file. Value is 1262@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} 1263where @var{watcher} is a username, and @var{type} 1264is zero or more of edit,unedit,commit separated by 1265@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). 1266 1267@item _editors 1268Users editing this file. Value is 1269@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} 1270where @var{editor} is a username, and @var{val} is 1271@var{time}+@var{hostname}+@var{pathname}, where 1272@var{time} is when the @code{cvs edit} command (or 1273equivalent) happened, 1274and @var{hostname} and @var{pathname} are for the working directory. 1275@end table 1276 1277Example: 1278 1279@c FIXME: sanity.sh should contain a similar test case 1280@c so we can compare this example from something from 1281@c Real Life(TM). See cvsclient.texi (under Notify) for more 1282@c discussion of the date format of _editors. 1283@example 1284Ffile1 _watched=;_watchers=joe>edit,mary>commit 1285Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs 1286D _watched= 1287@end example 1288 1289@noindent 1290means that the file @file{file1} should be checked out 1291read-only. Furthermore, joe is watching for edits and 1292mary is watching for commits. The file @file{file2} 1293should be checked out read-only; sue started editing it 1294on 8 Jan 1975 in the directory @file{/home/sue/cvs} on 1295the machine @code{workstn1}. Future files which are 1296added should be checked out read-only. To represent 1297this example here, we have shown a space after 1298@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact 1299there must be a single tab character there and no spaces. 1300 1301@node Locks 1302@subsection CVS locks in the repository 1303 1304@cindex #cvs.rfl, technical details 1305@cindex #cvs.pfl, technical details 1306@cindex #cvs.wfl, technical details 1307@cindex #cvs.lock, technical details 1308@cindex Locks, cvs, technical details 1309For an introduction to @sc{cvs} locks focusing on 1310user-visible behavior, see @ref{Concurrency}. The 1311following section is aimed at people who are writing 1312tools which want to access a @sc{cvs} repository without 1313interfering with other tools accessing the same 1314repository. If you find yourself confused by concepts 1315described here, like @dfn{read lock}, @dfn{write lock}, 1316and @dfn{deadlock}, you might consult the literature on 1317operating systems or databases. 1318 1319@cindex #cvs.tfl 1320Any file in the repository with a name starting 1321with @file{#cvs.rfl.} is a read lock. Any file in 1322the repository with a name starting with 1323@file{#cvs.pfl} is a promotable read lock. Any file in 1324the repository with a name starting with 1325@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} 1326(before @sc{cvs} 1.5) also created files with names starting 1327with @file{#cvs.tfl}, but they are not discussed here. 1328The directory @file{#cvs.lock} serves as a master 1329lock. That is, one must obtain this lock first before 1330creating any of the other locks. 1331 1332To obtain a read lock, first create the @file{#cvs.lock} 1333directory. This operation must be atomic (which should 1334be true for creating a directory under most operating 1335systems). If it fails because the directory already 1336existed, wait for a while and try again. After 1337obtaining the @file{#cvs.lock} lock, create a file 1338whose name is @file{#cvs.rfl.} followed by information 1339of your choice (for example, hostname and process 1340identification number). Then remove the 1341@file{#cvs.lock} directory to release the master lock. 1342Then proceed with reading the repository. When you are 1343done, remove the @file{#cvs.rfl} file to release the 1344read lock. 1345 1346Promotable read locks are a concept you may not find in other literature on 1347concurrency. They are used to allow a two (or more) pass process to only lock 1348a file for read on the first (read) pass(es), then upgrade its read locks to 1349write locks if necessary for a final pass, still assured that the files have 1350not changed since they were first read. @sc{cvs} uses promotable read locks, 1351for example, to prevent commit and tag verification passes from interfering 1352with other reading processes. It can then lock only a single directory at a 1353time for write during the write pass. 1354 1355To obtain a promotable read lock, first create the @file{#cvs.lock} directory, 1356as with a non-promotable read lock. Then check 1357that there are no files that start with 1358@file{#cvs.pfl}. If there are, remove the master @file{#cvs.lock} directory, 1359wait awhile (CVS waits 30 seconds between lock attempts), and try again. If 1360there are no other promotable locks, go ahead and create a file whose name is 1361@file{#cvs.pfl} followed by information of your choice (for example, CVS uses 1362its hostname and the process identification number of the CVS server process 1363creating the lock). If versions of @sc{cvs} older than version 1.12.4 access 1364your repository directly (not via a @sc{cvs} server of version 1.12.4 or 1365later), then you should also create a read lock since older versions of CVS 1366will ignore the promotable lock when attempting to create their own write lock. 1367Then remove the master @file{#cvs.lock} directory in order to allow other 1368processes to obtain read locks. 1369 1370To obtain a write lock, first create the 1371@file{#cvs.lock} directory, as with read locks. Then 1372check that there are no files whose names start with 1373@file{#cvs.rfl.} and no files whose names start with @file{#cvs.pfl} that are 1374not owned by the process attempting to get the write lock. If either exist, 1375remove @file{#cvs.lock}, wait for a while, and try again. If 1376there are no readers or promotable locks from other processes, then create a 1377file whose name is @file{#cvs.wfl} followed by information of your choice 1378(again, CVS uses the hostname and server process identification 1379number). Remove your @file{#cvs.pfl} file if present. Hang on to the 1380@file{#cvs.lock} lock. Proceed 1381with writing the repository. When you are done, first 1382remove the @file{#cvs.wfl} file and then the 1383@file{#cvs.lock} directory. Note that unlike the 1384@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just 1385informational; it has no effect on the locking operation 1386beyond what is provided by holding on to the 1387@file{#cvs.lock} lock itself. 1388 1389Note that each lock (write lock or read lock) only locks 1390a single directory in the repository, including 1391@file{Attic} and @file{CVS} but not including 1392subdirectories which represent other directories under 1393version control. To lock an entire tree, you need to 1394lock each directory (note that if you fail to obtain 1395any lock you need, you must release the whole tree 1396before waiting and trying again, to avoid deadlocks). 1397 1398Note also that @sc{cvs} expects write locks to control 1399access to individual @file{foo,v} files. @sc{rcs} has 1400a scheme where the @file{,foo,} file serves as a lock, 1401but @sc{cvs} does not implement it and so taking out a 1402@sc{cvs} write lock is recommended. See the comments at 1403rcs_internal_lockfile in the @sc{cvs} source code for 1404further discussion/rationale. 1405 1406@node CVSROOT storage 1407@subsection How files are stored in the CVSROOT directory 1408@cindex CVSROOT, storage of files 1409 1410The @file{$CVSROOT/CVSROOT} directory contains the 1411various administrative files. In some ways this 1412directory is just like any other directory in the 1413repository; it contains @sc{rcs} files whose names end 1414in @samp{,v}, and many of the @sc{cvs} commands operate 1415on it the same way. However, there are a few 1416differences. 1417 1418For each administrative file, in addition to the 1419@sc{rcs} file, there is also a checked out copy of the 1420file. For example, there is an @sc{rcs} file 1421@file{loginfo,v} and a file @file{loginfo} which 1422contains the latest revision contained in 1423@file{loginfo,v}. When you check in an administrative 1424file, @sc{cvs} should print 1425 1426@example 1427cvs commit: Rebuilding administrative file database 1428@end example 1429 1430@noindent 1431and update the checked out copy in 1432@file{$CVSROOT/CVSROOT}. If it does not, there is 1433something wrong (@pxref{BUGS}). To add your own files 1434to the files to be updated in this fashion, you can add 1435them to the @file{checkoutlist} administrative file 1436(@pxref{checkoutlist}). 1437 1438@cindex modules.db 1439@cindex modules.pag 1440@cindex modules.dir 1441By default, the @file{modules} file behaves as 1442described above. If the modules file is very large, 1443storing it as a flat text file may make looking up 1444modules slow (I'm not sure whether this is as much of a 1445concern now as when @sc{cvs} first evolved this 1446feature; I haven't seen benchmarks). Therefore, by 1447making appropriate edits to the @sc{cvs} source code 1448one can store the modules file in a database which 1449implements the @code{ndbm} interface, such as Berkeley 1450db or GDBM. If this option is in use, then the modules 1451database will be stored in the files @file{modules.db}, 1452@file{modules.pag}, and/or @file{modules.dir}. 1453@c I think fileattr also will use the database stuff. 1454@c Anything else? 1455 1456For information on the meaning of the various 1457administrative files, see @ref{Administrative files}. 1458 1459@node Working directory storage 1460@section How data is stored in the working directory 1461 1462@c FIXME: Somewhere we should discuss timestamps (test 1463@c case "stamps" in sanity.sh). But not here. Maybe 1464@c in some kind of "working directory" chapter which 1465@c would encompass the "Builds" one? But I'm not sure 1466@c whether that is a good organization (is it based on 1467@c what the user wants to do?). 1468 1469@cindex CVS directory, in working directory 1470While we are discussing @sc{cvs} internals which may 1471become visible from time to time, we might as well talk 1472about what @sc{cvs} puts in the @file{CVS} directories 1473in the working directories. As with the repository, 1474@sc{cvs} handles this information and one can usually 1475access it via @sc{cvs} commands. But in some cases it 1476may be useful to look at it, and other programs, such 1477as the @code{jCVS} graphical user interface or the 1478@code{VC} package for emacs, may need to look at it. 1479Such programs should follow the recommendations in this 1480section if they hope to be able to work with other 1481programs which use those files, including future 1482versions of the programs just mentioned and the 1483command-line @sc{cvs} client. 1484 1485The @file{CVS} directory contains several files. 1486Programs which are reading this directory should 1487silently ignore files which are in the directory but 1488which are not documented here, to allow for future 1489expansion. 1490 1491The files are stored according to the text file 1492convention for the system in question. This means that 1493working directories are not portable between systems 1494with differing conventions for storing text files. 1495This is intentional, on the theory that the files being 1496managed by @sc{cvs} probably will not be portable between 1497such systems either. 1498 1499@table @file 1500@item Root 1501This file contains the current @sc{cvs} root, as 1502described in @ref{Specifying a repository}. 1503 1504@cindex Repository file, in CVS directory 1505@cindex CVS/Repository file 1506@item Repository 1507This file contains the directory within the repository 1508which the current directory corresponds with. It can 1509be either an absolute pathname or a relative pathname; 1510@sc{cvs} has had the ability to read either format 1511since at least version 1.3 or so. The relative 1512pathname is relative to the root, and is the more 1513sensible approach, but the absolute pathname is quite 1514common and implementations should accept either. For 1515example, after the command 1516 1517@example 1518cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc 1519@end example 1520 1521@noindent 1522@file{Root} will contain 1523 1524@example 1525:local:/usr/local/cvsroot 1526@end example 1527 1528@noindent 1529and @file{Repository} will contain either 1530 1531@example 1532/usr/local/cvsroot/yoyodyne/tc 1533@end example 1534 1535@noindent 1536or 1537 1538@example 1539yoyodyne/tc 1540@end example 1541 1542If the particular working directory does not correspond 1543to a directory in the repository, then @file{Repository} 1544should contain @file{CVSROOT/Emptydir}. 1545@cindex Emptydir, in CVSROOT directory 1546@cindex CVSROOT/Emptydir directory 1547 1548@cindex Entries file, in CVS directory 1549@cindex CVS/Entries file 1550@item Entries 1551This file lists the files and directories in the 1552working directory. 1553The first character of each line indicates what sort of 1554line it is. If the character is unrecognized, programs 1555reading the file should silently skip that line, to 1556allow for future expansion. 1557 1558If the first character is @samp{/}, then the format is: 1559 1560@example 1561/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate} 1562@end example 1563 1564@noindent 1565where @samp{[} and @samp{]} are not part of the entry, 1566but instead indicate that the @samp{+} and conflict 1567marker are optional. @var{name} is the name of the 1568file within the directory. @var{revision} is the 1569revision that the file in the working derives from, or 1570@samp{0} for an added file, or @samp{-} followed by a 1571revision for a removed file. @var{timestamp} is the 1572timestamp of the file at the time that @sc{cvs} created 1573it; if the timestamp differs with the actual 1574modification time of the file it means the file has 1575been modified. It is stored in 1576the format used by the ISO C asctime() function (for 1577example, @samp{Sun Apr 7 01:29:26 1996}). One may 1578write a string which is not in that format, for 1579example, @samp{Result of merge}, to indicate that the 1580file should always be considered to be modified. This 1581is not a special case; to see whether a file is 1582modified a program should take the timestamp of the file 1583and simply do a string compare with @var{timestamp}. 1584If there was a conflict, @var{conflict} can be set to 1585the modification time of the file after the file has been 1586written with conflict markers (@pxref{Conflicts example}). 1587Thus if @var{conflict} is subsequently the same as the actual 1588modification time of the file it means that the user 1589has obviously not resolved the conflict. @var{options} 1590contains sticky options (for example @samp{-kb} for a 1591binary file). @var{tagdate} contains @samp{T} followed 1592by a tag name, or @samp{D} for a date, followed by a 1593sticky tag or date. Note that if @var{timestamp} 1594contains a pair of timestamps separated by a space, 1595rather than a single timestamp, you are dealing with a 1596version of @sc{cvs} earlier than @sc{cvs} 1.5 (not 1597documented here). 1598 1599The timezone on the timestamp in CVS/Entries (local or 1600universal) should be the same as the operating system 1601stores for the timestamp of the file itself. For 1602example, on Unix the file's timestamp is in universal 1603time (UT), so the timestamp in CVS/Entries should be 1604too. On @sc{vms}, the file's timestamp is in local 1605time, so @sc{cvs} on @sc{vms} should use local time. 1606This rule is so that files do not appear to be modified 1607merely because the timezone changed (for example, to or 1608from summer time). 1609@c See comments and calls to gmtime() and friends in 1610@c src/vers_ts.c (function time_stamp). 1611 1612If the first character of a line in @file{Entries} is 1613@samp{D}, then it indicates a subdirectory. @samp{D} 1614on a line all by itself indicates that the program 1615which wrote the @file{Entries} file does record 1616subdirectories (therefore, if there is such a line and 1617no other lines beginning with @samp{D}, one knows there 1618are no subdirectories). Otherwise, the line looks 1619like: 1620 1621@example 1622D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} 1623@end example 1624 1625@noindent 1626where @var{name} is the name of the subdirectory, and 1627all the @var{filler} fields should be silently ignored, 1628for future expansion. Programs which modify 1629@code{Entries} files should preserve these fields. 1630 1631The lines in the @file{Entries} file can be in any order. 1632 1633@cindex Entries.Log file, in CVS directory 1634@cindex CVS/Entries.Log file 1635@item Entries.Log 1636This file does not record any information beyond that 1637in @file{Entries}, but it does provide a way to update 1638the information without having to rewrite the entire 1639@file{Entries} file, including the ability to preserve 1640the information even if the program writing 1641@file{Entries} and @file{Entries.Log} abruptly aborts. 1642Programs which are reading the @file{Entries} file 1643should also check for @file{Entries.Log}. If the latter 1644exists, they should read @file{Entries} and then apply 1645the changes mentioned in @file{Entries.Log}. After 1646applying the changes, the recommended practice is to 1647rewrite @file{Entries} and then delete @file{Entries.Log}. 1648The format of a line in @file{Entries.Log} is a single 1649character command followed by a space followed by a 1650line in the format specified for a line in 1651@file{Entries}. The single character command is 1652@samp{A} to indicate that the entry is being added, 1653@samp{R} to indicate that the entry is being removed, 1654or any other character to indicate that the entire line 1655in @file{Entries.Log} should be silently ignored (for 1656future expansion). If the second character of the line 1657in @file{Entries.Log} is not a space, then it was 1658written by an older version of @sc{cvs} (not documented 1659here). 1660 1661Programs which are writing rather than reading can 1662safely ignore @file{Entries.Log} if they so choose. 1663 1664@cindex Entries.Backup file, in CVS directory 1665@cindex CVS/Entries.Backup file 1666@item Entries.Backup 1667This is a temporary file. Recommended usage is to 1668write a new entries file to @file{Entries.Backup}, and 1669then to rename it (atomically, where possible) to @file{Entries}. 1670 1671@cindex Entries.Static file, in CVS directory 1672@cindex CVS/Entries.Static file 1673@item Entries.Static 1674The only relevant thing about this file is whether it 1675exists or not. If it exists, then it means that only 1676part of a directory was gotten and @sc{cvs} will 1677not create additional files in that directory. To 1678clear it, use the @code{update} command with the 1679@samp{-d} option, which will get the additional files 1680and remove @file{Entries.Static}. 1681@c FIXME: This needs to be better documented, in places 1682@c other than Working Directory Storage. 1683@c FIXCVS: The fact that this setting exists needs to 1684@c be more visible to the user. For example "cvs 1685@c status foo", in the case where the file would be 1686@c gotten except for Entries.Static, might say 1687@c something to distinguish this from other cases. 1688@c One thing that periodically gets suggested is to 1689@c have "cvs update" print something when it skips 1690@c files due to Entries.Static, but IMHO that kind of 1691@c noise pretty much makes the Entries.Static feature 1692@c useless. 1693 1694@cindex Tag file, in CVS directory 1695@cindex CVS/Tag file 1696@cindex Sticky tags/dates, per-directory 1697@cindex Per-directory sticky tags/dates 1698@item Tag 1699This file contains per-directory sticky tags or dates. 1700The first character is @samp{T} for a branch tag, 1701@samp{N} for a non-branch tag, or @samp{D} for a date, 1702or another character to mean the file should be 1703silently ignored, for future expansion. This character 1704is followed by the tag or date. Note that 1705per-directory sticky tags or dates are used for things 1706like applying to files which are newly added; they 1707might not be the same as the sticky tags or dates on 1708individual files. For general information on sticky 1709tags and dates, see @ref{Sticky tags}. 1710@c FIXME: This needs to be much better documented, 1711@c preferably not in the context of "working directory 1712@c storage". 1713@c FIXME: The Sticky tags node needs to discuss, or xref to 1714@c someplace which discusses, per-directory sticky 1715@c tags and the distinction with per-file sticky tags. 1716 1717@cindex Notify file, in CVS directory 1718@cindex CVS/Notify file 1719@item Notify 1720This file stores notifications (for example, for 1721@code{edit} or @code{unedit}) which have not yet been 1722sent to the server. Its format is not yet documented 1723here. 1724 1725@cindex Notify.tmp file, in CVS directory 1726@cindex CVS/Notify.tmp file 1727@item Notify.tmp 1728This file is to @file{Notify} as @file{Entries.Backup} 1729is to @file{Entries}. That is, to write @file{Notify}, 1730first write the new contents to @file{Notify.tmp} and 1731then (atomically where possible), rename it to 1732@file{Notify}. 1733 1734@cindex Base directory, in CVS directory 1735@cindex CVS/Base directory 1736@item Base 1737If watches are in use, then an @code{edit} command 1738stores the original copy of the file in the @file{Base} 1739directory. This allows the @code{unedit} command to 1740operate even if it is unable to communicate with the 1741server. 1742 1743@cindex Baserev file, in CVS directory 1744@cindex CVS/Baserev file 1745@item Baserev 1746The file lists the revision for each of the files in 1747the @file{Base} directory. The format is: 1748 1749@example 1750B@var{name}/@var{rev}/@var{expansion} 1751@end example 1752 1753@noindent 1754where @var{expansion} should be ignored, to allow for 1755future expansion. 1756 1757@cindex Baserev.tmp file, in CVS directory 1758@cindex CVS/Baserev.tmp file 1759@item Baserev.tmp 1760This file is to @file{Baserev} as @file{Entries.Backup} 1761is to @file{Entries}. That is, to write @file{Baserev}, 1762first write the new contents to @file{Baserev.tmp} and 1763then (atomically where possible), rename it to 1764@file{Baserev}. 1765 1766@cindex Template file, in CVS directory 1767@cindex CVS/Template file 1768@item Template 1769This file contains the template specified by the 1770@file{rcsinfo} file (@pxref{rcsinfo}). It is only used 1771by the client; the non-client/server @sc{cvs} consults 1772@file{rcsinfo} directly. 1773@end table 1774 1775@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1776@node Intro administrative files 1777@section The administrative files 1778@cindex Administrative files (intro) 1779@cindex Modules file 1780@cindex CVSROOT, module name 1781@cindex Defining modules (intro) 1782 1783@c FIXME: this node should be reorganized into "general 1784@c information about admin files" and put the "editing 1785@c admin files" stuff up front rather than jumping into 1786@c the details of modules right away. Then the 1787@c Administrative files node can go away, the information 1788@c on each admin file distributed to a place appropriate 1789@c to its function, and this node can contain a table 1790@c listing each file and a @ref to its detailed description. 1791 1792The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative 1793files}. @xref{Administrative files}, for a complete description. 1794You can use @sc{cvs} without any of these files, but 1795some commands work better when at least the 1796@file{modules} file is properly set up. 1797 1798The most important of these files is the @file{modules} 1799file. It defines all modules in the repository. This 1800is a sample @file{modules} file. 1801 1802@c FIXME: The CVSROOT line is a goofy example now that 1803@c mkmodules doesn't exist. 1804@example 1805CVSROOT CVSROOT 1806modules CVSROOT modules 1807cvs gnu/cvs 1808rcs gnu/rcs 1809diff gnu/diff 1810tc yoyodyne/tc 1811@end example 1812 1813The @file{modules} file is line oriented. In its 1814simplest form each line contains the name of the 1815module, whitespace, and the directory where the module 1816resides. The directory is a path relative to 1817@code{$CVSROOT}. The last four lines in the example 1818above are examples of such lines. 1819 1820@c FIXME: might want to introduce the concept of options in modules file 1821@c (the old example which was here, -i mkmodules, is obsolete). 1822 1823The line that defines the module called @samp{modules} 1824uses features that are not explained here. 1825@xref{modules}, for a full explanation of all the 1826available features. 1827 1828@c FIXME: subsection without node is bogus 1829@subsection Editing administrative files 1830@cindex Editing administrative files 1831@cindex Administrative files, editing them 1832 1833You edit the administrative files in the same way that you would edit 1834any other module. Use @samp{cvs checkout CVSROOT} to get a working 1835copy, edit it, and commit your changes in the normal way. 1836 1837It is possible to commit an erroneous administrative 1838file. You can often fix the error and check in a new 1839revision, but sometimes a particularly bad error in the 1840administrative file makes it impossible to commit new 1841revisions. 1842@c @xref{Bad administrative files} for a hint 1843@c about how to solve such situations. 1844@c -- administrative file checking-- 1845 1846@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1847@node Multiple repositories 1848@section Multiple repositories 1849@cindex Multiple repositories 1850@cindex Repositories, multiple 1851@cindex Many repositories 1852@cindex Parallel repositories 1853@cindex Disjoint repositories 1854@cindex CVSROOT, multiple repositories 1855 1856In some situations it is a good idea to have more than 1857one repository, for instance if you have two 1858development groups that work on separate projects 1859without sharing any code. All you have to do to have 1860several repositories is to specify the appropriate 1861repository, using the @code{CVSROOT} environment 1862variable, the @samp{-d} option to @sc{cvs}, or (once 1863you have checked out a working directory) by simply 1864allowing @sc{cvs} to use the repository that was used 1865to check out the working directory 1866(@pxref{Specifying a repository}). 1867 1868The big advantage of having multiple repositories is 1869that they can reside on different servers. With @sc{cvs} 1870version 1.10, a single command cannot recurse into 1871directories from different repositories. With development 1872versions of @sc{cvs}, you can check out code from multiple 1873servers into your working directory. @sc{cvs} will 1874recurse and handle all the details of making 1875connections to as many server machines as necessary to 1876perform the requested command. Here is an example of 1877how to set up a working directory: 1878 1879@example 1880cvs -d server1:/cvs co dir1 1881cd dir1 1882cvs -d server2:/root co sdir 1883cvs update 1884@end example 1885 1886The @code{cvs co} commands set up the working 1887directory, and then the @code{cvs update} command will 1888contact server2, to update the dir1/sdir subdirectory, 1889and server1, to update everything else. 1890 1891@c FIXME: Does the FAQ have more about this? I have a 1892@c dim recollection, but I'm too lazy to check right now. 1893 1894@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1895@node Creating a repository 1896@section Creating a repository 1897 1898@cindex Repository, setting up 1899@cindex Creating a repository 1900@cindex Setting up a repository 1901 1902This section describes how to set up a @sc{cvs} repository for any 1903sort of access method. After completing the setup described in this 1904section, you should be able to access your @sc{cvs} repository immediately 1905via the local access method and several remote access methods. For 1906more information on setting up remote access to the repository you create 1907in this section, please read the section on @xref{Remote repositories}. 1908 1909To set up a @sc{cvs} repository, first choose the 1910machine and disk on which you want to store the 1911revision history of the source files. CPU and memory 1912requirements are modest, so most machines should be 1913adequate. For details see @ref{Server requirements}. 1914@c Possible that we should be providing a quick rule of 1915@c thumb, like the 32M memory for the server. That 1916@c might increase the number of people who are happy 1917@c with the answer, without following the xref. 1918 1919To estimate disk space 1920requirements, if you are importing RCS files from 1921another system, the size of those files is the 1922approximate initial size of your repository, or if you 1923are starting without any version history, a rule of 1924thumb is to allow for the server approximately three 1925times the size of the code to be under @sc{cvs} for the 1926repository (you will eventually outgrow this, but not 1927for a while). On the machines on which the developers 1928will be working, you'll want disk space for 1929approximately one working directory for each developer 1930(either the entire tree or a portion of it, depending 1931on what each developer uses). 1932 1933The repository should be accessible 1934(directly or via a networked file system) from all 1935machines which want to use @sc{cvs} in server or local 1936mode; the client machines need not have any access to 1937it other than via the @sc{cvs} protocol. It is not 1938possible to use @sc{cvs} to read from a repository 1939which one only has read access to; @sc{cvs} needs to be 1940able to create lock files (@pxref{Concurrency}). 1941 1942@cindex init (subcommand) 1943To create a repository, run the @code{cvs init} 1944command. It will set up an empty repository in the 1945@sc{cvs} root specified in the usual way 1946(@pxref{Repository}). For example, 1947 1948@example 1949cvs -d /usr/local/cvsroot init 1950@end example 1951 1952@code{cvs init} is careful to never overwrite any 1953existing files in the repository, so no harm is done if 1954you run @code{cvs init} on an already set-up 1955repository. 1956 1957@code{cvs init} will enable history logging; if you 1958don't want that, remove the history file after running 1959@code{cvs init}. @xref{history file}. 1960 1961@node Backing up 1962@section Backing up a repository 1963@cindex Repository, backing up 1964@cindex Backing up, repository 1965 1966There is nothing particularly magical about the files 1967in the repository; for the most part it is possible to 1968back them up just like any other files. However, there 1969are a few issues to consider. 1970 1971@cindex Locks, cvs, and backups 1972@cindex #cvs.rfl, and backups 1973The first is that to be paranoid, one should either not 1974use @sc{cvs} during the backup, or have the backup 1975program lock @sc{cvs} while doing the backup. To not 1976use @sc{cvs}, you might forbid logins to machines which 1977can access the repository, turn off your @sc{cvs} 1978server, or similar mechanisms. The details would 1979depend on your operating system and how you have 1980@sc{cvs} set up. To lock @sc{cvs}, you would create 1981@file{#cvs.rfl} locks in each repository directory. 1982See @ref{Concurrency}, for more on @sc{cvs} locks. 1983Having said all this, if you just back up without any 1984of these precautions, the results are unlikely to be 1985particularly dire. Restoring from backup, the 1986repository might be in an inconsistent state, but this 1987would not be particularly hard to fix manually. 1988 1989When you restore a repository from backup, assuming 1990that changes in the repository were made after the time 1991of the backup, working directories which were not 1992affected by the failure may refer to revisions which no 1993longer exist in the repository. Trying to run @sc{cvs} 1994in such directories will typically produce an error 1995message. One way to get those changes back into the 1996repository is as follows: 1997 1998@itemize @bullet 1999@item 2000Get a new working directory. 2001 2002@item 2003Copy the files from the working directory from before 2004the failure over to the new working directory (do not 2005copy the contents of the @file{CVS} directories, of 2006course). 2007 2008@item 2009Working in the new working directory, use commands such 2010as @code{cvs update} and @code{cvs diff} to figure out 2011what has changed, and then when you are ready, commit 2012the changes into the repository. 2013@end itemize 2014 2015@node Moving a repository 2016@section Moving a repository 2017@cindex Repository, moving 2018@cindex Moving a repository 2019@cindex Copying a repository 2020 2021Just as backing up the files in the repository is 2022pretty much like backing up any other files, if you 2023need to move a repository from one place to another it 2024is also pretty much like just moving any other 2025collection of files. 2026 2027The main thing to consider is that working directories 2028point to the repository. The simplest way to deal with 2029a moved repository is to just get a fresh working 2030directory after the move. Of course, you'll want to 2031make sure that the old working directory had been 2032checked in before the move, or you figured out some 2033other way to make sure that you don't lose any 2034changes. If you really do want to reuse the existing 2035working directory, it should be possible with manual 2036surgery on the @file{CVS/Repository} files. You can 2037see @ref{Working directory storage}, for information on 2038the @file{CVS/Repository} and @file{CVS/Root} files, but 2039unless you are sure you want to bother, it probably 2040isn't worth it. 2041@c FIXME: Surgery on CVS/Repository should be avoided 2042@c by making RELATIVE_REPOS the default. 2043@c FIXME-maybe: might want some documented way to 2044@c change the CVS/Root files in some particular tree. 2045@c But then again, I don't know, maybe just having 2046@c people do this in perl/shell/&c isn't so bad... 2047 2048@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2049@node Remote repositories 2050@section Remote repositories 2051@cindex Repositories, remote 2052@cindex Remote repositories 2053@cindex Client/Server Operation 2054@cindex Server, CVS 2055@cindex Remote repositories, port specification 2056@cindex Repositories, remote, port specification 2057@cindex Client/Server Operation, port specification 2058@cindex pserver (client/server connection method), port specification 2059@cindex kserver (client/server connection method), port specification 2060@cindex gserver (client/server connection method), port specification 2061@cindex port, specifying for remote repositories 2062 2063 Your working copy of the sources can be on a 2064different machine than the repository. Using @sc{cvs} 2065in this manner is known as @dfn{client/server} 2066operation. You run @sc{cvs} on a machine which can 2067mount your working directory, known as the 2068@dfn{client}, and tell it to communicate to a machine 2069which can mount the repository, known as the 2070@dfn{server}. Generally, using a remote 2071repository is just like using a local one, except that 2072the format of the repository name is: 2073 2074@example 2075[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 2076@end example 2077 2078Specifying a password in the repository name is not recommended during 2079checkout, since this will cause @sc{cvs} to store a cleartext copy of the 2080password in each created directory. @code{cvs login} first instead 2081(@pxref{Password authentication client}). 2082 2083The details of exactly what needs to be set up depend 2084on how you are connecting to the server. 2085 2086@c Should we try to explain which platforms are which? 2087@c Platforms like unix and VMS, which only allow 2088@c privileged programs to bind to sockets <1024 lose on 2089@c :server: 2090@c Platforms like Mac and VMS, whose rsh program is 2091@c unusable or nonexistent, lose on :ext: 2092@c Platforms like OS/2 and NT probably could plausibly 2093@c default either way (modulo -b troubles). 2094 2095@menu 2096* Server requirements:: Memory and other resources for servers 2097* The connection method:: Connection methods and method options 2098* Connecting via rsh:: Using the @code{rsh} program to connect 2099* Password authenticated:: Direct connections using passwords 2100* GSSAPI authenticated:: Direct connections using GSSAPI 2101* Kerberos authenticated:: Direct connections with Kerberos 2102* Connecting via fork:: Using a forked @code{cvs server} to connect 2103* Write proxies:: Distributing load across several CVS servers 2104@end menu 2105 2106@node Server requirements 2107@subsection Server requirements 2108 2109The quick answer to what sort of machine is suitable as 2110a server is that requirements are modest---a server 2111with 32M of memory or even less can handle a fairly 2112large source tree with a fair amount of activity. 2113@c Say something about CPU speed too? I'm even less sure 2114@c what to say on that subject... 2115 2116The real answer, of course, is more complicated. 2117Estimating the known areas of large memory consumption 2118should be sufficient to estimate memory requirements. 2119There are two such areas documented here; other memory 2120consumption should be small by comparison (if you find 2121that is not the case, let us know, as described in 2122@ref{BUGS}, so we can update this documentation). 2123 2124The first area of big memory consumption is large 2125checkouts, when using the @sc{cvs} server. The server 2126consists of two processes for each client that it is 2127serving. Memory consumption on the child process 2128should remain fairly small. Memory consumption on the 2129parent process, particularly if the network connection 2130to the client is slow, can be expected to grow to 2131slightly more than the size of the sources in a single 2132directory, or two megabytes, whichever is larger. 2133@c "two megabytes" of course is SERVER_HI_WATER. But 2134@c we don't mention that here because we are 2135@c documenting the default configuration of CVS. If it 2136@c is a "standard" thing to change that value, it 2137@c should be some kind of run-time configuration. 2138@c 2139@c See cvsclient.texi for more on the design decision 2140@c to not have locks in place while waiting for the 2141@c client, which is what results in memory consumption 2142@c as high as this. 2143 2144Multiplying the size of each @sc{cvs} server by the 2145number of servers which you expect to have active at 2146one time should give an idea of memory requirements for 2147the server. For the most part, the memory consumed by 2148the parent process probably can be swap space rather 2149than physical memory. 2150@c Has anyone verified that notion about swap space? 2151@c I say it based pretty much on guessing that the 2152@c ->text of the struct buffer_data only gets accessed 2153@c in a first in, first out fashion, but I haven't 2154@c looked very closely. 2155 2156@c What about disk usage in /tmp on the server? I think that 2157@c it can be substantial, but I haven't looked at this 2158@c again and tried to figure it out ("cvs import" is 2159@c probably the worst case...). 2160 2161The second area of large memory consumption is 2162@code{diff}, when checking in large files. This is 2163required even for binary files. The rule of thumb is 2164to allow about ten times the size of the largest file 2165you will want to check in, although five times may be 2166adequate. For example, if you want to check in a file 2167which is 10 megabytes, you should have 100 megabytes of 2168memory on the machine doing the checkin (the server 2169machine for client/server, or the machine running 2170@sc{cvs} for non-client/server). This can be swap 2171space rather than physical memory. Because the memory 2172is only required briefly, there is no particular need 2173to allow memory for more than one such checkin at a 2174time. 2175@c The 5-10 times rule of thumb is from Paul Eggert for 2176@c GNU diff. I don't think it is in the GNU diff 2177@c manual or anyplace like that. 2178@c 2179@c Probably we could be saying more about 2180@c non-client/server CVS. 2181@c I would guess for non-client/server CVS in an NFS 2182@c environment the biggest issues are the network and 2183@c the NFS server. 2184 2185Resource consumption for the client is even more 2186modest---any machine with enough capacity to run the 2187operating system in question should have little 2188trouble. 2189@c Is that true? I think the client still wants to 2190@c (bogusly) store entire files in memory at times. 2191 2192For information on disk space requirements, see 2193@ref{Creating a repository}. 2194 2195@node The connection method 2196@subsection The connection method 2197 2198In its simplest form, the @var{method} portion of the repository string 2199(@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork}, 2200@samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some 2201platforms, @samp{server}. 2202 2203If @var{method} is not specified, and the repository 2204name starts with a @samp{/}, then the default is @code{local}. 2205If @var{method} is not specified, and the repository 2206name does not start with a @samp{/}, then the default is @code{ext} 2207or @code{server}, depending on your platform; both the @samp{ext} 2208and @samp{server} methods are described in @ref{Connecting via rsh}. 2209 2210@cindex connection method options 2211@cindex options, connection method 2212The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection 2213methods all accept optional method options, specified as part of the 2214@var{method} string, like so: 2215 2216@example 2217:@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data} 2218@end example 2219 2220@sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though 2221it may sometimes be sensitive to the case of @var{arg}. The possible method 2222options are as follows: 2223 2224@table @code 2225@cindex CVS_PROXY_PORT 2226@cindex proxy, method option 2227@cindex proxyport, method option 2228@cindex proxies, web, connecting via 2229@cindex web proxies, connecting via 2230@cindex proxies, HTTP, connecting via 2231@cindex HTTP proxies, connecting via 2232@item proxy=@var{hostname} 2233@itemx proxyport=@var{port} 2234These two method options can be used to connect via an HTTP tunnel style web 2235proxy. @var{hostname} should be the name of the HTTP proxy server to connect 2236through and @var{port} is the port number on the HTTP proxy server to connect 2237via. @var{port} defaults to 8080. 2238 2239@strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy 2240server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.} 2241 2242For example, to connect pserver via a web proxy listening on port 8000 of 2243www.myproxy.net, you would use a method of: 2244 2245@example 2246:pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string} 2247@end example 2248 2249@strong{NOTE: In the above example, @var{pserver_connection_string} is still 2250required to connect and authenticate to the CVS server, as noted in the 2251upcoming sections on password authentication, @code{gserver}, and 2252@code{kserver}. The example above only demonstrates a modification to the 2253@var{method} portion of the repository name.} 2254 2255These options first appeared in @sc{cvs} version 1.12.7 and are valid as 2256modifcations to the @code{gserver} and @code{pserver} connection methods. 2257 2258@cindex CVS_RSH method option 2259@item CVS_RSH=@var{path} 2260This method option can be used with the @code{ext} method to specify the path 2261the @sc{cvs} client will use to find the remote shell used to contact the 2262@sc{cvs} server and takes precedence over any path specified in the 2263@code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}). For 2264example, to connect to a @sc{cvs} server via the local 2265@file{/path/to/ssh/command} command, you could choose to specify the following 2266@var{path} via the @code{CVS_RSH} method option: 2267 2268@example 2269:ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string} 2270@end example 2271 2272This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2273as a modifcation to the @code{ext} connection method. 2274 2275@cindex CVS_SERVER method option 2276@item CVS_SERVER=@var{path} 2277This method option can be used with the @code{ext} and @code{fork} methods to 2278specify the path @sc{cvs} will use to find the @sc{cvs} executable on the 2279@sc{cvs} server and takes precedence over any path specified in the 2280@code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}). For 2281example, to select the remote @file{/path/to/cvs/command} executable as your 2282@sc{cvs} server application on the @sc{cvs} server machine, you could choose to 2283specify the following @var{path} via the @code{CVS_SERVER} method option: 2284 2285@example 2286:ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string} 2287@end example 2288 2289@noindent 2290or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your 2291@code{$PATH} on the @sc{cvs} server: 2292 2293@example 2294:ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string} 2295@end example 2296 2297This method option first appeared in @sc{cvs} version 1.12.11 and is valid 2298as a modifcation to both the @code{ext} and @code{fork} connection methods. 2299 2300@cindex Redirect, method option 2301@item Redirect=@var{boolean-state} 2302The @code{Redirect} method option determines whether the @sc{cvs} client will 2303allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually 2304for write requests, as in a write proxy setup. 2305 2306A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config} 2307file options is acceptable here (@pxref{config}). For example, @samp{on}, 2308@samp{off}, @samp{true}, and @samp{false} are all valid values for 2309@var{boolean-state}. @var{boolean-state} for the @code{Redirect} method option 2310defaults to @samp{on}. 2311 2312This option will have no effect when talking to any non-secondary @sc{cvs} 2313server. For more on write proxies and secondary servers, please see 2314@ref{Write proxies}. 2315 2316This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2317as a modifcation to the @code{ext} connection method. 2318@end table 2319 2320As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER} 2321options, a method specification like the following would work: 2322 2323@example 2324:ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command: 2325@end example 2326 2327This means that you would not need to have 2328the @code{CVS_SERVER} or @code{CVS_RSH} environment 2329variables set correctly. See @ref{Connecting via rsh}, for more details on 2330these environment variables. 2331 2332@node Connecting via rsh 2333@subsection Connecting with rsh 2334 2335@cindex rsh 2336@sc{cvs} uses the @samp{rsh} protocol to perform these 2337operations, so the remote user host needs to have a 2338@file{.rhosts} file which grants access to the local 2339user. Note that the program that @sc{cvs} uses for this 2340purpose may be specified using the @file{--with-rsh} 2341flag to configure. 2342 2343For example, suppose you are the user @samp{mozart} on 2344the local machine @samp{toe.example.com}, and the 2345server machine is @samp{faun.example.org}. On 2346faun, put the following line into the file 2347@file{.rhosts} in @samp{bach}'s home directory: 2348 2349@example 2350toe.example.com mozart 2351@end example 2352 2353@noindent 2354Then test that @samp{rsh} is working with 2355 2356@example 2357rsh -l bach faun.example.org 'echo $PATH' 2358@end example 2359 2360@cindex CVS_SERVER, environment variable 2361Next you have to make sure that @code{rsh} will be able 2362to find the server. Make sure that the path which 2363@code{rsh} printed in the above example includes the 2364directory containing a program named @code{cvs} which 2365is the server. You need to set the path in 2366@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 2367or @file{.profile}. Alternately, you can set the 2368environment variable @code{CVS_SERVER} on the client 2369machine to the filename of the server you want to use, 2370for example @file{/usr/local/bin/cvs-1.6}. 2371For the @code{ext} and @code{fork} methods, you may 2372also specify @var{CVS_SERVER} as an otpion in the 2373@var{CVSROOT} so that you may use different servers for 2374differnt roots. See @ref{Remote repositories} for more 2375details. 2376 2377There is no need to edit @file{inetd.conf} or start a 2378@sc{cvs} server daemon. 2379 2380@cindex :server:, setting up 2381@cindex :ext:, setting up 2382@cindex Kerberos, using kerberized rsh 2383@cindex SSH (rsh replacement) 2384@cindex rsh replacements (Kerberized, SSH, &c) 2385There are two access methods that you use in @code{CVSROOT} 2386for rsh. @code{:server:} specifies an internal rsh 2387client, which is supported only by some @sc{cvs} ports. 2388@code{:ext:} specifies an external rsh program. By 2389default this is @code{rsh} (unless otherwise specified 2390by the @file{--with-rsh} flag to configure) but you may set the 2391@code{CVS_RSH} environment variable to invoke another 2392program which can access the remote server (for 2393example, @code{remsh} on HP-UX 9 because @code{rsh} is 2394something different). It must be a program which can 2395transmit data to and from the server without modifying 2396it; for example the Windows NT @code{rsh} is not 2397suitable since it by default translates between CRLF 2398and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 2399to @code{rsh} to get around this, but since this could 2400potentially cause problems for programs other than the 2401standard @code{rsh}, it may change in the future. If 2402you set @code{CVS_RSH} to @code{SSH} or some other rsh 2403replacement, the instructions in the rest of this 2404section concerning @file{.rhosts} and so on are likely 2405to be inapplicable; consult the documentation for your rsh 2406replacement. 2407 2408You may choose to specify the @var{CVS_RSH} option as a method option 2409in the @var{CVSROOT} string to allow you to use different connection tools 2410for different roots (@pxref{The connection method}). For example, allowing 2411some roots to use @code{CVS_RSH=remsh} and some to use 2412@code{CVS_RSH=ssh} for the @code{ext} method. See also 2413the @ref{Remote repositories} for more details. 2414@c See also the comment in src/client.c for rationale 2415@c concerning "rsh" being the default and never 2416@c "remsh". 2417 2418Continuing our example, supposing you want to access 2419the module @file{foo} in the repository 2420@file{/usr/local/cvsroot/}, on machine 2421@file{faun.example.org}, you are ready to go: 2422 2423@example 2424cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2425@end example 2426 2427@noindent 2428(The @file{bach@@} can be omitted if the username is 2429the same on both the local and remote hosts.) 2430 2431@c Should we mention "rsh host echo hi" and "rsh host 2432@c cat" (the latter followed by typing text and ^D) 2433@c as troubleshooting techniques? Probably yes 2434@c (people tend to have trouble setting this up), 2435@c but this kind of thing can be hard to spell out. 2436 2437@node Password authenticated 2438@subsection Direct connection with password authentication 2439 2440The @sc{cvs} client can also connect to the server 2441using a password protocol. This is particularly useful 2442if using @code{rsh} is not feasible (for example, 2443the server is behind a firewall), and Kerberos also is 2444not available. 2445 2446 To use this method, it is necessary to make 2447some adjustments on both the server and client sides. 2448 2449@menu 2450* Password authentication server:: Setting up the server 2451* Password authentication client:: Using the client 2452* Password authentication security:: What this method does and does not do 2453@end menu 2454 2455@node Password authentication server 2456@subsubsection Setting up the server for password authentication 2457 2458First of all, you probably want to tighten the 2459permissions on the @file{$CVSROOT} and 2460@file{$CVSROOT/CVSROOT} directories. See @ref{Password 2461authentication security}, for more details. 2462 2463@cindex pserver (subcommand) 2464@cindex Remote repositories, port specification 2465@cindex Repositories, remote, port specification 2466@cindex Client/Server Operation, port specification 2467@cindex pserver (client/server connection method), port specification 2468@cindex kserver (client/server connection method), port specification 2469@cindex gserver (client/server connection method), port specification 2470@cindex port, specifying for remote repositories 2471@cindex Password server, setting up 2472@cindex Authenticating server, setting up 2473@cindex inetd, configuring for pserver 2474@cindex xinetd, configuring for pserver 2475@c FIXME: this isn't quite right regarding port 2476@c numbers; CVS looks up "cvspserver" in 2477@c /etc/services (on unix, but what about non-unix?). 2478On the server side, the file @file{/etc/inetd.conf} 2479needs to be edited so @code{inetd} knows to run the 2480command @code{cvs pserver} when it receives a 2481connection on the right port. By default, the port 2482number is 2401; it would be different if your client 2483were compiled with @code{CVS_AUTH_PORT} defined to 2484something else, though. This can also be specified in the CVSROOT variable 2485(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 2486environment variable (@pxref{Environment variables}). 2487 2488 If your @code{inetd} allows raw port numbers in 2489@file{/etc/inetd.conf}, then the following (all on a 2490single line in @file{inetd.conf}) should be sufficient: 2491 2492@example 24932401 stream tcp nowait root /usr/local/bin/cvs 2494cvs -f --allow-root=/usr/cvsroot pserver 2495@end example 2496 2497@noindent 2498(You could also use the 2499@samp{-T} option to specify a temporary directory.) 2500 2501The @samp{--allow-root} option specifies the allowable 2502@sc{cvsroot} directory. Clients which attempt to use a 2503different @sc{cvsroot} directory will not be allowed to 2504connect. If there is more than one @sc{cvsroot} 2505directory which you want to allow, repeat the option. 2506(Unfortunately, many versions of @code{inetd} have very small 2507limits on the number of arguments and/or the total length 2508of the command. The usual solution to this problem is 2509to have @code{inetd} run a shell script which then invokes 2510@sc{cvs} with the necessary arguments.) 2511 2512 If your @code{inetd} wants a symbolic service 2513name instead of a raw port number, then put this in 2514@file{/etc/services}: 2515 2516@example 2517cvspserver 2401/tcp 2518@end example 2519 2520@noindent 2521and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 2522 2523If your system uses @code{xinetd} instead of @code{inetd}, 2524the procedure is slightly different. 2525Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2526 2527@example 2528service cvspserver 2529@{ 2530 port = 2401 2531 socket_type = stream 2532 protocol = tcp 2533 wait = no 2534 user = root 2535 passenv = PATH 2536 server = /usr/local/bin/cvs 2537 server_args = -f --allow-root=/usr/cvsroot pserver 2538@} 2539@end example 2540 2541@noindent 2542(If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2543the @code{port} line.) 2544 2545 Once the above is taken care of, restart your 2546@code{inetd}, or do whatever is necessary to force it 2547to reread its initialization files. 2548 2549If you are having trouble setting this up, see 2550@ref{Connection}. 2551 2552@cindex CVS passwd file 2553@cindex passwd (admin file) 2554Because the client stores and transmits passwords in 2555cleartext (almost---see @ref{Password authentication 2556security}, for details), a separate @sc{cvs} password 2557file is generally used, so people don't compromise 2558their regular passwords when they access the 2559repository. This file is 2560@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 2561administrative files}). It uses a colon-separated 2562format, similar to @file{/etc/passwd} on Unix systems, 2563except that it has fewer fields: @sc{cvs} username, 2564optional password, and an optional system username for 2565@sc{cvs} to run as if authentication succeeds. Here is 2566an example @file{passwd} file with five entries: 2567 2568@example 2569anonymous: 2570bach:ULtgRLXo7NRxs 2571spwang:1sOp854gDF3DY 2572melissa:tGX1fS8sun6rY:pubcvs 2573qproj:XR4EZcEs0szik:pubcvs 2574@end example 2575 2576@noindent 2577(The passwords are encrypted according to the standard 2578Unix @code{crypt()} function, so it is possible to 2579paste in passwords directly from regular Unix 2580@file{/etc/passwd} files.) 2581 2582The first line in the example will grant access to any 2583@sc{cvs} client attempting to authenticate as user 2584@code{anonymous}, no matter what password they use, 2585including an empty password. (This is typical for 2586sites granting anonymous read-only access; for 2587information on how to do the "read-only" part, see 2588@ref{Read-only access}.) 2589 2590The second and third lines will grant access to 2591@code{bach} and @code{spwang} if they supply their 2592respective plaintext passwords. 2593 2594@cindex User aliases 2595The fourth line will grant access to @code{melissa}, if 2596she supplies the correct password, but her @sc{cvs} 2597operations will actually run on the server side under 2598the system user @code{pubcvs}. Thus, there need not be 2599any system user named @code{melissa}, but there 2600@emph{must} be one named @code{pubcvs}. 2601 2602The fifth line shows that system user identities can be 2603shared: any client who successfully authenticates as 2604@code{qproj} will actually run as @code{pubcvs}, just 2605as @code{melissa} does. That way you could create a 2606single, shared system user for each project in your 2607repository, and give each developer their own line in 2608the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 2609username on each line would be different, but the 2610system username would be the same. The reason to have 2611different @sc{cvs} usernames is that @sc{cvs} will log their 2612actions under those names: when @code{melissa} commits 2613a change to a project, the checkin is recorded in the 2614project's history under the name @code{melissa}, not 2615@code{pubcvs}. And the reason to have them share a 2616system username is so that you can arrange permissions 2617in the relevant area of the repository such that only 2618that account has write-permission there. 2619 2620If the system-user field is present, all 2621password-authenticated @sc{cvs} commands run as that 2622user; if no system user is specified, @sc{cvs} simply 2623takes the @sc{cvs} username as the system username and 2624runs commands as that user. In either case, if there 2625is no such user on the system, then the @sc{cvs} 2626operation will fail (regardless of whether the client 2627supplied a valid password). 2628 2629The password and system-user fields can both be omitted 2630(and if the system-user field is omitted, then also 2631omit the colon that would have separated it from the 2632encrypted password). For example, this would be a 2633valid @file{$CVSROOT/CVSROOT/passwd} file: 2634 2635@example 2636anonymous::pubcvs 2637fish:rKa5jzULzmhOo:kfogel 2638sussman:1sOp854gDF3DY 2639@end example 2640 2641@noindent 2642When the password field is omitted or empty, then the 2643client's authentication attempt will succeed with any 2644password, including the empty string. However, the 2645colon after the @sc{cvs} username is always necessary, 2646even if the password is empty. 2647 2648@sc{cvs} can also fall back to use system authentication. 2649When authenticating a password, the server first checks 2650for the user in the @file{$CVSROOT/CVSROOT/passwd} 2651file. If it finds the user, it will use that entry for 2652authentication as described above. But if it does not 2653find the user, or if the @sc{cvs} @file{passwd} file 2654does not exist, then the server can try to authenticate 2655the username and password using the operating system's 2656user-lookup routines (this "fallback" behavior can be 2657disabled by setting @code{SystemAuth=no} in the 2658@sc{cvs} @file{config} file, @pxref{config}). 2659 2660The default fallback behavior is to look in 2661@file{/etc/passwd} for this system user unless your 2662system has PAM (Pluggable Authentication Modules) 2663and your @sc{cvs} server executable was configured to 2664use it at compile time (using @code{./configure --enable-pam} - see the 2665INSTALL file for more). In this case, PAM will be consulted instead. 2666This means that @sc{cvs} can be configured to use any password 2667authentication source PAM can be configured to use (possibilities 2668include a simple UNIX password, NIS, LDAP, and others) in its 2669global configuration file (usually @file{/etc/pam.conf} 2670or possibly @file{/etc/pam.d/cvs}). See your PAM documentation 2671for more details on PAM configuration. 2672 2673Note that PAM is an experimental feature in @sc{cvs} and feedback is 2674encouraged. Please send a mail to one of the @sc{cvs} mailing lists 2675(@code{info-cvs@@nongnu.org} or @code{bug-cvs@@nongnu.org}) if you use the 2676@sc{cvs} PAM support. 2677 2678@strong{WARNING: Using PAM gives the system administrator much more 2679flexibility about how @sc{cvs} users are authenticated but 2680no more security than other methods. See below for more.} 2681 2682CVS needs an "auth", "account" and "session" module in the 2683PAM configuration file. A typical PAM configuration 2684would therefore have the following lines 2685in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 2686system @file{/etc/passwd} authentication: 2687 2688@example 2689cvs auth required pam_unix.so 2690cvs account required pam_unix.so 2691cvs session required pam_unix.so 2692@end example 2693 2694The the equivalent @file{/etc/pam.d/cvs} would contain 2695 2696@example 2697auth required pam_unix.so 2698account required pam_unix.so 2699session required pam_unix.so 2700@end example 2701 2702Some systems require a full path to the module so that 2703@file{pam_unix.so} (Linux) would become something like 2704@file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris). 2705See the @file{contrib/pam} subdirectory of the @sc{cvs} 2706source distribution for further example configurations. 2707 2708The PAM service name given above as "cvs" is just 2709the service name in the default configuration and can be 2710set using 2711@code{./configure --with-hardcoded-pam-service-name=<pam-service-name>} 2712before compiling. @sc{cvs} can also be configured to use whatever 2713name it is invoked as as its PAM service name using 2714@code{./configure --without-hardcoded-pam-service-name}, but this 2715feature should not be used if you may not have control of the name 2716@sc{cvs} will be invoked as. 2717 2718Be aware, also, that falling back to system 2719authentication might be a security risk: @sc{cvs} 2720operations would then be authenticated with that user's 2721regular login password, and the password flies across 2722the network in plaintext. See @ref{Password 2723authentication security} for more on this. 2724This may be more of a problem with PAM authentication 2725because it is likely that the source of the system 2726password is some central authentication service like 2727LDAP which is also used to authenticate other services. 2728 2729On the other hand, PAM makes it very easy to change your password 2730regularly. If they are given the option of a one-password system for 2731all of their activities, users are often more willing to change their 2732password on a regular basis. 2733 2734In the non-PAM configuration where the password is stored in the 2735@file{CVSROOT/passwd} file, it is difficult to change passwords on a 2736regular basis since only administrative users (or in some cases 2737processes that act as an administrative user) are typically given 2738access to modify this file. Either there needs to be some 2739hand-crafted web page or set-uid program to update the file, or the 2740update needs to be done by submitting a request to an administrator to 2741perform the duty by hand. In the first case, having to remember to 2742update a separate password on a periodic basis can be difficult. In 2743the second case, the manual nature of the change will typically mean 2744that the password will not be changed unless it is absolutely 2745necessary. 2746 2747Note that PAM administrators should probably avoid configuring 2748one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If 2749OTPs are desired, the administrator may wish to encourage the use of 2750one of the other Client/Server access methods. See the section on 2751@pxref{Remote repositories} for a list of other methods. 2752 2753Right now, the only way to put a password in the 2754@sc{cvs} @file{passwd} file is to paste it there from 2755somewhere else. Someday, there may be a @code{cvs 2756passwd} command. 2757 2758Unlike many of the files in @file{$CVSROOT/CVSROOT}, it 2759is normal to edit the @file{passwd} file in-place, 2760rather than via @sc{cvs}. This is because of the 2761possible security risks of having the @file{passwd} 2762file checked out to people's working copies. If you do 2763want to include the @file{passwd} file in checkouts of 2764@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 2765 2766@c We might also suggest using the @code{htpasswd} command 2767@c from freely available web servers as well, but that 2768@c would open up a can of worms in that the users next 2769@c questions are likely to be "where do I get it?" and 2770@c "how do I use it?" 2771@c Also note that htpasswd, at least the version I had, 2772@c likes to clobber the third field. 2773 2774@node Password authentication client 2775@subsubsection Using the client with password authentication 2776@cindex Login (subcommand) 2777@cindex Password client, using 2778@cindex Authenticated client, using 2779@cindex :pserver:, setting up 2780To run a @sc{cvs} command on a remote repository via 2781the password-authenticating server, one specifies the 2782@code{pserver} protocol, optional username, repository host, an 2783optional port number, and path to the repository. For example: 2784 2785@example 2786cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 2787@end example 2788 2789@noindent 2790or 2791 2792@example 2793CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 2794cvs checkout someproj 2795@end example 2796 2797However, unless you're connecting to a public-access 2798repository (i.e., one where that username doesn't 2799require a password), you'll need to supply a password or @dfn{log in} first. 2800Logging in verifies your password with the repository and stores it in a file. 2801It's done with the @code{login} command, which will 2802prompt you interactively for the password if you didn't supply one as part of 2803@var{$CVSROOT}: 2804 2805@example 2806cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 2807CVS password: 2808@end example 2809 2810@noindent 2811or 2812 2813@example 2814cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 2815@end example 2816 2817After you enter the password, @sc{cvs} verifies it with 2818the server. If the verification succeeds, then that 2819combination of username, host, repository, and password 2820is permanently recorded, so future transactions with 2821that repository won't require you to run @code{cvs 2822login}. (If verification fails, @sc{cvs} will exit 2823complaining that the password was incorrect, and 2824nothing will be recorded.) 2825 2826The records are stored, by default, in the file 2827@file{$HOME/.cvspass}. That file's format is 2828human-readable, and to a degree human-editable, but 2829note that the passwords are not stored in 2830cleartext---they are trivially encoded to protect them 2831from "innocent" compromise (i.e., inadvertent viewing 2832by a system administrator or other non-malicious 2833person). 2834 2835@cindex CVS_PASSFILE, environment variable 2836You can change the default location of this file by 2837setting the @code{CVS_PASSFILE} environment variable. 2838If you use this variable, make sure you set it 2839@emph{before} @code{cvs login} is run. If you were to 2840set it after running @code{cvs login}, then later 2841@sc{cvs} commands would be unable to look up the 2842password for transmission to the server. 2843 2844Once you have logged in, all @sc{cvs} commands using 2845that remote repository and username will authenticate 2846with the stored password. So, for example 2847 2848@example 2849cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2850@end example 2851 2852@noindent 2853should just work (unless the password changes on the 2854server side, in which case you'll have to re-run 2855@code{cvs login}). 2856 2857Note that if the @samp{:pserver:} were not present in 2858the repository specification, @sc{cvs} would assume it 2859should use @code{rsh} to connect with the server 2860instead (@pxref{Connecting via rsh}). 2861 2862Of course, once you have a working copy checked out and 2863are running @sc{cvs} commands from within it, there is 2864no longer any need to specify the repository 2865explicitly, because @sc{cvs} can deduce the repository 2866from the working copy's @file{CVS} subdirectory. 2867 2868@c FIXME: seems to me this needs somewhat more 2869@c explanation. 2870@cindex Logout (subcommand) 2871The password for a given remote repository can be 2872removed from the @code{CVS_PASSFILE} by using the 2873@code{cvs logout} command. 2874 2875@node Password authentication security 2876@subsubsection Security considerations with password authentication 2877 2878@cindex Security, of pserver 2879The passwords are stored on the client side in a 2880trivial encoding of the cleartext, and transmitted in 2881the same encoding. The encoding is done only to 2882prevent inadvertent password compromises (i.e., a 2883system administrator accidentally looking at the file), 2884and will not prevent even a naive attacker from gaining 2885the password. 2886 2887@c FIXME: The bit about "access to the repository 2888@c implies general access to the system is *not* specific 2889@c to pserver; it applies to kerberos and SSH and 2890@c everything else too. Should reorganize the 2891@c documentation to make this clear. 2892The separate @sc{cvs} password file (@pxref{Password 2893authentication server}) allows people 2894to use a different password for repository access than 2895for login access. On the other hand, once a user has 2896non-read-only 2897access to the repository, she can execute programs on 2898the server system through a variety of means. Thus, repository 2899access implies fairly broad system access as well. It 2900might be possible to modify @sc{cvs} to prevent that, 2901but no one has done so as of this writing. 2902@c OpenBSD uses chroot() and copies the repository to 2903@c provide anonymous read-only access (for details see 2904@c http://www.openbsd.org/anoncvs.shar). While this 2905@c closes the most obvious holes, I'm not sure it 2906@c closes enough holes to recommend it (plus it is 2907@c *very* easy to accidentally screw up a setup of this 2908@c type). 2909 2910Note that because the @file{$CVSROOT/CVSROOT} directory 2911contains @file{passwd} and other files which are used 2912to check security, you must control the permissions on 2913this directory as tightly as the permissions on 2914@file{/etc}. The same applies to the @file{$CVSROOT} 2915directory itself and any directory 2916above it in the tree. Anyone who has write access to 2917such a directory will have the ability to become any 2918user on the system. Note that these permissions are 2919typically tighter than you would use if you are not 2920using pserver. 2921@c TODO: Would be really nice to document/implement a 2922@c scheme where the CVS server can run as some non-root 2923@c user, e.g. "cvs". CVSROOT/passwd would contain a 2924@c bunch of entries of the form foo:xxx:cvs (or the "cvs" 2925@c would be implicit). This would greatly reduce 2926@c security risks such as those hinted at in the 2927@c previous paragraph. I think minor changes to CVS 2928@c might be required but mostly this would just need 2929@c someone who wants to play with it, document it, &c. 2930 2931In summary, anyone who gets the password gets 2932repository access (which may imply some measure of general system 2933access as well). The password is available to anyone 2934who can sniff network packets or read a protected 2935(i.e., user read-only) file. If you want real 2936security, get Kerberos. 2937 2938@node GSSAPI authenticated 2939@subsection Direct connection with GSSAPI 2940 2941@cindex GSSAPI 2942@cindex Security, GSSAPI 2943@cindex :gserver:, setting up 2944@cindex Kerberos, using :gserver: 2945GSSAPI is a generic interface to network security 2946systems such as Kerberos 5. 2947If you have a working GSSAPI library, you can have 2948@sc{cvs} connect via a direct @sc{tcp} connection, 2949authenticating with GSSAPI. 2950 2951To do this, @sc{cvs} needs to be compiled with GSSAPI 2952support; when configuring @sc{cvs} it tries to detect 2953whether GSSAPI libraries using Kerberos version 5 are 2954present. You can also use the @file{--with-gssapi} 2955flag to configure. 2956 2957The connection is authenticated using GSSAPI, but the 2958message stream is @emph{not} authenticated by default. 2959You must use the @code{-a} global option to request 2960stream authentication. 2961 2962The data transmitted is @emph{not} encrypted by 2963default. Encryption support must be compiled into both 2964the client and the server; use the 2965@file{--enable-encrypt} configure option to turn it on. 2966You must then use the @code{-x} global option to 2967request encryption. 2968 2969GSSAPI connections are handled on the server side by 2970the same server which handles the password 2971authentication server; see @ref{Password authentication 2972server}. If you are using a GSSAPI mechanism such as 2973Kerberos which provides for strong authentication, you 2974will probably want to disable the ability to 2975authenticate via cleartext passwords. To do so, create 2976an empty @file{CVSROOT/passwd} password file, and set 2977@code{SystemAuth=no} in the config file 2978(@pxref{config}). 2979 2980The GSSAPI server uses a principal name of 2981cvs/@var{hostname}, where @var{hostname} is the 2982canonical name of the server host. You will have to 2983set this up as required by your GSSAPI mechanism. 2984 2985To connect using GSSAPI, use the @samp{:gserver:} method. For 2986example, 2987 2988@example 2989cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 2990@end example 2991 2992@node Kerberos authenticated 2993@subsection Direct connection with Kerberos 2994 2995@cindex Kerberos, using :kserver: 2996@cindex Security, Kerberos 2997@cindex :kserver:, setting up 2998The easiest way to use Kerberos is to use the Kerberos 2999@code{rsh}, as described in @ref{Connecting via rsh}. 3000The main disadvantage of using rsh is that all the data 3001needs to pass through additional programs, so it may be 3002slower. So if you have Kerberos installed you can 3003connect via a direct @sc{tcp} connection, 3004authenticating with Kerberos. 3005 3006This section concerns the Kerberos network security 3007system, version 4. Kerberos version 5 is supported via 3008the GSSAPI generic network security interface, as 3009described in the previous section. 3010 3011To do this, @sc{cvs} needs to be compiled with Kerberos 3012support; when configuring @sc{cvs} it tries to detect 3013whether Kerberos is present or you can use the 3014@file{--with-krb4} flag to configure. 3015 3016The data transmitted is @emph{not} encrypted by 3017default. Encryption support must be compiled into both 3018the client and server; use the 3019@file{--enable-encryption} configure option to turn it 3020on. You must then use the @code{-x} global option to 3021request encryption. 3022 3023The CVS client will attempt to connect to port 1999 by default. 3024 3025@cindex kinit 3026When you want to use @sc{cvs}, get a ticket in the 3027usual way (generally @code{kinit}); it must be a ticket 3028which allows you to log into the server machine. Then 3029you are ready to go: 3030 3031@example 3032cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 3033@end example 3034 3035Previous versions of @sc{cvs} would fall back to a 3036connection via rsh; this version will not do so. 3037 3038@node Connecting via fork 3039@subsection Connecting with fork 3040 3041@cindex fork, access method 3042@cindex :fork:, setting up 3043This access method allows you to connect to a 3044repository on your local disk via the remote protocol. 3045In other words it does pretty much the same thing as 3046@code{:local:}, but various quirks, bugs and the like are 3047those of the remote @sc{cvs} rather than the local 3048@sc{cvs}. 3049 3050For day-to-day operations you might prefer either 3051@code{:local:} or @code{:fork:}, depending on your 3052preferences. Of course @code{:fork:} comes in 3053particularly handy in testing or 3054debugging @code{cvs} and the remote protocol. 3055Specifically, we avoid all of the network-related 3056setup/configuration, timeouts, and authentication 3057inherent in the other remote access methods but still 3058create a connection which uses the remote protocol. 3059 3060To connect using the @code{fork} method, use 3061@samp{:fork:} and the pathname to your local 3062repository. For example: 3063 3064@example 3065cvs -d :fork:/usr/local/cvsroot checkout foo 3066@end example 3067 3068@cindex CVS_SERVER, and :fork: 3069As with @code{:ext:}, the server is called @samp{cvs} 3070by default, or the value of the @code{CVS_SERVER} 3071environment variable. 3072 3073 3074@node Write proxies 3075@subsection Distributing load across several CVS servers 3076 3077@cindex PrimaryServer, in CVSROOT/config 3078@cindex Primary server 3079@cindex Secondary server 3080@cindex proxy, write 3081@cindex write proxy 3082@sc{cvs} can be configured to distribute usage across several @sc{cvs} 3083servers. This is accomplished by means of one or more @dfn{write proxies}, or 3084@dfn{secondary servers}, for a single @dfn{primary server}. 3085 3086When a @sc{cvs} client accesses a secondary server and only sends read 3087requests, then the secondary server handles the entire request. If the client 3088sends any write requests, however, the secondary server asks the client to 3089redirect its write request to the primary server, if the client supports 3090redirect requests, and otherwise becomes a transparent proxy for the primary 3091server, which actually handles the write request. 3092 3093In this manner, any number of read-only secondary servers may be configured as 3094write proxies for the primary server, effectively distributing the load from 3095all read operations between the secondary servers and restricting the load on 3096the primary server to write operations and pushing changes to the secondaries. 3097 3098Primary servers will not automatically push changes to secondaries. This must 3099be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, & 3100@file{postwatch} scripts (@pxref{Trigger Scripts}) like the following: 3101 3102@example 3103ALL rsync -gopr -essh ./ secondary:/cvsroot/%p & 3104@end example 3105 3106You would probably actually want to lock directories for write on the secondary 3107and for read on the primary before running the @samp{rsync} in the above 3108example, but describing such a setup is beyond the scope of this document. 3109 3110A secondary advantage of a write proxy setup is that users pointing at the 3111secondary server can still execute fast read operations while on a network that 3112connects to the primary over a slow link or even one where the link to the 3113primary is periodically broken. Only write operations will require the network 3114link to the primary. 3115 3116To configure write proxies, the primary must be specified with the 3117@samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}). For the 3118transparent proxy mode to work, all secondary servers must also be running the 3119same version of the @sc{cvs} server, or at least one that provides the same 3120list of supported requests to the client as the primary server. This is not 3121necessary for redirection. 3122 3123Once a primary server is configured, secondary servers may be configured by: 3124 3125@enumerate 3126@item 3127Duplicating the primary repository at the new location. 3128@item 3129Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and 3130@file{postwatch} files on the primary to propagate writes to the new secondary. 3131@item 3132Configure remote access to the secondary(ies) as you would configure access 3133to any other CVS server (@pxref{Remote repositories}). 3134@item 3135Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to 3136@strong{all} incovations of the secondary server if the path to the @sc{cvs} 3137repository directory is different on the two servers and you wish to support 3138clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier 3139clients do not handle the @samp{Redirect} response). 3140 3141Please note, again, that writethrough proxy suport requires 3142@code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all} 3143incovations of the secondary server, not just @samp{pserver} invocations. 3144This may require a wrapper script for the @sc{cvs} executable 3145on your server machine. 3146@end enumerate 3147 3148 3149@c --------------------------------------------------------------------- 3150@node Read-only access 3151@section Read-only repository access 3152@cindex Read-only repository access 3153@cindex readers (admin file) 3154@cindex writers (admin file) 3155 3156 It is possible to grant read-only repository 3157access to people using the password-authenticated 3158server (@pxref{Password authenticated}). (The 3159other access methods do not have explicit support for 3160read-only users because those methods all assume login 3161access to the repository machine anyway, and therefore 3162the user can do whatever local file permissions allow 3163her to do.) 3164 3165 A user who has read-only access can do only 3166those @sc{cvs} operations which do not modify the 3167repository, except for certain ``administrative'' files 3168(such as lock files and the history file). It may be 3169desirable to use this feature in conjunction with 3170user-aliasing (@pxref{Password authentication server}). 3171 3172Unlike with previous versions of @sc{cvs}, read-only 3173users should be able merely to read the repository, and 3174not to execute programs on the server or otherwise gain 3175unexpected levels of access. Or to be more accurate, 3176the @emph{known} holes have been plugged. Because this 3177feature is new and has not received a comprehensive 3178security audit, you should use whatever level of 3179caution seems warranted given your attitude concerning 3180security. 3181 3182 There are two ways to specify read-only access 3183for a user: by inclusion, and by exclusion. 3184 3185 "Inclusion" means listing that user 3186specifically in the @file{$CVSROOT/CVSROOT/readers} 3187file, which is simply a newline-separated list of 3188users. Here is a sample @file{readers} file: 3189 3190@example 3191melissa 3192splotnik 3193jrandom 3194@end example 3195 3196@noindent 3197 (Don't forget the newline after the last user.) 3198 3199 "Exclusion" means explicitly listing everyone 3200who has @emph{write} access---if the file 3201 3202@example 3203$CVSROOT/CVSROOT/writers 3204@end example 3205 3206@noindent 3207exists, then only 3208those users listed in it have write access, and 3209everyone else has read-only access (of course, even the 3210read-only users still need to be listed in the 3211@sc{cvs} @file{passwd} file). The 3212@file{writers} file has the same format as the 3213@file{readers} file. 3214 3215 Note: if your @sc{cvs} @file{passwd} 3216file maps cvs users onto system users (@pxref{Password 3217authentication server}), make sure you deny or grant 3218read-only access using the @emph{cvs} usernames, not 3219the system usernames. That is, the @file{readers} and 3220@file{writers} files contain cvs usernames, which may 3221or may not be the same as system usernames. 3222 3223 Here is a complete description of the server's 3224behavior in deciding whether to grant read-only or 3225read-write access: 3226 3227 If @file{readers} exists, and this user is 3228listed in it, then she gets read-only access. Or if 3229@file{writers} exists, and this user is NOT listed in 3230it, then she also gets read-only access (this is true 3231even if @file{readers} exists but she is not listed 3232there). Otherwise, she gets full read-write access. 3233 3234 Of course there is a conflict if the user is 3235listed in both files. This is resolved in the more 3236conservative way, it being better to protect the 3237repository too much than too little: such a user gets 3238read-only access. 3239 3240@node Server temporary directory 3241@section Temporary directories for the server 3242@cindex Temporary directories, and server 3243@cindex Server, temporary directories 3244 3245While running, the @sc{cvs} server creates temporary 3246directories. They are named 3247 3248@example 3249cvs-serv@var{pid} 3250@end example 3251 3252@noindent 3253where @var{pid} is the process identification number of 3254the server. 3255They are located in the directory specified by 3256the @samp{-T} global option (@pxref{Global options}), 3257the @code{TMPDIR} environment variable (@pxref{Environment variables}), 3258or, failing that, @file{/tmp}. 3259 3260In most cases the server will remove the temporary 3261directory when it is done, whether it finishes normally 3262or abnormally. However, there are a few cases in which 3263the server does not or cannot remove the temporary 3264directory, for example: 3265 3266@itemize @bullet 3267@item 3268If the server aborts due to an internal server error, 3269it may preserve the directory to aid in debugging 3270 3271@item 3272If the server is killed in a way that it has no way of 3273cleaning up (most notably, @samp{kill -KILL} on unix). 3274 3275@item 3276If the system shuts down without an orderly shutdown, 3277which tells the server to clean up. 3278@end itemize 3279 3280In cases such as this, you will need to manually remove 3281the @file{cvs-serv@var{pid}} directories. As long as 3282there is no server running with process identification 3283number @var{pid}, it is safe to do so. 3284 3285@c --------------------------------------------------------------------- 3286@node Starting a new project 3287@chapter Starting a project with CVS 3288@cindex Starting a project with CVS 3289@cindex Creating a project 3290 3291@comment --moduledb-- 3292Because renaming files and moving them between 3293directories is somewhat inconvenient, the first thing 3294you do when you start a new project should be to think 3295through your file organization. It is not impossible 3296to rename or move files, but it does increase the 3297potential for confusion and @sc{cvs} does have some 3298quirks particularly in the area of renaming 3299directories. @xref{Moving files}. 3300 3301What to do next depends on the situation at hand. 3302 3303@menu 3304* Setting up the files:: Getting the files into the repository 3305* Defining the module:: How to make a module of the files 3306@end menu 3307@c -- File permissions! 3308 3309@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3310@node Setting up the files 3311@section Setting up the files 3312 3313The first step is to create the files inside the repository. This can 3314be done in a couple of different ways. 3315 3316@c -- The contributed scripts 3317@menu 3318* From files:: This method is useful with old projects 3319 where files already exists. 3320* From other version control systems:: Old projects where you want to 3321 preserve history from another system. 3322* From scratch:: Creating a directory tree from scratch. 3323@end menu 3324 3325@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3326@node From files 3327@subsection Creating a directory tree from a number of files 3328@cindex Importing files 3329 3330When you begin using @sc{cvs}, you will probably already have several 3331projects that can be 3332put under @sc{cvs} control. In these cases the easiest way is to use the 3333@code{import} command. An example is probably the easiest way to 3334explain how to use it. If the files you want to install in 3335@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 3336repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 3337 3338@example 3339$ cd @var{wdir} 3340$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 3341@end example 3342 3343Unless you supply a log message with the @samp{-m} 3344flag, @sc{cvs} starts an editor and prompts for a 3345message. The string @samp{yoyo} is a @dfn{vendor tag}, 3346and @samp{start} is a @dfn{release tag}. They may fill 3347no purpose in this context, but since @sc{cvs} requires 3348them they must be present. @xref{Tracking sources}, for 3349more information about them. 3350 3351You can now verify that it worked, and remove your 3352original source directory. 3353@c FIXME: Need to say more about "verify that it 3354@c worked". What should the user look for in the output 3355@c from "diff -r"? 3356 3357@example 3358$ cd .. 3359$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 3360$ diff -r @var{wdir} yoyodyne/@var{rdir} 3361$ rm -r @var{wdir} 3362@end example 3363 3364@noindent 3365Erasing the original sources is a good idea, to make sure that you do 3366not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 3367Of course, it would be wise to make sure that you have 3368a backup of the sources before you remove them. 3369 3370The @code{checkout} command can either take a module 3371name as argument (as it has done in all previous 3372examples) or a path name relative to @code{$CVSROOT}, 3373as it did in the example above. 3374 3375It is a good idea to check that the permissions 3376@sc{cvs} sets on the directories inside @code{$CVSROOT} 3377are reasonable, and that they belong to the proper 3378groups. @xref{File permissions}. 3379 3380If some of the files you want to import are binary, you 3381may want to use the wrappers features to specify which 3382files are binary and which are not. @xref{Wrappers}. 3383 3384@c The node name is too long, but I am having trouble 3385@c thinking of something more concise. 3386@node From other version control systems 3387@subsection Creating Files From Other Version Control Systems 3388@cindex Importing files, from other version control systems 3389 3390If you have a project which you are maintaining with 3391another version control system, such as @sc{rcs}, you 3392may wish to put the files from that project into 3393@sc{cvs}, and preserve the revision history of the 3394files. 3395 3396@table @asis 3397@cindex RCS, importing files from 3398@item From RCS 3399If you have been using @sc{rcs}, find the @sc{rcs} 3400files---usually a file named @file{foo.c} will have its 3401@sc{rcs} file in @file{RCS/foo.c,v} (but it could be 3402other places; consult the @sc{rcs} documentation for 3403details). Then create the appropriate directories in 3404@sc{cvs} if they do not already exist. Then copy the 3405files into the appropriate directories in the @sc{cvs} 3406repository (the name in the repository must be the name 3407of the source file with @samp{,v} added; the files go 3408directly in the appropriate directory of the repository, 3409not in an @file{RCS} subdirectory). This is one of the 3410few times when it is a good idea to access the @sc{cvs} 3411repository directly, rather than using @sc{cvs} 3412commands. Then you are ready to check out a new 3413working directory. 3414@c Someday there probably should be a "cvs import -t 3415@c rcs" or some such. It could even create magic 3416@c branches. It could also do something about the case 3417@c where the RCS file had a (non-magic) "0" branch. 3418 3419The @sc{rcs} file should not be locked when you move it 3420into @sc{cvs}; if it is, @sc{cvs} will have trouble 3421letting you operate on it. 3422@c What is the easiest way to unlock your files if you 3423@c have them locked? Especially if you have a lot of them? 3424@c This is a CVS bug/misfeature; importing RCS files 3425@c should ignore whether they are locked and leave them in 3426@c an unlocked state. Yet another reason for a separate 3427@c "import RCS file" command. 3428 3429@c How many is "many"? Or do they just import RCS files? 3430@item From another version control system 3431Many version control systems have the ability to export 3432@sc{rcs} files in the standard format. If yours does, 3433export the @sc{rcs} files and then follow the above 3434instructions. 3435 3436Failing that, probably your best bet is to write a 3437script that will check out the files one revision at a 3438time using the command line interface to the other 3439system, and then check the revisions into @sc{cvs}. 3440The @file{sccs2rcs} script mentioned below may be a 3441useful example to follow. 3442 3443@cindex SCCS, importing files from 3444@item From SCCS 3445There is a script in the @file{contrib} directory of 3446the @sc{cvs} source distribution called @file{sccs2rcs} 3447which converts @sc{sccs} files to @sc{rcs} files. 3448Note: you must run it on a machine which has both 3449@sc{sccs} and @sc{rcs} installed, and like everything 3450else in contrib it is unsupported (your mileage may 3451vary). 3452 3453@cindex PVCS, importing files from 3454@item From PVCS 3455There is a script in the @file{contrib} directory of 3456the @sc{cvs} source distribution called @file{pvcs_to_rcs} 3457which converts @sc{pvcs} archives to @sc{rcs} files. 3458You must run it on a machine which has both 3459@sc{pvcs} and @sc{rcs} installed, and like everything 3460else in contrib it is unsupported (your mileage may 3461vary). See the comments in the script for details. 3462@end table 3463@c CMZ and/or PATCHY were systems that were used in the 3464@c high energy physics community (especially for 3465@c CERNLIB). CERN has replaced them with CVS, but the 3466@c CAR format seems to live on as a way to submit 3467@c changes. There is a program car2cvs which converts 3468@c but I'm not sure where one gets a copy. 3469@c Not sure it is worth mentioning here, since it would 3470@c appear to affect only one particular community. 3471@c Best page for more information is: 3472@c http://wwwcn1.cern.ch/asd/cvs/index.html 3473@c See also: 3474@c http://ecponion.cern.ch/ecpsa/cernlib.html 3475 3476@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3477@node From scratch 3478@subsection Creating a directory tree from scratch 3479 3480@c Also/instead should be documenting 3481@c $ cvs co -l . 3482@c $ mkdir tc 3483@c $ cvs add tc 3484@c $ cd tc 3485@c $ mkdir man 3486@c $ cvs add man 3487@c etc. 3488@c Using import to create the directories only is 3489@c probably a somewhat confusing concept. 3490For a new project, the easiest thing to do is probably 3491to create an empty directory structure, like this: 3492 3493@example 3494$ mkdir tc 3495$ mkdir tc/man 3496$ mkdir tc/testing 3497@end example 3498 3499After that, you use the @code{import} command to create 3500the corresponding (empty) directory structure inside 3501the repository: 3502 3503@example 3504$ cd tc 3505$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 3506@end example 3507 3508This will add yoyodyne/@var{dir} as a directory under 3509@code{$CVSROOT}. 3510 3511Use @code{checkout} to get the new project. Then, use @code{add} 3512to add files (and new directories) as needed. 3513 3514@example 3515$ cd .. 3516$ cvs co yoyodyne/@var{dir} 3517@end example 3518 3519Check that the permissions @sc{cvs} sets on the 3520directories inside @code{$CVSROOT} are reasonable. 3521 3522@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3523@node Defining the module 3524@section Defining the module 3525@cindex Defining a module 3526@cindex Editing the modules file 3527@cindex Module, defining 3528@cindex Modules file, changing 3529 3530The next step is to define the module in the 3531@file{modules} file. This is not strictly necessary, 3532but modules can be convenient in grouping together 3533related files and directories. 3534 3535In simple cases these steps are sufficient to define a module. 3536 3537@enumerate 3538@item 3539Get a working copy of the modules file. 3540 3541@example 3542$ cvs checkout CVSROOT/modules 3543$ cd CVSROOT 3544@end example 3545 3546@item 3547Edit the file and insert a line that defines the module. @xref{Intro 3548administrative files}, for an introduction. @xref{modules}, for a full 3549description of the modules file. You can use the 3550following line to define the module @samp{tc}: 3551 3552@example 3553tc yoyodyne/tc 3554@end example 3555 3556@item 3557Commit your changes to the modules file. 3558 3559@example 3560$ cvs commit -m "Added the tc module." modules 3561@end example 3562 3563@item 3564Release the modules module. 3565 3566@example 3567$ cd .. 3568$ cvs release -d CVSROOT 3569@end example 3570@end enumerate 3571 3572@c --------------------------------------------------------------------- 3573@node Revisions 3574@chapter Revisions 3575 3576For many uses of @sc{cvs}, one doesn't need to worry 3577too much about revision numbers; @sc{cvs} assigns 3578numbers such as @code{1.1}, @code{1.2}, and so on, and 3579that is all one needs to know. However, some people 3580prefer to have more knowledge and control concerning 3581how @sc{cvs} assigns revision numbers. 3582 3583If one wants to keep track of a set of revisions 3584involving more than one file, such as which revisions 3585went into a particular release, one uses a @dfn{tag}, 3586which is a symbolic revision which can be assigned to a 3587numeric revision in each file. 3588 3589@menu 3590* Revision numbers:: The meaning of a revision number 3591* Versions revisions releases:: Terminology used in this manual 3592* Assigning revisions:: Assigning revisions 3593* Tags:: Tags--Symbolic revisions 3594* Tagging the working directory:: The cvs tag command 3595* Tagging by date/tag:: The cvs rtag command 3596* Modifying tags:: Adding, renaming, and deleting tags 3597* Tagging add/remove:: Tags with adding and removing files 3598* Sticky tags:: Certain tags are persistent 3599@end menu 3600 3601@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3602@node Revision numbers 3603@section Revision numbers 3604@cindex Revision numbers 3605@cindex Revision tree 3606@cindex Linear development 3607@cindex Number, revision- 3608@cindex Decimal revision number 3609@cindex Branch number 3610@cindex Number, branch 3611 3612Each version of a file has a unique @dfn{revision 3613number}. Revision numbers look like @samp{1.1}, 3614@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 3615A revision number always has an even number of 3616period-separated decimal integers. By default revision 36171.1 is the first revision of a file. Each successive 3618revision is given a new number by increasing the 3619rightmost number by one. The following figure displays 3620a few revisions, with newer revisions to the right. 3621 3622@example 3623 +-----+ +-----+ +-----+ +-----+ +-----+ 3624 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 3625 +-----+ +-----+ +-----+ +-----+ +-----+ 3626@end example 3627 3628It is also possible to end up with numbers containing 3629more than one period, for example @samp{1.3.2.2}. Such 3630revisions represent revisions on branches 3631(@pxref{Branching and merging}); such revision numbers 3632are explained in detail in @ref{Branches and 3633revisions}. 3634 3635@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3636@node Versions revisions releases 3637@section Versions, revisions and releases 3638@cindex Revisions, versions and releases 3639@cindex Versions, revisions and releases 3640@cindex Releases, revisions and versions 3641 3642A file can have several versions, as described above. 3643Likewise, a software product can have several versions. 3644A software product is often given a version number such 3645as @samp{4.1.1}. 3646 3647Versions in the first sense are called @dfn{revisions} 3648in this document, and versions in the second sense are 3649called @dfn{releases}. To avoid confusion, the word 3650@dfn{version} is almost never used in this document. 3651 3652@node Assigning revisions 3653@section Assigning revisions 3654 3655@c We avoid the "major revision" terminology. It seems 3656@c like jargon. Hopefully "first number" is clear enough. 3657@c 3658@c Well, in the context of software release numbers, 3659@c "major" and "minor" release or version numbers are 3660@c documented in at least the GNU Coding Standards, but I'm 3661@c still not sure I find that a valid reason to apply the 3662@c terminology to RCS revision numbers. "First", "Second", 3663@c "subsequent", and so on is almost surely clearer, 3664@c especially to a novice reader. -DRP 3665By default, @sc{cvs} will assign numeric revisions by 3666leaving the first number the same and incrementing the 3667second number. For example, @code{1.1}, @code{1.2}, 3668@code{1.3}, etc. 3669 3670When adding a new file, the second number will always 3671be one and the first number will equal the highest 3672first number of any file in that directory. For 3673example, the current directory contains files whose 3674highest numbered revisions are @code{1.7}, @code{3.1}, 3675and @code{4.12}, then an added file will be given the 3676numeric revision @code{4.1}. 3677(When using client/server @sc{cvs}, 3678only files that are actually sent to the server are considered.) 3679 3680@c This is sort of redundant with something we said a 3681@c while ago. Somewhere we need a better way of 3682@c introducing how the first number can be anything 3683@c except "1", perhaps. Also I don't think this 3684@c presentation is clear on why we are discussing releases 3685@c and first numbers of numeric revisions in the same 3686@c breath. 3687Normally there is no reason to care 3688about the revision numbers---it is easier to treat them 3689as internal numbers that @sc{cvs} maintains, and tags 3690provide a better way to distinguish between things like 3691release 1 versus release 2 of your product 3692(@pxref{Tags}). However, if you want to set the 3693numeric revisions, the @samp{-r} option to @code{cvs 3694commit} can do that. The @samp{-r} option implies the 3695@samp{-f} option, in the sense that it causes the 3696files to be committed even if they are not modified. 3697 3698For example, to bring all your files up to 3699revision 3.0 (including those that haven't changed), 3700you might invoke: 3701 3702@example 3703$ cvs commit -r 3.0 3704@end example 3705 3706Note that the number you specify with @samp{-r} must be 3707larger than any existing revision number. That is, if 3708revision 3.0 exists, you cannot @samp{cvs commit 3709-r 1.3}. If you want to maintain several releases in 3710parallel, you need to use a branch (@pxref{Branching and merging}). 3711 3712@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3713@node Tags 3714@section Tags--Symbolic revisions 3715@cindex Tags 3716 3717The revision numbers live a life of their own. They 3718need not have anything at all to do with the release 3719numbers of your software product. Depending 3720on how you use @sc{cvs} the revision numbers might change several times 3721between two releases. As an example, some of the 3722source files that make up @sc{rcs} 5.6 have the following 3723revision numbers: 3724@cindex RCS revision numbers 3725 3726@example 3727ci.c 5.21 3728co.c 5.9 3729ident.c 5.3 3730rcs.c 5.12 3731rcsbase.h 5.11 3732rcsdiff.c 5.10 3733rcsedit.c 5.11 3734rcsfcmp.c 5.9 3735rcsgen.c 5.10 3736rcslex.c 5.11 3737rcsmap.c 5.2 3738rcsutil.c 5.10 3739@end example 3740 3741@cindex tag (subcommand), introduction 3742@cindex Tags, symbolic name 3743@cindex Symbolic name (tag) 3744@cindex Name, symbolic (tag) 3745@cindex HEAD, as reserved tag name 3746@cindex BASE, as reserved tag name 3747You can use the @code{tag} command to give a symbolic name to a 3748certain revision of a file. You can use the @samp{-v} flag to the 3749@code{status} command to see all tags that a file has, and 3750which revision numbers they represent. Tag names must 3751start with an uppercase or lowercase letter and can 3752contain uppercase and lowercase letters, digits, 3753@samp{-}, and @samp{_}. The two tag names @code{BASE} 3754and @code{HEAD} are reserved for use by @sc{cvs}. It 3755is expected that future names which are special to 3756@sc{cvs} will be specially named, for example by 3757starting with @samp{.}, rather than being named analogously to 3758@code{BASE} and @code{HEAD}, to avoid conflicts with 3759actual tag names. 3760@c Including a character such as % or = has also been 3761@c suggested as the naming convention for future 3762@c special tag names. Starting with . is nice because 3763@c that is not a legal tag name as far as RCS is concerned. 3764@c FIXME: CVS actually accepts quite a few characters 3765@c in tag names, not just the ones documented above 3766@c (see RCS_check_tag). RCS 3767@c defines legitimate tag names by listing illegal 3768@c characters rather than legal ones. CVS is said to lose its 3769@c mind if you try to use "/" (try making such a tag sticky 3770@c and using "cvs status" client/server--see remote 3771@c protocol format for entries line for probable cause). 3772@c TODO: The testsuite 3773@c should test for whatever are documented above as 3774@c officially-OK tag names, and CVS should at least reject 3775@c characters that won't work, like "/". 3776 3777You'll want to choose some convention for naming tags, 3778based on information such as the name of the program 3779and the version number of the release. For example, 3780one might take the name of the program, immediately 3781followed by the version number with @samp{.} changed to 3782@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 3783@code{cvs1-9}. If you choose a consistent convention, 3784then you won't constantly be guessing whether a tag is 3785@code{cvs-1-9} or @code{cvs1_9} or what. You might 3786even want to consider enforcing your convention in the 3787@file{taginfo} file (@pxref{taginfo}). 3788@c Might be nice to say more about using taginfo this 3789@c way, like giving an example, or pointing out any particular 3790@c issues which arise. 3791 3792@cindex Adding a tag 3793@cindex Tags, example 3794The following example shows how you can add a tag to a 3795file. The commands must be issued inside your working 3796directory. That is, you should issue the 3797command in the directory where @file{backend.c} 3798resides. 3799 3800@example 3801$ cvs tag rel-0-4 backend.c 3802T backend.c 3803$ cvs status -v backend.c 3804=================================================================== 3805File: backend.c Status: Up-to-date 3806 3807 Version: 1.4 Tue Dec 1 14:39:01 1992 3808 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 3809 Sticky Tag: (none) 3810 Sticky Date: (none) 3811 Sticky Options: (none) 3812 3813 Existing Tags: 3814 rel-0-4 (revision: 1.4) 3815 3816@end example 3817 3818For a complete summary of the syntax of @code{cvs tag}, 3819including the various options, see @ref{Invoking CVS}. 3820 3821There is seldom reason to tag a file in isolation. A more common use is 3822to tag all the files that constitute a module with the same tag at 3823strategic points in the development life-cycle, such as when a release 3824is made. 3825 3826@example 3827$ cvs tag rel-1-0 . 3828cvs tag: Tagging . 3829T Makefile 3830T backend.c 3831T driver.c 3832T frontend.c 3833T parser.c 3834@end example 3835 3836@noindent 3837(When you give @sc{cvs} a directory as argument, it generally applies the 3838operation to all the files in that directory, and (recursively), to any 3839subdirectories that it may contain. @xref{Recursive behavior}.) 3840 3841@cindex Retrieving an old revision using tags 3842@cindex Tags, retrieving old revisions 3843The @code{checkout} command has a flag, @samp{-r}, that lets you check out 3844a certain revision of a module. This flag makes it easy to 3845retrieve the sources that make up release 1.0 of the module @samp{tc} at 3846any time in the future: 3847 3848@example 3849$ cvs checkout -r rel-1-0 tc 3850@end example 3851 3852@noindent 3853This is useful, for instance, if someone claims that there is a bug in 3854that release, but you cannot find the bug in the current working copy. 3855 3856You can also check out a module as it was on any branch at any given date. 3857@xref{checkout options}. When specifying @samp{-r} or @samp{-D} to 3858any of these commands, you will need beware of sticky 3859tags; see @ref{Sticky tags}. 3860 3861When you tag more than one file with the same tag you 3862can think about the tag as "a curve drawn through a 3863matrix of filename vs. revision number." Say we have 5 3864files with the following revisions: 3865 3866@example 3867@group 3868 file1 file2 file3 file4 file5 3869 3870 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 3871 1.2*- 1.2 1.2 -1.2*- 3872 1.3 \- 1.3*- 1.3 / 1.3 3873 1.4 \ 1.4 / 1.4 3874 \-1.5*- 1.5 3875 1.6 3876@end group 3877@end example 3878 3879At some time in the past, the @code{*} versions were tagged. 3880You can think of the tag as a handle attached to the curve 3881drawn through the tagged revisions. When you pull on 3882the handle, you get all the tagged revisions. Another 3883way to look at it is that you "sight" through a set of 3884revisions that is "flat" along the tagged revisions, 3885like this: 3886 3887@example 3888@group 3889 file1 file2 file3 file4 file5 3890 3891 1.1 3892 1.2 3893 1.1 1.3 _ 3894 1.1 1.2 1.4 1.1 / 3895 1.2*----1.3*----1.5*----1.2*----1.1* (--- <--- Look here 3896 1.3 1.6 1.3 \_ 3897 1.4 1.4 3898 1.5 3899@end group 3900@end example 3901 3902@node Tagging the working directory 3903@section Specifying what to tag from the working directory 3904 3905@cindex tag (subcommand) 3906The example in the previous section demonstrates one of 3907the most common ways to choose which revisions to tag. 3908Namely, running the @code{cvs tag} command without 3909arguments causes @sc{cvs} to select the revisions which 3910are checked out in the current working directory. For 3911example, if the copy of @file{backend.c} in working 3912directory was checked out from revision 1.4, then 3913@sc{cvs} will tag revision 1.4. Note that the tag is 3914applied immediately to revision 1.4 in the repository; 3915tagging is not like modifying a file, or other 3916operations in which one first modifies the working 3917directory and then runs @code{cvs commit} to transfer 3918that modification to the repository. 3919 3920One potentially surprising aspect of the fact that 3921@code{cvs tag} operates on the repository is that you 3922are tagging the checked-in revisions, which may differ 3923from locally modified files in your working directory. 3924If you want to avoid doing this by mistake, specify the 3925@samp{-c} option to @code{cvs tag}. If there are any 3926locally modified files, @sc{cvs} will abort with an 3927error before it tags any files: 3928 3929@example 3930$ cvs tag -c rel-0-4 3931cvs tag: backend.c is locally modified 3932cvs [tag aborted]: correct the above errors first! 3933@end example 3934 3935@node Tagging by date/tag 3936@section Specifying what to tag by date or revision 3937@cindex rtag (subcommand) 3938 3939The @code{cvs rtag} command tags the repository as of a 3940certain date or time (or can be used to tag the latest 3941revision). @code{rtag} works directly on the 3942repository contents (it requires no prior checkout and 3943does not look for a working directory). 3944 3945The following options specify which date or revision to 3946tag. See @ref{Common options}, for a complete 3947description of them. 3948 3949@table @code 3950@item -D @var{date} 3951Tag the most recent revision no later than @var{date}. 3952 3953@item -f 3954Only useful with the @samp{-D} or @samp{-r} 3955flags. If no matching revision is found, use the most 3956recent revision (instead of ignoring the file). 3957 3958@item -r @var{tag}[:@var{date}] 3959Tag the revision already tagged with @var{tag} or, when @var{date} is specified 3960and @var{tag} is a branch tag, the version from the branch @var{tag} as it 3961existed on @var{date}. See @ref{Common options}. 3962@end table 3963 3964The @code{cvs tag} command also allows one to specify 3965files by revision or date, using the same @samp{-r}, 3966@samp{-D}, and @samp{-f} options. However, this 3967feature is probably not what you want. The reason is 3968that @code{cvs tag} chooses which files to tag based on 3969the files that exist in the working directory, rather 3970than the files which existed as of the given tag/date. 3971Therefore, you are generally better off using @code{cvs 3972rtag}. The exceptions might be cases like: 3973 3974@example 3975cvs tag -r 1.4 stable backend.c 3976@end example 3977 3978@node Modifying tags 3979@section Deleting, moving, and renaming tags 3980 3981@c Also see: 3982@c "How do I move or rename a magic branch tag?" 3983@c in the FAQ (I think the issues it talks about still 3984@c apply, but this could use some sanity.sh work). 3985 3986Normally one does not modify tags. They exist in order 3987to record the history of the repository and so deleting 3988them or changing their meaning would, generally, not be 3989what you want. 3990 3991However, there might be cases in which one uses a tag 3992temporarily or accidentally puts one in the wrong 3993place. Therefore, one might delete, move, or rename a 3994tag. 3995 3996@noindent 3997@strong{WARNING: the commands in this section are 3998dangerous; they permanently discard historical 3999information and it can be difficult or impossible to 4000recover from errors. If you are a @sc{cvs} 4001administrator, you may consider restricting these 4002commands with the @file{taginfo} file (@pxref{taginfo}).} 4003 4004@cindex Deleting tags 4005@cindex Deleting branch tags 4006@cindex Removing tags 4007@cindex Removing branch tags 4008@cindex Tags, deleting 4009@cindex Branch tags, deleting 4010To delete a tag, specify the @samp{-d} option to either 4011@code{cvs tag} or @code{cvs rtag}. For example: 4012 4013@example 4014cvs rtag -d rel-0-4 tc 4015@end example 4016 4017@noindent 4018deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 4019In the event that branch tags are encountered within the repository 4020with the given name, a warning message will be issued and the branch 4021tag will not be deleted. If you are absolutely certain you know what 4022you are doing, the @code{-B} option may be specified to allow deletion 4023of branch tags. In that case, any non-branch tags encountered will 4024trigger warnings and will not be deleted. 4025 4026@noindent 4027@strong{WARNING: Moving branch tags is very dangerous! If you think 4028you need the @code{-B} option, think again and ask your @sc{cvs} 4029administrator about it (if that isn't you). There is almost certainly 4030another way to accomplish what you want to accomplish.} 4031 4032@cindex Moving tags 4033@cindex Moving branch tags 4034@cindex Tags, moving 4035@cindex Branch tags, moving 4036When we say @dfn{move} a tag, we mean to make the same 4037name point to different revisions. For example, the 4038@code{stable} tag may currently point to revision 1.4 4039of @file{backend.c} and perhaps we want to make it 4040point to revision 1.6. To move a non-branch tag, specify the 4041@samp{-F} option to either @code{cvs tag} or @code{cvs 4042rtag}. For example, the task just mentioned might be 4043accomplished as: 4044 4045@example 4046cvs tag -r 1.6 -F stable backend.c 4047@end example 4048 4049@noindent 4050If any branch tags are encountered in the repository 4051with the given name, a warning is issued and the branch 4052tag is not disturbed. If you are absolutely certain you 4053wish to move the branch tag, the @code{-B} option may be specified. 4054In that case, non-branch tags encountered with the given 4055name are ignored with a warning message. 4056 4057@noindent 4058@strong{WARNING: Moving branch tags is very dangerous! If you think you 4059need the @code{-B} option, think again and ask your @sc{cvs} 4060administrator about it (if that isn't you). There is almost certainly 4061another way to accomplish what you want to accomplish.} 4062 4063@cindex Renaming tags 4064@cindex Tags, renaming 4065When we say @dfn{rename} a tag, we mean to make a 4066different name point to the same revisions as the old 4067tag. For example, one may have misspelled the tag name 4068and want to correct it (hopefully before others are 4069relying on the old spelling). To rename a tag, first 4070create a new tag using the @samp{-r} option to 4071@code{cvs rtag}, and then delete the old name. (Caution: 4072this method will not work with branch tags.) 4073This leaves the new tag on exactly the 4074same files as the old tag. For example: 4075 4076@example 4077cvs rtag -r old-name-0-4 rel-0-4 tc 4078cvs rtag -d old-name-0-4 tc 4079@end example 4080 4081@node Tagging add/remove 4082@section Tagging and adding and removing files 4083 4084The subject of exactly how tagging interacts with 4085adding and removing files is somewhat obscure; for the 4086most part @sc{cvs} will keep track of whether files 4087exist or not without too much fussing. By default, 4088tags are applied to only files which have a revision 4089corresponding to what is being tagged. Files which did 4090not exist yet, or which were already removed, simply 4091omit the tag, and @sc{cvs} knows to treat the absence 4092of a tag as meaning that the file didn't exist as of 4093that tag. 4094 4095However, this can lose a small amount of information. 4096For example, suppose a file was added and then removed. 4097Then, if the tag is missing for that file, there is no 4098way to know whether the tag refers to the time before 4099the file was added, or the time after it was removed. 4100If you specify the @samp{-r} option to @code{cvs rtag}, 4101then @sc{cvs} tags the files which have been removed, 4102and thereby avoids this problem. For example, one 4103might specify @code{-r HEAD} to tag the head. 4104 4105On the subject of adding and removing files, the 4106@code{cvs rtag} command has a @samp{-a} option which 4107means to clear the tag from removed files that would 4108not otherwise be tagged. For example, one might 4109specify this option in conjunction with @samp{-F} when 4110moving a tag. If one moved a tag without @samp{-a}, 4111then the tag in the removed files might still refer to 4112the old revision, rather than reflecting the fact that 4113the file had been removed. I don't think this is 4114necessary if @samp{-r} is specified, as noted above. 4115 4116@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4117@node Sticky tags 4118@section Sticky tags 4119@cindex Sticky tags 4120@cindex Tags, sticky 4121 4122@c A somewhat related issue is per-directory sticky 4123@c tags (see comment at CVS/Tag in node Working 4124@c directory storage); we probably want to say 4125@c something like "you can set a sticky tag for only 4126@c some files, but you don't want to" or some such. 4127 4128Sometimes a working copy's revision has extra data 4129associated with it, for example it might be on a branch 4130(@pxref{Branching and merging}), or restricted to 4131versions prior to a certain date by @samp{checkout -D} 4132or @samp{update -D}. Because this data persists -- 4133that is, it applies to subsequent commands in the 4134working copy -- we refer to it as @dfn{sticky}. 4135 4136Most of the time, stickiness is an obscure aspect of 4137@sc{cvs} that you don't need to think about. However, 4138even if you don't want to use the feature, you may need 4139to know @emph{something} about sticky tags (for 4140example, how to avoid them!). 4141 4142You can use the @code{status} command to see if any 4143sticky tags or dates are set: 4144 4145@example 4146$ cvs status driver.c 4147=================================================================== 4148File: driver.c Status: Up-to-date 4149 4150 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 4151 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 4152 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4153 Sticky Date: (none) 4154 Sticky Options: (none) 4155 4156@end example 4157 4158@cindex Resetting sticky tags 4159@cindex Sticky tags, resetting 4160@cindex Deleting sticky tags 4161The sticky tags will remain on your working files until 4162you delete them with @samp{cvs update -A}. The 4163@samp{-A} option merges local changes into the version of the 4164file from the head of the trunk, removing any sticky tags, 4165dates, or options. See @ref{update} for more on the operation 4166of @code{cvs update}. 4167 4168@cindex Sticky date 4169The most common use of sticky tags is to identify which 4170branch one is working on, as described in 4171@ref{Accessing branches}. However, non-branch 4172sticky tags have uses as well. For example, 4173suppose that you want to avoid updating your working 4174directory, to isolate yourself from possibly 4175destabilizing changes other people are making. You 4176can, of course, just refrain from running @code{cvs 4177update}. But if you want to avoid updating only a 4178portion of a larger tree, then sticky tags can help. 4179If you check out a certain revision (such as 1.4) it 4180will become sticky. Subsequent @code{cvs update} 4181commands will 4182not retrieve the latest revision until you reset the 4183tag with @code{cvs update -A}. Likewise, use of the 4184@samp{-D} option to @code{update} or @code{checkout} 4185sets a @dfn{sticky date}, which, similarly, causes that 4186date to be used for future retrievals. 4187 4188People often want to retrieve an old version of 4189a file without setting a sticky tag. This can 4190be done with the @samp{-p} option to @code{checkout} or 4191@code{update}, which sends the contents of the file to 4192standard output. For example: 4193@example 4194$ cvs update -p -r 1.1 file1 >file1 4195=================================================================== 4196Checking out file1 4197RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 4198VERS: 1.1 4199*************** 4200$ 4201@end example 4202 4203However, this isn't the easiest way, if you are asking 4204how to undo a previous checkin (in this example, put 4205@file{file1} back to the way it was as of revision 42061.1). In that case you are better off using the 4207@samp{-j} option to @code{update}; for further 4208discussion see @ref{Merging two revisions}. 4209 4210@c --------------------------------------------------------------------- 4211@node Branching and merging 4212@chapter Branching and merging 4213@cindex Branching 4214@cindex Merging 4215@cindex Copying changes 4216@cindex Main trunk and branches 4217@cindex Revision tree, making branches 4218@cindex Branches, copying changes between 4219@cindex Changes, copying between branches 4220@cindex Modifications, copying between branches 4221 4222@sc{cvs} allows you to isolate changes onto a separate 4223line of development, known as a @dfn{branch}. When you 4224change files on a branch, those changes do not appear 4225on the main trunk or other branches. 4226 4227Later you can move changes from one branch to another 4228branch (or the main trunk) by @dfn{merging}. Merging 4229involves first running @code{cvs update -j}, to merge 4230the changes into the working directory. 4231You can then commit that revision, and thus effectively 4232copy the changes onto another branch. 4233 4234@menu 4235* Branches motivation:: What branches are good for 4236* Creating a branch:: Creating a branch 4237* Accessing branches:: Checking out and updating branches 4238* Branches and revisions:: Branches are reflected in revision numbers 4239* Magic branch numbers:: Magic branch numbers 4240* Merging a branch:: Merging an entire branch 4241* Merging more than once:: Merging from a branch several times 4242* Merging two revisions:: Merging differences between two revisions 4243* Merging adds and removals:: What if files are added or removed? 4244* Merging and keywords:: Avoiding conflicts due to keyword substitution 4245@end menu 4246 4247@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4248@node Branches motivation 4249@section What branches are good for 4250@cindex Branches motivation 4251@cindex What branches are good for 4252@cindex Motivation for branches 4253 4254@c FIXME: this node mentions one way to use branches, 4255@c but it is by no means the only way. For example, 4256@c the technique of committing a new feature on a branch, 4257@c until it is ready for the main trunk. The whole 4258@c thing is generally speaking more akin to the 4259@c "Revision management" node although it isn't clear to 4260@c me whether policy matters should be centralized or 4261@c distributed throughout the relevant sections. 4262Suppose that release 1.0 of tc has been made. You are continuing to 4263develop tc, planning to create release 1.1 in a couple of months. After a 4264while your customers start to complain about a fatal bug. You check 4265out release 1.0 (@pxref{Tags}) and find the bug 4266(which turns out to have a trivial fix). However, the current revision 4267of the sources are in a state of flux and are not expected to be stable 4268for at least another month. There is no way to make a 4269bug fix release based on the newest sources. 4270 4271The thing to do in a situation like this is to create a @dfn{branch} on 4272the revision trees for all the files that make up 4273release 1.0 of tc. You can then make 4274modifications to the branch without disturbing the main trunk. When the 4275modifications are finished you can elect to either incorporate them on 4276the main trunk, or leave them on the branch. 4277 4278@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4279@node Creating a branch 4280@section Creating a branch 4281@cindex Creating a branch 4282@cindex Branch, creating a 4283@cindex tag (subcommand), creating a branch using 4284@cindex rtag (subcommand), creating a branch using 4285 4286You can create a branch with @code{tag -b}; for 4287example, assuming you're in a working copy: 4288 4289@example 4290$ cvs tag -b rel-1-0-patches 4291@end example 4292 4293@c FIXME: we should be more explicit about the value of 4294@c having a tag on the branchpoint. For example 4295@c "cvs tag rel-1-0-patches-branchpoint" before 4296@c the "cvs tag -b". This points out that 4297@c rel-1-0-patches is a pretty awkward name for 4298@c this example (more so than for the rtag example 4299@c below). 4300 4301This splits off a branch based on the current revisions 4302in the working copy, assigning that branch the name 4303@samp{rel-1-0-patches}. 4304 4305It is important to understand that branches get created 4306in the repository, not in the working copy. Creating a 4307branch based on current revisions, as the above example 4308does, will @emph{not} automatically switch the working 4309copy to be on the new branch. For information on how 4310to do that, see @ref{Accessing branches}. 4311 4312You can also create a branch without reference to any 4313working copy, by using @code{rtag}: 4314 4315@example 4316$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 4317@end example 4318 4319@samp{-r rel-1-0} says that this branch should be 4320rooted at the revision that 4321corresponds to the tag @samp{rel-1-0}. It need not 4322be the most recent revision -- it's often useful to 4323split a branch off an old revision (for example, when 4324fixing a bug in a past release otherwise known to be 4325stable). 4326 4327As with @samp{tag}, the @samp{-b} flag tells 4328@code{rtag} to create a branch (rather than just a 4329symbolic revision name). Note that the numeric 4330revision number that matches @samp{rel-1-0} will 4331probably be different from file to file. 4332 4333So, the full effect of the command is to create a new 4334branch -- named @samp{rel-1-0-patches} -- in module 4335@samp{tc}, rooted in the revision tree at the point tagged 4336by @samp{rel-1-0}. 4337 4338@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4339@node Accessing branches 4340@section Accessing branches 4341@cindex Check out a branch 4342@cindex Retrieve a branch 4343@cindex Access a branch 4344@cindex Identifying a branch 4345@cindex Branch, check out 4346@cindex Branch, retrieving 4347@cindex Branch, accessing 4348@cindex Branch, identifying 4349 4350You can retrieve a branch in one of two ways: by 4351checking it out fresh from the repository, or by 4352switching an existing working copy over to the branch. 4353 4354To check out a branch from the repository, invoke 4355@samp{checkout} with the @samp{-r} flag, followed by 4356the tag name of the branch (@pxref{Creating a branch}): 4357 4358@example 4359$ cvs checkout -r rel-1-0-patches tc 4360@end example 4361 4362Or, if you already have a working copy, you can switch 4363it to a given branch with @samp{update -r}: 4364 4365@example 4366$ cvs update -r rel-1-0-patches tc 4367@end example 4368 4369@noindent 4370or equivalently: 4371 4372@example 4373$ cd tc 4374$ cvs update -r rel-1-0-patches 4375@end example 4376 4377It does not matter if the working copy was originally 4378on the main trunk or on some other branch -- the above 4379command will switch it to the named branch. And 4380similarly to a regular @samp{update} command, 4381@samp{update -r} merges any changes you have made, 4382notifying you of conflicts where they occur. 4383 4384Once you have a working copy tied to a particular 4385branch, it remains there until you tell it otherwise. 4386This means that changes checked in from the working 4387copy will add new revisions on that branch, while 4388leaving the main trunk and other branches unaffected. 4389 4390@cindex Branches, sticky 4391To find out what branch a working copy is on, you can 4392use the @samp{status} command. In its output, look for 4393the field named @samp{Sticky tag} (@pxref{Sticky tags}) 4394-- that's @sc{cvs}'s way of telling you the branch, if 4395any, of the current working files: 4396 4397@example 4398$ cvs status -v driver.c backend.c 4399=================================================================== 4400File: driver.c Status: Up-to-date 4401 4402 Version: 1.7 Sat Dec 5 18:25:54 1992 4403 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 4404 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4405 Sticky Date: (none) 4406 Sticky Options: (none) 4407 4408 Existing Tags: 4409 rel-1-0-patches (branch: 1.7.2) 4410 rel-1-0 (revision: 1.7) 4411 4412=================================================================== 4413File: backend.c Status: Up-to-date 4414 4415 Version: 1.4 Tue Dec 1 14:39:01 1992 4416 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 4417 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 4418 Sticky Date: (none) 4419 Sticky Options: (none) 4420 4421 Existing Tags: 4422 rel-1-0-patches (branch: 1.4.2) 4423 rel-1-0 (revision: 1.4) 4424 rel-0-4 (revision: 1.4) 4425 4426@end example 4427 4428Don't be confused by the fact that the branch numbers 4429for each file are different (@samp{1.7.2} and 4430@samp{1.4.2} respectively). The branch tag is the 4431same, @samp{rel-1-0-patches}, and the files are 4432indeed on the same branch. The numbers simply reflect 4433the point in each file's revision history at which the 4434branch was made. In the above example, one can deduce 4435that @samp{driver.c} had been through more changes than 4436@samp{backend.c} before this branch was created. 4437 4438See @ref{Branches and revisions} for details about how 4439branch numbers are constructed. 4440 4441@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4442@node Branches and revisions 4443@section Branches and revisions 4444@cindex Branch number 4445@cindex Number, branch 4446@cindex Revision numbers (branches) 4447 4448Ordinarily, a file's revision history is a linear 4449series of increments (@pxref{Revision numbers}): 4450 4451@example 4452 +-----+ +-----+ +-----+ +-----+ +-----+ 4453 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 4454 +-----+ +-----+ +-----+ +-----+ +-----+ 4455@end example 4456 4457However, @sc{cvs} is not limited to linear development. The 4458@dfn{revision tree} can be split into @dfn{branches}, 4459where each branch is a self-maintained line of 4460development. Changes made on one branch can easily be 4461moved back to the main trunk. 4462 4463Each branch has a @dfn{branch number}, consisting of an 4464odd number of period-separated decimal integers. The 4465branch number is created by appending an integer to the 4466revision number where the corresponding branch forked 4467off. Having branch numbers allows more than one branch 4468to be forked off from a certain revision. 4469 4470@need 3500 4471All revisions on a branch have revision numbers formed 4472by appending an ordinal number to the branch number. 4473The following figure illustrates branching with an 4474example. 4475 4476@example 4477@c This example used to have a 1.2.2.4 revision, which 4478@c might help clarify that development can continue on 4479@c 1.2.2. Might be worth reinstating if it can be done 4480@c without overfull hboxes. 4481@group 4482 +-------------+ 4483 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 4484 / +-------------+ 4485 / 4486 / 4487 +---------+ +---------+ +---------+ 4488Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4489 / +---------+ +---------+ +---------+ 4490 / 4491 / 4492+-----+ +-----+ +-----+ +-----+ +-----+ 4493! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4494+-----+ +-----+ +-----+ +-----+ +-----+ 4495 ! 4496 ! 4497 ! +---------+ +---------+ +---------+ 4498Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 4499 +---------+ +---------+ +---------+ 4500 4501@end group 4502@end example 4503 4504@c -- However, at least for me the figure is not enough. I suggest more 4505@c -- text to accompany it. "A picture is worth a thousand words", so you 4506@c -- have to make sure the reader notices the couple of hundred words 4507@c -- *you* had in mind more than the others! 4508 4509@c -- Why an even number of segments? This section implies that this is 4510@c -- how the main trunk is distinguished from branch roots, but you never 4511@c -- explicitly say that this is the purpose of the [by itself rather 4512@c -- surprising] restriction to an even number of segments. 4513 4514The exact details of how the branch number is 4515constructed is not something you normally need to be 4516concerned about, but here is how it works: When 4517@sc{cvs} creates a branch number it picks the first 4518unused even integer, starting with 2. So when you want 4519to create a branch from revision 6.4 it will be 4520numbered 6.4.2. All branch numbers ending in a zero 4521(such as 6.4.0) are used internally by @sc{cvs} 4522(@pxref{Magic branch numbers}). The branch 1.1.1 has a 4523special meaning. @xref{Tracking sources}. 4524 4525@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4526@node Magic branch numbers 4527@section Magic branch numbers 4528 4529@c Want xref to here from "log"? 4530 4531This section describes a @sc{cvs} feature called 4532@dfn{magic branches}. For most purposes, you need not 4533worry about magic branches; @sc{cvs} handles them for 4534you. However, they are visible to you in certain 4535circumstances, so it may be useful to have some idea of 4536how it works. 4537 4538Externally, branch numbers consist of an odd number of 4539dot-separated decimal integers. @xref{Revision 4540numbers}. That is not the whole truth, however. For 4541efficiency reasons @sc{cvs} sometimes inserts an extra 0 4542in the second rightmost position (1.2.4 becomes 45431.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 4544on). 4545 4546@sc{cvs} does a pretty good job at hiding these so 4547called magic branches, but in a few places the hiding 4548is incomplete: 4549 4550@itemize @bullet 4551@ignore 4552@c This is in ignore as I'm taking their word for it, 4553@c that this was fixed 4554@c a long time ago. But before deleting this 4555@c entirely, I'd rather verify it (and add a test 4556@c case to the testsuite). 4557@item 4558The magic branch can appear in the output from 4559@code{cvs status} in vanilla @sc{cvs} 1.3. This is 4560fixed in @sc{cvs} 1.3-s2. 4561 4562@end ignore 4563@item 4564The magic branch number appears in the output from 4565@code{cvs log}. 4566@c What output should appear instead? 4567 4568@item 4569You cannot specify a symbolic branch name to @code{cvs 4570admin}. 4571 4572@end itemize 4573 4574@c Can CVS do this automatically the first time 4575@c you check something in to that branch? Should 4576@c it? 4577You can use the @code{admin} command to reassign a 4578symbolic name to a branch the way @sc{rcs} expects it 4579to be. If @code{R4patches} is assigned to the branch 45801.4.2 (magic branch number 1.4.0.2) in file 4581@file{numbers.c} you can do this: 4582 4583@example 4584$ cvs admin -NR4patches:1.4.2 numbers.c 4585@end example 4586 4587It only works if at least one revision is already 4588committed on the branch. Be very careful so that you 4589do not assign the tag to the wrong number. (There is 4590no way to see how the tag was assigned yesterday). 4591 4592@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4593@node Merging a branch 4594@section Merging an entire branch 4595@cindex Merging a branch 4596@cindex -j (merging branches) 4597 4598You can merge changes made on a branch into your working copy by giving 4599the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 4600@samp{-j @var{branchname}} option it merges the changes made between the 4601greatest common ancestor (GCA) of the branch and the destination revision (in 4602the simple case below the GCA is the point where the branch forked) and the 4603newest revision on that branch into your working copy. 4604 4605@cindex Join 4606The @samp{-j} stands for ``join''. 4607 4608@cindex Branch merge example 4609@cindex Example, branch merge 4610@cindex Merge, branch example 4611Consider this revision tree: 4612 4613@example 4614+-----+ +-----+ +-----+ +-----+ 4615! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 4616+-----+ +-----+ +-----+ +-----+ 4617 ! 4618 ! 4619 ! +---------+ +---------+ 4620Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4621 +---------+ +---------+ 4622@end example 4623 4624@noindent 4625The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 4626following example assumes that the module @samp{mod} contains only one 4627file, @file{m.c}. 4628 4629@example 4630$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 4631 4632$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 4633 # @r{i.e. the changes between revision 1.2} 4634 # @r{and 1.2.2.2, into your working copy} 4635 # @r{of the file.} 4636 4637$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 4638@end example 4639 4640A conflict can result from a merge operation. If that 4641happens, you should resolve it before committing the 4642new revision. @xref{Conflicts example}. 4643 4644If your source files contain keywords (@pxref{Keyword substitution}), 4645you might be getting more conflicts than strictly necessary. See 4646@ref{Merging and keywords}, for information on how to avoid this. 4647 4648The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 4649same effect as above could be achieved with this: 4650 4651@example 4652$ cvs checkout -j R1fix mod 4653$ cvs commit -m "Included R1fix" 4654@end example 4655 4656It should be noted that @code{update -j @var{tagname}} will also work but may 4657not produce the desired result. @xref{Merging adds and removals}, for more. 4658 4659@node Merging more than once 4660@section Merging from a branch several times 4661 4662Continuing our example, the revision tree now looks 4663like this: 4664 4665@example 4666+-----+ +-----+ +-----+ +-----+ +-----+ 4667! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4668+-----+ +-----+ +-----+ +-----+ +-----+ 4669 ! * 4670 ! * 4671 ! +---------+ +---------+ 4672Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4673 +---------+ +---------+ 4674@end example 4675 4676@noindent 4677where the starred line represents the merge from the 4678@samp{R1fix} branch to the main trunk, as just 4679discussed. 4680 4681Now suppose that development continues on the 4682@samp{R1fix} branch: 4683 4684@example 4685+-----+ +-----+ +-----+ +-----+ +-----+ 4686! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4687+-----+ +-----+ +-----+ +-----+ +-----+ 4688 ! * 4689 ! * 4690 ! +---------+ +---------+ +---------+ 4691Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4692 +---------+ +---------+ +---------+ 4693@end example 4694 4695@noindent 4696and then you want to merge those new changes onto the 4697main trunk. If you just use the @code{cvs update -j 4698R1fix m.c} command again, @sc{cvs} will attempt to 4699merge again the changes which you have already merged, 4700which can have undesirable side effects. 4701 4702So instead you need to specify that you only want to 4703merge the changes on the branch which have not yet been 4704merged into the trunk. To do that you specify two 4705@samp{-j} options, and @sc{cvs} merges the changes from 4706the first revision to the second revision. For 4707example, in this case the simplest way would be 4708 4709@example 4710cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 4711 # @r{head of the R1fix branch} 4712@end example 4713 4714The problem with this is that you need to specify the 47151.2.2.2 revision manually. A slightly better approach 4716might be to use the date the last merge was done: 4717 4718@example 4719cvs update -j R1fix:yesterday -j R1fix m.c 4720@end example 4721 4722Better yet, tag the R1fix branch after every merge into 4723the trunk, and then use that tag for subsequent merges: 4724 4725@example 4726cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 4727@end example 4728 4729@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4730@node Merging two revisions 4731@section Merging differences between any two revisions 4732@cindex Merging two revisions 4733@cindex Revisions, merging differences between 4734@cindex Differences, merging 4735 4736With two @samp{-j @var{revision}} flags, the @code{update} 4737(and @code{checkout}) command can merge the differences 4738between any two revisions into your working file. 4739 4740@cindex Undoing a change 4741@cindex Removing a change 4742@example 4743$ cvs update -j 1.5 -j 1.3 backend.c 4744@end example 4745 4746@noindent 4747will undo all changes made between revision 47481.3 and 1.5. Note the order of the revisions! 4749 4750If you try to use this option when operating on 4751multiple files, remember that the numeric revisions will 4752probably be very different between the various files. 4753You almost always use symbolic 4754tags rather than revision numbers when operating on 4755multiple files. 4756 4757@cindex Restoring old version of removed file 4758@cindex Resurrecting old version of dead file 4759Specifying two @samp{-j} options can also undo file 4760removals or additions. For example, suppose you have 4761a file 4762named @file{file1} which existed as revision 1.1, and 4763you then removed it (thus adding a dead revision 1.2). 4764Now suppose you want to add it again, with the same 4765contents it had previously. Here is how to do it: 4766 4767@example 4768$ cvs update -j 1.2 -j 1.1 file1 4769U file1 4770$ cvs commit -m test 4771Checking in file1; 4772/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 4773new revision: 1.3; previous revision: 1.2 4774done 4775$ 4776@end example 4777 4778@node Merging adds and removals 4779@section Merging can add or remove files 4780 4781If the changes which you are merging involve removing 4782or adding some files, @code{update -j} will reflect 4783such additions or removals. 4784 4785@c FIXME: This example needs a lot more explanation. 4786@c We also need other examples for some of the other 4787@c cases (not all--there are too many--as long as we present a 4788@c coherent general principle). 4789For example: 4790@example 4791cvs update -A 4792touch a b c 4793cvs add a b c ; cvs ci -m "added" a b c 4794cvs tag -b branchtag 4795cvs update -r branchtag 4796touch d ; cvs add d 4797rm a ; cvs rm a 4798cvs ci -m "added d, removed a" 4799cvs update -A 4800cvs update -jbranchtag 4801@end example 4802 4803After these commands are executed and a @samp{cvs commit} is done, 4804file @file{a} will be removed and file @file{d} added in the main branch. 4805@c (which was determined by trying it) 4806 4807Note that using a single static tag (@samp{-j @var{tagname}}) 4808rather than a dynamic tag (@samp{-j @var{branchname}}) to merge 4809changes from a branch will usually not remove files which were removed on the 4810branch since @sc{cvs} does not automatically add static tags to dead revisions. 4811The exception to this rule occurs when 4812a static tag has been attached to a dead revision manually. Use the branch tag 4813to merge all changes from the branch or use two static tags as merge endpoints 4814to be sure that all intended changes are propagated in the merge. 4815 4816@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4817@node Merging and keywords 4818@section Merging and keywords 4819@cindex Merging, and keyword substitution 4820@cindex Keyword substitution, and merging 4821@cindex -j (merging branches), and keyword substitution 4822@cindex -kk, to avoid conflicts during a merge 4823 4824If you merge files containing keywords (@pxref{Keyword 4825substitution}), you will normally get numerous 4826conflicts during the merge, because the keywords are 4827expanded differently in the revisions which you are 4828merging. 4829 4830Therefore, you will often want to specify the 4831@samp{-kk} (@pxref{Substitution modes}) switch to the 4832merge command line. By substituting just the name of 4833the keyword, not the expanded value of that keyword, 4834this option ensures that the revisions which you are 4835merging will be the same as each other, and avoid 4836spurious conflicts. 4837 4838For example, suppose you have a file like this: 4839 4840@example 4841 +---------+ 4842 _! 1.1.2.1 ! <- br1 4843 / +---------+ 4844 / 4845 / 4846+-----+ +-----+ 4847! 1.1 !----! 1.2 ! 4848+-----+ +-----+ 4849@end example 4850 4851@noindent 4852and your working directory is currently on the trunk 4853(revision 1.2). Then you might get the following 4854results from a merge: 4855 4856@example 4857$ cat file1 4858key $@splitrcskeyword{Revision}: 1.2 $ 4859. . . 4860$ cvs update -j br1 4861U file1 4862RCS file: /cvsroot/first-dir/file1,v 4863retrieving revision 1.1 4864retrieving revision 1.1.2.1 4865Merging differences between 1.1 and 1.1.2.1 into file1 4866rcsmerge: warning: conflicts during merge 4867$ cat file1 4868@asis{}<<<<<<< file1 4869key $@splitrcskeyword{Revision}: 1.2 $ 4870@asis{}======= 4871key $@splitrcskeyword{Revision}: 1.1.2.1 $ 4872@asis{}>>>>>>> 1.1.2.1 4873. . . 4874@end example 4875 4876What happened was that the merge tried to merge the 4877differences between 1.1 and 1.1.2.1 into your working 4878directory. So, since the keyword changed from 4879@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 4880@sc{cvs} tried to merge that change into your working 4881directory, which conflicted with the fact that your 4882working directory had contained @code{Revision: 1.2}. 4883 4884Here is what happens if you had used @samp{-kk}: 4885 4886@example 4887$ cat file1 4888key $@splitrcskeyword{Revision}: 1.2 $ 4889. . . 4890$ cvs update -kk -j br1 4891U file1 4892RCS file: /cvsroot/first-dir/file1,v 4893retrieving revision 1.1 4894retrieving revision 1.1.2.1 4895Merging differences between 1.1 and 1.1.2.1 into file1 4896$ cat file1 4897key $@splitrcskeyword{Revision}$ 4898. . . 4899@end example 4900 4901What is going on here is that revision 1.1 and 1.1.2.1 4902both expand as plain @code{Revision}, and therefore 4903merging the changes between them into the working 4904directory need not change anything. Therefore, there 4905is no conflict. 4906 4907@strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a 4908major problem with using @samp{-kk} on merges. Namely, @samp{-kk} 4909overrode any default keyword expansion mode set in the archive file in 4910the repository. This could, unfortunately for some users, cause data 4911corruption in binary files (with a default keyword expansion mode set 4912to @samp{-kb}). Therefore, when a repository contained binary files, 4913conflicts had to be dealt with manually rather than using @samp{-kk} in 4914a merge command.} 4915 4916In @sc{cvs} version 1.12.2 and later, the keyword expansion mode 4917provided on the command line to any @sc{cvs} command no longer 4918overrides the @samp{-kb} keyword expansion mode setting for binary 4919files, though it will still override other default keyword expansion 4920modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts 4921on lines containing RCS keywords, even when your repository contains 4922binary files. 4923 4924@c --------------------------------------------------------------------- 4925@node Recursive behavior 4926@chapter Recursive behavior 4927@cindex Recursive (directory descending) 4928@cindex Directory, descending 4929@cindex Descending directories 4930@cindex Subdirectories 4931 4932Almost all of the subcommands of @sc{cvs} work 4933recursively when you specify a directory as an 4934argument. For instance, consider this directory 4935structure: 4936 4937@example 4938 @code{$HOME} 4939 | 4940 +--@t{tc} 4941 | | 4942 +--@t{CVS} 4943 | (internal @sc{cvs} files) 4944 +--@t{Makefile} 4945 +--@t{backend.c} 4946 +--@t{driver.c} 4947 +--@t{frontend.c} 4948 +--@t{parser.c} 4949 +--@t{man} 4950 | | 4951 | +--@t{CVS} 4952 | | (internal @sc{cvs} files) 4953 | +--@t{tc.1} 4954 | 4955 +--@t{testing} 4956 | 4957 +--@t{CVS} 4958 | (internal @sc{cvs} files) 4959 +--@t{testpgm.t} 4960 +--@t{test2.t} 4961@end example 4962 4963@noindent 4964If @file{tc} is the current working directory, the 4965following is true: 4966 4967@itemize @bullet 4968@item 4969@samp{cvs update testing} is equivalent to 4970 4971@example 4972cvs update testing/testpgm.t testing/test2.t 4973@end example 4974 4975@item 4976@samp{cvs update testing man} updates all files in the 4977subdirectories 4978 4979@item 4980@samp{cvs update .} or just @samp{cvs update} updates 4981all files in the @code{tc} directory 4982@end itemize 4983 4984If no arguments are given to @code{update} it will 4985update all files in the current working directory and 4986all its subdirectories. In other words, @file{.} is a 4987default argument to @code{update}. This is also true 4988for most of the @sc{cvs} subcommands, not only the 4989@code{update} command. 4990 4991The recursive behavior of the @sc{cvs} subcommands can be 4992turned off with the @samp{-l} option. 4993Conversely, the @samp{-R} option can be used to force recursion if 4994@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 4995 4996@example 4997$ cvs update -l # @r{Don't update files in subdirectories} 4998@end example 4999 5000@c --------------------------------------------------------------------- 5001@node Adding and removing 5002@chapter Adding, removing, and renaming files and directories 5003 5004In the course of a project, one will often add new 5005files. Likewise with removing or renaming, or with 5006directories. The general concept to keep in mind in 5007all these cases is that instead of making an 5008irreversible change you want @sc{cvs} to record the 5009fact that a change has taken place, just as with 5010modifying an existing file. The exact mechanisms to do 5011this in @sc{cvs} vary depending on the situation. 5012 5013@menu 5014* Adding files:: Adding files 5015* Removing files:: Removing files 5016* Removing directories:: Removing directories 5017* Moving files:: Moving and renaming files 5018* Moving directories:: Moving and renaming directories 5019@end menu 5020 5021@node Adding files 5022@section Adding files to a directory 5023@cindex Adding files 5024 5025To add a new file to a directory, follow these steps. 5026 5027@itemize @bullet 5028@item 5029You must have a working copy of the directory. 5030@xref{Getting the source}. 5031 5032@item 5033Create the new file inside your working copy of the directory. 5034 5035@item 5036Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you 5037want to version control the file. If the file contains 5038binary data, specify @samp{-kb} (@pxref{Binary files}). 5039 5040@item 5041Use @samp{cvs commit @var{filename}} to actually check 5042in the file into the repository. Other developers 5043cannot see the file until you perform this step. 5044@end itemize 5045 5046You can also use the @code{add} command to add a new 5047directory. 5048@c FIXCVS and/or FIXME: Adding a directory doesn't 5049@c require the commit step. This probably can be 5050@c considered a CVS bug, but it is possible we should 5051@c warn people since this behavior probably won't be 5052@c changing right away. 5053 5054Unlike most other commands, the @code{add} command is 5055not recursive. You have to expcicitly name files and 5056directories that you wish to add to the repository. 5057However, each directory will need to be added 5058separately before you will be able to add new files 5059to those directories. 5060 5061@example 5062$ mkdir -p foo/bar 5063$ cp ~/myfile foo/bar/myfile 5064$ cvs add foo foo/bar 5065$ cvs add foo/bar/myfile 5066@end example 5067 5068@cindex add (subcommand) 5069@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 5070 5071Schedule @var{files} to be added to the repository. 5072The files or directories specified with @code{add} must 5073already exist in the current directory. To add a whole 5074new directory hierarchy to the source repository (for 5075example, files received from a third-party vendor), use 5076the @code{import} command instead. @xref{import}. 5077 5078The added files are not placed in the source repository 5079until you use @code{commit} to make the change 5080permanent. Doing an @code{add} on a file that was 5081removed with the @code{remove} command will undo the 5082effect of the @code{remove}, unless a @code{commit} 5083command intervened. @xref{Removing files}, for an 5084example. 5085 5086The @samp{-k} option specifies the default way that 5087this file will be checked out; for more information see 5088@ref{Substitution modes}. 5089 5090@c As noted in BUGS, -m is broken client/server (Nov 5091@c 96). Also see testsuite log2-* tests. 5092The @samp{-m} option specifies a description for the 5093file. This description appears in the history log (if 5094it is enabled, @pxref{history file}). It will also be 5095saved in the version history inside the repository when 5096the file is committed. The @code{log} command displays 5097this description. The description can be changed using 5098@samp{admin -t}. @xref{admin}. If you omit the 5099@samp{-m @var{description}} flag, an empty string will 5100be used. You will not be prompted for a description. 5101@end deffn 5102 5103For example, the following commands add the file 5104@file{backend.c} to the repository: 5105 5106@c This example used to specify 5107@c -m "Optimizer and code generation passes." 5108@c to the cvs add command, but that doesn't work 5109@c client/server (see log2 in sanity.sh). Should fix CVS, 5110@c but also seems strange to document things which 5111@c don't work... 5112@example 5113$ cvs add backend.c 5114$ cvs commit -m "Early version. Not yet compilable." backend.c 5115@end example 5116 5117When you add a file it is added only on the branch 5118which you are working on (@pxref{Branching and merging}). You can 5119later merge the additions to another branch if you want 5120(@pxref{Merging adds and removals}). 5121@c Should we mention that earlier versions of CVS 5122@c lacked this feature (1.3) or implemented it in a buggy 5123@c way (well, 1.8 had many bugs in cvs update -j)? 5124@c Should we mention the bug/limitation regarding a 5125@c file being a regular file on one branch and a directory 5126@c on another? 5127@c FIXME: This needs an example, or several, here or 5128@c elsewhere, for it to make much sense. 5129@c Somewhere we need to discuss the aspects of death 5130@c support which don't involve branching, I guess. 5131@c Like the ability to re-create a release from a tag. 5132 5133@c --------------------------------------------------------------------- 5134@node Removing files 5135@section Removing files 5136@cindex Removing files 5137@cindex Deleting files 5138 5139@c FIXME: this node wants to be split into several 5140@c smaller nodes. Could make these children of 5141@c "Adding and removing", probably (death support could 5142@c be its own section, for example, as could the 5143@c various bits about undoing mistakes in adding and 5144@c removing). 5145Directories change. New files are added, and old files 5146disappear. Still, you want to be able to retrieve an 5147exact copy of old releases. 5148 5149Here is what you can do to remove a file, 5150but remain able to retrieve old revisions: 5151 5152@itemize @bullet 5153@c FIXME: should probably be saying something about 5154@c having a working directory in the first place. 5155@item 5156Make sure that you have not made any uncommitted 5157modifications to the file. @xref{Viewing differences}, 5158for one way to do that. You can also use the 5159@code{status} or @code{update} command. If you remove 5160the file without committing your changes, you will of 5161course not be able to retrieve the file as it was 5162immediately before you deleted it. 5163 5164@item 5165Remove the file from your working copy of the directory. 5166You can for instance use @code{rm}. 5167 5168@item 5169Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that 5170you really want to delete the file. 5171 5172@item 5173Use @samp{cvs commit @var{filename}} to actually 5174perform the removal of the file from the repository. 5175@end itemize 5176 5177@c FIXME: Somehow this should be linked in with a more 5178@c general discussion of death support. I don't know 5179@c whether we want to use the term "death support" or 5180@c not (we can perhaps get by without it), but we do 5181@c need to discuss the "dead" state in "cvs log" and 5182@c related subjects. The current discussion is 5183@c scattered around, and not xref'd to each other. 5184@c FIXME: I think this paragraph wants to be moved 5185@c later down, at least after the first example. 5186When you commit the removal of the file, @sc{cvs} 5187records the fact that the file no longer exists. It is 5188possible for a file to exist on only some branches and 5189not on others, or to re-add another file with the same 5190name later. @sc{cvs} will correctly create or not create 5191the file, based on the @samp{-r} and @samp{-D} options 5192specified to @code{checkout} or @code{update}. 5193 5194@c FIXME: This style seems to clash with how we 5195@c document things in general. 5196@cindex Remove (subcommand) 5197@deffn Command {cvs remove} [options] files @dots{} 5198 5199Schedule file(s) to be removed from the repository 5200(files which have not already been removed from the 5201working directory are not processed). This command 5202does not actually remove the file from the repository 5203until you commit the removal. For a full list of 5204options, see @ref{Invoking CVS}. 5205@end deffn 5206 5207Here is an example of removing several files: 5208 5209@example 5210$ cd test 5211$ rm *.c 5212$ cvs remove 5213cvs remove: Removing . 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 5222As a convenience you can remove the file and @code{cvs 5223remove} it in one step, by specifying the @samp{-f} 5224option. For example, the above example could also be 5225done like this: 5226 5227@example 5228$ cd test 5229$ cvs remove -f *.c 5230cvs remove: scheduling a.c for removal 5231cvs remove: scheduling b.c for removal 5232cvs remove: use 'cvs commit' to remove these files permanently 5233$ cvs ci -m "Removed unneeded files" 5234cvs commit: Examining . 5235cvs commit: Committing . 5236@end example 5237 5238If you execute @code{remove} for a file, and then 5239change your mind before you commit, you can undo the 5240@code{remove} with an @code{add} command. 5241@ignore 5242@c is this worth saying or not? Somehow it seems 5243@c confusing to me. 5244Of course, 5245since you have removed your copy of file in the working 5246directory, @sc{cvs} does not necessarily bring back the 5247contents of the file from right before you executed 5248@code{remove}; instead it gets the file from the 5249repository again. 5250@end ignore 5251 5252@c FIXME: what if you change your mind after you commit 5253@c it? (answer is also "cvs add" but we don't say that...). 5254@c We need some index entries for thinks like "undoing 5255@c removal" too. 5256 5257@example 5258$ ls 5259CVS ja.h oj.c 5260$ rm oj.c 5261$ cvs remove oj.c 5262cvs remove: scheduling oj.c for removal 5263cvs remove: use 'cvs commit' to remove this file permanently 5264$ cvs add oj.c 5265U oj.c 5266cvs add: oj.c, version 1.1.1.1, resurrected 5267@end example 5268 5269If you realize your mistake before you run the 5270@code{remove} command you can use @code{update} to 5271resurrect the file: 5272 5273@example 5274$ rm oj.c 5275$ cvs update oj.c 5276cvs update: warning: oj.c was lost 5277U oj.c 5278@end example 5279 5280When you remove a file it is removed only on the branch 5281which you are working on (@pxref{Branching and merging}). You can 5282later merge the removals to another branch if you want 5283(@pxref{Merging adds and removals}). 5284 5285@node Removing directories 5286@section Removing directories 5287@cindex Removing directories 5288@cindex Directories, removing 5289 5290In concept, removing directories is somewhat similar to 5291removing files---you want the directory to not exist in 5292your current working directories, but you also want to 5293be able to retrieve old releases in which the directory 5294existed. 5295 5296The way that you remove a directory is to remove all 5297the files in it. You don't remove the directory 5298itself; there is no way to do that. 5299Instead you specify the @samp{-P} option to 5300@code{cvs update} or @code{cvs checkout}, 5301which will cause @sc{cvs} to remove empty 5302directories from working directories. 5303(Note that @code{cvs export} always removes empty directories.) 5304Probably the 5305best way to do this is to always specify @samp{-P}; if 5306you want an empty directory then put a dummy file (for 5307example @file{.keepme}) in it to prevent @samp{-P} from 5308removing it. 5309 5310@c I'd try to give a rationale for this, but I'm not 5311@c sure there is a particularly convincing one. What 5312@c we would _like_ is for CVS to do a better job of version 5313@c controlling whether directories exist, to eliminate the 5314@c need for -P and so that a file can be a directory in 5315@c one revision and a regular file in another. 5316Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5317options of @code{checkout}. This way, 5318@sc{cvs} will be able to correctly create the directory 5319or not depending on whether the particular version you 5320are checking out contains any files in that directory. 5321 5322@c --------------------------------------------------------------------- 5323@node Moving files 5324@section Moving and renaming files 5325@cindex Moving files 5326@cindex Renaming files 5327@cindex Files, moving 5328 5329Moving files to a different directory or renaming them 5330is not difficult, but some of the ways in which this 5331works may be non-obvious. (Moving or renaming a 5332directory is even harder. @xref{Moving directories}.). 5333 5334The examples below assume that the file @var{old} is renamed to 5335@var{new}. 5336 5337@menu 5338* Outside:: The normal way to Rename 5339* Inside:: A tricky, alternative way 5340* Rename by copying:: Another tricky, alternative way 5341@end menu 5342 5343@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5344@node Outside 5345@subsection The Normal way to Rename 5346 5347@c More rename issues. Not sure whether these are 5348@c worth documenting; I'm putting them here because 5349@c it seems to be as good a place as any to try to 5350@c set down the issues. 5351@c * "cvs annotate" will annotate either the new 5352@c file or the old file; it cannot annotate _each 5353@c line_ based on whether it was last changed in the 5354@c new or old file. Unlike "cvs log", where the 5355@c consequences of having to select either the new 5356@c or old name seem fairly benign, this may be a 5357@c real advantage to having CVS know about renames 5358@c other than as a deletion and an addition. 5359 5360The normal way to move a file is to copy @var{old} to 5361@var{new}, and then issue the normal @sc{cvs} commands 5362to remove @var{old} from the repository, and add 5363@var{new} to it. 5364@c The following sentence is not true: one must cd into 5365@c the directory to run "cvs add". 5366@c (Both @var{old} and @var{new} could 5367@c contain relative paths, for example @file{foo/bar.c}). 5368 5369@example 5370$ mv @var{old} @var{new} 5371$ cvs remove @var{old} 5372$ cvs add @var{new} 5373$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 5374@end example 5375 5376This is the simplest way to move a file, it is not 5377error-prone, and it preserves the history of what was 5378done. Note that to access the history of the file you 5379must specify the old or the new name, depending on what 5380portion of the history you are accessing. For example, 5381@code{cvs log @var{old}} will give the log up until the 5382time of the rename. 5383 5384When @var{new} is committed its revision numbers will 5385start again, usually at 1.1, so if that bothers you, 5386use the @samp{-r @var{tag}} option to commit. For more 5387information see @ref{Assigning revisions}. 5388 5389@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5390@node Inside 5391@subsection Moving the history file 5392 5393This method is more dangerous, since it involves moving 5394files inside the repository. Read this entire section 5395before trying it out! 5396 5397@example 5398$ cd $CVSROOT/@var{dir} 5399$ mv @var{old},v @var{new},v 5400@end example 5401 5402@noindent 5403Advantages: 5404 5405@itemize @bullet 5406@item 5407The log of changes is maintained intact. 5408 5409@item 5410The revision numbers are not affected. 5411@end itemize 5412 5413@noindent 5414Disadvantages: 5415 5416@itemize @bullet 5417@item 5418Old releases cannot easily be fetched from the 5419repository. (The file will show up as @var{new} even 5420in revisions from the time before it was renamed). 5421 5422@item 5423There is no log information of when the file was renamed. 5424 5425@item 5426Nasty things might happen if someone accesses the history file 5427while you are moving it. Make sure no one else runs any of the @sc{cvs} 5428commands while you move it. 5429@end itemize 5430 5431@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5432@node Rename by copying 5433@subsection Copying the history file 5434 5435This way also involves direct modifications to the 5436repository. It is safe, but not without drawbacks. 5437 5438@example 5439# @r{Copy the @sc{rcs} file inside the repository} 5440$ cd $CVSROOT/@var{dir} 5441$ cp @var{old},v @var{new},v 5442# @r{Remove the old file} 5443$ cd ~/@var{dir} 5444$ rm @var{old} 5445$ cvs remove @var{old} 5446$ cvs commit @var{old} 5447# @r{Remove all tags from @var{new}} 5448$ cvs update @var{new} 5449$ cvs log @var{new} # @r{Remember the non-branch tag names} 5450$ cvs tag -d @var{tag1} @var{new} 5451$ cvs tag -d @var{tag2} @var{new} 5452@dots{} 5453@end example 5454 5455By removing the tags you will be able to check out old 5456revisions. 5457 5458@noindent 5459Advantages: 5460 5461@itemize @bullet 5462@item 5463@c FIXME: Is this true about -D now that we have death 5464@c support? See 5B.3 in the FAQ. 5465Checking out old revisions works correctly, as long as 5466you use @samp{-r @var{tag}} and not @samp{-D @var{date}} 5467to retrieve the revisions. 5468 5469@item 5470The log of changes is maintained intact. 5471 5472@item 5473The revision numbers are not affected. 5474@end itemize 5475 5476@noindent 5477Disadvantages: 5478 5479@itemize @bullet 5480@item 5481You cannot easily see the history of the file across the rename. 5482 5483@ignore 5484@c Is this true? I don't see how the revision numbers 5485@c _could_ start over, when new,v is just old,v with 5486@c the tags deleted. 5487@c If there is some need to reinstate this text, 5488@c it is "usually 1.1", not "1.0" and it needs an 5489@c xref to Assigning revisions 5490@item 5491Unless you use the @samp{-r @var{tag}} (@pxref{commit 5492options}) flag when @var{new} is committed its revision 5493numbers will start at 1.0 again. 5494@end ignore 5495@end itemize 5496 5497@c --------------------------------------------------------------------- 5498@node Moving directories 5499@section Moving and renaming directories 5500@cindex Moving directories 5501@cindex Renaming directories 5502@cindex Directories, moving 5503 5504The normal way to rename or move a directory is to 5505rename or move each file within it as described in 5506@ref{Outside}. Then check out with the @samp{-P} 5507option, as described in @ref{Removing directories}. 5508 5509If you really want to hack the repository to rename or 5510delete a directory in the repository, you can do it 5511like this: 5512 5513@enumerate 5514@item 5515Inform everyone who has a checked out copy of the directory that the 5516directory will be renamed. They should commit all their changes in all their 5517copies of the project containing the directory to be removed, and remove 5518all their working copies of said project, before you take the steps below. 5519 5520@item 5521Rename the directory inside the repository. 5522 5523@example 5524$ cd $CVSROOT/@var{parent-dir} 5525$ mv @var{old-dir} @var{new-dir} 5526@end example 5527 5528@item 5529Fix the @sc{cvs} administrative files, if necessary (for 5530instance if you renamed an entire module). 5531 5532@item 5533Tell everyone that they can check out again and continue 5534working. 5535 5536@end enumerate 5537 5538If someone had a working copy the @sc{cvs} commands will 5539cease to work for him, until he removes the directory 5540that disappeared inside the repository. 5541 5542It is almost always better to move the files in the 5543directory instead of moving the directory. If you move the 5544directory you are unlikely to be able to retrieve old 5545releases correctly, since they probably depend on the 5546name of the directories. 5547 5548@c --------------------------------------------------------------------- 5549@node History browsing 5550@chapter History browsing 5551@cindex History browsing 5552@cindex Traceability 5553@cindex Isolation 5554 5555@ignore 5556@c This is too long for an introduction (goal is 5557@c one 20x80 character screen), and also mixes up a 5558@c variety of issues (parallel development, history, 5559@c maybe even touches on process control). 5560 5561@c -- @quote{To lose ones history is to lose ones soul.} 5562@c -- /// 5563@c -- ///Those who cannot remember the past are condemned to repeat it. 5564@c -- /// -- George Santayana 5565@c -- /// 5566 5567@sc{cvs} tries to make it easy for a group of people to work 5568together. This is done in two ways: 5569 5570@itemize @bullet 5571@item 5572Isolation---You have your own working copy of the 5573source. You are not affected by modifications made by 5574others until you decide to incorporate those changes 5575(via the @code{update} command---@pxref{update}). 5576 5577@item 5578Traceability---When something has changed, you can 5579always see @emph{exactly} what changed. 5580@end itemize 5581 5582There are several features of @sc{cvs} that together lead 5583to traceability: 5584 5585@itemize @bullet 5586@item 5587Each revision of a file has an accompanying log 5588message. 5589 5590@item 5591All commits are optionally logged to a central history 5592database. 5593 5594@item 5595Logging information can be sent to a user-defined 5596program (@pxref{loginfo}). 5597@end itemize 5598 5599@c -- More text here. 5600 5601This chapter should talk about the history file, the 5602@code{log} command, the usefulness of ChangeLogs 5603even when you run @sc{cvs}, and things like that. 5604 5605@end ignore 5606 5607@c kind of lame, in a lot of ways the above text inside 5608@c the @ignore motivates this chapter better 5609Once you have used @sc{cvs} to store a version control 5610history---what files have changed when, how, and by 5611whom, there are a variety of mechanisms for looking 5612through the history. 5613 5614@c FIXME: should also be talking about how you look at 5615@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 5616@menu 5617* log messages:: Log messages 5618* history database:: The history database 5619* user-defined logging:: User-defined logging 5620@end menu 5621 5622@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5623@node log messages 5624@section Log messages 5625 5626@c FIXME: @xref to place where we talk about how to 5627@c specify message to commit. 5628Whenever you commit a file you specify a log message. 5629 5630@c FIXME: bring the information here, and get rid of or 5631@c greatly shrink the "log" node. 5632To look through the log messages which have been 5633specified for every revision which has been committed, 5634use the @code{cvs log} command (@pxref{log}). 5635 5636@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5637@node history database 5638@section The history database 5639 5640@c FIXME: bring the information from the history file 5641@c and history nodes here. Rewrite it to be motivated 5642@c better (start out by clearly explaining what gets 5643@c logged in history, for example). 5644You can use the history file (@pxref{history file}) to 5645log various @sc{cvs} actions. To retrieve the 5646information from the history file, use the @code{cvs 5647history} command (@pxref{history}). 5648 5649Note: you can control what is logged to this file by using the 5650@samp{LogHistory} keyword in the @file{CVSROOT/config} file 5651(@pxref{config}). 5652 5653@c 5654@c The history database has many problems: 5655@c * It is very unclear what field means what. This 5656@c could be improved greatly by better documentation, 5657@c but there are still non-orthogonalities (for 5658@c example, tag does not record the "repository" 5659@c field but most records do). 5660@c * Confusion about files, directories, and modules. 5661@c Some commands record one, some record others. 5662@c * File removal is not logged. There is an 'R' 5663@c record type documented, but CVS never uses it. 5664@c * Tags are only logged for the "cvs rtag" command, 5665@c not "cvs tag". The fix for this is not completely 5666@c clear (see above about modules vs. files). 5667@c * Are there other cases of operations that are not 5668@c logged? One would hope for all changes to the 5669@c repository to be logged somehow (particularly 5670@c operations like tagging, "cvs admin -k", and other 5671@c operations which do not record a history that one 5672@c can get with "cvs log"). Operations on the working 5673@c directory, like export, get, and release, are a 5674@c second category also covered by the current "cvs 5675@c history". 5676@c * The history file does not record the options given 5677@c to a command. The most serious manifestation of 5678@c this is perhaps that it doesn't record whether a command 5679@c was recursive. It is not clear to me whether one 5680@c wants to log at a level very close to the command 5681@c line, as a sort of way of logging each command 5682@c (more or less), or whether one wants 5683@c to log more at the level of what was changed (or 5684@c something in between), but either way the current 5685@c information has pretty big gaps. 5686@c * Further details about a tag--like whether it is a 5687@c branch tag or, if a non-branch tag, which branch it 5688@c is on. One can find out this information about the 5689@c tag as it exists _now_, but if the tag has been 5690@c moved, one doesn't know what it was like at the time 5691@c the history record was written. 5692@c * Whether operating on a particular tag, date, or 5693@c options was implicit (sticky) or explicit. 5694@c 5695@c Another item, only somewhat related to the above, is a 5696@c way to control what is logged in the history file. 5697@c This is probably the only good way to handle 5698@c different people having different ideas about 5699@c information/space tradeoffs. 5700@c 5701@c It isn't really clear that it makes sense to try to 5702@c patch up the history file format as it exists now to 5703@c include all that stuff. It might be better to 5704@c design a whole new CVSROOT/nhistory file and "cvs 5705@c nhistory" command, or some such, or in some other 5706@c way trying to come up with a clean break from the 5707@c past, which can address the above concerns. Another 5708@c open question is how/whether this relates to 5709@c taginfo/loginfo/etc. 5710 5711@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5712@node user-defined logging 5713@section User-defined logging 5714 5715@c FIXME: probably should centralize this information 5716@c here, at least to some extent. Maybe by moving the 5717@c loginfo, etc., nodes here and replacing 5718@c the "user-defined logging" node with one node for 5719@c each method. 5720You can customize @sc{cvs} to log various kinds of 5721actions, in whatever manner you choose. These 5722mechanisms operate by executing a script at various 5723times. The script might append a message to a file 5724listing the information and the programmer who created 5725it, or send mail to a group of developers, or, perhaps, 5726post a message to a particular newsgroup. To log 5727commits, use the @file{loginfo} file (@pxref{loginfo}), and 5728to log tagging operations, use the @file{taginfo} file 5729(@pxref{taginfo}). 5730 5731@c FIXME: What is difference between doing it in the 5732@c modules file and using loginfo/taginfo? Why should 5733@c user use one or the other? 5734To log commits, checkouts, exports, and tags, 5735respectively, you can also use the @samp{-i}, 5736@samp{-o}, @samp{-e}, and @samp{-t} options in the 5737modules file. For a more flexible way of giving 5738notifications to various users, which requires less in 5739the way of keeping centralized scripts up to date, use 5740the @code{cvs watch add} command (@pxref{Getting 5741Notified}); this command is useful even if you are not 5742using @code{cvs watch on}. 5743 5744@c --------------------------------------------------------------------- 5745@node Binary files 5746@chapter Handling binary files 5747@cindex Binary files 5748 5749The most common use for @sc{cvs} is to store text 5750files. With text files, @sc{cvs} can merge revisions, 5751display the differences between revisions in a 5752human-visible fashion, and other such operations. 5753However, if you are willing to give up a few of these 5754abilities, @sc{cvs} can store binary files. For 5755example, one might store a web site in @sc{cvs} 5756including both text files and binary images. 5757 5758@menu 5759* Binary why:: More details on issues with binary files 5760* Binary howto:: How to store them 5761@end menu 5762 5763@node Binary why 5764@section The issues with binary files 5765 5766While the need to manage binary files may seem obvious 5767if the files that you customarily work with are binary, 5768putting them into version control does present some 5769additional issues. 5770 5771One basic function of version control is to show the 5772differences between two revisions. For example, if 5773someone else checked in a new version of a file, you 5774may wish to look at what they changed and determine 5775whether their changes are good. For text files, 5776@sc{cvs} provides this functionality via the @code{cvs 5777diff} command. For binary files, it may be possible to 5778extract the two revisions and then compare them with a 5779tool external to @sc{cvs} (for example, word processing 5780software often has such a feature). If there is no 5781such tool, one must track changes via other mechanisms, 5782such as urging people to write good log messages, and 5783hoping that the changes they actually made were the 5784changes that they intended to make. 5785 5786Another ability of a version control system is the 5787ability to merge two revisions. For @sc{cvs} this 5788happens in two contexts. The first is when users make 5789changes in separate working directories 5790(@pxref{Multiple developers}). The second is when one 5791merges explicitly with the @samp{update -j} command 5792(@pxref{Branching and merging}). 5793 5794In the case of text 5795files, @sc{cvs} can merge changes made independently, 5796and signal a conflict if the changes conflict. With 5797binary files, the best that @sc{cvs} can do is present 5798the two different copies of the file, and leave it to 5799the user to resolve the conflict. The user may choose 5800one copy or the other, or may run an external merge 5801tool which knows about that particular file format, if 5802one exists. 5803Note that having the user merge relies primarily on the 5804user to not accidentally omit some changes, and thus is 5805potentially error prone. 5806 5807If this process is thought to be undesirable, the best 5808choice may be to avoid merging. To avoid the merges 5809that result from separate working directories, see the 5810discussion of reserved checkouts (file locking) in 5811@ref{Multiple developers}. To avoid the merges 5812resulting from branches, restrict use of branches. 5813 5814@node Binary howto 5815@section How to store binary files 5816 5817There are two issues with using @sc{cvs} to store 5818binary files. The first is that @sc{cvs} by default 5819converts line endings between the canonical form in 5820which they are stored in the repository (linefeed 5821only), and the form appropriate to the operating system 5822in use on the client (for example, carriage return 5823followed by line feed for Windows NT). 5824 5825The second is that a binary file might happen to 5826contain data which looks like a keyword (@pxref{Keyword 5827substitution}), so keyword expansion must be turned 5828off. 5829 5830@c FIXME: the third is that one can't do merges with 5831@c binary files. xref to Multiple Developers and the 5832@c reserved checkout issues. 5833 5834The @samp{-kb} option available with some @sc{cvs} 5835commands insures that neither line ending conversion 5836nor keyword expansion will be done. 5837 5838Here is an example of how you can create a new file 5839using the @samp{-kb} flag: 5840 5841@example 5842$ echo '$@splitrcskeyword{Id}$' > kotest 5843$ cvs add -kb -m"A test file" kotest 5844$ cvs ci -m"First checkin; contains a keyword" kotest 5845@end example 5846 5847If a file accidentally gets added without @samp{-kb}, 5848one can use the @code{cvs admin} command to recover. 5849For example: 5850 5851@example 5852$ echo '$@splitrcskeyword{Id}$' > kotest 5853$ cvs add -m"A test file" kotest 5854$ cvs ci -m"First checkin; contains a keyword" kotest 5855$ cvs admin -kb kotest 5856$ cvs update -A kotest 5857# @r{For non-unix systems:} 5858# @r{Copy in a good copy of the file from outside CVS} 5859$ cvs commit -m "make it binary" kotest 5860@end example 5861 5862@c Trying to describe this for both unix and non-unix 5863@c in the same description is very confusing. Might 5864@c want to split the two, or just ditch the unix "shortcut" 5865@c (unixheads don't do much with binary files, anyway). 5866@c This used to say "(Try the above example, and do a 5867@c @code{cat kotest} after every command)". But that 5868@c only really makes sense for the unix case. 5869When you check in the file @file{kotest} the file is 5870not preserved as a binary file, because you did not 5871check it in as a binary file. The @code{cvs 5872admin -kb} command sets the default keyword 5873substitution method for this file, but it does not 5874alter the working copy of the file that you have. If you need to 5875cope with line endings (that is, you are using 5876@sc{cvs} on a non-unix system), then you need to 5877check in a new copy of the file, as shown by the 5878@code{cvs commit} command above. 5879On unix, the @code{cvs update -A} command suffices. 5880@c FIXME: should also describe what the *other users* 5881@c need to do, if they have checked out copies which 5882@c have been corrupted by lack of -kb. I think maybe 5883@c "cvs update -kb" or "cvs 5884@c update -A" would suffice, although the user who 5885@c reported this suggested removing the file, manually 5886@c removing it from CVS/Entries, and then "cvs update" 5887(Note that you can use @code{cvs log} to determine the default keyword 5888substitution method for a file and @code{cvs status} to determine 5889the keyword substitution method for a working copy.) 5890 5891However, in using @code{cvs admin -k} to change the 5892keyword expansion, be aware that the keyword expansion 5893mode is not version controlled. This means that, for 5894example, that if you have a text file in old releases, 5895and a binary file with the same name in new releases, 5896@sc{cvs} provides no way to check out the file in text 5897or binary mode depending on what version you are 5898checking out. There is no good workaround for this 5899problem. 5900 5901You can also set a default for whether @code{cvs add} 5902and @code{cvs import} treat a file as binary based on 5903its name; for example you could say that files who 5904names end in @samp{.exe} are binary. @xref{Wrappers}. 5905There is currently no way to have @sc{cvs} detect 5906whether a file is binary based on its contents. The 5907main difficulty with designing such a feature is that 5908it is not clear how to distinguish between binary and 5909non-binary files, and the rules to apply would vary 5910considerably with the operating system. 5911@c For example, it would be good on MS-DOS-family OSes 5912@c for anything containing ^Z to be binary. Having 5913@c characters with the 8th bit set imply binary is almost 5914@c surely a bad idea in the context of ISO-8859-* and 5915@c other such character sets. On VMS or the Mac, we 5916@c could use the OS's file typing. This is a 5917@c commonly-desired feature, and something of this sort 5918@c may make sense. But there are a lot of pitfalls here. 5919@c 5920@c Another, probably better, way to tell is to read the 5921@c file in text mode, write it to a temp file in text 5922@c mode, and then do a binary mode compare of the two 5923@c files. If they differ, it is a binary file. This 5924@c might have problems on VMS (or some other system 5925@c with several different text modes), but in general 5926@c should be relatively portable. The only other 5927@c downside I can think of is that it would be fairly 5928@c slow, but that is perhaps a small price to pay for 5929@c not having your files corrupted. Another issue is 5930@c what happens if you import a text file with bare 5931@c linefeeds on Windows. Such files will show up on 5932@c Windows sometimes (I think some native windows 5933@c programs even write them, on occasion). Perhaps it 5934@c is reasonable to treat such files as binary; after 5935@c all it is something of a presumption to assume that 5936@c the user would want the linefeeds converted to CRLF. 5937 5938@c --------------------------------------------------------------------- 5939@node Multiple developers 5940@chapter Multiple developers 5941@cindex Multiple developers 5942@cindex Team of developers 5943@cindex File locking 5944@cindex Locking files 5945@cindex Working copy 5946@cindex Reserved checkouts 5947@cindex Unreserved checkouts 5948@cindex RCS-style locking 5949 5950When more than one person works on a software project 5951things often get complicated. Often, two people try to 5952edit the same file simultaneously. One solution, known 5953as @dfn{file locking} or @dfn{reserved checkouts}, is 5954to allow only one person to edit each file at a time. 5955This is the only solution with some version control 5956systems, including @sc{rcs} and @sc{sccs}. Currently 5957the usual way to get reserved checkouts with @sc{cvs} 5958is the @code{cvs admin -l} command (@pxref{admin 5959options}). This is not as nicely integrated into 5960@sc{cvs} as the watch features, described below, but it 5961seems that most people with a need for reserved 5962checkouts find it adequate. 5963@c Or "find it better than worrying about implementing 5964@c nicely integrated reserved checkouts" or ...? 5965 5966As of @sc{cvs} version 1.12.10, another technique for getting most of the 5967effect of reserved checkouts is to enable advisory locks. To enable advisory 5968locks, have all developers put "edit -c", "commit -c" in their 5969.cvsrc file, and turn on watches in the repository. This 5970prevents them from doing a @code{cvs edit} if anyone is 5971already editting the file. It also may 5972be possible to use plain watches together with suitable 5973procedures (not enforced by software), to avoid having 5974two people edit at the same time. 5975 5976@c Our unreserved checkout model might not 5977@c be quite the same as others. For example, I 5978@c think that some systems will tend to create a branch 5979@c in the case where CVS prints "up-to-date check failed". 5980@c It isn't clear to me whether we should try to 5981@c explore these subtleties; it could easily just 5982@c confuse people. 5983The default model with @sc{cvs} is known as 5984@dfn{unreserved checkouts}. In this model, developers 5985can edit their own @dfn{working copy} of a file 5986simultaneously. The first person that commits his 5987changes has no automatic way of knowing that another 5988has started to edit it. Others will get an error 5989message when they try to commit the file. They must 5990then use @sc{cvs} commands to bring their working copy 5991up to date with the repository revision. This process 5992is almost automatic. 5993 5994@c FIXME? should probably use the word "watch" here, to 5995@c tie this into the text below and above. 5996@sc{cvs} also supports mechanisms which facilitate 5997various kinds of communication, without actually 5998enforcing rules like reserved checkouts do. 5999 6000The rest of this chapter describes how these various 6001models work, and some of the issues involved in 6002choosing between them. 6003 6004@ignore 6005Here is a draft reserved checkout design or discussion 6006of the issues. This seems like as good a place as any 6007for this. 6008 6009Might want a cvs lock/cvs unlock--in which the names 6010differ from edit/unedit because the network must be up 6011for these to work. unedit gives an error if there is a 6012reserved checkout in place (so that people don't 6013accidentally leave locks around); unlock gives an error 6014if one is not in place (this is more arguable; perhaps 6015it should act like unedit in that case). 6016 6017On the other hand, might want it so that emacs, 6018scripts, etc., can get ready to edit a file without 6019having to know which model is in use. In that case we 6020would have a "cvs watch lock" (or .cvsrc?) (that is, 6021three settings, "on", "off", and "lock"). Having cvs 6022watch lock set would cause a get to record in the CVS 6023directory which model is in use, and cause "cvs edit" 6024to change behaviors. We'd want a way to query which 6025setting is in effect (this would be handy even if it is 6026only "on" or "off" as presently). If lock is in 6027effect, then commit would require a lock before 6028allowing a checkin; chmod wouldn't suffice (might be 6029debatable--see chmod comment below, in watches--but it 6030is the way people expect RCS to work and I can't think 6031of any significant downside. On the other hand, maybe 6032it isn't worth bothering, because people who are used 6033to RCS wouldn't think to use chmod anyway). 6034 6035Implementation: use file attributes or use RCS 6036locking. The former avoids more dependence on RCS 6037behaviors we will need to re-implement as we librarify 6038RCS, and makes it easier to import/export RCS files (in 6039that context, want to ignore the locker field). But 6040note that RCS locks are per-branch, which is the 6041correct behavior (this is also an issue for the "watch 6042on" features; they should be per-branch too). 6043 6044Here are a few more random notes about implementation 6045details, assuming "cvs watch lock" and 6046 6047CVS/Watched file? Or try to fit this into CVS/Entries somehow? 6048Cases: (1) file is checked out (unreserved or with watch on) by old 6049version of @sc{cvs}, now we do something with new one, (2) file is checked 6050out by new version, now we do something with old one. 6051 6052Remote protocol would have a "Watched" analogous to "Mode". Of course 6053it would apply to all Updated-like requests. How do we keep this 6054setting up to date? I guess that there wants to be a Watched request, 6055and the server would send a new one if it isn't up to date? (Ugh--hard 6056to implement and slows down "cvs -q update"--is there an easier way?) 6057 6058"cvs edit"--checks CVS/Watched, and if watch lock, then sends 6059"edit-lock" request. Which comes back with a Checked-in with 6060appropriate Watched (off, on, lock, locked, or some such?), or error 6061message if already locked. 6062 6063"cvs commit"--only will commit if off/on/locked. lock is not OK. 6064 6065Doc: 6066note that "cvs edit" must be connected to network if watch lock is in 6067effect. 6068 6069Talk about what to do if someone has locked a file and you want to 6070edit that file. (breaking locks, or lack thereof). 6071 6072 6073One other idea (which could work along with the 6074existing "cvs admin -l" reserved checkouts, as well as 6075the above): 6076 6077"cvs editors" could show who has the file locked, if 6078someone does. 6079 6080@end ignore 6081 6082@menu 6083* File status:: A file can be in several states 6084* Updating a file:: Bringing a file up-to-date 6085* Conflicts example:: An informative example 6086* Informing others:: To cooperate you must inform 6087* Concurrency:: Simultaneous repository access 6088* Watches:: Mechanisms to track who is editing files 6089* Choosing a model:: Reserved or unreserved checkouts? 6090@end menu 6091 6092@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6093@node File status 6094@section File status 6095@cindex File status 6096@cindex Status of a file 6097 6098@c Shouldn't this start with an example or something, 6099@c introducing the unreserved checkout model? Before we 6100@c dive into listing states? 6101Based on what operations you have performed on a 6102checked out file, and what operations others have 6103performed to that file in the repository, one can 6104classify a file in a number of states. The states, as 6105reported by the @code{status} command, are: 6106 6107@c The order of items is chosen to group logically 6108@c similar outputs together. 6109@c People who want alphabetical can use the index... 6110@table @asis 6111@cindex Up-to-date 6112@item Up-to-date 6113The file is identical with the latest revision in the 6114repository for the branch in use. 6115@c FIXME: should we clarify "in use"? The answer is 6116@c sticky tags, and trying to distinguish branch sticky 6117@c tags from non-branch sticky tags seems rather awkward 6118@c here. 6119@c FIXME: What happens with non-branch sticky tags? Is 6120@c a stuck file "Up-to-date" or "Needs checkout" or what? 6121 6122@item Locally Modified 6123@cindex Locally Modified 6124You have edited the file, and not yet committed your changes. 6125 6126@item Locally Added 6127@cindex Locally Added 6128You have added the file with @code{add}, and not yet 6129committed your changes. 6130@c There are many cases involving the file being 6131@c added/removed/modified in the working directory, and 6132@c added/removed/modified in the repository, which we 6133@c don't try to describe here. I'm not sure that "cvs 6134@c status" produces a non-confusing output in most of 6135@c those cases. 6136 6137@item Locally Removed 6138@cindex Locally Removed 6139You have removed the file with @code{remove}, and not yet 6140committed your changes. 6141 6142@item Needs Checkout 6143@cindex Needs Checkout 6144Someone else has committed a newer revision to the 6145repository. The name is slightly misleading; you will 6146ordinarily use @code{update} rather than 6147@code{checkout} to get that newer revision. 6148 6149@item Needs Patch 6150@cindex Needs Patch 6151@c See also newb-123j0 in sanity.sh (although that case 6152@c should probably be changed rather than documented). 6153Like Needs Checkout, but the @sc{cvs} server will send 6154a patch rather than the entire file. Sending a patch or 6155sending an entire file accomplishes the same thing. 6156 6157@item Needs Merge 6158@cindex Needs Merge 6159Someone else has committed a newer revision to the repository, and you 6160have also made modifications to the file. 6161 6162@item Unresolved Conflict 6163@cindex Unresolved Conflict 6164@c FIXCVS - This file status needs to be changed to some more informative 6165@c text that distinguishes it more clearly from each of the Locally Added, 6166@c File had conflicts on merge, and Unknown status types, but an exact and 6167@c succinct wording escapes me at the moment. 6168A file with the same name as this new file has been added to the repository 6169from a second workspace. This file will need to be moved out of the way 6170to allow an @code{update} to complete. 6171 6172@item File had conflicts on merge 6173@cindex File had conflicts on merge 6174@c is it worth saying that this message was "Unresolved 6175@c Conflict" in CVS 1.9 and earlier? I'm inclined to 6176@c think that is unnecessarily confusing to new users. 6177This is like Locally Modified, except that a previous 6178@code{update} command gave a conflict. If you have not 6179already done so, you need to 6180resolve the conflict as described in @ref{Conflicts example}. 6181 6182@item Unknown 6183@cindex Unknown 6184@sc{cvs} doesn't know anything about this file. For 6185example, you have created a new file and have not run 6186@code{add}. 6187@c 6188@c "Entry Invalid" and "Classify Error" are also in the 6189@c status.c. The latter definitely indicates a CVS bug 6190@c (should it be worded more like "internal error" so 6191@c people submit bug reports if they see it?). The former 6192@c I'm not as sure; I haven't tracked down whether/when it 6193@c appears in "cvs status" output. 6194 6195@end table 6196 6197To help clarify the file status, @code{status} also 6198reports the @code{Working revision} which is the 6199revision that the file in the working directory derives 6200from, and the @code{Repository revision} which is the 6201latest revision in the repository for the branch in 6202use. 6203The @samp{Commit Identifier} reflects the unique commitid 6204of the @code{commit}. 6205@c FIXME: should we clarify "in use"? The answer is 6206@c sticky tags, and trying to distinguish branch sticky 6207@c tags from non-branch sticky tags seems rather awkward 6208@c here. 6209@c FIXME: What happens with non-branch sticky tags? 6210@c What is the Repository Revision there? See the 6211@c comment at vn_rcs in cvs.h, which is kind of 6212@c confused--we really need to document better what this 6213@c field contains. 6214@c Q: Should we document "New file!" and other such 6215@c outputs or are they self-explanatory? 6216@c FIXME: what about the date to the right of "Working 6217@c revision"? It doesn't appear with client/server and 6218@c seems unnecessary (redundant with "ls -l") so 6219@c perhaps it should be removed for non-client/server too? 6220@c FIXME: Need some examples. 6221@c FIXME: Working revision can also be something like 6222@c "-1.3" for a locally removed file. Not at all 6223@c self-explanatory (and it is possible that CVS should 6224@c be changed rather than documenting this). 6225 6226@c Would be nice to have an @example showing output 6227@c from cvs status, with comments showing the xref 6228@c where each part of the output is described. This 6229@c might fit in nicely if it is desirable to split this 6230@c node in two; one to introduce "cvs status" and one 6231@c to list each of the states. 6232The options to @code{status} are listed in 6233@ref{Invoking CVS}. For information on its @code{Sticky tag} 6234and @code{Sticky date} output, see @ref{Sticky tags}. 6235For information on its @code{Sticky options} output, 6236see the @samp{-k} option in @ref{update options}. 6237 6238You can think of the @code{status} and @code{update} 6239commands as somewhat complementary. You use 6240@code{update} to bring your files up to date, and you 6241can use @code{status} to give you some idea of what an 6242@code{update} would do (of course, the state of the 6243repository might change before you actually run 6244@code{update}). In fact, if you want a command to 6245display file status in a more brief format than is 6246displayed by the @code{status} command, you can invoke 6247 6248@cindex update, to display file status 6249@example 6250$ cvs -n -q update 6251@end example 6252 6253The @samp{-n} option means to not actually do the 6254update, but merely to display statuses; the @samp{-q} 6255option avoids printing the name of each directory. For 6256more information on the @code{update} command, and 6257these options, see @ref{Invoking CVS}. 6258 6259@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6260@node Updating a file 6261@section Bringing a file up to date 6262@cindex Bringing a file up to date 6263@cindex Updating a file 6264@cindex Merging a file 6265@cindex Update, introduction 6266 6267When you want to update or merge a file, use the @code{cvs update -d} 6268command. For files that are not up to date this is roughly equivalent 6269to a @code{checkout} command: the newest revision of the file is 6270extracted from the repository and put in your working directory. The 6271@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} 6272that you wish it to create directories added by other developers. 6273 6274Your modifications to a file are never lost when you 6275use @code{update}. If no newer revision exists, 6276running @code{update} has no effect. If you have 6277edited the file, and a newer revision is available, 6278@sc{cvs} will merge all changes into your working copy. 6279 6280For instance, imagine that you checked out revision 1.4 and started 6281editing it. In the meantime someone else committed revision 1.5, and 6282shortly after that revision 1.6. If you run @code{update} on the file 6283now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 6284your file. 6285 6286@cindex Overlap 6287If any of the changes between 1.4 and 1.6 were made too 6288close to any of the changes you have made, an 6289@dfn{overlap} occurs. In such cases a warning is 6290printed, and the resulting file includes both 6291versions of the lines that overlap, delimited by 6292special markers. 6293@xref{update}, for a complete description of the 6294@code{update} command. 6295 6296@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6297@node Conflicts example 6298@section Conflicts example 6299@cindex Merge, an example 6300@cindex Example of merge 6301@cindex driver.c (merge example) 6302 6303Suppose revision 1.4 of @file{driver.c} contains this: 6304 6305@example 6306#include <stdio.h> 6307 6308void main() 6309@{ 6310 parse(); 6311 if (nerr == 0) 6312 gencode(); 6313 else 6314 fprintf(stderr, "No code generated.\n"); 6315 exit(nerr == 0 ? 0 : 1); 6316@} 6317@end example 6318 6319@noindent 6320Revision 1.6 of @file{driver.c} contains this: 6321 6322@example 6323#include <stdio.h> 6324 6325int main(int argc, 6326 char **argv) 6327@{ 6328 parse(); 6329 if (argc != 1) 6330 @{ 6331 fprintf(stderr, "tc: No args expected.\n"); 6332 exit(1); 6333 @} 6334 if (nerr == 0) 6335 gencode(); 6336 else 6337 fprintf(stderr, "No code generated.\n"); 6338 exit(!!nerr); 6339@} 6340@end example 6341 6342@noindent 6343Your working copy of @file{driver.c}, based on revision 63441.4, contains this before you run @samp{cvs update}: 6345@c -- Really include "cvs"? 6346 6347@example 6348#include <stdlib.h> 6349#include <stdio.h> 6350 6351void main() 6352@{ 6353 init_scanner(); 6354 parse(); 6355 if (nerr == 0) 6356 gencode(); 6357 else 6358 fprintf(stderr, "No code generated.\n"); 6359 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6360@} 6361@end example 6362 6363@noindent 6364You run @samp{cvs update}: 6365@c -- Really include "cvs"? 6366 6367@example 6368$ cvs update driver.c 6369RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 6370retrieving revision 1.4 6371retrieving revision 1.6 6372Merging differences between 1.4 and 1.6 into driver.c 6373rcsmerge warning: overlaps during merge 6374cvs update: conflicts found in driver.c 6375C driver.c 6376@end example 6377 6378@noindent 6379@cindex Conflicts (merge example) 6380@sc{cvs} tells you that there were some conflicts. 6381Your original working file is saved unmodified in 6382@file{.#driver.c.1.4}. The new version of 6383@file{driver.c} contains this: 6384 6385@example 6386#include <stdlib.h> 6387#include <stdio.h> 6388 6389int main(int argc, 6390 char **argv) 6391@{ 6392 init_scanner(); 6393 parse(); 6394 if (argc != 1) 6395 @{ 6396 fprintf(stderr, "tc: No args expected.\n"); 6397 exit(1); 6398 @} 6399 if (nerr == 0) 6400 gencode(); 6401 else 6402 fprintf(stderr, "No code generated.\n"); 6403@asis{}<<<<<<< driver.c 6404 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6405@asis{}======= 6406 exit(!!nerr); 6407@asis{}>>>>>>> 1.6 6408@} 6409@end example 6410 6411@noindent 6412@cindex Markers, conflict 6413@cindex Conflict markers 6414@cindex <<<<<<< 6415@cindex >>>>>>> 6416@cindex ======= 6417 6418Note how all non-overlapping modifications are incorporated in your working 6419copy, and that the overlapping section is clearly marked with 6420@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 6421 6422@cindex Resolving a conflict 6423@cindex Conflict resolution 6424You resolve the conflict by editing the file, removing the markers and 6425the erroneous line. Suppose you end up with this file: 6426@c -- Add xref to the pcl-cvs manual when it talks 6427@c -- about this. 6428@example 6429#include <stdlib.h> 6430#include <stdio.h> 6431 6432int main(int argc, 6433 char **argv) 6434@{ 6435 init_scanner(); 6436 parse(); 6437 if (argc != 1) 6438 @{ 6439 fprintf(stderr, "tc: No args expected.\n"); 6440 exit(1); 6441 @} 6442 if (nerr == 0) 6443 gencode(); 6444 else 6445 fprintf(stderr, "No code generated.\n"); 6446 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6447@} 6448@end example 6449 6450@noindent 6451You can now go ahead and commit this as revision 1.7. 6452 6453@example 6454$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 6455Checking in driver.c; 6456/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 6457new revision: 1.7; previous revision: 1.6 6458done 6459@end example 6460 6461For your protection, @sc{cvs} will refuse to check in a 6462file if a conflict occurred and you have not resolved 6463the conflict. Currently to resolve a conflict, you 6464must change the timestamp on the file. In previous 6465versions of @sc{cvs}, you also needed to 6466insure that the file contains no conflict markers. 6467Because 6468your file may legitimately contain conflict markers (that 6469is, occurrences of @samp{>>>>>>> } at the start of a 6470line that don't mark a conflict), the current 6471version of @sc{cvs} will print a warning and proceed to 6472check in the file. 6473@c The old behavior was really icky; the only way out 6474@c was to start hacking on 6475@c the @code{CVS/Entries} file or other such workarounds. 6476@c 6477@c If the timestamp thing isn't considered nice enough, 6478@c maybe there should be a "cvs resolved" command 6479@c which clears the conflict indication. For a nice user 6480@c interface, this should be invoked by an interactive 6481@c merge tool like emerge rather than by the user 6482@c directly--such a tool can verify that the user has 6483@c really dealt with each conflict. 6484 6485@cindex emerge 6486If you use release 1.04 or later of pcl-cvs (a @sc{gnu} 6487Emacs front-end for @sc{cvs}) you can use an Emacs 6488package called emerge to help you resolve conflicts. 6489See the documentation for pcl-cvs. 6490 6491@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6492@node Informing others 6493@section Informing others about commits 6494@cindex Informing others 6495@cindex Spreading information 6496@cindex Mail, automatic mail on commit 6497 6498It is often useful to inform others when you commit a 6499new revision of a file. The @samp{-i} option of the 6500@file{modules} file, or the @file{loginfo} file, can be 6501used to automate this process. @xref{modules}. 6502@xref{loginfo}. You can use these features of @sc{cvs} 6503to, for instance, instruct @sc{cvs} to mail a 6504message to all developers, or post a message to a local 6505newsgroup. 6506@c -- More text would be nice here. 6507 6508@node Concurrency 6509@section Several developers simultaneously attempting to run CVS 6510 6511@cindex Locks, cvs, introduction 6512@c For a discussion of *why* CVS creates locks, see 6513@c the comment at the start of src/lock.c 6514If several developers try to run @sc{cvs} at the same 6515time, one may get the following message: 6516 6517@example 6518[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 6519@end example 6520 6521@cindex #cvs.rfl, removing 6522@cindex #cvs.wfl, removing 6523@cindex #cvs.lock, removing 6524@sc{cvs} will try again every 30 seconds, and either 6525continue with the operation or print the message again, 6526if it still needs to wait. If a lock seems to stick 6527around for an undue amount of time, find the person 6528holding the lock and ask them about the cvs command 6529they are running. If they aren't running a cvs 6530command, look in the repository directory mentioned in 6531the message and remove files which they own whose names 6532start with @file{#cvs.rfl}, 6533@file{#cvs.wfl}, or @file{#cvs.lock}. 6534 6535Note that these locks are to protect @sc{cvs}'s 6536internal data structures and have no relationship to 6537the word @dfn{lock} in the sense used by 6538@sc{rcs}---which refers to reserved checkouts 6539(@pxref{Multiple developers}). 6540 6541Any number of people can be reading from a given 6542repository at a time; only when someone is writing do 6543the locks prevent other people from reading or writing. 6544 6545@cindex Atomic transactions, lack of 6546@cindex Transactions, atomic, lack of 6547@c the following talks about what one might call commit/update 6548@c atomicity. 6549@c Probably also should say something about 6550@c commit/commit atomicity, that is, "An update will 6551@c not get partial versions of more than one commit". 6552@c CVS currently has this property and I guess we can 6553@c make it a documented feature. 6554@c For example one person commits 6555@c a/one.c and b/four.c and another commits a/two.c and 6556@c b/three.c. Then an update cannot get the new a/one.c 6557@c and a/two.c and the old b/four.c and b/three.c. 6558One might hope for the following property: 6559 6560@quotation 6561If someone commits some changes in one cvs command, 6562then an update by someone else will either get all the 6563changes, or none of them. 6564@end quotation 6565 6566@noindent 6567but @sc{cvs} does @emph{not} have this property. For 6568example, given the files 6569 6570@example 6571a/one.c 6572a/two.c 6573b/three.c 6574b/four.c 6575@end example 6576 6577@noindent 6578if someone runs 6579 6580@example 6581cvs ci a/two.c b/three.c 6582@end example 6583 6584@noindent 6585and someone else runs @code{cvs update} at the same 6586time, the person running @code{update} might get only 6587the change to @file{b/three.c} and not the change to 6588@file{a/two.c}. 6589 6590@node Watches 6591@section Mechanisms to track who is editing files 6592@cindex Watches 6593 6594For many groups, use of @sc{cvs} in its default mode is 6595perfectly satisfactory. Users may sometimes go to 6596check in a modification only to find that another 6597modification has intervened, but they deal with it and 6598proceed with their check in. Other groups prefer to be 6599able to know who is editing what files, so that if two 6600people try to edit the same file they can choose to 6601talk about who is doing what when rather than be 6602surprised at check in time. The features in this 6603section allow such coordination, while retaining the 6604ability of two developers to edit the same file at the 6605same time. 6606 6607@c Some people might ask why CVS does not enforce the 6608@c rule on chmod, by requiring a cvs edit before a cvs 6609@c commit. The main reason is that it could always be 6610@c circumvented--one could edit the file, and 6611@c then when ready to check it in, do the cvs edit and put 6612@c in the new contents and do the cvs commit. One 6613@c implementation note: if we _do_ want to have cvs commit 6614@c require a cvs edit, we should store the state on 6615@c whether the cvs edit has occurred in the working 6616@c directory, rather than having the server try to keep 6617@c track of what working directories exist. 6618@c FIXME: should the above discussion be part of the 6619@c manual proper, somewhere, not just in a comment? 6620For maximum benefit developers should use @code{cvs 6621edit} (not @code{chmod}) to make files read-write to 6622edit them, and @code{cvs release} (not @code{rm}) to 6623discard a working directory which is no longer in use, 6624but @sc{cvs} is not able to enforce this behavior. 6625 6626If a development team wants stronger enforcement of 6627watches and all team members are using a @sc{cvs} client version 1.12.10 or 6628greater to access a @sc{cvs} server version 1.12.10 or greater, they can 6629enable advisory locks. To enable advisory locks, have all developers 6630put "edit -c" and "commit -c" into all .cvsrc files, 6631and make files default to read only by turning on watches 6632or putting "cvs -r" into all .cvsrc files. 6633This prevents multiple people from editting a file at 6634the same time (unless explicitly overriden with @samp{-f}). 6635 6636@c I'm a little dissatisfied with this presentation, 6637@c because "watch on"/"edit"/"editors" are one set of 6638@c functionality, and "watch add"/"watchers" is another 6639@c which is somewhat orthogonal even though they interact in 6640@c various ways. But I think it might be 6641@c confusing to describe them separately (e.g. "watch 6642@c add" with loginfo). I don't know. 6643 6644@menu 6645* Setting a watch:: Telling CVS to watch certain files 6646* Getting Notified:: Telling CVS to notify you 6647* Editing files:: How to edit a file which is being watched 6648* Watch information:: Information about who is watching and editing 6649* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 6650@end menu 6651 6652@node Setting a watch 6653@subsection Telling CVS to watch certain files 6654 6655To enable the watch features, you first specify that 6656certain files are to be watched. 6657 6658@cindex watch on (subcommand) 6659@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 6660 6661@cindex Read-only files, and watches 6662Specify that developers should run @code{cvs edit} 6663before editing @var{files}. @sc{cvs} will create working 6664copies of @var{files} read-only, to remind developers 6665to run the @code{cvs edit} command before working on 6666them. 6667 6668If @var{files} includes the name of a directory, @sc{cvs} 6669arranges to watch all files added to the corresponding 6670repository directory, and sets a default for files 6671added in the future; this allows the user to set 6672notification policies on a per-directory basis. The 6673contents of the directory are processed recursively, 6674unless the @code{-l} option is given. 6675The @code{-R} option can be used to force recursion if the @code{-l} 6676option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 6677 6678If @var{files} is omitted, it defaults to the current directory. 6679 6680@cindex watch off (subcommand) 6681@end deffn 6682 6683@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 6684 6685Do not create @var{files} read-only on checkout; thus, 6686developers will not be reminded to use @code{cvs edit} 6687and @code{cvs unedit}. 6688@ignore 6689@sc{cvs} will check out @var{files} 6690read-write as usual, unless other permissions override 6691due to the @code{PreservePermissions} option being 6692enabled in the @file{config} administrative file 6693(@pxref{Special Files}, @pxref{config}) 6694@end ignore 6695 6696The @var{files} and options are processed as for @code{cvs 6697watch on}. 6698 6699@end deffn 6700 6701@node Getting Notified 6702@subsection Telling CVS to notify you 6703 6704You can tell @sc{cvs} that you want to receive 6705notifications about various actions taken on a file. 6706You can do this without using @code{cvs watch on} for 6707the file, but generally you will want to use @code{cvs 6708watch on}, to remind developers to use the @code{cvs edit} 6709command. 6710 6711@cindex watch add (subcommand) 6712@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6713 6714Add the current user to the list of people to receive notification of 6715work done on @var{files}. 6716 6717The @code{-a} option specifies what kinds of events @sc{cvs} should notify 6718the user about. @var{action} is one of the following: 6719 6720@table @code 6721 6722@item edit 6723Another user has applied the @code{cvs edit} command (described 6724below) to a watched file. 6725 6726@item commit 6727Another user has committed changes to one of the named @var{files}. 6728 6729@item unedit 6730Another user has abandoned editing a file (other than by committing changes). 6731They can do this in several ways, by: 6732 6733@itemize @bullet 6734 6735@item 6736applying the @code{cvs unedit} command (described below) to the file 6737 6738@item 6739applying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6740(or recursively to a directory more than one level up) 6741 6742@item 6743deleting the file and allowing @code{cvs update} to recreate it 6744 6745@end itemize 6746 6747@item all 6748All of the above. 6749 6750@item none 6751None of the above. (This is useful with @code{cvs edit}, 6752described below.) 6753 6754@end table 6755 6756The @code{-a} option may appear more than once, or not at all. If 6757omitted, the action defaults to @code{all}. 6758 6759The @var{files} and options are processed as for 6760@code{cvs watch on}. 6761 6762@end deffn 6763 6764 6765@cindex watch remove (subcommand) 6766@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6767 6768Remove a notification request established using @code{cvs watch add}; 6769the arguments are the same. If the @code{-a} option is present, only 6770watches for the specified actions are removed. 6771 6772@end deffn 6773 6774@cindex notify (admin file) 6775When the conditions exist for notification, @sc{cvs} 6776calls the @file{notify} administrative file. Edit 6777@file{notify} as one edits the other administrative 6778files (@pxref{Intro administrative files}). This 6779file follows the usual conventions for administrative 6780files (@pxref{syntax}), where each line is a regular 6781expression followed by a command to execute. The 6782command should contain a single occurrence of @samp{%s} 6783which will be replaced by the user to notify; the rest 6784of the information regarding the notification will be 6785supplied to the command on standard input. The 6786standard thing to put in the @code{notify} file is the 6787single line: 6788 6789@example 6790ALL mail %s -s "CVS notification" 6791@end example 6792 6793@noindent 6794This causes users to be notified by electronic mail. 6795@c FIXME: should it be this hard to set up this 6796@c behavior (and the result when one fails to do so, 6797@c silent failure to notify, so non-obvious)? Should 6798@c CVS give a warning if no line in notify matches (and 6799@c document the use of "DEFAULT :" for the case where 6800@c skipping the notification is indeed desired)? 6801 6802@cindex users (admin file) 6803Note that if you set this up in the straightforward 6804way, users receive notifications on the server machine. 6805One could of course write a @file{notify} script which 6806directed notifications elsewhere, but to make this 6807easy, @sc{cvs} allows you to associate a notification 6808address for each user. To do so create a file 6809@file{users} in @file{CVSROOT} with a line for each 6810user in the format @var{user}:@var{value}. Then 6811instead of passing the name of the user to be notified 6812to @file{notify}, @sc{cvs} will pass the @var{value} 6813(normally an email address on some other machine). 6814 6815@sc{cvs} does not notify you for your own changes. 6816Currently this check is done based on whether the user 6817name of the person taking the action which triggers 6818notification matches the user name of the person 6819getting notification. In fact, in general, the watches 6820features only track one edit by each user. It probably 6821would be more useful if watches tracked each working 6822directory separately, so this behavior might be worth 6823changing. 6824@c "behavior might be worth changing" is an effort to 6825@c point to future directions while also not promising 6826@c that "they" (as in "why don't they fix CVS to....") 6827@c will do this. 6828@c one implementation issue is identifying whether a 6829@c working directory is same or different. Comparing 6830@c pathnames/hostnames is hopeless, but having the server 6831@c supply a serial number which the client stores in the 6832@c CVS directory as a magic cookie should work. 6833 6834@node Editing files 6835@subsection How to edit a file which is being watched 6836 6837@cindex Checkout, as term for getting ready to edit 6838Since a file which is being watched is checked out 6839read-only, you cannot simply edit it. To make it 6840read-write, and inform others that you are planning to 6841edit it, use the @code{cvs edit} command. Some systems 6842call this a @dfn{checkout}, but @sc{cvs} uses that term 6843for obtaining a copy of the sources (@pxref{Getting the 6844source}), an operation which those systems call a 6845@dfn{get} or a @dfn{fetch}. 6846@c Issue to think about: should we transition CVS 6847@c towards the "get" terminology? "cvs get" is already a 6848@c synonym for "cvs checkout" and that section of the 6849@c manual refers to "Getting the source". If this is 6850@c done, needs to be done gingerly (for example, we should 6851@c still accept "checkout" in .cvsrc files indefinitely 6852@c even if the CVS's messages are changed from "cvs checkout: " 6853@c to "cvs get: "). 6854@c There is a concern about whether "get" is not as 6855@c good for novices because it is a more general term 6856@c than "checkout" (and thus arguably harder to assign 6857@c a technical meaning for). 6858 6859@cindex edit (subcommand) 6860@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6861 6862Prepare to edit the working files @var{files}. @sc{cvs} makes the 6863@var{files} read-write, and notifies users who have requested 6864@code{edit} notification for any of @var{files}. 6865 6866The @code{cvs edit} command accepts the same options as the 6867@code{cvs watch add} command, and establishes a temporary watch for the 6868user on @var{files}; @sc{cvs} will remove the watch when @var{files} are 6869@code{unedit}ed or @code{commit}ted. If the user does not wish to 6870receive notifications, she should specify @code{-a none}. 6871 6872The @var{files} and the options are processed as for the @code{cvs 6873watch} commands. 6874 6875There are two additional options that @code{cvs edit} understands as of 6876@sc{cvs} client and server versions 1.12.10 but @code{cvs watch} does not. 6877The first is @code{-c}, which causes @code{cvs edit} to fail if anyone else 6878is editting the file. This is probably only useful when @samp{edit -c} and 6879@samp{commit -c} are specified in all developers' @file{.cvsrc} files. This 6880behavior may be overriden this via the @code{-f} option, which overrides 6881@code{-c} and allows multiple edits to succeed. 6882 6883@ignore 6884@strong{Caution: If the @code{PreservePermissions} 6885option is enabled in the repository (@pxref{config}), 6886@sc{cvs} will not change the permissions on any of the 6887@var{files}. The reason for this change is to ensure 6888that using @samp{cvs edit} does not interfere with the 6889ability to store file permissions in the @sc{cvs} 6890repository.} 6891@end ignore 6892 6893@end deffn 6894 6895Normally when you are done with a set of changes, you 6896use the @code{cvs commit} command, which checks in your 6897changes and returns the watched files to their usual 6898read-only state. But if you instead decide to abandon 6899your changes, or not to make any changes, you can use 6900the @code{cvs unedit} command. 6901 6902@cindex unedit (subcommand) 6903@cindex Abandoning work 6904@cindex Reverting to repository version 6905@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 6906 6907Abandon work on the working files @var{files}, and revert them to the 6908repository versions on which they are based. @sc{cvs} makes those 6909@var{files} read-only for which users have requested notification using 6910@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 6911notification for any of @var{files}. 6912 6913The @var{files} and options are processed as for the 6914@code{cvs watch} commands. 6915 6916If watches are not in use, the @code{unedit} command 6917probably does not work, and the way to revert to the 6918repository version is with the command @code{cvs update -C file} 6919(@pxref{update}). 6920The meaning is 6921not precisely the same; the latter may also 6922bring in some changes which have been made in the 6923repository since the last time you updated. 6924@c It would be a useful enhancement to CVS to make 6925@c unedit work in the non-watch case as well. 6926@end deffn 6927 6928When using client/server @sc{cvs}, you can use the 6929@code{cvs edit} and @code{cvs unedit} commands even if 6930@sc{cvs} is unable to successfully communicate with the 6931server; the notifications will be sent upon the next 6932successful @sc{cvs} command. 6933 6934@node Watch information 6935@subsection Information about who is watching and editing 6936 6937@cindex watchers (subcommand) 6938@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 6939 6940List the users currently watching changes to @var{files}. The report 6941includes the files being watched, and the mail address of each watcher. 6942 6943The @var{files} and options are processed as for the 6944@code{cvs watch} commands. 6945 6946@end deffn 6947 6948 6949@cindex editors (subcommand) 6950@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 6951 6952List the users currently working on @var{files}. The report 6953includes the mail address of each user, the time when the user began 6954working with the file, and the host and path of the working directory 6955containing the file. 6956 6957The @var{files} and options are processed as for the 6958@code{cvs watch} commands. 6959 6960@end deffn 6961 6962@node Watches Compatibility 6963@subsection Using watches with old versions of CVS 6964 6965@cindex CVS 1.6, and watches 6966If you use the watch features on a repository, it 6967creates @file{CVS} directories in the repository and 6968stores the information about watches in that directory. 6969If you attempt to use @sc{cvs} 1.6 or earlier with the 6970repository, you get an error message such as the 6971following (all on one line): 6972 6973@example 6974cvs update: cannot open CVS/Entries for reading: 6975No such file or directory 6976@end example 6977 6978@noindent 6979and your operation will likely be aborted. To use the 6980watch features, you must upgrade all copies of @sc{cvs} 6981which use that repository in local or server mode. If 6982you cannot upgrade, use the @code{watch off} and 6983@code{watch remove} commands to remove all watches, and 6984that will restore the repository to a state which 6985@sc{cvs} 1.6 can cope with. 6986 6987@node Choosing a model 6988@section Choosing between reserved or unreserved checkouts 6989@cindex Choosing, reserved or unreserved checkouts 6990 6991Reserved and unreserved checkouts each have pros and 6992cons. Let it be said that a lot of this is a matter of 6993opinion or what works given different groups' working 6994styles, but here is a brief description of some of the 6995issues. There are many ways to organize a team of 6996developers. @sc{cvs} does not try to enforce a certain 6997organization. It is a tool that can be used in several 6998ways. 6999 7000Reserved checkouts can be very counter-productive. If 7001two persons want to edit different parts of a file, 7002there may be no reason to prevent either of them from 7003doing so. Also, it is common for someone to take out a 7004lock on a file, because they are planning to edit it, 7005but then forget to release the lock. 7006 7007@c "many groups"? specifics? cites to papers on this? 7008@c some way to weasel-word it a bit more so we don't 7009@c need facts :-)? 7010People, especially people who are familiar with 7011reserved checkouts, often wonder how often conflicts 7012occur if unreserved checkouts are used, and how 7013difficult they are to resolve. The experience with 7014many groups is that they occur rarely and usually are 7015relatively straightforward to resolve. 7016 7017The rarity of serious conflicts may be surprising, until one realizes 7018that they occur only when two developers disagree on the proper design 7019for a given section of code; such a disagreement suggests that the 7020team has not been communicating properly in the first place. In order 7021to collaborate under @emph{any} source management regimen, developers 7022must agree on the general design of the system; given this agreement, 7023overlapping changes are usually straightforward to merge. 7024 7025In some cases unreserved checkouts are clearly 7026inappropriate. If no merge tool exists for the kind of 7027file you are managing (for example word processor files 7028or files edited by Computer Aided Design programs), and 7029it is not desirable to change to a program which uses a 7030mergeable data format, then resolving conflicts is 7031going to be unpleasant enough that you generally will 7032be better off to simply avoid the conflicts instead, by 7033using reserved checkouts. 7034 7035The watches features described above in @ref{Watches} 7036can be considered to be an intermediate model between 7037reserved checkouts and unreserved checkouts. When you 7038go to edit a file, it is possible to find out who else 7039is editing it. And rather than having the system 7040simply forbid both people editing the file, it can tell 7041you what the situation is and let you figure out 7042whether it is a problem in that particular case or not. 7043Therefore, for some groups watches can be 7044considered the best of both the reserved checkout and unreserved 7045checkout worlds. 7046 7047As of @sc{cvs} client and server versions 1.12.10, you may also enable 7048advisory locks by putting @samp{edit -c} and @samp{commit -c} in all 7049developers' @file{.cvsrc} files. After this is done, @code{cvs edit} 7050will fail if there are any other editors, and @code{cvs commit} will 7051fail if the committer has not registered to edit the file via @code{cvs edit}. 7052This is most effective in conjunction with files checked out read-only by 7053default, which may be enabled by turning on watches in the repository or by 7054putting @samp{cvs -r} in all @file{.cvsrc} files. 7055 7056 7057@c --------------------------------------------------------------------- 7058@node Revision management 7059@chapter Revision management 7060@cindex Revision management 7061 7062@c -- This chapter could be expanded a lot. 7063@c -- Experiences are very welcome! 7064 7065If you have read this far, you probably have a pretty 7066good grasp on what @sc{cvs} can do for you. This 7067chapter talks a little about things that you still have 7068to decide. 7069 7070If you are doing development on your own using @sc{cvs} 7071you could probably skip this chapter. The questions 7072this chapter takes up become more important when more 7073than one person is working in a repository. 7074 7075@menu 7076* When to commit:: Some discussion on the subject 7077@end menu 7078 7079@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7080@node When to commit 7081@section When to commit? 7082@cindex When to commit 7083@cindex Committing, when to 7084@cindex Policy 7085 7086Your group should decide which policy to use regarding 7087commits. Several policies are possible, and as your 7088experience with @sc{cvs} grows you will probably find 7089out what works for you. 7090 7091If you commit files too quickly you might commit files 7092that do not even compile. If your partner updates his 7093working sources to include your buggy file, he will be 7094unable to compile the code. On the other hand, other 7095persons will not be able to benefit from the 7096improvements you make to the code if you commit very 7097seldom, and conflicts will probably be more common. 7098 7099It is common to only commit files after making sure 7100that they can be compiled. Some sites require that the 7101files pass a test suite. Policies like this can be 7102enforced using the commitinfo file 7103(@pxref{commitinfo}), but you should think twice before 7104you enforce such a convention. By making the 7105development environment too controlled it might become 7106too regimented and thus counter-productive to the real 7107goal, which is to get software written. 7108 7109@c --------------------------------------------------------------------- 7110@node Keyword substitution 7111@chapter Keyword substitution 7112@cindex Keyword substitution 7113@cindex Keyword expansion 7114@cindex Identifying files 7115 7116@comment Be careful when editing this chapter. 7117@comment Remember that this file is kept under 7118@comment version control, so we must not accidentally 7119@comment include a valid keyword in the running text. 7120 7121As long as you edit source files inside a working 7122directory you can always find out the state of 7123your files via @samp{cvs status} and @samp{cvs log}. 7124But as soon as you export the files from your 7125development environment it becomes harder to identify 7126which revisions they are. 7127 7128@sc{cvs} can use a mechanism known as @dfn{keyword 7129substitution} (or @dfn{keyword expansion}) to help 7130identifying the files. Embedded strings of the form 7131@code{$@var{keyword}$} and 7132@code{$@var{keyword}:@dots{}$} in a file are replaced 7133with strings of the form 7134@code{$@var{keyword}:@var{value}$} whenever you obtain 7135a new revision of the file. 7136 7137@menu 7138* Keyword list:: Keywords 7139* Using keywords:: Using keywords 7140* Avoiding substitution:: Avoiding substitution 7141* Substitution modes:: Substitution modes 7142* Configuring keyword expansion:: Configuring keyword expansion 7143* Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. 7144@end menu 7145 7146@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7147@node Keyword list 7148@section Keyword List 7149@cindex Keyword List 7150 7151@c FIXME: need some kind of example here I think, 7152@c perhaps in a 7153@c "Keyword intro" node. The intro in the "Keyword 7154@c substitution" node itself seems OK, but to launch 7155@c into a list of the keywords somehow seems too abrupt. 7156 7157This is a list of the keywords: 7158 7159@table @code 7160@cindex Author keyword 7161@item $@splitrcskeyword{Author}$ 7162The login name of the user who checked in the revision. 7163 7164@cindex CVSHeader keyword 7165@item $@splitrcskeyword{CVSHeader}$ 7166A standard header (similar to $@splitrcskeyword{Header}$, but with 7167the CVS root stripped off). It contains the relative 7168pathname of the @sc{rcs} file to the CVS root, the 7169revision number, the date (UTC), the author, the state, 7170and the locker (if locked). Files will normally never 7171be locked when you use @sc{cvs}. 7172 7173Note that this keyword has only been recently 7174introduced to @sc{cvs} and may cause problems with 7175existing installations if $@splitrcskeyword{CVSHeader}$ is already 7176in the files for a different purpose. This keyword may 7177be excluded using the @code{KeywordExpand=eCVSHeader} 7178in the @file{CVSROOT/config} file. 7179See @ref{Configuring keyword expansion} for more details. 7180 7181@cindex Date keyword 7182@item $@splitrcskeyword{Date}$ 7183The date and time (UTC) the revision was checked in. 7184 7185@cindex Header keyword 7186@item $@splitrcskeyword{Header}$ 7187A standard header containing the full pathname of the 7188@sc{rcs} file, the revision number, the date (UTC), the 7189author, the state, and the locker (if locked). Files 7190will normally never be locked when you use @sc{cvs}. 7191 7192@cindex Id keyword 7193@item $@splitrcskeyword{Id}$ 7194Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} 7195filename is without a path. 7196 7197@cindex Name keyword 7198@item $@splitrcskeyword{Name}$ 7199Tag name used to check out this file. The keyword is 7200expanded only if one checks out with an explicit tag 7201name. For example, when running the command @code{cvs 7202co -r first}, the keyword expands to @samp{Name: first}. 7203 7204@cindex Locker keyword 7205@item $@splitrcskeyword{Locker}$ 7206The login name of the user who locked the revision 7207(empty if not locked, which is the normal case unless 7208@code{cvs admin -l} is in use). 7209 7210@cindex Log keyword 7211@cindex MaxCommentLeaderLength 7212@cindex UseArchiveCommentLeader 7213@cindex Log keyword, configuring substitution behavior 7214@item $@splitrcskeyword{Log}$ 7215The log message supplied during commit, preceded by a 7216header containing the @sc{rcs} filename, the revision 7217number, the author, and the date (UTC). Existing log 7218messages are @emph{not} replaced. Instead, the new log 7219message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}. 7220By default, each new line is prefixed with the same string which 7221precedes the @code{$@splitrcskeyword{Log}$} keyword, unless it exceeds the 7222@code{MaxCommentLeaderLength} set in @file{CVSROOT/config}. 7223 7224For example, if the file contains: 7225 7226@example 7227 /* Here is what people have been up to: 7228 * 7229 * $@splitrcskeyword{Log}: frob.c,v $ 7230 * Revision 1.1 1997/01/03 14:23:51 joe 7231 * Add the superfrobnicate option 7232 * 7233 */ 7234@end example 7235 7236@noindent 7237then additional lines which are added when expanding 7238the @code{$@splitrcskeyword{Log}$} keyword will be preceded by @samp{ * }. 7239Unlike previous versions of @sc{cvs} and @sc{rcs}, the 7240@dfn{comment leader} from the @sc{rcs} file is not used. 7241The @code{$@splitrcskeyword{Log}$} keyword is useful for 7242accumulating a complete change log in a source file, 7243but for several reasons it can be problematic. 7244 7245If the prefix of the @code{$@splitrcskeyword{Log}$} keyword turns out to be 7246longer than @code{MaxCommentLeaderLength}, CVS will skip expansion of this 7247keyword unless @code{UseArchiveCommentLeader} is also set in 7248@file{CVSROOT/config} and a @samp{comment leader} is set in the RCS archive 7249file, in which case the comment leader will be used instead. For more on 7250setting the comment leader in the RCS archive file, @xref{admin}. For more 7251on configuring the default @code{$@splitrcskeyword{Log}$} substitution 7252behavior, @xref{config}. 7253 7254@xref{Log keyword}. 7255 7256@cindex RCSfile keyword 7257@item $@splitrcskeyword{RCSfile}$ 7258The name of the RCS file without a path. 7259 7260@cindex Revision keyword 7261@item $@splitrcskeyword{Revision}$ 7262The revision number assigned to the revision. 7263 7264@cindex Source keyword 7265@item $@splitrcskeyword{Source}$ 7266The full pathname of the RCS file. 7267 7268@cindex State keyword 7269@item $@splitrcskeyword{State}$ 7270The state assigned to the revision. States can be 7271assigned with @code{cvs admin -s}---see @ref{admin options}. 7272 7273@cindex Local keyword 7274@item Local keyword 7275The @code{LocalKeyword} option in the @file{CVSROOT/config} file 7276may be used to specify a local keyword which is to be 7277used as an alias for one of the keywords: $@splitrcskeyword{Id}$, 7278$@splitrcskeyword{Header}$, or $@splitrcskeyword{CVSHeader}$. For 7279example, if the @file{CVSROOT/config} file contains 7280a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a 7281file with the local keyword $@splitrcskeyword{MYBSD}$ will be 7282expanded as if it were a $@splitrcskeyword{CVSHeader}$ keyword. If 7283the src/frob.c file contained this keyword, it might 7284look something like this: 7285 7286@example 7287 /* 7288 * $@splitrcskeyword{MYBSD}: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 7289 */ 7290@end example 7291 7292Many repositories make use of a such a ``local 7293keyword'' feature. An old patch to @sc{cvs} provided 7294the @code{LocalKeyword} feature using a @code{tag=} 7295option and called this the ``custom tag'' or ``local 7296tag'' feature. It was used in conjunction with the 7297what they called the @code{tagexpand=} option. In 7298@sc{cvs} this other option is known as the 7299@code{KeywordExpand} option. 7300See @ref{Configuring keyword expansion} for more 7301details. 7302 7303Examples from popular projects include: 7304$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7305$@splitrcskeyword{OpenBSD}$, $@splitrcskeyword{XFree86}$, 7306$@splitrcskeyword{Xorg}$. 7307 7308The advantage of this is that you can include your 7309local version information in a file using this local 7310keyword without disrupting the upstream version 7311information (which may be a different local keyword or 7312a standard keyword). Allowing bug reports and the like 7313to more properly identify the source of the original 7314bug to the third-party and reducing the number of 7315conflicts that arise during an import of a new version. 7316 7317All keyword expansion except the local keyword may be 7318disabled using the @code{KeywordExpand} option in 7319the @file{CVSROOT/config} file---see 7320@ref{Configuring keyword expansion} for more details. 7321 7322@end table 7323 7324@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7325@node Using keywords 7326@section Using keywords 7327 7328To include a keyword string you simply include the 7329relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the 7330file, and commit the file. @sc{cvs} will automatically (Or, 7331more accurately, as part of the update run that 7332automatically happens after a commit.) 7333expand the string as part of the commit operation. 7334 7335It is common to embed the @code{$@splitrcskeyword{Id}$} string in 7336the source files so that it gets passed through to 7337generated files. For example, if you are managing 7338computer program source code, you might include a 7339variable which is initialized to contain that string. 7340Or some C compilers may provide a @code{#pragma ident} 7341directive. Or a document management system might 7342provide a way to pass a string through to generated 7343files. 7344 7345@c Would be nice to give an example, but doing this in 7346@c portable C is not possible and the problem with 7347@c picking any one language (VMS HELP files, Ada, 7348@c troff, whatever) is that people use CVS for all 7349@c kinds of files. 7350 7351@cindex Ident (shell command) 7352The @code{ident} command (which is part of the @sc{rcs} 7353package) can be used to extract keywords and their 7354values from a file. This can be handy for text files, 7355but it is even more useful for extracting keywords from 7356binary files. 7357 7358@example 7359$ ident samp.c 7360samp.c: 7361 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7362$ gcc samp.c 7363$ ident a.out 7364a.out: 7365 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7366@end example 7367 7368@cindex What (shell command) 7369S@sc{ccs} is another popular revision control system. 7370It has a command, @code{what}, which is very similar to 7371@code{ident} and used for the same purpose. Many sites 7372without @sc{rcs} have @sc{sccs}. Since @code{what} 7373looks for the character sequence @code{@@(#)} it is 7374easy to include keywords that are detected by either 7375command. Simply prefix the keyword with the 7376magic @sc{sccs} phrase, like this: 7377 7378@example 7379static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 7380@end example 7381 7382@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7383@node Avoiding substitution 7384@section Avoiding substitution 7385 7386Keyword substitution has its disadvantages. Sometimes 7387you might want the literal text string 7388@samp{$@splitrcskeyword{Author}$} to appear inside a file without 7389@sc{cvs} interpreting it as a keyword and expanding it 7390into something like @samp{$@splitrcskeyword{Author}: ceder $}. 7391 7392There is unfortunately no way to selectively turn off 7393keyword substitution. You can use @samp{-ko} 7394(@pxref{Substitution modes}) to turn off keyword 7395substitution entirely. 7396 7397In many cases you can avoid using keywords in 7398the source, even though they appear in the final 7399product. For example, the source for this manual 7400contains @samp{$@@asis@{@}Author$} whenever the text 7401@samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff} 7402and @code{troff} you can embed the null-character 7403@code{\&} inside the keyword for a similar effect. 7404 7405It is also possible to specify an explicit list of 7406keywords to include or exclude using the 7407@code{KeywordExpand} option in the 7408@file{CVSROOT/config} file--see @ref{Configuring keyword expansion} 7409for more details. This feature is intended primarily 7410for use with the @code{LocalKeyword} option--see 7411@ref{Keyword list}. 7412 7413@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7414@node Substitution modes 7415@section Substitution modes 7416@cindex Keyword substitution, changing modes 7417@cindex -k (keyword substitution) 7418@cindex Kflag 7419 7420@c FIXME: This could be made more coherent, by expanding it 7421@c with more examples or something. 7422Each file has a stored default substitution mode, and 7423each working directory copy of a file also has a 7424substitution mode. The former is set by the @samp{-k} 7425option to @code{cvs add} and @code{cvs admin}; the 7426latter is set by the @samp{-k} or @samp{-A} options to @code{cvs 7427checkout} or @code{cvs update}. 7428@code{cvs diff} and @code{cvs rdiff} also 7429have @samp{-k} options. 7430For some examples, 7431see @ref{Binary files}, and @ref{Merging and keywords}. 7432@c The fact that -A is overloaded to mean both reset 7433@c sticky options and reset sticky tags/dates is 7434@c somewhat questionable. Perhaps there should be 7435@c separate options to reset sticky options (e.g. -k 7436@c A") and tags/dates (someone suggested -r HEAD could 7437@c do this instead of setting a sticky tag of "HEAD" 7438@c as in the status quo but I haven't thought much 7439@c about that idea. Of course -r .reset or something 7440@c could be coined if this needs to be a new option). 7441@c On the other hand, having -A mean "get things back 7442@c into the state after a fresh checkout" has a certain 7443@c appeal, and maybe there is no sufficient reason for 7444@c creeping featurism in this area. 7445 7446The modes available are: 7447 7448@table @samp 7449@item -kkv 7450Generate keyword strings using the default form, e.g. 7451@code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision} 7452keyword. 7453 7454@item -kkvl 7455Like @samp{-kkv}, except that a locker's name is always 7456inserted if the given revision is currently locked. 7457The locker's name is only relevant if @code{cvs admin 7458-l} is in use. 7459 7460@item -kk 7461Generate only keyword names in keyword strings; omit 7462their values. For example, for the @code{Revision} 7463keyword, generate the string @code{$@splitrcskeyword{Revision}$} 7464instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option 7465is useful to ignore differences due to keyword 7466substitution when comparing different revisions of a 7467file (@pxref{Merging and keywords}). 7468 7469@item -ko 7470Generate the old keyword string, present in the working 7471file just before it was checked in. For example, for 7472the @code{Revision} keyword, generate the string 7473@code{$@splitrcskeyword{Revision}: 1.1 $} instead of 7474@code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the 7475string appeared when the file was checked in. 7476 7477@item -kb 7478Like @samp{-ko}, but also inhibit conversion of line 7479endings between the canonical form in which they are 7480stored in the repository (linefeed only), and the form 7481appropriate to the operating system in use on the 7482client. For systems, like unix, which use linefeed 7483only to terminate lines, this is very similar to 7484@samp{-ko}. For more information on binary files, see 7485@ref{Binary files}. In @sc{cvs} version 1.12.2 and later 7486@samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or 7487@code{cvs import} may not be overridden by a @samp{-k} option 7488specified on the command line. 7489 7490@item -kv 7491Generate only keyword values for keyword strings. For 7492example, for the @code{Revision} keyword, generate the string 7493@code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. 7494This can help generate files in programming languages 7495where it is hard to strip keyword delimiters like 7496@code{$@splitrcskeyword{Revision}: $} from a string. However, 7497further keyword substitution cannot be performed once 7498the keyword names are removed, so this option should be 7499used with care. 7500 7501One often would like to use @samp{-kv} with @code{cvs 7502export}---@pxref{export}. But be aware that doesn't 7503handle an export containing binary files correctly. 7504 7505@end table 7506 7507@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7508@node Configuring keyword expansion 7509@section Configuring Keyword Expansion 7510@cindex Configuring keyword expansion 7511 7512In a repository that includes third-party software on 7513vendor branches, it is sometimes helpful to configure 7514CVS to use a local keyword instead of the standard 7515$@splitrcskeyword{Id}$ or $@splitrcskeyword{Header}$ keywords. Examples from 7516real projects include $@splitrcskeyword{Xorg}$, $@splitrcskeyword{XFree86}$, 7517$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7518$@splitrcskeyword{OpenBSD}$, and even $@splitrcskeyword{dotat}$. 7519The advantage of this is that 7520you can include your local version information in a 7521file using this local keyword (sometimes called a 7522``custom tag'' or a ``local tag'') without disrupting 7523the upstream version information (which may be a 7524different local keyword or a standard keyword). In 7525these cases, it is typically desirable to disable the 7526expansion of all keywords except the configured local 7527keyword. 7528 7529The @code{KeywordExpand} option in the 7530@file{CVSROOT/config} file is intended to allow for the 7531either the explicit exclusion of a keyword or list of 7532keywords, or for the explicit inclusion of a keyword or 7533a list of keywords. This list may include the 7534@code{LocalKeyword} that has been configured. 7535 7536The @code{KeywordExpand} option is followed by 7537@code{=} and the next character may either be @code{i} 7538to start an inclusion list or @code{e} to start an 7539exclusion list. If the following lines were added to 7540the @file{CVSROOT/config} file: 7541 7542@example 7543 # Add a "MyBSD" keyword and restrict keyword 7544 # expansion 7545 LocalKeyword=MyBSD=CVSHeader 7546 KeywordExpand=iMyBSD 7547@end example 7548 7549then only the $@splitrcskeyword{MyBSD}$ keyword would be expanded. 7550A list may be used. The this example: 7551 7552@example 7553 # Add a "MyBSD" keyword and restrict keyword 7554 # expansion to the MyBSD, Name and Date keywords. 7555 LocalKeyword=MyBSD=CVSHeader 7556 KeywordExpand=iMyBSD,Name,Date 7557@end example 7558 7559would allow $@splitrcskeyword{MyBSD}$, $@splitrcskeyword{Name}$, and 7560$@splitrcskeyword{Date}$ to be expanded. 7561 7562It is also possible to configure an exclusion list 7563using the following: 7564 7565@example 7566 # Do not expand the non-RCS keyword CVSHeader 7567 KeywordExpand=eCVSHeader 7568@end example 7569 7570This allows @sc{cvs} to ignore the recently introduced 7571$@splitrcskeyword{CVSHeader}$ keyword and retain all of the 7572others. The exclusion entry could also contain the 7573standard RCS keyword list, but this could be confusing 7574to users that expect RCS keywords to be expanded, so 7575care should be taken to properly set user expectations 7576for a repository that is configured in that manner. 7577 7578If there is a desire to not have any RCS keywords 7579expanded and not use the @code{-ko} flags everywhere, 7580an administrator may disable all keyword expansion 7581using the @file{CVSROOT/config} line: 7582 7583@example 7584 # Do not expand any RCS keywords 7585 KeywordExpand=i 7586@end example 7587 7588this could be confusing to users that expect RCS 7589keywords like $@splitrcskeyword{Id}$ to be expanded properly, 7590so care should be taken to properly set user 7591expectations for a repository so configured. 7592 7593It should be noted that a patch to provide both the 7594@code{KeywordExpand} and @code{LocalKeyword} features 7595has been around a long time. However, that patch 7596implemented these features using @code{tag=} and 7597@code{tagexpand=} keywords and those keywords are NOT 7598recognized. 7599 7600@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7601@node Log keyword 7602@section Problems with the $@splitrcskeyword{Log}$ keyword. 7603 7604The @code{$@splitrcskeyword{Log}$} keyword is somewhat 7605controversial. As long as you are working on your 7606development system the information is easily accessible 7607even if you do not use the @code{$@splitrcskeyword{Log}$} 7608keyword---just do a @code{cvs log}. Once you export 7609the file the history information might be useless 7610anyhow. 7611 7612A more serious concern is that @sc{cvs} is not good at 7613handling @code{$@splitrcskeyword{Log}$} entries when a branch is 7614merged onto the main trunk. Conflicts often result 7615from the merging operation. 7616@c Might want to check whether the CVS implementation 7617@c of RCS_merge has this problem the same way rcsmerge 7618@c does. I would assume so.... 7619 7620People also tend to "fix" the log entries in the file 7621(correcting spelling mistakes and maybe even factual 7622errors). If that is done the information from 7623@code{cvs log} will not be consistent with the 7624information inside the file. This may or may not be a 7625problem in real life. 7626 7627It has been suggested that the @code{$@splitrcskeyword{Log}$} 7628keyword should be inserted @emph{last} in the file, and 7629not in the files header, if it is to be used at all. 7630That way the long list of change messages will not 7631interfere with everyday source file browsing. 7632 7633@c --------------------------------------------------------------------- 7634@node Tracking sources 7635@chapter Tracking third-party sources 7636@cindex Third-party sources 7637@cindex Tracking sources 7638 7639@c FIXME: Need discussion of added and removed files. 7640@c FIXME: This doesn't really adequately introduce the 7641@c concepts of "vendor" and "you". They don't *have* 7642@c to be separate organizations or separate people. 7643@c We want a description which is somewhat more based on 7644@c the technical issues of which sources go where, but 7645@c also with enough examples of how this relates to 7646@c relationships like customer-supplier, developer-QA, 7647@c maintainer-contributor, or whatever, to make it 7648@c seem concrete. 7649If you modify a program to better fit your site, you 7650probably want to include your modifications when the next 7651release of the program arrives. @sc{cvs} can help you with 7652this task. 7653 7654@cindex Vendor 7655@cindex Vendor branch 7656@cindex Branch, vendor- 7657In the terminology used in @sc{cvs}, the supplier of the 7658program is called a @dfn{vendor}. The unmodified 7659distribution from the vendor is checked in on its own 7660branch, the @dfn{vendor branch}. @sc{cvs} reserves branch 76611.1.1 for this use. 7662 7663When you modify the source and commit it, your revision 7664will end up on the main trunk. When a new release is 7665made by the vendor, you commit it on the vendor branch 7666and copy the modifications onto the main trunk. 7667 7668Use the @code{import} command to create and update 7669the vendor branch. When you import a new file, 7670(usually) the vendor branch is made the `head' revision, so 7671anyone that checks out a copy of the file gets that 7672revision. When a local modification is committed it is 7673placed on the main trunk, and made the `head' 7674revision. 7675 7676@menu 7677* First import:: Importing for the first time 7678* Update imports:: Updating with the import command 7679* Reverting local changes:: Reverting to the latest vendor release 7680* Binary files in imports:: Binary files require special handling 7681* Keywords in imports:: Keyword substitution might be undesirable 7682* Multiple vendor branches:: What if you get sources from several places? 7683@end menu 7684 7685@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7686@node First import 7687@section Importing for the first time 7688@cindex Importing modules 7689 7690@c Should mention naming conventions for vendor tags, 7691@c release tags, and perhaps directory names. 7692Use the @code{import} command to check in the sources 7693for the first time. When you use the @code{import} 7694command to track third-party sources, the @dfn{vendor 7695tag} and @dfn{release tags} are useful. The 7696@dfn{vendor tag} is a symbolic name for the branch 7697(which is always 1.1.1, unless you use the @samp{-b 7698@var{branch}} flag---see @ref{Multiple vendor branches}.). The 7699@dfn{release tags} are symbolic names for a particular 7700release, such as @samp{FSF_0_04}. 7701 7702@c I'm not completely sure this belongs here. But 7703@c we need to say it _somewhere_ reasonably obvious; it 7704@c is a common misconception among people first learning CVS 7705Note that @code{import} does @emph{not} change the 7706directory in which you invoke it. In particular, it 7707does not set up that directory as a @sc{cvs} working 7708directory; if you want to work with the sources import 7709them first and then check them out into a different 7710directory (@pxref{Getting the source}). 7711 7712@cindex wdiff (import example) 7713Suppose you have the sources to a program called 7714@code{wdiff} in a directory @file{wdiff-0.04}, 7715and are going to make private modifications that you 7716want to be able to use even when new releases are made 7717in the future. You start by importing the source to 7718your repository: 7719 7720@example 7721$ cd wdiff-0.04 7722$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 7723@end example 7724 7725The vendor tag is named @samp{FSF_DIST} in the above 7726example, and the only release tag assigned is 7727@samp{WDIFF_0_04}. 7728@c FIXME: Need to say where fsf/wdiff comes from. 7729 7730@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7731@node Update imports 7732@section Updating with the import command 7733 7734When a new release of the source arrives, you import it into the 7735repository with the same @code{import} command that you used to set up 7736the repository in the first place. The only difference is that you 7737specify a different release tag this time: 7738 7739@example 7740$ tar xfz wdiff-0.05.tar.gz 7741$ cd wdiff-0.05 7742$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 7743@end example 7744 7745@strong{WARNING: If you use a release tag that already exists in one of the 7746repository archives, files removed by an import may not be detected.} 7747 7748For files that have not been modified locally, the newly created 7749revision becomes the head revision. If you have made local 7750changes, @code{import} will warn you that you must merge the changes 7751into the main trunk, and tell you to use @samp{checkout -j} to do so: 7752 7753@c FIXME: why "wdiff" here and "fsf/wdiff" in the 7754@c "import"? I think the assumption is that one has 7755@c "wdiff fsf/wdiff" or some such in modules, but it 7756@c would be better to not use modules in this example. 7757@example 7758$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 7759@end example 7760 7761@noindent 7762The above command will check out the latest revision of 7763@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 7764since yesterday into the working copy. If any conflicts arise during 7765the merge they should be resolved in the normal way (@pxref{Conflicts 7766example}). Then, the modified files may be committed. 7767 7768However, it is much better to use the two release tags rather than using 7769a date on the branch as suggested above: 7770 7771@example 7772$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 7773@end example 7774 7775@noindent 7776The reason this is better is that 7777using a date, as suggested above, assumes that you do 7778not import more than one release of a product per day. 7779More importantly, using the release tags allows @sc{cvs} to detect files 7780that were removed between the two vendor releases and mark them for 7781removal. Since @code{import} has no way to detect removed files, you 7782should do a merge like this even if @code{import} doesn't tell you to. 7783 7784@node Reverting local changes 7785@section Reverting to the latest vendor release 7786 7787You can also revert local changes completely and return 7788to the latest vendor release by changing the `head' 7789revision back to the vendor branch on all files. For 7790example, if you have a checked-out copy of the sources 7791in @file{~/work.d/wdiff}, and you want to revert to the 7792vendor's version for all the files in that directory, 7793you would type: 7794 7795@example 7796$ cd ~/work.d/wdiff 7797$ cvs admin -bFSF_DIST . 7798@end example 7799 7800@noindent 7801You must specify the @samp{-bFSF_DIST} without any space 7802after the @samp{-b}. @xref{admin options}. 7803 7804@node Binary files in imports 7805@section How to handle binary files with cvs import 7806 7807Use the @samp{-k} wrapper option to tell import which 7808files are binary. @xref{Wrappers}. 7809 7810@node Keywords in imports 7811@section How to handle keyword substitution with cvs import 7812 7813The sources which you are importing may contain 7814keywords (@pxref{Keyword substitution}). For example, 7815the vendor may use @sc{cvs} or some other system 7816which uses similar keyword expansion syntax. If you 7817just import the files in the default fashion, then 7818the keyword expansions supplied by the vendor will 7819be replaced by keyword expansions supplied by your 7820own copy of @sc{cvs}. It may be more convenient to 7821maintain the expansions supplied by the vendor, so 7822that this information can supply information about 7823the sources that you imported from the vendor. 7824 7825To maintain the keyword expansions supplied by the 7826vendor, supply the @samp{-ko} option to @code{cvs 7827import} the first time you import the file. 7828This will turn off keyword expansion 7829for that file entirely, so if you want to be more 7830selective you'll have to think about what you want 7831and use the @samp{-k} option to @code{cvs update} or 7832@code{cvs admin} as appropriate. 7833@c Supplying -ko to import if the file already existed 7834@c has no effect. Not clear to me whether it should 7835@c or not. 7836 7837@node Multiple vendor branches 7838@section Multiple vendor branches 7839 7840All the examples so far assume that there is only one 7841vendor from which you are getting sources. In some 7842situations you might get sources from a variety of 7843places. For example, suppose that you are dealing with 7844a project where many different people and teams are 7845modifying the software. There are a variety of ways to 7846handle this, but in some cases you have a bunch of 7847source trees lying around and what you want to do more 7848than anything else is just to all put them in @sc{cvs} so 7849that you at least have them in one place. 7850 7851For handling situations in which there may be more than 7852one vendor, you may specify the @samp{-b} option to 7853@code{cvs import}. It takes as an argument the vendor 7854branch to import to. The default is @samp{-b 1.1.1}. 7855 7856For example, suppose that there are two teams, the red 7857team and the blue team, that are sending you sources. 7858You want to import the red team's efforts to branch 78591.1.1 and use the vendor tag RED. You want to import 7860the blue team's efforts to branch 1.1.3 and use the 7861vendor tag BLUE. So the commands you might use are: 7862 7863@example 7864$ cvs import dir RED RED_1-0 7865$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 7866@end example 7867 7868Note that if your vendor tag does not match your 7869@samp{-b} option, @sc{cvs} will not detect this case! For 7870example, 7871 7872@example 7873$ cvs import -b 1.1.3 dir RED RED_1-0 7874@end example 7875 7876@noindent 7877Be careful; this kind of mismatch is sure to sow 7878confusion or worse. I can't think of a useful purpose 7879for the ability to specify a mismatch here, but if you 7880discover such a use, don't. @sc{cvs} is likely to make this 7881an error in some future release. 7882 7883@c Probably should say more about the semantics of 7884@c multiple branches. What about the default branch? 7885@c What about joining (perhaps not as useful with 7886@c multiple branches, or perhaps it is. Either way 7887@c should be mentioned). 7888 7889@c I'm not sure about the best location for this. In 7890@c one sense, it might belong right after we've introduced 7891@c CVS's basic version control model, because people need 7892@c to figure out builds right away. The current location 7893@c is based on the theory that it kind of akin to the 7894@c "Revision management" section. 7895@node Builds 7896@chapter How your build system interacts with CVS 7897@cindex Builds 7898@cindex make 7899 7900As mentioned in the introduction, @sc{cvs} does not 7901contain software for building your software from source 7902code. This section describes how various aspects of 7903your build system might interact with @sc{cvs}. 7904 7905@c Is there a way to discuss this without reference to 7906@c tools other than CVS? I'm not sure there is; I 7907@c wouldn't think that people who learn CVS first would 7908@c even have this concern. 7909One common question, especially from people who are 7910accustomed to @sc{rcs}, is how to make their build get 7911an up to date copy of the sources. The answer to this 7912with @sc{cvs} is two-fold. First of all, since 7913@sc{cvs} itself can recurse through directories, there 7914is no need to modify your @file{Makefile} (or whatever 7915configuration file your build tool uses) to make sure 7916each file is up to date. Instead, just use two 7917commands, first @code{cvs -q update} and then 7918@code{make} or whatever the command is to invoke your 7919build tool. Secondly, you do not necessarily 7920@emph{want} to get a copy of a change someone else made 7921until you have finished your own work. One suggested 7922approach is to first update your sources, then 7923implement, build and 7924test the change you were thinking of, and then commit 7925your sources (updating first if necessary). By 7926periodically (in between changes, using the approach 7927just described) updating your entire tree, you ensure 7928that your sources are sufficiently up to date. 7929 7930@cindex Bill of materials 7931One common need is to record which versions of which 7932source files went into a particular build. This kind 7933of functionality is sometimes called @dfn{bill of 7934materials} or something similar. The best way to do 7935this with @sc{cvs} is to use the @code{tag} command to 7936record which versions went into a given build 7937(@pxref{Tags}). 7938 7939Using @sc{cvs} in the most straightforward manner 7940possible, each developer will have a copy of the entire 7941source tree which is used in a particular build. If 7942the source tree is small, or if developers are 7943geographically dispersed, this is the preferred 7944solution. In fact one approach for larger projects is 7945to break a project down into smaller 7946@c I say subsystem instead of module because they may or 7947@c may not use the modules file. 7948separately-compiled subsystems, and arrange a way of 7949releasing them internally so that each developer need 7950check out only those subsystems which they are 7951actively working on. 7952 7953Another approach is to set up a structure which allows 7954developers to have their own copies of some files, and 7955for other files to access source files from a central 7956location. Many people have come up with some such a 7957@c two such people are paul@sander.cupertino.ca.us (for 7958@c a previous employer) 7959@c and gunnar.tornblom@se.abb.com (spicm and related tools), 7960@c but as far as I know 7961@c no one has nicely packaged or released such a system (or 7962@c instructions for constructing one). 7963system using features such as the symbolic link feature 7964found in many operating systems, or the @code{VPATH} 7965feature found in many versions of @code{make}. One build 7966tool which is designed to help with this kind of thing 7967is Odin (see 7968@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 7969@c Should we be saying more about Odin? Or how you use 7970@c it with CVS? Also, the Prime Time Freeware for Unix 7971@c disk (see http://www.ptf.com/) has Odin (with a nice 7972@c paragraph summarizing it on the web), so that might be a 7973@c semi-"official" place to point people. 7974@c 7975@c Of course, many non-CVS systems have this kind of 7976@c functionality, for example OSF's ODE 7977@c (http://www.osf.org/ode/) or mk 7978@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 7979@c He has changed providers in the past; a search engine search 7980@c for "Peter Ziobrzynski" probably won't get too many 7981@c spurious hits :-). A more stable URL might be 7982@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 7983@c there is any point in mentioning them here unless they 7984@c can work with CVS. 7985 7986@c --------------------------------------------------------------------- 7987@node Special Files 7988@chapter Special Files 7989 7990@cindex Special files 7991@cindex Device nodes 7992@cindex Ownership, saving in CVS 7993@cindex Permissions, saving in CVS 7994@cindex Hard links 7995@cindex Symbolic links 7996 7997In normal circumstances, @sc{cvs} works only with regular 7998files. Every file in a project is assumed to be 7999persistent; it must be possible to open, read and close 8000them; and so on. @sc{cvs} also ignores file permissions and 8001ownerships, leaving such issues to be resolved by the 8002developer at installation time. In other words, it is 8003not possible to "check in" a device into a repository; 8004if the device file cannot be opened, @sc{cvs} will refuse to 8005handle it. Files also lose their ownerships and 8006permissions during repository transactions. 8007 8008@ignore 8009If the configuration variable @code{PreservePermissions} 8010(@pxref{config}) is set in the repository, @sc{cvs} will 8011save the following file characteristics in the 8012repository: 8013 8014@itemize @bullet 8015@item user and group ownership 8016@item permissions 8017@item major and minor device numbers 8018@item symbolic links 8019@item hard link structure 8020@end itemize 8021 8022Using the @code{PreservePermissions} option affects the 8023behavior of @sc{cvs} in several ways. First, some of the 8024new operations supported by @sc{cvs} are not accessible to 8025all users. In particular, file ownership and special 8026file characteristics may only be changed by the 8027superuser. When the @code{PreservePermissions} 8028configuration variable is set, therefore, users will 8029have to be `root' in order to perform @sc{cvs} operations. 8030 8031When @code{PreservePermissions} is in use, some @sc{cvs} 8032operations (such as @samp{cvs status}) will not 8033recognize a file's hard link structure, and so will 8034emit spurious warnings about mismatching hard links. 8035The reason is that @sc{cvs}'s internal structure does not 8036make it easy for these operations to collect all the 8037necessary data about hard links, so they check for file 8038conflicts with inaccurate data. 8039 8040A more subtle difference is that @sc{cvs} considers a file 8041to have changed only if its contents have changed 8042(specifically, if the modification time of the working 8043file does not match that of the repository's file). 8044Therefore, if only the permissions, ownership or hard 8045linkage have changed, or if a device's major or minor 8046numbers have changed, @sc{cvs} will not notice. In order to 8047commit such a change to the repository, you must force 8048the commit with @samp{cvs commit -f}. This also means 8049that if a file's permissions have changed and the 8050repository file is newer than the working copy, 8051performing @samp{cvs update} will silently change the 8052permissions on the working copy. 8053 8054Changing hard links in a @sc{cvs} repository is particularly 8055delicate. Suppose that file @file{foo} is linked to 8056file @file{old}, but is later relinked to file 8057@file{new}. You can wind up in the unusual situation 8058where, although @file{foo}, @file{old} and @file{new} 8059have all had their underlying link patterns changed, 8060only @file{foo} and @file{new} have been modified, so 8061@file{old} is not considered a candidate for checking 8062in. It can be very easy to produce inconsistent 8063results this way. Therefore, we recommend that when it 8064is important to save hard links in a repository, the 8065prudent course of action is to @code{touch} any file 8066whose linkage or status has changed since the last 8067checkin. Indeed, it may be wise to @code{touch *} 8068before each commit in a directory with complex hard 8069link structures. 8070 8071It is worth noting that only regular files may 8072be merged, for reasons that hopefully are obvious. If 8073@samp{cvs update} or @samp{cvs checkout -j} attempts to 8074merge a symbolic link with a regular file, or two 8075device files for different kinds of devices, @sc{cvs} will 8076report a conflict and refuse to perform the merge. At 8077the same time, @samp{cvs diff} will not report any 8078differences between these files, since no meaningful 8079textual comparisons can be made on files which contain 8080no text. 8081 8082The @code{PreservePermissions} features do not work 8083with client/server @sc{cvs}. Another limitation is 8084that hard links must be to other files within the same 8085directory; hard links across directories are not 8086supported. 8087@end ignore 8088 8089@c --------------------------------------------------------------------- 8090@c ----- START MAN 1 ----- 8091@node CVS commands 8092@appendix Guide to CVS commands 8093 8094This appendix describes the overall structure of 8095@sc{cvs} commands, and describes some commands in 8096detail (others are described elsewhere; for a quick 8097reference to @sc{cvs} commands, @pxref{Invoking CVS}). 8098@c The idea is that we want to move the commands which 8099@c are described here into the main body of the manual, 8100@c in the process reorganizing the manual to be 8101@c organized around what the user wants to do, not 8102@c organized around CVS commands. 8103@c 8104@c Note that many users do expect a manual which is 8105@c organized by command. At least some users do. 8106@c One good addition to the "organized by command" 8107@c section (if any) would be "see also" links. 8108@c The awk manual might be a good example; it has a 8109@c reference manual which is more verbose than Invoking 8110@c CVS but probably somewhat less verbose than CVS 8111@c Commands. 8112 8113@menu 8114* Structure:: Overall structure of CVS commands 8115* Exit status:: Indicating CVS's success or failure 8116* ~/.cvsrc:: Default options with the ~/.cvsrc file 8117* Global options:: Options you give to the left of cvs_command 8118* Common options:: Options you give to the right of cvs_command 8119* Date input formats:: Acceptable formats for date specifications 8120* admin:: Administration 8121* annotate:: What revision modified each line of a file? 8122* checkout:: Checkout sources for editing 8123* commit:: Check files into the repository 8124* diff:: Show differences between revisions 8125* export:: Export sources from CVS, similar to checkout 8126* history:: Show status of files and users 8127* import:: Import sources into CVS, using vendor branches 8128* log:: Show log messages for files 8129* ls & rls:: List files in the repository 8130* rdiff:: 'patch' format diffs between releases 8131* release:: Indicate that a directory is no longer in use 8132* server & pserver:: Act as a server for a client on stdin/stdout 8133* update:: Bring work tree in sync with repository 8134@end menu 8135 8136@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8137@node Structure 8138@appendixsec Overall structure of CVS commands 8139@cindex Structure 8140@cindex CVS command structure 8141@cindex Command structure 8142@cindex Format of CVS commands 8143 8144The overall format of all @sc{cvs} commands is: 8145 8146@example 8147cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 8148@end example 8149 8150@table @code 8151@item cvs 8152The name of the @sc{cvs} program. 8153 8154@item cvs_options 8155Some options that affect all sub-commands of @sc{cvs}. These are 8156described below. 8157 8158@item cvs_command 8159One of several different sub-commands. Some of the commands have 8160aliases that can be used instead; those aliases are noted in the 8161reference manual for that command. There are only two situations 8162where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 8163list of available commands, and @samp{cvs -v} displays version 8164information on @sc{cvs} itself. 8165 8166@item command_options 8167Options that are specific for the command. 8168 8169@item command_args 8170Arguments to the commands. 8171@end table 8172 8173There is unfortunately some confusion between 8174@code{cvs_options} and @code{command_options}. 8175When given as a @code{cvs_option}, some options only 8176affect some of the commands. When given as a 8177@code{command_option} it may have a different meaning, and 8178be accepted by more commands. In other words, do not 8179take the above categorization too seriously. Look at 8180the documentation instead. 8181 8182@node Exit status 8183@appendixsec CVS's exit status 8184@cindex Exit status, of CVS 8185 8186@sc{cvs} can indicate to the calling environment whether it 8187succeeded or failed by setting its @dfn{exit status}. 8188The exact way of testing the exit status will vary from 8189one operating system to another. For example in a unix 8190shell script the @samp{$?} variable will be 0 if the 8191last command returned a successful exit status, or 8192greater than 0 if the exit status indicated failure. 8193 8194If @sc{cvs} is successful, it returns a successful status; 8195if there is an error, it prints an error message and 8196returns a failure status. The one exception to this is 8197the @code{cvs diff} command. It will return a 8198successful status if it found no differences, or a 8199failure status if there were differences or if there 8200was an error. Because this behavior provides no good 8201way to detect errors, in the future it is possible that 8202@code{cvs diff} will be changed to behave like the 8203other @sc{cvs} commands. 8204@c It might seem like checking whether cvs -q diff 8205@c produces empty or non-empty output can tell whether 8206@c there were differences or not. But it seems like 8207@c there are cases with output but no differences 8208@c (testsuite basica-8b). It is not clear to me how 8209@c useful it is for a script to be able to check 8210@c whether there were differences. 8211@c FIXCVS? In previous versions of CVS, cvs diff 8212@c returned 0 for no differences, 1 for differences, or 8213@c 2 for errors. Is this behavior worth trying to 8214@c bring back (but what does it mean for VMS?)? 8215 8216@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8217@node ~/.cvsrc 8218@appendixsec Default options and the ~/.cvsrc file 8219@cindex .cvsrc file 8220@cindex Option defaults 8221 8222There are some @code{command_options} that are used so 8223often that you might have set up an alias or some other 8224means to make sure you always specify that option. One 8225example (the one that drove the implementation of the 8226@file{.cvsrc} support, actually) is that many people find the 8227default output of the @samp{diff} command to be very 8228hard to read, and that either context diffs or unidiffs 8229are much easier to understand. 8230 8231The @file{~/.cvsrc} file is a way that you can add 8232default options to @code{cvs_commands} within cvs, 8233instead of relying on aliases or other shell scripts. 8234 8235The format of the @file{~/.cvsrc} file is simple. The 8236file is searched for a line that begins with the same 8237name as the @code{cvs_command} being executed. If a 8238match is found, then the remainder of the line is split 8239up (at whitespace characters) into separate options and 8240added to the command arguments @emph{before} any 8241options from the command line. 8242 8243If a command has two names (e.g., @code{checkout} and 8244@code{co}), the official name, not necessarily the one 8245used on the command line, will be used to match against 8246the file. So if this is the contents of the user's 8247@file{~/.cvsrc} file: 8248 8249@example 8250log -N 8251diff -uN 8252rdiff -u 8253update -Pd 8254checkout -P 8255release -d 8256@end example 8257 8258@noindent 8259the command @samp{cvs checkout foo} would have the 8260@samp{-P} option added to the arguments, as well as 8261@samp{cvs co foo}. 8262 8263With the example file above, the output from @samp{cvs 8264diff foobar} will be in unidiff format. @samp{cvs diff 8265-c foobar} will provide context diffs, as usual. 8266Getting "old" format diffs would be slightly more 8267complicated, because @code{diff} doesn't have an option 8268to specify use of the "old" format, so you would need 8269@samp{cvs -f diff foobar}. 8270 8271In place of the command name you can use @code{cvs} to 8272specify global options (@pxref{Global options}). For 8273example the following line in @file{.cvsrc} 8274 8275@example 8276cvs -z6 8277@end example 8278 8279@noindent 8280causes @sc{cvs} to use compression level 6. 8281 8282@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8283@node Global options 8284@appendixsec Global options 8285@cindex Options, global 8286@cindex Global options 8287@cindex Left-hand options 8288 8289The available @samp{cvs_options} (that are given to the 8290left of @samp{cvs_command}) are: 8291 8292@table @code 8293@item --allow-root=@var{rootdir} 8294May be invoked multiple times to specify one legal @sc{cvsroot} directory with 8295each invocation. Also causes CVS to preparse the configuration file for each 8296specified root, which can be useful when configuring write proxies, See 8297@ref{Password authentication server} & @ref{Write proxies}. 8298 8299@cindex Authentication, stream 8300@cindex Stream authentication 8301@item -a 8302Authenticate all communication between the client and 8303the server. Only has an effect on the @sc{cvs} client. 8304As of this writing, this is only implemented when using 8305a GSSAPI connection (@pxref{GSSAPI authenticated}). 8306Authentication prevents certain sorts of attacks 8307involving hijacking the active @sc{tcp} connection. 8308Enabling authentication does not enable encryption. 8309 8310@cindex RCSBIN, overriding 8311@cindex Overriding RCSBIN 8312@item -b @var{bindir} 8313In @sc{cvs} 1.9.18 and older, this specified that 8314@sc{rcs} programs are in the @var{bindir} directory. 8315Current versions of @sc{cvs} do not run @sc{rcs} 8316programs; for compatibility this option is accepted, 8317but it does nothing. 8318 8319@cindex TMPDIR, environment variable 8320@cindex temporary file directory, set via command line 8321@cindex temporary file directory, set via environment variable 8322@cindex temporary file directory, set via config 8323@cindex temporary files, location of 8324@item -T @var{tempdir} 8325Use @var{tempdir} as the directory where temporary files are 8326located. 8327 8328The @sc{cvs} client and server store temporary files in a temporary directory. 8329The path to this temporary directory is set via, in order of precedence: 8330 8331@itemize @bullet 8332@item 8333The argument to the global @samp{-T} option. 8334 8335@item 8336The value set for @code{TmpDir} in the config file (server only - 8337@pxref{config}). 8338 8339@item 8340The contents of the @code{$TMPDIR} environment variable (@code{%TMPDIR%} on 8341Windows - @pxref{Environment variables}). 8342 8343@item 8344/tmp 8345 8346@end itemize 8347 8348Temporary directories should always be specified as an absolute pathname. 8349When running a CVS client, @samp{-T} affects only the local process; 8350specifying @samp{-T} for the client has no effect on the server and 8351vice versa. 8352 8353@cindex CVSROOT, overriding 8354@cindex Overriding CVSROOT 8355@item -d @var{cvs_root_directory} 8356Use @var{cvs_root_directory} as the root directory 8357pathname of the repository. Overrides the setting of 8358the @code{$CVSROOT} environment variable. @xref{Repository}. 8359 8360@cindex EDITOR, overriding 8361@cindex Overriding EDITOR 8362@item -e @var{editor} 8363Use @var{editor} to enter revision log information. Overrides the 8364setting of the @code{$CVSEDITOR} and @code{$EDITOR} 8365environment variables. For more information, see 8366@ref{Committing your changes}. 8367 8368@item -f 8369Do not read the @file{~/.cvsrc} file. This 8370option is most often used because of the 8371non-orthogonality of the @sc{cvs} option set. For 8372example, the @samp{cvs log} option @samp{-N} (turn off 8373display of tag names) does not have a corresponding 8374option to turn the display on. So if you have 8375@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 8376you may need to use @samp{-f} to show the tag names. 8377 8378@item -H 8379@itemx --help 8380Display usage information about the specified @samp{cvs_command} 8381(but do not actually execute the command). If you don't specify 8382a command name, @samp{cvs -H} displays overall help for 8383@sc{cvs}, including a list of other help options. 8384@c It seems to me it is better to document it this way 8385@c rather than trying to update this documentation 8386@c every time that we add a --help-foo option. But 8387@c perhaps that is confusing... 8388 8389@cindex Read-only repository mode 8390@item -R 8391Turns on read-only repository mode. This allows one to check out from a 8392read-only repository, such as within an anoncvs server, or from a @sc{cd-rom} 8393repository. 8394 8395Same effect as if the @code{CVSREADONLYFS} environment 8396variable is set. Using @samp{-R} can also considerably 8397speed up checkouts over NFS. 8398 8399@cindex Read-only mode 8400@item -n 8401Do not change any files. Attempt to execute the 8402@samp{cvs_command}, but only to issue reports; do not remove, 8403update, or merge any existing files, or create any new files. 8404 8405Note that @sc{cvs} will not necessarily produce exactly 8406the same output as without @samp{-n}. In some cases 8407the output will be the same, but in other cases 8408@sc{cvs} will skip some of the processing that would 8409have been required to produce the exact same output. 8410 8411@item -Q 8412Cause the command to be really quiet; the command will only 8413generate output for serious problems. 8414 8415@item -q 8416Cause the command to be somewhat quiet; informational messages, 8417such as reports of recursion through subdirectories, are 8418suppressed. 8419 8420@cindex Read-only files, and -r 8421@item -r 8422Make new working files read-only. Same effect 8423as if the @code{$CVSREAD} environment variable is set 8424(@pxref{Environment variables}). The default is to 8425make working files writable, unless watches are on 8426(@pxref{Watches}). 8427 8428@item -s @var{variable}=@var{value} 8429Set a user variable (@pxref{Variables}). 8430 8431@cindex Trace 8432@item -t 8433Trace program execution; display messages showing the steps of 8434@sc{cvs} activity. Particularly useful with @samp{-n} to explore the 8435potential impact of an unfamiliar command. 8436 8437@item -v 8438@item --version 8439Display version and copyright information for @sc{cvs}. 8440 8441@cindex CVSREAD, overriding 8442@cindex Overriding CVSREAD 8443@item -w 8444Make new working files read-write. Overrides the 8445setting of the @code{$CVSREAD} environment variable. 8446Files are created read-write by default, unless @code{$CVSREAD} is 8447set or @samp{-r} is given. 8448@c Note that -w only overrides -r and CVSREAD; it has 8449@c no effect on files which are readonly because of 8450@c "cvs watch on". My guess is that is the way it 8451@c should be (or should "cvs -w get" on a watched file 8452@c be the same as a get and a cvs edit?), but I'm not 8453@c completely sure whether to document it this way. 8454 8455@item -x 8456@cindex Encryption 8457Encrypt all communication between the client and the 8458server. Only has an effect on the @sc{cvs} client. As 8459of this writing, this is only implemented when using a 8460GSSAPI connection (@pxref{GSSAPI authenticated}) or a 8461Kerberos connection (@pxref{Kerberos authenticated}). 8462Enabling encryption implies that message traffic is 8463also authenticated. Encryption support is not 8464available by default; it must be enabled using a 8465special configure option, @file{--enable-encryption}, 8466when you build @sc{cvs}. 8467 8468@item -z @var{level} 8469@cindex Compression 8470@cindex Gzip 8471Request compression @var{level} for network traffic. 8472@sc{cvs} interprets @var{level} identically to the @code{gzip} program. 8473Valid levels are 1 (high speed, low compression) to 84749 (low speed, high compression), or 0 to disable 8475compression (the default). Data sent to the server will 8476be compressed at the requested level and the client will request 8477the server use the same compression level for data returned. The 8478server will use the closest level allowed by the server administrator to 8479compress returned data. This option only has an effect when passed to 8480the @sc{cvs} client. 8481@end table 8482 8483@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8484@node Common options 8485@appendixsec Common command options 8486@cindex Common options 8487@cindex Right-hand options 8488 8489This section describes the @samp{command_options} that 8490are available across several @sc{cvs} commands. These 8491options are always given to the right of 8492@samp{cvs_command}. Not all 8493commands support all of these options; each option is 8494only supported for commands where it makes sense. 8495However, when a command has one of these options you 8496can almost always count on the same behavior of the 8497option as in other commands. (Other command options, 8498which are listed with the individual commands, may have 8499different behavior from one @sc{cvs} command to the other). 8500 8501@strong{Note: the @samp{history} command is an exception; it supports 8502many options that conflict even with these standard options.} 8503 8504@table @code 8505@cindex Dates 8506@cindex Time 8507@cindex Specifying dates 8508@item -D @var{date_spec} 8509Use the most recent revision no later than @var{date_spec}. 8510@var{date_spec} is a single argument, a date description 8511specifying a date in the past. 8512 8513The specification is @dfn{sticky} when you use it to make a 8514private copy of a source file; that is, when you get a working 8515file using @samp{-D}, @sc{cvs} records the date you specified, so that 8516further updates in the same directory will use the same date 8517(for more information on sticky tags/dates, @pxref{Sticky tags}). 8518 8519@samp{-D} is available with the @code{annotate}, @code{checkout}, 8520@code{diff}, @code{export}, @code{history}, @code{ls}, 8521@code{rdiff}, @code{rls}, @code{rtag}, @code{tag}, and @code{update} commands. 8522(The @code{history} command uses this option in a 8523slightly different way; @pxref{history options}). 8524 8525For a complete description of the date formats accepted by @sc{cvs}, 8526@ref{Date input formats}. 8527@c What other formats should we accept? I don't want 8528@c to start accepting a whole mess of non-standard 8529@c new formats (there are a lot which are in wide use in 8530@c one context or another), but practicality does 8531@c dictate some level of flexibility. 8532@c * POSIX.2 (e.g. touch, ls output, date) and other 8533@c POSIX and/or de facto unix standards (e.g. at). The 8534@c practice here is too inconsistent to be of any use. 8535@c * VMS dates. This is not a formal standard, but 8536@c there is a published specification (see SYS$ASCTIM 8537@c and SYS$BINTIM in the _VMS System Services Reference 8538@c Manual_), it is implemented consistently in VMS 8539@c utilities, and VMS users will expect CVS running on 8540@c VMS to support this format (and if we're going to do 8541@c that, better to make CVS support it on all 8542@c platforms. Maybe). 8543@c 8544@c One more note: In output, CVS should consistently 8545@c use one date format, and that format should be one that 8546@c it accepts in input as well. The former isn't 8547@c really true (see survey below), and I'm not 8548@c sure that either of those formats is accepted in 8549@c input. 8550@c 8551@c cvs log 8552@c current 1996/01/02 13:45:31 8553@c Internet 02 Jan 1996 13:45:31 UT 8554@c ISO 1996-01-02 13:45:31 8555@c cvs ann 8556@c current 02-Jan-96 8557@c Internet-like 02 Jan 96 8558@c ISO 96-01-02 8559@c cvs status 8560@c current Tue Jun 11 02:54:53 1996 8561@c Internet [Tue,] 11 Jun 1996 02:54:53 8562@c ISO 1996-06-11 02:54:53 8563@c note: date possibly should be omitted entirely for 8564@c other reasons. 8565@c cvs editors 8566@c current Tue Jun 11 02:54:53 1996 GMT 8567@c cvs history 8568@c current 06/11 02:54 +0000 8569@c any others? 8570@c There is a good chance the proper solution has to 8571@c involve at least some level of letting the user 8572@c decide which format (with the default being the 8573@c formats CVS has always used; changing these might be 8574@c _very_ disruptive since scripts may very well be 8575@c parsing them). 8576@c 8577@c Another random bit of prior art concerning dates is 8578@c the strptime function which takes templates such as 8579@c "%m/%d/%y", and apparent a variant of getdate() 8580@c which also honors them. See 8581@c X/Open CAE Specification, System Interfaces and 8582@c Headers Issue 4, Version 2 (September 1994), in the 8583@c entry for getdate() on page 231 8584 8585Remember to quote the argument to the @samp{-D} 8586flag so that your shell doesn't interpret spaces as 8587argument separators. A command using the @samp{-D} 8588flag can look like this: 8589 8590@example 8591$ cvs diff -D "1 hour ago" cvs.texinfo 8592@end example 8593 8594@cindex Forcing a tag match 8595@item -f 8596When you specify a particular date or tag to @sc{cvs} commands, they 8597normally ignore files that do not contain the tag (or did not 8598exist prior to the date) that you specified. Use the @samp{-f} option 8599if you want files retrieved even when there is no match for the 8600tag or date. (The most recent revision of the file 8601will be used). 8602 8603Note that even with @samp{-f}, a tag that you specify 8604must exist (that is, in some file, not necessary in 8605every file). This is so that @sc{cvs} will continue to 8606give an error if you mistype a tag name. 8607 8608@need 800 8609@samp{-f} is available with these commands: 8610@code{annotate}, @code{checkout}, @code{export}, 8611@code{rdiff}, @code{rtag}, and @code{update}. 8612 8613@strong{WARNING: The @code{commit} and @code{remove} 8614commands also have a 8615@samp{-f} option, but it has a different behavior for 8616those commands. See @ref{commit options}, and 8617@ref{Removing files}.} 8618 8619@item -k @var{kflag} 8620Override the default processing of RCS keywords other than 8621@samp{-kb}. @xref{Keyword substitution}, for the meaning of 8622@var{kflag}. Used with the @code{checkout} and @code{update} 8623commands, your @var{kflag} specification is 8624@dfn{sticky}; that is, when you use this option 8625with a @code{checkout} or @code{update} command, 8626@sc{cvs} associates your selected @var{kflag} with any files 8627it operates on, and continues to use that @var{kflag} with future 8628commands on the same files until you specify otherwise. 8629 8630The @samp{-k} option is available with the @code{add}, 8631@code{checkout}, @code{diff}, @code{export}, @code{import}, 8632@code{rdiff}, and @code{update} commands. 8633 8634@strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag 8635overrode the @samp{-kb} indication for a binary file. This could 8636sometimes corrupt binary files. @xref{Merging and keywords}, for 8637more.} 8638 8639@item -l 8640Local; run only in current working directory, rather than 8641recursing through subdirectories. 8642 8643Available with the following commands: @code{annotate}, @code{checkout}, 8644@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8645@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, 8646@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8647and @code{watchers}. 8648 8649@cindex Editor, avoiding invocation of 8650@cindex Avoiding editor invocation 8651@item -m @var{message} 8652Use @var{message} as log information, instead of 8653invoking an editor. 8654 8655Available with the following commands: @code{add}, 8656@code{commit} and @code{import}. 8657 8658@item -n 8659Do not run any tag program. (A program can be 8660specified to run in the modules 8661database (@pxref{modules}); this option bypasses it). 8662 8663@strong{Note: this is not the same as the @samp{cvs -n} 8664program option, which you can specify to the left of a cvs command!} 8665 8666Available with the @code{checkout}, @code{commit}, @code{export}, 8667and @code{rtag} commands. 8668 8669@item -P 8670Prune empty directories. See @ref{Removing directories}. 8671 8672@item -p 8673Pipe the files retrieved from the repository to standard output, 8674rather than writing them in the current directory. Available 8675with the @code{checkout} and @code{update} commands. 8676 8677@item -R 8678Process directories recursively. This is the default for all @sc{cvs} 8679commands, with the exception of @code{ls} & @code{rls}. 8680 8681Available with the following commands: @code{annotate}, @code{checkout}, 8682@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8683@code{ls}, @code{rdiff}, @code{remove}, @code{rls}, @code{rtag}, 8684@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8685and @code{watchers}. 8686 8687@item -r @var{tag} 8688@item -r @var{tag}[:@var{date}] 8689@cindex HEAD, special tag 8690@cindex BASE, special tag 8691Use the revision specified by the @var{tag} argument (and the @var{date} 8692argument for the commands which accept it) instead of the 8693default @dfn{head} revision. As well as arbitrary tags defined 8694with the @code{tag} or @code{rtag} command, two special tags are 8695always available: @samp{HEAD} refers to the most recent version 8696available in the repository, and @samp{BASE} refers to the 8697revision you last checked out into the current working directory. 8698 8699@c FIXME: What does HEAD really mean? I believe that 8700@c the current answer is the head of the default branch 8701@c for all cvs commands except diff. For diff, it 8702@c seems to be (a) the head of the trunk (or the default 8703@c branch?) if there is no sticky tag, (b) the head of the 8704@c branch for the sticky tag, if there is a sticky tag. 8705@c (b) is ugly as it differs 8706@c from what HEAD means for other commands, but people 8707@c and/or scripts are quite possibly used to it. 8708@c See "head" tests in sanity.sh. 8709@c Probably the best fix is to introduce two new 8710@c special tags, ".thead" for the head of the trunk, 8711@c and ".bhead" for the head of the current branch. 8712@c Then deprecate HEAD. This has the advantage of 8713@c not surprising people with a change to HEAD, and a 8714@c side benefit of also phasing out the poorly-named 8715@c HEAD (see discussion of reserved tag names in node 8716@c "Tags"). Of course, .thead and .bhead should be 8717@c carefully implemented (with the implementation the 8718@c same for "diff" as for everyone else), test cases 8719@c written (similar to the ones in "head"), new tests 8720@c cases written for things like default branches, &c. 8721 8722The tag specification is sticky when you use this 8723with @code{checkout} or @code{update} to make your own 8724copy of a file: @sc{cvs} remembers the tag and continues to use it on 8725future update commands, until you specify otherwise (for more information 8726on sticky tags/dates, @pxref{Sticky tags}). 8727 8728The tag can be either a symbolic or numeric tag, as 8729described in @ref{Tags}, or the name of a branch, as 8730described in @ref{Branching and merging}. 8731When @var{tag} is the name of a 8732branch, some commands accept the optional @var{date} argument to specify 8733the revision as of the given date on the branch. 8734When a command expects a specific revision, 8735the name of a branch is interpreted as the most recent 8736revision on that branch. 8737 8738Specifying the @samp{-q} global option along with the 8739@samp{-r} command option is often useful, to suppress 8740the warning messages when the @sc{rcs} file 8741does not contain the specified tag. 8742 8743@strong{Note: this is not the same as the overall @samp{cvs -r} option, 8744which you can specify to the left of a @sc{cvs} command!} 8745 8746@samp{-r @var{tag}} is available with the @code{commit} and @code{history} 8747commands. 8748 8749@samp{-r @var{tag}[:@var{date}]} is available with the @code{annotate}, 8750@code{checkout}, @code{diff}, @code{export}, @code{rdiff}, @code{rtag}, 8751and @code{update} commands. 8752 8753@item -W 8754Specify file names that should be filtered. You can 8755use this option repeatedly. The spec can be a file 8756name pattern of the same type that you can specify in 8757the @file{.cvswrappers} file. 8758Available with the following commands: @code{import}, 8759and @code{update}. 8760 8761@end table 8762 8763@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8764@include getdate-cvs.texi 8765 8766@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8767@node admin 8768@appendixsec admin---Administration 8769@cindex Admin (subcommand) 8770 8771@itemize @bullet 8772@item 8773Requires: repository, working directory. 8774@item 8775Changes: repository. 8776@item 8777Synonym: rcs 8778@end itemize 8779 8780This is the @sc{cvs} interface to assorted 8781administrative facilities. Some of them have 8782questionable usefulness for @sc{cvs} but exist for 8783historical purposes. Some of the questionable options 8784are likely to disappear in the future. This command 8785@emph{does} work recursively, so extreme care should be 8786used. 8787 8788@cindex cvsadmin 8789@cindex UserAdminOptions, in CVSROOT/config 8790On unix, if there is a group named @code{cvsadmin}, 8791only members of that group can run @code{cvs admin} 8792commands, except for those specified using the 8793@code{UserAdminOptions} configuration option in the 8794@file{CVSROOT/config} file. Options specified using 8795@code{UserAdminOptions} can be run by any user. See 8796@ref{config} for more on @code{UserAdminOptions}. 8797 8798The @code{cvsadmin} group should exist on the server, 8799or any system running the non-client/server @sc{cvs}. 8800To disallow @code{cvs admin} for all users, create a 8801group with no users in it. On NT, the @code{cvsadmin} 8802feature does not exist and all users 8803can run @code{cvs admin}. 8804 8805@menu 8806* admin options:: admin options 8807@end menu 8808 8809@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8810@node admin options 8811@appendixsubsec admin options 8812 8813Some of these options have questionable usefulness for 8814@sc{cvs} but exist for historical purposes. Some even 8815make it impossible to use @sc{cvs} until you undo the 8816effect! 8817 8818@table @code 8819@item -A@var{oldfile} 8820Might not work together with @sc{cvs}. Append the 8821access list of @var{oldfile} to the access list of the 8822@sc{rcs} file. 8823 8824@item -a@var{logins} 8825Might not work together with @sc{cvs}. Append the 8826login names appearing in the comma-separated list 8827@var{logins} to the access list of the @sc{rcs} file. 8828 8829@item -b[@var{rev}] 8830Set the default branch to @var{rev}. In @sc{cvs}, you 8831normally do not manipulate default branches; sticky 8832tags (@pxref{Sticky tags}) are a better way to decide 8833which branch you want to work on. There is one reason 8834to run @code{cvs admin -b}: to revert to the vendor's 8835version when using vendor branches (@pxref{Reverting 8836local changes}). 8837There can be no space between @samp{-b} and its argument. 8838@c Hmm, we don't document the usage where rev is 8839@c omitted. Maybe that usage can/should be deprecated 8840@c (and replaced with -bHEAD or something?) (so we can toss 8841@c the optional argument). Note that -bHEAD does not 8842@c work, as of 17 Sep 1997, but probably will once "cvs 8843@c admin" is internal to CVS. 8844 8845@cindex Comment leader 8846@item -c@var{string} 8847Sets the comment leader to @var{string}. The comment 8848leader is not used by current versions of @sc{cvs} or 8849@sc{rcs} 5.7. Therefore, you can almost surely not 8850worry about it. @xref{Keyword substitution}. 8851 8852@item -e[@var{logins}] 8853Might not work together with @sc{cvs}. Erase the login 8854names appearing in the comma-separated list 8855@var{logins} from the access list of the RCS file. If 8856@var{logins} is omitted, erase the entire access list. 8857There can be no space between @samp{-e} and its argument. 8858 8859@item -I 8860Run interactively, even if the standard input is not a 8861terminal. This option does not work with the 8862client/server @sc{cvs} and is likely to disappear in 8863a future release of @sc{cvs}. 8864 8865@item -i 8866Useless with @sc{cvs}. This creates and initializes a 8867new @sc{rcs} file, without depositing a revision. With 8868@sc{cvs}, add files with the @code{cvs add} command 8869(@pxref{Adding files}). 8870 8871@item -k@var{subst} 8872Set the default keyword 8873substitution to @var{subst}. @xref{Keyword 8874substitution}. Giving an explicit @samp{-k} option to 8875@code{cvs update}, @code{cvs export}, or @code{cvs 8876checkout} overrides this default. 8877 8878@item -l[@var{rev}] 8879Lock the revision with number @var{rev}. If a branch 8880is given, lock the latest revision on that branch. If 8881@var{rev} is omitted, lock the latest revision on the 8882default branch. There can be no space between 8883@samp{-l} and its argument. 8884 8885This can be used in conjunction with the 8886@file{rcslock.pl} script in the @file{contrib} 8887directory of the @sc{cvs} source distribution to 8888provide reserved checkouts (where only one user can be 8889editing a given file at a time). See the comments in 8890that file for details (and see the @file{README} file 8891in that directory for disclaimers about the unsupported 8892nature of contrib). According to comments in that 8893file, locking must set to strict (which is the default). 8894 8895@item -L 8896Set locking to strict. Strict locking means that the 8897owner of an RCS file is not exempt from locking for 8898checkin. For use with @sc{cvs}, strict locking must be 8899set; see the discussion under the @samp{-l} option above. 8900 8901@cindex Changing a log message 8902@cindex Replacing a log message 8903@cindex Correcting a log message 8904@cindex Fixing a log message 8905@cindex Log message, correcting 8906@item -m@var{rev}:@var{msg} 8907Replace the log message of revision @var{rev} with 8908@var{msg}. 8909 8910@c The rcs -M option, to suppress sending mail, has never been 8911@c documented as a cvs admin option. 8912 8913@item -N@var{name}[:[@var{rev}]] 8914Act like @samp{-n}, except override any previous 8915assignment of @var{name}. For use with magic branches, 8916see @ref{Magic branch numbers}. 8917 8918@item -n@var{name}[:[@var{rev}]] 8919Associate the symbolic name @var{name} with the branch 8920or revision @var{rev}. It is normally better to use 8921@samp{cvs tag} or @samp{cvs rtag} instead. Delete the 8922symbolic name if both @samp{:} and @var{rev} are 8923omitted; otherwise, print an error message if 8924@var{name} is already associated with another number. 8925If @var{rev} is symbolic, it is expanded before 8926association. A @var{rev} consisting of a branch number 8927followed by a @samp{.} stands for the current latest 8928revision in the branch. A @samp{:} with an empty 8929@var{rev} stands for the current latest revision on the 8930default branch, normally the trunk. For example, 8931@samp{cvs admin -n@var{name}:} associates @var{name} with the 8932current latest revision of all the RCS files; 8933this contrasts with @samp{cvs admin -n@var{name}:$} which 8934associates @var{name} with the revision numbers 8935extracted from keyword strings in the corresponding 8936working files. 8937 8938@cindex Deleting revisions 8939@cindex Outdating revisions 8940@cindex Saving space 8941@item -o@var{range} 8942Deletes (@dfn{outdates}) the revisions given by 8943@var{range}. 8944 8945Note that this command can be quite dangerous unless 8946you know @emph{exactly} what you are doing (for example 8947see the warnings below about how the 8948@var{rev1}:@var{rev2} syntax is confusing). 8949 8950If you are short on disc this option might help you. 8951But think twice before using it---there is no way short 8952of restoring the latest backup to undo this command! 8953If you delete different revisions than you planned, 8954either due to carelessness or (heaven forbid) a @sc{cvs} 8955bug, there is no opportunity to correct the error 8956before the revisions are deleted. It probably would be 8957a good idea to experiment on a copy of the repository 8958first. 8959 8960Specify @var{range} in one of the following ways: 8961 8962@table @code 8963@item @var{rev1}::@var{rev2} 8964Collapse all revisions between rev1 and rev2, so that 8965@sc{cvs} only stores the differences associated with going 8966from rev1 to rev2, not intermediate steps. For 8967example, after @samp{-o 1.3::1.5} one can retrieve 8968revision 1.3, revision 1.5, or the differences to get 8969from 1.3 to 1.5, but not the revision 1.4, or the 8970differences between 1.3 and 1.4. Other examples: 8971@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 8972effect, because there are no intermediate revisions to 8973remove. 8974 8975@item ::@var{rev} 8976Collapse revisions between the beginning of the branch 8977containing @var{rev} and @var{rev} itself. The 8978branchpoint and @var{rev} are left intact. For 8979example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 8980revision 1.3.2.5, and everything in between, but leaves 89811.3 and 1.3.2.6 intact. 8982 8983@item @var{rev}:: 8984Collapse revisions between @var{rev} and the end of the 8985branch containing @var{rev}. Revision @var{rev} is 8986left intact but the head revision is deleted. 8987 8988@item @var{rev} 8989Delete the revision @var{rev}. For example, @samp{-o 89901.3} is equivalent to @samp{-o 1.2::1.4}. 8991 8992@item @var{rev1}:@var{rev2} 8993Delete the revisions from @var{rev1} to @var{rev2}, 8994inclusive, on the same branch. One will not be able to 8995retrieve @var{rev1} or @var{rev2} or any of the 8996revisions in between. For example, the command 8997@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 8998It means to delete revisions up to, and including, the 8999tag R_1_02. But beware! If there are files that have not 9000changed between R_1_02 and R_1_03 the file will have 9001@emph{the same} numerical revision number assigned to 9002the tags R_1_02 and R_1_03. So not only will it be 9003impossible to retrieve R_1_02; R_1_03 will also have to 9004be restored from the tapes! In most cases you want to 9005specify @var{rev1}::@var{rev2} instead. 9006 9007@item :@var{rev} 9008Delete revisions from the beginning of the 9009branch containing @var{rev} up to and including 9010@var{rev}. 9011 9012@item @var{rev}: 9013Delete revisions from revision @var{rev}, including 9014@var{rev} itself, to the end of the branch containing 9015@var{rev}. 9016@end table 9017 9018None of the revisions to be deleted may have 9019branches or locks. 9020 9021If any of the revisions to be deleted have symbolic 9022names, and one specifies one of the @samp{::} syntaxes, 9023then @sc{cvs} will give an error and not delete any 9024revisions. If you really want to delete both the 9025symbolic names and the revisions, first delete the 9026symbolic names with @code{cvs tag -d}, then run 9027@code{cvs admin -o}. If one specifies the 9028non-@samp{::} syntaxes, then @sc{cvs} will delete the 9029revisions but leave the symbolic names pointing to 9030nonexistent revisions. This behavior is preserved for 9031compatibility with previous versions of @sc{cvs}, but 9032because it isn't very useful, in the future it may 9033change to be like the @samp{::} case. 9034 9035Due to the way @sc{cvs} handles branches @var{rev} 9036cannot be specified symbolically if it is a branch. 9037@xref{Magic branch numbers}, for an explanation. 9038@c FIXME: is this still true? I suspect not. 9039 9040Make sure that no-one has checked out a copy of the 9041revision you outdate. Strange things will happen if he 9042starts to edit it and tries to check it back in. For 9043this reason, this option is not a good way to take back 9044a bogus commit; commit a new revision undoing the bogus 9045change instead (@pxref{Merging two revisions}). 9046 9047@item -q 9048Run quietly; do not print diagnostics. 9049 9050@item -s@var{state}[:@var{rev}] 9051Useful with @sc{cvs}. Set the state attribute of the 9052revision @var{rev} to @var{state}. If @var{rev} is a 9053branch number, assume the latest revision on that 9054branch. If @var{rev} is omitted, assume the latest 9055revision on the default branch. Any identifier is 9056acceptable for @var{state}. A useful set of states is 9057@samp{Exp} (for experimental), @samp{Stab} (for 9058stable), and @samp{Rel} (for released). By default, 9059the state of a new revision is set to @samp{Exp} when 9060it is created. The state is visible in the output from 9061@var{cvs log} (@pxref{log}), and in the 9062@samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords 9063(@pxref{Keyword substitution}). Note that @sc{cvs} 9064uses the @code{dead} state for its own purposes (@pxref{Attic}); to 9065take a file to or from the @code{dead} state use 9066commands like @code{cvs remove} and @code{cvs add} 9067(@pxref{Adding and removing}), not @code{cvs admin -s}. 9068 9069@item -t[@var{file}] 9070Useful with @sc{cvs}. Write descriptive text from the 9071contents of the named @var{file} into the RCS file, 9072deleting the existing text. The @var{file} pathname 9073may not begin with @samp{-}. The descriptive text can be seen in the 9074output from @samp{cvs log} (@pxref{log}). 9075There can be no space between @samp{-t} and its argument. 9076 9077If @var{file} is omitted, 9078obtain the text from standard input, terminated by 9079end-of-file or by a line containing @samp{.} by itself. 9080Prompt for the text if interaction is possible; see 9081@samp{-I}. 9082 9083@item -t-@var{string} 9084Similar to @samp{-t@var{file}}. Write descriptive text 9085from the @var{string} into the @sc{rcs} file, deleting 9086the existing text. 9087There can be no space between @samp{-t} and its argument. 9088 9089@c The rcs -T option, do not update last-mod time for 9090@c minor changes, has never been documented as a 9091@c cvs admin option. 9092 9093@item -U 9094Set locking to non-strict. Non-strict locking means 9095that the owner of a file need not lock a revision for 9096checkin. For use with @sc{cvs}, strict locking must be 9097set; see the discussion under the @samp{-l} option 9098above. 9099 9100@item -u[@var{rev}] 9101See the option @samp{-l} above, for a discussion of 9102using this option with @sc{cvs}. Unlock the revision 9103with number @var{rev}. If a branch is given, unlock 9104the latest revision on that branch. If @var{rev} is 9105omitted, remove the latest lock held by the caller. 9106Normally, only the locker of a revision may unlock it; 9107somebody else unlocking a revision breaks the lock. 9108This causes the original locker to be sent a @code{commit} 9109notification (@pxref{Getting Notified}). 9110There can be no space between @samp{-u} and its argument. 9111 9112@item -V@var{n} 9113In previous versions of @sc{cvs}, this option meant to 9114write an @sc{rcs} file which would be acceptable to 9115@sc{rcs} version @var{n}, but it is now obsolete and 9116specifying it will produce an error. 9117@c Note that -V without an argument has never been 9118@c documented as a cvs admin option. 9119 9120@item -x@var{suffixes} 9121In previous versions of @sc{cvs}, this was documented 9122as a way of specifying the names of the @sc{rcs} 9123files. However, @sc{cvs} has always required that the 9124@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 9125this option has never done anything useful. 9126 9127@c The rcs -z option, to specify the timezone, has 9128@c never been documented as a cvs admin option. 9129@end table 9130 9131@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9132@node annotate 9133@appendixsec annotate---What revision modified each line of a file? 9134@cindex annotate (subcommand) 9135 9136@itemize @bullet 9137@item 9138Synopsis: annotate [options] files@dots{} 9139@item 9140Requires: repository. 9141@item 9142Changes: nothing. 9143@end itemize 9144 9145For each file in @var{files}, print the head revision 9146of the trunk, together with information on the last 9147modification for each line. 9148 9149@menu 9150* annotate options:: annotate options 9151* annotate example:: annotate example 9152@end menu 9153 9154@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9155@node annotate options 9156@appendixsubsec annotate options 9157 9158These standard options are supported by @code{annotate} 9159(@pxref{Common options}, for a complete description of 9160them): 9161 9162@table @code 9163@item -l 9164Local directory only, no recursion. 9165 9166@item -R 9167Process directories recursively. 9168 9169@item -f 9170Use head revision if tag/date not found. 9171 9172@item -F 9173Annotate binary files. 9174 9175@item -r @var{tag}[:@var{date}] 9176Annotate file as of specified revision/tag or, when @var{date} is specified 9177and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9178existed on @var{date}. See @ref{Common options}. 9179 9180@item -D @var{date} 9181Annotate file as of specified date. 9182@end table 9183 9184@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9185@node annotate example 9186@appendixsubsec annotate example 9187 9188For example: 9189 9190@example 9191$ cvs annotate ssfile 9192Annotations for ssfile 9193*************** 91941.1 (mary 27-Mar-96): ssfile line 1 91951.2 (joe 28-Mar-96): ssfile line 2 9196@end example 9197 9198The file @file{ssfile} currently contains two lines. 9199The @code{ssfile line 1} line was checked in by 9200@code{mary} on March 27. Then, on March 28, @code{joe} 9201added a line @code{ssfile line 2}, without modifying 9202the @code{ssfile line 1} line. This report doesn't 9203tell you anything about lines which have been deleted 9204or replaced; you need to use @code{cvs diff} for that 9205(@pxref{diff}). 9206 9207The options to @code{cvs annotate} are listed in 9208@ref{Invoking CVS}, and can be used to select the files 9209and revisions to annotate. The options are described 9210in more detail there and in @ref{Common options}. 9211 9212@c FIXME: maybe an example using the options? Just 9213@c what it means to select a revision might be worth a 9214@c few words of explanation ("you want to see who 9215@c changed this line *before* 1.4"...). 9216 9217@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9218@node checkout 9219@appendixsec checkout---Check out sources for editing 9220@cindex checkout (subcommand) 9221@cindex co (subcommand) 9222 9223@itemize @bullet 9224@item 9225Synopsis: checkout [options] modules@dots{} 9226@item 9227Requires: repository. 9228@item 9229Changes: working directory. 9230@item 9231Synonyms: co, get 9232@end itemize 9233 9234Create or update a working directory containing copies of the 9235source files specified by @var{modules}. You must execute 9236@code{checkout} before using most of the other @sc{cvs} 9237commands, since most of them operate on your working 9238directory. 9239 9240The @var{modules} are either 9241symbolic names for some 9242collection of source directories and files, or paths to 9243directories or files in the repository. The symbolic 9244names are defined in the @samp{modules} file. 9245@xref{modules}. 9246@c Needs an example, particularly of the non-"modules" 9247@c case but probably of both. 9248 9249@c FIXME: this seems like a very odd place to introduce 9250@c people to how CVS works. The bit about unreserved 9251@c checkouts is also misleading as it depends on how 9252@c things are set up. 9253Depending on the modules you specify, @code{checkout} may 9254recursively create directories and populate them with 9255the appropriate source files. You can then edit these 9256source files at any time (regardless of whether other 9257software developers are editing their own copies of the 9258sources); update them to include new changes applied by 9259others to the source repository; or commit your work as 9260a permanent change to the source repository. 9261 9262Note that @code{checkout} is used to create 9263directories. The top-level directory created is always 9264added to the directory where @code{checkout} is 9265invoked, and usually has the same name as the specified 9266module. In the case of a module alias, the created 9267sub-directory may have a different name, but you can be 9268sure that it will be a sub-directory, and that 9269@code{checkout} will show the relative path leading to 9270each file as it is extracted into your private work 9271area (unless you specify the @samp{-Q} global option). 9272 9273The files created by @code{checkout} are created 9274read-write, unless the @samp{-r} option to @sc{cvs} 9275(@pxref{Global options}) is specified, the 9276@code{CVSREAD} environment variable is specified 9277(@pxref{Environment variables}), or a watch is in 9278effect for that file (@pxref{Watches}). 9279 9280Note that running @code{checkout} on a directory that was already 9281built by a prior @code{checkout} is also permitted. 9282This is similar to specifying the @samp{-d} option 9283to the @code{update} command in the sense that new 9284directories that have been created in the repository 9285will appear in your work area. 9286However, @code{checkout} takes a module name whereas 9287@code{update} takes a directory name. Also 9288to use @code{checkout} this way it must be run from the 9289top level directory (where you originally ran 9290@code{checkout} from), so before you run 9291@code{checkout} to update an existing directory, don't 9292forget to change your directory to the top level 9293directory. 9294 9295For the output produced by the @code{checkout} command 9296see @ref{update output}. 9297 9298@menu 9299* checkout options:: checkout options 9300* checkout examples:: checkout examples 9301@end menu 9302 9303@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9304@node checkout options 9305@appendixsubsec checkout options 9306 9307These standard options are supported by @code{checkout} 9308(@pxref{Common options}, for a complete description of 9309them): 9310 9311@table @code 9312@item -D @var{date} 9313Use the most recent revision no later than @var{date}. 9314This option is sticky, and implies @samp{-P}. See 9315@ref{Sticky tags}, for more information on sticky tags/dates. 9316 9317@item -f 9318Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision is 9319found, retrieve the most recent revision (instead of ignoring the file). 9320 9321@item -k @var{kflag} 9322Process keywords according to @var{kflag}. See 9323@ref{Keyword substitution}. 9324This option is sticky; future updates of 9325this file in this working directory will use the same 9326@var{kflag}. The @code{status} command can be viewed 9327to see the sticky options. See @ref{Invoking CVS}, for 9328more information on the @code{status} command. 9329 9330@item -l 9331Local; run only in current working directory. 9332 9333@item -n 9334Do not run any checkout program (as specified 9335with the @samp{-o} option in the modules file; 9336@pxref{modules}). 9337 9338@item -P 9339Prune empty directories. See @ref{Moving directories}. 9340 9341@item -p 9342Pipe files to the standard output. 9343 9344@item -R 9345Checkout directories recursively. This option is on by default. 9346 9347@item -r @var{tag}[:@var{date}] 9348Checkout the revision specified by @var{tag} or, when @var{date} is specified 9349and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9350existed on @var{date}. This option is sticky, and implies @samp{-P}. 9351See @ref{Sticky tags}, for more information on sticky tags/dates. Also, 9352see @ref{Common options}. 9353@end table 9354 9355In addition to those, you can use these special command 9356options with @code{checkout}: 9357 9358@table @code 9359@item -A 9360Reset any sticky tags, dates, or @samp{-k} options. 9361See @ref{Sticky tags}, for more information on sticky tags/dates. 9362 9363@item -c 9364Copy the module file, sorted, to the standard output, 9365instead of creating or modifying any files or 9366directories in your working directory. 9367 9368@item -d @var{dir} 9369Create a directory called @var{dir} for the working 9370files, instead of using the module name. In general, 9371using this flag is equivalent to using @samp{mkdir 9372@var{dir}; cd @var{dir}} followed by the checkout 9373command without the @samp{-d} flag. 9374 9375There is an important exception, however. It is very 9376convenient when checking out a single item to have the 9377output appear in a directory that doesn't contain empty 9378intermediate directories. In this case @emph{only}, 9379@sc{cvs} tries to ``shorten'' pathnames to avoid those empty 9380directories. 9381 9382For example, given a module @samp{foo} that contains 9383the file @samp{bar.c}, the command @samp{cvs co -d dir 9384foo} will create directory @samp{dir} and place 9385@samp{bar.c} inside. Similarly, given a module 9386@samp{bar} which has subdirectory @samp{baz} wherein 9387there is a file @samp{quux.c}, the command @samp{cvs co 9388-d dir bar/baz} will create directory @samp{dir} and 9389place @samp{quux.c} inside. 9390 9391Using the @samp{-N} flag will defeat this behavior. 9392Given the same module definitions above, @samp{cvs co 9393-N -d dir foo} will create directories @samp{dir/foo} 9394and place @samp{bar.c} inside, while @samp{cvs co -N -d 9395dir bar/baz} will create directories @samp{dir/bar/baz} 9396and place @samp{quux.c} inside. 9397 9398@item -j @var{tag} 9399With two @samp{-j} options, merge changes from the 9400revision specified with the first @samp{-j} option to 9401the revision specified with the second @samp{j} option, 9402into the working directory. 9403 9404With one @samp{-j} option, merge changes from the 9405ancestor revision to the revision specified with the 9406@samp{-j} option, into the working directory. The 9407ancestor revision is the common ancestor of the 9408revision which the working directory is based on, and 9409the revision specified in the @samp{-j} option. 9410 9411In addition, each -j option can contain an optional 9412date specification which, when used with branches, can 9413limit the chosen revision to one within a specific 9414date. An optional date is specified by adding a colon 9415(:) to the tag: 9416@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 9417 9418@xref{Branching and merging}. 9419 9420@item -N 9421Only useful together with @samp{-d @var{dir}}. With 9422this option, @sc{cvs} will not ``shorten'' module paths 9423in your working directory when you check out a single 9424module. See the @samp{-d} flag for examples and a 9425discussion. 9426 9427@item -s 9428Like @samp{-c}, but include the status of all modules, 9429and sort it by the status string. @xref{modules}, for 9430info about the @samp{-s} option that is used inside the 9431modules file to set the module status. 9432@end table 9433 9434@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9435@node checkout examples 9436@appendixsubsec checkout examples 9437 9438Get a copy of the module @samp{tc}: 9439 9440@example 9441$ cvs checkout tc 9442@end example 9443 9444Get a copy of the module @samp{tc} as it looked one day 9445ago: 9446 9447@example 9448$ cvs checkout -D yesterday tc 9449@end example 9450 9451@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9452@node commit 9453@appendixsec commit---Check files into the repository 9454@cindex commit (subcommand) 9455 9456@itemize @bullet 9457@item 9458Synopsis: commit [-lnRf] [-m 'log_message' | 9459-F file] [-r revision] [files@dots{}] 9460@item 9461Requires: working directory, repository. 9462@item 9463Changes: repository. 9464@item 9465Synonym: ci 9466@end itemize 9467 9468Use @code{commit} when you want to incorporate changes 9469from your working source files into the source 9470repository. 9471 9472If you don't specify particular files to commit, all of 9473the files in your working current directory are 9474examined. @code{commit} is careful to change in the 9475repository only those files that you have really 9476changed. By default (or if you explicitly specify the 9477@samp{-R} option), files in subdirectories are also 9478examined and committed if they have changed; you can 9479use the @samp{-l} option to limit @code{commit} to the 9480current directory only. 9481 9482@code{commit} verifies that the selected files are up 9483to date with the current revisions in the source 9484repository; it will notify you, and exit without 9485committing, if any of the specified files must be made 9486current first with @code{update} (@pxref{update}). 9487@code{commit} does not call the @code{update} command 9488for you, but rather leaves that for you to do when the 9489time is right. 9490 9491When all is well, an editor is invoked to allow you to 9492enter a log message that will be written to one or more 9493logging programs (@pxref{modules}, and @pxref{loginfo}) 9494and placed in the @sc{rcs} file inside the 9495repository. This log message can be retrieved with the 9496@code{log} command; see @ref{log}. You can specify the 9497log message on the command line with the @samp{-m 9498@var{message}} option, and thus avoid the editor invocation, 9499or use the @samp{-F @var{file}} option to specify 9500that the argument file contains the log message. 9501 9502At @code{commit}, a unique commitid is placed in the @sc{rcs} 9503file inside the repository. All files committed at once 9504get the same commitid. The commitid can be retrieved with 9505the @code{log} and @code{status} command; see @ref{log}, 9506@ref{File status}. 9507 9508@menu 9509* commit options:: commit options 9510* commit examples:: commit examples 9511@end menu 9512 9513@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9514@node commit options 9515@appendixsubsec commit options 9516 9517These standard options are supported by @code{commit} 9518(@pxref{Common options}, for a complete description of 9519them): 9520 9521@table @code 9522@item -l 9523Local; run only in current working directory. 9524 9525@item -R 9526Commit directories recursively. This is on by default. 9527 9528@item -r @var{revision} 9529Commit to @var{revision}. @var{revision} must be 9530either a branch, or a revision on the main trunk that 9531is higher than any existing revision number 9532(@pxref{Assigning revisions}). You 9533cannot commit to a specific revision on a branch. 9534@c FIXME: Need xref for branch case. 9535@end table 9536 9537@code{commit} also supports these options: 9538 9539@table @code 9540@item -c 9541Refuse to commit files unless the user has registered a valid edit on the 9542file via @code{cvs edit}. This is most useful when @samp{commit -c} 9543and @samp{edit -c} have been placed in all @file{.cvsrc} files. 9544A commit can be forced anyways by either registering an edit retroactively 9545via @code{cvs edit} (no changes to the file will be lost) or using the 9546@code{-f} option to commit. Support for @code{commit -c} requires both 9547client and a server versions 1.12.10 or greater. 9548 9549@item -F @var{file} 9550Read the log message from @var{file}, instead 9551of invoking an editor. 9552 9553@item -f 9554Note that this is not the standard behavior of 9555the @samp{-f} option as defined in @ref{Common options}. 9556 9557Force @sc{cvs} to commit a new revision even if you haven't 9558made any changes to the file. As of @sc{cvs} version 1.12.10, 9559it also causes the @code{-c} option to be ignored. If the current revision 9560of @var{file} is 1.7, then the following two commands 9561are equivalent: 9562 9563@example 9564$ cvs commit -f @var{file} 9565$ cvs commit -r 1.8 @var{file} 9566@end example 9567 9568@c This is odd, but it's how CVS has worked for some 9569@c time. 9570The @samp{-f} option disables recursion (i.e., it 9571implies @samp{-l}). To force @sc{cvs} to commit a new 9572revision for all files in all subdirectories, you must 9573use @samp{-f -R}. 9574 9575@item -m @var{message} 9576Use @var{message} as the log message, instead of 9577invoking an editor. 9578@end table 9579 9580@need 2000 9581@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9582@node commit examples 9583@appendixsubsec commit examples 9584 9585@c FIXME: this material wants to be somewhere 9586@c in "Branching and merging". 9587 9588@appendixsubsubsec Committing to a branch 9589 9590You can commit to a branch revision (one that has an 9591even number of dots) with the @samp{-r} option. To 9592create a branch revision, use the @samp{-b} option 9593of the @code{rtag} or @code{tag} commands 9594(@pxref{Branching and merging}). Then, either @code{checkout} or 9595@code{update} can be used to base your sources on the 9596newly created branch. From that point on, all 9597@code{commit} changes made within these working sources 9598will be automatically added to a branch revision, 9599thereby not disturbing main-line development in any 9600way. For example, if you had to create a patch to the 96011.2 version of the product, even though the 2.0 version 9602is already under development, you might do: 9603 9604@example 9605$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 9606$ cvs checkout -r FCS1_2_Patch product_module 9607$ cd product_module 9608[[ hack away ]] 9609$ cvs commit 9610@end example 9611 9612@noindent 9613This works automatically since the @samp{-r} option is 9614sticky. 9615 9616@appendixsubsubsec Creating the branch after editing 9617 9618Say you have been working on some extremely 9619experimental software, based on whatever revision you 9620happened to checkout last week. If others in your 9621group would like to work on this software with you, but 9622without disturbing main-line development, you could 9623commit your change to a new branch. Others can then 9624checkout your experimental stuff and utilize the full 9625benefit of @sc{cvs} conflict resolution. The scenario might 9626look like: 9627 9628@c FIXME: Should we be recommending tagging the branchpoint? 9629@example 9630[[ hacked sources are present ]] 9631$ cvs tag -b EXPR1 9632$ cvs update -r EXPR1 9633$ cvs commit 9634@end example 9635 9636The @code{update} command will make the @samp{-r 9637EXPR1} option sticky on all files. Note that your 9638changes to the files will never be removed by the 9639@code{update} command. The @code{commit} will 9640automatically commit to the correct branch, because the 9641@samp{-r} is sticky. You could also do like this: 9642 9643@c FIXME: Should we be recommending tagging the branchpoint? 9644@example 9645[[ hacked sources are present ]] 9646$ cvs tag -b EXPR1 9647$ cvs commit -r EXPR1 9648@end example 9649 9650@noindent 9651but then, only those files that were changed by you 9652will have the @samp{-r EXPR1} sticky flag. If you hack 9653away, and commit without specifying the @samp{-r EXPR1} 9654flag, some files may accidentally end up on the main 9655trunk. 9656 9657To work with you on the experimental change, others 9658would simply do 9659 9660@example 9661$ cvs checkout -r EXPR1 whatever_module 9662@end example 9663 9664@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9665@node diff 9666@appendixsec diff---Show differences between revisions 9667@cindex diff (subcommand) 9668 9669@itemize @bullet 9670@item 9671Synopsis: diff [-lR] [-k kflag] [format_options] [(-r rev1[:date1] | -D date1) [-r rev2[:date2] | -D date2]] [files@dots{}] 9672@item 9673Requires: working directory, repository. 9674@item 9675Changes: nothing. 9676@end itemize 9677 9678The @code{diff} command is used to compare different 9679revisions of files. The default action is to compare 9680your working files with the revisions they were based 9681on, and report any differences that are found. 9682 9683If any file names are given, only those files are 9684compared. If any directories are given, all files 9685under them will be compared. 9686 9687The exit status for diff is different than for other 9688@sc{cvs} commands; for details @ref{Exit status}. 9689 9690@menu 9691* diff options:: diff options 9692* diff examples:: diff examples 9693@end menu 9694 9695@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9696@node diff options 9697@appendixsubsec diff options 9698 9699These standard options are supported by @code{diff} 9700(@pxref{Common options}, for a complete description of 9701them): 9702 9703@table @code 9704@item -D @var{date} 9705Use the most recent revision no later than @var{date}. 9706See @samp{-r} for how this affects the comparison. 9707 9708@item -k @var{kflag} 9709Process keywords according to @var{kflag}. See 9710@ref{Keyword substitution}. 9711 9712@item -l 9713Local; run only in current working directory. 9714 9715@item -R 9716Examine directories recursively. This option is on by 9717default. 9718 9719@item -r @var{tag}[:@var{date}] 9720Compare with revision specified by @var{tag} or, when @var{date} is specified 9721and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9722existed on @var{date}. Zero, one or two 9723@samp{-r} options can be present. With no @samp{-r} 9724option, the working file will be compared with the 9725revision it was based on. With one @samp{-r}, that 9726revision will be compared to your current working file. 9727With two @samp{-r} options those two revisions will be 9728compared (and your working file will not affect the 9729outcome in any way). 9730@c We should be a lot more explicit, with examples, 9731@c about the difference between "cvs diff" and "cvs 9732@c diff -r HEAD". This often confuses new users. 9733 9734One or both @samp{-r} options can be replaced by a 9735@samp{-D @var{date}} option, described above. 9736@end table 9737 9738@c Conceptually, this is a disaster. There are 3 9739@c zillion diff formats that we support via the diff 9740@c library. It is not obvious to me that we should 9741@c document them all. Maybe just the most common ones 9742@c like -c and -u, and think about phasing out the 9743@c obscure ones. 9744@c FIXCVS: also should be a way to specify an external 9745@c diff program (which can be different for different 9746@c file types) and pass through 9747@c arbitrary options, so that the user can do 9748@c "--pass=-Z --pass=foo" or something even if CVS 9749@c doesn't know about the "-Z foo" option to diff. 9750@c This would fit nicely with deprecating/eliminating 9751@c the obscure options of the diff library, because it 9752@c would let people specify an external GNU diff if 9753@c they are into that sort of thing. 9754The following options specify the format of the 9755output. They have the same meaning as in GNU diff. 9756Most options have two equivalent names, one of which is a single letter 9757preceded by @samp{-}, and the other of which is a long name preceded by 9758@samp{--}. 9759 9760@table @samp 9761@item -@var{lines} 9762Show @var{lines} (an integer) lines of context. This option does not 9763specify an output format by itself; it has no effect unless it is 9764combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9765operation, @code{patch} typically needs at least two lines of context. 9766 9767@item -a 9768Treat all files as text and compare them line-by-line, even if they 9769do not seem to be text. 9770 9771@item -b 9772Ignore trailing white space and consider all other sequences of one or 9773more white space characters to be equivalent. 9774 9775@item -B 9776Ignore changes that just insert or delete blank lines. 9777 9778@item --binary 9779Read and write data in binary mode. 9780 9781@item --brief 9782Report only whether the files differ, not the details of the 9783differences. 9784 9785@item -c 9786Use the context output format. 9787 9788@item -C @var{lines} 9789@itemx --context@r{[}=@var{lines}@r{]} 9790Use the context output format, showing @var{lines} (an integer) lines of 9791context, or three if @var{lines} is not given. 9792For proper operation, @code{patch} typically needs at least two lines of 9793context. 9794 9795@item --changed-group-format=@var{format} 9796Use @var{format} to output a line group containing differing lines from 9797both files in if-then-else format. @xref{Line group formats}. 9798 9799@item -d 9800Change the algorithm to perhaps find a smaller set of changes. This makes 9801@code{diff} slower (sometimes much slower). 9802 9803@item -e 9804@itemx --ed 9805Make output that is a valid @code{ed} script. 9806 9807@item --expand-tabs 9808Expand tabs to spaces in the output, to preserve the alignment of tabs 9809in the input files. 9810 9811@item -f 9812Make output that looks vaguely like an @code{ed} script but has changes 9813in the order they appear in the file. 9814 9815@item -F @var{regexp} 9816In context and unified format, for each hunk of differences, show some 9817of the last preceding line that matches @var{regexp}. 9818 9819@item --forward-ed 9820Make output that looks vaguely like an @code{ed} script but has changes 9821in the order they appear in the file. 9822 9823@item -H 9824Use heuristics to speed handling of large files that have numerous 9825scattered small changes. 9826 9827@item --horizon-lines=@var{lines} 9828Do not discard the last @var{lines} lines of the common prefix 9829and the first @var{lines} lines of the common suffix. 9830 9831@item -i 9832Ignore changes in case; consider upper- and lower-case letters 9833equivalent. 9834 9835@item -I @var{regexp} 9836Ignore changes that just insert or delete lines that match @var{regexp}. 9837 9838@item --ifdef=@var{name} 9839Make merged if-then-else output using @var{name}. 9840 9841@item --ignore-all-space 9842Ignore white space when comparing lines. 9843 9844@item --ignore-blank-lines 9845Ignore changes that just insert or delete blank lines. 9846 9847@item --ignore-case 9848Ignore changes in case; consider upper- and lower-case to be the same. 9849 9850@item --ignore-matching-lines=@var{regexp} 9851Ignore changes that just insert or delete lines that match @var{regexp}. 9852 9853@item --ignore-space-change 9854Ignore trailing white space and consider all other sequences of one or 9855more white space characters to be equivalent. 9856 9857@item --initial-tab 9858Output a tab rather than a space before the text of a line in normal or 9859context format. This causes the alignment of tabs in the line to look 9860normal. 9861 9862@item -L @var{label} 9863Use @var{label} instead of the file name in the context format 9864and unified format headers. 9865 9866@item --label=@var{label} 9867Use @var{label} instead of the file name in the context format 9868and unified format headers. 9869 9870@item --left-column 9871Print only the left column of two common lines in side by side format. 9872 9873@item --line-format=@var{format} 9874Use @var{format} to output all input lines in if-then-else format. 9875@xref{Line formats}. 9876 9877@item --minimal 9878Change the algorithm to perhaps find a smaller set of changes. This 9879makes @code{diff} slower (sometimes much slower). 9880 9881@item -n 9882Output RCS-format diffs; like @samp{-f} except that each command 9883specifies the number of lines affected. 9884 9885@item -N 9886@itemx --new-file 9887In directory comparison, if a file is found in only one directory, 9888treat it as present but empty in the other directory. 9889 9890@item --new-group-format=@var{format} 9891Use @var{format} to output a group of lines taken from just the second 9892file in if-then-else format. @xref{Line group formats}. 9893 9894@item --new-line-format=@var{format} 9895Use @var{format} to output a line taken from just the second file in 9896if-then-else format. @xref{Line formats}. 9897 9898@item --old-group-format=@var{format} 9899Use @var{format} to output a group of lines taken from just the first 9900file in if-then-else format. @xref{Line group formats}. 9901 9902@item --old-line-format=@var{format} 9903Use @var{format} to output a line taken from just the first file in 9904if-then-else format. @xref{Line formats}. 9905 9906@item -p 9907Show which C function each change is in. 9908 9909@item --rcs 9910Output RCS-format diffs; like @samp{-f} except that each command 9911specifies the number of lines affected. 9912 9913@item --report-identical-files 9914@itemx -s 9915Report when two files are the same. 9916 9917@item --show-c-function 9918Show which C function each change is in. 9919 9920@item --show-function-line=@var{regexp} 9921In context and unified format, for each hunk of differences, show some 9922of the last preceding line that matches @var{regexp}. 9923 9924@item --side-by-side 9925Use the side by side output format. 9926 9927@item --speed-large-files 9928Use heuristics to speed handling of large files that have numerous 9929scattered small changes. 9930 9931@item --suppress-common-lines 9932Do not print common lines in side by side format. 9933 9934@item -t 9935Expand tabs to spaces in the output, to preserve the alignment of tabs 9936in the input files. 9937 9938@item -T 9939Output a tab rather than a space before the text of a line in normal or 9940context format. This causes the alignment of tabs in the line to look 9941normal. 9942 9943@item --text 9944Treat all files as text and compare them line-by-line, even if they 9945do not appear to be text. 9946 9947@item -u 9948Use the unified output format. 9949 9950@item --unchanged-group-format=@var{format} 9951Use @var{format} to output a group of common lines taken from both files 9952in if-then-else format. @xref{Line group formats}. 9953 9954@item --unchanged-line-format=@var{format} 9955Use @var{format} to output a line common to both files in if-then-else 9956format. @xref{Line formats}. 9957 9958@item -U @var{lines} 9959@itemx --unified@r{[}=@var{lines}@r{]} 9960Use the unified output format, showing @var{lines} (an integer) lines of 9961context, or three if @var{lines} is not given. 9962For proper operation, @code{patch} typically needs at least two lines of 9963context. 9964 9965@item -w 9966Ignore white space when comparing lines. 9967 9968@item -W @var{columns} 9969@itemx --width=@var{columns} 9970Use an output width of @var{columns} in side by side format. 9971 9972@item -y 9973Use the side by side output format. 9974@end table 9975 9976@menu 9977* Line group formats:: Line group formats 9978* Line formats:: Line formats 9979@end menu 9980 9981@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9982@node Line group formats 9983@appendixsubsubsec Line group formats 9984 9985Line group formats let you specify formats suitable for many 9986applications that allow if-then-else input, including programming 9987languages and text formatting languages. A line group format specifies 9988the output format for a contiguous group of similar lines. 9989 9990For example, the following command compares the TeX file @file{myfile} 9991with the original version from the repository, 9992and outputs a merged file in which old regions are 9993surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 9994regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 9995 9996@example 9997cvs diff \ 9998 --old-group-format='\begin@{em@} 9999%<\end@{em@} 10000' \ 10001 --new-group-format='\begin@{bf@} 10002%>\end@{bf@} 10003' \ 10004 myfile 10005@end example 10006 10007The following command is equivalent to the above example, but it is a 10008little more verbose, because it spells out the default line group formats. 10009 10010@example 10011cvs diff \ 10012 --old-group-format='\begin@{em@} 10013%<\end@{em@} 10014' \ 10015 --new-group-format='\begin@{bf@} 10016%>\end@{bf@} 10017' \ 10018 --unchanged-group-format='%=' \ 10019 --changed-group-format='\begin@{em@} 10020%<\end@{em@} 10021\begin@{bf@} 10022%>\end@{bf@} 10023' \ 10024 myfile 10025@end example 10026 10027Here is a more advanced example, which outputs a diff listing with 10028headers containing line numbers in a ``plain English'' style. 10029 10030@example 10031cvs diff \ 10032 --unchanged-group-format='' \ 10033 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 10034%<' \ 10035 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 10036%>' \ 10037 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 10038%<-------- to: 10039%>' \ 10040 myfile 10041@end example 10042 10043To specify a line group format, use one of the options 10044listed below. You can specify up to four line group formats, one for 10045each kind of line group. You should quote @var{format}, because it 10046typically contains shell metacharacters. 10047 10048@table @samp 10049@item --old-group-format=@var{format} 10050These line groups are hunks containing only lines from the first file. 10051The default old group format is the same as the changed group format if 10052it is specified; otherwise it is a format that outputs the line group as-is. 10053 10054@item --new-group-format=@var{format} 10055These line groups are hunks containing only lines from the second 10056file. The default new group format is same as the changed group 10057format if it is specified; otherwise it is a format that outputs the 10058line group as-is. 10059 10060@item --changed-group-format=@var{format} 10061These line groups are hunks containing lines from both files. The 10062default changed group format is the concatenation of the old and new 10063group formats. 10064 10065@item --unchanged-group-format=@var{format} 10066These line groups contain lines common to both files. The default 10067unchanged group format is a format that outputs the line group as-is. 10068@end table 10069 10070In a line group format, ordinary characters represent themselves; 10071conversion specifications start with @samp{%} and have one of the 10072following forms. 10073 10074@table @samp 10075@item %< 10076stands for the lines from the first file, including the trailing newline. 10077Each line is formatted according to the old line format (@pxref{Line formats}). 10078 10079@item %> 10080stands for the lines from the second file, including the trailing newline. 10081Each line is formatted according to the new line format. 10082 10083@item %= 10084stands for the lines common to both files, including the trailing newline. 10085Each line is formatted according to the unchanged line format. 10086 10087@item %% 10088stands for @samp{%}. 10089 10090@item %c'@var{C}' 10091where @var{C} is a single character, stands for @var{C}. 10092@var{C} may not be a backslash or an apostrophe. 10093For example, @samp{%c':'} stands for a colon, even inside 10094the then-part of an if-then-else format, which a colon would 10095normally terminate. 10096 10097@item %c'\@var{O}' 10098where @var{O} is a string of 1, 2, or 3 octal digits, 10099stands for the character with octal code @var{O}. 10100For example, @samp{%c'\0'} stands for a null character. 10101 10102@item @var{F}@var{n} 10103where @var{F} is a @code{printf} conversion specification and @var{n} is one 10104of the following letters, stands for @var{n}'s value formatted with @var{F}. 10105 10106@table @samp 10107@item e 10108The line number of the line just before the group in the old file. 10109 10110@item f 10111The line number of the first line in the group in the old file; 10112equals @var{e} + 1. 10113 10114@item l 10115The line number of the last line in the group in the old file. 10116 10117@item m 10118The line number of the line just after the group in the old file; 10119equals @var{l} + 1. 10120 10121@item n 10122The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 10123 10124@item E, F, L, M, N 10125Likewise, for lines in the new file. 10126 10127@end table 10128 10129The @code{printf} conversion specification can be @samp{%d}, 10130@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 10131lower case hexadecimal, or upper case hexadecimal output 10132respectively. After the @samp{%} the following options can appear in 10133sequence: a @samp{-} specifying left-justification; an integer 10134specifying the minimum field width; and a period followed by an 10135optional integer specifying the minimum number of digits. 10136For example, @samp{%5dN} prints the number of new lines in the group 10137in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 10138 10139@item (@var{A}=@var{B}?@var{T}:@var{E}) 10140If @var{A} equals @var{B} then @var{T} else @var{E}. 10141@var{A} and @var{B} are each either a decimal constant 10142or a single letter interpreted as above. 10143This format spec is equivalent to @var{T} if 10144@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 10145 10146For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 10147@samp{no lines} if @var{N} (the number of lines in the group in the 10148new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 10149otherwise. 10150@end table 10151 10152@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10153@node Line formats 10154@appendixsubsubsec Line formats 10155 10156Line formats control how each line taken from an input file is 10157output as part of a line group in if-then-else format. 10158 10159For example, the following command outputs text with a one-column 10160change indicator to the left of the text. The first column of output 10161is @samp{-} for deleted lines, @samp{|} for added lines, and a space 10162for unchanged lines. The formats contain newline characters where 10163newlines are desired on output. 10164 10165@example 10166cvs diff \ 10167 --old-line-format='-%l 10168' \ 10169 --new-line-format='|%l 10170' \ 10171 --unchanged-line-format=' %l 10172' \ 10173 myfile 10174@end example 10175 10176To specify a line format, use one of the following options. You should 10177quote @var{format}, since it often contains shell metacharacters. 10178 10179@table @samp 10180@item --old-line-format=@var{format} 10181formats lines just from the first file. 10182 10183@item --new-line-format=@var{format} 10184formats lines just from the second file. 10185 10186@item --unchanged-line-format=@var{format} 10187formats lines common to both files. 10188 10189@item --line-format=@var{format} 10190formats all lines; in effect, it sets all three above options simultaneously. 10191@end table 10192 10193In a line format, ordinary characters represent themselves; 10194conversion specifications start with @samp{%} and have one of the 10195following forms. 10196 10197@table @samp 10198@item %l 10199stands for the contents of the line, not counting its trailing 10200newline (if any). This format ignores whether the line is incomplete. 10201 10202@item %L 10203stands for the contents of the line, including its trailing newline 10204(if any). If a line is incomplete, this format preserves its 10205incompleteness. 10206 10207@item %% 10208stands for @samp{%}. 10209 10210@item %c'@var{C}' 10211where @var{C} is a single character, stands for @var{C}. 10212@var{C} may not be a backslash or an apostrophe. 10213For example, @samp{%c':'} stands for a colon. 10214 10215@item %c'\@var{O}' 10216where @var{O} is a string of 1, 2, or 3 octal digits, 10217stands for the character with octal code @var{O}. 10218For example, @samp{%c'\0'} stands for a null character. 10219 10220@item @var{F}n 10221where @var{F} is a @code{printf} conversion specification, 10222stands for the line number formatted with @var{F}. 10223For example, @samp{%.5dn} prints the line number using the 10224@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 10225more about printf conversion specifications. 10226 10227@end table 10228 10229The default line format is @samp{%l} followed by a newline character. 10230 10231If the input contains tab characters and it is important that they line 10232up on output, you should ensure that @samp{%l} or @samp{%L} in a line 10233format is just after a tab stop (e.g.@: by preceding @samp{%l} or 10234@samp{%L} with a tab character), or you should use the @samp{-t} or 10235@samp{--expand-tabs} option. 10236 10237Taken together, the line and line group formats let you specify many 10238different formats. For example, the following command uses a format 10239similar to @code{diff}'s normal format. You can tailor this command 10240to get fine control over @code{diff}'s output. 10241 10242@example 10243cvs diff \ 10244 --old-line-format='< %l 10245' \ 10246 --new-line-format='> %l 10247' \ 10248 --old-group-format='%df%(f=l?:,%dl)d%dE 10249%<' \ 10250 --new-group-format='%dea%dF%(F=L?:,%dL) 10251%>' \ 10252 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 10253%<--- 10254%>' \ 10255 --unchanged-group-format='' \ 10256 myfile 10257@end example 10258 10259@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10260@node diff examples 10261@appendixsubsec diff examples 10262 10263The following line produces a Unidiff (@samp{-u} flag) 10264between revision 1.14 and 1.19 of 10265@file{backend.c}. Due to the @samp{-kk} flag no 10266keywords are substituted, so differences that only depend 10267on keyword substitution are ignored. 10268 10269@example 10270$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 10271@end example 10272 10273Suppose the experimental branch EXPR1 was based on a 10274set of files tagged RELEASE_1_0. To see what has 10275happened on that branch, the following can be used: 10276 10277@example 10278$ cvs diff -r RELEASE_1_0 -r EXPR1 10279@end example 10280 10281A command like this can be used to produce a context 10282diff between two releases: 10283 10284@example 10285$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 10286@end example 10287 10288If you are maintaining ChangeLogs, a command like the following 10289just before you commit your changes may help you write 10290the ChangeLog entry. All local modifications that have 10291not yet been committed will be printed. 10292 10293@example 10294$ cvs diff -u | less 10295@end example 10296 10297@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10298@node export 10299@appendixsec export---Export sources from CVS, similar to checkout 10300@cindex export (subcommand) 10301 10302@itemize @bullet 10303@item 10304Synopsis: export [-flNnR] (-r rev[:date] | -D date) [-k subst] [-d dir] module@dots{} 10305@item 10306Requires: repository. 10307@item 10308Changes: current directory. 10309@end itemize 10310 10311This command is a variant of @code{checkout}; use it 10312when you want a copy of the source for module without 10313the @sc{cvs} administrative directories. For example, you 10314might use @code{export} to prepare source for shipment 10315off-site. This command requires that you specify a 10316date or tag (with @samp{-D} or @samp{-r}), so that you 10317can count on reproducing the source you ship to others 10318(and thus it always prunes empty directories). 10319 10320One often would like to use @samp{-kv} with @code{cvs 10321export}. This causes any keywords to be 10322expanded such that an import done at some other site 10323will not lose the keyword revision information. But be 10324aware that doesn't handle an export containing binary 10325files correctly. Also be aware that after having used 10326@samp{-kv}, one can no longer use the @code{ident} 10327command (which is part of the @sc{rcs} suite---see 10328ident(1)) which looks for keyword strings. If 10329you want to be able to use @code{ident} you must not 10330use @samp{-kv}. 10331 10332@menu 10333* export options:: export options 10334@end menu 10335 10336@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10337@node export options 10338@appendixsubsec export options 10339 10340These standard options are supported by @code{export} 10341(@pxref{Common options}, for a complete description of 10342them): 10343 10344@table @code 10345@item -D @var{date} 10346Use the most recent revision no later than @var{date}. 10347 10348@item -f 10349If no matching revision is found, retrieve the most 10350recent revision (instead of ignoring the file). 10351 10352@item -l 10353Local; run only in current working directory. 10354 10355@item -n 10356Do not run any checkout program. 10357 10358@item -R 10359Export directories recursively. This is on by default. 10360 10361@item -r @var{tag}[:@var{date}] 10362Export the revision specified by @var{tag} or, when @var{date} is specified 10363and @var{tag} is a branch tag, the version from the branch @var{tag} as it 10364existed on @var{date}. See @ref{Common options}. 10365@end table 10366 10367In addition, these options (that are common to 10368@code{checkout} and @code{export}) are also supported: 10369 10370@table @code 10371@item -d @var{dir} 10372Create a directory called @var{dir} for the working 10373files, instead of using the module name. 10374@xref{checkout options}, for complete details on how 10375@sc{cvs} handles this flag. 10376 10377@item -k @var{subst} 10378Set keyword expansion mode (@pxref{Substitution modes}). 10379 10380@item -N 10381Only useful together with @samp{-d @var{dir}}. 10382@xref{checkout options}, for complete details on how 10383@sc{cvs} handles this flag. 10384@end table 10385 10386@ignore 10387@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10388@c @node export examples 10389@appendixsubsec export examples 10390 10391Contributed examples are gratefully accepted. 10392@c -- Examples here!! 10393@end ignore 10394 10395@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10396@node history 10397@appendixsec history---Show status of files and users 10398@cindex history (subcommand) 10399 10400@itemize @bullet 10401@item 10402Synopsis: history [-report] [-flags] [-options args] [files@dots{}] 10403@item 10404Requires: the file @file{$CVSROOT/CVSROOT/history} 10405@item 10406Changes: nothing. 10407@end itemize 10408 10409@sc{cvs} can keep a history log that tracks each use of most @sc{cvs} 10410commands. You can use @code{history} to display this information in 10411various formats. 10412 10413To enable logging, the @samp{LogHistory} config option must be set to 10414some value other than the empty string and the history file specified by 10415the @samp{HistoryLogPath} option must be writable by all users who may run 10416the @sc{cvs} executable (@pxref{config}). 10417 10418To enable the @code{history} command, logging must be enabled as above and 10419the @samp{HistorySearchPath} config option (@pxref{config}) must be set to 10420specify some number of the history logs created thereby and these files must 10421be readable by each user who might run the @code{history} command. 10422 10423Creating a repository via the @code{cvs init} command will enable logging of 10424all possible events to a single history log file 10425(@file{$CVSROOT/CVSROOT/history}) with read and write permissions for all 10426users (@pxref{Creating a repository}). 10427 10428@strong{Note: @code{history} uses @samp{-f}, @samp{-l}, 10429@samp{-n}, and @samp{-p} in ways that conflict with the 10430normal use inside @sc{cvs} (@pxref{Common options}).} 10431 10432@menu 10433* history options:: history options 10434@end menu 10435 10436@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10437@node history options 10438@appendixsubsec history options 10439 10440Several options (shown above as @samp{-report}) control what 10441kind of report is generated: 10442 10443@table @code 10444@item -c 10445Report on each time commit was used (i.e., each time 10446the repository was modified). 10447 10448@item -e 10449Everything (all record types). Equivalent to 10450specifying @samp{-x} with all record types. Of course, 10451@samp{-e} will also include record types which are 10452added in a future version of @sc{cvs}; if you are 10453writing a script which can only handle certain record 10454types, you'll want to specify @samp{-x}. 10455 10456@item -m @var{module} 10457Report on a particular module. (You can meaningfully 10458use @samp{-m} more than once on the command line.) 10459 10460@item -o 10461Report on checked-out modules. This is the default report type. 10462 10463@item -T 10464Report on all tags. 10465 10466@item -x @var{type} 10467Extract a particular set of record types @var{type} from the @sc{cvs} 10468history. The types are indicated by single letters, 10469which you may specify in combination. 10470 10471Certain commands have a single record type: 10472 10473@table @code 10474@item F 10475release 10476@item O 10477checkout 10478@item E 10479export 10480@item T 10481rtag 10482@end table 10483 10484@noindent 10485One of five record types may result from an update: 10486 10487@table @code 10488@item C 10489A merge was necessary but collisions were 10490detected (requiring manual merging). 10491@item G 10492A merge was necessary and it succeeded. 10493@item U 10494A working file was copied from the repository. 10495@item P 10496A working file was patched to match the repository. 10497@item W 10498The working copy of a file was deleted during 10499update (because it was gone from the repository). 10500@end table 10501 10502@noindent 10503One of three record types results from commit: 10504 10505@table @code 10506@item A 10507A file was added for the first time. 10508@item M 10509A file was modified. 10510@item R 10511A file was removed. 10512@end table 10513@end table 10514 10515The options shown as @samp{-flags} constrain or expand 10516the report without requiring option arguments: 10517 10518@table @code 10519@item -a 10520Show data for all users (the default is to show data 10521only for the user executing @code{history}). 10522 10523@item -l 10524Show last modification only. 10525 10526@item -w 10527Show only the records for modifications done from the 10528same working directory where @code{history} is 10529executing. 10530@end table 10531 10532The options shown as @samp{-options @var{args}} constrain the report 10533based on an argument: 10534 10535@table @code 10536@item -b @var{str} 10537Show data back to a record containing the string 10538@var{str} in either the module name, the file name, or 10539the repository path. 10540 10541@item -D @var{date} 10542Show data since @var{date}. This is slightly different 10543from the normal use of @samp{-D @var{date}}, which 10544selects the newest revision older than @var{date}. 10545 10546@item -f @var{file} 10547Show data for a particular file 10548(you can specify several @samp{-f} options on the same command line). 10549This is equivalent to specifying the file on the command line. 10550 10551@item -n @var{module} 10552Show data for a particular module 10553(you can specify several @samp{-n} options on the same command line). 10554 10555@item -p @var{repository} 10556Show data for a particular source repository (you 10557can specify several @samp{-p} options on the same command 10558line). 10559 10560@item -r @var{rev} 10561Show records referring to revisions since the revision 10562or tag named @var{rev} appears in individual @sc{rcs} 10563files. Each @sc{rcs} file is searched for the revision or 10564tag. 10565 10566@item -t @var{tag} 10567Show records since tag @var{tag} was last added to the 10568history file. This differs from the @samp{-r} flag 10569above in that it reads only the history file, not the 10570@sc{rcs} files, and is much faster. 10571 10572@item -u @var{name} 10573Show records for user @var{name}. 10574 10575@item -z @var{timezone} 10576Show times in the selected records using the specified 10577time zone instead of UTC. 10578@end table 10579 10580@ignore 10581@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10582@c @node history examples 10583@appendixsubsec history examples 10584 10585Contributed examples will gratefully be accepted. 10586@c -- Examples here! 10587@end ignore 10588 10589@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10590@node import 10591@appendixsec import---Import sources into CVS, using vendor branches 10592@cindex import (subcommand) 10593 10594@c FIXME: This node is way too long for one which has subnodes. 10595 10596@itemize @bullet 10597@item 10598Synopsis: import [-options] repository vendortag releasetag@dots{} 10599@item 10600Requires: Repository, source distribution directory. 10601@item 10602Changes: repository. 10603@end itemize 10604 10605Use @code{import} to incorporate an entire source 10606distribution from an outside source (e.g., a source 10607vendor) into your source repository directory. You can 10608use this command both for initial creation of a 10609repository, and for wholesale updates to the module 10610from the outside source. @xref{Tracking sources}, for 10611a discussion on this subject. 10612 10613The @var{repository} argument gives a directory name 10614(or a path to a directory) under the @sc{cvs} root directory 10615for repositories; if the directory did not exist, 10616import creates it. 10617 10618When you use import for updates to source that has been 10619modified in your source repository (since a prior 10620import), it will notify you of any files that conflict 10621in the two branches of development; use @samp{checkout 10622-j} to reconcile the differences, as import instructs 10623you to do. 10624 10625If @sc{cvs} decides a file should be ignored 10626(@pxref{cvsignore}), it does not import it and prints 10627@samp{I } followed by the filename (@pxref{import output}, for a 10628complete description of the output). 10629 10630If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 10631any file whose names match the specifications in that 10632file will be treated as packages and the appropriate 10633filtering will be performed on the file/directory 10634before being imported. @xref{Wrappers}. 10635 10636The outside source is saved in a first-level 10637branch, by default 1.1.1. Updates are leaves of this 10638branch; for example, files from the first imported 10639collection of source will be revision 1.1.1.1, then 10640files from the first imported update will be revision 106411.1.1.2, and so on. 10642 10643At least three arguments are required. 10644@var{repository} is needed to identify the collection 10645of source. @var{vendortag} is a tag for the entire 10646branch (e.g., for 1.1.1). You must also specify at 10647least one @var{releasetag} to uniquely identify the files at 10648the leaves created each time you execute @code{import}. The 10649@var{releasetag} should be new, not previously existing in the 10650repository file, and uniquely identify the imported release, 10651 10652@c I'm not completely sure this belongs here. But 10653@c we need to say it _somewhere_ reasonably obvious; it 10654@c is a common misconception among people first learning CVS 10655Note that @code{import} does @emph{not} change the 10656directory in which you invoke it. In particular, it 10657does not set up that directory as a @sc{cvs} working 10658directory; if you want to work with the sources import 10659them first and then check them out into a different 10660directory (@pxref{Getting the source}). 10661 10662@menu 10663* import options:: import options 10664* import output:: import output 10665* import examples:: import examples 10666@end menu 10667 10668@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10669@node import options 10670@appendixsubsec import options 10671 10672This standard option is supported by @code{import} 10673(@pxref{Common options}, for a complete description): 10674 10675@table @code 10676@item -m @var{message} 10677Use @var{message} as log information, instead of 10678invoking an editor. 10679@end table 10680 10681There are the following additional special options. 10682 10683@table @code 10684@item -b @var{branch} 10685See @ref{Multiple vendor branches}. 10686 10687@item -k @var{subst} 10688Indicate the keyword expansion mode desired. This 10689setting will apply to all files created during the 10690import, but not to any files that previously existed in 10691the repository. See @ref{Substitution modes}, for a 10692list of valid @samp{-k} settings. 10693 10694@item -I @var{name} 10695Specify file names that should be ignored during 10696import. You can use this option repeatedly. To avoid 10697ignoring any files at all (even those ignored by 10698default), specify `-I !'. 10699 10700@var{name} can be a file name pattern of the same type 10701that you can specify in the @file{.cvsignore} file. 10702@xref{cvsignore}. 10703@c -- Is this really true? 10704 10705@item -W @var{spec} 10706Specify file names that should be filtered during 10707import. You can use this option repeatedly. 10708 10709@var{spec} can be a file name pattern of the same type 10710that you can specify in the @file{.cvswrappers} 10711file. @xref{Wrappers}. 10712 10713@item -X 10714Modify the algorithm used by @sc{cvs} when importing new files 10715so that new files do not immediately appear on the main trunk. 10716 10717Specifically, this flag causes @sc{cvs} to mark new files as 10718if they were deleted on the main trunk, by taking the following 10719steps for each file in addition to those normally taken on import: 10720creating a new revision on the main trunk indicating that 10721the new file is @code{dead}, resetting the new file's default branch, 10722and placing the file in the Attic (@pxref{Attic}) directory. 10723 10724Use of this option can be forced on a repository-wide basis 10725by setting the @samp{ImportNewFilesToVendorBranchOnly} option in 10726CVSROOT/config (@pxref{config}). 10727@end table 10728 10729@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10730@node import output 10731@appendixsubsec import output 10732 10733@code{import} keeps you informed of its progress by printing a line 10734for each file, preceded by one character indicating the status of the file: 10735 10736@table @code 10737@item U @var{file} 10738The file already exists in the repository and has not been locally 10739modified; a new revision has been created (if necessary). 10740 10741@item N @var{file} 10742The file is a new file which has been added to the repository. 10743 10744@item C @var{file} 10745The file already exists in the repository but has been locally modified; 10746you will have to merge the changes. 10747 10748@item I @var{file} 10749The file is being ignored (@pxref{cvsignore}). 10750 10751@cindex Symbolic link, importing 10752@cindex Link, symbolic, importing 10753@c FIXME: also (somewhere else) probably 10754@c should be documenting what happens if you "cvs add" 10755@c a symbolic link. Also maybe what happens if 10756@c you manually create symbolic links within the 10757@c repository (? - not sure why we'd want to suggest 10758@c doing that). 10759@item L @var{file} 10760The file is a symbolic link; @code{cvs import} ignores symbolic links. 10761People periodically suggest that this behavior should 10762be changed, but if there is a consensus on what it 10763should be changed to, it is not apparent. 10764(Various options in the @file{modules} file can be used 10765to recreate symbolic links on checkout, update, etc.; 10766@pxref{modules}.) 10767@end table 10768 10769@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10770@node import examples 10771@appendixsubsec import examples 10772 10773See @ref{Tracking sources}, and @ref{From files}. 10774 10775@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10776@node log 10777@appendixsec log---Print out log information for files 10778@cindex log (subcommand) 10779 10780@itemize @bullet 10781@item 10782Synopsis: log [options] [files@dots{}] 10783@item 10784Requires: repository, working directory. 10785@item 10786Changes: nothing. 10787@end itemize 10788 10789Display log information for files. @code{log} used to 10790call the @sc{rcs} utility @code{rlog}. Although this 10791is no longer true in the current sources, this history 10792determines the format of the output and the options, 10793which are not quite in the style of the other @sc{cvs} 10794commands. 10795 10796@cindex Timezone, in output 10797@cindex Zone, time, in output 10798The output includes the location of the @sc{rcs} file, 10799the @dfn{head} revision (the latest revision on the 10800trunk), all symbolic names (tags) and some other 10801things. For each revision, the revision number, the 10802date, the author, the number of lines added/deleted, the commitid 10803and the log message are printed. All dates are displayed 10804in local time at the client. This is typically specified in 10805the @code{$TZ} environment variable, which can be set to 10806govern how @code{log} displays dates. 10807 10808@strong{Note: @code{log} uses @samp{-R} in a way that conflicts 10809with the normal use inside @sc{cvs} (@pxref{Common options}).} 10810 10811@menu 10812* log options:: log options 10813* log examples:: log examples 10814@end menu 10815 10816@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10817@node log options 10818@appendixsubsec log options 10819 10820By default, @code{log} prints all information that is 10821available. All other options restrict the output. Note that the revision 10822selection options (@code{-d}, @code{-r}, @code{-s}, and @code{-w}) have no 10823effect, other than possibly causing a search for files in Attic directories, 10824when used in conjunction with the options that restrict the output to only 10825@code{log} header fields (@code{-b}, @code{-h}, @code{-R}, and @code{-t}) 10826unless the @code{-S} option is also specified. 10827 10828@table @code 10829@item -b 10830Print information about the revisions on the default 10831branch, normally the highest branch on the trunk. 10832 10833@item -d @var{dates} 10834Print information about revisions with a checkin 10835date/time in the range given by the 10836semicolon-separated list of dates. The date formats 10837accepted are those accepted by the @samp{-D} option to 10838many other @sc{cvs} commands (@pxref{Common options}). 10839Dates can be combined into ranges as follows: 10840 10841@c Should we be thinking about accepting ISO8601 10842@c ranges? For example "1972-09-10/1972-09-12". 10843@table @code 10844@item @var{d1}<@var{d2} 10845@itemx @var{d2}>@var{d1} 10846Select the revisions that were deposited between 10847@var{d1} and @var{d2}. 10848 10849@item <@var{d} 10850@itemx @var{d}> 10851Select all revisions dated @var{d} or earlier. 10852 10853@item @var{d}< 10854@itemx >@var{d} 10855Select all revisions dated @var{d} or later. 10856 10857@item @var{d} 10858Select the single, latest revision dated @var{d} or 10859earlier. 10860@end table 10861 10862The @samp{>} or @samp{<} characters may be followed by 10863@samp{=} to indicate an inclusive range rather than an 10864exclusive one. 10865 10866Note that the separator is a semicolon (;). 10867 10868@item -h 10869Print only the name of the @sc{rcs} file, name 10870of the file in the working directory, head, 10871default branch, access list, locks, symbolic names, and 10872suffix. 10873 10874@item -l 10875Local; run only in current working directory. (Default 10876is to run recursively). 10877 10878@item -N 10879Do not print the list of tags for this file. This 10880option can be very useful when your site uses a lot of 10881tags, so rather than "more"'ing over 3 pages of tag 10882information, the log information is presented without 10883tags at all. 10884 10885@item -R 10886Print only the name of the @sc{rcs} file. 10887 10888@c Note that using a bare revision (in addition to not 10889@c being explicitly documented here) is potentially 10890@c confusing; it shows the log message to get from the 10891@c previous revision to that revision. "-r1.3 -r1.6" 10892@c (equivalent to "-r1.3,1.6") is even worse; it 10893@c prints the messages to get from 1.2 to 1.3 and 1.5 10894@c to 1.6. By analogy with "cvs diff", users might 10895@c expect that it is more like specifying a range. 10896@c It is not 100% clear to me how much of this should 10897@c be documented (for example, multiple -r options 10898@c perhaps could/should be deprecated given the false 10899@c analogy with "cvs diff"). 10900@c In general, this section should be rewritten to talk 10901@c about messages to get from revision rev1 to rev2, 10902@c rather than messages for revision rev2 (that is, the 10903@c messages are associated with a change not a static 10904@c revision and failing to make this distinction causes 10905@c much confusion). 10906@item -r@var{revisions} 10907Print information about revisions given in the 10908comma-separated list @var{revisions} of revisions and 10909ranges. The following table explains the available 10910range formats: 10911 10912@table @code 10913@item @var{rev1}:@var{rev2} 10914Revisions @var{rev1} to @var{rev2} (which must be on 10915the same branch). 10916 10917@item @var{rev1}::@var{rev2} 10918The same, but excluding @var{rev1}. 10919 10920@item :@var{rev} 10921@itemx ::@var{rev} 10922Revisions from the beginning of the branch up to 10923and including @var{rev}. 10924 10925@item @var{rev}: 10926Revisions starting with @var{rev} to the end of the 10927branch containing @var{rev}. 10928 10929@item @var{rev}:: 10930Revisions starting just after @var{rev} to the end of the 10931branch containing @var{rev}. 10932 10933@item @var{branch} 10934An argument that is a branch means all revisions on 10935that branch. 10936 10937@item @var{branch1}:@var{branch2} 10938@itemx @var{branch1}::@var{branch2} 10939A range of branches means all revisions 10940on the branches in that range. 10941 10942@item @var{branch}. 10943The latest revision in @var{branch}. 10944@end table 10945 10946A bare @samp{-r} with no revisions means the latest 10947revision on the default branch, normally the trunk. 10948There can be no space between the @samp{-r} option and 10949its argument. 10950 10951@item -S 10952Suppress the header if no revisions are selected. 10953 10954@item -s @var{states} 10955Print information about revisions whose state 10956attributes match one of the states given in the 10957comma-separated list @var{states}. Individual states may 10958be any text string, though @sc{cvs} commonly only uses two 10959states, @samp{Exp} and @samp{dead}. See @ref{admin options} 10960for more information. 10961 10962@item -t 10963Print the same as @samp{-h}, plus the descriptive text. 10964 10965@item -w@var{logins} 10966Print information about revisions checked in by users 10967with login names appearing in the comma-separated list 10968@var{logins}. If @var{logins} is omitted, the user's 10969login is assumed. There can be no space between the 10970@samp{-w} option and its argument. 10971@end table 10972 10973@code{log} prints the intersection of the revisions 10974selected with the options @samp{-d}, @samp{-s}, and 10975@samp{-w}, intersected with the union of the revisions 10976selected by @samp{-b} and @samp{-r}. 10977 10978@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10979@node log examples 10980@appendixsubsec log examples 10981 10982@cindex Timezone, in output 10983@cindex Zone, time, in output 10984Since @code{log} shows dates in local time, 10985you might want to see them in Coordinated Universal Time (UTC) or 10986some other timezone. 10987To do this you can set your @code{$TZ} environment 10988variable before invoking @sc{cvs}: 10989 10990@example 10991$ TZ=UTC cvs log foo.c 10992$ TZ=EST cvs log bar.c 10993@end example 10994 10995(If you are using a @code{csh}-style shell, like @code{tcsh}, 10996you would need to prefix the examples above with @code{env}.) 10997 10998@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10999@node ls & rls 11000@appendixsec ls & rls 11001@cindex ls (subcommand) 11002@cindex rls (subcommand) 11003 11004@itemize @bullet 11005@item 11006ls [-e | -l] [-RP] [-r tag[:date]] [-D date] [path@dots{}] 11007@item 11008Requires: repository for @code{rls}, repository & working directory for 11009@code{ls}. 11010@item 11011Changes: nothing. 11012@item 11013Synonym: @code{dir} & @code{list} are synonyms for @code{ls} and @code{rdir} 11014& @code{rlist} are synonyms for @code{rls}. 11015@end itemize 11016 11017The @code{ls} and @code{rls} commands are used to list 11018files and directories in the repository. 11019 11020By default @code{ls} lists the files and directories 11021that belong in your working directory, what would be 11022there after an @code{update}. 11023 11024By default @code{rls} lists the files and directories 11025on the tip of the trunk in the topmost directory of the 11026repository. 11027 11028Both commands accept an optional list of file and 11029directory names, relative to the working directory for 11030@code{ls} and the topmost directory of the repository 11031for @code{rls}. Neither is recursive by default. 11032 11033@menu 11034* ls & rls options:: ls & rls options 11035* rls examples: rls examples 11036@end menu 11037 11038@node ls & rls options 11039@appendixsubsec ls & rls options 11040 11041These standard options are supported by @code{ls} & @code{rls}: 11042 11043@table @code 11044@item -d 11045Show dead revisions (with tag when specified). 11046 11047@item -e 11048Display in CVS/Entries format. This format is meant to remain easily parsable 11049by automation. 11050 11051@item -l 11052Display all details. 11053 11054@item -P 11055Don't list contents of empty directories when recursing. 11056 11057@item -R 11058List recursively. 11059 11060@item -r @var{tag}[:@var{date}] 11061Show files specified by @var{tag} or, when @var{date} is specified 11062and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11063existed on @var{date}. See @ref{Common options}. 11064 11065@item -D @var{date} 11066Show files from date. 11067@end table 11068 11069@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11070@node rls examples 11071@appendixsubsec rls examples 11072 11073@example 11074$ cvs rls 11075cvs rls: Listing module: `.' 11076CVSROOT 11077first-dir 11078@end example 11079 11080@example 11081$ cvs rls CVSROOT 11082cvs rls: Listing module: `CVSROOT' 11083checkoutlist 11084commitinfo 11085config 11086cvswrappers 11087loginfo 11088modules 11089notify 11090rcsinfo 11091taginfo 11092verifymsg 11093 11094@end example 11095 11096@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11097@node rdiff 11098@appendixsec rdiff---'patch' format diffs between releases 11099@cindex rdiff (subcommand) 11100 11101@itemize @bullet 11102@item 11103rdiff [-flags] [-V vn] (-r tag1[:date1] | -D date1) [-r tag2[:date2] | -D date2] modules@dots{} 11104@item 11105Requires: repository. 11106@item 11107Changes: nothing. 11108@item 11109Synonym: patch 11110@end itemize 11111 11112Builds a Larry Wall format patch(1) file between two 11113releases, that can be fed directly into the @code{patch} 11114program to bring an old release up-to-date with the new 11115release. (This is one of the few @sc{cvs} commands that 11116operates directly from the repository, and doesn't 11117require a prior checkout.) The diff output is sent to 11118the standard output device. 11119 11120You can specify (using the standard @samp{-r} and 11121@samp{-D} options) any combination of one or two 11122revisions or dates. If only one revision or date is 11123specified, the patch file reflects differences between 11124that revision or date and the current head revisions in 11125the @sc{rcs} file. 11126 11127Note that if the software release affected is contained 11128in more than one directory, then it may be necessary to 11129specify the @samp{-p} option to the @code{patch} command when 11130patching the old sources, so that @code{patch} is able to find 11131the files that are located in other directories. 11132 11133@menu 11134* rdiff options:: rdiff options 11135* rdiff examples:: rdiff examples 11136@end menu 11137 11138@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11139@node rdiff options 11140@appendixsubsec rdiff options 11141 11142These standard options are supported by @code{rdiff} 11143(@pxref{Common options}, for a complete description of 11144them): 11145 11146@table @code 11147@item -D @var{date} 11148Use the most recent revision no later than @var{date}. 11149 11150@item -f 11151If no matching revision is found, retrieve the most 11152recent revision (instead of ignoring the file). 11153 11154@item -k @var{kflag} 11155Process keywords according to @var{kflag}. See 11156@ref{Keyword substitution}. 11157 11158@item -l 11159Local; don't descend subdirectories. 11160 11161@item -p 11162Show which C function each change is in. 11163 11164@item -R 11165Examine directories recursively. This option is on by default. 11166 11167@item -r @var{tag} 11168Use the revision specified by @var{tag}, or when @var{date} is specified 11169and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11170existed on @var{date}. See @ref{Common options}. 11171@end table 11172 11173In addition to the above, these options are available: 11174 11175@table @code 11176@item -c 11177Use the context diff format. This is the default format. 11178 11179@item -s 11180Create a summary change report instead of a patch. The 11181summary includes information about files that were 11182changed or added between the releases. It is sent to 11183the standard output device. This is useful for finding 11184out, for example, which files have changed between two 11185dates or revisions. 11186 11187@item -t 11188A diff of the top two revisions is sent to the standard 11189output device. This is most useful for seeing what the 11190last change to a file was. 11191 11192@item -u 11193Use the unidiff format for the context diffs. 11194Remember that old versions 11195of the @code{patch} program can't handle the unidiff 11196format, so if you plan to post this patch to the net 11197you should probably not use @samp{-u}. 11198 11199@item -V @var{vn} 11200Expand keywords according to the rules current in 11201@sc{rcs} version @var{vn} (the expansion format changed with 11202@sc{rcs} version 5). Note that this option is no 11203longer accepted. @sc{cvs} will always expand keywords the 11204way that @sc{rcs} version 5 does. 11205@end table 11206 11207@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11208@node rdiff examples 11209@appendixsubsec rdiff examples 11210 11211Suppose you receive mail from @t{foo@@example.net} asking for an 11212update from release 1.2 to 1.4 of the tc compiler. You 11213have no such patches on hand, but with @sc{cvs} that can 11214easily be fixed with a command such as this: 11215 11216@example 11217$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 11218$$ Mail -s 'The patches you asked for' foo@@example.net 11219@end example 11220 11221Suppose you have made release 1.3, and forked a branch 11222called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1} 11223corresponds to release 1.3.1, which was made some time 11224ago. Now, you want to see how much development has been 11225done on the branch. This command can be used: 11226 11227@example 11228$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 11229cvs rdiff: Diffing module-name 11230File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 11231File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 11232File bar.h,v changed from revision 1.29.2.1 to 1.2 11233@end example 11234 11235@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11236@node release 11237@appendixsec release---Indicate that a Module is no longer in use 11238@cindex release (subcommand) 11239 11240@itemize @bullet 11241@item 11242release [-d] directories@dots{} 11243@item 11244Requires: Working directory. 11245@item 11246Changes: Working directory, history log. 11247@end itemize 11248 11249This command is meant to safely cancel the effect of 11250@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it 11251isn't strictly necessary to use this command. You can 11252always simply delete your working directory, if you 11253like; but you risk losing changes you may have 11254forgotten, and you leave no trace in the @sc{cvs} history 11255file (@pxref{history file}) that you've abandoned your 11256checkout. 11257 11258Use @samp{cvs release} to avoid these problems. This 11259command checks that no uncommitted changes are 11260present; that you are executing it from immediately 11261above a @sc{cvs} working directory; and that the repository 11262recorded for your files is the same as the repository 11263defined in the module database. 11264 11265If all these conditions are true, @samp{cvs release} 11266leaves a record of its execution (attesting to your 11267intentionally abandoning your checkout) in the @sc{cvs} 11268history log. 11269 11270@menu 11271* release options:: release options 11272* release output:: release output 11273* release examples:: release examples 11274@end menu 11275 11276@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11277@node release options 11278@appendixsubsec release options 11279 11280The @code{release} command supports one command option: 11281 11282@table @code 11283@item -d 11284Delete your working copy of the file if the release 11285succeeds. If this flag is not given your files will 11286remain in your working directory. 11287 11288@strong{WARNING: The @code{release} command deletes 11289all directories and files recursively. This 11290has the very serious side-effect that any directory 11291that you have created inside your checked-out sources, 11292and not added to the repository (using the @code{add} 11293command; @pxref{Adding files}) will be silently deleted---even 11294if it is non-empty!} 11295@end table 11296 11297@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11298@node release output 11299@appendixsubsec release output 11300 11301Before @code{release} releases your sources it will 11302print a one-line message for any file that is not 11303up-to-date. 11304 11305@table @code 11306@item U @var{file} 11307@itemx P @var{file} 11308There exists a newer revision of this file in the 11309repository, and you have not modified your local copy 11310of the file (@samp{U} and @samp{P} mean the same thing). 11311 11312@item A @var{file} 11313The file has been added to your private copy of the 11314sources, but has not yet been committed to the 11315repository. If you delete your copy of the sources 11316this file will be lost. 11317 11318@item R @var{file} 11319The file has been removed from your private copy of the 11320sources, but has not yet been removed from the 11321repository, since you have not yet committed the 11322removal. @xref{commit}. 11323 11324@item M @var{file} 11325The file is modified in your working directory. There 11326might also be a newer revision inside the repository. 11327 11328@item ? @var{file} 11329@var{file} is in your working directory, but does not 11330correspond to anything in the source repository, and is 11331not in the list of files for @sc{cvs} to ignore (see the 11332description of the @samp{-I} option, and 11333@pxref{cvsignore}). If you remove your working 11334sources, this file will be lost. 11335@end table 11336 11337@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11338@node release examples 11339@appendixsubsec release examples 11340 11341Release the @file{tc} directory, and delete your local working copy 11342of the files. 11343 11344@example 11345$ cd .. # @r{You must stand immediately above the} 11346 # @r{sources when you issue @samp{cvs release}.} 11347$ cvs release -d tc 11348You have [0] altered files in this repository. 11349Are you sure you want to release (and delete) directory `tc': y 11350$ 11351@end example 11352 11353@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11354@node server & pserver 11355@appendixsec server & pserver---Act as a server for a client on stdin/stdout 11356@cindex pserver (subcommand) 11357@cindex server (subcommand) 11358 11359@itemize @bullet 11360@item 11361pserver [-c path] 11362 11363server [-c path] 11364@item 11365Requires: repository, client conversation on stdin/stdout 11366@item 11367Changes: Repository or, indirectly, client working directory. 11368@end itemize 11369 11370The @sc{cvs} @code{server} and @code{pserver} commands are used to provide 11371repository access to remote clients and expect a client conversation on 11372stdin & stdout. Typically these commands are launched from @code{inetd} or 11373via @code{ssh} (@pxref{Remote repositories}). 11374 11375@code{server} expects that the client has already been authenticated somehow, 11376typically via @sc{ssh}, and @code{pserver} attempts to authenticate the client 11377itself. 11378 11379Only one option is available with the @code{server} and @code{pserver} 11380commands: 11381 11382@cindex configuration file 11383@table @code 11384@item -c path 11385Load configuration from @var{path} rather than the default location 11386@file{$CVSROOT/CVSROOT/config} (@pxref{config}). @var{path} must be 11387@file{/etc/cvs.conf} or prefixed by @file{/etc/cvs/}. This option is 11388supported beginning with @sc{cvs} release 1.12.13. 11389@end table 11390 11391@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11392@node update 11393@appendixsec update---Bring work tree in sync with repository 11394@cindex update (subcommand) 11395 11396@itemize @bullet 11397@item 11398update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag[:date] | -D date] [-W spec] files@dots{} 11399@item 11400Requires: repository, working directory. 11401@item 11402Changes: working directory. 11403@end itemize 11404 11405After you've run checkout to create your private copy 11406of source from the common repository, other developers 11407will continue changing the central source. From time 11408to time, when it is convenient in your development 11409process, you can use the @code{update} command from 11410within your working directory to reconcile your work 11411with any revisions applied to the source repository 11412since your last checkout or update. Without the @code{-C} 11413option, @code{update} will also merge any differences 11414between the local copy of files and their base revisions 11415into any destination revisions specified with @code{-r}, 11416@code{-D}, or @code{-A}. 11417 11418@menu 11419* update options:: update options 11420* update output:: update output 11421@end menu 11422 11423@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11424@node update options 11425@appendixsubsec update options 11426 11427These standard options are available with @code{update} 11428(@pxref{Common options}, for a complete description of 11429them): 11430 11431@table @code 11432@item -D date 11433Use the most recent revision no later than @var{date}. 11434This option is sticky, and implies @samp{-P}. 11435See @ref{Sticky tags}, for more information on sticky tags/dates. 11436 11437@item -f 11438Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision 11439is found, retrieve the most recent revision (instead of ignoring the file). 11440 11441@item -k @var{kflag} 11442Process keywords according to @var{kflag}. See 11443@ref{Keyword substitution}. 11444This option is sticky; future updates of 11445this file in this working directory will use the same 11446@var{kflag}. The @code{status} command can be viewed 11447to see the sticky options. See @ref{Invoking CVS}, for 11448more information on the @code{status} command. 11449 11450@item -l 11451Local; run only in current working directory. @xref{Recursive behavior}. 11452 11453@item -P 11454Prune empty directories. See @ref{Moving directories}. 11455 11456@item -p 11457Pipe files to the standard output. 11458 11459@item -R 11460Update directories recursively (default). @xref{Recursive 11461behavior}. 11462 11463@item -r @var{tag}[:@var{date}] 11464Retrieve the revisions specified by @var{tag} or, when @var{date} is specified 11465and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11466existed on @var{date}. This option is sticky, and implies @samp{-P}. 11467See @ref{Sticky tags}, for more information on sticky tags/dates. Also 11468see @ref{Common options}. 11469@end table 11470 11471@need 800 11472These special options are also available with 11473@code{update}. 11474 11475@table @code 11476@item -A 11477Reset any sticky tags, dates, or @samp{-k} options. 11478See @ref{Sticky tags}, for more information on sticky tags/dates. 11479 11480@item -C 11481Overwrite locally modified files with clean copies from 11482the repository (the modified file is saved in 11483@file{.#@var{file}.@var{revision}}, however). 11484 11485@item -d 11486Create any directories that exist in the repository if 11487they're missing from the working directory. Normally, 11488@code{update} acts only on directories and files that 11489were already enrolled in your working directory. 11490 11491This is useful for updating directories that were 11492created in the repository since the initial checkout; 11493but it has an unfortunate side effect. If you 11494deliberately avoided certain directories in the 11495repository when you created your working directory 11496(either through use of a module name or by listing 11497explicitly the files and directories you wanted on the 11498command line), then updating with @samp{-d} will create 11499those directories, which may not be what you want. 11500 11501@item -I @var{name} 11502Ignore files whose names match @var{name} (in your 11503working directory) during the update. You can specify 11504@samp{-I} more than once on the command line to specify 11505several files to ignore. Use @samp{-I !} to avoid 11506ignoring any files at all. @xref{cvsignore}, for other 11507ways to make @sc{cvs} ignore some files. 11508 11509@item -W@var{spec} 11510Specify file names that should be filtered during 11511update. You can use this option repeatedly. 11512 11513@var{spec} can be a file name pattern of the same type 11514that you can specify in the @file{.cvswrappers} 11515file. @xref{Wrappers}. 11516 11517@item -j@var{revision} 11518With two @samp{-j} options, merge changes from the 11519revision specified with the first @samp{-j} option to 11520the revision specified with the second @samp{j} option, 11521into the working directory. 11522 11523With one @samp{-j} option, merge changes from the 11524ancestor revision to the revision specified with the 11525@samp{-j} option, into the working directory. The 11526ancestor revision is the common ancestor of the 11527revision which the working directory is based on, and 11528the revision specified in the @samp{-j} option. 11529 11530Note that using a single @samp{-j @var{tagname}} option rather than 11531@samp{-j @var{branchname}} to merge changes from a branch will 11532often not remove files which were removed on the branch. 11533@xref{Merging adds and removals}, for more. 11534 11535In addition, each @samp{-j} option can contain an optional 11536date specification which, when used with branches, can 11537limit the chosen revision to one within a specific 11538date. An optional date is specified by adding a colon 11539(:) to the tag: 11540@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 11541 11542@xref{Branching and merging}. 11543 11544@end table 11545 11546@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11547@node update output 11548@appendixsubsec update output 11549 11550@code{update} and @code{checkout} keep you informed of 11551their progress by printing a line for each file, preceded 11552by one character indicating the status of the file: 11553 11554@table @code 11555@item U @var{file} 11556The file was brought up to date with respect to the 11557repository. This is done for any file that exists in 11558the repository but not in your working directory, and for files 11559that you haven't changed but are not the most recent 11560versions available in the repository. 11561 11562@item P @var{file} 11563Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 11564file. This accomplishes the same thing as @samp{U} using less bandwidth. 11565 11566@item A @var{file} 11567The file has been added to your private copy of the 11568sources, and will be added to the source repository 11569when you run @code{commit} on the file. This is a 11570reminder to you that the file needs to be committed. 11571 11572@item R @var{file} 11573The file has been removed from your private copy of the 11574sources, and will be removed from the source repository 11575when you run @code{commit} on the file. This is a 11576reminder to you that the file needs to be committed. 11577 11578@item M @var{file} 11579The file is modified in your working directory. 11580 11581@samp{M} can indicate one of two states for a file 11582you're working on: either there were no modifications 11583to the same file in the repository, so that your file 11584remains as you last saw it; or there were modifications 11585in the repository as well as in your copy, but they 11586were merged successfully, without conflict, in your 11587working directory. 11588 11589@sc{cvs} will print some messages if it merges your work, 11590and a backup copy of your working file (as it looked 11591before you ran @code{update}) will be made. The exact 11592name of that file is printed while @code{update} runs. 11593 11594@item C @var{file} 11595@cindex .# files 11596@cindex __ files (VMS) 11597A conflict was detected while trying to merge your 11598changes to @var{file} with changes from the source 11599repository. @var{file} (the copy in your working 11600directory) is now the result of attempting to merge 11601the two revisions; an unmodified copy of your file 11602is also in your working directory, with the name 11603@file{.#@var{file}.@var{revision}} where @var{revision} 11604is the revision that your modified file started 11605from. Resolve the conflict as described in 11606@ref{Conflicts example}. 11607@c "some systems" as in out-of-the-box OSes? Not as 11608@c far as I know. We need to advise sysadmins as well 11609@c as users how to set up this kind of purge, if that is 11610@c what they want. 11611@c We also might want to think about cleaner solutions, 11612@c like having CVS remove the .# file once the conflict 11613@c has been resolved or something like that. 11614(Note that some systems automatically purge 11615files that begin with @file{.#} if they have not been 11616accessed for a few days. If you intend to keep a copy 11617of your original file, it is a very good idea to rename 11618it.) Under @sc{vms}, the file name starts with 11619@file{__} rather than @file{.#}. 11620 11621@item ? @var{file} 11622@var{file} is in your working directory, but does not 11623correspond to anything in the source repository, and is 11624not in the list of files for @sc{cvs} to ignore (see the 11625description of the @samp{-I} option, and 11626@pxref{cvsignore}). 11627@end table 11628 11629@c ----- END MAN 1 ----- 11630@c --------------------------------------------------------------------- 11631@node Invoking CVS 11632@appendix Quick reference to CVS commands 11633@cindex Command reference 11634@cindex Reference, commands 11635@cindex Invoking CVS 11636 11637This appendix describes how to invoke @sc{cvs}, with 11638references to where each command or feature is 11639described in detail. For other references run the 11640@code{cvs --help} command, or see @ref{Index}. 11641 11642A @sc{cvs} command looks like: 11643 11644@example 11645cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 11646@end example 11647 11648Global options: 11649 11650@table @code 11651@item --allow-root=@var{rootdir} 11652Specify legal @sc{cvsroot} directory (server only) (not 11653in @sc{cvs} 1.9 and older). See @ref{Password 11654authentication server}. 11655 11656@item -a 11657Authenticate all communication (client only) (not in @sc{cvs} 116581.9 and older). See @ref{Global options}. 11659 11660@item -b 11661Specify RCS location (@sc{cvs} 1.9 and older). See 11662@ref{Global options}. 11663 11664@item -d @var{root} 11665Specify the @sc{cvsroot}. See @ref{Repository}. 11666 11667@item -e @var{editor} 11668Edit messages with @var{editor}. See @ref{Committing 11669your changes}. 11670 11671@item -f 11672Do not read the @file{~/.cvsrc} file. See @ref{Global 11673options}. 11674 11675@item -H 11676@itemx --help 11677Print a help message. See @ref{Global options}. 11678 11679@item -n 11680Do not change any files. See @ref{Global options}. 11681 11682@item -Q 11683Be really quiet. See @ref{Global options}. 11684 11685@item -q 11686Be somewhat quiet. See @ref{Global options}. 11687 11688@item -r 11689Make new working files read-only. See @ref{Global options}. 11690 11691@item -s @var{variable}=@var{value} 11692Set a user variable. See @ref{Variables}. 11693 11694@item -T @var{tempdir} 11695Put temporary files in @var{tempdir}. See @ref{Global 11696options}. 11697 11698@item -t 11699Trace @sc{cvs} execution. See @ref{Global options}. 11700 11701@item -v 11702@item --version 11703Display version and copyright information for @sc{cvs}. 11704 11705@item -w 11706Make new working files read-write. See @ref{Global 11707options}. 11708 11709@item -x 11710Encrypt all communication (client only). 11711See @ref{Global options}. 11712 11713@item -z @var{gzip-level} 11714@cindex Compression 11715@cindex Gzip 11716Set the compression level (client only). 11717See @ref{Global options}. 11718@end table 11719 11720Keyword expansion modes (@pxref{Substitution modes}): 11721 11722@example 11723-kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 11724-kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11725-kk $@splitrcskeyword{Id}$ 11726-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 11727-ko @i{no expansion} 11728-kb @i{no expansion, file is binary} 11729@end example 11730 11731Keywords (@pxref{Keyword list}): 11732 11733@example 11734$@splitrcskeyword{Author}: joe $ 11735$@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ 11736$@splitrcskeyword{CVSHeader}: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11737$@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11738$@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11739$@splitrcskeyword{Locker}: harry $ 11740$@splitrcskeyword{Name}: snapshot_1_14 $ 11741$@splitrcskeyword{RCSfile}: file1,v $ 11742$@splitrcskeyword{Revision}: 1.1 $ 11743$@splitrcskeyword{Source}: /home/files/file1,v $ 11744$@splitrcskeyword{State}: Exp $ 11745$@splitrcskeyword{Log}: file1,v $ 11746Revision 1.1 1993/12/09 03:30:17 joe 11747Initial revision 11748 11749@end example 11750 11751@c The idea behind this table is that we want each item 11752@c to be a sentence or two at most. Preferably a 11753@c single line. 11754@c 11755@c In some cases refs to "foo options" are just to get 11756@c this thing written quickly, not because the "foo 11757@c options" node is really the best place to point. 11758Commands, command options, and command arguments: 11759 11760@table @code 11761@c ------------------------------------------------------------ 11762@item add [@var{options}] [@var{files}@dots{}] 11763Add a new file/directory. See @ref{Adding files}. 11764 11765@table @code 11766@item -k @var{kflag} 11767Set keyword expansion. 11768 11769@item -m @var{msg} 11770Set file description. 11771@end table 11772 11773@c ------------------------------------------------------------ 11774@item admin [@var{options}] [@var{files}@dots{}] 11775Administration of history files in the repository. See 11776@ref{admin}. 11777@c This list omits those options which are not 11778@c documented as being useful with CVS. That might be 11779@c a mistake... 11780 11781@table @code 11782@item -b[@var{rev}] 11783Set default branch. See @ref{Reverting local changes}. 11784 11785@item -c@var{string} 11786Set comment leader. 11787 11788@item -k@var{subst} 11789Set keyword substitution. See @ref{Keyword 11790substitution}. 11791 11792@item -l[@var{rev}] 11793Lock revision @var{rev}, or latest revision. 11794 11795@item -m@var{rev}:@var{msg} 11796Replace the log message of revision @var{rev} with 11797@var{msg}. 11798 11799@item -o@var{range} 11800Delete revisions from the repository. See 11801@ref{admin options}. 11802 11803@item -q 11804Run quietly; do not print diagnostics. 11805 11806@item -s@var{state}[:@var{rev}] 11807Set the state. See @ref{admin options} for more information on possible 11808states. 11809 11810@c Does not work for client/server CVS 11811@item -t 11812Set file description from standard input. 11813 11814@item -t@var{file} 11815Set file description from @var{file}. 11816 11817@item -t-@var{string} 11818Set file description to @var{string}. 11819 11820@item -u[@var{rev}] 11821Unlock revision @var{rev}, or latest revision. 11822@end table 11823 11824@c ------------------------------------------------------------ 11825@item annotate [@var{options}] [@var{files}@dots{}] 11826Show last revision where each line was modified. See 11827@ref{annotate}. 11828 11829@table @code 11830@item -D @var{date} 11831Annotate the most recent revision no later than 11832@var{date}. See @ref{Common options}. 11833 11834@item -F 11835Force annotation of binary files. (Without this option, 11836binary files are skipped with a message.) 11837 11838@item -f 11839Use head revision if tag/date not found. See 11840@ref{Common options}. 11841 11842@item -l 11843Local; run only in current working directory. @xref{Recursive behavior}. 11844 11845@item -R 11846Operate recursively (default). @xref{Recursive 11847behavior}. 11848 11849@item -r @var{tag}[:@var{date}] 11850Annotate revisions specified by @var{tag} or, when @var{date} is specified 11851and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11852existed on @var{date}. See @ref{Common options}. 11853@end table 11854 11855@c ------------------------------------------------------------ 11856@item checkout [@var{options}] @var{modules}@dots{} 11857Get a copy of the sources. See @ref{checkout}. 11858 11859@table @code 11860@item -A 11861Reset any sticky tags/date/options. See @ref{Sticky 11862tags} and @ref{Keyword substitution}. 11863 11864@item -c 11865Output the module database. See @ref{checkout options}. 11866 11867@item -D @var{date} 11868Check out revisions as of @var{date} (is sticky). See 11869@ref{Common options}. 11870 11871@item -d @var{dir} 11872Check out into @var{dir}. See @ref{checkout options}. 11873 11874@item -f 11875Use head revision if tag/date not found. See 11876@ref{Common options}. 11877 11878@c Probably want to use rev1/rev2 style like for diff 11879@c -r. Here and in on-line help. 11880@item -j @var{tag}[:@var{date}] 11881Merge in the change specified by @var{tag}, or when @var{date} is specified 11882and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11883existed on @var{date}. See @ref{checkout options}. 11884 11885@item -k @var{kflag} 11886Use @var{kflag} keyword expansion. See 11887@ref{Substitution modes}. 11888 11889@item -l 11890Local; run only in current working directory. @xref{Recursive behavior}. 11891 11892@item -N 11893Don't ``shorten'' module paths if -d specified. See 11894@ref{checkout options}. 11895 11896@item -n 11897Do not run module program (if any). See @ref{checkout options}. 11898 11899@item -P 11900Prune empty directories. See @ref{Moving directories}. 11901 11902@item -p 11903Check out files to standard output (avoids 11904stickiness). See @ref{checkout options}. 11905 11906@item -R 11907Operate recursively (default). @xref{Recursive 11908behavior}. 11909 11910@item -r @var{tag}[:@var{date}] 11911Checkout the revision already tagged with @var{tag} or, when @var{date} is 11912specified and @var{tag} is a branch tag, the version from the branch @var{tag} 11913as it existed on @var{date}. This . See @ref{Common options}. 11914 11915@item -s 11916Like -c, but include module status. See @ref{checkout options}. 11917@end table 11918 11919@c ------------------------------------------------------------ 11920@item commit [@var{options}] [@var{files}@dots{}] 11921Check changes into the repository. See @ref{commit}. 11922 11923@table @code 11924@item -c 11925Check for valid edits before committing. Requires a @sc{cvs} client and server 11926both version 1.12.10 or greater. 11927 11928@item -F @var{file} 11929Read log message from @var{file}. See @ref{commit options}. 11930 11931@item -f 11932@c What is this "disables recursion"? It is from the 11933@c on-line help; is it documented in this manual? 11934Force the file to be committed; disables recursion. 11935See @ref{commit options}. 11936 11937@item -l 11938Local; run only in current working directory. See @ref{Recursive behavior}. 11939 11940@item -m @var{msg} 11941Use @var{msg} as log message. See @ref{commit options}. 11942 11943@item -n 11944Do not run module program (if any). See @ref{commit options}. 11945 11946@item -R 11947Operate recursively (default). @xref{Recursive 11948behavior}. 11949 11950@item -r @var{rev} 11951Commit to @var{rev}. See @ref{commit options}. 11952@c FIXME: should be dragging over text from 11953@c commit options, especially if it can be cleaned up 11954@c and made concise enough. 11955@end table 11956 11957@c ------------------------------------------------------------ 11958@item diff [@var{options}] [@var{files}@dots{}] 11959Show differences between revisions. See @ref{diff}. 11960In addition to the options shown below, accepts a wide 11961variety of options to control output style, for example 11962@samp{-c} for context diffs. 11963 11964@table @code 11965@item -D @var{date1} 11966Diff revision for date against working file. See 11967@ref{diff options}. 11968 11969@item -D @var{date2} 11970Diff @var{rev1}/@var{date1} against @var{date2}. See 11971@ref{diff options}. 11972 11973@item -l 11974Local; run only in current working directory. See @ref{Recursive behavior}. 11975 11976@item -N 11977Include diffs for added and removed files. See 11978@ref{diff options}. 11979 11980@item -R 11981Operate recursively (default). @xref{Recursive 11982behavior}. 11983 11984@item -r @var{tag1}[:@var{date1}] 11985Diff the revisions specified by @var{tag1} or, when @var{date1} is specified 11986and @var{tag1} is a branch tag, the version from the branch @var{tag1} as it 11987existed on @var{date1}, against the working file. See @ref{diff options} 11988and @ref{Common options}. 11989 11990@item -r @var{tag2}[:@var{date2}] 11991Diff the revisions specified by @var{tag2} or, when @var{date2} is specified 11992and @var{tag2} is a branch tag, the version from the branch @var{tag2} as it 11993existed on @var{date2}, against @var{rev1}/@var{date1}. See @ref{diff options} 11994and @ref{Common options}. 11995@end table 11996 11997@c ------------------------------------------------------------ 11998@item edit [@var{options}] [@var{files}@dots{}] 11999Get ready to edit a watched file. See @ref{Editing files}. 12000 12001@table @code 12002@item -a @var{actions} 12003Specify actions for temporary watch, where 12004@var{actions} is @code{edit}, @code{unedit}, 12005@code{commit}, @code{all}, or @code{none}. See 12006@ref{Editing files}. 12007 12008@item -c 12009Check edits: Edit fails if someone else is already editting the file. 12010Requires a @sc{cvs} client and server both of version 1.12.10 or greater. 12011 12012@item -f 12013Force edit; ignore other edits. Added in CVS 1.12.10. 12014 12015@item -l 12016Local; run only in current working directory. See @ref{Recursive behavior}. 12017 12018@item -R 12019Operate recursively (default). @xref{Recursive 12020behavior}. 12021@end table 12022 12023@c ------------------------------------------------------------ 12024@item editors [@var{options}] [@var{files}@dots{}] 12025See who is editing a watched file. See @ref{Watch information}. 12026 12027@table @code 12028@item -l 12029Local; run only in current working directory. See @ref{Recursive behavior}. 12030 12031@item -R 12032Operate recursively (default). @xref{Recursive 12033behavior}. 12034@end table 12035 12036@c ------------------------------------------------------------ 12037@item export [@var{options}] @var{modules}@dots{} 12038Export files from @sc{cvs}. See @ref{export}. 12039 12040@table @code 12041@item -D @var{date} 12042Check out revisions as of @var{date}. See 12043@ref{Common options}. 12044 12045@item -d @var{dir} 12046Check out into @var{dir}. See @ref{export options}. 12047 12048@item -f 12049Use head revision if tag/date not found. See 12050@ref{Common options}. 12051 12052@item -k @var{kflag} 12053Use @var{kflag} keyword expansion. See 12054@ref{Substitution modes}. 12055 12056@item -l 12057Local; run only in current working directory. @xref{Recursive behavior}. 12058 12059@item -N 12060Don't ``shorten'' module paths if -d specified. See 12061@ref{export options}. 12062 12063@item -n 12064Do not run module program (if any). See @ref{export options}. 12065 12066@item -R 12067Operate recursively (default). @xref{Recursive 12068behavior}. 12069 12070@item -r @var{tag}[:@var{date}] 12071Export the revisions specified by @var{tag} or, when @var{date} is specified 12072and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12073existed on @var{date}. See @ref{Common options}. 12074@end table 12075 12076@c ------------------------------------------------------------ 12077@item history [@var{options}] [@var{files}@dots{}] 12078Show repository access history. See @ref{history}. 12079 12080@table @code 12081@item -a 12082All users (default is self). See @ref{history options}. 12083 12084@item -b @var{str} 12085Back to record with @var{str} in module/file/repos 12086field. See @ref{history options}. 12087 12088@item -c 12089Report on committed (modified) files. See @ref{history options}. 12090 12091@item -D @var{date} 12092Since @var{date}. See @ref{history options}. 12093 12094@item -e 12095Report on all record types. See @ref{history options}. 12096 12097@item -l 12098Last modified (committed or modified report). See @ref{history options}. 12099 12100@item -m @var{module} 12101Report on @var{module} (repeatable). See @ref{history options}. 12102 12103@item -n @var{module} 12104In @var{module}. See @ref{history options}. 12105 12106@item -o 12107Report on checked out modules. See @ref{history options}. 12108 12109@item -p @var{repository} 12110In @var{repository}. See @ref{history options}. 12111 12112@item -r @var{rev} 12113Since revision @var{rev}. See @ref{history options}. 12114 12115@item -T 12116@c What the @#$@# is a TAG? Same as a tag? This 12117@c wording is also in the online-line help. 12118Produce report on all TAGs. See @ref{history options}. 12119 12120@item -t @var{tag} 12121Since tag record placed in history file (by anyone). 12122See @ref{history options}. 12123 12124@item -u @var{user} 12125For user @var{user} (repeatable). See @ref{history options}. 12126 12127@item -w 12128Working directory must match. See @ref{history options}. 12129 12130@item -x @var{types} 12131Report on @var{types}, one or more of 12132@code{TOEFWUPCGMAR}. See @ref{history options}. 12133 12134@item -z @var{zone} 12135Output for time zone @var{zone}. See @ref{history options}. 12136@end table 12137 12138@c ------------------------------------------------------------ 12139@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 12140Import files into @sc{cvs}, using vendor branches. See 12141@ref{import}. 12142 12143@table @code 12144@item -b @var{bra} 12145Import to vendor branch @var{bra}. See 12146@ref{Multiple vendor branches}. 12147 12148@item -d 12149Use the file's modification time as the time of 12150import. See @ref{import options}. 12151 12152@item -k @var{kflag} 12153Set default keyword substitution mode. See 12154@ref{import options}. 12155 12156@item -m @var{msg} 12157Use @var{msg} for log message. See 12158@ref{import options}. 12159 12160@item -I @var{ign} 12161More files to ignore (! to reset). See 12162@ref{import options}. 12163 12164@item -W @var{spec} 12165More wrappers. See @ref{import options}. 12166@end table 12167 12168@c ------------------------------------------------------------ 12169@item init 12170Create a @sc{cvs} repository if it doesn't exist. See 12171@ref{Creating a repository}. 12172 12173@c ------------------------------------------------------------ 12174@item kserver 12175Kerberos authenticated server. 12176See @ref{Kerberos authenticated}. 12177 12178@c ------------------------------------------------------------ 12179@item log [@var{options}] [@var{files}@dots{}] 12180Print out history information for files. See @ref{log}. 12181 12182@table @code 12183@item -b 12184Only list revisions on the default branch. See @ref{log options}. 12185 12186@item -d @var{dates} 12187Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12188latest before). See @ref{log options}. 12189 12190@item -h 12191Only print header. See @ref{log options}. 12192 12193@item -l 12194Local; run only in current working directory. See @ref{Recursive behavior}. 12195 12196@item -N 12197Do not list tags. See @ref{log options}. 12198 12199@item -R 12200Only print name of RCS file. See @ref{log options}. 12201 12202@item -r@var{revs} 12203Only list revisions @var{revs}. See @ref{log options}. 12204 12205@item -s @var{states} 12206Only list revisions with specified states. See @ref{log options}. 12207 12208@item -t 12209Only print header and descriptive text. See @ref{log 12210options}. 12211 12212@item -w@var{logins} 12213Only list revisions checked in by specified logins. See @ref{log options}. 12214@end table 12215 12216@c ------------------------------------------------------------ 12217@item login 12218Prompt for password for authenticating server. See 12219@ref{Password authentication client}. 12220 12221@c ------------------------------------------------------------ 12222@item logout 12223Remove stored password for authenticating server. See 12224@ref{Password authentication client}. 12225 12226@c ------------------------------------------------------------ 12227@item pserver 12228Password authenticated server. 12229See @ref{Password authentication server}. 12230 12231@c ------------------------------------------------------------ 12232@item rannotate [@var{options}] [@var{modules}@dots{}] 12233Show last revision where each line was modified. See 12234@ref{annotate}. 12235 12236@table @code 12237@item -D @var{date} 12238Annotate the most recent revision no later than 12239@var{date}. See @ref{Common options}. 12240 12241@item -F 12242Force annotation of binary files. (Without this option, 12243binary files are skipped with a message.) 12244 12245@item -f 12246Use head revision if tag/date not found. See 12247@ref{Common options}. 12248 12249@item -l 12250Local; run only in current working directory. @xref{Recursive behavior}. 12251 12252@item -R 12253Operate recursively (default). @xref{Recursive behavior}. 12254 12255@item -r @var{tag}[:@var{date}] 12256Annotate the revision specified by @var{tag} or, when @var{date} is specified 12257and @var{tag} is a branch tag, the version from the branch @var{tag} 12258as it existed on @var{date}. See @ref{Common options}. 12259@end table 12260 12261@c ------------------------------------------------------------ 12262@item rdiff [@var{options}] @var{modules}@dots{} 12263Show differences between releases. See @ref{rdiff}. 12264 12265@table @code 12266@item -c 12267Context diff output format (default). See @ref{rdiff options}. 12268 12269@item -D @var{date} 12270Select revisions based on @var{date}. See @ref{Common options}. 12271 12272@item -f 12273Use head revision if tag/date not found. See 12274@ref{Common options}. 12275 12276@item -l 12277Local; run only in current working directory. See @ref{Recursive behavior}. 12278 12279@item -R 12280Operate recursively (default). @xref{Recursive 12281behavior}. 12282 12283@item -r @var{tag}[:@var{date}] 12284Select the revisions specified by @var{tag} or, when @var{date} is specified 12285and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12286existed on @var{date}. See @ref{diff options} and @ref{Common options}. 12287 12288@item -s 12289Short patch - one liner per file. See @ref{rdiff options}. 12290 12291@item -t 12292Top two diffs - last change made to the file. See 12293@ref{diff options}. 12294 12295@item -u 12296Unidiff output format. See @ref{rdiff options}. 12297 12298@item -V @var{vers} 12299Use RCS Version @var{vers} for keyword expansion (obsolete). See 12300@ref{rdiff options}. 12301@end table 12302 12303@c ------------------------------------------------------------ 12304@item release [@var{options}] @var{directory} 12305Indicate that a directory is no longer in use. See 12306@ref{release}. 12307 12308@table @code 12309@item -d 12310Delete the given directory. See @ref{release options}. 12311@end table 12312 12313@c ------------------------------------------------------------ 12314@item remove [@var{options}] [@var{files}@dots{}] 12315Remove an entry from the repository. See @ref{Removing files}. 12316 12317@table @code 12318@item -f 12319Delete the file before removing it. See @ref{Removing files}. 12320 12321@item -l 12322Local; run only in current working directory. See @ref{Recursive behavior}. 12323 12324@item -R 12325Operate recursively (default). @xref{Recursive 12326behavior}. 12327@end table 12328 12329@c ------------------------------------------------------------ 12330@item rlog [@var{options}] [@var{files}@dots{}] 12331Print out history information for modules. See @ref{log}. 12332 12333@table @code 12334@item -b 12335Only list revisions on the default branch. See @ref{log options}. 12336 12337@item -d @var{dates} 12338Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12339latest before). See @ref{log options}. 12340 12341@item -h 12342Only print header. See @ref{log options}. 12343 12344@item -l 12345Local; run only in current working directory. See @ref{Recursive behavior}. 12346 12347@item -N 12348Do not list tags. See @ref{log options}. 12349 12350@item -R 12351Only print name of RCS file. See @ref{log options}. 12352 12353@item -r@var{revs} 12354Only list revisions @var{revs}. See @ref{log options}. 12355 12356@item -s @var{states} 12357Only list revisions with specified states. See @ref{log options}. 12358 12359@item -t 12360Only print header and descriptive text. See @ref{log options}. 12361 12362@item -w@var{logins} 12363Only list revisions checked in by specified logins. See @ref{log options}. 12364@end table 12365 12366@c ------------------------------------------------------------ 12367@item rtag [@var{options}] @var{tag} @var{modules}@dots{} 12368Add a symbolic tag to a module. 12369See @ref{Revisions} and @ref{Branching and merging}. 12370 12371@table @code 12372@item -a 12373Clear tag from removed files that would not otherwise 12374be tagged. See @ref{Tagging add/remove}. 12375 12376@item -b 12377Create a branch named @var{tag}. See @ref{Branching and merging}. 12378 12379@item -B 12380Used in conjunction with -F or -d, enables movement and deletion of 12381branch tags. Use with extreme caution. 12382 12383@item -D @var{date} 12384Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12385 12386@item -d 12387Delete @var{tag}. See @ref{Modifying tags}. 12388 12389@item -F 12390Move @var{tag} if it already exists. See @ref{Modifying tags}. 12391 12392@item -f 12393Force a head revision match if tag/date not found. 12394See @ref{Tagging by date/tag}. 12395 12396@item -l 12397Local; run only in current working directory. See @ref{Recursive behavior}. 12398 12399@item -n 12400No execution of tag program. See @ref{Common options}. 12401 12402@item -R 12403Operate recursively (default). @xref{Recursive 12404behavior}. 12405 12406@item -r @var{tag}[:@var{date}] 12407Tag the revision already tagged with @var{tag} or, when @var{date} is specified 12408and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12409existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12410@end table 12411 12412@c ------------------------------------------------------------ 12413@item server 12414Rsh server. See @ref{Connecting via rsh}. 12415 12416@c ------------------------------------------------------------ 12417@item status [@var{options}] @var{files}@dots{} 12418Display status information in a working directory. See 12419@ref{File status}. 12420 12421@table @code 12422@item -l 12423Local; run only in current working directory. See @ref{Recursive behavior}. 12424 12425@item -R 12426Operate recursively (default). @xref{Recursive behavior}. 12427 12428@item -v 12429Include tag information for file. See @ref{Tags}. 12430@end table 12431 12432@c ------------------------------------------------------------ 12433@item tag [@var{options}] @var{tag} [@var{files}@dots{}] 12434Add a symbolic tag to checked out version of files. 12435See @ref{Revisions} and @ref{Branching and merging}. 12436 12437@table @code 12438@item -b 12439Create a branch named @var{tag}. See @ref{Branching and merging}. 12440 12441@item -c 12442Check that working files are unmodified. See 12443@ref{Tagging the working directory}. 12444 12445@item -D @var{date} 12446Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12447 12448@item -d 12449Delete @var{tag}. See @ref{Modifying tags}. 12450 12451@item -F 12452Move @var{tag} if it already exists. See @ref{Modifying tags}. 12453 12454@item -f 12455Force a head revision match if tag/date not found. 12456See @ref{Tagging by date/tag}. 12457 12458@item -l 12459Local; run only in current working directory. See @ref{Recursive behavior}. 12460 12461@item -R 12462Operate recursively (default). @xref{Recursive behavior}. 12463 12464@item -r @var{tag}[:@var{date}] 12465Tag the revision already tagged with @var{tag}, or when @var{date} is specified 12466and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12467existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12468@end table 12469 12470@c ------------------------------------------------------------ 12471@item unedit [@var{options}] [@var{files}@dots{}] 12472Undo an edit command. See @ref{Editing files}. 12473 12474@table @code 12475@item -l 12476Local; run only in current working directory. See @ref{Recursive behavior}. 12477 12478@item -R 12479Operate recursively (default). @xref{Recursive behavior}. 12480@end table 12481 12482@c ------------------------------------------------------------ 12483@item update [@var{options}] [@var{files}@dots{}] 12484Bring work tree in sync with repository. See 12485@ref{update}. 12486 12487@table @code 12488@item -A 12489Reset any sticky tags/date/options. See @ref{Sticky 12490tags} and @ref{Keyword substitution}. 12491 12492@item -C 12493Overwrite locally modified files with clean copies from 12494the repository (the modified file is saved in 12495@file{.#@var{file}.@var{revision}}, however). 12496 12497@item -D @var{date} 12498Check out revisions as of @var{date} (is sticky). See 12499@ref{Common options}. 12500 12501@item -d 12502Create directories. See @ref{update options}. 12503 12504@item -f 12505Use head revision if tag/date not found. See 12506@ref{Common options}. 12507 12508@item -I @var{ign} 12509More files to ignore (! to reset). See 12510@ref{import options}. 12511 12512@c Probably want to use rev1/rev2 style like for diff 12513@c -r. Here and in on-line help. 12514@item -j @var{tag}[:@var{date}] 12515Merge in changes from revisions specified by @var{tag} or, when @var{date} is 12516specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12517as it existed on @var{date}. See @ref{update options}. 12518 12519@item -k @var{kflag} 12520Use @var{kflag} keyword expansion. See 12521@ref{Substitution modes}. 12522 12523@item -l 12524Local; run only in current working directory. @xref{Recursive behavior}. 12525 12526@item -P 12527Prune empty directories. See @ref{Moving directories}. 12528 12529@item -p 12530Check out files to standard output (avoids 12531stickiness). See @ref{update options}. 12532 12533@item -R 12534Operate recursively (default). @xref{Recursive 12535behavior}. 12536 12537@item -r @var{tag}[:@var{date}] 12538Checkout the revisions specified by @var{tag} or, when @var{date} is specified 12539and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12540existed on @var{date}. See @ref{Common options}. 12541 12542@item -W @var{spec} 12543More wrappers. See @ref{import options}. 12544@end table 12545 12546@c ------------------------------------------------------------ 12547@item version 12548@cindex version (subcommand) 12549 12550Display the version of @sc{cvs} being used. If the repository 12551is remote, display both the client and server versions. 12552 12553@c ------------------------------------------------------------ 12554@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 12555 12556on/off: turn on/off read-only checkouts of files. See 12557@ref{Setting a watch}. 12558 12559add/remove: add or remove notification on actions. See 12560@ref{Getting Notified}. 12561 12562@table @code 12563@item -a @var{actions} 12564Specify actions for temporary watch, where 12565@var{actions} is @code{edit}, @code{unedit}, 12566@code{commit}, @code{all}, or @code{none}. See 12567@ref{Editing files}. 12568 12569@item -l 12570Local; run only in current working directory. See @ref{Recursive behavior}. 12571 12572@item -R 12573Operate recursively (default). @xref{Recursive 12574behavior}. 12575@end table 12576 12577@c ------------------------------------------------------------ 12578@item watchers [@var{options}] [@var{files}@dots{}] 12579See who is watching a file. See @ref{Watch information}. 12580 12581@table @code 12582@item -l 12583Local; run only in current working directory. See @ref{Recursive behavior}. 12584 12585@item -R 12586Operate recursively (default). @xref{Recursive 12587behavior}. 12588@end table 12589 12590@end table 12591 12592@c --------------------------------------------------------------------- 12593@node Administrative files 12594@appendix Reference manual for Administrative files 12595@cindex Administrative files (reference) 12596@cindex Files, reference manual 12597@cindex Reference manual (files) 12598@cindex CVSROOT (file) 12599 12600Inside the repository, in the directory 12601@file{$CVSROOT/CVSROOT}, there are a number of 12602supportive files for @sc{cvs}. You can use @sc{cvs} in a limited 12603fashion without any of them, but if they are set up 12604properly they can help make life easier. For a 12605discussion of how to edit them, see @ref{Intro 12606administrative files}. 12607 12608The most important of these files is the @file{modules} 12609file, which defines the modules inside the repository. 12610 12611@menu 12612* modules:: Defining modules 12613* Wrappers:: Specify binary-ness based on file name 12614* Trigger Scripts:: Launch scripts in response to server events 12615* rcsinfo:: Templates for the log messages 12616* cvsignore:: Ignoring files via cvsignore 12617* checkoutlist:: Adding your own administrative files 12618* history file:: History information 12619* Variables:: Various variables are expanded 12620* config:: Miscellaneous CVS configuration 12621@end menu 12622 12623@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12624@node modules 12625@appendixsec The modules file 12626@cindex Modules (admin file) 12627@cindex Defining modules (reference manual) 12628 12629The @file{modules} file records your definitions of 12630names for collections of source code. @sc{cvs} will 12631use these definitions if you use @sc{cvs} to update the 12632modules file (use normal commands like @code{add}, 12633@code{commit}, etc). 12634 12635The @file{modules} file may contain blank lines and 12636comments (lines beginning with @samp{#}) as well as 12637module definitions. Long lines can be continued on the 12638next line by specifying a backslash (@samp{\}) as the 12639last character on the line. 12640 12641There are three basic types of modules: alias modules, 12642regular modules, and ampersand modules. The difference 12643between them is the way that they map files in the 12644repository to files in the working directory. In all 12645of the following examples, the top-level repository 12646contains a directory called @file{first-dir}, which 12647contains two files, @file{file1} and @file{file2}, and a 12648directory @file{sdir}. @file{first-dir/sdir} contains 12649a file @file{sfile}. 12650 12651@c FIXME: should test all the examples in this section. 12652 12653@menu 12654* Alias modules:: The simplest kind of module 12655* Regular modules:: 12656* Ampersand modules:: 12657* Excluding directories:: Excluding directories from a module 12658* Module options:: Regular and ampersand modules can take options 12659* Module program options:: How the modules ``program options'' programs 12660 are run. 12661@end menu 12662 12663@node Alias modules 12664@appendixsubsec Alias modules 12665@cindex Alias modules 12666@cindex -a, in modules file 12667 12668Alias modules are the simplest kind of module: 12669 12670@table @code 12671@item @var{mname} -a @var{aliases}@dots{} 12672This represents the simplest way of defining a module 12673@var{mname}. The @samp{-a} flags the definition as a 12674simple alias: @sc{cvs} will treat any use of @var{mname} (as 12675a command argument) as if the list of names 12676@var{aliases} had been specified instead. 12677@var{aliases} may contain either other module names or 12678paths. When you use paths in aliases, @code{checkout} 12679creates all intermediate directories in the working 12680directory, just as if the path had been specified 12681explicitly in the @sc{cvs} arguments. 12682@end table 12683 12684For example, if the modules file contains: 12685 12686@example 12687amodule -a first-dir 12688@end example 12689 12690@noindent 12691then the following two commands are equivalent: 12692 12693@example 12694$ cvs co amodule 12695$ cvs co first-dir 12696@end example 12697 12698@noindent 12699and they each would provide output such as: 12700 12701@example 12702cvs checkout: Updating first-dir 12703U first-dir/file1 12704U first-dir/file2 12705cvs checkout: Updating first-dir/sdir 12706U first-dir/sdir/sfile 12707@end example 12708 12709@node Regular modules 12710@appendixsubsec Regular modules 12711@cindex Regular modules 12712 12713@table @code 12714@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 12715In the simplest case, this form of module definition 12716reduces to @samp{@var{mname} @var{dir}}. This defines 12717all the files in directory @var{dir} as module mname. 12718@var{dir} is a relative path (from @code{$CVSROOT}) to a 12719directory of source in the source repository. In this 12720case, on checkout, a single directory called 12721@var{mname} is created as a working directory; no 12722intermediate directory levels are used by default, even 12723if @var{dir} was a path involving several directory 12724levels. 12725@end table 12726 12727For example, if a module is defined by: 12728 12729@example 12730regmodule first-dir 12731@end example 12732 12733@noindent 12734then regmodule will contain the files from first-dir: 12735 12736@example 12737$ cvs co regmodule 12738cvs checkout: Updating regmodule 12739U regmodule/file1 12740U regmodule/file2 12741cvs checkout: Updating regmodule/sdir 12742U regmodule/sdir/sfile 12743$ 12744@end example 12745 12746By explicitly specifying files in the module definition 12747after @var{dir}, you can select particular files from 12748directory @var{dir}. Here is 12749an example: 12750 12751@example 12752regfiles first-dir/sdir sfile 12753@end example 12754 12755@noindent 12756With this definition, getting the regfiles module 12757will create a single working directory 12758@file{regfiles} containing the file listed, which 12759comes from a directory deeper 12760in the @sc{cvs} source repository: 12761 12762@example 12763$ cvs co regfiles 12764U regfiles/sfile 12765$ 12766@end example 12767 12768@node Ampersand modules 12769@appendixsubsec Ampersand modules 12770@cindex Ampersand modules 12771@cindex &, in modules file 12772 12773A module definition can refer to other modules by 12774including @samp{&@var{module}} in its definition. 12775@example 12776@var{mname} [ options ] @var{&module}@dots{} 12777@end example 12778 12779Then getting the module creates a subdirectory for each such 12780module, in the directory containing the module. For 12781example, if modules contains 12782 12783@example 12784ampermod &first-dir 12785@end example 12786 12787@noindent 12788then a checkout will create an @code{ampermod} directory 12789which contains a directory called @code{first-dir}, 12790which in turns contains all the directories and files 12791which live there. For example, the command 12792 12793@example 12794$ cvs co ampermod 12795@end example 12796 12797@noindent 12798will create the following files: 12799 12800@example 12801ampermod/first-dir/file1 12802ampermod/first-dir/file2 12803ampermod/first-dir/sdir/sfile 12804@end example 12805 12806There is one quirk/bug: the messages that @sc{cvs} 12807prints omit the @file{ampermod}, and thus do not 12808correctly display the location to which it is checking 12809out the files: 12810 12811@example 12812$ cvs co ampermod 12813cvs checkout: Updating first-dir 12814U first-dir/file1 12815U first-dir/file2 12816cvs checkout: Updating first-dir/sdir 12817U first-dir/sdir/sfile 12818$ 12819@end example 12820 12821Do not rely on this buggy behavior; it may get fixed in 12822a future release of @sc{cvs}. 12823 12824@c FIXCVS: What happens if regular and & modules are 12825@c combined, as in "ampermodule first-dir &second-dir"? 12826@c When I tried it, it seemed to just ignore the 12827@c "first-dir". I think perhaps it should be an error 12828@c (but this needs further investigation). 12829@c In addition to discussing what each one does, we 12830@c should put in a few words about why you would use one or 12831@c the other in various situations. 12832 12833@node Excluding directories 12834@appendixsubsec Excluding directories 12835@cindex Excluding directories, in modules file 12836@cindex !, in modules file 12837 12838An alias module may exclude particular directories from 12839other modules by using an exclamation mark (@samp{!}) 12840before the name of each directory to be excluded. 12841 12842For example, if the modules file contains: 12843 12844@example 12845exmodule -a !first-dir/sdir first-dir 12846@end example 12847 12848@noindent 12849then checking out the module @samp{exmodule} will check 12850out everything in @samp{first-dir} except any files in 12851the subdirectory @samp{first-dir/sdir}. 12852@c Note that the "!first-dir/sdir" sometimes must be listed 12853@c before "first-dir". That seems like a probable bug, in which 12854@c case perhaps it should be fixed (to allow either 12855@c order) rather than documented. See modules4 in testsuite. 12856 12857@node Module options 12858@appendixsubsec Module options 12859@cindex Options, in modules file 12860 12861Either regular modules or ampersand modules can contain 12862options, which supply additional information concerning 12863the module. 12864 12865@table @code 12866@cindex -d, in modules file 12867@item -d @var{name} 12868Name the working directory something other than the 12869module name. 12870@c FIXME: Needs a bunch of examples, analogous to the 12871@c examples for alias, regular, and ampersand modules 12872@c which show where the files go without -d. 12873 12874@cindex Export program 12875@cindex -e, in modules file 12876@item -e @var{prog} 12877Specify a program @var{prog} to run whenever files in a 12878module are exported. @var{prog} runs with a single 12879argument, the module name. 12880@c FIXME: Is it run on server? client? 12881 12882@cindex Checkout program 12883@cindex -o, in modules file 12884@item -o @var{prog} 12885Specify a program @var{prog} to run whenever files in a 12886module are checked out. @var{prog} runs with a single 12887argument, the module name. See @ref{Module program options} for 12888information on how @var{prog} is called. 12889@c FIXME: Is it run on server? client? 12890 12891@cindex Status of a module 12892@cindex Module status 12893@cindex -s, in modules file 12894@item -s @var{status} 12895Assign a status to the module. When the module file is 12896printed with @samp{cvs checkout -s} the modules are 12897sorted according to primarily module status, and 12898secondarily according to the module name. This option 12899has no other meaning. You can use this option for 12900several things besides status: for instance, list the 12901person that is responsible for this module. 12902 12903@cindex Tag program 12904@cindex -t, in modules file 12905@item -t @var{prog} 12906Specify a program @var{prog} to run whenever files in a 12907module are tagged with @code{rtag}. @var{prog} runs 12908with two arguments: the module name and the symbolic 12909tag specified to @code{rtag}. It is not run 12910when @code{tag} is executed. Generally you will find 12911that the @file{taginfo} file is a better solution (@pxref{taginfo}). 12912@c FIXME: Is it run on server? client? 12913@c Problems with -t include: 12914@c * It is run after the tag not before 12915@c * It doesn't get passed all the information that 12916@c taginfo does ("mov", &c). 12917@c * It only is run for rtag, not tag. 12918@end table 12919 12920You should also see @pxref{Module program options} about how the 12921``program options'' programs are run. 12922 12923@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12924 12925@node Module program options 12926@appendixsubsec How the modules file ``program options'' programs are run 12927@cindex Modules file program options 12928@cindex -t, in modules file 12929@cindex -o, in modules file 12930@cindex -e, in modules file 12931 12932@noindent 12933For checkout, rtag, and export, the program is server-based, and as such the 12934following applies:- 12935 12936If using remote access methods (pserver, ext, etc.), 12937@sc{cvs} will execute this program on the server from a temporary 12938directory. The path is searched for this program. 12939 12940If using ``local access'' (on a local or remote NFS file system, i.e. 12941repository set just to a path), 12942the program will be executed from the newly checked-out tree, if 12943found there, or alternatively searched for in the path if not. 12944 12945The programs are all run after the operation has effectively 12946completed. 12947 12948 12949@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12950@node Wrappers 12951@appendixsec The cvswrappers file 12952@cindex cvswrappers (admin file) 12953@cindex CVSWRAPPERS, environment variable 12954@cindex Wrappers 12955 12956@c FIXME: need some better way of separating this out 12957@c by functionality. -m is 12958@c one feature, and -k is a another. And this discussion 12959@c should be better motivated (e.g. start with the 12960@c problems, then explain how the feature solves it). 12961 12962Wrappers refers to a @sc{cvs} feature which lets you 12963control certain settings based on the name of the file 12964which is being operated on. The settings are @samp{-k} 12965for binary files, and @samp{-m} for nonmergeable text 12966files. 12967 12968The @samp{-m} option 12969specifies the merge methodology that should be used when 12970a non-binary file is updated. @code{MERGE} means the usual 12971@sc{cvs} behavior: try to merge the files. @code{COPY} 12972means that @code{cvs update} will refuse to merge 12973files, as it also does for files specified as binary 12974with @samp{-kb} (but if the file is specified as 12975binary, there is no need to specify @samp{-m 'COPY'}). 12976@sc{cvs} will provide the user with the 12977two versions of the files, and require the user using 12978mechanisms outside @sc{cvs}, to insert any necessary 12979changes. 12980 12981@strong{WARNING: do not use @code{COPY} with 12982@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 12983copy one version of your file over the other, wiping 12984out the previous contents.} 12985@c Ordinarily we don't document the behavior of old 12986@c versions. But this one is so dangerous, I think we 12987@c must. I almost renamed it to -m 'NOMERGE' so we 12988@c could say "never use -m 'COPY'". 12989The @samp{-m} wrapper option only affects behavior when 12990merging is done on update; it does not affect how files 12991are stored. See @ref{Binary files}, for more on 12992binary files. 12993 12994The basic format of the file @file{cvswrappers} is: 12995 12996@c FIXME: @example is all wrong for this. Use @deffn or 12997@c something more sensible. 12998@example 12999wildcard [option value][option value]... 13000 13001where option is one of 13002-m update methodology value: MERGE or COPY 13003-k keyword expansion value: expansion mode 13004 13005and value is a single-quote delimited value. 13006@end example 13007 13008@ignore 13009@example 13010*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' 13011*.c -t 'indent %s %s' 13012@end example 13013@c When does the filter need to be an absolute pathname 13014@c and when will something like the above work? I 13015@c suspect it relates to the PATH of the server (which 13016@c in turn depends on all kinds of stuff, e.g. inetd 13017@c for pserver). I'm not sure whether/where to discuss 13018@c this. 13019@c FIXME: What do the %s's stand for? 13020 13021@noindent 13022The above example of a @file{cvswrappers} file 13023states that all files/directories that end with a @code{.nib} 13024should be filtered with the @file{wrap} program before 13025checking the file into the repository. The file should 13026be filtered though the @file{unwrap} program when the 13027file is checked out of the repository. The 13028@file{cvswrappers} file also states that a @code{COPY} 13029methodology should be used when updating the files in 13030the repository (that is, no merging should be performed). 13031 13032@c What pitfalls arise when using indent this way? Is 13033@c it a winning thing to do? Would be nice to at least 13034@c hint at those issues; we want our examples to tell 13035@c how to solve problems, not just to say that cvs can 13036@c do certain things. 13037The last example line says that all files that end with 13038@code{.c} should be filtered with @file{indent} 13039before being checked into the repository. Unlike the previous 13040example, no filtering of the @code{.c} file is done when 13041it is checked out of the repository. 13042@noindent 13043The @code{-t} filter is called with two arguments, 13044the first is the name of the file/directory to filter 13045and the second is the pathname to where the resulting 13046filtered file should be placed. 13047 13048@noindent 13049The @code{-f} filter is called with one argument, 13050which is the name of the file to filter from. The end 13051result of this filter will be a file in the users directory 13052that they can work on as they normally would. 13053 13054Note that the @samp{-t}/@samp{-f} features do not 13055conveniently handle one portion of @sc{cvs}'s operation: 13056determining when files are modified. @sc{cvs} will still 13057want a file (or directory) to exist, and it will use 13058its modification time to determine whether a file is 13059modified. If @sc{cvs} erroneously thinks a file is 13060unmodified (for example, a directory is unchanged but 13061one of the files within it is changed), you can force 13062it to check in the file anyway by specifying the 13063@samp{-f} option to @code{cvs commit} (@pxref{commit 13064options}). 13065@c This is, of course, a serious design flaw in -t/-f. 13066@c Probably the whole functionality needs to be 13067@c redesigned (starting from requirements) to fix this. 13068@end ignore 13069 13070@c FIXME: We don't document -W or point to where it is 13071@c documented. Or .cvswrappers. 13072For example, the following command imports a 13073directory, treating files whose name ends in 13074@samp{.exe} as binary: 13075 13076@example 13077cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 13078@end example 13079 13080@c Another good example, would be storing files 13081@c (e.g. binary files) compressed in the repository. 13082@c :::::::::::::::::: 13083@c cvswrappers 13084@c :::::::::::::::::: 13085@c *.t12 -m 'COPY' 13086@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 13087@c 13088@c :::::::::::::::::: 13089@c gunzipcp 13090@c :::::::::::::::::: 13091@c : 13092@c [ -f $1 ] || exit 1 13093@c zcat $1 > /tmp/.#$1.$$ 13094@c mv /tmp/.#$1.$$ $1 13095@c 13096@c :::::::::::::::::: 13097@c gzipcp 13098@c :::::::::::::::::: 13099@c : 13100@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 13101@c if [ ! -d $DIRNAME ] ; then 13102@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 13103@c fi 13104@c gzip -c $DIRNAME > $2 13105@c One catch--"cvs diff" will not invoke the wrappers 13106@c (probably a CVS bug, although I haven't thought it out). 13107 13108@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13109@node Trigger Scripts 13110@appendixsec The Trigger Scripts 13111@cindex info files 13112@cindex trigger scripts 13113@cindex script hooks 13114 13115@c FIXME 13116@c Somewhere there needs to be a more "how-to" guide to writing these. 13117@c One particular issue that people sometimes are worried about is performance, 13118@c and the impact of writing in perl or sh or ____. Performance comparisons 13119@c should probably remain outside the scope of this document, but at least 13120@c _that_ much could be referenced, perhaps with links to other sources. 13121 13122Several of the administrative files support triggers, or the launching external 13123scripts or programs at specific times before or after particular events, during 13124the execution of @sc{cvs} commands. These hooks can be used to prevent certain 13125actions, log them, and/or maintain anything else you deem practical. 13126 13127All the trigger scripts are launched in a copy of the user sandbox being 13128committed, on the server, in client-server mode. In local mode, the scripts 13129are actually launched directly from the user sandbox directory being committed. 13130For most intents and purposes, the same scripts can be run in both locations 13131without alteration. 13132 13133@menu 13134* syntax:: The common syntax 13135* Trigger Script Security:: Trigger script security 13136 13137* commit files:: The commit support files (commitinfo, 13138 verifymsg, loginfo) 13139* commitinfo:: Pre-commit checking 13140* verifymsg:: How are log messages evaluated? 13141* loginfo:: Where should log messages be sent? 13142 13143* postadmin:: Logging admin commands 13144* taginfo:: Verifying/Logging tags 13145* posttag:: Logging tags 13146* postwatch:: Logging watch commands 13147 13148* preproxy:: Launch a script on a secondary server prior 13149 to becoming a write proxy 13150* postproxy:: Launch a script on a secondary server after 13151 completing proxy operations 13152@end menu 13153 13154@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13155@node syntax 13156@appendixsubsec The common syntax 13157@cindex info files, common syntax 13158@cindex script hooks, common syntax 13159@cindex trigger script hooks, common syntax 13160@cindex syntax of trigger script hooks 13161 13162@c FIXME: having this so totally separate from the 13163@c Variables node is rather bogus. 13164 13165The administrative files such as @file{commitinfo}, 13166@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 13167all have a common format. The purpose of the files are 13168described later on. The common syntax is described 13169here. 13170 13171@cindex Regular expression syntax 13172Each line contains the following: 13173 13174@itemize @bullet 13175@cindex @samp{ALL} keyword, in lieu of regular expressions in script hooks 13176@cindex @samp{DEFAULT} keyword, in lieu of regular expressions in script hooks 13177@item 13178A regular expression or the literal string @samp{DEFAULT}. Some script hooks 13179also support the literal string @samp{ALL}. Other than the @samp{ALL} and 13180@samp{DEFAULT} keywords, this is a basic regular expression in the syntax used 13181by GNU emacs. See the descriptions of the individual script hooks for 13182information on whether the @samp{ALL} keyword is supported 13183(@pxref{Trigger Scripts}). 13184@c FIXME: What we probably should be saying is "POSIX Basic 13185@c Regular Expression with the following extensions (`\(' 13186@c `\|' '+' etc)" 13187@c rather than define it with reference to emacs. 13188@c The reference to emacs is not strictly speaking 13189@c true, as we don't support \=, \s, or \S. Also it isn't 13190@c clear we should document and/or promise to continue to 13191@c support all the obscure emacs extensions like \<. 13192@c Also need to better cite (or include) full 13193@c documentation for the syntax. 13194@c Also see comment in configure.in about what happens to the 13195@c syntax if we pick up a system-supplied regexp matcher. 13196 13197@item 13198A whitespace separator---one or more spaces and/or tabs. 13199 13200@item 13201A file name or command-line template. 13202@end itemize 13203 13204@noindent 13205Blank lines are ignored. Lines that start with the 13206character @samp{#} are treated as comments. Long lines 13207unfortunately can @emph{not} be broken in two parts in 13208any way. 13209 13210The first regular expression that matches the current 13211directory name in the repository or the first line containing @samp{DEFAULT} 13212in lieu of a regular expression is used and all lines containing @samp{ALL} is 13213used for the hooks which support the @samp{ALL} keyword. The rest of the line 13214is used as a file name or command-line template as appropriate. See the 13215descriptions of the individual script hooks for information on whether the 13216@samp{ALL} keyword is supported (@pxref{Trigger Scripts}). 13217 13218@cindex format strings 13219@cindex format strings, common syntax 13220@cindex info files, common syntax, format strings 13221@cindex Common syntax of info files, format strings 13222@noindent 13223@emph{Note: The following information on format strings is valid 13224as long as the line @code{UseNewInfoFmtStrings=yes} appears in 13225your repository's config file (@pxref{config}). Otherwise, 13226default format strings may be appended to the command line and 13227the @samp{loginfo} file, especially, can exhibit slightly 13228different behavior. For more information, 13229@xref{Updating Commit Files}.} 13230 13231In the cases where the second segment of the matched line is a 13232command line template (e.g. @file{commitinfo}, @file{loginfo}, 13233& @file{verifymsg}), the command line template may contain format 13234strings which will be replaced with specific values before the 13235script is run. 13236@c FIXCVS then FIXME - it really would make sense to allow %r & maybe even %p 13237@c to be used in rcsinfo to construct a path, but I haven't 13238@c coded this yet. 13239 13240Format strings can represent a single variable or one or more 13241attributes of a list variable. An example of a list variable 13242would be the list available to scripts hung on the loginfo hooks 13243- the list of files which were just committed. In the case of 13244loginfo, three attributes are available for each list item: file 13245name, precommit version, and postcommit version. 13246 13247Format strings consist of a @samp{%} character followed by an optional 13248@samp{@{} (required in the multiple list attribute case), a 13249single format character representing a variable or a single attribute of 13250list elements or multiple format characters representing attributes of 13251list elements, and a closing @samp{@}} when the open bracket was present. 13252 13253@emph{Flat format strings}, or single format characters which get replaced 13254with a single value, will generate a single argument 13255to the called script, regardless of whether the replacement variable contains 13256white space or other special characters. 13257 13258@emph{List attributes} will generate an argument for each attribute 13259requested for each list item. For example, @samp{%@{sVv@}} 13260in a @file{loginfo} command template will generate three 13261arguments (file name, precommit version, postcommit version, 13262...) for each file committed. As in the flat format string 13263case, each attribute will be passed in as a single argument 13264regardless of whether it contains white space or other 13265special characters. 13266 13267@samp{%%} will be replaced with a literal @samp{%}. 13268 13269The format strings available to all script hooks are: 13270 13271@table @t 13272@item c 13273The canonical name of the command being executed. For instance, in the case of 13274a hook run from @code{cvs up}, @sc{cvs} would replace @samp{%c} with the string 13275@samp{update} and, in the case of a hook run from @code{cvs ci}, @sc{cvs} would 13276replace @samp{%c} with the string @samp{commit}. 13277@item n 13278The null, or empty, string. 13279@item p 13280The name of the directory being operated on within the repository. 13281@item r 13282The name of the repository (the path portion of @code{$CVSROOT}). 13283@item R 13284On a server, the name of the referrer, if any. The referrer is the CVSROOT the 13285client reports it used to contact a server which then referred it to this 13286server. Should usually be set on a primary server with a write proxy setup. 13287@end table 13288 13289Other format strings are file specific. See the docs on the 13290particular script hooks for more information 13291(@pxref{Trigger Scripts}). 13292 13293As an example, the following line in a @file{loginfo} file would 13294match only the directory @file{module} and any subdirectories of 13295@file{module}: 13296 13297@example 13298^module\(/\|$\) (echo; echo %p; echo %@{sVv@}; cat) >>$CVSROOT/CVSROOT/commitlog 13299@end example 13300 13301Using this same line and assuming a commit of new revisions 133021.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27, 13303respectively, of file1 and file2 in module, something like the 13304following log message should be appended to commitlog: 13305 13306@example 13307 13308module 13309file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1 13310Update of /cvsroot/module 13311In directory localhost.localdomain:/home/jrandom/work/module 13312 13313Modified Files: 13314 file1 file2 13315Log Message: 13316A log message. 13317@end example 13318 13319@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13320@node Trigger Script Security 13321@appendixsubsec Security and the Trigger Scripts 13322@cindex info files, security 13323@cindex script hooks, security 13324@cindex trigger scripts, security 13325 13326Security is a huge subject, and implementing a secure system is a non-trivial 13327task. This section will barely touch on all the issues involved, but it is 13328well to note that, as with any script you will be allowing an untrusted 13329user to run on your server, there are measures you can take to help prevent 13330your trigger scripts from being abused. 13331 13332For instance, since the CVS trigger scripts all run in a copy of the user's 13333sandbox on the server, a naively coded Perl trigger script which attempts to 13334use a Perl module that is not installed on the system can be hijacked by any 13335user with commit access who is checking in a file with the correct name. Other 13336scripting languages may be vulnerable to similar hacks. 13337 13338One way to make a script more secure, at least with Perl, is to use scripts 13339which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. 13340In the most basic terms, this causes Perl to avoid running code that may have 13341come from an external source. Please run the @code{perldoc perlsec} command 13342for more on Perl security. Again, other languages may implement other security 13343verification hooks which look more or less like Perl's "taint-check" mechanism. 13344 13345@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13346@node commit files 13347@appendixsubsec The commit support files 13348@cindex Commits, administrative support files 13349@cindex commit files, see Info files 13350 13351The @samp{-i} flag in the @file{modules} file can be 13352used to run a certain program whenever files are 13353committed (@pxref{modules}). The files described in 13354this section provide other, more flexible, ways to run 13355programs whenever something is committed. 13356 13357There are three kinds of programs that can be run on 13358commit. They are specified in files in the repository, 13359as described below. The following table summarizes the 13360file names and the purpose of the corresponding 13361programs. 13362 13363@table @file 13364@item commitinfo 13365The program is responsible for checking that the commit 13366is allowed. If it exits with a non-zero exit status 13367the commit will be aborted. @xref{commitinfo}. 13368 13369@item verifymsg 13370The specified program is used to evaluate the log message, 13371and possibly verify that it contains all required 13372fields. This is most useful in combination with the 13373@file{rcsinfo} file, which can hold a log message 13374template (@pxref{rcsinfo}). @xref{verifymsg}. 13375 13376@item loginfo 13377The specified program is called when the commit is 13378complete. It receives the log message and some 13379additional information and can store the log message in 13380a file, or mail it to appropriate persons, or maybe 13381post it to a local newsgroup, or@dots{} Your 13382imagination is the limit! @xref{loginfo}. 13383@end table 13384 13385@menu 13386* Updating Commit Files:: Updating legacy repositories to stop using 13387 deprecated command line template formats 13388@end menu 13389 13390@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13391@node Updating Commit Files 13392@appendixsubsubsec Updating legacy repositories to stop using deprecated command line template formats 13393@cindex info files, common syntax, updating legacy repositories 13394@cindex Syntax of info files, updating legacy repositories 13395@cindex Common syntax of info files, updating legacy repositories 13396New repositories are created set to use the new format strings by default, so 13397if you are creating a new repository, you shouldn't have to worry about this 13398section. 13399 13400If you are attempting to maintain a legacy repository which was 13401making use of the @file{commitinfo}, @file{editinfo}, @file{verifymsg}, 13402@file{loginfo}, and/or @file{taginfo} script hooks, you should have no 13403immediate problems with using the current @sc{cvs} executable, but your users 13404will probably start to see deprecation warnings. 13405 13406The reason for this is that all of the script hooks have been updated to 13407use a new command line parser that extensibly supports multiple 13408@file{loginfo} & @file{notify} style format strings (@pxref{syntax}) 13409and this support is not completely compatible with the old style format 13410strings. 13411 13412The quick upgrade method is to stick a @samp{1} after each format string 13413in your old @file{loginfo} file. For example: 13414 13415@example 13416DEFAULT (echo ""; id; echo %@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13417@end example 13418 13419would become: 13420 13421@example 13422DEFAULT (echo ""; id; echo %1@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13423@end example 13424 13425If you were counting on the fact that only the first @samp{%} in the line was 13426replaced as a format string, you may also have to double up any further 13427percent signs on the line. 13428 13429If you did this all at once and checked it in, everything should still be 13430running properly. 13431 13432Now add the following line to your config file (@pxref{config}): 13433@example 13434UseNewInfoFmtStrings=yes 13435@end example 13436 13437Everything should still be running properly, but your users will probably 13438start seeing new deprecation warnings. 13439 13440Dealing with the deprecation warnings now generated by @file{commitinfo}, 13441@file{editinfo}, @file{verifymsg}, and @file{taginfo} should be easy. Simply 13442specify what are currently implicit arguments explicitly. This means appending 13443the following strings to each active command line template in each file: 13444@table @code 13445@item commitinfo 13446@samp{ %r/%p %s} 13447@item editinfo 13448@samp{ %l} 13449@item taginfo 13450@samp{ %t %o %p %@{sv@}} 13451@item verifymsg 13452@samp{ %l} 13453@end table 13454 13455If you don't desire that any of the newly available information be passed to 13456the scripts hanging off of these hooks, no further modifications to these 13457files should be necessary to insure current and future compatibility with 13458@sc{cvs}'s format strings. 13459 13460Fixing @file{loginfo} could be a little tougher. The old style 13461@file{loginfo} format strings caused a single space and comma separated 13462argument to be passed in in place of the format string. This is what will 13463continue to be generated due to the deprecated @samp{1} you inserted into 13464the format strings. 13465 13466Since the new format separates each individual item and passes it into the 13467script as a separate argument (for a good reason - arguments containing commas 13468and/or white space are now parsable), to remove the deprecated @samp{1} from 13469your @file{loginfo} command line templates, you will most likely have to 13470rewrite any scripts called by the hook to handle the new argument format. 13471 13472Also note that the way @samp{%} followed by unrecognized characters and by 13473@samp{@{@}} was treated in past versions of CVS is not strictly adhered to as 13474there were bugs in the old versions. Specifically, @samp{%@{@}} would eat the 13475next character and unrecognized strings resolved only to the empty string, 13476which was counter to what was stated in the documentation. This version will 13477do what the documentation said it should have (if you were using only some 13478combination of @samp{%@{sVv@}}, e.g. @samp{%@{sVv@}}, @samp{%@{sV@}}, or 13479@samp{%v}, you should have no troubles). 13480 13481On the bright side, you should have plenty of time to do this before all 13482support for the old format strings is removed from @sc{cvs}, so you can just 13483put up with the deprecation warnings for awhile if you like. 13484 13485@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13486@node commitinfo 13487@appendixsubsec Commitinfo 13488@cindex @file{commitinfo} 13489@cindex Commits, precommit verification of 13490@cindex commitinfo (admin file) 13491@cindex info files, commitinfo 13492@cindex script hooks, commitinfo 13493@cindex trigger scripts, commitinfo 13494@cindex info files, precommit verification of commits 13495@cindex script hooks, precommit verification of commits 13496@cindex trigger scripts, precommit verification of commits 13497 13498The @file{commitinfo} file defines programs to execute 13499whenever @samp{cvs commit} is about to execute. These 13500programs are used for pre-commit checking to verify 13501that the modified, added and removed files are really 13502ready to be committed. This could be used, for 13503instance, to verify that the changed files conform to 13504to your site's standards for coding practice. 13505 13506The @file{commitinfo} file has the standard form for script hooks 13507(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13508a command to execute. It supports only the DEFAULT keywords. 13509 13510@cindex format strings, commitinfo admin file 13511In addition to the common format strings (@pxref{syntax}), 13512@file{commitinfo} supports: 13513 13514@table @t 13515@item @{s@} 13516a list of the names of files to be committed 13517@end table 13518 13519@cindex commitinfo (admin file), updating legacy repositories 13520@cindex compatibility notes, commitinfo admin file 13521Currently, if no format strings are specified, a default 13522string of @samp{ %r/%p %@{s@}} will be appended to the command 13523line template before replacement is performed, but this 13524feature is deprecated. It is simply in place so that legacy 13525repositories will remain compatible with the new @sc{cvs} application. 13526For information on updating, @pxref{Updating Commit Files}. 13527 13528@cindex Exit status, of commitinfo 13529@cindex commitinfo (admin file), exit status 13530The first line with a regular expression matching the 13531directory within the repository will be used. If the 13532command returns a non-zero exit status the commit will 13533be aborted. 13534@c FIXME: need example(s) of what "directory within the 13535@c repository" means. 13536 13537@cindex @file{commitinfo}, working directory 13538@cindex @file{commitinfo}, command environment 13539The command will be run in the root of the workspace 13540containing the new versions of any files the user would like 13541to modify (commit), @emph{or in a copy of the workspace on 13542the server (@pxref{Remote repositories})}. If a file is 13543being removed, there will be no copy of the file under the 13544current directory. If a file is being added, there will be 13545no corresponding archive file in the repository unless the 13546file is being resurrected. 13547 13548Note that both the repository directory and the corresponding 13549Attic (@pxref{Attic}) directory may need to be checked to 13550locate the archive file corresponding to any given file being 13551committed. Much of the information about the specific commit 13552request being made, including the destination branch, commit 13553message, and command line options specified, is not available 13554to the command. 13555 13556@c FIXME: should discuss using commitinfo to control 13557@c who has checkin access to what (e.g. Joe can check into 13558@c directories a, b, and c, and Mary can check into 13559@c directories b, c, and d--note this case cannot be 13560@c conveniently handled with unix groups). Of course, 13561@c adding a new set of features to CVS might be a more 13562@c natural way to fix this problem than telling people to 13563@c use commitinfo. 13564@c FIXME: Should make some reference, especially in 13565@c the context of controlling who has access, to the fact 13566@c that commitinfo can be circumvented. Perhaps 13567@c mention SETXID (but has it been carefully examined 13568@c for holes?). This fits in with the discussion of 13569@c general CVS security in "Password authentication 13570@c security" (the bit which is not pserver-specific). 13571 13572@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13573@node verifymsg 13574@appendixsubsec Verifying log messages 13575@cindex @file{verifymsg} (admin file) 13576@cindex Log message, verifying 13577@cindex logging, commits 13578 13579Once you have entered a log message, you can evaluate 13580that message to check for specific content, such as 13581a bug ID. Use the @file{verifymsg} file to 13582specify a program that is used to verify the log message. 13583This program could be a simple script that checks 13584that the entered message contains the required fields. 13585 13586The @file{verifymsg} file is often most useful together 13587with the @file{rcsinfo} file, which can be used to 13588specify a log message template (@pxref{rcsinfo}). 13589 13590The @file{verifymsg} file has the standard form for script hooks 13591(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13592a command to execute. It supports only the DEFAULT keywords. 13593 13594@cindex format strings, verifymsg admin file 13595In addition to the common format strings (@pxref{syntax}), 13596@file{verifymsg} supports: 13597 13598@table @t 13599@item l 13600the full path to the file containing the log message to be verified 13601@item @{sV@} 13602File attributes, where: 13603@table @t 13604@item s 13605file name 13606@item V 13607old version number (pre-checkin) 13608@end table 13609@end table 13610 13611@cindex verifymsg (admin/commit file), updating legacy repositories 13612@cindex compatibility notes, verifymsg admin file 13613Currently, if no format strings are specified, a default 13614string of @samp{ %l} will be appended to the command 13615line template before replacement is performed, but this 13616feature is deprecated. It is simply in place so that legacy 13617repositories will remain compatible with the new @sc{cvs} application. 13618For information on updating, @pxref{Updating Commit Files}. 13619 13620One thing that should be noted is that the @samp{ALL} 13621keyword is not supported. If more than one matching 13622line is found, the first one is used. This can be 13623useful for specifying a default verification script in a 13624directory, and then overriding it in a subdirectory. 13625 13626@cindex Exit status, of @file{verifymsg} 13627If the verification script exits with a non-zero exit status, 13628the commit is aborted. 13629 13630@cindex @file{verifymsg}, changing the log message 13631In the default configuration, CVS allows the 13632verification script to change the log message. This is 13633controlled via the RereadLogAfterVerify CVSROOT/config 13634option. 13635 13636When @samp{RereadLogAfterVerify=always} or 13637@samp{RereadLogAfterVerify=stat}, the log message will 13638either always be reread after the verification script 13639is run or reread only if the log message file status 13640has changed. 13641 13642@xref{config}, for more on CVSROOT/config options. 13643 13644It is NOT a good idea for a @file{verifymsg} script to 13645interact directly with the user in the various 13646client/server methods. For the @code{pserver} method, 13647there is no protocol support for communicating between 13648@file{verifymsg} and the client on the remote end. For the 13649@code{ext} and @code{server} methods, it is possible 13650for CVS to become confused by the characters going 13651along the same channel as the CVS protocol 13652messages. See @ref{Remote repositories}, for more 13653information on client/server setups. In addition, at the time 13654the @file{verifymsg} script runs, the CVS 13655server has locks in place in the repository. If control is 13656returned to the user here then other users may be stuck waiting 13657for access to the repository. 13658 13659This option can be useful if you find yourself using an 13660rcstemplate that needs to be modified to remove empty 13661elements or to fill in default values. It can also be 13662useful if the rcstemplate has changed in the repository 13663and the CVS/Template was not updated, but is able to be 13664adapted to the new format by the verification script 13665that is run by @file{verifymsg}. 13666 13667An example of an update might be to change all 13668occurrences of 'BugId:' to be 'DefectId:' (which can be 13669useful if the rcstemplate has recently been changed and 13670there are still checked-out user trees with cached 13671copies in the CVS/Template file of the older version). 13672 13673Another example of an update might be to delete a line 13674that contains 'BugID: none' from the log message after 13675validation of that value as being allowed is made. 13676 13677@menu 13678* verifymsg example:: Verifymsg example 13679@end menu 13680 13681@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13682@node verifymsg example 13683@appendixsubsubsec Verifying log messages 13684@cindex verifymsg, example 13685The following is a little silly example of a 13686@file{verifymsg} file, together with the corresponding 13687@file{rcsinfo} file, the log message template and a 13688verification script. We begin with the log message template. 13689We want to always record a bug-id number on the first 13690line of the log message. The rest of log message is 13691free text. The following template is found in the file 13692@file{/usr/cvssupport/tc.template}. 13693 13694@example 13695BugId: 13696@end example 13697 13698The script @file{/usr/cvssupport/bugid.verify} is used to 13699evaluate the log message. 13700 13701@example 13702#!/bin/sh 13703# 13704# bugid.verify filename 13705# 13706# Verify that the log message contains a valid bugid 13707# on the first line. 13708# 13709if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 13710 exit 0 13711elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 13712 # It is okay to allow commits with 'BugId: none', 13713 # but do not put that text into the real log message. 13714 grep -v '^BugId:[ ]*none$' > $1.rewrite 13715 mv $1.rewrite $1 13716 exit 0 13717else 13718 echo "No BugId found." 13719 exit 1 13720fi 13721@end example 13722 13723The @file{verifymsg} file contains this line: 13724 13725@example 13726^tc /usr/cvssupport/bugid.verify %l 13727@end example 13728 13729The @file{rcsinfo} file contains this line: 13730 13731@example 13732^tc /usr/cvssupport/tc.template 13733@end example 13734 13735The @file{config} file contains this line: 13736 13737@example 13738RereadLogAfterVerify=always 13739@end example 13740 13741 13742 13743@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13744@node loginfo 13745@appendixsubsec Loginfo 13746@cindex loginfo (admin file) 13747@cindex logging, commits 13748@cindex Storing log messages 13749@cindex Mailing log messages 13750@cindex Distributing log messages 13751@cindex Log messages 13752 13753The @file{loginfo} file is used to control where log information is sent after 13754versioned changes are made to repository archive files and after directories 13755are added ot the repository. @ref{posttag} for how to log tagging 13756information and @ref{postadmin} for how to log changes due to the @code{admin} 13757command. 13758 13759The @file{loginfo} file has the standard form for script hooks 13760(@pxref{Trigger Scripts}), where each line is a regular expression followed by 13761a command to execute. It supports the ALL and DEFAULT keywords. 13762 13763Any specified scripts are called: 13764 13765@table @code 13766@item commit 13767Once per directory, immediately after a successfully completing the commit of 13768all files within that directory. 13769@item import 13770Once per import, immediately after completion of all write operations. 13771@item add 13772Immediately after the successful @code{add} of a directory. 13773@end table 13774 13775Any script called via @file{loginfo} will be fed the log information on its 13776standard input. Note that the filter program @strong{must} read @strong{all} 13777of the log information from its standard input or @sc{cvs} may fail with a 13778broken pipe signal. 13779 13780@cindex format strings, loginfo admin file 13781In addition to the common format strings (@pxref{syntax}), 13782@file{loginfo} supports: 13783 13784@table @t 13785@item @{stVv@} 13786File attributes, where: 13787@table @t 13788@item s 13789file name 13790@item T 13791tag name of destination, or the empty string when there is no associated 13792tag name (this usually means the trunk) 13793@item V 13794old version number (pre-checkin) 13795@item v 13796new version number (post-checkin) 13797@end table 13798@end table 13799 13800For example, some valid format strings are @samp{%%}, 13801@samp{%s}, @samp{%@{s@}}, and @samp{%@{stVv@}}. 13802 13803@cindex loginfo (admin file), updating legacy repositories 13804@cindex compatibility notes, loginfo admin file 13805Currently, if @samp{UseNewInfoFmtStrings} is not set in the @file{config} 13806administration file (@pxref{config}), the format strings will be substituted 13807as they were in past versions of @sc{cvs}, but this feature is deprecated. 13808It is simply in place so that legacy repositories will remain compatible with 13809the new @sc{cvs} application. For information on updating, 13810please see @ref{Updating Commit Files}. 13811 13812As an example, if @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%p} 13813and @samp{%@{sVv@}} are the format strings, and three files (@t{ChangeLog}, 13814@t{Makefile}, @t{foo.c}) were modified, the output might be: 13815 13816@example 13817yoyodyne/tc ChangeLog 1.1 1.2 Makefile 1.3 1.4 foo.c 1.12 1.13 13818@end example 13819 13820Note: when @sc{cvs} is accessing a remote repository, 13821@file{loginfo} will be run on the @emph{remote} 13822(i.e., server) side, not the client side (@pxref{Remote 13823repositories}). 13824 13825@menu 13826* loginfo example:: Loginfo example 13827* Keeping a checked out copy:: Updating a tree on every checkin 13828@end menu 13829 13830@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13831@node loginfo example 13832@appendixsubsubsec Loginfo example 13833 13834The following @file{loginfo} file, together with the 13835tiny shell-script below, appends all log messages 13836to the file @file{$CVSROOT/CVSROOT/commitlog}, 13837and any commits to the administrative files (inside 13838the @file{CVSROOT} directory) are also logged in 13839@file{/usr/adm/cvsroot-log}. 13840Commits to the @file{prog1} directory are mailed to @t{ceder}. 13841 13842@c FIXME: is it a CVS feature or bug that only the 13843@c first matching line is used? It is documented 13844@c above, but is it useful? For example, if we wanted 13845@c to run both "cvs-log" and "Mail" for the CVSROOT 13846@c directory, it is kind of awkward if 13847@c only the first matching line is used. 13848@example 13849ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 13850^CVSROOT\(/\|$\) /usr/local/bin/cvs-log /usr/adm/cvsroot-log $USER 13851^prog1\(/\|$\) Mail -s "%p %s" ceder 13852@end example 13853 13854The shell-script @file{/usr/local/bin/cvs-log} looks 13855like this: 13856 13857@example 13858#!/bin/sh 13859(echo "------------------------------------------------------"; 13860 echo -n "$2 "; 13861 date; 13862 echo; 13863 cat) >> $1 13864@end example 13865 13866 13867 13868@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13869@node Keeping a checked out copy 13870@appendixsubsubsec Keeping a checked out copy 13871 13872@c What other index entries? It seems like 13873@c people might want to use a lot of different 13874@c words for this functionality. 13875@cindex Keeping a checked out copy 13876@cindex Checked out copy, keeping 13877@cindex Web pages, maintaining with CVS 13878 13879It is often useful to maintain a directory tree which 13880contains files which correspond to the latest version 13881in the repository. For example, other developers might 13882want to refer to the latest sources without having to 13883check them out, or you might be maintaining a web site 13884with @sc{cvs} and want every checkin to cause the files 13885used by the web server to be updated. 13886@c Can we offer more details on the web example? Or 13887@c point the user at how to figure it out? This text 13888@c strikes me as sufficient for someone who already has 13889@c some idea of what we mean but not enough for the naive 13890@c user/sysadmin to understand it and set it up. 13891 13892The way to do this is by having loginfo invoke 13893@code{cvs update}. Doing so in the naive way will 13894cause a problem with locks, so the @code{cvs update} 13895must be run in the background. 13896@c Should we try to describe the problem with locks? 13897@c It seems like a digression for someone who just 13898@c wants to know how to make it work. 13899@c Another choice which might work for a single file 13900@c is to use "cvs -n update -p" which doesn't take 13901@c out locks (I think) but I don't see many advantages 13902@c of that and we might as well document something which 13903@c works for multiple files. 13904Here is an example for unix (this should all be on one line): 13905 13906@example 13907^cyclic-pages\(/\|$\) (date; cat; (sleep 2; cd /u/www/local-docs; 13908 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 13909@end example 13910 13911This will cause checkins to repository directory @code{cyclic-pages} 13912and its subdirectories to update the checked 13913out tree in @file{/u/www/local-docs}. 13914@c More info on some of the details? The "sleep 2" is 13915@c so if we are lucky the lock will be gone by the time 13916@c we start and we can wait 2 seconds instead of 30. 13917 13918 13919 13920@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13921@node postadmin 13922@appendixsubsec Logging admin commands 13923@cindex postadmin (admin file) 13924@cindex script hook, postadmin 13925@cindex Admin commands, logging 13926 13927The @file{postadmin} file defines programs to execute after an @code{admin} 13928command modifies files. The @file{postadmin} file has the standard form 13929for script hooks (@pxref{Trigger Scripts}), where each line is a regular 13930expression followed by a command to execute. It supports the ALL and DEFAULT 13931keywords. 13932 13933@cindex format strings, postadmin admin file 13934The @file{postadmin} file supports no format strings other than the common 13935ones (@pxref{syntax}), 13936 13937 13938 13939@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13940@node taginfo 13941@appendixsubsec Taginfo 13942@cindex taginfo (admin file) 13943@cindex script hook, taginfo 13944@cindex Tags, logging 13945@cindex Tags, verifying 13946The @file{taginfo} file defines programs to execute 13947when someone executes a @code{tag} or @code{rtag} 13948command. The @file{taginfo} file has the standard form 13949for script hooks (@pxref{Trigger Scripts}), where each line 13950is a regular expression followed by a command to execute. 13951It supports the ALL and DEFAULT keywords. 13952 13953@cindex format strings, taginfo admin file 13954In addition to the common format strings (@pxref{syntax}), 13955@file{taginfo} supports: 13956 13957@table @t 13958@item b 13959tag type (@code{T} for branch, @code{N} for not-branch, or @code{?} for 13960unknown, as during delete operations) 13961@item o 13962operation (@code{add} for @code{tag}, @code{mov} for @code{tag -F}, or 13963@code{del} for @code{tag -d}) 13964@item t 13965new tag name 13966@item @{sTVv@} 13967file attributes, where: 13968@table @t 13969@item s 13970file name 13971@item T 13972tag name of destination, or the empty string when there is no associated 13973tag name (this usually means the trunk) 13974@item V 13975old version number (for a move or delete operation) 13976@item v 13977new version number (for an add or move operation) 13978@end table 13979@end table 13980 13981For example, some valid format strings are @samp{%%}, @samp{%p}, @samp{%t}, 13982@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 13983 13984@cindex taginfo (admin file), updating legacy repositories 13985@cindex compatibility notes, taginfo admin file 13986Currently, if no format strings are specified, a default 13987string of @samp{ %t %o %p %@{sv@}} will be appended to the command 13988line template before replacement is performed, but this 13989feature is deprecated. It is simply in place so that legacy 13990repositories will remain compatible with the new @sc{cvs} application. 13991For information on updating, @pxref{Updating Commit Files}. 13992 13993@cindex Exit status, of taginfo admin file 13994@cindex taginfo (admin file), exit status 13995A non-zero exit of the filter program will cause the tag to be 13996aborted. 13997 13998Here is an example of using @file{taginfo} to log @code{tag} and @code{rtag} 13999commands. In the @file{taginfo} file put: 14000 14001@example 14002ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %@{sVv@} 14003@end example 14004 14005@noindent 14006Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 14007following script: 14008 14009@example 14010#!/bin/sh 14011echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 14012@end example 14013 14014 14015 14016@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14017@node posttag 14018@appendixsubsec Logging tags 14019@cindex posttag (admin file) 14020@cindex script hook, posttag 14021@cindex Tags, logging 14022 14023The @file{posttag} file defines programs to execute after a @code{tag} or 14024@code{rtag} command modifies files. The @file{posttag} file has the standard 14025form for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14026expression followed by a command to execute. It supports the ALL and DEFAULT 14027keywords. 14028 14029@cindex format strings, posttag admin file 14030The @file{posttag} admin file supports the same format strings as the 14031@file{taginfo} file (@pxref{taginfo}), 14032 14033 14034 14035@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14036@node postwatch 14037@appendixsubsec Logging watch commands 14038@cindex postwatch (admin file) 14039@cindex script hook, postwatch 14040@cindex Watch family of commands, logging 14041 14042The @file{postwatch} file defines programs to execute after any command (for 14043instance, @code{watch}, @code{edit}, @code{unedit}, or @code{commit}) modifies 14044any @file{CVS/fileattr} file in the repository (@pxref{Watches}). The 14045@file{postwatch} file has the standard form for script hooks 14046(@pxref{Trigger Scripts}), where each line is a regular expression followed by 14047a command to execute. It supports the ALL and DEFAULT keywords. 14048 14049@cindex format strings, postwatch admin file 14050The @file{postwatch} file supports no format strings other than the common 14051ones (@pxref{syntax}), but it is worth noting that the @code{%c} format string 14052may not be replaced as you might expect. Client runs of @code{edit} and 14053@code{unedit} can sometimes skip contacting the @sc{cvs} server and cache the 14054notification of the file attribute change to be sent the next time the client 14055contacts the server for whatever other reason, 14056 14057 14058 14059@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14060@node preproxy 14061@appendixsubsec Launch a Script before Proxying 14062@cindex preproxy (admin file) 14063@cindex script hook, preproxy 14064@cindex Write proxy, verifying 14065@cindex Write proxy, logging 14066 14067The @file{preproxy} file defines programs to execute after a secondary 14068server receives a write request from a client, just before it starts up the 14069primary server and becomes a write proxy. This hook could be used to 14070dial a modem, launch an SSH tunnel, establish a VPN, or anything else that 14071might be necessary to do before contacting the primary server. 14072 14073@file{preproxy} scripts are called once, at the time of the write request, with 14074the repository argument (if requested) set from the topmost directory sent by 14075the client. 14076 14077The @file{preproxy} file has the standard form 14078for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14079expression followed by a command to execute. It supports the ALL and DEFAULT 14080keywords. 14081 14082@cindex format strings, preproxy admin file 14083In addition to the common format strings, the @file{preproxy} file supports the 14084following format string: 14085 14086@table @t 14087@item P 14088the CVSROOT string which specifies the primary server 14089@end table 14090 14091 14092 14093@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14094@node postproxy 14095@appendixsubsec Launch a Script after Proxying 14096@cindex postproxy (admin file) 14097@cindex script hook, postproxy 14098@cindex Write proxy, logging 14099@cindex Write proxy, pull updates 14100@cindex secondary server, pull updates 14101 14102The @file{postproxy} file defines programs to execute after a secondary 14103server notes that the connection to the primary server has shut down and before 14104it releases the client by shutting down the connection to the client. 14105This could hook could be used to 14106disconnect a modem, an SSH tunnel, a VPN, or anything else that 14107might be necessary to do after contacting the primary server. This hook should 14108also be used to pull updates from the primary server before allowing the client 14109which did the write to disconnect since otherwise the client's next read 14110request may generate error messages and fail upon encountering an out of date 14111repository on the secondary server. 14112 14113@file{postproxy} scripts are called once per directory. 14114 14115The @file{postproxy} file has the standard form 14116for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14117expression followed by a command to execute. It supports the ALL and DEFAULT 14118keywords. 14119 14120@cindex format strings, postproxy admin file 14121In addition to the common format strings, the @file{postproxy} file supports 14122the following format string: 14123 14124@table @t 14125@item P 14126the CVSROOT string which specifies the primary server 14127@end table 14128 14129 14130 14131@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14132@node rcsinfo 14133@appendixsec Rcsinfo 14134@cindex rcsinfo (admin file) 14135@cindex Form for log message 14136@cindex Log message template 14137@cindex Template for log message 14138@cindex logging, commits 14139 14140The @file{rcsinfo} file can be used to specify a form to 14141edit when filling out the commit log. The 14142@file{rcsinfo} file has a syntax similar to the 14143@file{verifymsg}, @file{commitinfo} and @file{loginfo} 14144files. @xref{syntax}. Unlike the other files the second 14145part is @emph{not} a command-line template. Instead, 14146the part after the regular expression should be a full pathname to 14147a file containing the log message template. 14148 14149If the repository name does not match any of the 14150regular expressions in this file, the @samp{DEFAULT} 14151line is used, if it is specified. 14152 14153All occurrences of the name @samp{ALL} appearing as a 14154regular expression are used in addition to the first 14155matching regular expression or @samp{DEFAULT}. 14156 14157@c FIXME: should be offering advice, somewhere around 14158@c here, about where to put the template file. The 14159@c verifymsg example uses /usr/cvssupport but doesn't 14160@c say anything about what that directory is for or 14161@c whether it is hardwired into CVS or who creates 14162@c it or anything. In particular we should say 14163@c how to version control the template file. A 14164@c probably better answer than the /usr/cvssupport 14165@c stuff is to use checkoutlist (with xref to the 14166@c checkoutlist doc). 14167@c Also I am starting to see a connection between 14168@c this and the Keeping a checked out copy node. 14169@c Probably want to say something about that. 14170The log message template will be used as a default log 14171message. If you specify a log message with @samp{cvs 14172commit -m @var{message}} or @samp{cvs commit -f 14173@var{file}} that log message will override the 14174template. 14175 14176@xref{verifymsg}, for an example @file{rcsinfo} 14177file. 14178 14179When @sc{cvs} is accessing a remote repository, 14180the contents of @file{rcsinfo} at the time a directory 14181is first checked out will specify a template. This 14182template will be updated on all @samp{cvs update} 14183commands. It will also be added to new directories 14184added with a @samp{cvs add new-directory} command. 14185In versions of @sc{cvs} prior to version 1.12, the 14186@file{CVS/Template} file was not updated. If the 14187@sc{cvs} server is at version 1.12 or higher an older 14188client may be used and the @file{CVS/Template} will 14189be updated from the server. 14190 14191@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14192@node cvsignore 14193@appendixsec Ignoring files via cvsignore 14194@cindex cvsignore (admin file), global 14195@cindex Global cvsignore 14196@cindex Ignoring files 14197@c -- This chapter should maybe be moved to the 14198@c tutorial part of the manual? 14199 14200There are certain file names that frequently occur 14201inside your working copy, but that you don't want to 14202put under @sc{cvs} control. Examples are all the object 14203files that you get while you compile your sources. 14204Normally, when you run @samp{cvs update}, it prints a 14205line for each file it encounters that it doesn't know 14206about (@pxref{update output}). 14207 14208@sc{cvs} has a list of files (or sh(1) file name patterns) 14209that it should ignore while running @code{update}, 14210@code{import} and @code{release}. 14211@c -- Are those the only three commands affected? 14212This list is constructed in the following way. 14213 14214@itemize @bullet 14215@item 14216The list is initialized to include certain file name 14217patterns: names associated with @sc{cvs} 14218administration, or with other common source control 14219systems; common names for patch files, object files, 14220archive files, and editor backup files; and other names 14221that are usually artifacts of assorted utilities. 14222Currently, the default list of ignored file name 14223patterns is: 14224 14225@cindex Ignored files 14226@cindex Automatically ignored files 14227@example 14228 RCS SCCS CVS CVS.adm 14229 RCSLOG cvslog.* 14230 tags TAGS 14231 .make.state .nse_depinfo 14232 *~ #* .#* ,* _$* *$ 14233 *.old *.bak *.BAK *.orig *.rej .del-* 14234 *.a *.olb *.o *.obj *.so *.exe 14235 *.Z *.elc *.ln 14236 core 14237@end example 14238 14239@item 14240The per-repository list in 14241@file{$CVSROOT/CVSROOT/cvsignore} is appended to 14242the list, if that file exists. 14243 14244@item 14245The per-user list in @file{.cvsignore} in your home 14246directory is appended to the list, if it exists. 14247 14248@item 14249Any entries in the environment variable 14250@code{$CVSIGNORE} is appended to the list. 14251 14252@item 14253Any @samp{-I} options given to @sc{cvs} is appended. 14254 14255@item 14256As @sc{cvs} traverses through your directories, the contents 14257of any @file{.cvsignore} will be appended to the list. 14258The patterns found in @file{.cvsignore} are only valid 14259for the directory that contains them, not for 14260any sub-directories. 14261@end itemize 14262 14263In any of the 5 places listed above, a single 14264exclamation mark (@samp{!}) clears the ignore list. 14265This can be used if you want to store any file which 14266normally is ignored by @sc{cvs}. 14267 14268Specifying @samp{-I !} to @code{cvs import} will import 14269everything, which is generally what you want to do if 14270you are importing files from a pristine distribution or 14271any other source which is known to not contain any 14272extraneous files. However, looking at the rules above 14273you will see there is a fly in the ointment; if the 14274distribution contains any @file{.cvsignore} files, then 14275the patterns from those files will be processed even if 14276@samp{-I !} is specified. The only workaround is to 14277remove the @file{.cvsignore} files in order to do the 14278import. Because this is awkward, in the future 14279@samp{-I !} might be modified to override 14280@file{.cvsignore} files in each directory. 14281 14282Note that the syntax of the ignore files consists of a 14283series of lines, each of which contains a space 14284separated list of filenames. This offers no clean way 14285to specify filenames which contain spaces, but you can 14286use a workaround like @file{foo?bar} to match a file 14287named @file{foo bar} (it also matches @file{fooxbar} 14288and the like). Also note that there is currently no 14289way to specify comments. 14290@c FIXCVS? I don't _like_ this syntax at all, but 14291@c changing it raises all the usual compatibility 14292@c issues and I'm also not sure what to change it to. 14293 14294@node checkoutlist 14295@appendixsec The checkoutlist file 14296@cindex checkoutlist 14297 14298It may be helpful to use @sc{cvs} to maintain your own 14299files in the @file{CVSROOT} directory. For example, 14300suppose that you have a script @file{logcommit.pl} 14301which you run by including the following line in the 14302@file{commitinfo} administrative file: 14303 14304@example 14305ALL $CVSROOT/CVSROOT/logcommit.pl %r/%p %s 14306@end example 14307 14308To maintain @file{logcommit.pl} with @sc{cvs} you would 14309add the following line to the @file{checkoutlist} 14310administrative file: 14311 14312@example 14313logcommit.pl 14314@end example 14315 14316The format of @file{checkoutlist} is one line for each 14317file that you want to maintain using @sc{cvs}, giving 14318the name of the file, followed optionally by more whitespace 14319and any error message that should print if the file cannot be 14320checked out into CVSROOT after a commit: 14321 14322@example 14323logcommit.pl Could not update CVSROOT/logcommit.pl. 14324@end example 14325 14326After setting up @file{checkoutlist} in this fashion, 14327the files listed there will function just like 14328@sc{cvs}'s built-in administrative files. For example, 14329when checking in one of the files you should get a 14330message such as: 14331 14332@example 14333cvs commit: Rebuilding administrative file database 14334@end example 14335 14336@noindent 14337and the checked out copy in the @file{CVSROOT} 14338directory should be updated. 14339 14340Note that listing @file{passwd} (@pxref{Password 14341authentication server}) in @file{checkoutlist} is not 14342recommended for security reasons. 14343 14344For information about keeping a checkout out copy in a 14345more general context than the one provided by 14346@file{checkoutlist}, see @ref{Keeping a checked out 14347copy}. 14348 14349@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14350@node history file 14351@appendixsec The history file 14352@cindex History file 14353@cindex Log information, saving 14354 14355By default, the file @file{$CVSROOT/CVSROOT/history} is used 14356to log information for the @code{history} command (@pxref{history}). 14357This file name may be changed with the @samp{HistoryLogPath} and 14358@samp{HistorySearchPath} config options (@pxref{config}). 14359 14360The file format of the @file{history} file is 14361documented only in comments in the @sc{cvs} source 14362code, but generally programs should use the @code{cvs 14363history} command to access it anyway, in case the 14364format changes with future releases of @sc{cvs}. 14365 14366@node Variables 14367@appendixsec Expansions in administrative files 14368@cindex Internal variables 14369@cindex Variables 14370 14371Sometimes in writing an administrative file, you might 14372want the file to be able to know various things based 14373on environment @sc{cvs} is running in. There are 14374several mechanisms to do that. 14375 14376To find the home directory of the user running @sc{cvs} 14377(from the @code{HOME} environment variable), use 14378@samp{~} followed by @samp{/} or the end of the line. 14379Likewise for the home directory of @var{user}, use 14380@samp{~@var{user}}. These variables are expanded on 14381the server machine, and don't get any reasonable 14382expansion if pserver (@pxref{Password authenticated}) 14383is in use; therefore user variables (see below) may be 14384a better choice to customize behavior based on the user 14385running @sc{cvs}. 14386@c Based on these limitations, should we deprecate ~? 14387@c What is it good for? Are people using it? 14388 14389One may want to know about various pieces of 14390information internal to @sc{cvs}. A @sc{cvs} internal 14391variable has the syntax @code{$@{@var{variable}@}}, 14392where @var{variable} starts with a letter and consists 14393of alphanumeric characters and @samp{_}. If the 14394character following @var{variable} is a 14395non-alphanumeric character other than @samp{_}, the 14396@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 14397internal variables are: 14398 14399@table @code 14400@item CVSROOT 14401@cindex CVSROOT, internal variable 14402This is the absolute path to the current @sc{cvs} root directory. 14403@xref{Repository}, for a description of the various 14404ways to specify this, but note that the internal 14405variable contains just the directory and not any 14406of the access method information. 14407 14408@item RCSBIN 14409@cindex RCSBIN, internal variable 14410In @sc{cvs} 1.9.18 and older, this specified the 14411directory where @sc{cvs} was looking for @sc{rcs} 14412programs. Because @sc{cvs} no longer runs @sc{rcs} 14413programs, specifying this internal variable is now an 14414error. 14415 14416@item CVSEDITOR 14417@cindex CVSEDITOR, internal variable 14418@itemx EDITOR 14419@cindex EDITOR, internal variable 14420@itemx VISUAL 14421@cindex VISUAL, internal variable 14422These all expand to the same value, which is the editor 14423that @sc{cvs} is using. @xref{Global options}, for how 14424to specify this. 14425 14426@item USER 14427@cindex USER, internal variable 14428Username of the user running @sc{cvs} (on the @sc{cvs} 14429server machine). 14430When using pserver, this is the user specified in the repository 14431specification which need not be the same as the username the 14432server is running as (@pxref{Password authentication server}). 14433Do not confuse this with the environment variable of the same name. 14434 14435@item SESSIONID 14436@cindex COMMITID, internal variable 14437Unique Session ID of the @sc{cvs} process. This is a 14438random string of printable characters of at least 16 14439characters length. Users should assume that it may 14440someday grow to at most 256 characters in length. 14441 14442@item COMMITID 14443@cindex COMMITID, internal variable 14444Unique Session ID of the @sc{cvs} process. This is a 14445random string of printable characters of at least 16 14446characters length. Users should assume that it may 14447someday grow to at most 256 characters in length. 14448@end table 14449 14450If you want to pass a value to the administrative files 14451which the user who is running @sc{cvs} can specify, 14452use a user variable. 14453@cindex User variables 14454To expand a user variable, the 14455administrative file contains 14456@code{$@{=@var{variable}@}}. To set a user variable, 14457specify the global option @samp{-s} to @sc{cvs}, with 14458argument @code{@var{variable}=@var{value}}. It may be 14459particularly useful to specify this option via 14460@file{.cvsrc} (@pxref{~/.cvsrc}). 14461 14462For example, if you want the administrative file to 14463refer to a test directory you might create a user 14464variable @code{TESTDIR}. Then if @sc{cvs} is invoked 14465as 14466 14467@example 14468cvs -s TESTDIR=/work/local/tests 14469@end example 14470 14471@noindent 14472and the 14473administrative file contains @code{sh 14474$@{=TESTDIR@}/runtests}, then that string is expanded 14475to @code{sh /work/local/tests/runtests}. 14476 14477All other strings containing @samp{$} are reserved; 14478there is no way to quote a @samp{$} character so that 14479@samp{$} represents itself. 14480 14481Environment variables passed to administrative files are: 14482 14483@table @code 14484@cindex environment variables, passed to administrative files 14485 14486@item CVS_USER 14487@cindex CVS_USER, environment variable 14488The @sc{cvs}-specific username provided by the user, if it 14489can be provided (currently just for the pserver access 14490method), and to the empty string otherwise. (@code{CVS_USER} 14491and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 14492is used to map @sc{cvs} usernames to system usernames.) 14493 14494@item LOGNAME 14495@cindex LOGNAME, environment variable 14496The username of the system user. 14497 14498@item USER 14499@cindex USER, environment variable 14500Same as @code{LOGNAME}. 14501Do not confuse this with the internal variable of the same name. 14502@end table 14503 14504@node config 14505@appendixsec The CVSROOT/config configuration file 14506 14507@cindex configuration file 14508@cindex config, in CVSROOT 14509@cindex CVSROOT/config 14510 14511Usually, the @file{config} file is found at @file{$CVSROOT/CVSROOT/config}, 14512but this may be overridden on the @code{pserver} and @code{server} command 14513lines (@pxref{server & pserver}). 14514 14515The administrative file @file{config} contains various 14516miscellaneous settings which affect the behavior of 14517@sc{cvs}. The syntax is slightly different from the 14518other administrative files. 14519 14520Leading white space on any line is ignored, though the syntax is very strict 14521and will reject spaces and tabs almost anywhere else. 14522 14523Empty lines, lines containing nothing but white space, and lines which start 14524with @samp{#} (discounting any leading white space) are ignored. 14525 14526@c FIXME: where do we define comments for the other 14527@c administrative files. 14528Other lines consist of the optional leading white space, a keyword, @samp{=}, 14529and a value. Please note again that this syntax is very strict. 14530Extraneous spaces or tabs, other than the leading white space, are not 14531permitted on these lines. 14532@c See comments in parseinfo.c:parse_config for more 14533@c discussion of this strictness. 14534 14535As of CVS 1.12.13, lines of the form @samp{[@var{CVSROOT}]} mark the subsequent 14536section of the config file as applying only to certain repositories. Multiple 14537@samp{[@var{CVSROOT}]} lines without intervening 14538@samp{@var{KEYWORD}=@var{VALUE}} pairs cause processing to fall through, 14539processing subsequent keywords for any root in the list. Finally, keywords 14540and values which appear before any @samp{[@var{CVSROOT}]} lines are defaults, 14541and may to apply to any repository. For example, consider the following file: 14542 14543@example 14544# Defaults 14545LogHistory=TMAR 14546 14547[/cvsroots/team1] 14548 LockDir=/locks/team1 14549 14550[/cvsroots/team2] 14551 LockDir=/locks/team2 14552 14553[/cvsroots/team3] 14554 LockDir=/locks/team3 14555 14556[/cvsroots/team4] 14557 LockDir=/locks/team4 14558 14559[/cvsroots/team3] 14560[/cvsroots/team4] 14561 # Override logged commands for teams 3 & 4. 14562 LogHistory=all 14563@end example 14564 14565This example file sets up separate lock directories for each project, as well 14566as a default set of logged commands overridden for the example's team 3 & 14567team 4. This syntax could be useful, for instance, if you wished to share a 14568single config file, for instance @file{/etc/cvs.conf}, among several 14569repositories. 14570 14571Currently defined keywords are: 14572 14573@table @code 14574@cindex HistoryLogPath, in CVSROOT/config 14575@item HistorySearchPath=@var{pattern} 14576Request that @sc{cvs} look for its history information in files matching 14577@var{pattern}, which is a standard UNIX file glob. If @var{pattern} matches 14578multiple files, all will be searched in lexicographically sorted order. 14579@xref{history}, and @ref{history file}, for more. 14580 14581If no value is supplied for this option, it defaults to 14582@file{$CVSROOT/CVSROOT/history}. 14583 14584@cindex HistorySearchPath, in CVSROOT/config 14585@item HistoryLogPath=@var{path} 14586Control where @sc{cvs} logs its history. If the file does not exist, @sc{cvs} 14587will attempt to create it. Format strings, as available to the GNU C 14588@code{strftime} function and often the UNIX date command, and the string 14589@var{$CVSROOT} will be substituted in this path. For example, consider the 14590line: 14591 14592@example 14593HistoryLogPath=$CVSROOT/CVSROOT/history/%Y-%m-%d 14594@end example 14595 14596This line would cause @sc{cvs} to attempt to create its history file in a 14597subdirectory (@file{history}) of the configuration directory (@file{CVSROOT}) 14598with a name equal to the current date representation in the ISO8601 format (for 14599example, on May 11, 2005, @sc{cvs} would attempt to log its history under the 14600repository root directory in a file named @file{CVSROOT/history/2005-05-11}). 14601@xref{history}, and @ref{history file}, for more. 14602 14603If no value is supplied for this option, it defaults to 14604@file{$CVSROOT/CVSROOT/history}. 14605 14606@cindex ImportNewFilesToVendorBranchOnly, in CVSROOT/config 14607@cindex import, config admin file 14608@cindex config (admin file), import 14609@item ImportNewFilesToVendorBranchOnly=@var{value} 14610Specify whether @code{cvs import} should always behave as if the 14611@samp{-X} flag was specified on the command line. 14612@var{value} may be either @samp{yes} or @samp{no}. If set to @samp{yes}, 14613all uses of @code{cvs import} on the repository will behave as if the 14614@samp{-X} flag was set. The default value is @samp{no}. 14615 14616@cindex KeywordExpand, in CVSROOT/config 14617@item KeywordExpand=@var{value} 14618Specify @samp{i} followed by a list of keywords to be expanded 14619(for example, @samp{KeywordExpand=iMYCVS,Name,Date}), 14620or @samp{e} followed by a list of keywords not to be expanded 14621(for example, @samp{KeywordExpand=eCVSHeader}). 14622For more on keyword expansion, see @ref{Configuring keyword expansion}. 14623 14624@cindex LocalKeyword, in CVSROOT/config 14625@item LocalKeyword=@var{value} 14626Specify a local alias for a standard keyword. 14627For example, @samp{LocalKeyword=MYCVS=CVSHeader}. 14628For more on local keywords, see @ref{Keyword substitution}. 14629 14630@cindex LockDir, in CVSROOT/config 14631@item LockDir=@var{directory} 14632Put @sc{cvs} lock files in @var{directory} rather than 14633directly in the repository. This is useful if you want 14634to let users read from the repository while giving them 14635write access only to @var{directory}, not to the 14636repository. 14637It can also be used to put the locks on a very fast 14638in-memory file system to speed up locking and unlocking 14639the repository. 14640You need to create @var{directory}, but 14641@sc{cvs} will create subdirectories of @var{directory} as it 14642needs them. For information on @sc{cvs} locks, see 14643@ref{Concurrency}. 14644 14645@c Mention this in Compatibility section? 14646Before enabling the LockDir option, make sure that you 14647have tracked down and removed any copies of @sc{cvs} 1.9 or 14648older. Such versions neither support LockDir, nor will 14649give an error indicating that they don't support it. 14650The result, if this is allowed to happen, is that some 14651@sc{cvs} users will put the locks one place, and others will 14652put them another place, and therefore the repository 14653could become corrupted. @sc{cvs} 1.10 does not support 14654LockDir but it will print a warning if run on a 14655repository with LockDir enabled. 14656 14657@cindex LogHistory, in CVSROOT/config 14658@item LogHistory=@var{value} 14659Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). 14660Default of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log 14661all transactions. Any subset of the default is 14662legal. (For example, to only log transactions that modify the 14663@file{*,v} files, use @samp{LogHistory=TMAR}.) To disable history logging 14664completely, use @samp{LogHistory=}. 14665 14666@cindex MaxCommentLeaderLength, in CVSROOT/config 14667@cindex Log keyword, configuring substitution behavior 14668@item MaxCommentLeaderLength=@var{length} 14669Set to some length, in bytes, where a trailing @samp{k}, @samp{M}, @samp{G}, 14670or @samp{T} causes the preceding nubmer to be interpreted as kilobytes, 14671megabytes, gigabytes, or terrabytes, respectively, will cause 14672@code{$@splitrcskeyword{Log}$} keywords (@pxref{Keyword substitution}), with 14673more than @var{length} bytes preceding it on a line to be ignored (or to fall 14674back on the comment leader set in the RCS archive file - see 14675@code{UseArchiveCommentLeader} below). Defaults to 20 bytes to allow checkouts 14676to proceed normally when they include binary files containing 14677@code{$@splitrcskeyword{Log}$} keywords and which users have neglected to mark 14678as binary. 14679 14680@cindex MinCompressionLevel, in CVSROOT/config 14681@cindex MaxCompressionLevel, in CVSROOT/config 14682@cindex Compression levels, restricting on server 14683@item MinCompressionLevel=@var{value} 14684@itemx MaxCompressionLevel=@var{value} 14685Restricts the level of compression used by the @sc{cvs} server to a @var{value} 14686between 0 and 9. @var{value}s 1 through 9 are the same @sc{zlib} compression 14687levels accepted by the @samp{-z} option (@pxref{Global options}), and 0 means 14688no compression. When one or both of these keys are set and a client requests a 14689level outside the specified range, the server will simply use the closest 14690permissable level. Clients will continue compressing at the level requested by 14691the user. 14692 14693The exception is when level 0 (no compression) is not available and the client 14694fails to request any compression. The @sc{cvs} server will then exit with an 14695error message when it becomes apparent that the client is not going to request 14696compression. This will not happen with clients version 1.12.13 and later since 14697these client versions allow the server to notify them that they must request 14698some level of compression. 14699 14700@ignore 14701@cindex PreservePermissions, in CVSROOT/config 14702@item PreservePermissions=@var{value} 14703Enable support for saving special device files, 14704symbolic links, file permissions and ownerships in the 14705repository. The default value is @samp{no}. 14706@xref{Special Files}, for the full implications of using 14707this keyword. 14708@end ignore 14709 14710@cindex PrimaryServer, in CVSROOT/config 14711@cindex Primary server 14712@cindex Secondary server 14713@cindex proxy, write 14714@cindex write proxy 14715@item PrimaryServer=@var{CVSROOT} 14716When specified, and the repository specified by @var{CVSROOT} is not the one 14717currently being accessed, then the server will turn itself into a transparent 14718proxy to @var{CVSROOT} for write requests. The @var{hostname} configured as 14719part of @var{CVSROOT} must resolve to the same string returned by the 14720@command{uname} command on the primary server for this to work. Host name 14721resolution is performed via some combination of @command{named}, a broken out 14722line from @file{/etc/hosts}, and the Network Information Service (NIS or YP), 14723depending on the configuration of the particular system. 14724 14725Only the @samp{:ext:} method is 14726currently supported for primaries (actually, @samp{:fork:} is supported as 14727well, but only for testing - if you find another use for accessing a primary 14728via the @samp{:fork:} method, please send a note to @email{bug-cvs@@nongnu.org} 14729about it). See @ref{Write proxies} for more on configuring and using write 14730proxies. 14731 14732@cindex RCSBIN, in CVSROOT/config 14733@item RCSBIN=@var{bindir} 14734For @sc{cvs} 1.9.12 through 1.9.18, this setting told 14735@sc{cvs} to look for @sc{rcs} programs in the 14736@var{bindir} directory. Current versions of @sc{cvs} 14737do not run @sc{rcs} programs; for compatibility this 14738setting is accepted, but it does nothing. 14739 14740@cindex RereadLogAfterVerify, in CVSROOT/config 14741@cindex @file{verifymsg}, changing the log message 14742@item RereadLogAfterVerify=@var{value} 14743Modify the @samp{commit} command such that CVS will reread the 14744log message after running the program specified by @file{verifymsg}. 14745@var{value} may be one of @samp{yes} or @samp{always}, indicating that 14746the log message should always be reread; @samp{no} 14747or @samp{never}, indicating that it should never be 14748reread; or @var{value} may be @samp{stat}, indicating 14749that the file should be checked with the file system 14750@samp{stat()} function to see if it has changed (see warning below) 14751before rereading. The default value is @samp{always}. 14752 14753@strong{Note: the `stat' mode can cause CVS to pause for up to 14754one extra second per directory committed. This can be less IO and 14755CPU intensive but is not recommended for use with large repositories} 14756 14757@xref{verifymsg}, for more information on how verifymsg 14758may be used. 14759 14760@cindex SystemAuth, in CVSROOT/config 14761@item SystemAuth=@var{value} 14762If @var{value} is @samp{yes}, then pserver should check 14763for users in the system's user database if not found in 14764@file{CVSROOT/passwd}. If it is @samp{no}, then all 14765pserver users must exist in @file{CVSROOT/passwd}. 14766The default is @samp{yes}. For more on pserver, see 14767@ref{Password authenticated}. 14768 14769@cindex TmpDir, in config 14770@cindex temporary files, location of 14771@cindex temporary directory, set in config 14772@item TmpDir=@var{path} 14773Specify @var{path} as the directory to create temporary files in. 14774@xref{Global options}, for more on setting the path to the temporary 14775directory. This option first appeared with @sc{cvs} release 1.12.13. 14776 14777@cindex TopLevelAdmin, in CVSROOT/config 14778@item TopLevelAdmin=@var{value} 14779Modify the @samp{checkout} command to create a 14780@samp{CVS} directory at the top level of the new 14781working directory, in addition to @samp{CVS} 14782directories created within checked-out directories. 14783The default value is @samp{no}. 14784 14785This option is useful if you find yourself performing 14786many commands at the top level of your working 14787directory, rather than in one of the checked out 14788subdirectories. The @file{CVS} directory created there 14789will mean you don't have to specify @code{CVSROOT} for 14790each command. It also provides a place for the 14791@file{CVS/Template} file (@pxref{Working directory 14792storage}). 14793 14794@cindex UseArchiveCommentLeader, in CVSROOT/config 14795@cindex Log keyword, configuring substitution behavior 14796@item UseArchiveCommentLeader=@var{value} 14797Set to @code{true}, if the text preceding a @code{$@splitrcskeyword{Log}$} 14798keyword is found to exceed @code{MaxCommentLeaderLength} (above) bytes, then 14799the comment leader set in the RCS archive file (@pxref{admin}), if any, will 14800be used instead. If there is no comment leader set in the archive file or 14801@var{value} is set to @samp{false}, then the keyword will not be expanded 14802(@pxref{Keyword list}). To force the comment leader in the RCS archive file to 14803be used exclusively (and @code{$@splitrcskeyword{Log}$} expansion skipped in 14804files where the comment leader has not been set in the archive file), set 14805@var{value} and set @code{MaxCommentLeaderLength} to @code{0}. 14806 14807@cindex UseNewInfoFmtStrings, in CVSROOT/config 14808@cindex format strings, config admin file 14809@cindex config (admin file), updating legacy repositories 14810@cindex compatibility notes, config admin file 14811@item UseNewInfoFmtStrings=@var{value} 14812Specify whether @sc{cvs} should support the new or old command line 14813template model for the commit support files (@pxref{commit files}). 14814This configuration variable began life in deprecation and is only here 14815in order to give people time to update legacy repositories to use the new 14816format string syntax before support for the old syntax is removed. For 14817information on updating your repository to support the new model, 14818please see @ref{Updating Commit Files}. 14819 14820@emph{Note that new repositories (created with the @code{cvs init} command) 14821will have this value set to @samp{yes}, but the default value is @samp{no}.} 14822 14823@cindex UserAdminOptions, in CVSROOT/config 14824@item UserAdminOptions=@var{value} 14825Control what options will be allowed with the @code{cvs admin} 14826command (@pxref{admin}) for users not in the @code{cvsadmin} group. 14827The @var{value} string is a list of single character options 14828which should be allowed. If a user who is not a member of the 14829@code{cvsadmin} group tries to execute any @code{cvs admin} 14830option which is not listed they will will receive an error message 14831reporting that the option is restricted. 14832 14833If no @code{cvsadmin} group exists on the server, @sc{cvs} will 14834ignore the @code{UserAdminOptions} keyword (@pxref{admin}). 14835 14836When not specified, @code{UserAdminOptions} defaults to 14837@samp{k}. In other words, it defaults to allowing 14838users outside of the @code{cvsadmin} group to use the 14839@code{cvs admin} command only to change the default keyword 14840expansion mode for files. 14841 14842As an example, to restrict users not in the @code{cvsadmin} 14843group to using @code{cvs admin} to change the default keyword 14844substitution mode, lock revisions, unlock revisions, and 14845replace the log message, use @samp{UserAdminOptions=klum}. 14846@end table 14847 14848 14849 14850@c --------------------------------------------------------------------- 14851@node Environment variables 14852@appendix All environment variables which affect CVS 14853@cindex Environment variables 14854@cindex Reference manual for variables 14855 14856This is a complete list of all environment variables 14857that affect @sc{cvs} (Windows users, please bear with this list; 14858$VAR is equivalent to %VAR% at the Windows command prompt). 14859 14860@table @code 14861@cindex CVSIGNORE, environment variable 14862@item $CVSIGNORE 14863A whitespace-separated list of file name patterns that 14864@sc{cvs} should ignore. @xref{cvsignore}. 14865 14866@cindex CVSWRAPPERS, environment variable 14867@item $CVSWRAPPERS 14868A whitespace-separated list of file name patterns that 14869@sc{cvs} should treat as wrappers. @xref{Wrappers}. 14870 14871@cindex CVSREAD, environment variable 14872@cindex Read-only files, and CVSREAD 14873@item $CVSREAD 14874If this is set, @code{checkout} and @code{update} will 14875try hard to make the files in your working directory 14876read-only. When this is not set, the default behavior 14877is to permit modification of your working files. 14878 14879@cindex CVSREADONLYFS, environment variable 14880@item $CVSREADONLYFS 14881Turns on read-only repository mode. This allows one to 14882check out from a read-only repository, such as within 14883an anoncvs server, or from a @sc{cd-rom} repository. 14884 14885It has the same effect as if the @samp{-R} command-line 14886option is used. This can also allow the use of 14887read-only NFS repositories. 14888 14889@item $CVSUMASK 14890Controls permissions of files in the repository. See 14891@ref{File permissions}. 14892 14893@item $CVSROOT 14894Should contain the full pathname to the root of the @sc{cvs} 14895source repository (where the @sc{rcs} files are 14896kept). This information must be available to @sc{cvs} for 14897most commands to execute; if @code{$CVSROOT} is not set, 14898or if you wish to override it for one invocation, you 14899can supply it on the command line: @samp{cvs -d cvsroot 14900cvs_command@dots{}} Once you have checked out a working 14901directory, @sc{cvs} stores the appropriate root (in 14902the file @file{CVS/Root}), so normally you only need to 14903worry about this when initially checking out a working 14904directory. 14905 14906@item $CVSEDITOR 14907@cindex CVSEDITOR, environment variable 14908@itemx $EDITOR 14909@cindex EDITOR, environment variable 14910@itemx $VISUAL 14911@cindex VISUAL, environment variable 14912Specifies the program to use for recording log messages 14913during commit. @code{$CVSEDITOR} overrides 14914@code{$EDITOR}, which overrides @code{$VISUAL}. 14915See @ref{Committing your changes} for more or 14916@ref{Global options} for alternative ways of specifying a 14917log editor. 14918 14919@cindex PATH, environment variable 14920@item $PATH 14921If @code{$RCSBIN} is not set, and no path is compiled 14922into @sc{cvs}, it will use @code{$PATH} to try to find all 14923programs it uses. 14924 14925@cindex HOME, environment variable 14926@item $HOME 14927@cindex HOMEPATH, environment variable 14928@item $HOMEPATH 14929@cindex HOMEDRIVE, environment variable 14930@item $HOMEDRIVE 14931Used to locate the directory where the @file{.cvsrc} 14932file, and other such files, are searched. On Unix, @sc{cvs} 14933just checks for @code{HOME}. On Windows NT, the system will 14934set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 14935for example to @file{\joe}. On Windows 95, you'll 14936probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 14937@c We are being vague about whether HOME works on 14938@c Windows; see long comment in windows-NT/filesubr.c. 14939 14940@cindex CVS_RSH, environment variable 14941@item $CVS_RSH 14942Specifies the external program which @sc{cvs} connects with, 14943when @code{:ext:} access method is specified. 14944@pxref{Connecting via rsh}. 14945 14946@item $CVS_SERVER 14947Used in client-server mode when accessing a remote 14948repository using @sc{rsh}. It specifies the name of 14949the program to start on the server side (and any 14950necessary arguments) when accessing a remote repository 14951using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 14952The default value for @code{:ext:} and @code{:server:} is @code{cvs}; 14953the default value for @code{:fork:} is the name used to run the client. 14954@pxref{Connecting via rsh} 14955 14956@item $CVS_PASSFILE 14957Used in client-server mode when accessing the @code{cvs 14958login server}. Default value is @file{$HOME/.cvspass}. 14959@pxref{Password authentication client} 14960 14961@cindex CVS_CLIENT_PORT 14962@item $CVS_CLIENT_PORT 14963Used in client-server mode to set the port to use when accessing the server 14964via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 14965if the port is not specified in the CVSROOT. 14966@pxref{Remote repositories} 14967 14968@cindex CVS_PROXY_PORT 14969@item $CVS_PROXY_PORT 14970Used in client-server mode to set the port to use when accessing a server 14971via a web proxy, if the port is not specified in the CVSROOT. Works with 14972GSSAPI, and the password authentication protocol. 14973@pxref{Remote repositories} 14974 14975@cindex CVS_RCMD_PORT, environment variable 14976@item $CVS_RCMD_PORT 14977Used in client-server mode. If set, specifies the port 14978number to be used when accessing the @sc{rcmd} demon on 14979the server side. (Currently not used for Unix clients). 14980 14981@cindex CVS_CLIENT_LOG, environment variable 14982@item $CVS_CLIENT_LOG 14983Used for debugging only in client-server 14984mode. If set, everything sent to the server is logged 14985into @file{@code{$CVS_CLIENT_LOG}.in} and everything 14986sent from the server is logged into 14987@file{@code{$CVS_CLIENT_LOG}.out}. 14988 14989@cindex CVS_SERVER_SLEEP, environment variable 14990@item $CVS_SERVER_SLEEP 14991Used only for debugging the server side in 14992client-server mode. If set, delays the start of the 14993server child process the specified amount of 14994seconds so that you can attach to it with a debugger. 14995 14996@cindex CVS_IGNORE_REMOTE_ROOT, environment variable 14997@item $CVS_IGNORE_REMOTE_ROOT 14998For @sc{cvs} 1.10 and older, setting this variable 14999prevents @sc{cvs} from overwriting the @file{CVS/Root} 15000file when the @samp{-d} global option is specified. 15001Later versions of @sc{cvs} do not rewrite 15002@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 15003effect. 15004 15005@cindex CVS_LOCAL_BRANCH_NUM, environment variable 15006@item $CVS_LOCAL_BRANCH_NUM 15007Setting this variable allows some control over the 15008branch number that is assigned. This is specifically to 15009support the local commit feature of CVSup. If one sets 15010@code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches 15011the local repository, the revision numbers will look 15012like 1.66.1000.xx. There is almost a dead-set certainty 15013that there will be no conflicts with version numbers. 15014 15015@cindex COMSPEC, environment variable 15016@item $COMSPEC 15017Used under OS/2 only. It specifies the name of the 15018command interpreter and defaults to @sc{cmd.exe}. 15019 15020@cindex TMPDIR, environment variable 15021@cindex temporary file directory, set via environment variable 15022@cindex temporary files, location of 15023@item $TMPDIR 15024Directory in which temporary files are located. 15025@xref{Global options}, for more on setting the temporary directory. 15026 15027@cindex CVS_PID, environment variable 15028@item $CVS_PID 15029This is the process identification (aka pid) number of 15030the @sc{cvs} process. It is often useful in the 15031programs and/or scripts specified by the 15032@file{commitinfo}, @file{verifymsg}, @file{loginfo} 15033files. 15034@end table 15035 15036@node Compatibility 15037@appendix Compatibility between CVS Versions 15038 15039@cindex CVS, versions of 15040@cindex Versions, of CVS 15041@cindex Compatibility, between CVS versions 15042@c We don't mention versions older than CVS 1.3 15043@c on the theory that it would clutter it up for the vast 15044@c majority of people, who don't have anything that old. 15045@c 15046The repository format is compatible going back to 15047@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 15048you have copies of @sc{cvs} 1.6 or older and you want 15049to use the optional developer communication features. 15050@c If you "cvs rm" and commit using 1.3, then you'll 15051@c want to run "rcs -sdead <file,v>" on each of the 15052@c files in the Attic if you then want 1.5 and 15053@c later to recognize those files as dead (I think the 15054@c symptom if this is not done is that files reappear 15055@c in joins). (Wait: the above will work but really to 15056@c be strictly correct we should suggest checking 15057@c in a new revision rather than just changing the 15058@c state of the head revision, shouldn't we?). 15059@c The old convert.sh script was for this, but it never 15060@c did get updated to reflect use of the RCS "dead" 15061@c state. 15062@c Note: this is tricky to document without confusing 15063@c people--need to carefully say what CVS version we 15064@c are talking about and keep in mind the distinction 15065@c between a 15066@c repository created with 1.3 and on which one now 15067@c uses 1.5+, and a repository on which one wants to 15068@c use both versions side by side (e.g. during a 15069@c transition period). 15070@c Wait, can't CVS just detect the case in which a file 15071@c is in the Attic but the head revision is not dead? 15072@c Not sure whether this should produce a warning or 15073@c something, and probably needs further thought, but 15074@c it would appear that the situation can be detected. 15075@c 15076@c We might want to separate out the 1.3 compatibility 15077@c section (for repository & working directory) from the 15078@c rest--that might help avoid confusing people who 15079@c are upgrading (for example) from 1.6 to 1.8. 15080@c 15081@c A minor incompatibility is if a current version of CVS 15082@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 15083@c see this as if there is no tag. Seems to me this is 15084@c too obscure to mention. 15085 15086The working directory format is compatible going back 15087to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 15088and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 15089a working directory checked out with @sc{cvs} 1.3, 15090@sc{cvs} will convert it, but to go back to @sc{cvs} 150911.3 you need to check out a new working directory with 15092@sc{cvs} 1.3. 15093 15094The remote protocol is interoperable going back to @sc{cvs} 1.5, but no 15095further (1.5 was the first official release with the remote protocol, 15096but some older versions might still be floating around). In many 15097cases you need to upgrade both the client and the server to take 15098advantage of new features and bug fixes, however. 15099 15100@c Perhaps should be saying something here about the 15101@c "D" lines in Entries (written by CVS 1.9; 1.8 and 15102@c older don't use them). These are supposed to be 15103@c compatible in both directions, but I'm not sure 15104@c they quite are 100%. One common gripe is if you 15105@c "rm -r" a directory and 1.9 gets confused, as it 15106@c still sees it in Entries. That one is fixed in 15107@c (say) 1.9.6. Someone else reported problems with 15108@c starting with a directory which was checked out with 15109@c an old version, and then using a new version, and 15110@c some "D" lines appeared, but not for every 15111@c directory, causing some directories to be skipped. 15112@c They weren't sure how to reproduce this, though. 15113 15114@c --------------------------------------------------------------------- 15115@node Troubleshooting 15116@appendix Troubleshooting 15117 15118If you are having trouble with @sc{cvs}, this appendix 15119may help. If there is a particular error message which 15120you are seeing, then you can look up the message 15121alphabetically. If not, you can look through the 15122section on other problems to see if your problem is 15123mentioned there. 15124 15125@menu 15126* Error messages:: Partial list of CVS errors 15127* Connection:: Trouble making a connection to a CVS server 15128* Other problems:: Problems not readily listed by error message 15129@end menu 15130 15131@ignore 15132@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 15133@c @node Bad administrative files 15134@appendixsec Bad administrative files 15135 15136@c -- Give hints on how to fix them 15137@end ignore 15138 15139@node Error messages 15140@appendixsec Partial list of error messages 15141 15142Here is a partial list of error messages that you may 15143see from @sc{cvs}. It is not a complete list---@sc{cvs} 15144is capable of printing many, many error messages, often 15145with parts of them supplied by the operating system, 15146but the intention is to list the common and/or 15147potentially confusing error messages. 15148 15149The messages are alphabetical, but introductory text 15150such as @samp{cvs update: } is not considered in 15151ordering them. 15152 15153In some cases the list includes messages printed by old 15154versions of @sc{cvs} (partly because users may not be 15155sure which version of @sc{cvs} they are using at any 15156particular moment). 15157@c If we want to start retiring messages, perhaps we 15158@c should pick a cutoff version (for example, no more 15159@c messages which are specific to versions before 1.9) 15160@c and then move the old messages to an "old messages" 15161@c node rather than deleting them completely. 15162 15163@table @code 15164@c FIXME: What is the correct way to format a multiline 15165@c error message here? Maybe @table is the wrong 15166@c choice? Texinfo gurus? 15167@item @var{file}:@var{line}: Assertion '@var{text}' failed 15168The exact format of this message may vary depending on 15169your system. It indicates a bug in @sc{cvs}, which can 15170be handled as described in @ref{BUGS}. 15171 15172@item cvs @var{command}: authorization failed: server @var{host} rejected access 15173This is a generic response when trying to connect to a 15174pserver server which chooses not to provide a 15175specific reason for denying authorization. Check that 15176the username and password specified are correct and 15177that the @code{CVSROOT} specified is allowed by @samp{--allow-root} 15178in @file{inetd.conf}. See @ref{Password authenticated}. 15179 15180@item cvs @var{command}: conflict: removed @var{file} was modified by second party 15181This message indicates that you removed a file, and 15182someone else modified it. To resolve the conflict, 15183first run @samp{cvs add @var{file}}. If desired, look 15184at the other party's modification to decide whether you 15185still want to remove it. If you don't want to remove 15186it, stop here. If you do want to remove it, proceed 15187with @samp{cvs remove @var{file}} and commit your 15188removal. 15189@c Tests conflicts2-142b* in sanity.sh test for this. 15190 15191@item cannot change permissions on temporary directory 15192@example 15193Operation not permitted 15194@end example 15195This message has been happening in a non-reproducible, 15196occasional way when we run the client/server testsuite, 15197both on Red Hat Linux 3.0.3 and 4.1. We haven't been 15198able to figure out what causes it, nor is it known 15199whether it is specific to Linux (or even to this 15200particular machine!). If the problem does occur on 15201other unices, @samp{Operation not permitted} would be 15202likely to read @samp{Not owner} or whatever the system 15203in question uses for the unix @code{EPERM} error. If 15204you have any information to add, please let us know as 15205described in @ref{BUGS}. If you experience this error 15206while using @sc{cvs}, retrying the operation which 15207produced it should work fine. 15208@c This has been seen in a variety of tests, including 15209@c multibranch-2, multibranch-5, and basic1-24-rm-rm, 15210@c so it doesn't seem particularly specific to any one 15211@c test. 15212 15213@item cvs [server aborted]: Cannot check out files into the repository itself 15214The obvious cause for this message (especially for 15215non-client/server @sc{cvs}) is that the @sc{cvs} root 15216is, for example, @file{/usr/local/cvsroot} and you try 15217to check out files when you are in a subdirectory, such 15218as @file{/usr/local/cvsroot/test}. However, there is a 15219more subtle cause, which is that the temporary 15220directory on the server is set to a subdirectory of the 15221root (which is also not allowed). If this is the 15222problem, set the temporary directory to somewhere else, 15223for example @file{/var/tmp}; see @code{TMPDIR} in 15224@ref{Environment variables}, for how to set the 15225temporary directory. 15226 15227@item cannot commit files as 'root' 15228See @samp{'root' is not allowed to commit files}. 15229 15230@c For one example see basica-1a10 in the testsuite 15231@c For another example, "cvs co ." on NT; see comment 15232@c at windows-NT/filesubr.c (expand_wild). 15233@c For another example, "cvs co foo/bar" where foo exists. 15234@item cannot open CVS/Entries for reading: No such file or directory 15235This generally indicates a @sc{cvs} internal error, and 15236can be handled as with other @sc{cvs} bugs 15237(@pxref{BUGS}). Usually there is a workaround---the 15238exact nature of which would depend on the situation but 15239which hopefully could be figured out. 15240 15241@c This is more obscure than it might sound; it only 15242@c happens if you run "cvs init" from a directory which 15243@c contains a CVS/Root file at the start. 15244@item cvs [init aborted]: cannot open CVS/Root: No such file or directory 15245This message is harmless. Provided it is not 15246accompanied by other errors, the operation has 15247completed successfully. This message should not occur 15248with current versions of @sc{cvs}, but it is documented 15249here for the benefit of @sc{cvs} 1.9 and older. 15250 15251@item cvs server: cannot open /root/.cvsignore: Permission denied 15252@itemx cvs [server aborted]: can't chdir(/root): Permission denied 15253See @ref{Connection}. 15254 15255@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 15256This message has been reported as intermittently 15257happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 15258unknown; if you know more about what causes it, let us 15259know as described in @ref{BUGS}. 15260 15261@item cvs [@var{command} aborted]: cannot start server via rcmd 15262This, unfortunately, is a rather nonspecific error 15263message which @sc{cvs} 1.9 will print if you are 15264running the @sc{cvs} client and it is having trouble 15265connecting to the server. Current versions of @sc{cvs} 15266should print a much more specific error message. If 15267you get this message when you didn't mean to run the 15268client at all, you probably forgot to specify 15269@code{:local:}, as described in @ref{Repository}. 15270 15271@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 15272@sc{cvs} 1.9 and older will print this message 15273when trying to check in a binary file if 15274@sc{rcs} is not correctly installed. Re-read the 15275instructions that came with your @sc{rcs} distribution 15276and the @sc{install} file in the @sc{cvs} 15277distribution. Alternately, upgrade to a current 15278version of @sc{cvs}, which checks in files itself 15279rather than via @sc{rcs}. 15280 15281@item cvs checkout: could not check out @var{file} 15282With @sc{cvs} 1.9, this can mean that the @code{co} program 15283(part of @sc{rcs}) returned a failure. It should be 15284preceded by another error message, however it has been 15285observed without another error message and the cause is 15286not well-understood. With the current version of @sc{cvs}, 15287which does not run @code{co}, if this message occurs 15288without another error message, it is definitely a @sc{cvs} 15289bug (@pxref{BUGS}). 15290@c My current suspicion is that the RCS in the rcs (not 15291@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 15292@c CD is bad (remains to be confirmed). 15293@c There is also a report of something which looks 15294@c very similar on SGI, Irix 5.2, so I dunno. 15295 15296@item cvs [login aborted]: could not find out home directory 15297This means that you need to set the environment 15298variables that @sc{cvs} uses to locate your home directory. 15299See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 15300@ref{Environment variables}. 15301 15302@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 15303@sc{cvs} 1.9 and older will print this message if there was 15304a problem finding the @code{rcsmerge} program. Make 15305sure that it is in your @code{PATH}, or upgrade to a 15306current version of @sc{cvs}, which does not require 15307an external @code{rcsmerge} program. 15308 15309@item cvs [update aborted]: could not patch @var{file}: No such file or directory 15310This means that there was a problem finding the 15311@code{patch} program. Make sure that it is in your 15312@code{PATH}. Note that despite appearances the message 15313is @emph{not} referring to whether it can find @var{file}. 15314If both the client and the server are running a current 15315version of @sc{cvs}, then there is no need for an 15316external patch program and you should not see this 15317message. But if either client or server is running 15318@sc{cvs} 1.9, then you need @code{patch}. 15319 15320@item cvs update: could not patch @var{file}; will refetch 15321This means that for whatever reason the client was 15322unable to apply a patch that the server sent. The 15323message is nothing to be concerned about, because 15324inability to apply the patch only slows things down and 15325has no effect on what @sc{cvs} does. 15326@c xref to update output. Or File status? 15327@c Or some place else that 15328@c explains this whole "patch"/P/Needs Patch thing? 15329 15330@item dying gasps from @var{server} unexpected 15331There is a known bug in the server for @sc{cvs} 1.9.18 15332and older which can cause this. For me, this was 15333reproducible if I used the @samp{-t} global option. It 15334was fixed by Andy Piper's 14 Nov 1997 change to 15335src/filesubr.c, if anyone is curious. 15336If you see the message, 15337you probably can just retry the operation which failed, 15338or if you have discovered information concerning its 15339cause, please let us know as described in @ref{BUGS}. 15340 15341@item end of file from server (consult above messages if any) 15342The most common cause for this message is if you are 15343using an external @code{rsh} program and it exited with 15344an error. In this case the @code{rsh} program should 15345have printed a message, which will appear before the 15346above message. For more information on setting up a 15347@sc{cvs} client and server, see @ref{Remote repositories}. 15348 15349@item cvs [update aborted]: EOF in key in RCS file @var{file},v 15350@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 15351This means that there is a syntax error in the given 15352@sc{rcs} file. Note that this might be true even if @sc{rcs} can 15353read the file OK; @sc{cvs} does more error checking of 15354errors in the RCS file. That is why you may see this 15355message when upgrading from @sc{cvs} 1.9 to @sc{cvs} 153561.10. The likely cause for the original corruption is 15357hardware, the operating system, or the like. Of 15358course, if you find a case in which @sc{cvs} seems to 15359corrupting the file, by all means report it, 15360(@pxref{BUGS}). 15361There are quite a few variations of this error message, 15362depending on exactly where in the @sc{rcs} file @sc{cvs} 15363finds the syntax error. 15364 15365@cindex mkmodules 15366@item cvs commit: Executing 'mkmodules' 15367This means that your repository is set up for a version 15368of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 153691.8 or later, the above message will be preceded by 15370 15371@example 15372cvs commit: Rebuilding administrative file database 15373@end example 15374 15375If you see both messages, the database is being rebuilt 15376twice, which is unnecessary but harmless. If you wish 15377to avoid the duplication, and you have no versions of 15378@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 15379every place it appears in your @code{modules} 15380file. For more information on the @code{modules} file, 15381see @ref{modules}. 15382 15383@c This message comes from "co", and I believe is 15384@c possible only with older versions of CVS which call 15385@c co. The problem with being able to create the bogus 15386@c RCS file still exists, though (and I think maybe 15387@c there is a different symptom(s) now). 15388@c FIXME: Would be nice to have a more exact wording 15389@c for this message. 15390@item missing author 15391Typically this can happen if you created an RCS file 15392with your username set to empty. @sc{cvs} will, bogusly, 15393create an illegal RCS file with no value for the author 15394field. The solution is to make sure your username is 15395set to a non-empty value and re-create the RCS file. 15396@c "make sure your username is set" is complicated in 15397@c and of itself, as there are the environment 15398@c variables the system login name, &c, and it depends 15399@c on the version of CVS. 15400 15401@item cvs [checkout aborted]: no such tag @var{tag} 15402This message means that @sc{cvs} isn't familiar with 15403the tag @var{tag}. Usually the root cause is that you have 15404mistyped a tag name. Ocassionally this can also occur because the 15405users creating tags do not have permissions to write to the 15406@file{CVSROOT/val-tags} file (@pxref{File permissions}, for more). 15407 15408Prior to @sc{cvs} version 1.12.10, there were a few relatively 15409obscure cases where a given tag could be created in an archive 15410file in the repository but @sc{cvs} would require the user to 15411@c Search sanity.sh for "no such tag" to see some of 15412@c the relatively obscure cases. 15413try a few other @sc{cvs} commands involving that tag 15414until one was found whch caused @sc{cvs} to update 15415@cindex CVSROOT/val-tags file, forcing tags into 15416@cindex val-tags file, forcing tags into 15417the @file{val-tags} file, at which point the originally failing command 15418would begin to work. This same method can be used to repair a @file{val-tags} 15419file that becomes out of date due to the permissions problem mentioned above. 15420This updating is only required once per tag - once a tag is listed in 15421@file{val-tags}, it stays there. 15422 15423Note that using @samp{tag -f} to not require tag matches did not and 15424does not override this check (@pxref{Common options}). 15425 15426@item *PANIC* administration files missing 15427This typically means that there is a directory named 15428@sc{cvs} but it does not contain the administrative files 15429which @sc{cvs} puts in a CVS directory. If the problem is 15430that you created a CVS directory via some mechanism 15431other than @sc{cvs}, then the answer is simple, use a name 15432other than @sc{cvs}. If not, it indicates a @sc{cvs} bug 15433(@pxref{BUGS}). 15434 15435@item rcs error: Unknown option: -x,v/ 15436This message will be followed by a usage message for 15437@sc{rcs}. It means that you have an old version of 15438@sc{rcs} (probably supplied with your operating 15439system), as well as an old version of @sc{cvs}. 15440@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 15441later; current versions of @sc{cvs} do not run @sc{rcs} programs. 15442@c For more information on installing @sc{cvs}, see 15443@c (FIXME: where? it depends on whether you are 15444@c getting binaries or sources or what). 15445@c The message can also say "ci error" or something 15446@c instead of "rcs error", I suspect. 15447 15448@item cvs [server aborted]: received broken pipe signal 15449This message can be caused by a loginfo program that fails to 15450read all of the log information from its standard input. 15451If you find it happening in any other circumstances, 15452please let us know as described in @ref{BUGS}. 15453 15454@item 'root' is not allowed to commit files 15455When committing a permanent change, @sc{cvs} makes a log entry of 15456who committed the change. If you are committing the change logged 15457in as "root" (not under "su" or other root-priv giving program), 15458@sc{cvs} cannot determine who is actually making the change. 15459As such, by default, @sc{cvs} disallows changes to be committed by users 15460logged in as "root". (You can disable this option by passing the 15461@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 15462On some systems this means editing the appropriate @file{config.h} file 15463before building @sc{cvs}.) 15464 15465@item cvs [server aborted]: Secondary out of sync with primary! 15466 15467This usually means that the version of @sc{cvs} running on a secondary 15468server is incompatible with the version running on the primary server 15469(@pxref{Write proxies}). 15470This will not occur if the client supports redirection. 15471 15472It is not the version number that is significant here, but the list of 15473supported requests that the servers provide to the client. 15474For example, even if both servers were the same version, 15475if the secondary was compiled with GSSAPI support and the primary was not, 15476the list of supported requests provided by the two servers 15477would be different and the secondary would not work as a transparent 15478proxy to the primary. 15479Conversely, even if the two servers were radically different versions 15480but both provided the same list of valid requests to the client, 15481the transparent proxy would succeed. 15482 15483@item Terminated with fatal signal 11 15484This message usually indicates that @sc{cvs} (the server, if you're 15485using client/server mode) has run out of (virtual) memory. 15486Although @sc{cvs} tries to catch the error and issue a more meaningful 15487message, there are many circumstances where that is not possible. 15488If you appear to have lots of memory available to the system, 15489the problem is most likely that you're running into a system-wide 15490limit on the amount of memory a single process can use or a 15491similar process-specific limit. 15492The mechanisms for displaying and setting such limits vary from 15493system to system, so you'll have to consult an expert for your 15494particular system if you don't know how to do that. 15495 15496@item Too many arguments! 15497This message is typically printed by the @file{log.pl} 15498script which is in the @file{contrib} directory in the 15499@sc{cvs} source distribution. In some versions of 15500@sc{cvs}, @file{log.pl} has been part of the default 15501@sc{cvs} installation. The @file{log.pl} script gets 15502called from the @file{loginfo} administrative file. 15503Check that the arguments passed in @file{loginfo} match 15504what your version of @file{log.pl} expects. In 15505particular, the @file{log.pl} from @sc{cvs} 1.3 and 15506older expects the log file as an argument whereas the 15507@file{log.pl} from @sc{cvs} 1.5 and newer expects the 15508log file to be specified with a @samp{-f} option. Of 15509course, if you don't need @file{log.pl} you can just 15510comment it out of @file{loginfo}. 15511 15512@item cvs [update aborted]: unexpected EOF reading @var{file},v 15513See @samp{EOF in key in RCS file}. 15514 15515@item cvs [login aborted]: unrecognized auth response from @var{server} 15516This message typically means that the server is not set 15517up properly. For example, if @file{inetd.conf} points 15518to a nonexistent cvs executable. To debug it further, 15519find the log file which inetd writes 15520(@file{/var/log/messages} or whatever inetd uses on 15521your system). For details, see @ref{Connection}, and 15522@ref{Password authentication server}. 15523 15524@item cvs commit: Up-to-date check failed for `@var{file}' 15525This means that someone else has committed a change to 15526that file since the last time that you did a @code{cvs 15527update}. So before proceeding with your @code{cvs 15528commit} you need to @code{cvs update}. @sc{cvs} will merge 15529the changes that you made and the changes that the 15530other person made. If it does not detect any conflicts 15531it will report @samp{M @var{file}} and you are ready 15532to @code{cvs commit}. If it detects conflicts it will 15533print a message saying so, will report @samp{C @var{file}}, 15534and you need to manually resolve the 15535conflict. For more details on this process see 15536@ref{Conflicts example}. 15537 15538@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 15539@example 15540Only one of [exEX3] allowed 15541@end example 15542This indicates a problem with the installation of 15543@code{diff3} and @code{rcsmerge}. Specifically 15544@code{rcsmerge} was compiled to look for GNU diff3, but 15545it is finding unix diff3 instead. The exact text of 15546the message will vary depending on the system. The 15547simplest solution is to upgrade to a current version of 15548@sc{cvs}, which does not rely on external 15549@code{rcsmerge} or @code{diff3} programs. 15550 15551@item warning: unrecognized response `@var{text}' from cvs server 15552If @var{text} contains a valid response (such as 15553@samp{ok}) followed by an extra carriage return 15554character (on many systems this will cause the second 15555part of the message to overwrite the first part), then 15556it probably means that you are using the @samp{:ext:} 15557access method with a version of rsh, such as most 15558non-unix rsh versions, which does not by default 15559provide a transparent data stream. In such cases you 15560probably want to try @samp{:server:} instead of 15561@samp{:ext:}. If @var{text} is something else, this 15562may signify a problem with your @sc{cvs} server. 15563Double-check your installation against the instructions 15564for setting up the @sc{cvs} server. 15565@c FIXCVS: should be printing CR as \r or \015 or some 15566@c such, probably. 15567 15568@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 15569This is a normal message, not an error. See 15570@ref{Concurrency}, for more details. 15571 15572@item cvs commit: warning: editor session failed 15573@cindex Exit status, of editor 15574This means that the editor which @sc{cvs} is using exits with a nonzero 15575exit status. Some versions of vi will do this even when there was not 15576a problem editing the file. If so, point the 15577@code{CVSEDITOR} environment variable to a small script 15578such as: 15579 15580@example 15581#!/bin/sh 15582vi $* 15583exit 0 15584@end example 15585 15586@item cvs update: warning: @var{file} was lost 15587This means that the working copy of @var{file} has been deleted 15588but it has not been removed from @sc{cvs}. 15589This is nothing to be concerned about, 15590the update will just recreate the local file from the repository. 15591(This is a convenient way to discard local changes to a file: 15592just delete it and then run @code{cvs update}.) 15593 15594@item cvs update: warning: @var{file} is not (any longer) pertinent 15595This means that the working copy of @var{file} has been deleted, 15596it has not been removed from @sc{cvs} in the current working directory, 15597but it has been removed from @sc{cvs} in some other working directory. 15598This is nothing to be concerned about, 15599the update would have removed the local file anyway. 15600 15601@end table 15602 15603@node Connection 15604@appendixsec Trouble making a connection to a CVS server 15605 15606This section concerns what to do if you are having 15607trouble making a connection to a @sc{cvs} server. If 15608you are running the @sc{cvs} command line client 15609running on Windows, first upgrade the client to 15610@sc{cvs} 1.9.12 or later. The error reporting in 15611earlier versions provided much less information about 15612what the problem was. If the client is non-Windows, 15613@sc{cvs} 1.9 should be fine. 15614 15615If the error messages are not sufficient to track down 15616the problem, the next steps depend largely on which 15617access method you are using. 15618 15619@table @code 15620@cindex :ext:, troubleshooting 15621@item :ext: 15622Try running the rsh program from the command line. For 15623example: "rsh servername cvs -v" should print @sc{cvs} 15624version information. If this doesn't work, you need to 15625fix it before you can worry about @sc{cvs} problems. 15626 15627@cindex :server:, troubleshooting 15628@item :server: 15629You don't need a command line rsh program to use this 15630access method, but if you have an rsh program around, 15631it may be useful as a debugging tool. Follow the 15632directions given for :ext:. 15633 15634@cindex :pserver:, troubleshooting 15635@item :pserver: 15636Errors along the lines of "connection refused" typically indicate 15637that inetd isn't even listening for connections on port 2401 15638whereas errors like "connection reset by peer", 15639"received broken pipe signal", "recv() from server: EOF", 15640or "end of file from server" 15641typically indicate that inetd is listening for 15642connections but is unable to start @sc{cvs} (this is frequently 15643caused by having an incorrect path in @file{inetd.conf} 15644or by firewall software rejecting the connection). 15645"unrecognized auth response" errors are caused by a bad command 15646line in @file{inetd.conf}, typically an invalid option or forgetting 15647to put the @samp{pserver} command at the end of the line. 15648Another less common problem is invisible control characters that 15649your editor "helpfully" added without you noticing. 15650 15651One good debugging tool is to "telnet servername 156522401". After connecting, send any text (for example 15653"foo" followed by return). If @sc{cvs} is working 15654correctly, it will respond with 15655 15656@example 15657cvs [pserver aborted]: bad auth protocol start: foo 15658@end example 15659 15660If instead you get: 15661 15662@example 15663Usage: cvs [cvs-options] command [command-options-and-arguments] 15664... 15665@end example 15666 15667@noindent 15668then you're missing the @samp{pserver} command at the end of the 15669line in @file{inetd.conf}; check to make sure that the entire command 15670is on one line and that it's complete. 15671 15672Likewise, if you get something like: 15673 15674@example 15675Unknown command: `pserved' 15676 15677CVS commands are: 15678 add Add a new file/directory to the repository 15679... 15680@end example 15681 15682@noindent 15683then you've misspelled @samp{pserver} in some way. If it isn't 15684obvious, check for invisible control characters (particularly 15685carriage returns) in @file{inetd.conf}. 15686 15687If it fails to work at all, then make sure inetd is working 15688right. Change the invocation in @file{inetd.conf} to run the 15689echo program instead of cvs. For example: 15690 15691@example 156922401 stream tcp nowait root /bin/echo echo hello 15693@end example 15694 15695After making that change and instructing inetd to 15696re-read its configuration file, "telnet servername 156972401" should show you the text hello and then the 15698server should close the connection. If this doesn't 15699work, you need to fix it before you can worry about 15700@sc{cvs} problems. 15701 15702On AIX systems, the system will often have its own 15703program trying to use port 2401. This is AIX's problem 15704in the sense that port 2401 is registered for use with 15705@sc{cvs}. I hear that there is an AIX patch available 15706to address this problem. 15707 15708Another good debugging tool is the @samp{-d} 15709(debugging) option to inetd. Consult your system 15710documentation for more information. 15711 15712If you seem to be connecting but get errors like: 15713 15714@example 15715cvs server: cannot open /root/.cvsignore: Permission denied 15716cvs [server aborted]: can't chdir(/root): Permission denied 15717@end example 15718 15719@noindent 15720then you probably haven't specified @samp{-f} in @file{inetd.conf}. 15721(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 15722your system setting the @code{$HOME} environment variable 15723for programs being run by inetd. In this case, you can either 15724have inetd run a shell script that unsets @code{$HOME} and then runs 15725@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 15726environment.) 15727 15728If you can connect successfully for a while but then can't, 15729you've probably hit inetd's rate limit. 15730(If inetd receives too many requests for the same service 15731in a short period of time, it assumes that something is wrong 15732and temporarily disables the service.) 15733Check your inetd documentation to find out how to adjust the 15734rate limit (some versions of inetd have a single rate limit, 15735others allow you to set the limit for each service separately.) 15736@end table 15737 15738@node Other problems 15739@appendixsec Other common problems 15740 15741Here is a list of problems which do not fit into the 15742above categories. They are in no particular order. 15743 15744@itemize @bullet 15745@item 15746On Windows, if there is a 30 second or so delay when 15747you run a @sc{cvs} command, it may mean that you have 15748your home directory set to @file{C:/}, for example (see 15749@code{HOMEDRIVE} and @code{HOMEPATH} in 15750@ref{Environment variables}). @sc{cvs} expects the home 15751directory to not end in a slash, for example @file{C:} 15752or @file{C:\cvs}. 15753@c FIXCVS: CVS should at least detect this and print an 15754@c error, presumably. 15755 15756@item 15757If you are running @sc{cvs} 1.9.18 or older, and 15758@code{cvs update} finds a conflict and tries to 15759merge, as described in @ref{Conflicts example}, but 15760doesn't tell you there were conflicts, then you may 15761have an old version of @sc{rcs}. The easiest solution 15762probably is to upgrade to a current version of 15763@sc{cvs}, which does not rely on external @sc{rcs} 15764programs. 15765@end itemize 15766 15767@c --------------------------------------------------------------------- 15768@node Credits 15769@appendix Credits 15770 15771@cindex Contributors (manual) 15772@cindex Credits (manual) 15773Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 15774wrote the manual pages which were distributed with 15775@sc{cvs} 1.3. Much of their text was copied into this 15776manual. He also read an early draft 15777of this manual and contributed many ideas and 15778corrections. 15779 15780The mailing-list @code{info-cvs} is sometimes 15781informative. I have included information from postings 15782made by the following persons: 15783David G. Grubbs <@t{dgg@@think.com}>. 15784 15785Some text has been extracted from the man pages for 15786@sc{rcs}. 15787 15788The @sc{cvs} @sc{faq} by David G. Grubbs has provided 15789useful material. The @sc{faq} is no longer maintained, 15790however, and this manual is about the closest thing there 15791is to a successor (with respect to documenting how to 15792use @sc{cvs}, at least). 15793 15794In addition, the following persons have helped by 15795telling me about mistakes I've made: 15796 15797@display 15798Roxanne Brunskill <@t{rbrunski@@datap.ca}>, 15799Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 15800Karl Pingle <@t{pingle@@acuson.com}>, 15801Thomas A Peterson <@t{tap@@src.honeywell.com}>, 15802Inge Wallin <@t{ingwa@@signum.se}>, 15803Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 15804and Michael Brown <@t{brown@@wi.extrel.com}>. 15805@end display 15806 15807The list of contributors here is not comprehensive; for a more 15808complete list of who has contributed to this manual see 15809the file @file{doc/ChangeLog} in the @sc{cvs} source 15810distribution. 15811 15812@c --------------------------------------------------------------------- 15813@node BUGS 15814@appendix Dealing with bugs in CVS or this manual 15815 15816@cindex Bugs in this manual or CVS 15817Neither @sc{cvs} nor this manual is perfect, and they 15818probably never will be. If you are having trouble 15819using @sc{cvs}, or think you have found a bug, there 15820are a number of things you can do about it. Note that 15821if the manual is unclear, that can be considered a bug 15822in the manual, so these problems are often worth doing 15823something about as well as problems with @sc{cvs} itself. 15824 15825@cindex Reporting bugs 15826@cindex Bugs, reporting 15827@cindex Errors, reporting 15828@itemize @bullet 15829@item 15830If you want someone to help you and fix bugs that you 15831report, there are companies which will do that for a 15832fee. One such company is: 15833 15834@cindex Ximbiot 15835@cindex Support, getting CVS support 15836@example 15837Ximbiot 15838319 S. River St. 15839Harrisburg, PA 17104-1657 15840USA 15841Email: info@@ximbiot.com 15842Phone: (717) 579-6168 15843Fax: (717) 234-3125 15844@url{http://ximbiot.com/} 15845 15846@end example 15847 15848@item 15849If you got @sc{cvs} through a distributor, such as an 15850operating system vendor or a vendor of freeware 15851@sc{cd-rom}s, you may wish to see whether the 15852distributor provides support. Often, they will provide 15853no support or minimal support, but this may vary from 15854distributor to distributor. 15855 15856@item 15857If you have the skills and time to do so, you may wish 15858to fix the bug yourself. If you wish to submit your 15859fix for inclusion in future releases of @sc{cvs}, see 15860the file @sc{hacking} in the @sc{cvs} source 15861distribution. It contains much more information on the 15862process of submitting fixes. 15863 15864@item 15865There may be resources on the net which can help. A 15866good place to start is: 15867 15868@example 15869@url{http://cvs.nongnu.org/} 15870@end example 15871 15872If you are so inspired, increasing the information 15873available on the net is likely to be appreciated. For 15874example, before the standard @sc{cvs} distribution 15875worked on Windows 95, there was a web page with some 15876explanation and patches for running @sc{cvs} on Windows 1587795, and various people helped out by mentioning this 15878page on mailing lists or newsgroups when the subject 15879came up. 15880 15881@item 15882It is also possible to report bugs to @email{bug-cvs@@nongnu.org}. 15883Note that someone may or may not want to do anything 15884with your bug report---if you need a solution consider 15885one of the options mentioned above. People probably do 15886want to hear about bugs which are particularly severe 15887in consequences and/or easy to fix, however. You can 15888also increase your odds by being as clear as possible 15889about the exact nature of the bug and any other 15890relevant information. The way to report bugs is to 15891send email to @email{bug-cvs@@nongnu.org}. Note 15892that submissions to @email{bug-cvs@@nongnu.org} may be distributed 15893under the terms of the @sc{gnu} Public License, so if 15894you don't like this, don't submit them. There is 15895usually no justification for sending mail directly to 15896one of the @sc{cvs} maintainers rather than to 15897@email{bug-cvs@@nongnu.org}; those maintainers who want to hear 15898about such bug reports read @email{bug-cvs@@nongnu.org}. Also note 15899that sending a bug report to other mailing lists or 15900newsgroups is @emph{not} a substitute for sending it to 15901@email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on 15902whatever forum you prefer, but there are not 15903necessarily any maintainers reading bug reports sent 15904anywhere except @email{bug-cvs@@nongnu.org}. 15905@end itemize 15906 15907@cindex Known bugs in this manual or CVS 15908People often ask if there is a list of known bugs or 15909whether a particular bug is a known one. The file 15910@sc{bugs} in the @sc{cvs} source distribution is one 15911list of known bugs, but it doesn't necessarily try to 15912be comprehensive. Perhaps there will never be a 15913comprehensive, detailed list of known bugs. 15914 15915@c --------------------------------------------------------------------- 15916@node Index 15917@unnumbered Index 15918@cindex Index 15919 15920@printindex cp 15921 15922@bye 15923 15924Local Variables: 15925fill-column: 55 15926End: 15927