1 \input texinfo @c -*-texinfo-*- 2 @comment Documentation for CVS. 3 @setfilename cvs.info 4 @macro copyleftnotice 5 @noindent 6 Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 7 2001, 2002, 2003, 2004, 2005, 2006 8 Free Software Foundation, Inc. 9 10 @multitable @columnfractions .12 .88 11 @item Portions 12 @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 13 2006 Derek R. Price, 14 @item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006 15 Ximbiot @url{http://ximbiot.com}, 16 @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 17 @item @tab and Copyright @copyright{} others. 18 @end multitable 19 20 @ignore 21 Permission is granted to process this file through Tex and print the 22 results, provided the printed document carries copying permission 23 notice 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 27 Permission is granted to make and distribute verbatim copies of 28 this manual provided the copyright notice and this permission notice 29 are preserved on all copies. 30 31 Permission is granted to copy and distribute modified versions of this 32 manual under the conditions for verbatim copying, provided also that the 33 entire resulting derived work is distributed under the terms of a 34 permission notice identical to this one. 35 36 Permission is granted to copy and distribute translations of this manual 37 into another language, under the above conditions for modified versions, 38 except that this permission notice may be stated in a translation 39 approved by the Free Software Foundation. 40 @end macro 41 42 @comment This file is part of the CVS distribution. 43 44 @comment CVS is free software; you can redistribute it and/or modify 45 @comment it under the terms of the GNU General Public License as published by 46 @comment the Free Software Foundation; either version 2, or (at your option) 47 @comment any later version. 48 49 @comment CVS is distributed in the hope that it will be useful, 50 @comment but WITHOUT ANY WARRANTY; without even the implied warranty of 51 @comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 52 @comment GNU General Public License for more details. 53 54 @c See ../README for A4 vs. US letter size. 55 @c When we provided A4 postscript, and people tried to 56 @c print it on US letter, the usual complaint was that the 57 @c page numbers would get cut off. 58 @c If one prints US letter on A4, reportedly there is 59 @c some extra space at the top and/or bottom, and the side 60 @c margins are a bit narrow, but no text is lost. 61 @c 62 @c See 63 @c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html 64 @c for more on paper sizes. Insuring that margins are 65 @c big enough to print on either A4 or US letter does 66 @c indeed seem to be the usual approach (RFC2346). 67 68 @c This document seems to get overfull hboxes with some 69 @c frequency (probably because the tendency is to 70 @c sanity-check it with "make info" and run TeX less 71 @c often). The big ugly boxes just seem to add insult 72 @c to injury, and I'm not aware of them helping to fix 73 @c the overfull hboxes at all. 74 @finalout 75 76 @include version.texi 77 @settitle CVS---Concurrent Versions System v@value{VERSION} 78 @setchapternewpage odd 79 80 @c -- TODO list: 81 @c -- Fix all lines that match "^@c -- " 82 @c -- Also places marked with FIXME should be manual 83 @c problems (as opposed to FIXCVS for CVS problems). 84 85 @c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by 86 @c @asis when generating info and dvi, and by <i></i> in the generated html, 87 @c such that keywords are not expanded in the generated html. 88 @ifnothtml 89 @macro splitrcskeyword {arg} 90 @asis{}\arg\ 91 @end macro 92 @end ifnothtml 93 94 @ifhtml 95 @macro splitrcskeyword {arg} 96 @i{}\arg\ 97 @end macro 98 @end ifhtml 99 100 @dircategory GNU Packages 101 @direntry 102 * CVS: (cvs). Concurrent Versions System 103 @end direntry 104 @dircategory Individual utilities 105 @direntry 106 * cvs: (cvs)CVS commands. Concurrent Versions System 107 @end direntry 108 109 @comment The titlepage section does not appear in the Info file. 110 @titlepage 111 @sp 4 112 @comment The title is printed in a large font. 113 @center @titlefont{Version Management} 114 @sp 1 115 @center @titlefont{with} 116 @sp 1 117 @center @titlefont{CVS} 118 @sp 2 119 @center for @sc{cvs} @value{VERSION} 120 @comment -release- 121 @sp 3 122 @center Per Cederqvist et al 123 124 @comment The following two commands start the copyright page 125 @comment for the printed manual. This will not appear in the Info file. 126 @page 127 @vskip 0pt plus 1filll 128 @copyleftnotice 129 @end titlepage 130 131 @summarycontents 132 133 @contents 134 135 @comment ================================================================ 136 @comment The real text starts here 137 @comment ================================================================ 138 139 @ifnottex 140 @c --------------------------------------------------------------------- 141 @node Top 142 @top 143 144 This 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 164 CVS 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 174 References. 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 192 This chapter is for people who have never used 193 @sc{cvs}, and perhaps have never used version control 194 software before. 195 196 If you are already familiar with @sc{cvs} and are just 197 trying to learn a particular feature or remember a 198 certain 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 214 record 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! 222 For example, bugs sometimes creep in when 223 software is modified, and you might not detect the bug 224 until a long time after you make the modification. 225 With @sc{cvs}, you can easily retrieve old versions to see 226 exactly which change caused the bug. This can 227 sometimes be a big help. 228 229 You could of course save every version of every file 230 you have ever created. This would 231 however waste an enormous amount of disk space. @sc{cvs} 232 stores all the versions of a file in a single file in a 233 clever way that only stores the differences between 234 versions. 235 236 @sc{cvs} also helps you if you are part of a group of people working 237 on the same project. It is all too easy to overwrite 238 each others' changes unless you are extremely careful. 239 Some editors, like @sc{gnu} Emacs, try to make sure that 240 two people never modify the same file at the 241 same time. Unfortunately, if someone is using another 242 editor, that safeguard will not work. @sc{cvs} solves this problem 243 by insulating the different developers from each other. Every 244 developer works in his own directory, and @sc{cvs} merges 245 the 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 252 Dick Grune, posted to the newsgroup 253 @code{comp.sources.unix} in the volume 6 254 release of July, 1986. While no actual code from 255 these shell scripts is present in the current version 256 of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms 257 come from them. 258 259 In April, 1989, Brian Berliner designed and coded @sc{cvs}. 260 Jeff Polk later helped Brian with the design of the @sc{cvs} 261 module and vendor branch support. 262 263 @cindex Source, getting CVS source 264 You can get @sc{cvs} in a variety of ways, including 265 free download from the Internet. For more information 266 on 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 275 There is a mailing list, known as @email{info-cvs@@nongnu.org}, 276 devoted to @sc{cvs}. To subscribe or 277 unsubscribe 278 write to 279 @email{info-cvs-request@@nongnu.org}. 280 If you prefer a Usenet group, there is a one-way mirror (posts to the email 281 list 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 283 Usenet group for posts is @url{news:comp.software.config-mgmt} which is for 284 @sc{cvs} discussions (along with other configuration 285 management systems). In the future, it might be 286 possible to create a 287 @code{comp.software.config-mgmt.cvs}, but probably only 288 if 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 297 You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list, 298 described in more detail in @ref{BUGS}. To subscribe 299 send mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way 300 Usenet mirror (posts to the Usenet group are usually sent to the email list and 301 visa 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 309 not try to be everything for everyone. 310 311 @table @asis 312 @item @sc{cvs} is not a build system. 313 314 Though the structure of your repository and modules 315 file interact with your build system 316 (e.g. @file{Makefile}s), they are essentially 317 independent. 318 319 @sc{cvs} does not dictate how you build anything. It 320 merely stores files for retrieval in a tree structure 321 you devise. 322 323 @sc{cvs} does not dictate how to use disk space in the 324 checked out working directories. If you write your 325 @file{Makefile}s or scripts in every directory so they 326 have to know the relative positions of everything else, 327 you wind up requiring the entire repository to be 328 checked out. 329 330 If you modularize your work, and construct a build 331 system that will share files (via links, mounts, 332 @code{VPATH} in @file{Makefile}s, etc.), you can 333 arrange your disk usage however you like. 334 335 But you have to remember that @emph{any} such system is 336 a lot of work to construct and maintain. @sc{cvs} does 337 not address the issues involved. 338 339 Of course, you should place the tools created to 340 support such a build system (scripts, @file{Makefile}s, 341 etc) under @sc{cvs}. 342 343 Figuring out what files need to be rebuilt when 344 something changes is, again, something to be handled 345 outside the scope of @sc{cvs}. One traditional 346 approach is to use @code{make} for building, and use 347 some automated tool for generating the dependencies which 348 @code{make} uses. 349 350 See @ref{Builds}, for more information on doing builds 351 in conjunction with @sc{cvs}. 352 353 @item @sc{cvs} is not a substitute for management. 354 355 Your managers and project leaders are expected to talk 356 to you frequently enough to make certain you are aware 357 of schedules, merge points, branch names and release 358 dates. If they don't, @sc{cvs} can't help. 359 360 @sc{cvs} is an instrument for making sources dance to 361 your tune. But you are the piper and the composer. No 362 instrument plays itself or writes its own music. 363 364 @item @sc{cvs} is not a substitute for developer communication. 365 366 When faced with conflicts within a single file, most 367 developers manage to resolve them without too much 368 effort. But a more general definition of ``conflict'' 369 includes problems too difficult to solve without 370 communication between developers. 371 372 @sc{cvs} cannot determine when simultaneous changes 373 within a single file, or across a whole collection of 374 files, will logically conflict with one another. Its 375 concept of a @dfn{conflict} is purely textual, arising 376 when two changes to the same base file are near enough 377 to spook the merge (i.e. @code{diff3}) command. 378 379 @sc{cvs} does not claim to help at all in figuring out 380 non-textual or distributed conflicts in program logic. 381 382 For example: Say you change the arguments to function 383 @code{X} defined in file @file{A}. At the same time, 384 someone edits file @file{B}, adding new calls to 385 function @code{X} using the old arguments. You are 386 outside the realm of @sc{cvs}'s competence. 387 388 Acquire the habit of reading specs and talking to your 389 peers. 390 391 392 @item @sc{cvs} does not have change control 393 394 Change control refers to a number of things. First of 395 all it can mean @dfn{bug-tracking}, that is being able 396 to keep a database of reported bugs and the status of 397 each one (is it fixed? in what release? has the bug 398 submitter 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 403 Another aspect of change control is keeping track of 404 the fact that changes to several files were in fact 405 changed together as one logical change. If you check 406 in several files in a single @code{cvs commit} 407 operation, @sc{cvs} then forgets that those files were 408 checked in together, and the fact that they have the 409 same log message is the only thing tying them 410 together. Keeping a @sc{gnu} style @file{ChangeLog} 411 can 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 416 Another aspect of change control, in some systems, is 417 the ability to keep track of the status of each 418 change. Some changes have been written by a developer, 419 others have been reviewed by a second developer, and so 420 on. Generally, the way to do this with @sc{cvs} is to 421 generate a diff (using @code{cvs diff} or @code{diff}) 422 and email it to someone who can then apply it using the 423 @code{patch} utility. This is very flexible, but 424 depends on mechanisms outside @sc{cvs} to make sure 425 nothing falls through the cracks. 426 427 @item @sc{cvs} is not an automated testing program 428 429 It should be possible to enforce mandatory use of a 430 test suite using the @code{commitinfo} file. I haven't 431 heard a lot about projects trying to do that or whether 432 there are subtle gotchas, however. 433 434 @item @sc{cvs} does not have a built-in process model 435 436 Some systems provide ways to ensure that changes or 437 releases go through various steps, with various 438 approvals as needed. Generally, one can accomplish 439 this with @sc{cvs} but it might be a little more work. 440 In some cases you'll want to use the @file{commitinfo}, 441 @file{loginfo}, @file{rcsinfo}, or @file{verifymsg} 442 files, to require that certain steps be performed 443 before cvs will allow a checkin. Also consider whether 444 features such as branches and tags can be used to 445 perform tasks such as doing work in a development tree 446 and then merging certain changes over to a stable tree 447 only 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) 476 The repository contains directories and files, in an 477 arbitrary tree. The @dfn{modules} feature can be used 478 to group together a set of directories or files into a 479 single entity (@pxref{modules}). A typical usage is to 480 define one module per project. 481 @end ignore 482 483 As a way of introducing @sc{cvs}, we'll go through a 484 typical work-session using @sc{cvs}. The first thing 485 to understand is that @sc{cvs} stores all files in a 486 centralized @dfn{repository} (@pxref{Repository}); this 487 section 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 493 Suppose you are working on a simple compiler. The source 494 consists of a handful of C files and a @file{Makefile}. 495 The compiler is called @samp{tc} (Trivial Compiler), 496 and the repository is set up so that there is a module 497 called @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 515 The first thing you must do is to get your own working copy of the 516 source for @samp{tc}. For this, you use the @code{checkout} command: 517 518 @example 519 $ cvs checkout tc 520 @end example 521 522 @noindent 523 This will create a new directory called @file{tc} and populate it with 524 the source files. 525 526 @example 527 $ cd tc 528 $ ls 529 CVS Makefile backend.c driver.c frontend.c parser.c 530 @end example 531 532 The @file{CVS} directory is used internally by 533 @sc{cvs}. Normally, you should not modify or remove 534 any of the files in it. 535 536 You start your favorite editor, hack away at @file{backend.c}, and a couple 537 of hours later you have added an optimization pass to the compiler. 538 A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that 539 you 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 547 When you have checked that the compiler is still compilable you decide 548 to make a new version of @file{backend.c}. This will 549 store your new @file{backend.c} in the repository and 550 make it available to anyone else who is using that same 551 repository. 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 559 message. You type in ``Added an optimization pass.'', 560 save the temporary file, and exit the editor. 561 562 @cindex CVSEDITOR, environment variable 563 @cindex EDITOR, environment variable 564 The environment variable @code{$CVSEDITOR} determines 565 which editor is started. If @code{$CVSEDITOR} is not 566 set, then if the environment variable @code{$EDITOR} is 567 set, it will be used. If both @code{$CVSEDITOR} and 568 @code{$EDITOR} are not set then there is a default 569 which will vary with your operating system, for example 570 @code{vi} for unix or @code{notepad} for Windows 571 NT/95. 572 573 @cindex VISUAL, environment variable 574 In addition, @sc{cvs} checks the @code{$VISUAL} environment 575 variable. Opinions vary on whether this behavior is desirable and 576 whether future releases of @sc{cvs} should check @code{$VISUAL} or 577 ignore 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. 585 When @sc{cvs} starts the editor, it includes a list of 586 files which are modified. For the @sc{cvs} client, 587 this list is based on comparing the modification time 588 of the file against the modification time that the file 589 had when it was last gotten or updated. Therefore, if 590 a file's modification time has changed but its contents 591 have not, it will show up as modified. The simplest 592 way to handle this is simply not to worry about it---if 593 you proceed with the commit @sc{cvs} will detect that 594 the contents are not modified and treat it as an 595 unmodified file. The next @code{update} will clue 596 @sc{cvs} in to the fact that the file is unmodified, 597 and it will reset its stored timestamp so that the file 598 will 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 615 If you want to avoid 616 starting an editor you can specify the log message on 617 the command line using the @samp{-m} flag instead, like 618 this: 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 632 Before you turn to other tasks you decide to remove your working copy of 633 tc. One acceptable way to do that is of course 634 635 @example 636 $ cd .. 637 $ rm -r tc 638 @end example 639 640 @noindent 641 but a better way is to use the @code{release} command (@pxref{release}): 642 643 @example 644 $ cd .. 645 $ cvs release -d tc 646 M driver.c 647 ? tc 648 You have [1] altered files in this repository. 649 Are you sure you want to release (and delete) directory `tc': n 650 ** `release' aborted by user choice. 651 @end example 652 653 The @code{release} command checks that all your modifications have been 654 committed. If history logging is enabled it also makes a note in the 655 history file. @xref{history file}. 656 657 When you use the @samp{-d} flag with @code{release}, it 658 also removes your working copy. 659 660 In the example above, the @code{release} command wrote a couple of lines 661 of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. 662 That is nothing to worry about: @file{tc} is the executable compiler, 663 and it should not be stored in the repository. @xref{cvsignore}, 664 for information about how to make that warning go away. 665 @xref{release output}, for a complete explanation of 666 all possible output from @code{release}. 667 668 @samp{M driver.c} is more serious. It means that the 669 file @file{driver.c} has been modified since it was 670 checked out. 671 672 The @code{release} command always finishes by telling 673 you how many modified files you have in your working 674 copy of the sources, and then asks you for confirmation 675 before deleting any files or making any note in the 676 history file. 677 678 You decide to play it safe and answer @kbd{n @key{RET}} 679 when @code{release} asks for confirmation. 680 681 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 682 @node Viewing differences 683 @subsection Viewing differences 684 @cindex Viewing differences 685 @cindex Diff 686 687 You do not remember modifying @file{driver.c}, so you want to see what 688 has happened to that file. 689 690 @example 691 $ cd tc 692 $ cvs diff driver.c 693 @end example 694 695 This command runs @code{diff} to compare the version of @file{driver.c} 696 that you checked out with your working copy. When you see the output 697 you remember that you added a command line option that enabled the 698 optimization 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 703 Checking in driver.c; 704 /usr/local/cvsroot/tc/driver.c,v <-- driver.c 705 new revision: 1.2; previous revision: 1.1 706 done 707 $ cd .. 708 $ cvs release -d tc 709 ? tc 710 You have [0] altered files in this repository. 711 Are 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 724 The @sc{cvs} @dfn{repository} stores a complete copy of 725 all the files and directories which are under version 726 control. 727 728 Normally, you never access any of the files in the 729 repository directly. Instead, you use @sc{cvs} 730 commands to get your own copy of the files into a 731 @dfn{working directory}, and then 732 work on that copy. When you've finished a set of 733 changes, you check (or @dfn{commit}) them back into the 734 repository. The repository then contains the changes 735 which you have made, as well as recording exactly what 736 you changed, when you changed it, and other such 737 information. Note that the repository is not a 738 subdirectory of the working directory, or vice versa; 739 they 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 747 means. It might be on the local computer, or it might 748 be on a computer across the room or across the world. 749 To distinguish various ways to access a repository, the 750 repository name can start with an @dfn{access method}. 751 For example, the access method @code{:local:} means to 752 access a repository directory, so the repository 753 @code{:local:/usr/local/cvsroot} means that the 754 repository is in @file{/usr/local/cvsroot} on the 755 computer running @sc{cvs}. For information on other 756 access 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? 760 If the access method is omitted, then if the repository 761 starts with @samp{/}, then @code{:local:} is 762 assumed. If it does not start with @samp{/} then either 763 @code{:ext:} or @code{:server:} is assumed. For 764 example, 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 768 Windows NT, for example) your local repository is 769 @file{c:\src\cvsroot}, then you must specify the access 770 method, 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. 776 The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains 777 administrative files for @sc{cvs}. The other directories contain the actual 778 user-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 797 There are several ways to tell @sc{cvs} 798 where to find the repository. You can name the 799 repository on the command line explicitly, with the 800 @code{-d} (for "directory") option: 801 802 @example 803 cvs -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 812 variable to an absolute path to the root of the 813 repository, @file{/usr/local/cvsroot} in this example. 814 To set @code{$CVSROOT}, @code{csh} and @code{tcsh} 815 users should have this line in their @file{.cshrc} or 816 @file{.tcshrc} files: 817 818 @example 819 setenv 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 827 CVSROOT=/usr/local/cvsroot 828 export 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 834 override the @code{$CVSROOT} environment variable. 835 Once you've checked a working copy out from the 836 repository, it will remember where its repository is 837 (the information is recorded in the 838 @file{CVS/Root} file in the working copy). 839 840 The @code{-d} option and the @file{CVS/Root} file both 841 override the @code{$CVSROOT} environment variable. If 842 @code{-d} option differs from @file{CVS/Root}, the 843 former is used. Of course, for proper operation they 844 should 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 851 For most purposes it isn't important @emph{how} 852 @sc{cvs} stores information in the repository. In 853 fact, the format has changed in the past, and is likely 854 to change in the future. Since in almost all cases one 855 accesses the repository via @sc{cvs} commands, such 856 changes need not be disruptive. 857 858 However, in some cases it may be necessary to 859 understand how @sc{cvs} stores data in the repository, 860 for example you might need to track down @sc{cvs} locks 861 (@pxref{Concurrency}) or you might need to deal with 862 the 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 894 The overall structure of the repository is a directory 895 tree corresponding to the directories in the working 896 directory. For example, supposing the repository is in 897 898 @example 899 /usr/local/cvsroot 900 @end example 901 902 @noindent 903 here is a possible directory tree (showing only the 904 directories): 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 938 With the directories are @dfn{history files} for each file 939 under version control. The name of the history file is 940 the name of the corresponding file with @samp{,v} 941 appended to the end. Here is what the repository for 942 the @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.... 973 The history files contain, among other things, enough 974 information to recreate any revision of the file, a log 975 of all commit messages and the user-name of the person 976 who committed the revision. The history files are 977 known as @dfn{RCS files}, because the first program to 978 store files in that format was a version control system 979 known as @sc{rcs}. For a full 980 description of the file format, see the @code{man} page 981 @cite{rcsfile(5)}, distributed with @sc{rcs}, or the 982 file @file{doc/RCSFILES} in the @sc{cvs} source 983 distribution. This 984 file format has become very common---many systems other 985 than @sc{cvs} or @sc{rcs} can at least import history 986 files 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 994 The @sc{rcs} files used in @sc{cvs} differ in a few 995 ways from the standard format. The biggest difference 996 is magic branches; for more information see @ref{Magic 997 branch numbers}. Also in @sc{cvs} the valid tag names 998 are a subset of what @sc{rcs} accepts; for @sc{cvs}'s 999 rules 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 1013 All @samp{,v} files are created read-only, and you 1014 should not change the permission of those files. The 1015 directories inside the repository should be writable by 1016 the persons that have permission to modify the files in 1017 each directory. This normally means that you must 1018 create a UNIX group (see group(5)) consisting of the 1019 persons that are to edit the files in a project, and 1020 set up the repository so that it is that group that 1021 owns the directory. 1022 (On some systems, you also need to set the set-group-ID-on-execution bit 1023 on the repository directories (see chmod(1)) so that newly-created files 1024 and directories get the group-ID of the parent directory rather than 1025 that 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 1030 This means that you can only control access to files on 1031 a per-directory basis. 1032 1033 Note that users must also have write access to check 1034 out files, because @sc{cvs} needs to create lock files 1035 (@pxref{Concurrency}). You can use LockDir in CVSROOT/config 1036 to put the lock files somewhere other than in the repository 1037 if 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 1046 Also note that users must have write access to the 1047 @file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep 1048 track of what tags are valid tag names (it is sometimes 1049 updated when tags are used, as well as when they are 1050 created). 1051 1052 Each @sc{rcs} file will be owned by the user who last 1053 checked it in. This has little significance; what 1054 really 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 1059 for new directories that are added inside the tree, but 1060 you must fix the permissions manually when a new 1061 directory should have different permissions than its 1062 parent directory. If you set the @code{CVSUMASK} 1063 environment variable that will control the file 1064 permissions which @sc{cvs} uses in creating directories 1065 and/or files in the repository. @code{CVSUMASK} does 1066 not affect the file permissions in the working 1067 directory; such files have the permissions which are 1068 typical for newly created files, except that sometimes 1069 @sc{cvs} creates them read-only (see the sections on 1070 watches, @ref{Setting a watch}; -r, @ref{Global 1071 options}; 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 1085 Note that using the client/server @sc{cvs} 1086 (@pxref{Remote repositories}), there is no good way to 1087 set @code{CVSUMASK}; the setting on the client machine 1088 has no effect. If you are connecting with @code{rsh}, you 1089 can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as 1090 described in the documentation for your operating 1091 system. This behavior might change in future versions 1092 of @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 1114 Using pserver, you will generally need stricter 1115 permissions on the @sc{cvsroot} directory and 1116 directories above it in the tree; see @ref{Password 1117 authentication security}. 1118 1119 @cindex Setuid 1120 @cindex Setgid 1121 @cindex Security, setuid 1122 @cindex Installed images (VMS) 1123 Some operating systems have features which allow a 1124 particular program to run with the ability to perform 1125 operations which the caller of the program could not. 1126 For example, the set user ID (setuid) or set group ID 1127 (setgid) features of unix or the installed image 1128 feature of VMS. @sc{cvs} was not written to use such 1129 features and therefore attempting to install @sc{cvs} in 1130 this fashion will provide protection against only 1131 accidental lapses; anyone who is trying to circumvent 1132 the measure will be able to do so, and depending on how 1133 you have set it up may gain access to more than just 1134 @sc{cvs}. You may wish to instead consider pserver. It 1135 shares some of the same attributes, in terms of 1136 possibly providing a false sense of security or opening 1137 security holes wider than the ones you are trying to 1138 fix, so read the documentation on pserver security 1139 carefully 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 1148 Some file permission issues are specific to Windows 1149 operating systems (Windows 95, Windows NT, and 1150 presumably future operating systems in this family. 1151 Some of the following might apply to OS/2 but I'm not 1152 sure). 1153 1154 If you are using local @sc{cvs} and the repository is on a 1155 networked file system which is served by the Samba SMB 1156 server, some people have reported problems with 1157 permissions. Enabling WRITE=YES in the samba 1158 configuration is said to fix/workaround it. 1159 Disclaimer: I haven't investigated enough to know the 1160 implications of enabling that option, nor do I know 1161 whether there is something which @sc{cvs} could be doing 1162 differently in order to avoid the problem. If you find 1163 something out, please let us know as described in 1164 @ref{BUGS}. 1165 1166 @node Attic 1167 @subsection The attic 1168 @cindex Attic 1169 1170 You 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 1173 talking about the file @file{backend.c} in the 1174 directory @file{yoyodyne/tc}, then the file normally 1175 would be in 1176 1177 @example 1178 /usr/local/cvsroot/yoyodyne/tc/backend.c,v 1179 @end example 1180 1181 @noindent 1182 but 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 1190 instead. It should not matter from a user point of 1191 view whether a file is in the attic; @sc{cvs} keeps 1192 track of this and looks in the attic when it needs to. 1193 But in case you want to know, the rule is that the RCS 1194 file is stored in the attic if and only if the head 1195 revision on the trunk has state @code{dead}. A 1196 @code{dead} state means that file has been removed, or 1197 never added, for that revision. For example, if you 1198 add a file on a branch, it will have a trunk revision 1199 in @code{dead} state, and a branch revision in a 1200 non-@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 1210 The @file{CVS} directory in each repository directory 1211 contains information such as file attributes (in a file 1212 called @file{CVS/fileattr}. In the 1213 future additional files may be added to this directory, 1214 so implementations should silently ignore additional 1215 files. 1216 1217 This behavior is implemented only by @sc{cvs} 1.7 and 1218 later; for details see @ref{Watches Compatibility}. 1219 1220 The format of the @file{fileattr} file is a series of entries 1221 of the following form (where @samp{@{} and @samp{@}} 1222 means the text between the braces can be repeated zero 1223 or 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 1229 attributes for that file. 1230 1231 @var{ent-type} is @samp{D}, 1232 and @var{filename} empty, to specify default attributes 1233 to be used for newly added files. 1234 1235 Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older 1236 will delete them any time it writes file attributes. 1237 @sc{cvs} 1.10 and later will preserve them. 1238 1239 Note that the order of the lines is not significant; 1240 a program writing the fileattr file may 1241 rearrange them at its convenience. 1242 1243 There is currently no way of quoting tabs or line feeds in the 1244 filename, @samp{=} in @var{attrname}, 1245 @samp{;} in @var{attrval}, etc. Note: some implementations also 1246 don't handle a NUL character in any of the fields, but 1247 implementations are encouraged to allow it. 1248 1249 By convention, @var{attrname} starting with @samp{_} is for an attribute given 1250 special 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 1253 Built-in attributes: 1254 1255 @table @code 1256 @item _watched 1257 Present means the file is watched and should be checked out 1258 read-only. 1259 1260 @item _watchers 1261 Users with watches for this file. Value is 1262 @var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} 1263 where @var{watcher} is a username, and @var{type} 1264 is 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 1268 Users editing this file. Value is 1269 @var{editor} > @var{val} @{ , @var{editor} > @var{val} @} 1270 where @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 1273 equivalent) happened, 1274 and @var{hostname} and @var{pathname} are for the working directory. 1275 @end table 1276 1277 Example: 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 1284 Ffile1 _watched=;_watchers=joe>edit,mary>commit 1285 Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs 1286 D _watched= 1287 @end example 1288 1289 @noindent 1290 means that the file @file{file1} should be checked out 1291 read-only. Furthermore, joe is watching for edits and 1292 mary is watching for commits. The file @file{file2} 1293 should be checked out read-only; sue started editing it 1294 on 8 Jan 1975 in the directory @file{/home/sue/cvs} on 1295 the machine @code{workstn1}. Future files which are 1296 added should be checked out read-only. To represent 1297 this example here, we have shown a space after 1298 @samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact 1299 there 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 1309 For an introduction to @sc{cvs} locks focusing on 1310 user-visible behavior, see @ref{Concurrency}. The 1311 following section is aimed at people who are writing 1312 tools which want to access a @sc{cvs} repository without 1313 interfering with other tools accessing the same 1314 repository. If you find yourself confused by concepts 1315 described here, like @dfn{read lock}, @dfn{write lock}, 1316 and @dfn{deadlock}, you might consult the literature on 1317 operating systems or databases. 1318 1319 @cindex #cvs.tfl 1320 Any file in the repository with a name starting 1321 with @file{#cvs.rfl.} is a read lock. Any file in 1322 the repository with a name starting with 1323 @file{#cvs.pfl} is a promotable read lock. Any file in 1324 the 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 1327 with @file{#cvs.tfl}, but they are not discussed here. 1328 The directory @file{#cvs.lock} serves as a master 1329 lock. That is, one must obtain this lock first before 1330 creating any of the other locks. 1331 1332 To obtain a read lock, first create the @file{#cvs.lock} 1333 directory. This operation must be atomic (which should 1334 be true for creating a directory under most operating 1335 systems). If it fails because the directory already 1336 existed, wait for a while and try again. After 1337 obtaining the @file{#cvs.lock} lock, create a file 1338 whose name is @file{#cvs.rfl.} followed by information 1339 of your choice (for example, hostname and process 1340 identification number). Then remove the 1341 @file{#cvs.lock} directory to release the master lock. 1342 Then proceed with reading the repository. When you are 1343 done, remove the @file{#cvs.rfl} file to release the 1344 read lock. 1345 1346 Promotable read locks are a concept you may not find in other literature on 1347 concurrency. They are used to allow a two (or more) pass process to only lock 1348 a file for read on the first (read) pass(es), then upgrade its read locks to 1349 write locks if necessary for a final pass, still assured that the files have 1350 not changed since they were first read. @sc{cvs} uses promotable read locks, 1351 for example, to prevent commit and tag verification passes from interfering 1352 with other reading processes. It can then lock only a single directory at a 1353 time for write during the write pass. 1354 1355 To obtain a promotable read lock, first create the @file{#cvs.lock} directory, 1356 as with a non-promotable read lock. Then check 1357 that there are no files that start with 1358 @file{#cvs.pfl}. If there are, remove the master @file{#cvs.lock} directory, 1359 wait awhile (CVS waits 30 seconds between lock attempts), and try again. If 1360 there 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 1362 its hostname and the process identification number of the CVS server process 1363 creating the lock). If versions of @sc{cvs} older than version 1.12.4 access 1364 your repository directly (not via a @sc{cvs} server of version 1.12.4 or 1365 later), then you should also create a read lock since older versions of CVS 1366 will ignore the promotable lock when attempting to create their own write lock. 1367 Then remove the master @file{#cvs.lock} directory in order to allow other 1368 processes to obtain read locks. 1369 1370 To obtain a write lock, first create the 1371 @file{#cvs.lock} directory, as with read locks. Then 1372 check 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 1374 not owned by the process attempting to get the write lock. If either exist, 1375 remove @file{#cvs.lock}, wait for a while, and try again. If 1376 there are no readers or promotable locks from other processes, then create a 1377 file whose name is @file{#cvs.wfl} followed by information of your choice 1378 (again, CVS uses the hostname and server process identification 1379 number). Remove your @file{#cvs.pfl} file if present. Hang on to the 1380 @file{#cvs.lock} lock. Proceed 1381 with writing the repository. When you are done, first 1382 remove 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 1385 informational; it has no effect on the locking operation 1386 beyond what is provided by holding on to the 1387 @file{#cvs.lock} lock itself. 1388 1389 Note that each lock (write lock or read lock) only locks 1390 a single directory in the repository, including 1391 @file{Attic} and @file{CVS} but not including 1392 subdirectories which represent other directories under 1393 version control. To lock an entire tree, you need to 1394 lock each directory (note that if you fail to obtain 1395 any lock you need, you must release the whole tree 1396 before waiting and trying again, to avoid deadlocks). 1397 1398 Note also that @sc{cvs} expects write locks to control 1399 access to individual @file{foo,v} files. @sc{rcs} has 1400 a scheme where the @file{,foo,} file serves as a lock, 1401 but @sc{cvs} does not implement it and so taking out a 1402 @sc{cvs} write lock is recommended. See the comments at 1403 rcs_internal_lockfile in the @sc{cvs} source code for 1404 further discussion/rationale. 1405 1406 @node CVSROOT storage 1407 @subsection How files are stored in the CVSROOT directory 1408 @cindex CVSROOT, storage of files 1409 1410 The @file{$CVSROOT/CVSROOT} directory contains the 1411 various administrative files. In some ways this 1412 directory is just like any other directory in the 1413 repository; it contains @sc{rcs} files whose names end 1414 in @samp{,v}, and many of the @sc{cvs} commands operate 1415 on it the same way. However, there are a few 1416 differences. 1417 1418 For each administrative file, in addition to the 1419 @sc{rcs} file, there is also a checked out copy of the 1420 file. For example, there is an @sc{rcs} file 1421 @file{loginfo,v} and a file @file{loginfo} which 1422 contains the latest revision contained in 1423 @file{loginfo,v}. When you check in an administrative 1424 file, @sc{cvs} should print 1425 1426 @example 1427 cvs commit: Rebuilding administrative file database 1428 @end example 1429 1430 @noindent 1431 and update the checked out copy in 1432 @file{$CVSROOT/CVSROOT}. If it does not, there is 1433 something wrong (@pxref{BUGS}). To add your own files 1434 to the files to be updated in this fashion, you can add 1435 them to the @file{checkoutlist} administrative file 1436 (@pxref{checkoutlist}). 1437 1438 @cindex modules.db 1439 @cindex modules.pag 1440 @cindex modules.dir 1441 By default, the @file{modules} file behaves as 1442 described above. If the modules file is very large, 1443 storing it as a flat text file may make looking up 1444 modules slow (I'm not sure whether this is as much of a 1445 concern now as when @sc{cvs} first evolved this 1446 feature; I haven't seen benchmarks). Therefore, by 1447 making appropriate edits to the @sc{cvs} source code 1448 one can store the modules file in a database which 1449 implements the @code{ndbm} interface, such as Berkeley 1450 db or GDBM. If this option is in use, then the modules 1451 database 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 1456 For information on the meaning of the various 1457 administrative 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 1470 While we are discussing @sc{cvs} internals which may 1471 become visible from time to time, we might as well talk 1472 about what @sc{cvs} puts in the @file{CVS} directories 1473 in the working directories. As with the repository, 1474 @sc{cvs} handles this information and one can usually 1475 access it via @sc{cvs} commands. But in some cases it 1476 may be useful to look at it, and other programs, such 1477 as the @code{jCVS} graphical user interface or the 1478 @code{VC} package for emacs, may need to look at it. 1479 Such programs should follow the recommendations in this 1480 section if they hope to be able to work with other 1481 programs which use those files, including future 1482 versions of the programs just mentioned and the 1483 command-line @sc{cvs} client. 1484 1485 The @file{CVS} directory contains several files. 1486 Programs which are reading this directory should 1487 silently ignore files which are in the directory but 1488 which are not documented here, to allow for future 1489 expansion. 1490 1491 The files are stored according to the text file 1492 convention for the system in question. This means that 1493 working directories are not portable between systems 1494 with differing conventions for storing text files. 1495 This is intentional, on the theory that the files being 1496 managed by @sc{cvs} probably will not be portable between 1497 such systems either. 1498 1499 @table @file 1500 @item Root 1501 This file contains the current @sc{cvs} root, as 1502 described in @ref{Specifying a repository}. 1503 1504 @cindex Repository file, in CVS directory 1505 @cindex CVS/Repository file 1506 @item Repository 1507 This file contains the directory within the repository 1508 which the current directory corresponds with. It can 1509 be either an absolute pathname or a relative pathname; 1510 @sc{cvs} has had the ability to read either format 1511 since at least version 1.3 or so. The relative 1512 pathname is relative to the root, and is the more 1513 sensible approach, but the absolute pathname is quite 1514 common and implementations should accept either. For 1515 example, after the command 1516 1517 @example 1518 cvs -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 1529 and @file{Repository} will contain either 1530 1531 @example 1532 /usr/local/cvsroot/yoyodyne/tc 1533 @end example 1534 1535 @noindent 1536 or 1537 1538 @example 1539 yoyodyne/tc 1540 @end example 1541 1542 If the particular working directory does not correspond 1543 to a directory in the repository, then @file{Repository} 1544 should 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 1551 This file lists the files and directories in the 1552 working directory. 1553 The first character of each line indicates what sort of 1554 line it is. If the character is unrecognized, programs 1555 reading the file should silently skip that line, to 1556 allow for future expansion. 1557 1558 If 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 1565 where @samp{[} and @samp{]} are not part of the entry, 1566 but instead indicate that the @samp{+} and conflict 1567 marker are optional. @var{name} is the name of the 1568 file within the directory. @var{revision} is the 1569 revision that the file in the working derives from, or 1570 @samp{0} for an added file, or @samp{-} followed by a 1571 revision for a removed file. @var{timestamp} is the 1572 timestamp of the file at the time that @sc{cvs} created 1573 it; if the timestamp differs with the actual 1574 modification time of the file it means the file has 1575 been modified. It is stored in 1576 the format used by the ISO C asctime() function (for 1577 example, @samp{Sun Apr 7 01:29:26 1996}). One may 1578 write a string which is not in that format, for 1579 example, @samp{Result of merge}, to indicate that the 1580 file should always be considered to be modified. This 1581 is not a special case; to see whether a file is 1582 modified a program should take the timestamp of the file 1583 and simply do a string compare with @var{timestamp}. 1584 If there was a conflict, @var{conflict} can be set to 1585 the modification time of the file after the file has been 1586 written with conflict markers (@pxref{Conflicts example}). 1587 Thus if @var{conflict} is subsequently the same as the actual 1588 modification time of the file it means that the user 1589 has obviously not resolved the conflict. @var{options} 1590 contains sticky options (for example @samp{-kb} for a 1591 binary file). @var{tagdate} contains @samp{T} followed 1592 by a tag name, or @samp{D} for a date, followed by a 1593 sticky tag or date. Note that if @var{timestamp} 1594 contains a pair of timestamps separated by a space, 1595 rather than a single timestamp, you are dealing with a 1596 version of @sc{cvs} earlier than @sc{cvs} 1.5 (not 1597 documented here). 1598 1599 The timezone on the timestamp in CVS/Entries (local or 1600 universal) should be the same as the operating system 1601 stores for the timestamp of the file itself. For 1602 example, on Unix the file's timestamp is in universal 1603 time (UT), so the timestamp in CVS/Entries should be 1604 too. On @sc{vms}, the file's timestamp is in local 1605 time, so @sc{cvs} on @sc{vms} should use local time. 1606 This rule is so that files do not appear to be modified 1607 merely because the timezone changed (for example, to or 1608 from summer time). 1609 @c See comments and calls to gmtime() and friends in 1610 @c src/vers_ts.c (function time_stamp). 1611 1612 If the first character of a line in @file{Entries} is 1613 @samp{D}, then it indicates a subdirectory. @samp{D} 1614 on a line all by itself indicates that the program 1615 which wrote the @file{Entries} file does record 1616 subdirectories (therefore, if there is such a line and 1617 no other lines beginning with @samp{D}, one knows there 1618 are no subdirectories). Otherwise, the line looks 1619 like: 1620 1621 @example 1622 D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} 1623 @end example 1624 1625 @noindent 1626 where @var{name} is the name of the subdirectory, and 1627 all the @var{filler} fields should be silently ignored, 1628 for future expansion. Programs which modify 1629 @code{Entries} files should preserve these fields. 1630 1631 The 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 1636 This file does not record any information beyond that 1637 in @file{Entries}, but it does provide a way to update 1638 the information without having to rewrite the entire 1639 @file{Entries} file, including the ability to preserve 1640 the information even if the program writing 1641 @file{Entries} and @file{Entries.Log} abruptly aborts. 1642 Programs which are reading the @file{Entries} file 1643 should also check for @file{Entries.Log}. If the latter 1644 exists, they should read @file{Entries} and then apply 1645 the changes mentioned in @file{Entries.Log}. After 1646 applying the changes, the recommended practice is to 1647 rewrite @file{Entries} and then delete @file{Entries.Log}. 1648 The format of a line in @file{Entries.Log} is a single 1649 character command followed by a space followed by a 1650 line 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, 1654 or any other character to indicate that the entire line 1655 in @file{Entries.Log} should be silently ignored (for 1656 future expansion). If the second character of the line 1657 in @file{Entries.Log} is not a space, then it was 1658 written by an older version of @sc{cvs} (not documented 1659 here). 1660 1661 Programs which are writing rather than reading can 1662 safely 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 1667 This is a temporary file. Recommended usage is to 1668 write a new entries file to @file{Entries.Backup}, and 1669 then 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 1674 The only relevant thing about this file is whether it 1675 exists or not. If it exists, then it means that only 1676 part of a directory was gotten and @sc{cvs} will 1677 not create additional files in that directory. To 1678 clear it, use the @code{update} command with the 1679 @samp{-d} option, which will get the additional files 1680 and 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 1699 This file contains per-directory sticky tags or dates. 1700 The first character is @samp{T} for a branch tag, 1701 @samp{N} for a non-branch tag, or @samp{D} for a date, 1702 or another character to mean the file should be 1703 silently ignored, for future expansion. This character 1704 is followed by the tag or date. Note that 1705 per-directory sticky tags or dates are used for things 1706 like applying to files which are newly added; they 1707 might not be the same as the sticky tags or dates on 1708 individual files. For general information on sticky 1709 tags 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 1720 This file stores notifications (for example, for 1721 @code{edit} or @code{unedit}) which have not yet been 1722 sent to the server. Its format is not yet documented 1723 here. 1724 1725 @cindex Notify.tmp file, in CVS directory 1726 @cindex CVS/Notify.tmp file 1727 @item Notify.tmp 1728 This file is to @file{Notify} as @file{Entries.Backup} 1729 is to @file{Entries}. That is, to write @file{Notify}, 1730 first write the new contents to @file{Notify.tmp} and 1731 then (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 1737 If watches are in use, then an @code{edit} command 1738 stores the original copy of the file in the @file{Base} 1739 directory. This allows the @code{unedit} command to 1740 operate even if it is unable to communicate with the 1741 server. 1742 1743 @cindex Baserev file, in CVS directory 1744 @cindex CVS/Baserev file 1745 @item Baserev 1746 The file lists the revision for each of the files in 1747 the @file{Base} directory. The format is: 1748 1749 @example 1750 B@var{name}/@var{rev}/@var{expansion} 1751 @end example 1752 1753 @noindent 1754 where @var{expansion} should be ignored, to allow for 1755 future expansion. 1756 1757 @cindex Baserev.tmp file, in CVS directory 1758 @cindex CVS/Baserev.tmp file 1759 @item Baserev.tmp 1760 This file is to @file{Baserev} as @file{Entries.Backup} 1761 is to @file{Entries}. That is, to write @file{Baserev}, 1762 first write the new contents to @file{Baserev.tmp} and 1763 then (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 1769 This file contains the template specified by the 1770 @file{rcsinfo} file (@pxref{rcsinfo}). It is only used 1771 by 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 1792 The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative 1793 files}. @xref{Administrative files}, for a complete description. 1794 You can use @sc{cvs} without any of these files, but 1795 some commands work better when at least the 1796 @file{modules} file is properly set up. 1797 1798 The most important of these files is the @file{modules} 1799 file. It defines all modules in the repository. This 1800 is 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 1805 CVSROOT CVSROOT 1806 modules CVSROOT modules 1807 cvs gnu/cvs 1808 rcs gnu/rcs 1809 diff gnu/diff 1810 tc yoyodyne/tc 1811 @end example 1812 1813 The @file{modules} file is line oriented. In its 1814 simplest form each line contains the name of the 1815 module, whitespace, and the directory where the module 1816 resides. The directory is a path relative to 1817 @code{$CVSROOT}. The last four lines in the example 1818 above 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 1823 The line that defines the module called @samp{modules} 1824 uses features that are not explained here. 1825 @xref{modules}, for a full explanation of all the 1826 available 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 1833 You edit the administrative files in the same way that you would edit 1834 any other module. Use @samp{cvs checkout CVSROOT} to get a working 1835 copy, edit it, and commit your changes in the normal way. 1836 1837 It is possible to commit an erroneous administrative 1838 file. You can often fix the error and check in a new 1839 revision, but sometimes a particularly bad error in the 1840 administrative file makes it impossible to commit new 1841 revisions. 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 1856 In some situations it is a good idea to have more than 1857 one repository, for instance if you have two 1858 development groups that work on separate projects 1859 without sharing any code. All you have to do to have 1860 several repositories is to specify the appropriate 1861 repository, using the @code{CVSROOT} environment 1862 variable, the @samp{-d} option to @sc{cvs}, or (once 1863 you have checked out a working directory) by simply 1864 allowing @sc{cvs} to use the repository that was used 1865 to check out the working directory 1866 (@pxref{Specifying a repository}). 1867 1868 The big advantage of having multiple repositories is 1869 that they can reside on different servers. With @sc{cvs} 1870 version 1.10, a single command cannot recurse into 1871 directories from different repositories. With development 1872 versions of @sc{cvs}, you can check out code from multiple 1873 servers into your working directory. @sc{cvs} will 1874 recurse and handle all the details of making 1875 connections to as many server machines as necessary to 1876 perform the requested command. Here is an example of 1877 how to set up a working directory: 1878 1879 @example 1880 cvs -d server1:/cvs co dir1 1881 cd dir1 1882 cvs -d server2:/root co sdir 1883 cvs update 1884 @end example 1885 1886 The @code{cvs co} commands set up the working 1887 directory, and then the @code{cvs update} command will 1888 contact server2, to update the dir1/sdir subdirectory, 1889 and 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 1902 This section describes how to set up a @sc{cvs} repository for any 1903 sort of access method. After completing the setup described in this 1904 section, you should be able to access your @sc{cvs} repository immediately 1905 via the local access method and several remote access methods. For 1906 more information on setting up remote access to the repository you create 1907 in this section, please read the section on @xref{Remote repositories}. 1908 1909 To set up a @sc{cvs} repository, first choose the 1910 machine and disk on which you want to store the 1911 revision history of the source files. CPU and memory 1912 requirements are modest, so most machines should be 1913 adequate. 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 1919 To estimate disk space 1920 requirements, if you are importing RCS files from 1921 another system, the size of those files is the 1922 approximate initial size of your repository, or if you 1923 are starting without any version history, a rule of 1924 thumb is to allow for the server approximately three 1925 times the size of the code to be under @sc{cvs} for the 1926 repository (you will eventually outgrow this, but not 1927 for a while). On the machines on which the developers 1928 will be working, you'll want disk space for 1929 approximately one working directory for each developer 1930 (either the entire tree or a portion of it, depending 1931 on what each developer uses). 1932 1933 The repository should be accessible 1934 (directly or via a networked file system) from all 1935 machines which want to use @sc{cvs} in server or local 1936 mode; the client machines need not have any access to 1937 it other than via the @sc{cvs} protocol. It is not 1938 possible to use @sc{cvs} to read from a repository 1939 which one only has read access to; @sc{cvs} needs to be 1940 able to create lock files (@pxref{Concurrency}). 1941 1942 To create a repository, run the @code{cvs init} 1943 command (@pxref{init}). 1944 1945 @node Backing up 1946 @section Backing up a repository 1947 @cindex Repository, backing up 1948 @cindex Backing up, repository 1949 1950 There is nothing particularly magical about the files 1951 in the repository; for the most part it is possible to 1952 back them up just like any other files. However, there 1953 are a few issues to consider. 1954 1955 @cindex Locks, cvs, and backups 1956 @cindex #cvs.rfl, and backups 1957 The first is that to be paranoid, one should either not 1958 use @sc{cvs} during the backup, or have the backup 1959 program lock @sc{cvs} while doing the backup. To not 1960 use @sc{cvs}, you might forbid logins to machines which 1961 can access the repository, turn off your @sc{cvs} 1962 server, or similar mechanisms. The details would 1963 depend on your operating system and how you have 1964 @sc{cvs} set up. To lock @sc{cvs}, you would create 1965 @file{#cvs.rfl} locks in each repository directory. 1966 See @ref{Concurrency}, for more on @sc{cvs} locks. 1967 Having said all this, if you just back up without any 1968 of these precautions, the results are unlikely to be 1969 particularly dire. Restoring from backup, the 1970 repository might be in an inconsistent state, but this 1971 would not be particularly hard to fix manually. 1972 1973 When you restore a repository from backup, assuming 1974 that changes in the repository were made after the time 1975 of the backup, working directories which were not 1976 affected by the failure may refer to revisions which no 1977 longer exist in the repository. Trying to run @sc{cvs} 1978 in such directories will typically produce an error 1979 message. One way to get those changes back into the 1980 repository is as follows: 1981 1982 @itemize @bullet 1983 @item 1984 Get a new working directory. 1985 1986 @item 1987 Copy the files from the working directory from before 1988 the failure over to the new working directory (do not 1989 copy the contents of the @file{CVS} directories, of 1990 course). 1991 1992 @item 1993 Working in the new working directory, use commands such 1994 as @code{cvs update} and @code{cvs diff} to figure out 1995 what has changed, and then when you are ready, commit 1996 the changes into the repository. 1997 @end itemize 1998 1999 @node Moving a repository 2000 @section Moving a repository 2001 @cindex Repository, moving 2002 @cindex Moving a repository 2003 @cindex Copying a repository 2004 2005 Just as backing up the files in the repository is 2006 pretty much like backing up any other files, if you 2007 need to move a repository from one place to another it 2008 is also pretty much like just moving any other 2009 collection of files. 2010 2011 The main thing to consider is that working directories 2012 point to the repository. The simplest way to deal with 2013 a moved repository is to just get a fresh working 2014 directory after the move. Of course, you'll want to 2015 make sure that the old working directory had been 2016 checked in before the move, or you figured out some 2017 other way to make sure that you don't lose any 2018 changes. If you really do want to reuse the existing 2019 working directory, it should be possible with manual 2020 surgery on the @file{CVS/Repository} files. You can 2021 see @ref{Working directory storage}, for information on 2022 the @file{CVS/Repository} and @file{CVS/Root} files, but 2023 unless you are sure you want to bother, it probably 2024 isn't worth it. 2025 @c FIXME: Surgery on CVS/Repository should be avoided 2026 @c by making RELATIVE_REPOS the default. 2027 @c FIXME-maybe: might want some documented way to 2028 @c change the CVS/Root files in some particular tree. 2029 @c But then again, I don't know, maybe just having 2030 @c people do this in perl/shell/&c isn't so bad... 2031 2032 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2033 @node Remote repositories 2034 @section Remote repositories 2035 @cindex Repositories, remote 2036 @cindex Remote repositories 2037 @cindex Client/Server Operation 2038 @cindex Server, CVS 2039 @cindex Remote repositories, port specification 2040 @cindex Repositories, remote, port specification 2041 @cindex Client/Server Operation, port specification 2042 @cindex pserver (client/server connection method), port specification 2043 @cindex kserver (client/server connection method), port specification 2044 @cindex gserver (client/server connection method), port specification 2045 @cindex port, specifying for remote repositories 2046 2047 Your working copy of the sources can be on a 2048 different machine than the repository. Using @sc{cvs} 2049 in this manner is known as @dfn{client/server} 2050 operation. You run @sc{cvs} on a machine which can 2051 mount your working directory, known as the 2052 @dfn{client}, and tell it to communicate to a machine 2053 which can mount the repository, known as the 2054 @dfn{server}. Generally, using a remote 2055 repository is just like using a local one, except that 2056 the format of the repository name is: 2057 2058 @example 2059 [:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 2060 @end example 2061 2062 Specifying a password in the repository name is not recommended during 2063 checkout, since this will cause @sc{cvs} to store a cleartext copy of the 2064 password in each created directory. @code{cvs login} first instead 2065 (@pxref{Password authentication client}). 2066 2067 The details of exactly what needs to be set up depend 2068 on how you are connecting to the server. 2069 2070 @c Should we try to explain which platforms are which? 2071 @c Platforms like unix and VMS, which only allow 2072 @c privileged programs to bind to sockets <1024 lose on 2073 @c :server: 2074 @c Platforms like Mac and VMS, whose rsh program is 2075 @c unusable or nonexistent, lose on :ext: 2076 @c Platforms like OS/2 and NT probably could plausibly 2077 @c default either way (modulo -b troubles). 2078 2079 @menu 2080 * Server requirements:: Memory and other resources for servers 2081 * The connection method:: Connection methods and method options 2082 * Connecting via rsh:: Using the @code{rsh} program to connect 2083 * Password authenticated:: Direct connections using passwords 2084 * GSSAPI authenticated:: Direct connections using GSSAPI 2085 * Kerberos authenticated:: Direct connections with Kerberos 2086 * Connecting via fork:: Using a forked @code{cvs server} to connect 2087 * Write proxies:: Distributing load across several CVS servers 2088 @end menu 2089 2090 @node Server requirements 2091 @subsection Server requirements 2092 2093 The quick answer to what sort of machine is suitable as 2094 a server is that requirements are modest---a server 2095 with 32M of memory or even less can handle a fairly 2096 large source tree with a fair amount of activity. 2097 @c Say something about CPU speed too? I'm even less sure 2098 @c what to say on that subject... 2099 2100 The real answer, of course, is more complicated. 2101 Estimating the known areas of large memory consumption 2102 should be sufficient to estimate memory requirements. 2103 There are two such areas documented here; other memory 2104 consumption should be small by comparison (if you find 2105 that is not the case, let us know, as described in 2106 @ref{BUGS}, so we can update this documentation). 2107 2108 The first area of big memory consumption is large 2109 checkouts, when using the @sc{cvs} server. The server 2110 consists of two processes for each client that it is 2111 serving. Memory consumption on the child process 2112 should remain fairly small. Memory consumption on the 2113 parent process, particularly if the network connection 2114 to the client is slow, can be expected to grow to 2115 slightly more than the size of the sources in a single 2116 directory, or two megabytes, whichever is larger. 2117 @c "two megabytes" of course is SERVER_HI_WATER. But 2118 @c we don't mention that here because we are 2119 @c documenting the default configuration of CVS. If it 2120 @c is a "standard" thing to change that value, it 2121 @c should be some kind of run-time configuration. 2122 @c 2123 @c See cvsclient.texi for more on the design decision 2124 @c to not have locks in place while waiting for the 2125 @c client, which is what results in memory consumption 2126 @c as high as this. 2127 2128 Multiplying the size of each @sc{cvs} server by the 2129 number of servers which you expect to have active at 2130 one time should give an idea of memory requirements for 2131 the server. For the most part, the memory consumed by 2132 the parent process probably can be swap space rather 2133 than physical memory. 2134 @c Has anyone verified that notion about swap space? 2135 @c I say it based pretty much on guessing that the 2136 @c ->text of the struct buffer_data only gets accessed 2137 @c in a first in, first out fashion, but I haven't 2138 @c looked very closely. 2139 2140 @c What about disk usage in /tmp on the server? I think that 2141 @c it can be substantial, but I haven't looked at this 2142 @c again and tried to figure it out ("cvs import" is 2143 @c probably the worst case...). 2144 2145 The second area of large memory consumption is 2146 @code{diff}, when checking in large files. This is 2147 required even for binary files. The rule of thumb is 2148 to allow about ten times the size of the largest file 2149 you will want to check in, although five times may be 2150 adequate. For example, if you want to check in a file 2151 which is 10 megabytes, you should have 100 megabytes of 2152 memory on the machine doing the checkin (the server 2153 machine for client/server, or the machine running 2154 @sc{cvs} for non-client/server). This can be swap 2155 space rather than physical memory. Because the memory 2156 is only required briefly, there is no particular need 2157 to allow memory for more than one such checkin at a 2158 time. 2159 @c The 5-10 times rule of thumb is from Paul Eggert for 2160 @c GNU diff. I don't think it is in the GNU diff 2161 @c manual or anyplace like that. 2162 @c 2163 @c Probably we could be saying more about 2164 @c non-client/server CVS. 2165 @c I would guess for non-client/server CVS in an NFS 2166 @c environment the biggest issues are the network and 2167 @c the NFS server. 2168 2169 Resource consumption for the client is even more 2170 modest---any machine with enough capacity to run the 2171 operating system in question should have little 2172 trouble. 2173 @c Is that true? I think the client still wants to 2174 @c (bogusly) store entire files in memory at times. 2175 2176 For information on disk space requirements, see 2177 @ref{Creating a repository}. 2178 2179 @node The connection method 2180 @subsection The connection method 2181 2182 In its simplest form, the @var{method} portion of the repository string 2183 (@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork}, 2184 @samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some 2185 platforms, @samp{server}. 2186 2187 If @var{method} is not specified, and the repository 2188 name starts with a @samp{/}, then the default is @code{local}. 2189 If @var{method} is not specified, and the repository 2190 name does not start with a @samp{/}, then the default is @code{ext} 2191 or @code{server}, depending on your platform; both the @samp{ext} 2192 and @samp{server} methods are described in @ref{Connecting via rsh}. 2193 2194 @cindex connection method options 2195 @cindex options, connection method 2196 The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection 2197 methods all accept optional method options, specified as part of the 2198 @var{method} string, like so: 2199 2200 @example 2201 :@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data} 2202 @end example 2203 2204 @sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though 2205 it may sometimes be sensitive to the case of @var{arg}. The possible method 2206 options are as follows: 2207 2208 @table @code 2209 @cindex CVS_PROXY_PORT 2210 @cindex proxy, method option 2211 @cindex proxyport, method option 2212 @cindex proxies, web, connecting via 2213 @cindex web proxies, connecting via 2214 @cindex proxies, HTTP, connecting via 2215 @cindex HTTP proxies, connecting via 2216 @item proxy=@var{hostname} 2217 @itemx proxyport=@var{port} 2218 These two method options can be used to connect via an HTTP tunnel style web 2219 proxy. @var{hostname} should be the name of the HTTP proxy server to connect 2220 through and @var{port} is the port number on the HTTP proxy server to connect 2221 via. @var{port} defaults to 8080. 2222 2223 @strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy 2224 server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.} 2225 2226 For example, to connect pserver via a web proxy listening on port 8000 of 2227 www.myproxy.net, you would use a method of: 2228 2229 @example 2230 :pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string} 2231 @end example 2232 2233 @strong{NOTE: In the above example, @var{pserver_connection_string} is still 2234 required to connect and authenticate to the CVS server, as noted in the 2235 upcoming sections on password authentication, @code{gserver}, and 2236 @code{kserver}. The example above only demonstrates a modification to the 2237 @var{method} portion of the repository name.} 2238 2239 These options first appeared in @sc{cvs} version 1.12.7 and are valid as 2240 modifcations to the @code{gserver} and @code{pserver} connection methods. 2241 2242 @cindex CVS_RSH method option 2243 @item CVS_RSH=@var{path} 2244 This method option can be used with the @code{ext} method to specify the path 2245 the @sc{cvs} client will use to find the remote shell used to contact the 2246 @sc{cvs} server and takes precedence over any path specified in the 2247 @code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}). For 2248 example, to connect to a @sc{cvs} server via the local 2249 @file{/path/to/ssh/command} command, you could choose to specify the following 2250 @var{path} via the @code{CVS_RSH} method option: 2251 2252 @example 2253 :ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string} 2254 @end example 2255 2256 This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2257 as a modifcation to the @code{ext} connection method. 2258 2259 @cindex CVS_SERVER method option 2260 @item CVS_SERVER=@var{path} 2261 This method option can be used with the @code{ext} and @code{fork} methods to 2262 specify the path @sc{cvs} will use to find the @sc{cvs} executable on the 2263 @sc{cvs} server and takes precedence over any path specified in the 2264 @code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}). For 2265 example, to select the remote @file{/path/to/cvs/command} executable as your 2266 @sc{cvs} server application on the @sc{cvs} server machine, you could choose to 2267 specify the following @var{path} via the @code{CVS_SERVER} method option: 2268 2269 @example 2270 :ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string} 2271 @end example 2272 2273 @noindent 2274 or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your 2275 @code{$PATH} on the @sc{cvs} server: 2276 2277 @example 2278 :ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string} 2279 @end example 2280 2281 This method option first appeared in @sc{cvs} version 1.12.11 and is valid 2282 as a modifcation to both the @code{ext} and @code{fork} connection methods. 2283 2284 @cindex Redirect, method option 2285 @item Redirect=@var{boolean-state} 2286 The @code{Redirect} method option determines whether the @sc{cvs} client will 2287 allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually 2288 for write requests, as in a write proxy setup. 2289 2290 A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config} 2291 file options is acceptable here (@pxref{config}). For example, @samp{on}, 2292 @samp{off}, @samp{true}, and @samp{false} are all valid values for 2293 @var{boolean-state}. @var{boolean-state} for the @code{Redirect} method option 2294 defaults to @samp{on}. 2295 2296 This option will have no effect when talking to any non-secondary @sc{cvs} 2297 server. For more on write proxies and secondary servers, please see 2298 @ref{Write proxies}. 2299 2300 This method option first appeared in @sc{cvs} version 1.12.11 and is valid only 2301 as a modifcation to the @code{ext} connection method. 2302 @end table 2303 2304 As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER} 2305 options, a method specification like the following would work: 2306 2307 @example 2308 :ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command: 2309 @end example 2310 2311 This means that you would not need to have 2312 the @code{CVS_SERVER} or @code{CVS_RSH} environment 2313 variables set correctly. See @ref{Connecting via rsh}, for more details on 2314 these environment variables. 2315 2316 @node Connecting via rsh 2317 @subsection Connecting with rsh 2318 2319 @cindex rsh 2320 @sc{cvs} uses the @samp{rsh} protocol to perform these 2321 operations, so the remote user host needs to have a 2322 @file{.rhosts} file which grants access to the local 2323 user. Note that the program that @sc{cvs} uses for this 2324 purpose may be specified using the @file{--with-rsh} 2325 flag to configure. 2326 2327 For example, suppose you are the user @samp{mozart} on 2328 the local machine @samp{toe.example.com}, and the 2329 server machine is @samp{faun.example.org}. On 2330 faun, put the following line into the file 2331 @file{.rhosts} in @samp{bach}'s home directory: 2332 2333 @example 2334 toe.example.com mozart 2335 @end example 2336 2337 @noindent 2338 Then test that @samp{rsh} is working with 2339 2340 @example 2341 rsh -l bach faun.example.org 'echo $PATH' 2342 @end example 2343 2344 @cindex CVS_SERVER, environment variable 2345 Next you have to make sure that @code{rsh} will be able 2346 to find the server. Make sure that the path which 2347 @code{rsh} printed in the above example includes the 2348 directory containing a program named @code{cvs} which 2349 is the server. You need to set the path in 2350 @file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 2351 or @file{.profile}. Alternately, you can set the 2352 environment variable @code{CVS_SERVER} on the client 2353 machine to the filename of the server you want to use, 2354 for example @file{/usr/local/bin/cvs-1.6}. 2355 For the @code{ext} and @code{fork} methods, you may 2356 also specify @var{CVS_SERVER} as an otpion in the 2357 @var{CVSROOT} so that you may use different servers for 2358 differnt roots. See @ref{Remote repositories} for more 2359 details. 2360 2361 There is no need to edit @file{inetd.conf} or start a 2362 @sc{cvs} server daemon. 2363 2364 @cindex :server:, setting up 2365 @cindex :ext:, setting up 2366 @cindex Kerberos, using kerberized rsh 2367 @cindex SSH (rsh replacement) 2368 @cindex rsh replacements (Kerberized, SSH, &c) 2369 There are two access methods that you use in @code{CVSROOT} 2370 for rsh. @code{:server:} specifies an internal rsh 2371 client, which is supported only by some @sc{cvs} ports. 2372 @code{:ext:} specifies an external rsh program. By 2373 default this is @code{rsh} (unless otherwise specified 2374 by the @file{--with-rsh} flag to configure) but you may set the 2375 @code{CVS_RSH} environment variable to invoke another 2376 program which can access the remote server (for 2377 example, @code{remsh} on HP-UX 9 because @code{rsh} is 2378 something different). It must be a program which can 2379 transmit data to and from the server without modifying 2380 it; for example the Windows NT @code{rsh} is not 2381 suitable since it by default translates between CRLF 2382 and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 2383 to @code{rsh} to get around this, but since this could 2384 potentially cause problems for programs other than the 2385 standard @code{rsh}, it may change in the future. If 2386 you set @code{CVS_RSH} to @code{SSH} or some other rsh 2387 replacement, the instructions in the rest of this 2388 section concerning @file{.rhosts} and so on are likely 2389 to be inapplicable; consult the documentation for your rsh 2390 replacement. 2391 2392 You may choose to specify the @var{CVS_RSH} option as a method option 2393 in the @var{CVSROOT} string to allow you to use different connection tools 2394 for different roots (@pxref{The connection method}). For example, allowing 2395 some roots to use @code{CVS_RSH=remsh} and some to use 2396 @code{CVS_RSH=ssh} for the @code{ext} method. See also 2397 the @ref{Remote repositories} for more details. 2398 @c See also the comment in src/client.c for rationale 2399 @c concerning "rsh" being the default and never 2400 @c "remsh". 2401 2402 Continuing our example, supposing you want to access 2403 the module @file{foo} in the repository 2404 @file{/usr/local/cvsroot/}, on machine 2405 @file{faun.example.org}, you are ready to go: 2406 2407 @example 2408 cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2409 @end example 2410 2411 @noindent 2412 (The @file{bach@@} can be omitted if the username is 2413 the same on both the local and remote hosts.) 2414 2415 @c Should we mention "rsh host echo hi" and "rsh host 2416 @c cat" (the latter followed by typing text and ^D) 2417 @c as troubleshooting techniques? Probably yes 2418 @c (people tend to have trouble setting this up), 2419 @c but this kind of thing can be hard to spell out. 2420 2421 @node Password authenticated 2422 @subsection Direct connection with password authentication 2423 2424 The @sc{cvs} client can also connect to the server 2425 using a password protocol. This is particularly useful 2426 if using @code{rsh} is not feasible (for example, 2427 the server is behind a firewall), and Kerberos also is 2428 not available. 2429 2430 To use this method, it is necessary to make 2431 some adjustments on both the server and client sides. 2432 2433 @menu 2434 * Password authentication server:: Setting up the server 2435 * Password authentication client:: Using the client 2436 * Password authentication security:: What this method does and does not do 2437 @end menu 2438 2439 @node Password authentication server 2440 @subsubsection Setting up the server for password authentication 2441 2442 First of all, you probably want to tighten the 2443 permissions on the @file{$CVSROOT} and 2444 @file{$CVSROOT/CVSROOT} directories. See @ref{Password 2445 authentication security}, for more details. 2446 2447 @cindex pserver (subcommand) 2448 @cindex Remote repositories, port specification 2449 @cindex Repositories, remote, port specification 2450 @cindex Client/Server Operation, port specification 2451 @cindex pserver (client/server connection method), port specification 2452 @cindex kserver (client/server connection method), port specification 2453 @cindex gserver (client/server connection method), port specification 2454 @cindex port, specifying for remote repositories 2455 @cindex Password server, setting up 2456 @cindex Authenticating server, setting up 2457 @cindex inetd, configuring for pserver 2458 @cindex xinetd, configuring for pserver 2459 @c FIXME: this isn't quite right regarding port 2460 @c numbers; CVS looks up "cvspserver" in 2461 @c /etc/services (on unix, but what about non-unix?). 2462 On the server side, the file @file{/etc/inetd.conf} 2463 needs to be edited so @code{inetd} knows to run the 2464 command @code{cvs pserver} when it receives a 2465 connection on the right port. By default, the port 2466 number is 2401; it would be different if your client 2467 were compiled with @code{CVS_AUTH_PORT} defined to 2468 something else, though. This can also be specified in the CVSROOT variable 2469 (@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 2470 environment variable (@pxref{Environment variables}). 2471 2472 If your @code{inetd} allows raw port numbers in 2473 @file{/etc/inetd.conf}, then the following (all on a 2474 single line in @file{inetd.conf}) should be sufficient: 2475 2476 @example 2477 2401 stream tcp nowait root /usr/local/bin/cvs 2478 cvs -f --allow-root=/usr/cvsroot pserver 2479 @end example 2480 2481 @noindent 2482 (You could also use the 2483 @samp{-T} option to specify a temporary directory.) 2484 2485 The @samp{--allow-root} option specifies the allowable 2486 @sc{cvsroot} directory. Clients which attempt to use a 2487 different @sc{cvsroot} directory will not be allowed to 2488 connect. If there is more than one @sc{cvsroot} 2489 directory which you want to allow, repeat the option. 2490 (Unfortunately, many versions of @code{inetd} have very small 2491 limits on the number of arguments and/or the total length 2492 of the command. The usual solution to this problem is 2493 to have @code{inetd} run a shell script which then invokes 2494 @sc{cvs} with the necessary arguments.) 2495 2496 If your @code{inetd} wants a symbolic service 2497 name instead of a raw port number, then put this in 2498 @file{/etc/services}: 2499 2500 @example 2501 cvspserver 2401/tcp 2502 @end example 2503 2504 @noindent 2505 and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 2506 2507 If your system uses @code{xinetd} instead of @code{inetd}, 2508 the procedure is slightly different. 2509 Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2510 2511 @example 2512 service cvspserver 2513 @{ 2514 port = 2401 2515 socket_type = stream 2516 protocol = tcp 2517 wait = no 2518 user = root 2519 passenv = PATH 2520 server = /usr/local/bin/cvs 2521 server_args = -f --allow-root=/usr/cvsroot pserver 2522 @} 2523 @end example 2524 2525 @noindent 2526 (If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2527 the @code{port} line.) 2528 2529 Once the above is taken care of, restart your 2530 @code{inetd}, or do whatever is necessary to force it 2531 to reread its initialization files. 2532 2533 If you are having trouble setting this up, see 2534 @ref{Connection}. 2535 2536 @cindex CVS passwd file 2537 @cindex passwd (admin file) 2538 Because the client stores and transmits passwords in 2539 cleartext (almost---see @ref{Password authentication 2540 security}, for details), a separate @sc{cvs} password 2541 file is generally used, so people don't compromise 2542 their regular passwords when they access the 2543 repository. This file is 2544 @file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 2545 administrative files}). It uses a colon-separated 2546 format, similar to @file{/etc/passwd} on Unix systems, 2547 except that it has fewer fields: @sc{cvs} username, 2548 optional password, and an optional system username for 2549 @sc{cvs} to run as if authentication succeeds. Here is 2550 an example @file{passwd} file with five entries: 2551 2552 @example 2553 anonymous: 2554 bach:ULtgRLXo7NRxs 2555 spwang:1sOp854gDF3DY 2556 melissa:tGX1fS8sun6rY:pubcvs 2557 qproj:XR4EZcEs0szik:pubcvs 2558 @end example 2559 2560 @noindent 2561 (The passwords are encrypted according to the standard 2562 Unix @code{crypt()} function, so it is possible to 2563 paste in passwords directly from regular Unix 2564 @file{/etc/passwd} files.) 2565 2566 The first line in the example will grant access to any 2567 @sc{cvs} client attempting to authenticate as user 2568 @code{anonymous}, no matter what password they use, 2569 including an empty password. (This is typical for 2570 sites granting anonymous read-only access; for 2571 information on how to do the "read-only" part, see 2572 @ref{Read-only access}.) 2573 2574 The second and third lines will grant access to 2575 @code{bach} and @code{spwang} if they supply their 2576 respective plaintext passwords. 2577 2578 @cindex User aliases 2579 The fourth line will grant access to @code{melissa}, if 2580 she supplies the correct password, but her @sc{cvs} 2581 operations will actually run on the server side under 2582 the system user @code{pubcvs}. Thus, there need not be 2583 any system user named @code{melissa}, but there 2584 @emph{must} be one named @code{pubcvs}. 2585 2586 The fifth line shows that system user identities can be 2587 shared: any client who successfully authenticates as 2588 @code{qproj} will actually run as @code{pubcvs}, just 2589 as @code{melissa} does. That way you could create a 2590 single, shared system user for each project in your 2591 repository, and give each developer their own line in 2592 the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 2593 username on each line would be different, but the 2594 system username would be the same. The reason to have 2595 different @sc{cvs} usernames is that @sc{cvs} will log their 2596 actions under those names: when @code{melissa} commits 2597 a change to a project, the checkin is recorded in the 2598 project's history under the name @code{melissa}, not 2599 @code{pubcvs}. And the reason to have them share a 2600 system username is so that you can arrange permissions 2601 in the relevant area of the repository such that only 2602 that account has write-permission there. 2603 2604 If the system-user field is present, all 2605 password-authenticated @sc{cvs} commands run as that 2606 user; if no system user is specified, @sc{cvs} simply 2607 takes the @sc{cvs} username as the system username and 2608 runs commands as that user. In either case, if there 2609 is no such user on the system, then the @sc{cvs} 2610 operation will fail (regardless of whether the client 2611 supplied a valid password). 2612 2613 The password and system-user fields can both be omitted 2614 (and if the system-user field is omitted, then also 2615 omit the colon that would have separated it from the 2616 encrypted password). For example, this would be a 2617 valid @file{$CVSROOT/CVSROOT/passwd} file: 2618 2619 @example 2620 anonymous::pubcvs 2621 fish:rKa5jzULzmhOo:kfogel 2622 sussman:1sOp854gDF3DY 2623 @end example 2624 2625 @noindent 2626 When the password field is omitted or empty, then the 2627 client's authentication attempt will succeed with any 2628 password, including the empty string. However, the 2629 colon after the @sc{cvs} username is always necessary, 2630 even if the password is empty. 2631 2632 @sc{cvs} can also fall back to use system authentication. 2633 When authenticating a password, the server first checks 2634 for the user in the @file{$CVSROOT/CVSROOT/passwd} 2635 file. If it finds the user, it will use that entry for 2636 authentication as described above. But if it does not 2637 find the user, or if the @sc{cvs} @file{passwd} file 2638 does not exist, then the server can try to authenticate 2639 the username and password using the operating system's 2640 user-lookup routines (this "fallback" behavior can be 2641 disabled by setting @code{SystemAuth=no} in the 2642 @sc{cvs} @file{config} file, @pxref{config}). 2643 2644 The default fallback behavior is to look in 2645 @file{/etc/passwd} for this system user unless your 2646 system has PAM (Pluggable Authentication Modules) 2647 and your @sc{cvs} server executable was configured to 2648 use it at compile time (using @code{./configure --enable-pam} - see the 2649 INSTALL file for more). In this case, PAM will be consulted instead. 2650 This means that @sc{cvs} can be configured to use any password 2651 authentication source PAM can be configured to use (possibilities 2652 include a simple UNIX password, NIS, LDAP, and others) in its 2653 global configuration file (usually @file{/etc/pam.conf} 2654 or possibly @file{/etc/pam.d/cvs}). See your PAM documentation 2655 for more details on PAM configuration. 2656 2657 Note that PAM is an experimental feature in @sc{cvs} and feedback is 2658 encouraged. Please send a mail to one of the @sc{cvs} mailing lists 2659 (@code{info-cvs@@nongnu.org} or @code{bug-cvs@@nongnu.org}) if you use the 2660 @sc{cvs} PAM support. 2661 2662 @strong{WARNING: Using PAM gives the system administrator much more 2663 flexibility about how @sc{cvs} users are authenticated but 2664 no more security than other methods. See below for more.} 2665 2666 CVS needs an "auth", "account" and "session" module in the 2667 PAM configuration file. A typical PAM configuration 2668 would therefore have the following lines 2669 in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 2670 system @file{/etc/passwd} authentication: 2671 2672 @example 2673 cvs auth required pam_unix.so 2674 cvs account required pam_unix.so 2675 cvs session required pam_unix.so 2676 @end example 2677 2678 The the equivalent @file{/etc/pam.d/cvs} would contain 2679 2680 @example 2681 auth required pam_unix.so 2682 account required pam_unix.so 2683 session required pam_unix.so 2684 @end example 2685 2686 Some systems require a full path to the module so that 2687 @file{pam_unix.so} (Linux) would become something like 2688 @file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris). 2689 See the @file{contrib/pam} subdirectory of the @sc{cvs} 2690 source distribution for further example configurations. 2691 2692 The PAM service name given above as "cvs" is just 2693 the service name in the default configuration and can be 2694 set using 2695 @code{./configure --with-hardcoded-pam-service-name=<pam-service-name>} 2696 before compiling. @sc{cvs} can also be configured to use whatever 2697 name it is invoked as as its PAM service name using 2698 @code{./configure --without-hardcoded-pam-service-name}, but this 2699 feature should not be used if you may not have control of the name 2700 @sc{cvs} will be invoked as. 2701 2702 Be aware, also, that falling back to system 2703 authentication might be a security risk: @sc{cvs} 2704 operations would then be authenticated with that user's 2705 regular login password, and the password flies across 2706 the network in plaintext. See @ref{Password 2707 authentication security} for more on this. 2708 This may be more of a problem with PAM authentication 2709 because it is likely that the source of the system 2710 password is some central authentication service like 2711 LDAP which is also used to authenticate other services. 2712 2713 On the other hand, PAM makes it very easy to change your password 2714 regularly. If they are given the option of a one-password system for 2715 all of their activities, users are often more willing to change their 2716 password on a regular basis. 2717 2718 In the non-PAM configuration where the password is stored in the 2719 @file{CVSROOT/passwd} file, it is difficult to change passwords on a 2720 regular basis since only administrative users (or in some cases 2721 processes that act as an administrative user) are typically given 2722 access to modify this file. Either there needs to be some 2723 hand-crafted web page or set-uid program to update the file, or the 2724 update needs to be done by submitting a request to an administrator to 2725 perform the duty by hand. In the first case, having to remember to 2726 update a separate password on a periodic basis can be difficult. In 2727 the second case, the manual nature of the change will typically mean 2728 that the password will not be changed unless it is absolutely 2729 necessary. 2730 2731 Note that PAM administrators should probably avoid configuring 2732 one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If 2733 OTPs are desired, the administrator may wish to encourage the use of 2734 one of the other Client/Server access methods. See the section on 2735 @pxref{Remote repositories} for a list of other methods. 2736 2737 Right now, the only way to put a password in the 2738 @sc{cvs} @file{passwd} file is to paste it there from 2739 somewhere else. Someday, there may be a @code{cvs 2740 passwd} command. 2741 2742 Unlike many of the files in @file{$CVSROOT/CVSROOT}, it 2743 is normal to edit the @file{passwd} file in-place, 2744 rather than via @sc{cvs}. This is because of the 2745 possible security risks of having the @file{passwd} 2746 file checked out to people's working copies. If you do 2747 want to include the @file{passwd} file in checkouts of 2748 @file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 2749 2750 @c We might also suggest using the @code{htpasswd} command 2751 @c from freely available web servers as well, but that 2752 @c would open up a can of worms in that the users next 2753 @c questions are likely to be "where do I get it?" and 2754 @c "how do I use it?" 2755 @c Also note that htpasswd, at least the version I had, 2756 @c likes to clobber the third field. 2757 2758 @node Password authentication client 2759 @subsubsection Using the client with password authentication 2760 @cindex Login (subcommand) 2761 @cindex Password client, using 2762 @cindex Authenticated client, using 2763 @cindex :pserver:, setting up 2764 To run a @sc{cvs} command on a remote repository via 2765 the password-authenticating server, one specifies the 2766 @code{pserver} protocol, optional username, repository host, an 2767 optional port number, and path to the repository. For example: 2768 2769 @example 2770 cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 2771 @end example 2772 2773 @noindent 2774 or 2775 2776 @example 2777 CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 2778 cvs checkout someproj 2779 @end example 2780 2781 However, unless you're connecting to a public-access 2782 repository (i.e., one where that username doesn't 2783 require a password), you'll need to supply a password or @dfn{log in} first. 2784 Logging in verifies your password with the repository and stores it in a file. 2785 It's done with the @code{login} command, which will 2786 prompt you interactively for the password if you didn't supply one as part of 2787 @var{$CVSROOT}: 2788 2789 @example 2790 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 2791 CVS password: 2792 @end example 2793 2794 @noindent 2795 or 2796 2797 @example 2798 cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 2799 @end example 2800 2801 After you enter the password, @sc{cvs} verifies it with 2802 the server. If the verification succeeds, then that 2803 combination of username, host, repository, and password 2804 is permanently recorded, so future transactions with 2805 that repository won't require you to run @code{cvs 2806 login}. (If verification fails, @sc{cvs} will exit 2807 complaining that the password was incorrect, and 2808 nothing will be recorded.) 2809 2810 The records are stored, by default, in the file 2811 @file{$HOME/.cvspass}. That file's format is 2812 human-readable, and to a degree human-editable, but 2813 note that the passwords are not stored in 2814 cleartext---they are trivially encoded to protect them 2815 from "innocent" compromise (i.e., inadvertent viewing 2816 by a system administrator or other non-malicious 2817 person). 2818 2819 @cindex CVS_PASSFILE, environment variable 2820 You can change the default location of this file by 2821 setting the @code{CVS_PASSFILE} environment variable. 2822 If you use this variable, make sure you set it 2823 @emph{before} @code{cvs login} is run. If you were to 2824 set it after running @code{cvs login}, then later 2825 @sc{cvs} commands would be unable to look up the 2826 password for transmission to the server. 2827 2828 Once you have logged in, all @sc{cvs} commands using 2829 that remote repository and username will authenticate 2830 with the stored password. So, for example 2831 2832 @example 2833 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2834 @end example 2835 2836 @noindent 2837 should just work (unless the password changes on the 2838 server side, in which case you'll have to re-run 2839 @code{cvs login}). 2840 2841 Note that if the @samp{:pserver:} were not present in 2842 the repository specification, @sc{cvs} would assume it 2843 should use @code{rsh} to connect with the server 2844 instead (@pxref{Connecting via rsh}). 2845 2846 Of course, once you have a working copy checked out and 2847 are running @sc{cvs} commands from within it, there is 2848 no longer any need to specify the repository 2849 explicitly, because @sc{cvs} can deduce the repository 2850 from the working copy's @file{CVS} subdirectory. 2851 2852 @c FIXME: seems to me this needs somewhat more 2853 @c explanation. 2854 @cindex Logout (subcommand) 2855 The password for a given remote repository can be 2856 removed from the @code{CVS_PASSFILE} by using the 2857 @code{cvs logout} command. 2858 2859 @node Password authentication security 2860 @subsubsection Security considerations with password authentication 2861 2862 @cindex Security, of pserver 2863 The passwords are stored on the client side in a 2864 trivial encoding of the cleartext, and transmitted in 2865 the same encoding. The encoding is done only to 2866 prevent inadvertent password compromises (i.e., a 2867 system administrator accidentally looking at the file), 2868 and will not prevent even a naive attacker from gaining 2869 the password. 2870 2871 @c FIXME: The bit about "access to the repository 2872 @c implies general access to the system is *not* specific 2873 @c to pserver; it applies to kerberos and SSH and 2874 @c everything else too. Should reorganize the 2875 @c documentation to make this clear. 2876 The separate @sc{cvs} password file (@pxref{Password 2877 authentication server}) allows people 2878 to use a different password for repository access than 2879 for login access. On the other hand, once a user has 2880 non-read-only 2881 access to the repository, she can execute programs on 2882 the server system through a variety of means. Thus, repository 2883 access implies fairly broad system access as well. It 2884 might be possible to modify @sc{cvs} to prevent that, 2885 but no one has done so as of this writing. 2886 @c OpenBSD uses chroot() and copies the repository to 2887 @c provide anonymous read-only access (for details see 2888 @c http://www.openbsd.org/anoncvs.shar). While this 2889 @c closes the most obvious holes, I'm not sure it 2890 @c closes enough holes to recommend it (plus it is 2891 @c *very* easy to accidentally screw up a setup of this 2892 @c type). 2893 2894 Note that because the @file{$CVSROOT/CVSROOT} directory 2895 contains @file{passwd} and other files which are used 2896 to check security, you must control the permissions on 2897 this directory as tightly as the permissions on 2898 @file{/etc}. The same applies to the @file{$CVSROOT} 2899 directory itself and any directory 2900 above it in the tree. Anyone who has write access to 2901 such a directory will have the ability to become any 2902 user on the system. Note that these permissions are 2903 typically tighter than you would use if you are not 2904 using pserver. 2905 @c TODO: Would be really nice to document/implement a 2906 @c scheme where the CVS server can run as some non-root 2907 @c user, e.g. "cvs". CVSROOT/passwd would contain a 2908 @c bunch of entries of the form foo:xxx:cvs (or the "cvs" 2909 @c would be implicit). This would greatly reduce 2910 @c security risks such as those hinted at in the 2911 @c previous paragraph. I think minor changes to CVS 2912 @c might be required but mostly this would just need 2913 @c someone who wants to play with it, document it, &c. 2914 2915 In summary, anyone who gets the password gets 2916 repository access (which may imply some measure of general system 2917 access as well). The password is available to anyone 2918 who can sniff network packets or read a protected 2919 (i.e., user read-only) file. If you want real 2920 security, get Kerberos. 2921 2922 @node GSSAPI authenticated 2923 @subsection Direct connection with GSSAPI 2924 2925 @cindex GSSAPI 2926 @cindex Security, GSSAPI 2927 @cindex :gserver:, setting up 2928 @cindex Kerberos, using :gserver: 2929 GSSAPI is a generic interface to network security 2930 systems such as Kerberos 5. 2931 If you have a working GSSAPI library, you can have 2932 @sc{cvs} connect via a direct @sc{tcp} connection, 2933 authenticating with GSSAPI. 2934 2935 To do this, @sc{cvs} needs to be compiled with GSSAPI 2936 support; when configuring @sc{cvs} it tries to detect 2937 whether GSSAPI libraries using Kerberos version 5 are 2938 present. You can also use the @file{--with-gssapi} 2939 flag to configure. 2940 2941 The connection is authenticated using GSSAPI, but the 2942 message stream is @emph{not} authenticated by default. 2943 You must use the @code{-a} global option to request 2944 stream authentication. 2945 2946 The data transmitted is @emph{not} encrypted by 2947 default. Encryption support must be compiled into both 2948 the client and the server; use the 2949 @file{--enable-encrypt} configure option to turn it on. 2950 You must then use the @code{-x} global option to 2951 request encryption. 2952 2953 GSSAPI connections are handled on the server side by 2954 the same server which handles the password 2955 authentication server; see @ref{Password authentication 2956 server}. If you are using a GSSAPI mechanism such as 2957 Kerberos which provides for strong authentication, you 2958 will probably want to disable the ability to 2959 authenticate via cleartext passwords. To do so, create 2960 an empty @file{CVSROOT/passwd} password file, and set 2961 @code{SystemAuth=no} in the config file 2962 (@pxref{config}). 2963 2964 The GSSAPI server uses a principal name of 2965 cvs/@var{hostname}, where @var{hostname} is the 2966 canonical name of the server host. You will have to 2967 set this up as required by your GSSAPI mechanism. 2968 2969 To connect using GSSAPI, use the @samp{:gserver:} method. For 2970 example, 2971 2972 @example 2973 cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 2974 @end example 2975 2976 @node Kerberos authenticated 2977 @subsection Direct connection with Kerberos 2978 2979 @cindex Kerberos, using :kserver: 2980 @cindex Security, Kerberos 2981 @cindex :kserver:, setting up 2982 The easiest way to use Kerberos is to use the Kerberos 2983 @code{rsh}, as described in @ref{Connecting via rsh}. 2984 The main disadvantage of using rsh is that all the data 2985 needs to pass through additional programs, so it may be 2986 slower. So if you have Kerberos installed you can 2987 connect via a direct @sc{tcp} connection, 2988 authenticating with Kerberos. 2989 2990 This section concerns the Kerberos network security 2991 system, version 4. Kerberos version 5 is supported via 2992 the GSSAPI generic network security interface, as 2993 described in the previous section. 2994 2995 To do this, @sc{cvs} needs to be compiled with Kerberos 2996 support; when configuring @sc{cvs} it tries to detect 2997 whether Kerberos is present or you can use the 2998 @file{--with-krb4} flag to configure. 2999 3000 The data transmitted is @emph{not} encrypted by 3001 default. Encryption support must be compiled into both 3002 the client and server; use the 3003 @file{--enable-encryption} configure option to turn it 3004 on. You must then use the @code{-x} global option to 3005 request encryption. 3006 3007 The CVS client will attempt to connect to port 1999 by default. 3008 3009 @cindex kinit 3010 When you want to use @sc{cvs}, get a ticket in the 3011 usual way (generally @code{kinit}); it must be a ticket 3012 which allows you to log into the server machine. Then 3013 you are ready to go: 3014 3015 @example 3016 cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 3017 @end example 3018 3019 Previous versions of @sc{cvs} would fall back to a 3020 connection via rsh; this version will not do so. 3021 3022 @node Connecting via fork 3023 @subsection Connecting with fork 3024 3025 @cindex fork, access method 3026 @cindex :fork:, setting up 3027 This access method allows you to connect to a 3028 repository on your local disk via the remote protocol. 3029 In other words it does pretty much the same thing as 3030 @code{:local:}, but various quirks, bugs and the like are 3031 those of the remote @sc{cvs} rather than the local 3032 @sc{cvs}. 3033 3034 For day-to-day operations you might prefer either 3035 @code{:local:} or @code{:fork:}, depending on your 3036 preferences. Of course @code{:fork:} comes in 3037 particularly handy in testing or 3038 debugging @code{cvs} and the remote protocol. 3039 Specifically, we avoid all of the network-related 3040 setup/configuration, timeouts, and authentication 3041 inherent in the other remote access methods but still 3042 create a connection which uses the remote protocol. 3043 3044 To connect using the @code{fork} method, use 3045 @samp{:fork:} and the pathname to your local 3046 repository. For example: 3047 3048 @example 3049 cvs -d :fork:/usr/local/cvsroot checkout foo 3050 @end example 3051 3052 @cindex CVS_SERVER, and :fork: 3053 As with @code{:ext:}, the server is called @samp{cvs} 3054 by default, or the value of the @code{CVS_SERVER} 3055 environment variable. 3056 3057 3058 @node Write proxies 3059 @subsection Distributing load across several CVS servers 3060 3061 @cindex PrimaryServer, in CVSROOT/config 3062 @cindex Primary server 3063 @cindex Secondary server 3064 @cindex proxy, write 3065 @cindex write proxy 3066 @sc{cvs} can be configured to distribute usage across several @sc{cvs} 3067 servers. This is accomplished by means of one or more @dfn{write proxies}, or 3068 @dfn{secondary servers}, for a single @dfn{primary server}. 3069 3070 When a @sc{cvs} client accesses a secondary server and only sends read 3071 requests, then the secondary server handles the entire request. If the client 3072 sends any write requests, however, the secondary server asks the client to 3073 redirect its write request to the primary server, if the client supports 3074 redirect requests, and otherwise becomes a transparent proxy for the primary 3075 server, which actually handles the write request. 3076 3077 In this manner, any number of read-only secondary servers may be configured as 3078 write proxies for the primary server, effectively distributing the load from 3079 all read operations between the secondary servers and restricting the load on 3080 the primary server to write operations and pushing changes to the secondaries. 3081 3082 Primary servers will not automatically push changes to secondaries. This must 3083 be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, & 3084 @file{postwatch} scripts (@pxref{Trigger Scripts}) like the following: 3085 3086 @example 3087 ALL rsync -gopr -essh ./ secondary:/cvsroot/%p & 3088 @end example 3089 3090 You would probably actually want to lock directories for write on the secondary 3091 and for read on the primary before running the @samp{rsync} in the above 3092 example, but describing such a setup is beyond the scope of this document. 3093 3094 A secondary advantage of a write proxy setup is that users pointing at the 3095 secondary server can still execute fast read operations while on a network that 3096 connects to the primary over a slow link or even one where the link to the 3097 primary is periodically broken. Only write operations will require the network 3098 link to the primary. 3099 3100 To configure write proxies, the primary must be specified with the 3101 @samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}). For the 3102 transparent proxy mode to work, all secondary servers must also be running the 3103 same version of the @sc{cvs} server, or at least one that provides the same 3104 list of supported requests to the client as the primary server. This is not 3105 necessary for redirection. 3106 3107 Once a primary server is configured, secondary servers may be configured by: 3108 3109 @enumerate 3110 @item 3111 Duplicating the primary repository at the new location. 3112 @item 3113 Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and 3114 @file{postwatch} files on the primary to propagate writes to the new secondary. 3115 @item 3116 Configure remote access to the secondary(ies) as you would configure access 3117 to any other CVS server (@pxref{Remote repositories}). 3118 @item 3119 Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to 3120 @strong{all} incovations of the secondary server if the path to the @sc{cvs} 3121 repository directory is different on the two servers and you wish to support 3122 clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier 3123 clients do not handle the @samp{Redirect} response). 3124 3125 Please note, again, that writethrough proxy suport requires 3126 @code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all} 3127 incovations of the secondary server, not just @samp{pserver} invocations. 3128 This may require a wrapper script for the @sc{cvs} executable 3129 on your server machine. 3130 @end enumerate 3131 3132 3133 @c --------------------------------------------------------------------- 3134 @node Read-only access 3135 @section Read-only repository access 3136 @cindex Read-only repository access 3137 @cindex readers (admin file) 3138 @cindex writers (admin file) 3139 3140 It is possible to grant read-only repository 3141 access to people using the password-authenticated 3142 server (@pxref{Password authenticated}). (The 3143 other access methods do not have explicit support for 3144 read-only users because those methods all assume login 3145 access to the repository machine anyway, and therefore 3146 the user can do whatever local file permissions allow 3147 her to do.) 3148 3149 A user who has read-only access can do only 3150 those @sc{cvs} operations which do not modify the 3151 repository, except for certain ``administrative'' files 3152 (such as lock files and the history file). It may be 3153 desirable to use this feature in conjunction with 3154 user-aliasing (@pxref{Password authentication server}). 3155 3156 Unlike with previous versions of @sc{cvs}, read-only 3157 users should be able merely to read the repository, and 3158 not to execute programs on the server or otherwise gain 3159 unexpected levels of access. Or to be more accurate, 3160 the @emph{known} holes have been plugged. Because this 3161 feature is new and has not received a comprehensive 3162 security audit, you should use whatever level of 3163 caution seems warranted given your attitude concerning 3164 security. 3165 3166 There are two ways to specify read-only access 3167 for a user: by inclusion, and by exclusion. 3168 3169 "Inclusion" means listing that user 3170 specifically in the @file{$CVSROOT/CVSROOT/readers} 3171 file, which is simply a newline-separated list of 3172 users. Here is a sample @file{readers} file: 3173 3174 @example 3175 melissa 3176 splotnik 3177 jrandom 3178 @end example 3179 3180 @noindent 3181 (Don't forget the newline after the last user.) 3182 3183 "Exclusion" means explicitly listing everyone 3184 who has @emph{write} access---if the file 3185 3186 @example 3187 $CVSROOT/CVSROOT/writers 3188 @end example 3189 3190 @noindent 3191 exists, then only 3192 those users listed in it have write access, and 3193 everyone else has read-only access (of course, even the 3194 read-only users still need to be listed in the 3195 @sc{cvs} @file{passwd} file). The 3196 @file{writers} file has the same format as the 3197 @file{readers} file. 3198 3199 Note: if your @sc{cvs} @file{passwd} 3200 file maps cvs users onto system users (@pxref{Password 3201 authentication server}), make sure you deny or grant 3202 read-only access using the @emph{cvs} usernames, not 3203 the system usernames. That is, the @file{readers} and 3204 @file{writers} files contain cvs usernames, which may 3205 or may not be the same as system usernames. 3206 3207 Here is a complete description of the server's 3208 behavior in deciding whether to grant read-only or 3209 read-write access: 3210 3211 If @file{readers} exists, and this user is 3212 listed in it, then she gets read-only access. Or if 3213 @file{writers} exists, and this user is NOT listed in 3214 it, then she also gets read-only access (this is true 3215 even if @file{readers} exists but she is not listed 3216 there). Otherwise, she gets full read-write access. 3217 3218 Of course there is a conflict if the user is 3219 listed in both files. This is resolved in the more 3220 conservative way, it being better to protect the 3221 repository too much than too little: such a user gets 3222 read-only access. 3223 3224 @node Server temporary directory 3225 @section Temporary directories for the server 3226 @cindex Temporary directories, and server 3227 @cindex Server, temporary directories 3228 3229 While running, the @sc{cvs} server creates temporary 3230 directories. They are named 3231 3232 @example 3233 cvs-serv@var{pid} 3234 @end example 3235 3236 @noindent 3237 where @var{pid} is the process identification number of 3238 the server. 3239 They are located in the directory specified by 3240 the @samp{-T} global option (@pxref{Global options}), 3241 the @code{TMPDIR} environment variable (@pxref{Environment variables}), 3242 or, failing that, @file{/tmp}. 3243 3244 In most cases the server will remove the temporary 3245 directory when it is done, whether it finishes normally 3246 or abnormally. However, there are a few cases in which 3247 the server does not or cannot remove the temporary 3248 directory, for example: 3249 3250 @itemize @bullet 3251 @item 3252 If the server aborts due to an internal server error, 3253 it may preserve the directory to aid in debugging 3254 3255 @item 3256 If the server is killed in a way that it has no way of 3257 cleaning up (most notably, @samp{kill -KILL} on unix). 3258 3259 @item 3260 If the system shuts down without an orderly shutdown, 3261 which tells the server to clean up. 3262 @end itemize 3263 3264 In cases such as this, you will need to manually remove 3265 the @file{cvs-serv@var{pid}} directories. As long as 3266 there is no server running with process identification 3267 number @var{pid}, it is safe to do so. 3268 3269 @c --------------------------------------------------------------------- 3270 @node Starting a new project 3271 @chapter Starting a project with CVS 3272 @cindex Starting a project with CVS 3273 @cindex Creating a project 3274 3275 @comment --moduledb-- 3276 Because renaming files and moving them between 3277 directories is somewhat inconvenient, the first thing 3278 you do when you start a new project should be to think 3279 through your file organization. It is not impossible 3280 to rename or move files, but it does increase the 3281 potential for confusion and @sc{cvs} does have some 3282 quirks particularly in the area of renaming 3283 directories. @xref{Moving files}. 3284 3285 What to do next depends on the situation at hand. 3286 3287 @menu 3288 * Setting up the files:: Getting the files into the repository 3289 * Defining the module:: How to make a module of the files 3290 @end menu 3291 @c -- File permissions! 3292 3293 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3294 @node Setting up the files 3295 @section Setting up the files 3296 3297 The first step is to create the files inside the repository. This can 3298 be done in a couple of different ways. 3299 3300 @c -- The contributed scripts 3301 @menu 3302 * From files:: This method is useful with old projects 3303 where files already exist. 3304 * From other version control systems:: Old projects where you want to 3305 preserve history from another system. 3306 * From scratch:: Creating a directory tree from scratch. 3307 @end menu 3308 3309 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3310 @node From files 3311 @subsection Creating a directory tree from a number of files 3312 @cindex Importing files 3313 3314 When you begin using @sc{cvs}, you will probably already have several 3315 projects that can be 3316 put under @sc{cvs} control. In these cases the easiest way is to use the 3317 @code{import} command. An example is probably the easiest way to 3318 explain how to use it. If the files you want to install in 3319 @sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 3320 repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 3321 3322 @example 3323 $ cd @var{wdir} 3324 $ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 3325 @end example 3326 3327 Unless you supply a log message with the @samp{-m} 3328 flag, @sc{cvs} starts an editor and prompts for a 3329 message. The string @samp{yoyo} is a @dfn{vendor tag}, 3330 and @samp{start} is a @dfn{release tag}. They may fill 3331 no purpose in this context, but since @sc{cvs} requires 3332 them they must be present. @xref{Tracking sources}, for 3333 more information about them. 3334 3335 You can now verify that it worked, and remove your 3336 original source directory. 3337 @c FIXME: Need to say more about "verify that it 3338 @c worked". What should the user look for in the output 3339 @c from "diff -r"? 3340 3341 @example 3342 $ cd .. 3343 $ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 3344 $ diff -r @var{wdir} yoyodyne/@var{rdir} 3345 $ rm -r @var{wdir} 3346 @end example 3347 3348 @noindent 3349 Erasing the original sources is a good idea, to make sure that you do 3350 not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 3351 Of course, it would be wise to make sure that you have 3352 a backup of the sources before you remove them. 3353 3354 The @code{checkout} command can either take a module 3355 name as argument (as it has done in all previous 3356 examples) or a path name relative to @code{$CVSROOT}, 3357 as it did in the example above. 3358 3359 It is a good idea to check that the permissions 3360 @sc{cvs} sets on the directories inside @code{$CVSROOT} 3361 are reasonable, and that they belong to the proper 3362 groups. @xref{File permissions}. 3363 3364 If some of the files you want to import are binary, you 3365 may want to use the wrappers features to specify which 3366 files are binary and which are not. @xref{Wrappers}. 3367 3368 @c The node name is too long, but I am having trouble 3369 @c thinking of something more concise. 3370 @node From other version control systems 3371 @subsection Creating Files From Other Version Control Systems 3372 @cindex Importing files, from other version control systems 3373 3374 If you have a project which you are maintaining with 3375 another version control system, such as @sc{rcs}, you 3376 may wish to put the files from that project into 3377 @sc{cvs}, and preserve the revision history of the 3378 files. 3379 3380 @table @asis 3381 @cindex RCS, importing files from 3382 @item From RCS 3383 If you have been using @sc{rcs}, find the @sc{rcs} 3384 files---usually a file named @file{foo.c} will have its 3385 @sc{rcs} file in @file{RCS/foo.c,v} (but it could be 3386 other places; consult the @sc{rcs} documentation for 3387 details). Then create the appropriate directories in 3388 @sc{cvs} if they do not already exist. Then copy the 3389 files into the appropriate directories in the @sc{cvs} 3390 repository (the name in the repository must be the name 3391 of the source file with @samp{,v} added; the files go 3392 directly in the appropriate directory of the repository, 3393 not in an @file{RCS} subdirectory). This is one of the 3394 few times when it is a good idea to access the @sc{cvs} 3395 repository directly, rather than using @sc{cvs} 3396 commands. Then you are ready to check out a new 3397 working directory. 3398 @c Someday there probably should be a "cvs import -t 3399 @c rcs" or some such. It could even create magic 3400 @c branches. It could also do something about the case 3401 @c where the RCS file had a (non-magic) "0" branch. 3402 3403 The @sc{rcs} file should not be locked when you move it 3404 into @sc{cvs}; if it is, @sc{cvs} will have trouble 3405 letting you operate on it. 3406 @c What is the easiest way to unlock your files if you 3407 @c have them locked? Especially if you have a lot of them? 3408 @c This is a CVS bug/misfeature; importing RCS files 3409 @c should ignore whether they are locked and leave them in 3410 @c an unlocked state. Yet another reason for a separate 3411 @c "import RCS file" command. 3412 3413 @c How many is "many"? Or do they just import RCS files? 3414 @item From another version control system 3415 Many version control systems have the ability to export 3416 @sc{rcs} files in the standard format. If yours does, 3417 export the @sc{rcs} files and then follow the above 3418 instructions. 3419 3420 Failing that, probably your best bet is to write a 3421 script that will check out the files one revision at a 3422 time using the command line interface to the other 3423 system, and then check the revisions into @sc{cvs}. 3424 The @file{sccs2rcs} script mentioned below may be a 3425 useful example to follow. 3426 3427 @cindex SCCS, importing files from 3428 @item From SCCS 3429 There is a script in the @file{contrib} directory of 3430 the @sc{cvs} source distribution called @file{sccs2rcs} 3431 which converts @sc{sccs} files to @sc{rcs} files. 3432 Note: you must run it on a machine which has both 3433 @sc{sccs} and @sc{rcs} installed, and like everything 3434 else in contrib it is unsupported (your mileage may 3435 vary). 3436 3437 @cindex PVCS, importing files from 3438 @item From PVCS 3439 There is a script in the @file{contrib} directory of 3440 the @sc{cvs} source distribution called @file{pvcs_to_rcs} 3441 which converts @sc{pvcs} archives to @sc{rcs} files. 3442 You must run it on a machine which has both 3443 @sc{pvcs} and @sc{rcs} installed, and like everything 3444 else in contrib it is unsupported (your mileage may 3445 vary). See the comments in the script for details. 3446 @end table 3447 @c CMZ and/or PATCHY were systems that were used in the 3448 @c high energy physics community (especially for 3449 @c CERNLIB). CERN has replaced them with CVS, but the 3450 @c CAR format seems to live on as a way to submit 3451 @c changes. There is a program car2cvs which converts 3452 @c but I'm not sure where one gets a copy. 3453 @c Not sure it is worth mentioning here, since it would 3454 @c appear to affect only one particular community. 3455 @c Best page for more information is: 3456 @c http://wwwcn1.cern.ch/asd/cvs/index.html 3457 @c See also: 3458 @c http://ecponion.cern.ch/ecpsa/cernlib.html 3459 3460 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3461 @node From scratch 3462 @subsection Creating a directory tree from scratch 3463 3464 @c Also/instead should be documenting 3465 @c $ cvs co -l . 3466 @c $ mkdir tc 3467 @c $ cvs add tc 3468 @c $ cd tc 3469 @c $ mkdir man 3470 @c $ cvs add man 3471 @c etc. 3472 @c Using import to create the directories only is 3473 @c probably a somewhat confusing concept. 3474 For a new project, the easiest thing to do is probably 3475 to create an empty directory structure, like this: 3476 3477 @example 3478 $ mkdir tc 3479 $ mkdir tc/man 3480 $ mkdir tc/testing 3481 @end example 3482 3483 After that, you use the @code{import} command to create 3484 the corresponding (empty) directory structure inside 3485 the repository: 3486 3487 @example 3488 $ cd tc 3489 $ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 3490 @end example 3491 3492 This will add yoyodyne/@var{dir} as a directory under 3493 @code{$CVSROOT}. 3494 3495 Use @code{checkout} to get the new project. Then, use @code{add} 3496 to add files (and new directories) as needed. 3497 3498 @example 3499 $ cd .. 3500 $ cvs co yoyodyne/@var{dir} 3501 @end example 3502 3503 Check that the permissions @sc{cvs} sets on the 3504 directories inside @code{$CVSROOT} are reasonable. 3505 3506 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3507 @node Defining the module 3508 @section Defining the module 3509 @cindex Defining a module 3510 @cindex Editing the modules file 3511 @cindex Module, defining 3512 @cindex Modules file, changing 3513 3514 The next step is to define the module in the 3515 @file{modules} file. This is not strictly necessary, 3516 but modules can be convenient in grouping together 3517 related files and directories. 3518 3519 In simple cases these steps are sufficient to define a module. 3520 3521 @enumerate 3522 @item 3523 Get a working copy of the modules file. 3524 3525 @example 3526 $ cvs checkout CVSROOT/modules 3527 $ cd CVSROOT 3528 @end example 3529 3530 @item 3531 Edit the file and insert a line that defines the module. @xref{Intro 3532 administrative files}, for an introduction. @xref{modules}, for a full 3533 description of the modules file. You can use the 3534 following line to define the module @samp{tc}: 3535 3536 @example 3537 tc yoyodyne/tc 3538 @end example 3539 3540 @item 3541 Commit your changes to the modules file. 3542 3543 @example 3544 $ cvs commit -m "Added the tc module." modules 3545 @end example 3546 3547 @item 3548 Release the modules module. 3549 3550 @example 3551 $ cd .. 3552 $ cvs release -d CVSROOT 3553 @end example 3554 @end enumerate 3555 3556 @c --------------------------------------------------------------------- 3557 @node Revisions 3558 @chapter Revisions 3559 3560 For many uses of @sc{cvs}, one doesn't need to worry 3561 too much about revision numbers; @sc{cvs} assigns 3562 numbers such as @code{1.1}, @code{1.2}, and so on, and 3563 that is all one needs to know. However, some people 3564 prefer to have more knowledge and control concerning 3565 how @sc{cvs} assigns revision numbers. 3566 3567 If one wants to keep track of a set of revisions 3568 involving more than one file, such as which revisions 3569 went into a particular release, one uses a @dfn{tag}, 3570 which is a symbolic revision which can be assigned to a 3571 numeric revision in each file. 3572 3573 @menu 3574 * Revision numbers:: The meaning of a revision number 3575 * Versions revisions releases:: Terminology used in this manual 3576 * Assigning revisions:: Assigning revisions 3577 * Tags:: Tags--Symbolic revisions 3578 * Tagging the working directory:: The cvs tag command 3579 * Tagging by date/tag:: The cvs rtag command 3580 * Modifying tags:: Adding, renaming, and deleting tags 3581 * Tagging add/remove:: Tags with adding and removing files 3582 * Sticky tags:: Certain tags are persistent 3583 @end menu 3584 3585 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3586 @node Revision numbers 3587 @section Revision numbers 3588 @cindex Revision numbers 3589 @cindex Revision tree 3590 @cindex Linear development 3591 @cindex Number, revision- 3592 @cindex Decimal revision number 3593 @cindex Branch number 3594 @cindex Number, branch 3595 3596 Each version of a file has a unique @dfn{revision 3597 number}. Revision numbers look like @samp{1.1}, 3598 @samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 3599 A revision number always has an even number of 3600 period-separated decimal integers. By default revision 3601 1.1 is the first revision of a file. Each successive 3602 revision is given a new number by increasing the 3603 rightmost number by one. The following figure displays 3604 a few revisions, with newer revisions to the right. 3605 3606 @example 3607 +-----+ +-----+ +-----+ +-----+ +-----+ 3608 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 3609 +-----+ +-----+ +-----+ +-----+ +-----+ 3610 @end example 3611 3612 It is also possible to end up with numbers containing 3613 more than one period, for example @samp{1.3.2.2}. Such 3614 revisions represent revisions on branches 3615 (@pxref{Branching and merging}); such revision numbers 3616 are explained in detail in @ref{Branches and 3617 revisions}. 3618 3619 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3620 @node Versions revisions releases 3621 @section Versions, revisions and releases 3622 @cindex Revisions, versions and releases 3623 @cindex Versions, revisions and releases 3624 @cindex Releases, revisions and versions 3625 3626 A file can have several versions, as described above. 3627 Likewise, a software product can have several versions. 3628 A software product is often given a version number such 3629 as @samp{4.1.1}. 3630 3631 Versions in the first sense are called @dfn{revisions} 3632 in this document, and versions in the second sense are 3633 called @dfn{releases}. To avoid confusion, the word 3634 @dfn{version} is almost never used in this document. 3635 3636 @node Assigning revisions 3637 @section Assigning revisions 3638 3639 @c We avoid the "major revision" terminology. It seems 3640 @c like jargon. Hopefully "first number" is clear enough. 3641 @c 3642 @c Well, in the context of software release numbers, 3643 @c "major" and "minor" release or version numbers are 3644 @c documented in at least the GNU Coding Standards, but I'm 3645 @c still not sure I find that a valid reason to apply the 3646 @c terminology to RCS revision numbers. "First", "Second", 3647 @c "subsequent", and so on is almost surely clearer, 3648 @c especially to a novice reader. -DRP 3649 By default, @sc{cvs} will assign numeric revisions by 3650 leaving the first number the same and incrementing the 3651 second number. For example, @code{1.1}, @code{1.2}, 3652 @code{1.3}, etc. 3653 3654 When adding a new file, the second number will always 3655 be one and the first number will equal the highest 3656 first number of any file in that directory. For 3657 example, the current directory contains files whose 3658 highest numbered revisions are @code{1.7}, @code{3.1}, 3659 and @code{4.12}, then an added file will be given the 3660 numeric revision @code{4.1}. 3661 (When using client/server @sc{cvs}, 3662 only files that are actually sent to the server are considered.) 3663 3664 @c This is sort of redundant with something we said a 3665 @c while ago. Somewhere we need a better way of 3666 @c introducing how the first number can be anything 3667 @c except "1", perhaps. Also I don't think this 3668 @c presentation is clear on why we are discussing releases 3669 @c and first numbers of numeric revisions in the same 3670 @c breath. 3671 Normally there is no reason to care 3672 about the revision numbers---it is easier to treat them 3673 as internal numbers that @sc{cvs} maintains, and tags 3674 provide a better way to distinguish between things like 3675 release 1 versus release 2 of your product 3676 (@pxref{Tags}). However, if you want to set the 3677 numeric revisions, the @samp{-r} option to @code{cvs 3678 commit} can do that. The @samp{-r} option implies the 3679 @samp{-f} option, in the sense that it causes the 3680 files to be committed even if they are not modified. 3681 3682 For example, to bring all your files up to 3683 revision 3.0 (including those that haven't changed), 3684 you might invoke: 3685 3686 @example 3687 $ cvs commit -r 3.0 3688 @end example 3689 3690 Note that the number you specify with @samp{-r} must be 3691 larger than any existing revision number. That is, if 3692 revision 3.0 exists, you cannot @samp{cvs commit 3693 -r 1.3}. If you want to maintain several releases in 3694 parallel, you need to use a branch (@pxref{Branching and merging}). 3695 3696 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3697 @node Tags 3698 @section Tags--Symbolic revisions 3699 @cindex Tags 3700 3701 The revision numbers live a life of their own. They 3702 need not have anything at all to do with the release 3703 numbers of your software product. Depending 3704 on how you use @sc{cvs} the revision numbers might change several times 3705 between two releases. As an example, some of the 3706 source files that make up @sc{rcs} 5.6 have the following 3707 revision numbers: 3708 @cindex RCS revision numbers 3709 3710 @example 3711 ci.c 5.21 3712 co.c 5.9 3713 ident.c 5.3 3714 rcs.c 5.12 3715 rcsbase.h 5.11 3716 rcsdiff.c 5.10 3717 rcsedit.c 5.11 3718 rcsfcmp.c 5.9 3719 rcsgen.c 5.10 3720 rcslex.c 5.11 3721 rcsmap.c 5.2 3722 rcsutil.c 5.10 3723 @end example 3724 3725 @cindex tag (subcommand), introduction 3726 @cindex Tags, symbolic name 3727 @cindex Symbolic name (tag) 3728 @cindex Name, symbolic (tag) 3729 @cindex HEAD, as reserved tag name 3730 @cindex BASE, as reserved tag name 3731 You can use the @code{tag} command to give a symbolic name to a 3732 certain revision of a file. You can use the @samp{-v} flag to the 3733 @code{status} command to see all tags that a file has, and 3734 which revision numbers they represent. Tag names must 3735 start with an uppercase or lowercase letter and can 3736 contain uppercase and lowercase letters, digits, 3737 @samp{-}, and @samp{_}. The two tag names @code{BASE} 3738 and @code{HEAD} are reserved for use by @sc{cvs}. It 3739 is expected that future names which are special to 3740 @sc{cvs} will be specially named, for example by 3741 starting with @samp{.}, rather than being named analogously to 3742 @code{BASE} and @code{HEAD}, to avoid conflicts with 3743 actual tag names. 3744 @c Including a character such as % or = has also been 3745 @c suggested as the naming convention for future 3746 @c special tag names. Starting with . is nice because 3747 @c that is not a legal tag name as far as RCS is concerned. 3748 @c FIXME: CVS actually accepts quite a few characters 3749 @c in tag names, not just the ones documented above 3750 @c (see RCS_check_tag). RCS 3751 @c defines legitimate tag names by listing illegal 3752 @c characters rather than legal ones. CVS is said to lose its 3753 @c mind if you try to use "/" (try making such a tag sticky 3754 @c and using "cvs status" client/server--see remote 3755 @c protocol format for entries line for probable cause). 3756 @c TODO: The testsuite 3757 @c should test for whatever are documented above as 3758 @c officially-OK tag names, and CVS should at least reject 3759 @c characters that won't work, like "/". 3760 3761 You'll want to choose some convention for naming tags, 3762 based on information such as the name of the program 3763 and the version number of the release. For example, 3764 one might take the name of the program, immediately 3765 followed by the version number with @samp{.} changed to 3766 @samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 3767 @code{cvs1-9}. If you choose a consistent convention, 3768 then you won't constantly be guessing whether a tag is 3769 @code{cvs-1-9} or @code{cvs1_9} or what. You might 3770 even want to consider enforcing your convention in the 3771 @file{taginfo} file (@pxref{taginfo}). 3772 @c Might be nice to say more about using taginfo this 3773 @c way, like giving an example, or pointing out any particular 3774 @c issues which arise. 3775 3776 @cindex Adding a tag 3777 @cindex Tags, example 3778 The following example shows how you can add a tag to a 3779 file. The commands must be issued inside your working 3780 directory. That is, you should issue the 3781 command in the directory where @file{backend.c} 3782 resides. 3783 3784 @example 3785 $ cvs tag rel-0-4 backend.c 3786 T backend.c 3787 $ cvs status -v backend.c 3788 =================================================================== 3789 File: backend.c Status: Up-to-date 3790 3791 Version: 1.4 Tue Dec 1 14:39:01 1992 3792 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 3793 Sticky Tag: (none) 3794 Sticky Date: (none) 3795 Sticky Options: (none) 3796 3797 Existing Tags: 3798 rel-0-4 (revision: 1.4) 3799 3800 @end example 3801 3802 For a complete summary of the syntax of @code{cvs tag}, 3803 including the various options, see @ref{Invoking CVS}. 3804 3805 There is seldom reason to tag a file in isolation. A more common use is 3806 to tag all the files that constitute a module with the same tag at 3807 strategic points in the development life-cycle, such as when a release 3808 is made. 3809 3810 @example 3811 $ cvs tag rel-1-0 . 3812 cvs tag: Tagging . 3813 T Makefile 3814 T backend.c 3815 T driver.c 3816 T frontend.c 3817 T parser.c 3818 @end example 3819 3820 @noindent 3821 (When you give @sc{cvs} a directory as argument, it generally applies the 3822 operation to all the files in that directory, and (recursively), to any 3823 subdirectories that it may contain. @xref{Recursive behavior}.) 3824 3825 @cindex Retrieving an old revision using tags 3826 @cindex Tags, retrieving old revisions 3827 The @code{checkout} command has a flag, @samp{-r}, that lets you check out 3828 a certain revision of a module. This flag makes it easy to 3829 retrieve the sources that make up release 1.0 of the module @samp{tc} at 3830 any time in the future: 3831 3832 @example 3833 $ cvs checkout -r rel-1-0 tc 3834 @end example 3835 3836 @noindent 3837 This is useful, for instance, if someone claims that there is a bug in 3838 that release, but you cannot find the bug in the current working copy. 3839 3840 You can also check out a module as it was on any branch at any given date. 3841 @xref{checkout options}. When specifying @samp{-r} or @samp{-D} to 3842 any of these commands, you will need beware of sticky 3843 tags; see @ref{Sticky tags}. 3844 3845 When you tag more than one file with the same tag you 3846 can think about the tag as "a curve drawn through a 3847 matrix of filename vs. revision number." Say we have 5 3848 files with the following revisions: 3849 3850 @example 3851 @group 3852 file1 file2 file3 file4 file5 3853 3854 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 3855 1.2*- 1.2 1.2 -1.2*- 3856 1.3 \- 1.3*- 1.3 / 1.3 3857 1.4 \ 1.4 / 1.4 3858 \-1.5*- 1.5 3859 1.6 3860 @end group 3861 @end example 3862 3863 At some time in the past, the @code{*} versions were tagged. 3864 You can think of the tag as a handle attached to the curve 3865 drawn through the tagged revisions. When you pull on 3866 the handle, you get all the tagged revisions. Another 3867 way to look at it is that you "sight" through a set of 3868 revisions that is "flat" along the tagged revisions, 3869 like this: 3870 3871 @example 3872 @group 3873 file1 file2 file3 file4 file5 3874 3875 1.1 3876 1.2 3877 1.1 1.3 _ 3878 1.1 1.2 1.4 1.1 / 3879 1.2*----1.3*----1.5*----1.2*----1.1* (--- <--- Look here 3880 1.3 1.6 1.3 \_ 3881 1.4 1.4 3882 1.5 3883 @end group 3884 @end example 3885 3886 @node Tagging the working directory 3887 @section Specifying what to tag from the working directory 3888 3889 @cindex tag (subcommand) 3890 The example in the previous section demonstrates one of 3891 the most common ways to choose which revisions to tag. 3892 Namely, running the @code{cvs tag} command without 3893 arguments causes @sc{cvs} to select the revisions which 3894 are checked out in the current working directory. For 3895 example, if the copy of @file{backend.c} in working 3896 directory was checked out from revision 1.4, then 3897 @sc{cvs} will tag revision 1.4. Note that the tag is 3898 applied immediately to revision 1.4 in the repository; 3899 tagging is not like modifying a file, or other 3900 operations in which one first modifies the working 3901 directory and then runs @code{cvs commit} to transfer 3902 that modification to the repository. 3903 3904 One potentially surprising aspect of the fact that 3905 @code{cvs tag} operates on the repository is that you 3906 are tagging the checked-in revisions, which may differ 3907 from locally modified files in your working directory. 3908 If you want to avoid doing this by mistake, specify the 3909 @samp{-c} option to @code{cvs tag}. If there are any 3910 locally modified files, @sc{cvs} will abort with an 3911 error before it tags any files: 3912 3913 @example 3914 $ cvs tag -c rel-0-4 3915 cvs tag: backend.c is locally modified 3916 cvs [tag aborted]: correct the above errors first! 3917 @end example 3918 3919 @node Tagging by date/tag 3920 @section Specifying what to tag by date or revision 3921 @cindex rtag (subcommand) 3922 3923 The @code{cvs rtag} command tags the repository as of a 3924 certain date or time (or can be used to tag the latest 3925 revision). @code{rtag} works directly on the 3926 repository contents (it requires no prior checkout and 3927 does not look for a working directory). 3928 3929 The following options specify which date or revision to 3930 tag. See @ref{Common options}, for a complete 3931 description of them. 3932 3933 @table @code 3934 @item -D @var{date} 3935 Tag the most recent revision no later than @var{date}. 3936 3937 @item -f 3938 Only useful with the @samp{-D} or @samp{-r} 3939 flags. If no matching revision is found, use the most 3940 recent revision (instead of ignoring the file). 3941 3942 @item -r @var{tag}[:@var{date}] 3943 Tag the revision already tagged with @var{tag} or, when @var{date} is specified 3944 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 3945 existed on @var{date}. See @ref{Common options}. 3946 @end table 3947 3948 The @code{cvs tag} command also allows one to specify 3949 files by revision or date, using the same @samp{-r}, 3950 @samp{-D}, and @samp{-f} options. However, this 3951 feature is probably not what you want. The reason is 3952 that @code{cvs tag} chooses which files to tag based on 3953 the files that exist in the working directory, rather 3954 than the files which existed as of the given tag/date. 3955 Therefore, you are generally better off using @code{cvs 3956 rtag}. The exceptions might be cases like: 3957 3958 @example 3959 cvs tag -r 1.4 stable backend.c 3960 @end example 3961 3962 @node Modifying tags 3963 @section Deleting, moving, and renaming tags 3964 3965 @c Also see: 3966 @c "How do I move or rename a magic branch tag?" 3967 @c in the FAQ (I think the issues it talks about still 3968 @c apply, but this could use some sanity.sh work). 3969 3970 Normally one does not modify tags. They exist in order 3971 to record the history of the repository and so deleting 3972 them or changing their meaning would, generally, not be 3973 what you want. 3974 3975 However, there might be cases in which one uses a tag 3976 temporarily or accidentally puts one in the wrong 3977 place. Therefore, one might delete, move, or rename a 3978 tag. 3979 3980 @noindent 3981 @strong{WARNING: the commands in this section are 3982 dangerous; they permanently discard historical 3983 information and it can be difficult or impossible to 3984 recover from errors. If you are a @sc{cvs} 3985 administrator, you may consider restricting these 3986 commands with the @file{taginfo} file (@pxref{taginfo}).} 3987 3988 @cindex Deleting tags 3989 @cindex Deleting branch tags 3990 @cindex Removing tags 3991 @cindex Removing branch tags 3992 @cindex Tags, deleting 3993 @cindex Branch tags, deleting 3994 To delete a tag, specify the @samp{-d} option to either 3995 @code{cvs tag} or @code{cvs rtag}. For example: 3996 3997 @example 3998 cvs rtag -d rel-0-4 tc 3999 @end example 4000 4001 @noindent 4002 deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 4003 In the event that branch tags are encountered within the repository 4004 with the given name, a warning message will be issued and the branch 4005 tag will not be deleted. If you are absolutely certain you know what 4006 you are doing, the @code{-B} option may be specified to allow deletion 4007 of branch tags. In that case, any non-branch tags encountered will 4008 trigger warnings and will not be deleted. 4009 4010 @noindent 4011 @strong{WARNING: Moving branch tags is very dangerous! If you think 4012 you need the @code{-B} option, think again and ask your @sc{cvs} 4013 administrator about it (if that isn't you). There is almost certainly 4014 another way to accomplish what you want to accomplish.} 4015 4016 @cindex Moving tags 4017 @cindex Moving branch tags 4018 @cindex Tags, moving 4019 @cindex Branch tags, moving 4020 When we say @dfn{move} a tag, we mean to make the same 4021 name point to different revisions. For example, the 4022 @code{stable} tag may currently point to revision 1.4 4023 of @file{backend.c} and perhaps we want to make it 4024 point to revision 1.6. To move a non-branch tag, specify the 4025 @samp{-F} option to either @code{cvs tag} or @code{cvs 4026 rtag}. For example, the task just mentioned might be 4027 accomplished as: 4028 4029 @example 4030 cvs tag -r 1.6 -F stable backend.c 4031 @end example 4032 4033 @noindent 4034 If any branch tags are encountered in the repository 4035 with the given name, a warning is issued and the branch 4036 tag is not disturbed. If you are absolutely certain you 4037 wish to move the branch tag, the @code{-B} option may be specified. 4038 In that case, non-branch tags encountered with the given 4039 name are ignored with a warning message. 4040 4041 @noindent 4042 @strong{WARNING: Moving branch tags is very dangerous! If you think you 4043 need the @code{-B} option, think again and ask your @sc{cvs} 4044 administrator about it (if that isn't you). There is almost certainly 4045 another way to accomplish what you want to accomplish.} 4046 4047 @cindex Renaming tags 4048 @cindex Tags, renaming 4049 When we say @dfn{rename} a tag, we mean to make a 4050 different name point to the same revisions as the old 4051 tag. For example, one may have misspelled the tag name 4052 and want to correct it (hopefully before others are 4053 relying on the old spelling). To rename a tag, first 4054 create a new tag using the @samp{-r} option to 4055 @code{cvs rtag}, and then delete the old name. (Caution: 4056 this method will not work with branch tags.) 4057 This leaves the new tag on exactly the 4058 same files as the old tag. For example: 4059 4060 @example 4061 cvs rtag -r old-name-0-4 rel-0-4 tc 4062 cvs rtag -d old-name-0-4 tc 4063 @end example 4064 4065 @node Tagging add/remove 4066 @section Tagging and adding and removing files 4067 4068 The subject of exactly how tagging interacts with 4069 adding and removing files is somewhat obscure; for the 4070 most part @sc{cvs} will keep track of whether files 4071 exist or not without too much fussing. By default, 4072 tags are applied to only files which have a revision 4073 corresponding to what is being tagged. Files which did 4074 not exist yet, or which were already removed, simply 4075 omit the tag, and @sc{cvs} knows to treat the absence 4076 of a tag as meaning that the file didn't exist as of 4077 that tag. 4078 4079 However, this can lose a small amount of information. 4080 For example, suppose a file was added and then removed. 4081 Then, if the tag is missing for that file, there is no 4082 way to know whether the tag refers to the time before 4083 the file was added, or the time after it was removed. 4084 If you specify the @samp{-r} option to @code{cvs rtag}, 4085 then @sc{cvs} tags the files which have been removed, 4086 and thereby avoids this problem. For example, one 4087 might specify @code{-r HEAD} to tag the head. 4088 4089 On the subject of adding and removing files, the 4090 @code{cvs rtag} command has a @samp{-a} option which 4091 means to clear the tag from removed files that would 4092 not otherwise be tagged. For example, one might 4093 specify this option in conjunction with @samp{-F} when 4094 moving a tag. If one moved a tag without @samp{-a}, 4095 then the tag in the removed files might still refer to 4096 the old revision, rather than reflecting the fact that 4097 the file had been removed. I don't think this is 4098 necessary if @samp{-r} is specified, as noted above. 4099 4100 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4101 @node Sticky tags 4102 @section Sticky tags 4103 @cindex Sticky tags 4104 @cindex Tags, sticky 4105 4106 @c A somewhat related issue is per-directory sticky 4107 @c tags (see comment at CVS/Tag in node Working 4108 @c directory storage); we probably want to say 4109 @c something like "you can set a sticky tag for only 4110 @c some files, but you don't want to" or some such. 4111 4112 Sometimes a working copy's revision has extra data 4113 associated with it, for example it might be on a branch 4114 (@pxref{Branching and merging}), or restricted to 4115 versions prior to a certain date by @samp{checkout -D} 4116 or @samp{update -D}. Because this data persists -- 4117 that is, it applies to subsequent commands in the 4118 working copy -- we refer to it as @dfn{sticky}. 4119 4120 Most of the time, stickiness is an obscure aspect of 4121 @sc{cvs} that you don't need to think about. However, 4122 even if you don't want to use the feature, you may need 4123 to know @emph{something} about sticky tags (for 4124 example, how to avoid them!). 4125 4126 You can use the @code{status} command to see if any 4127 sticky tags or dates are set: 4128 4129 @example 4130 $ cvs status driver.c 4131 =================================================================== 4132 File: driver.c Status: Up-to-date 4133 4134 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 4135 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 4136 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4137 Sticky Date: (none) 4138 Sticky Options: (none) 4139 4140 @end example 4141 4142 @cindex Resetting sticky tags 4143 @cindex Sticky tags, resetting 4144 @cindex Deleting sticky tags 4145 The sticky tags will remain on your working files until 4146 you delete them with @samp{cvs update -A}. The 4147 @samp{-A} option merges local changes into the version of the 4148 file from the head of the trunk, removing any sticky tags, 4149 dates, or options. See @ref{update} for more on the operation 4150 of @code{cvs update}. 4151 4152 @cindex Sticky date 4153 The most common use of sticky tags is to identify which 4154 branch one is working on, as described in 4155 @ref{Accessing branches}. However, non-branch 4156 sticky tags have uses as well. For example, 4157 suppose that you want to avoid updating your working 4158 directory, to isolate yourself from possibly 4159 destabilizing changes other people are making. You 4160 can, of course, just refrain from running @code{cvs 4161 update}. But if you want to avoid updating only a 4162 portion of a larger tree, then sticky tags can help. 4163 If you check out a certain revision (such as 1.4) it 4164 will become sticky. Subsequent @code{cvs update} 4165 commands will 4166 not retrieve the latest revision until you reset the 4167 tag with @code{cvs update -A}. Likewise, use of the 4168 @samp{-D} option to @code{update} or @code{checkout} 4169 sets a @dfn{sticky date}, which, similarly, causes that 4170 date to be used for future retrievals. 4171 4172 People often want to retrieve an old version of 4173 a file without setting a sticky tag. This can 4174 be done with the @samp{-p} option to @code{checkout} or 4175 @code{update}, which sends the contents of the file to 4176 standard output. For example: 4177 @example 4178 $ cvs update -p -r 1.1 file1 >file1 4179 =================================================================== 4180 Checking out file1 4181 RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 4182 VERS: 1.1 4183 *************** 4184 $ 4185 @end example 4186 4187 However, this isn't the easiest way, if you are asking 4188 how to undo a previous checkin (in this example, put 4189 @file{file1} back to the way it was as of revision 4190 1.1). In that case you are better off using the 4191 @samp{-j} option to @code{update}; for further 4192 discussion see @ref{Merging two revisions}. 4193 4194 @c --------------------------------------------------------------------- 4195 @node Branching and merging 4196 @chapter Branching and merging 4197 @cindex Branching 4198 @cindex Merging 4199 @cindex Copying changes 4200 @cindex Main trunk and branches 4201 @cindex Revision tree, making branches 4202 @cindex Branches, copying changes between 4203 @cindex Changes, copying between branches 4204 @cindex Modifications, copying between branches 4205 4206 @sc{cvs} allows you to isolate changes onto a separate 4207 line of development, known as a @dfn{branch}. When you 4208 change files on a branch, those changes do not appear 4209 on the main trunk or other branches. 4210 4211 Later you can move changes from one branch to another 4212 branch (or the main trunk) by @dfn{merging}. Merging 4213 involves first running @code{cvs update -j}, to merge 4214 the changes into the working directory. 4215 You can then commit that revision, and thus effectively 4216 copy the changes onto another branch. 4217 4218 @menu 4219 * Branches motivation:: What branches are good for 4220 * Creating a branch:: Creating a branch 4221 * Accessing branches:: Checking out and updating branches 4222 * Branches and revisions:: Branches are reflected in revision numbers 4223 * Magic branch numbers:: Magic branch numbers 4224 * Merging a branch:: Merging an entire branch 4225 * Merging more than once:: Merging from a branch several times 4226 * Merging two revisions:: Merging differences between two revisions 4227 * Merging adds and removals:: What if files are added or removed? 4228 * Merging and keywords:: Avoiding conflicts due to keyword substitution 4229 @end menu 4230 4231 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4232 @node Branches motivation 4233 @section What branches are good for 4234 @cindex Branches motivation 4235 @cindex What branches are good for 4236 @cindex Motivation for branches 4237 4238 @c FIXME: this node mentions one way to use branches, 4239 @c but it is by no means the only way. For example, 4240 @c the technique of committing a new feature on a branch, 4241 @c until it is ready for the main trunk. The whole 4242 @c thing is generally speaking more akin to the 4243 @c "Revision management" node although it isn't clear to 4244 @c me whether policy matters should be centralized or 4245 @c distributed throughout the relevant sections. 4246 Suppose that release 1.0 of tc has been made. You are continuing to 4247 develop tc, planning to create release 1.1 in a couple of months. After a 4248 while your customers start to complain about a fatal bug. You check 4249 out release 1.0 (@pxref{Tags}) and find the bug 4250 (which turns out to have a trivial fix). However, the current revision 4251 of the sources are in a state of flux and are not expected to be stable 4252 for at least another month. There is no way to make a 4253 bug fix release based on the newest sources. 4254 4255 The thing to do in a situation like this is to create a @dfn{branch} on 4256 the revision trees for all the files that make up 4257 release 1.0 of tc. You can then make 4258 modifications to the branch without disturbing the main trunk. When the 4259 modifications are finished you can elect to either incorporate them on 4260 the main trunk, or leave them on the branch. 4261 4262 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4263 @node Creating a branch 4264 @section Creating a branch 4265 @cindex Creating a branch 4266 @cindex Branch, creating a 4267 @cindex tag (subcommand), creating a branch using 4268 @cindex rtag (subcommand), creating a branch using 4269 4270 You can create a branch with @code{tag -b}; for 4271 example, assuming you're in a working copy: 4272 4273 @example 4274 $ cvs tag -b rel-1-0-patches 4275 @end example 4276 4277 @c FIXME: we should be more explicit about the value of 4278 @c having a tag on the branchpoint. For example 4279 @c "cvs tag rel-1-0-patches-branchpoint" before 4280 @c the "cvs tag -b". This points out that 4281 @c rel-1-0-patches is a pretty awkward name for 4282 @c this example (more so than for the rtag example 4283 @c below). 4284 4285 This splits off a branch based on the current revisions 4286 in the working copy, assigning that branch the name 4287 @samp{rel-1-0-patches}. 4288 4289 It is important to understand that branches get created 4290 in the repository, not in the working copy. Creating a 4291 branch based on current revisions, as the above example 4292 does, will @emph{not} automatically switch the working 4293 copy to be on the new branch. For information on how 4294 to do that, see @ref{Accessing branches}. 4295 4296 You can also create a branch without reference to any 4297 working copy, by using @code{rtag}: 4298 4299 @example 4300 $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 4301 @end example 4302 4303 @samp{-r rel-1-0} says that this branch should be 4304 rooted at the revision that 4305 corresponds to the tag @samp{rel-1-0}. It need not 4306 be the most recent revision -- it's often useful to 4307 split a branch off an old revision (for example, when 4308 fixing a bug in a past release otherwise known to be 4309 stable). 4310 4311 As with @samp{tag}, the @samp{-b} flag tells 4312 @code{rtag} to create a branch (rather than just a 4313 symbolic revision name). Note that the numeric 4314 revision number that matches @samp{rel-1-0} will 4315 probably be different from file to file. 4316 4317 So, the full effect of the command is to create a new 4318 branch -- named @samp{rel-1-0-patches} -- in module 4319 @samp{tc}, rooted in the revision tree at the point tagged 4320 by @samp{rel-1-0}. 4321 4322 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4323 @node Accessing branches 4324 @section Accessing branches 4325 @cindex Check out a branch 4326 @cindex Retrieve a branch 4327 @cindex Access a branch 4328 @cindex Identifying a branch 4329 @cindex Branch, check out 4330 @cindex Branch, retrieving 4331 @cindex Branch, accessing 4332 @cindex Branch, identifying 4333 4334 You can retrieve a branch in one of two ways: by 4335 checking it out fresh from the repository, or by 4336 switching an existing working copy over to the branch. 4337 4338 To check out a branch from the repository, invoke 4339 @samp{checkout} with the @samp{-r} flag, followed by 4340 the tag name of the branch (@pxref{Creating a branch}): 4341 4342 @example 4343 $ cvs checkout -r rel-1-0-patches tc 4344 @end example 4345 4346 Or, if you already have a working copy, you can switch 4347 it to a given branch with @samp{update -r}: 4348 4349 @example 4350 $ cvs update -r rel-1-0-patches tc 4351 @end example 4352 4353 @noindent 4354 or equivalently: 4355 4356 @example 4357 $ cd tc 4358 $ cvs update -r rel-1-0-patches 4359 @end example 4360 4361 It does not matter if the working copy was originally 4362 on the main trunk or on some other branch -- the above 4363 command will switch it to the named branch. And 4364 similarly to a regular @samp{update} command, 4365 @samp{update -r} merges any changes you have made, 4366 notifying you of conflicts where they occur. 4367 4368 Once you have a working copy tied to a particular 4369 branch, it remains there until you tell it otherwise. 4370 This means that changes checked in from the working 4371 copy will add new revisions on that branch, while 4372 leaving the main trunk and other branches unaffected. 4373 4374 @cindex Branches, sticky 4375 To find out what branch a working copy is on, you can 4376 use the @samp{status} command. In its output, look for 4377 the field named @samp{Sticky tag} (@pxref{Sticky tags}) 4378 -- that's @sc{cvs}'s way of telling you the branch, if 4379 any, of the current working files: 4380 4381 @example 4382 $ cvs status -v driver.c backend.c 4383 =================================================================== 4384 File: driver.c Status: Up-to-date 4385 4386 Version: 1.7 Sat Dec 5 18:25:54 1992 4387 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 4388 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4389 Sticky Date: (none) 4390 Sticky Options: (none) 4391 4392 Existing Tags: 4393 rel-1-0-patches (branch: 1.7.2) 4394 rel-1-0 (revision: 1.7) 4395 4396 =================================================================== 4397 File: backend.c Status: Up-to-date 4398 4399 Version: 1.4 Tue Dec 1 14:39:01 1992 4400 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 4401 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 4402 Sticky Date: (none) 4403 Sticky Options: (none) 4404 4405 Existing Tags: 4406 rel-1-0-patches (branch: 1.4.2) 4407 rel-1-0 (revision: 1.4) 4408 rel-0-4 (revision: 1.4) 4409 4410 @end example 4411 4412 Don't be confused by the fact that the branch numbers 4413 for each file are different (@samp{1.7.2} and 4414 @samp{1.4.2} respectively). The branch tag is the 4415 same, @samp{rel-1-0-patches}, and the files are 4416 indeed on the same branch. The numbers simply reflect 4417 the point in each file's revision history at which the 4418 branch was made. In the above example, one can deduce 4419 that @samp{driver.c} had been through more changes than 4420 @samp{backend.c} before this branch was created. 4421 4422 See @ref{Branches and revisions} for details about how 4423 branch numbers are constructed. 4424 4425 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4426 @node Branches and revisions 4427 @section Branches and revisions 4428 @cindex Branch number 4429 @cindex Number, branch 4430 @cindex Revision numbers (branches) 4431 4432 Ordinarily, a file's revision history is a linear 4433 series of increments (@pxref{Revision numbers}): 4434 4435 @example 4436 +-----+ +-----+ +-----+ +-----+ +-----+ 4437 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 4438 +-----+ +-----+ +-----+ +-----+ +-----+ 4439 @end example 4440 4441 However, @sc{cvs} is not limited to linear development. The 4442 @dfn{revision tree} can be split into @dfn{branches}, 4443 where each branch is a self-maintained line of 4444 development. Changes made on one branch can easily be 4445 moved back to the main trunk. 4446 4447 Each branch has a @dfn{branch number}, consisting of an 4448 odd number of period-separated decimal integers. The 4449 branch number is created by appending an integer to the 4450 revision number where the corresponding branch forked 4451 off. Having branch numbers allows more than one branch 4452 to be forked off from a certain revision. 4453 4454 @need 3500 4455 All revisions on a branch have revision numbers formed 4456 by appending an ordinal number to the branch number. 4457 The following figure illustrates branching with an 4458 example. 4459 4460 @example 4461 @c This example used to have a 1.2.2.4 revision, which 4462 @c might help clarify that development can continue on 4463 @c 1.2.2. Might be worth reinstating if it can be done 4464 @c without overfull hboxes. 4465 @group 4466 +-------------+ 4467 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 4468 / +-------------+ 4469 / 4470 / 4471 +---------+ +---------+ +---------+ 4472 Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4473 / +---------+ +---------+ +---------+ 4474 / 4475 / 4476 +-----+ +-----+ +-----+ +-----+ +-----+ 4477 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4478 +-----+ +-----+ +-----+ +-----+ +-----+ 4479 ! 4480 ! 4481 ! +---------+ +---------+ +---------+ 4482 Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 4483 +---------+ +---------+ +---------+ 4484 4485 @end group 4486 @end example 4487 4488 @c -- However, at least for me the figure is not enough. I suggest more 4489 @c -- text to accompany it. "A picture is worth a thousand words", so you 4490 @c -- have to make sure the reader notices the couple of hundred words 4491 @c -- *you* had in mind more than the others! 4492 4493 @c -- Why an even number of segments? This section implies that this is 4494 @c -- how the main trunk is distinguished from branch roots, but you never 4495 @c -- explicitly say that this is the purpose of the [by itself rather 4496 @c -- surprising] restriction to an even number of segments. 4497 4498 The exact details of how the branch number is 4499 constructed is not something you normally need to be 4500 concerned about, but here is how it works: When 4501 @sc{cvs} creates a branch number it picks the first 4502 unused even integer, starting with 2. So when you want 4503 to create a branch from revision 6.4 it will be 4504 numbered 6.4.2. All branch numbers ending in a zero 4505 (such as 6.4.0) are used internally by @sc{cvs} 4506 (@pxref{Magic branch numbers}). The branch 1.1.1 has a 4507 special meaning. @xref{Tracking sources}. 4508 4509 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4510 @node Magic branch numbers 4511 @section Magic branch numbers 4512 4513 @c Want xref to here from "log"? 4514 4515 This section describes a @sc{cvs} feature called 4516 @dfn{magic branches}. For most purposes, you need not 4517 worry about magic branches; @sc{cvs} handles them for 4518 you. However, they are visible to you in certain 4519 circumstances, so it may be useful to have some idea of 4520 how it works. 4521 4522 Externally, branch numbers consist of an odd number of 4523 dot-separated decimal integers. @xref{Revision 4524 numbers}. That is not the whole truth, however. For 4525 efficiency reasons @sc{cvs} sometimes inserts an extra 0 4526 in the second rightmost position (1.2.4 becomes 4527 1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 4528 on). 4529 4530 @sc{cvs} does a pretty good job at hiding these so 4531 called magic branches, but in a few places the hiding 4532 is incomplete: 4533 4534 @itemize @bullet 4535 @ignore 4536 @c This is in ignore as I'm taking their word for it, 4537 @c that this was fixed 4538 @c a long time ago. But before deleting this 4539 @c entirely, I'd rather verify it (and add a test 4540 @c case to the testsuite). 4541 @item 4542 The magic branch can appear in the output from 4543 @code{cvs status} in vanilla @sc{cvs} 1.3. This is 4544 fixed in @sc{cvs} 1.3-s2. 4545 4546 @end ignore 4547 @item 4548 The magic branch number appears in the output from 4549 @code{cvs log}. 4550 @c What output should appear instead? 4551 4552 @item 4553 You cannot specify a symbolic branch name to @code{cvs 4554 admin}. 4555 4556 @end itemize 4557 4558 @c Can CVS do this automatically the first time 4559 @c you check something in to that branch? Should 4560 @c it? 4561 You can use the @code{admin} command to reassign a 4562 symbolic name to a branch the way @sc{rcs} expects it 4563 to be. If @code{R4patches} is assigned to the branch 4564 1.4.2 (magic branch number 1.4.0.2) in file 4565 @file{numbers.c} you can do this: 4566 4567 @example 4568 $ cvs admin -NR4patches:1.4.2 numbers.c 4569 @end example 4570 4571 It only works if at least one revision is already 4572 committed on the branch. Be very careful so that you 4573 do not assign the tag to the wrong number. (There is 4574 no way to see how the tag was assigned yesterday). 4575 4576 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4577 @node Merging a branch 4578 @section Merging an entire branch 4579 @cindex Merging a branch 4580 @cindex -j (merging branches) 4581 4582 You can merge changes made on a branch into your working copy by giving 4583 the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 4584 @samp{-j @var{branchname}} option it merges the changes made between the 4585 greatest common ancestor (GCA) of the branch and the destination revision (in 4586 the simple case below the GCA is the point where the branch forked) and the 4587 newest revision on that branch into your working copy. 4588 4589 @cindex Join 4590 The @samp{-j} stands for ``join''. 4591 4592 @cindex Branch merge example 4593 @cindex Example, branch merge 4594 @cindex Merge, branch example 4595 Consider this revision tree: 4596 4597 @example 4598 +-----+ +-----+ +-----+ +-----+ 4599 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 4600 +-----+ +-----+ +-----+ +-----+ 4601 ! 4602 ! 4603 ! +---------+ +---------+ 4604 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4605 +---------+ +---------+ 4606 @end example 4607 4608 @noindent 4609 The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 4610 following example assumes that the module @samp{mod} contains only one 4611 file, @file{m.c}. 4612 4613 @example 4614 $ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 4615 4616 $ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 4617 # @r{i.e. the changes between revision 1.2} 4618 # @r{and 1.2.2.2, into your working copy} 4619 # @r{of the file.} 4620 4621 $ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 4622 @end example 4623 4624 A conflict can result from a merge operation. If that 4625 happens, you should resolve it before committing the 4626 new revision. @xref{Conflicts example}. 4627 4628 If your source files contain keywords (@pxref{Keyword substitution}), 4629 you might be getting more conflicts than strictly necessary. See 4630 @ref{Merging and keywords}, for information on how to avoid this. 4631 4632 The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 4633 same effect as above could be achieved with this: 4634 4635 @example 4636 $ cvs checkout -j R1fix mod 4637 $ cvs commit -m "Included R1fix" 4638 @end example 4639 4640 It should be noted that @code{update -j @var{tagname}} will also work but may 4641 not produce the desired result. @xref{Merging adds and removals}, for more. 4642 4643 @node Merging more than once 4644 @section Merging from a branch several times 4645 4646 Continuing our example, the revision tree now looks 4647 like this: 4648 4649 @example 4650 +-----+ +-----+ +-----+ +-----+ +-----+ 4651 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4652 +-----+ +-----+ +-----+ +-----+ +-----+ 4653 ! * 4654 ! * 4655 ! +---------+ +---------+ 4656 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4657 +---------+ +---------+ 4658 @end example 4659 4660 @noindent 4661 where the starred line represents the merge from the 4662 @samp{R1fix} branch to the main trunk, as just 4663 discussed. 4664 4665 Now suppose that development continues on the 4666 @samp{R1fix} branch: 4667 4668 @example 4669 +-----+ +-----+ +-----+ +-----+ +-----+ 4670 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4671 +-----+ +-----+ +-----+ +-----+ +-----+ 4672 ! * 4673 ! * 4674 ! +---------+ +---------+ +---------+ 4675 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4676 +---------+ +---------+ +---------+ 4677 @end example 4678 4679 @noindent 4680 and then you want to merge those new changes onto the 4681 main trunk. If you just use the @code{cvs update -j 4682 R1fix m.c} command again, @sc{cvs} will attempt to 4683 merge again the changes which you have already merged, 4684 which can have undesirable side effects. 4685 4686 So instead you need to specify that you only want to 4687 merge the changes on the branch which have not yet been 4688 merged into the trunk. To do that you specify two 4689 @samp{-j} options, and @sc{cvs} merges the changes from 4690 the first revision to the second revision. For 4691 example, in this case the simplest way would be 4692 4693 @example 4694 cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 4695 # @r{head of the R1fix branch} 4696 @end example 4697 4698 The problem with this is that you need to specify the 4699 1.2.2.2 revision manually. A slightly better approach 4700 might be to use the date the last merge was done: 4701 4702 @example 4703 cvs update -j R1fix:yesterday -j R1fix m.c 4704 @end example 4705 4706 Better yet, tag the R1fix branch after every merge into 4707 the trunk, and then use that tag for subsequent merges: 4708 4709 @example 4710 cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 4711 @end example 4712 4713 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4714 @node Merging two revisions 4715 @section Merging differences between any two revisions 4716 @cindex Merging two revisions 4717 @cindex Revisions, merging differences between 4718 @cindex Differences, merging 4719 4720 With two @samp{-j @var{revision}} flags, the @code{update} 4721 (and @code{checkout}) command can merge the differences 4722 between any two revisions into your working file. 4723 4724 @cindex Undoing a change 4725 @cindex Removing a change 4726 @example 4727 $ cvs update -j 1.5 -j 1.3 backend.c 4728 @end example 4729 4730 @noindent 4731 will undo all changes made between revision 4732 1.3 and 1.5. Note the order of the revisions! 4733 4734 If you try to use this option when operating on 4735 multiple files, remember that the numeric revisions will 4736 probably be very different between the various files. 4737 You almost always use symbolic 4738 tags rather than revision numbers when operating on 4739 multiple files. 4740 4741 @cindex Restoring old version of removed file 4742 @cindex Resurrecting old version of dead file 4743 Specifying two @samp{-j} options can also undo file 4744 removals or additions. For example, suppose you have 4745 a file 4746 named @file{file1} which existed as revision 1.1, and 4747 you then removed it (thus adding a dead revision 1.2). 4748 Now suppose you want to add it again, with the same 4749 contents it had previously. Here is how to do it: 4750 4751 @example 4752 $ cvs update -j 1.2 -j 1.1 file1 4753 U file1 4754 $ cvs commit -m test 4755 Checking in file1; 4756 /tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 4757 new revision: 1.3; previous revision: 1.2 4758 done 4759 $ 4760 @end example 4761 4762 @node Merging adds and removals 4763 @section Merging can add or remove files 4764 4765 If the changes which you are merging involve removing 4766 or adding some files, @code{update -j} will reflect 4767 such additions or removals. 4768 4769 @c FIXME: This example needs a lot more explanation. 4770 @c We also need other examples for some of the other 4771 @c cases (not all--there are too many--as long as we present a 4772 @c coherent general principle). 4773 For example: 4774 @example 4775 cvs update -A 4776 touch a b c 4777 cvs add a b c ; cvs ci -m "added" a b c 4778 cvs tag -b branchtag 4779 cvs update -r branchtag 4780 touch d ; cvs add d 4781 rm a ; cvs rm a 4782 cvs ci -m "added d, removed a" 4783 cvs update -A 4784 cvs update -jbranchtag 4785 @end example 4786 4787 After these commands are executed and a @samp{cvs commit} is done, 4788 file @file{a} will be removed and file @file{d} added in the main branch. 4789 @c (which was determined by trying it) 4790 4791 Note that using a single static tag (@samp{-j @var{tagname}}) 4792 rather than a dynamic tag (@samp{-j @var{branchname}}) to merge 4793 changes from a branch will usually not remove files which were removed on the 4794 branch since @sc{cvs} does not automatically add static tags to dead revisions. 4795 The exception to this rule occurs when 4796 a static tag has been attached to a dead revision manually. Use the branch tag 4797 to merge all changes from the branch or use two static tags as merge endpoints 4798 to be sure that all intended changes are propagated in the merge. 4799 4800 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4801 @node Merging and keywords 4802 @section Merging and keywords 4803 @cindex Merging, and keyword substitution 4804 @cindex Keyword substitution, and merging 4805 @cindex -j (merging branches), and keyword substitution 4806 @cindex -kk, to avoid conflicts during a merge 4807 4808 If you merge files containing keywords (@pxref{Keyword 4809 substitution}), you will normally get numerous 4810 conflicts during the merge, because the keywords are 4811 expanded differently in the revisions which you are 4812 merging. 4813 4814 Therefore, you will often want to specify the 4815 @samp{-kk} (@pxref{Substitution modes}) switch to the 4816 merge command line. By substituting just the name of 4817 the keyword, not the expanded value of that keyword, 4818 this option ensures that the revisions which you are 4819 merging will be the same as each other, and avoid 4820 spurious conflicts. 4821 4822 For example, suppose you have a file like this: 4823 4824 @example 4825 +---------+ 4826 _! 1.1.2.1 ! <- br1 4827 / +---------+ 4828 / 4829 / 4830 +-----+ +-----+ 4831 ! 1.1 !----! 1.2 ! 4832 +-----+ +-----+ 4833 @end example 4834 4835 @noindent 4836 and your working directory is currently on the trunk 4837 (revision 1.2). Then you might get the following 4838 results from a merge: 4839 4840 @example 4841 $ cat file1 4842 key $@splitrcskeyword{Revision}: 1.2 $ 4843 . . . 4844 $ cvs update -j br1 4845 U file1 4846 RCS file: /cvsroot/first-dir/file1,v 4847 retrieving revision 1.1 4848 retrieving revision 1.1.2.1 4849 Merging differences between 1.1 and 1.1.2.1 into file1 4850 rcsmerge: warning: conflicts during merge 4851 $ cat file1 4852 @asis{}<<<<<<< file1 4853 key $@splitrcskeyword{Revision}: 1.2 $ 4854 @asis{}======= 4855 key $@splitrcskeyword{Revision}: 1.1.2.1 $ 4856 @asis{}>>>>>>> 1.1.2.1 4857 . . . 4858 @end example 4859 4860 What happened was that the merge tried to merge the 4861 differences between 1.1 and 1.1.2.1 into your working 4862 directory. So, since the keyword changed from 4863 @code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 4864 @sc{cvs} tried to merge that change into your working 4865 directory, which conflicted with the fact that your 4866 working directory had contained @code{Revision: 1.2}. 4867 4868 Here is what happens if you had used @samp{-kk}: 4869 4870 @example 4871 $ cat file1 4872 key $@splitrcskeyword{Revision}: 1.2 $ 4873 . . . 4874 $ cvs update -kk -j br1 4875 U file1 4876 RCS file: /cvsroot/first-dir/file1,v 4877 retrieving revision 1.1 4878 retrieving revision 1.1.2.1 4879 Merging differences between 1.1 and 1.1.2.1 into file1 4880 $ cat file1 4881 key $@splitrcskeyword{Revision}$ 4882 . . . 4883 @end example 4884 4885 What is going on here is that revision 1.1 and 1.1.2.1 4886 both expand as plain @code{Revision}, and therefore 4887 merging the changes between them into the working 4888 directory need not change anything. Therefore, there 4889 is no conflict. 4890 4891 @strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a 4892 major problem with using @samp{-kk} on merges. Namely, @samp{-kk} 4893 overrode any default keyword expansion mode set in the archive file in 4894 the repository. This could, unfortunately for some users, cause data 4895 corruption in binary files (with a default keyword expansion mode set 4896 to @samp{-kb}). Therefore, when a repository contained binary files, 4897 conflicts had to be dealt with manually rather than using @samp{-kk} in 4898 a merge command.} 4899 4900 In @sc{cvs} version 1.12.2 and later, the keyword expansion mode 4901 provided on the command line to any @sc{cvs} command no longer 4902 overrides the @samp{-kb} keyword expansion mode setting for binary 4903 files, though it will still override other default keyword expansion 4904 modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts 4905 on lines containing RCS keywords, even when your repository contains 4906 binary files. 4907 4908 @c --------------------------------------------------------------------- 4909 @node Recursive behavior 4910 @chapter Recursive behavior 4911 @cindex Recursive (directory descending) 4912 @cindex Directory, descending 4913 @cindex Descending directories 4914 @cindex Subdirectories 4915 4916 Almost all of the subcommands of @sc{cvs} work 4917 recursively when you specify a directory as an 4918 argument. For instance, consider this directory 4919 structure: 4920 4921 @example 4922 @code{$HOME} 4923 | 4924 +--@t{tc} 4925 | | 4926 +--@t{CVS} 4927 | (internal @sc{cvs} files) 4928 +--@t{Makefile} 4929 +--@t{backend.c} 4930 +--@t{driver.c} 4931 +--@t{frontend.c} 4932 +--@t{parser.c} 4933 +--@t{man} 4934 | | 4935 | +--@t{CVS} 4936 | | (internal @sc{cvs} files) 4937 | +--@t{tc.1} 4938 | 4939 +--@t{testing} 4940 | 4941 +--@t{CVS} 4942 | (internal @sc{cvs} files) 4943 +--@t{testpgm.t} 4944 +--@t{test2.t} 4945 @end example 4946 4947 @noindent 4948 If @file{tc} is the current working directory, the 4949 following is true: 4950 4951 @itemize @bullet 4952 @item 4953 @samp{cvs update testing} is equivalent to 4954 4955 @example 4956 cvs update testing/testpgm.t testing/test2.t 4957 @end example 4958 4959 @item 4960 @samp{cvs update testing man} updates all files in the 4961 subdirectories 4962 4963 @item 4964 @samp{cvs update .} or just @samp{cvs update} updates 4965 all files in the @code{tc} directory 4966 @end itemize 4967 4968 If no arguments are given to @code{update} it will 4969 update all files in the current working directory and 4970 all its subdirectories. In other words, @file{.} is a 4971 default argument to @code{update}. This is also true 4972 for most of the @sc{cvs} subcommands, not only the 4973 @code{update} command. 4974 4975 The recursive behavior of the @sc{cvs} subcommands can be 4976 turned off with the @samp{-l} option. 4977 Conversely, the @samp{-R} option can be used to force recursion if 4978 @samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 4979 4980 @example 4981 $ cvs update -l # @r{Don't update files in subdirectories} 4982 @end example 4983 4984 @c --------------------------------------------------------------------- 4985 @node Adding and removing 4986 @chapter Adding, removing, and renaming files and directories 4987 4988 In the course of a project, one will often add new 4989 files. Likewise with removing or renaming, or with 4990 directories. The general concept to keep in mind in 4991 all these cases is that instead of making an 4992 irreversible change you want @sc{cvs} to record the 4993 fact that a change has taken place, just as with 4994 modifying an existing file. The exact mechanisms to do 4995 this in @sc{cvs} vary depending on the situation. 4996 4997 @menu 4998 * Adding files:: Adding files 4999 * Removing files:: Removing files 5000 * Removing directories:: Removing directories 5001 * Moving files:: Moving and renaming files 5002 * Moving directories:: Moving and renaming directories 5003 @end menu 5004 5005 @node Adding files 5006 @section Adding files to a directory 5007 @cindex Adding files 5008 5009 To add a new file to a directory, follow these steps. 5010 5011 @itemize @bullet 5012 @item 5013 You must have a working copy of the directory. 5014 @xref{Getting the source}. 5015 5016 @item 5017 Create the new file inside your working copy of the directory. 5018 5019 @item 5020 Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you 5021 want to version control the file. If the file contains 5022 binary data, specify @samp{-kb} (@pxref{Binary files}). 5023 5024 @item 5025 Use @samp{cvs commit @var{filename}} to actually check 5026 in the file into the repository. Other developers 5027 cannot see the file until you perform this step. 5028 @end itemize 5029 5030 You can also use the @code{add} command to add a new 5031 directory. 5032 @c FIXCVS and/or FIXME: Adding a directory doesn't 5033 @c require the commit step. This probably can be 5034 @c considered a CVS bug, but it is possible we should 5035 @c warn people since this behavior probably won't be 5036 @c changing right away. 5037 5038 Unlike most other commands, the @code{add} command is 5039 not recursive. You have to explicitly name files and 5040 directories that you wish to add to the repository. 5041 However, each directory will need to be added 5042 separately before you will be able to add new files 5043 to those directories. 5044 5045 @example 5046 $ mkdir -p foo/bar 5047 $ cp ~/myfile foo/bar/myfile 5048 $ cvs add foo foo/bar 5049 $ cvs add foo/bar/myfile 5050 @end example 5051 5052 @cindex add (subcommand) 5053 @deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 5054 5055 Schedule @var{files} to be added to the repository. 5056 The files or directories specified with @code{add} must 5057 already exist in the current directory. To add a whole 5058 new directory hierarchy to the source repository (for 5059 example, files received from a third-party vendor), use 5060 the @code{import} command instead. @xref{import}. 5061 5062 The added files are not placed in the source repository 5063 until you use @code{commit} to make the change 5064 permanent. Doing an @code{add} on a file that was 5065 removed with the @code{remove} command will undo the 5066 effect of the @code{remove}, unless a @code{commit} 5067 command intervened. @xref{Removing files}, for an 5068 example. 5069 5070 The @samp{-k} option specifies the default way that 5071 this file will be checked out; for more information see 5072 @ref{Substitution modes}. 5073 5074 @c As noted in BUGS, -m is broken client/server (Nov 5075 @c 96). Also see testsuite log2-* tests. 5076 The @samp{-m} option specifies a description for the 5077 file. This description appears in the history log (if 5078 it is enabled, @pxref{history file}). It will also be 5079 saved in the version history inside the repository when 5080 the file is committed. The @code{log} command displays 5081 this description. The description can be changed using 5082 @samp{admin -t}. @xref{admin}. If you omit the 5083 @samp{-m @var{description}} flag, an empty string will 5084 be used. You will not be prompted for a description. 5085 @end deffn 5086 5087 For example, the following commands add the file 5088 @file{backend.c} to the repository: 5089 5090 @c This example used to specify 5091 @c -m "Optimizer and code generation passes." 5092 @c to the cvs add command, but that doesn't work 5093 @c client/server (see log2 in sanity.sh). Should fix CVS, 5094 @c but also seems strange to document things which 5095 @c don't work... 5096 @example 5097 $ cvs add backend.c 5098 $ cvs commit -m "Early version. Not yet compilable." backend.c 5099 @end example 5100 5101 When you add a file it is added only on the branch 5102 which you are working on (@pxref{Branching and merging}). You can 5103 later merge the additions to another branch if you want 5104 (@pxref{Merging adds and removals}). 5105 @c Should we mention that earlier versions of CVS 5106 @c lacked this feature (1.3) or implemented it in a buggy 5107 @c way (well, 1.8 had many bugs in cvs update -j)? 5108 @c Should we mention the bug/limitation regarding a 5109 @c file being a regular file on one branch and a directory 5110 @c on another? 5111 @c FIXME: This needs an example, or several, here or 5112 @c elsewhere, for it to make much sense. 5113 @c Somewhere we need to discuss the aspects of death 5114 @c support which don't involve branching, I guess. 5115 @c Like the ability to re-create a release from a tag. 5116 5117 @c --------------------------------------------------------------------- 5118 @node Removing files 5119 @section Removing files 5120 @cindex Removing files 5121 @cindex Deleting files 5122 5123 @c FIXME: this node wants to be split into several 5124 @c smaller nodes. Could make these children of 5125 @c "Adding and removing", probably (death support could 5126 @c be its own section, for example, as could the 5127 @c various bits about undoing mistakes in adding and 5128 @c removing). 5129 Directories change. New files are added, and old files 5130 disappear. Still, you want to be able to retrieve an 5131 exact copy of old releases. 5132 5133 Here is what you can do to remove a file, 5134 but remain able to retrieve old revisions: 5135 5136 @itemize @bullet 5137 @c FIXME: should probably be saying something about 5138 @c having a working directory in the first place. 5139 @item 5140 Make sure that you have not made any uncommitted 5141 modifications to the file. @xref{Viewing differences}, 5142 for one way to do that. You can also use the 5143 @code{status} or @code{update} command. If you remove 5144 the file without committing your changes, you will of 5145 course not be able to retrieve the file as it was 5146 immediately before you deleted it. 5147 5148 @item 5149 Remove the file from your working copy of the directory. 5150 You can for instance use @code{rm}. 5151 5152 @item 5153 Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that 5154 you really want to delete the file. 5155 5156 @item 5157 Use @samp{cvs commit @var{filename}} to actually 5158 perform the removal of the file from the repository. 5159 @end itemize 5160 5161 @c FIXME: Somehow this should be linked in with a more 5162 @c general discussion of death support. I don't know 5163 @c whether we want to use the term "death support" or 5164 @c not (we can perhaps get by without it), but we do 5165 @c need to discuss the "dead" state in "cvs log" and 5166 @c related subjects. The current discussion is 5167 @c scattered around, and not xref'd to each other. 5168 @c FIXME: I think this paragraph wants to be moved 5169 @c later down, at least after the first example. 5170 When you commit the removal of the file, @sc{cvs} 5171 records the fact that the file no longer exists. It is 5172 possible for a file to exist on only some branches and 5173 not on others, or to re-add another file with the same 5174 name later. @sc{cvs} will correctly create or not create 5175 the file, based on the @samp{-r} and @samp{-D} options 5176 specified to @code{checkout} or @code{update}. 5177 5178 @c FIXME: This style seems to clash with how we 5179 @c document things in general. 5180 @cindex Remove (subcommand) 5181 @deffn Command {cvs remove} [options] files @dots{} 5182 5183 Schedule file(s) to be removed from the repository 5184 (files which have not already been removed from the 5185 working directory are not processed). This command 5186 does not actually remove the file from the repository 5187 until you commit the removal. For a full list of 5188 options, see @ref{Invoking CVS}. 5189 @end deffn 5190 5191 Here is an example of removing several files: 5192 5193 @example 5194 $ cd test 5195 $ rm *.c 5196 $ cvs remove 5197 cvs remove: Removing . 5198 cvs remove: scheduling a.c for removal 5199 cvs remove: scheduling b.c for removal 5200 cvs remove: use 'cvs commit' to remove these files permanently 5201 $ cvs ci -m "Removed unneeded files" 5202 cvs commit: Examining . 5203 cvs commit: Committing . 5204 @end example 5205 5206 As a convenience you can remove the file and @code{cvs 5207 remove} it in one step, by specifying the @samp{-f} 5208 option. For example, the above example could also be 5209 done like this: 5210 5211 @example 5212 $ cd test 5213 $ cvs remove -f *.c 5214 cvs remove: scheduling a.c for removal 5215 cvs remove: scheduling b.c for removal 5216 cvs remove: use 'cvs commit' to remove these files permanently 5217 $ cvs ci -m "Removed unneeded files" 5218 cvs commit: Examining . 5219 cvs commit: Committing . 5220 @end example 5221 5222 If you execute @code{remove} for a file, and then 5223 change your mind before you commit, you can undo the 5224 @code{remove} with an @code{add} command. 5225 @ignore 5226 @c is this worth saying or not? Somehow it seems 5227 @c confusing to me. 5228 Of course, 5229 since you have removed your copy of file in the working 5230 directory, @sc{cvs} does not necessarily bring back the 5231 contents of the file from right before you executed 5232 @code{remove}; instead it gets the file from the 5233 repository again. 5234 @end ignore 5235 5236 @c FIXME: what if you change your mind after you commit 5237 @c it? (answer is also "cvs add" but we don't say that...). 5238 @c We need some index entries for thinks like "undoing 5239 @c removal" too. 5240 5241 @example 5242 $ ls 5243 CVS ja.h oj.c 5244 $ rm oj.c 5245 $ cvs remove oj.c 5246 cvs remove: scheduling oj.c for removal 5247 cvs remove: use 'cvs commit' to remove this file permanently 5248 $ cvs add oj.c 5249 U oj.c 5250 cvs add: oj.c, version 1.1.1.1, resurrected 5251 @end example 5252 5253 If you realize your mistake before you run the 5254 @code{remove} command you can use @code{update} to 5255 resurrect the file: 5256 5257 @example 5258 $ rm oj.c 5259 $ cvs update oj.c 5260 cvs update: warning: oj.c was lost 5261 U oj.c 5262 @end example 5263 5264 When you remove a file it is removed only on the branch 5265 which you are working on (@pxref{Branching and merging}). You can 5266 later merge the removals to another branch if you want 5267 (@pxref{Merging adds and removals}). 5268 5269 @node Removing directories 5270 @section Removing directories 5271 @cindex Removing directories 5272 @cindex Directories, removing 5273 5274 In concept, removing directories is somewhat similar to 5275 removing files---you want the directory to not exist in 5276 your current working directories, but you also want to 5277 be able to retrieve old releases in which the directory 5278 existed. 5279 5280 The way that you remove a directory is to remove all 5281 the files in it. You don't remove the directory 5282 itself; there is no way to do that. 5283 Instead you specify the @samp{-P} option to 5284 @code{cvs update} or @code{cvs checkout}, 5285 which will cause @sc{cvs} to remove empty 5286 directories from working directories. 5287 (Note that @code{cvs export} always removes empty directories.) 5288 Probably the 5289 best way to do this is to always specify @samp{-P}; if 5290 you want an empty directory then put a dummy file (for 5291 example @file{.keepme}) in it to prevent @samp{-P} from 5292 removing it. 5293 5294 @c I'd try to give a rationale for this, but I'm not 5295 @c sure there is a particularly convincing one. What 5296 @c we would _like_ is for CVS to do a better job of version 5297 @c controlling whether directories exist, to eliminate the 5298 @c need for -P and so that a file can be a directory in 5299 @c one revision and a regular file in another. 5300 Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5301 options of @code{checkout}. This way, 5302 @sc{cvs} will be able to correctly create the directory 5303 or not depending on whether the particular version you 5304 are checking out contains any files in that directory. 5305 5306 @c --------------------------------------------------------------------- 5307 @node Moving files 5308 @section Moving and renaming files 5309 @cindex Moving files 5310 @cindex Renaming files 5311 @cindex Files, moving 5312 5313 Moving files to a different directory or renaming them 5314 is not difficult, but some of the ways in which this 5315 works may be non-obvious. (Moving or renaming a 5316 directory is even harder. @xref{Moving directories}.). 5317 5318 The examples below assume that the file @var{old} is renamed to 5319 @var{new}. 5320 5321 @menu 5322 * Outside:: The normal way to Rename 5323 * Inside:: A tricky, alternative way 5324 * Rename by copying:: Another tricky, alternative way 5325 @end menu 5326 5327 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5328 @node Outside 5329 @subsection The Normal way to Rename 5330 5331 @c More rename issues. Not sure whether these are 5332 @c worth documenting; I'm putting them here because 5333 @c it seems to be as good a place as any to try to 5334 @c set down the issues. 5335 @c * "cvs annotate" will annotate either the new 5336 @c file or the old file; it cannot annotate _each 5337 @c line_ based on whether it was last changed in the 5338 @c new or old file. Unlike "cvs log", where the 5339 @c consequences of having to select either the new 5340 @c or old name seem fairly benign, this may be a 5341 @c real advantage to having CVS know about renames 5342 @c other than as a deletion and an addition. 5343 5344 The normal way to move a file is to copy @var{old} to 5345 @var{new}, and then issue the normal @sc{cvs} commands 5346 to remove @var{old} from the repository, and add 5347 @var{new} to it. 5348 @c The following sentence is not true: one must cd into 5349 @c the directory to run "cvs add". 5350 @c (Both @var{old} and @var{new} could 5351 @c contain relative paths, for example @file{foo/bar.c}). 5352 5353 @example 5354 $ mv @var{old} @var{new} 5355 $ cvs remove @var{old} 5356 $ cvs add @var{new} 5357 $ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 5358 @end example 5359 5360 This is the simplest way to move a file, it is not 5361 error-prone, and it preserves the history of what was 5362 done. Note that to access the history of the file you 5363 must specify the old or the new name, depending on what 5364 portion of the history you are accessing. For example, 5365 @code{cvs log @var{old}} will give the log up until the 5366 time of the rename. 5367 5368 When @var{new} is committed its revision numbers will 5369 start again, usually at 1.1, so if that bothers you, 5370 use the @samp{-r @var{tag}} option to commit. For more 5371 information see @ref{Assigning revisions}. 5372 5373 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5374 @node Inside 5375 @subsection Moving the history file 5376 5377 This method is more dangerous, since it involves moving 5378 files inside the repository. Read this entire section 5379 before trying it out! 5380 5381 @example 5382 $ cd $CVSROOT/@var{dir} 5383 $ mv @var{old},v @var{new},v 5384 @end example 5385 5386 @noindent 5387 Advantages: 5388 5389 @itemize @bullet 5390 @item 5391 The log of changes is maintained intact. 5392 5393 @item 5394 The revision numbers are not affected. 5395 @end itemize 5396 5397 @noindent 5398 Disadvantages: 5399 5400 @itemize @bullet 5401 @item 5402 Old releases cannot easily be fetched from the 5403 repository. (The file will show up as @var{new} even 5404 in revisions from the time before it was renamed). 5405 5406 @item 5407 There is no log information of when the file was renamed. 5408 5409 @item 5410 Nasty things might happen if someone accesses the history file 5411 while you are moving it. Make sure no one else runs any of the @sc{cvs} 5412 commands while you move it. 5413 @end itemize 5414 5415 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5416 @node Rename by copying 5417 @subsection Copying the history file 5418 5419 This way also involves direct modifications to the 5420 repository. It is safe, but not without drawbacks. 5421 5422 @example 5423 # @r{Copy the @sc{rcs} file inside the repository} 5424 $ cd $CVSROOT/@var{dir} 5425 $ cp @var{old},v @var{new},v 5426 # @r{Remove the old file} 5427 $ cd ~/@var{dir} 5428 $ rm @var{old} 5429 $ cvs remove @var{old} 5430 $ cvs commit @var{old} 5431 # @r{Remove all tags from @var{new}} 5432 $ cvs update @var{new} 5433 $ cvs log @var{new} # @r{Remember the non-branch tag names} 5434 $ cvs tag -d @var{tag1} @var{new} 5435 $ cvs tag -d @var{tag2} @var{new} 5436 @dots{} 5437 @end example 5438 5439 By removing the tags you will be able to check out old 5440 revisions. 5441 5442 @noindent 5443 Advantages: 5444 5445 @itemize @bullet 5446 @item 5447 @c FIXME: Is this true about -D now that we have death 5448 @c support? See 5B.3 in the FAQ. 5449 Checking out old revisions works correctly, as long as 5450 you use @samp{-r @var{tag}} and not @samp{-D @var{date}} 5451 to retrieve the revisions. 5452 5453 @item 5454 The log of changes is maintained intact. 5455 5456 @item 5457 The revision numbers are not affected. 5458 @end itemize 5459 5460 @noindent 5461 Disadvantages: 5462 5463 @itemize @bullet 5464 @item 5465 You cannot easily see the history of the file across the rename. 5466 5467 @ignore 5468 @c Is this true? I don't see how the revision numbers 5469 @c _could_ start over, when new,v is just old,v with 5470 @c the tags deleted. 5471 @c If there is some need to reinstate this text, 5472 @c it is "usually 1.1", not "1.0" and it needs an 5473 @c xref to Assigning revisions 5474 @item 5475 Unless you use the @samp{-r @var{tag}} (@pxref{commit 5476 options}) flag when @var{new} is committed its revision 5477 numbers will start at 1.0 again. 5478 @end ignore 5479 @end itemize 5480 5481 @c --------------------------------------------------------------------- 5482 @node Moving directories 5483 @section Moving and renaming directories 5484 @cindex Moving directories 5485 @cindex Renaming directories 5486 @cindex Directories, moving 5487 5488 The normal way to rename or move a directory is to 5489 rename or move each file within it as described in 5490 @ref{Outside}. Then check out with the @samp{-P} 5491 option, as described in @ref{Removing directories}. 5492 5493 If you really want to hack the repository to rename or 5494 delete a directory in the repository, you can do it 5495 like this: 5496 5497 @enumerate 5498 @item 5499 Inform everyone who has a checked out copy of the directory that the 5500 directory will be renamed. They should commit all their changes in all their 5501 copies of the project containing the directory to be removed, and remove 5502 all their working copies of said project, before you take the steps below. 5503 5504 @item 5505 Rename the directory inside the repository. 5506 5507 @example 5508 $ cd $CVSROOT/@var{parent-dir} 5509 $ mv @var{old-dir} @var{new-dir} 5510 @end example 5511 5512 @item 5513 Fix the @sc{cvs} administrative files, if necessary (for 5514 instance if you renamed an entire module). 5515 5516 @item 5517 Tell everyone that they can check out again and continue 5518 working. 5519 5520 @end enumerate 5521 5522 If someone had a working copy the @sc{cvs} commands will 5523 cease to work for him, until he removes the directory 5524 that disappeared inside the repository. 5525 5526 It is almost always better to move the files in the 5527 directory instead of moving the directory. If you move the 5528 directory you are unlikely to be able to retrieve old 5529 releases correctly, since they probably depend on the 5530 name of the directories. 5531 5532 @c --------------------------------------------------------------------- 5533 @node History browsing 5534 @chapter History browsing 5535 @cindex History browsing 5536 @cindex Traceability 5537 @cindex Isolation 5538 5539 @ignore 5540 @c This is too long for an introduction (goal is 5541 @c one 20x80 character screen), and also mixes up a 5542 @c variety of issues (parallel development, history, 5543 @c maybe even touches on process control). 5544 5545 @c -- @quote{To lose ones history is to lose ones soul.} 5546 @c -- /// 5547 @c -- ///Those who cannot remember the past are condemned to repeat it. 5548 @c -- /// -- George Santayana 5549 @c -- /// 5550 5551 @sc{cvs} tries to make it easy for a group of people to work 5552 together. This is done in two ways: 5553 5554 @itemize @bullet 5555 @item 5556 Isolation---You have your own working copy of the 5557 source. You are not affected by modifications made by 5558 others until you decide to incorporate those changes 5559 (via the @code{update} command---@pxref{update}). 5560 5561 @item 5562 Traceability---When something has changed, you can 5563 always see @emph{exactly} what changed. 5564 @end itemize 5565 5566 There are several features of @sc{cvs} that together lead 5567 to traceability: 5568 5569 @itemize @bullet 5570 @item 5571 Each revision of a file has an accompanying log 5572 message. 5573 5574 @item 5575 All commits are optionally logged to a central history 5576 database. 5577 5578 @item 5579 Logging information can be sent to a user-defined 5580 program (@pxref{loginfo}). 5581 @end itemize 5582 5583 @c -- More text here. 5584 5585 This chapter should talk about the history file, the 5586 @code{log} command, the usefulness of ChangeLogs 5587 even when you run @sc{cvs}, and things like that. 5588 5589 @end ignore 5590 5591 @c kind of lame, in a lot of ways the above text inside 5592 @c the @ignore motivates this chapter better 5593 Once you have used @sc{cvs} to store a version control 5594 history---what files have changed when, how, and by 5595 whom, there are a variety of mechanisms for looking 5596 through the history. 5597 5598 @c FIXME: should also be talking about how you look at 5599 @c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 5600 @menu 5601 * log messages:: Log messages 5602 * history database:: The history database 5603 * user-defined logging:: User-defined logging 5604 @end menu 5605 5606 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5607 @node log messages 5608 @section Log messages 5609 5610 @c FIXME: @xref to place where we talk about how to 5611 @c specify message to commit. 5612 Whenever you commit a file you specify a log message. 5613 5614 @c FIXME: bring the information here, and get rid of or 5615 @c greatly shrink the "log" node. 5616 To look through the log messages which have been 5617 specified for every revision which has been committed, 5618 use the @code{cvs log} command (@pxref{log & rlog}). 5619 5620 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5621 @node history database 5622 @section The history database 5623 5624 @c FIXME: bring the information from the history file 5625 @c and history nodes here. Rewrite it to be motivated 5626 @c better (start out by clearly explaining what gets 5627 @c logged in history, for example). 5628 You can use the history file (@pxref{history file}) to 5629 log various @sc{cvs} actions. To retrieve the 5630 information from the history file, use the @code{cvs 5631 history} command (@pxref{history}). 5632 5633 Note: you can control what is logged to this file by using the 5634 @samp{LogHistory} keyword in the @file{CVSROOT/config} file 5635 (@pxref{config}). 5636 5637 @c 5638 @c The history database has many problems: 5639 @c * It is very unclear what field means what. This 5640 @c could be improved greatly by better documentation, 5641 @c but there are still non-orthogonalities (for 5642 @c example, tag does not record the "repository" 5643 @c field but most records do). 5644 @c * Confusion about files, directories, and modules. 5645 @c Some commands record one, some record others. 5646 @c * File removal is not logged. There is an 'R' 5647 @c record type documented, but CVS never uses it. 5648 @c * Tags are only logged for the "cvs rtag" command, 5649 @c not "cvs tag". The fix for this is not completely 5650 @c clear (see above about modules vs. files). 5651 @c * Are there other cases of operations that are not 5652 @c logged? One would hope for all changes to the 5653 @c repository to be logged somehow (particularly 5654 @c operations like tagging, "cvs admin -k", and other 5655 @c operations which do not record a history that one 5656 @c can get with "cvs log"). Operations on the working 5657 @c directory, like export, get, and release, are a 5658 @c second category also covered by the current "cvs 5659 @c history". 5660 @c * The history file does not record the options given 5661 @c to a command. The most serious manifestation of 5662 @c this is perhaps that it doesn't record whether a command 5663 @c was recursive. It is not clear to me whether one 5664 @c wants to log at a level very close to the command 5665 @c line, as a sort of way of logging each command 5666 @c (more or less), or whether one wants 5667 @c to log more at the level of what was changed (or 5668 @c something in between), but either way the current 5669 @c information has pretty big gaps. 5670 @c * Further details about a tag--like whether it is a 5671 @c branch tag or, if a non-branch tag, which branch it 5672 @c is on. One can find out this information about the 5673 @c tag as it exists _now_, but if the tag has been 5674 @c moved, one doesn't know what it was like at the time 5675 @c the history record was written. 5676 @c * Whether operating on a particular tag, date, or 5677 @c options was implicit (sticky) or explicit. 5678 @c 5679 @c Another item, only somewhat related to the above, is a 5680 @c way to control what is logged in the history file. 5681 @c This is probably the only good way to handle 5682 @c different people having different ideas about 5683 @c information/space tradeoffs. 5684 @c 5685 @c It isn't really clear that it makes sense to try to 5686 @c patch up the history file format as it exists now to 5687 @c include all that stuff. It might be better to 5688 @c design a whole new CVSROOT/nhistory file and "cvs 5689 @c nhistory" command, or some such, or in some other 5690 @c way trying to come up with a clean break from the 5691 @c past, which can address the above concerns. Another 5692 @c open question is how/whether this relates to 5693 @c taginfo/loginfo/etc. 5694 5695 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5696 @node user-defined logging 5697 @section User-defined logging 5698 5699 @c FIXME: probably should centralize this information 5700 @c here, at least to some extent. Maybe by moving the 5701 @c loginfo, etc., nodes here and replacing 5702 @c the "user-defined logging" node with one node for 5703 @c each method. 5704 You can customize @sc{cvs} to log various kinds of 5705 actions, in whatever manner you choose. These 5706 mechanisms operate by executing a script at various 5707 times. The script might append a message to a file 5708 listing the information and the programmer who created 5709 it, or send mail to a group of developers, or, perhaps, 5710 post a message to a particular newsgroup. To log 5711 commits, use the @file{loginfo} file (@pxref{loginfo}), and 5712 to log tagging operations, use the @file{taginfo} file 5713 (@pxref{taginfo}). 5714 5715 @c FIXME: What is difference between doing it in the 5716 @c modules file and using loginfo/taginfo? Why should 5717 @c user use one or the other? 5718 To log commits, checkouts, exports, and tags, 5719 respectively, you can also use the @samp{-i}, 5720 @samp{-o}, @samp{-e}, and @samp{-t} options in the 5721 modules file. For a more flexible way of giving 5722 notifications to various users, which requires less in 5723 the way of keeping centralized scripts up to date, use 5724 the @code{cvs watch add} command (@pxref{Getting 5725 Notified}); this command is useful even if you are not 5726 using @code{cvs watch on}. 5727 5728 @c --------------------------------------------------------------------- 5729 @node Binary files 5730 @chapter Handling binary files 5731 @cindex Binary files 5732 5733 The most common use for @sc{cvs} is to store text 5734 files. With text files, @sc{cvs} can merge revisions, 5735 display the differences between revisions in a 5736 human-visible fashion, and other such operations. 5737 However, if you are willing to give up a few of these 5738 abilities, @sc{cvs} can store binary files. For 5739 example, one might store a web site in @sc{cvs} 5740 including both text files and binary images. 5741 5742 @menu 5743 * Binary why:: More details on issues with binary files 5744 * Binary howto:: How to store them 5745 @end menu 5746 5747 @node Binary why 5748 @section The issues with binary files 5749 5750 While the need to manage binary files may seem obvious 5751 if the files that you customarily work with are binary, 5752 putting them into version control does present some 5753 additional issues. 5754 5755 One basic function of version control is to show the 5756 differences between two revisions. For example, if 5757 someone else checked in a new version of a file, you 5758 may wish to look at what they changed and determine 5759 whether their changes are good. For text files, 5760 @sc{cvs} provides this functionality via the @code{cvs 5761 diff} command. For binary files, it may be possible to 5762 extract the two revisions and then compare them with a 5763 tool external to @sc{cvs} (for example, word processing 5764 software often has such a feature). If there is no 5765 such tool, one must track changes via other mechanisms, 5766 such as urging people to write good log messages, and 5767 hoping that the changes they actually made were the 5768 changes that they intended to make. 5769 5770 Another ability of a version control system is the 5771 ability to merge two revisions. For @sc{cvs} this 5772 happens in two contexts. The first is when users make 5773 changes in separate working directories 5774 (@pxref{Multiple developers}). The second is when one 5775 merges explicitly with the @samp{update -j} command 5776 (@pxref{Branching and merging}). 5777 5778 In the case of text 5779 files, @sc{cvs} can merge changes made independently, 5780 and signal a conflict if the changes conflict. With 5781 binary files, the best that @sc{cvs} can do is present 5782 the two different copies of the file, and leave it to 5783 the user to resolve the conflict. The user may choose 5784 one copy or the other, or may run an external merge 5785 tool which knows about that particular file format, if 5786 one exists. 5787 Note that having the user merge relies primarily on the 5788 user to not accidentally omit some changes, and thus is 5789 potentially error prone. 5790 5791 If this process is thought to be undesirable, the best 5792 choice may be to avoid merging. To avoid the merges 5793 that result from separate working directories, see the 5794 discussion of reserved checkouts (file locking) in 5795 @ref{Multiple developers}. To avoid the merges 5796 resulting from branches, restrict use of branches. 5797 5798 @node Binary howto 5799 @section How to store binary files 5800 5801 There are two issues with using @sc{cvs} to store 5802 binary files. The first is that @sc{cvs} by default 5803 converts line endings between the canonical form in 5804 which they are stored in the repository (linefeed 5805 only), and the form appropriate to the operating system 5806 in use on the client (for example, carriage return 5807 followed by line feed for Windows NT). 5808 5809 The second is that a binary file might happen to 5810 contain data which looks like a keyword (@pxref{Keyword 5811 substitution}), so keyword expansion must be turned 5812 off. 5813 5814 @c FIXME: the third is that one can't do merges with 5815 @c binary files. xref to Multiple Developers and the 5816 @c reserved checkout issues. 5817 5818 The @samp{-kb} option available with some @sc{cvs} 5819 commands insures that neither line ending conversion 5820 nor keyword expansion will be done. 5821 5822 Here is an example of how you can create a new file 5823 using the @samp{-kb} flag: 5824 5825 @example 5826 $ echo '$@splitrcskeyword{Id}$' > kotest 5827 $ cvs add -kb -m"A test file" kotest 5828 $ cvs ci -m"First checkin; contains a keyword" kotest 5829 @end example 5830 5831 If a file accidentally gets added without @samp{-kb}, 5832 one can use the @code{cvs admin} command to recover. 5833 For example: 5834 5835 @example 5836 $ echo '$@splitrcskeyword{Id}$' > kotest 5837 $ cvs add -m"A test file" kotest 5838 $ cvs ci -m"First checkin; contains a keyword" kotest 5839 $ cvs admin -kb kotest 5840 $ cvs update -A kotest 5841 # @r{For non-unix systems:} 5842 # @r{Copy in a good copy of the file from outside CVS} 5843 $ cvs commit -m "make it binary" kotest 5844 @end example 5845 5846 @c Trying to describe this for both unix and non-unix 5847 @c in the same description is very confusing. Might 5848 @c want to split the two, or just ditch the unix "shortcut" 5849 @c (unixheads don't do much with binary files, anyway). 5850 @c This used to say "(Try the above example, and do a 5851 @c @code{cat kotest} after every command)". But that 5852 @c only really makes sense for the unix case. 5853 When you check in the file @file{kotest} the file is 5854 not preserved as a binary file, because you did not 5855 check it in as a binary file. The @code{cvs 5856 admin -kb} command sets the default keyword 5857 substitution method for this file, but it does not 5858 alter the working copy of the file that you have. If you need to 5859 cope with line endings (that is, you are using 5860 @sc{cvs} on a non-unix system), then you need to 5861 check in a new copy of the file, as shown by the 5862 @code{cvs commit} command above. 5863 On unix, the @code{cvs update -A} command suffices. 5864 @c FIXME: should also describe what the *other users* 5865 @c need to do, if they have checked out copies which 5866 @c have been corrupted by lack of -kb. I think maybe 5867 @c "cvs update -kb" or "cvs 5868 @c update -A" would suffice, although the user who 5869 @c reported this suggested removing the file, manually 5870 @c removing it from CVS/Entries, and then "cvs update" 5871 (Note that you can use @code{cvs log} to determine the default keyword 5872 substitution method for a file and @code{cvs status} to determine 5873 the keyword substitution method for a working copy.) 5874 5875 However, in using @code{cvs admin -k} to change the 5876 keyword expansion, be aware that the keyword expansion 5877 mode is not version controlled. This means that, for 5878 example, that if you have a text file in old releases, 5879 and a binary file with the same name in new releases, 5880 @sc{cvs} provides no way to check out the file in text 5881 or binary mode depending on what version you are 5882 checking out. There is no good workaround for this 5883 problem. 5884 5885 You can also set a default for whether @code{cvs add} 5886 and @code{cvs import} treat a file as binary based on 5887 its name; for example you could say that files who 5888 names end in @samp{.exe} are binary. @xref{Wrappers}. 5889 There is currently no way to have @sc{cvs} detect 5890 whether a file is binary based on its contents. The 5891 main difficulty with designing such a feature is that 5892 it is not clear how to distinguish between binary and 5893 non-binary files, and the rules to apply would vary 5894 considerably with the operating system. 5895 @c For example, it would be good on MS-DOS-family OSes 5896 @c for anything containing ^Z to be binary. Having 5897 @c characters with the 8th bit set imply binary is almost 5898 @c surely a bad idea in the context of ISO-8859-* and 5899 @c other such character sets. On VMS or the Mac, we 5900 @c could use the OS's file typing. This is a 5901 @c commonly-desired feature, and something of this sort 5902 @c may make sense. But there are a lot of pitfalls here. 5903 @c 5904 @c Another, probably better, way to tell is to read the 5905 @c file in text mode, write it to a temp file in text 5906 @c mode, and then do a binary mode compare of the two 5907 @c files. If they differ, it is a binary file. This 5908 @c might have problems on VMS (or some other system 5909 @c with several different text modes), but in general 5910 @c should be relatively portable. The only other 5911 @c downside I can think of is that it would be fairly 5912 @c slow, but that is perhaps a small price to pay for 5913 @c not having your files corrupted. Another issue is 5914 @c what happens if you import a text file with bare 5915 @c linefeeds on Windows. Such files will show up on 5916 @c Windows sometimes (I think some native windows 5917 @c programs even write them, on occasion). Perhaps it 5918 @c is reasonable to treat such files as binary; after 5919 @c all it is something of a presumption to assume that 5920 @c the user would want the linefeeds converted to CRLF. 5921 5922 @c --------------------------------------------------------------------- 5923 @node Multiple developers 5924 @chapter Multiple developers 5925 @cindex Multiple developers 5926 @cindex Team of developers 5927 @cindex File locking 5928 @cindex Locking files 5929 @cindex Working copy 5930 @cindex Reserved checkouts 5931 @cindex Unreserved checkouts 5932 @cindex RCS-style locking 5933 5934 When more than one person works on a software project 5935 things often get complicated. Often, two people try to 5936 edit the same file simultaneously. One solution, known 5937 as @dfn{file locking} or @dfn{reserved checkouts}, is 5938 to allow only one person to edit each file at a time. 5939 This is the only solution with some version control 5940 systems, including @sc{rcs} and @sc{sccs}. Currently 5941 the usual way to get reserved checkouts with @sc{cvs} 5942 is the @code{cvs admin -l} command (@pxref{admin 5943 options}). This is not as nicely integrated into 5944 @sc{cvs} as the watch features, described below, but it 5945 seems that most people with a need for reserved 5946 checkouts find it adequate. 5947 @c Or "find it better than worrying about implementing 5948 @c nicely integrated reserved checkouts" or ...? 5949 5950 As of @sc{cvs} version 1.12.10, another technique for getting most of the 5951 effect of reserved checkouts is to enable advisory locks. To enable advisory 5952 locks, have all developers put "edit -c", "commit -c" in their 5953 .cvsrc file, and turn on watches in the repository. This 5954 prevents them from doing a @code{cvs edit} if anyone is 5955 already editting the file. It also may 5956 be possible to use plain watches together with suitable 5957 procedures (not enforced by software), to avoid having 5958 two people edit at the same time. 5959 5960 @c Our unreserved checkout model might not 5961 @c be quite the same as others. For example, I 5962 @c think that some systems will tend to create a branch 5963 @c in the case where CVS prints "up-to-date check failed". 5964 @c It isn't clear to me whether we should try to 5965 @c explore these subtleties; it could easily just 5966 @c confuse people. 5967 The default model with @sc{cvs} is known as 5968 @dfn{unreserved checkouts}. In this model, developers 5969 can edit their own @dfn{working copy} of a file 5970 simultaneously. The first person that commits his 5971 changes has no automatic way of knowing that another 5972 has started to edit it. Others will get an error 5973 message when they try to commit the file. They must 5974 then use @sc{cvs} commands to bring their working copy 5975 up to date with the repository revision. This process 5976 is almost automatic. 5977 5978 @c FIXME? should probably use the word "watch" here, to 5979 @c tie this into the text below and above. 5980 @sc{cvs} also supports mechanisms which facilitate 5981 various kinds of communication, without actually 5982 enforcing rules like reserved checkouts do. 5983 5984 The rest of this chapter describes how these various 5985 models work, and some of the issues involved in 5986 choosing between them. 5987 5988 @ignore 5989 Here is a draft reserved checkout design or discussion 5990 of the issues. This seems like as good a place as any 5991 for this. 5992 5993 Might want a cvs lock/cvs unlock--in which the names 5994 differ from edit/unedit because the network must be up 5995 for these to work. unedit gives an error if there is a 5996 reserved checkout in place (so that people don't 5997 accidentally leave locks around); unlock gives an error 5998 if one is not in place (this is more arguable; perhaps 5999 it should act like unedit in that case). 6000 6001 On the other hand, might want it so that emacs, 6002 scripts, etc., can get ready to edit a file without 6003 having to know which model is in use. In that case we 6004 would have a "cvs watch lock" (or .cvsrc?) (that is, 6005 three settings, "on", "off", and "lock"). Having cvs 6006 watch lock set would cause a get to record in the CVS 6007 directory which model is in use, and cause "cvs edit" 6008 to change behaviors. We'd want a way to query which 6009 setting is in effect (this would be handy even if it is 6010 only "on" or "off" as presently). If lock is in 6011 effect, then commit would require a lock before 6012 allowing a checkin; chmod wouldn't suffice (might be 6013 debatable--see chmod comment below, in watches--but it 6014 is the way people expect RCS to work and I can't think 6015 of any significant downside. On the other hand, maybe 6016 it isn't worth bothering, because people who are used 6017 to RCS wouldn't think to use chmod anyway). 6018 6019 Implementation: use file attributes or use RCS 6020 locking. The former avoids more dependence on RCS 6021 behaviors we will need to re-implement as we librarify 6022 RCS, and makes it easier to import/export RCS files (in 6023 that context, want to ignore the locker field). But 6024 note that RCS locks are per-branch, which is the 6025 correct behavior (this is also an issue for the "watch 6026 on" features; they should be per-branch too). 6027 6028 Here are a few more random notes about implementation 6029 details, assuming "cvs watch lock" and 6030 6031 CVS/Watched file? Or try to fit this into CVS/Entries somehow? 6032 Cases: (1) file is checked out (unreserved or with watch on) by old 6033 version of @sc{cvs}, now we do something with new one, (2) file is checked 6034 out by new version, now we do something with old one. 6035 6036 Remote protocol would have a "Watched" analogous to "Mode". Of course 6037 it would apply to all Updated-like requests. How do we keep this 6038 setting up to date? I guess that there wants to be a Watched request, 6039 and the server would send a new one if it isn't up to date? (Ugh--hard 6040 to implement and slows down "cvs -q update"--is there an easier way?) 6041 6042 "cvs edit"--checks CVS/Watched, and if watch lock, then sends 6043 "edit-lock" request. Which comes back with a Checked-in with 6044 appropriate Watched (off, on, lock, locked, or some such?), or error 6045 message if already locked. 6046 6047 "cvs commit"--only will commit if off/on/locked. lock is not OK. 6048 6049 Doc: 6050 note that "cvs edit" must be connected to network if watch lock is in 6051 effect. 6052 6053 Talk about what to do if someone has locked a file and you want to 6054 edit that file. (breaking locks, or lack thereof). 6055 6056 6057 One other idea (which could work along with the 6058 existing "cvs admin -l" reserved checkouts, as well as 6059 the above): 6060 6061 "cvs editors" could show who has the file locked, if 6062 someone does. 6063 6064 @end ignore 6065 6066 @menu 6067 * File status:: A file can be in several states 6068 * Updating a file:: Bringing a file up-to-date 6069 * Conflicts example:: An informative example 6070 * Informing others:: To cooperate you must inform 6071 * Concurrency:: Simultaneous repository access 6072 * Watches:: Mechanisms to track who is editing files 6073 * Choosing a model:: Reserved or unreserved checkouts? 6074 @end menu 6075 6076 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6077 @node File status 6078 @section File status 6079 @cindex File status 6080 @cindex Status of a file 6081 6082 @c Shouldn't this start with an example or something, 6083 @c introducing the unreserved checkout model? Before we 6084 @c dive into listing states? 6085 Based on what operations you have performed on a 6086 checked out file, and what operations others have 6087 performed to that file in the repository, one can 6088 classify a file in a number of states. The states, as 6089 reported by the @code{status} command, are: 6090 6091 @c The order of items is chosen to group logically 6092 @c similar outputs together. 6093 @c People who want alphabetical can use the index... 6094 @table @asis 6095 @cindex Up-to-date 6096 @item Up-to-date 6097 The file is identical with the latest revision in the 6098 repository for the branch in use. 6099 @c FIXME: should we clarify "in use"? The answer is 6100 @c sticky tags, and trying to distinguish branch sticky 6101 @c tags from non-branch sticky tags seems rather awkward 6102 @c here. 6103 @c FIXME: What happens with non-branch sticky tags? Is 6104 @c a stuck file "Up-to-date" or "Needs checkout" or what? 6105 6106 @item Locally Modified 6107 @cindex Locally Modified 6108 You have edited the file, and not yet committed your changes. 6109 6110 @item Locally Added 6111 @cindex Locally Added 6112 You have added the file with @code{add}, and not yet 6113 committed your changes. 6114 @c There are many cases involving the file being 6115 @c added/removed/modified in the working directory, and 6116 @c added/removed/modified in the repository, which we 6117 @c don't try to describe here. I'm not sure that "cvs 6118 @c status" produces a non-confusing output in most of 6119 @c those cases. 6120 6121 @item Locally Removed 6122 @cindex Locally Removed 6123 You have removed the file with @code{remove}, and not yet 6124 committed your changes. 6125 6126 @item Needs Checkout 6127 @cindex Needs Checkout 6128 Someone else has committed a newer revision to the 6129 repository. The name is slightly misleading; you will 6130 ordinarily use @code{update} rather than 6131 @code{checkout} to get that newer revision. 6132 6133 @item Needs Patch 6134 @cindex Needs Patch 6135 @c See also newb-123j0 in sanity.sh (although that case 6136 @c should probably be changed rather than documented). 6137 Like Needs Checkout, but the @sc{cvs} server will send 6138 a patch rather than the entire file. Sending a patch or 6139 sending an entire file accomplishes the same thing. 6140 6141 @item Needs Merge 6142 @cindex Needs Merge 6143 Someone else has committed a newer revision to the repository, and you 6144 have also made modifications to the file. 6145 6146 @item Unresolved Conflict 6147 @cindex Unresolved Conflict 6148 @c FIXCVS - This file status needs to be changed to some more informative 6149 @c text that distinguishes it more clearly from each of the Locally Added, 6150 @c File had conflicts on merge, and Unknown status types, but an exact and 6151 @c succinct wording escapes me at the moment. 6152 A file with the same name as this new file has been added to the repository 6153 from a second workspace. This file will need to be moved out of the way 6154 to allow an @code{update} to complete. 6155 6156 @item File had conflicts on merge 6157 @cindex File had conflicts on merge 6158 @c is it worth saying that this message was "Unresolved 6159 @c Conflict" in CVS 1.9 and earlier? I'm inclined to 6160 @c think that is unnecessarily confusing to new users. 6161 This is like Locally Modified, except that a previous 6162 @code{update} command gave a conflict. If you have not 6163 already done so, you need to 6164 resolve the conflict as described in @ref{Conflicts example}. 6165 6166 @item Unknown 6167 @cindex Unknown 6168 @sc{cvs} doesn't know anything about this file. For 6169 example, you have created a new file and have not run 6170 @code{add}. 6171 @c 6172 @c "Entry Invalid" and "Classify Error" are also in the 6173 @c status.c. The latter definitely indicates a CVS bug 6174 @c (should it be worded more like "internal error" so 6175 @c people submit bug reports if they see it?). The former 6176 @c I'm not as sure; I haven't tracked down whether/when it 6177 @c appears in "cvs status" output. 6178 6179 @end table 6180 6181 To help clarify the file status, @code{status} also 6182 reports the @code{Working revision} which is the 6183 revision that the file in the working directory derives 6184 from, and the @code{Repository revision} which is the 6185 latest revision in the repository for the branch in 6186 use. 6187 The @samp{Commit Identifier} reflects the unique commitid 6188 of the @code{commit}. 6189 @c FIXME: should we clarify "in use"? The answer is 6190 @c sticky tags, and trying to distinguish branch sticky 6191 @c tags from non-branch sticky tags seems rather awkward 6192 @c here. 6193 @c FIXME: What happens with non-branch sticky tags? 6194 @c What is the Repository Revision there? See the 6195 @c comment at vn_rcs in cvs.h, which is kind of 6196 @c confused--we really need to document better what this 6197 @c field contains. 6198 @c Q: Should we document "New file!" and other such 6199 @c outputs or are they self-explanatory? 6200 @c FIXME: what about the date to the right of "Working 6201 @c revision"? It doesn't appear with client/server and 6202 @c seems unnecessary (redundant with "ls -l") so 6203 @c perhaps it should be removed for non-client/server too? 6204 @c FIXME: Need some examples. 6205 @c FIXME: Working revision can also be something like 6206 @c "-1.3" for a locally removed file. Not at all 6207 @c self-explanatory (and it is possible that CVS should 6208 @c be changed rather than documenting this). 6209 6210 @c Would be nice to have an @example showing output 6211 @c from cvs status, with comments showing the xref 6212 @c where each part of the output is described. This 6213 @c might fit in nicely if it is desirable to split this 6214 @c node in two; one to introduce "cvs status" and one 6215 @c to list each of the states. 6216 The options to @code{status} are listed in 6217 @ref{Invoking CVS}. For information on its @code{Sticky tag} 6218 and @code{Sticky date} output, see @ref{Sticky tags}. 6219 For information on its @code{Sticky options} output, 6220 see the @samp{-k} option in @ref{update options}. 6221 6222 You can think of the @code{status} and @code{update} 6223 commands as somewhat complementary. You use 6224 @code{update} to bring your files up to date, and you 6225 can use @code{status} to give you some idea of what an 6226 @code{update} would do (of course, the state of the 6227 repository might change before you actually run 6228 @code{update}). In fact, if you want a command to 6229 display file status in a more brief format than is 6230 displayed by the @code{status} command, you can invoke 6231 6232 @cindex update, to display file status 6233 @example 6234 $ cvs -n -q update 6235 @end example 6236 6237 The @samp{-n} option means to not actually do the 6238 update, but merely to display statuses; the @samp{-q} 6239 option avoids printing the name of each directory. For 6240 more information on the @code{update} command, and 6241 these options, see @ref{Invoking CVS}. 6242 6243 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6244 @node Updating a file 6245 @section Bringing a file up to date 6246 @cindex Bringing a file up to date 6247 @cindex Updating a file 6248 @cindex Merging a file 6249 @cindex Update, introduction 6250 6251 When you want to update or merge a file, use the @code{cvs update -d} 6252 command. For files that are not up to date this is roughly equivalent 6253 to a @code{checkout} command: the newest revision of the file is 6254 extracted from the repository and put in your working directory. The 6255 @code{-d} option, not necessary with @code{checkout}, tells @sc{cvs} 6256 that you wish it to create directories added by other developers. 6257 6258 Your modifications to a file are never lost when you 6259 use @code{update}. If no newer revision exists, 6260 running @code{update} has no effect. If you have 6261 edited the file, and a newer revision is available, 6262 @sc{cvs} will merge all changes into your working copy. 6263 6264 For instance, imagine that you checked out revision 1.4 and started 6265 editing it. In the meantime someone else committed revision 1.5, and 6266 shortly after that revision 1.6. If you run @code{update} on the file 6267 now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 6268 your file. 6269 6270 @cindex Overlap 6271 If any of the changes between 1.4 and 1.6 were made too 6272 close to any of the changes you have made, an 6273 @dfn{overlap} occurs. In such cases a warning is 6274 printed, and the resulting file includes both 6275 versions of the lines that overlap, delimited by 6276 special markers. 6277 @xref{update}, for a complete description of the 6278 @code{update} command. 6279 6280 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6281 @node Conflicts example 6282 @section Conflicts example 6283 @cindex Merge, an example 6284 @cindex Example of merge 6285 @cindex driver.c (merge example) 6286 6287 Suppose revision 1.4 of @file{driver.c} contains this: 6288 6289 @example 6290 #include <stdio.h> 6291 6292 void main() 6293 @{ 6294 parse(); 6295 if (nerr == 0) 6296 gencode(); 6297 else 6298 fprintf(stderr, "No code generated.\n"); 6299 exit(nerr == 0 ? 0 : 1); 6300 @} 6301 @end example 6302 6303 @noindent 6304 Revision 1.6 of @file{driver.c} contains this: 6305 6306 @example 6307 #include <stdio.h> 6308 6309 int main(int argc, 6310 char **argv) 6311 @{ 6312 parse(); 6313 if (argc != 1) 6314 @{ 6315 fprintf(stderr, "tc: No args expected.\n"); 6316 exit(1); 6317 @} 6318 if (nerr == 0) 6319 gencode(); 6320 else 6321 fprintf(stderr, "No code generated.\n"); 6322 exit(!!nerr); 6323 @} 6324 @end example 6325 6326 @noindent 6327 Your working copy of @file{driver.c}, based on revision 6328 1.4, contains this before you run @samp{cvs update}: 6329 @c -- Really include "cvs"? 6330 6331 @example 6332 #include <stdlib.h> 6333 #include <stdio.h> 6334 6335 void main() 6336 @{ 6337 init_scanner(); 6338 parse(); 6339 if (nerr == 0) 6340 gencode(); 6341 else 6342 fprintf(stderr, "No code generated.\n"); 6343 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6344 @} 6345 @end example 6346 6347 @noindent 6348 You run @samp{cvs update}: 6349 @c -- Really include "cvs"? 6350 6351 @example 6352 $ cvs update driver.c 6353 RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 6354 retrieving revision 1.4 6355 retrieving revision 1.6 6356 Merging differences between 1.4 and 1.6 into driver.c 6357 rcsmerge warning: overlaps during merge 6358 cvs update: conflicts found in driver.c 6359 C driver.c 6360 @end example 6361 6362 @noindent 6363 @cindex Conflicts (merge example) 6364 @sc{cvs} tells you that there were some conflicts. 6365 Your original working file is saved unmodified in 6366 @file{.#driver.c.1.4}. The new version of 6367 @file{driver.c} contains this: 6368 6369 @example 6370 #include <stdlib.h> 6371 #include <stdio.h> 6372 6373 int main(int argc, 6374 char **argv) 6375 @{ 6376 init_scanner(); 6377 parse(); 6378 if (argc != 1) 6379 @{ 6380 fprintf(stderr, "tc: No args expected.\n"); 6381 exit(1); 6382 @} 6383 if (nerr == 0) 6384 gencode(); 6385 else 6386 fprintf(stderr, "No code generated.\n"); 6387 @asis{}<<<<<<< driver.c 6388 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6389 @asis{}======= 6390 exit(!!nerr); 6391 @asis{}>>>>>>> 1.6 6392 @} 6393 @end example 6394 6395 @noindent 6396 @cindex Markers, conflict 6397 @cindex Conflict markers 6398 @cindex <<<<<<< 6399 @cindex >>>>>>> 6400 @cindex ======= 6401 6402 Note how all non-overlapping modifications are incorporated in your working 6403 copy, and that the overlapping section is clearly marked with 6404 @samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 6405 6406 @cindex Resolving a conflict 6407 @cindex Conflict resolution 6408 You resolve the conflict by editing the file, removing the markers and 6409 the erroneous line. Suppose you end up with this file: 6410 @c -- Add xref to the pcl-cvs manual when it talks 6411 @c -- about this. 6412 @example 6413 #include <stdlib.h> 6414 #include <stdio.h> 6415 6416 int main(int argc, 6417 char **argv) 6418 @{ 6419 init_scanner(); 6420 parse(); 6421 if (argc != 1) 6422 @{ 6423 fprintf(stderr, "tc: No args expected.\n"); 6424 exit(1); 6425 @} 6426 if (nerr == 0) 6427 gencode(); 6428 else 6429 fprintf(stderr, "No code generated.\n"); 6430 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6431 @} 6432 @end example 6433 6434 @noindent 6435 You can now go ahead and commit this as revision 1.7. 6436 6437 @example 6438 $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 6439 Checking in driver.c; 6440 /usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 6441 new revision: 1.7; previous revision: 1.6 6442 done 6443 @end example 6444 6445 For your protection, @sc{cvs} will refuse to check in a 6446 file if a conflict occurred and you have not resolved 6447 the conflict. Currently to resolve a conflict, you 6448 must change the timestamp on the file. In previous 6449 versions of @sc{cvs}, you also needed to 6450 insure that the file contains no conflict markers. 6451 Because 6452 your file may legitimately contain conflict markers (that 6453 is, occurrences of @samp{>>>>>>> } at the start of a 6454 line that don't mark a conflict), the current 6455 version of @sc{cvs} will print a warning and proceed to 6456 check in the file. 6457 @c The old behavior was really icky; the only way out 6458 @c was to start hacking on 6459 @c the @code{CVS/Entries} file or other such workarounds. 6460 @c 6461 @c If the timestamp thing isn't considered nice enough, 6462 @c maybe there should be a "cvs resolved" command 6463 @c which clears the conflict indication. For a nice user 6464 @c interface, this should be invoked by an interactive 6465 @c merge tool like emerge rather than by the user 6466 @c directly--such a tool can verify that the user has 6467 @c really dealt with each conflict. 6468 6469 @cindex emerge 6470 If you use release 1.04 or later of pcl-cvs (a @sc{gnu} 6471 Emacs front-end for @sc{cvs}) you can use an Emacs 6472 package called emerge to help you resolve conflicts. 6473 See the documentation for pcl-cvs. 6474 6475 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6476 @node Informing others 6477 @section Informing others about commits 6478 @cindex Informing others 6479 @cindex Spreading information 6480 @cindex Mail, automatic mail on commit 6481 6482 It is often useful to inform others when you commit a 6483 new revision of a file. The @samp{-i} option of the 6484 @file{modules} file, or the @file{loginfo} file, can be 6485 used to automate this process. @xref{modules}. 6486 @xref{loginfo}. You can use these features of @sc{cvs} 6487 to, for instance, instruct @sc{cvs} to mail a 6488 message to all developers, or post a message to a local 6489 newsgroup. 6490 @c -- More text would be nice here. 6491 6492 @node Concurrency 6493 @section Several developers simultaneously attempting to run CVS 6494 6495 @cindex Locks, cvs, introduction 6496 @c For a discussion of *why* CVS creates locks, see 6497 @c the comment at the start of src/lock.c 6498 If several developers try to run @sc{cvs} at the same 6499 time, one may get the following message: 6500 6501 @example 6502 [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 6503 @end example 6504 6505 @cindex #cvs.rfl, removing 6506 @cindex #cvs.wfl, removing 6507 @cindex #cvs.lock, removing 6508 @sc{cvs} will try again every 30 seconds, and either 6509 continue with the operation or print the message again, 6510 if it still needs to wait. If a lock seems to stick 6511 around for an undue amount of time, find the person 6512 holding the lock and ask them about the cvs command 6513 they are running. If they aren't running a cvs 6514 command, look in the repository directory mentioned in 6515 the message and remove files which they own whose names 6516 start with @file{#cvs.rfl}, 6517 @file{#cvs.wfl}, or @file{#cvs.lock}. 6518 6519 Note that these locks are to protect @sc{cvs}'s 6520 internal data structures and have no relationship to 6521 the word @dfn{lock} in the sense used by 6522 @sc{rcs}---which refers to reserved checkouts 6523 (@pxref{Multiple developers}). 6524 6525 Any number of people can be reading from a given 6526 repository at a time; only when someone is writing do 6527 the locks prevent other people from reading or writing. 6528 6529 @cindex Atomic transactions, lack of 6530 @cindex Transactions, atomic, lack of 6531 @c the following talks about what one might call commit/update 6532 @c atomicity. 6533 @c Probably also should say something about 6534 @c commit/commit atomicity, that is, "An update will 6535 @c not get partial versions of more than one commit". 6536 @c CVS currently has this property and I guess we can 6537 @c make it a documented feature. 6538 @c For example one person commits 6539 @c a/one.c and b/four.c and another commits a/two.c and 6540 @c b/three.c. Then an update cannot get the new a/one.c 6541 @c and a/two.c and the old b/four.c and b/three.c. 6542 One might hope for the following property: 6543 6544 @quotation 6545 If someone commits some changes in one cvs command, 6546 then an update by someone else will either get all the 6547 changes, or none of them. 6548 @end quotation 6549 6550 @noindent 6551 but @sc{cvs} does @emph{not} have this property. For 6552 example, given the files 6553 6554 @example 6555 a/one.c 6556 a/two.c 6557 b/three.c 6558 b/four.c 6559 @end example 6560 6561 @noindent 6562 if someone runs 6563 6564 @example 6565 cvs ci a/two.c b/three.c 6566 @end example 6567 6568 @noindent 6569 and someone else runs @code{cvs update} at the same 6570 time, the person running @code{update} might get only 6571 the change to @file{b/three.c} and not the change to 6572 @file{a/two.c}. 6573 6574 @node Watches 6575 @section Mechanisms to track who is editing files 6576 @cindex Watches 6577 6578 For many groups, use of @sc{cvs} in its default mode is 6579 perfectly satisfactory. Users may sometimes go to 6580 check in a modification only to find that another 6581 modification has intervened, but they deal with it and 6582 proceed with their check in. Other groups prefer to be 6583 able to know who is editing what files, so that if two 6584 people try to edit the same file they can choose to 6585 talk about who is doing what when rather than be 6586 surprised at check in time. The features in this 6587 section allow such coordination, while retaining the 6588 ability of two developers to edit the same file at the 6589 same time. 6590 6591 @c Some people might ask why CVS does not enforce the 6592 @c rule on chmod, by requiring a cvs edit before a cvs 6593 @c commit. The main reason is that it could always be 6594 @c circumvented--one could edit the file, and 6595 @c then when ready to check it in, do the cvs edit and put 6596 @c in the new contents and do the cvs commit. One 6597 @c implementation note: if we _do_ want to have cvs commit 6598 @c require a cvs edit, we should store the state on 6599 @c whether the cvs edit has occurred in the working 6600 @c directory, rather than having the server try to keep 6601 @c track of what working directories exist. 6602 @c FIXME: should the above discussion be part of the 6603 @c manual proper, somewhere, not just in a comment? 6604 For maximum benefit developers should use @code{cvs 6605 edit} (not @code{chmod}) to make files read-write to 6606 edit them, and @code{cvs release} (not @code{rm}) to 6607 discard a working directory which is no longer in use, 6608 but @sc{cvs} is not able to enforce this behavior. 6609 6610 If a development team wants stronger enforcement of 6611 watches and all team members are using a @sc{cvs} client version 1.12.10 or 6612 greater to access a @sc{cvs} server version 1.12.10 or greater, they can 6613 enable advisory locks. To enable advisory locks, have all developers 6614 put "edit -c" and "commit -c" into all .cvsrc files, 6615 and make files default to read only by turning on watches 6616 or putting "cvs -r" into all .cvsrc files. 6617 This prevents multiple people from editting a file at 6618 the same time (unless explicitly overriden with @samp{-f}). 6619 6620 @c I'm a little dissatisfied with this presentation, 6621 @c because "watch on"/"edit"/"editors" are one set of 6622 @c functionality, and "watch add"/"watchers" is another 6623 @c which is somewhat orthogonal even though they interact in 6624 @c various ways. But I think it might be 6625 @c confusing to describe them separately (e.g. "watch 6626 @c add" with loginfo). I don't know. 6627 6628 @menu 6629 * Setting a watch:: Telling CVS to watch certain files 6630 * Getting Notified:: Telling CVS to notify you 6631 * Editing files:: How to edit a file which is being watched 6632 * Watch information:: Information about who is watching and editing 6633 * Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 6634 @end menu 6635 6636 @node Setting a watch 6637 @subsection Telling CVS to watch certain files 6638 6639 To enable the watch features, you first specify that 6640 certain files are to be watched. 6641 6642 @cindex watch on (subcommand) 6643 @deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 6644 6645 @cindex Read-only files, and watches 6646 Specify that developers should run @code{cvs edit} 6647 before editing @var{files}. @sc{cvs} will create working 6648 copies of @var{files} read-only, to remind developers 6649 to run the @code{cvs edit} command before working on 6650 them. 6651 6652 If @var{files} includes the name of a directory, @sc{cvs} 6653 arranges to watch all files added to the corresponding 6654 repository directory, and sets a default for files 6655 added in the future; this allows the user to set 6656 notification policies on a per-directory basis. The 6657 contents of the directory are processed recursively, 6658 unless the @code{-l} option is given. 6659 The @code{-R} option can be used to force recursion if the @code{-l} 6660 option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 6661 6662 If @var{files} is omitted, it defaults to the current directory. 6663 6664 @cindex watch off (subcommand) 6665 @end deffn 6666 6667 @deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 6668 6669 Do not create @var{files} read-only on checkout; thus, 6670 developers will not be reminded to use @code{cvs edit} 6671 and @code{cvs unedit}. 6672 @ignore 6673 @sc{cvs} will check out @var{files} 6674 read-write as usual, unless other permissions override 6675 due to the @code{PreservePermissions} option being 6676 enabled in the @file{config} administrative file 6677 (@pxref{Special Files}, @pxref{config}) 6678 @end ignore 6679 6680 The @var{files} and options are processed as for @code{cvs 6681 watch on}. 6682 6683 @end deffn 6684 6685 @node Getting Notified 6686 @subsection Telling CVS to notify you 6687 6688 You can tell @sc{cvs} that you want to receive 6689 notifications about various actions taken on a file. 6690 You can do this without using @code{cvs watch on} for 6691 the file, but generally you will want to use @code{cvs 6692 watch on}, to remind developers to use the @code{cvs edit} 6693 command. 6694 6695 @cindex watch add (subcommand) 6696 @deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6697 6698 Add the current user to the list of people to receive notification of 6699 work done on @var{files}. 6700 6701 The @code{-a} option specifies what kinds of events @sc{cvs} should notify 6702 the user about. @var{action} is one of the following: 6703 6704 @table @code 6705 6706 @item edit 6707 Another user has applied the @code{cvs edit} command (described 6708 below) to a watched file. 6709 6710 @item commit 6711 Another user has committed changes to one of the named @var{files}. 6712 6713 @item unedit 6714 Another user has abandoned editing a file (other than by committing changes). 6715 They can do this in several ways, by: 6716 6717 @itemize @bullet 6718 6719 @item 6720 applying the @code{cvs unedit} command (described below) to the file 6721 6722 @item 6723 applying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6724 (or recursively to a directory more than one level up) 6725 6726 @item 6727 deleting the file and allowing @code{cvs update} to recreate it 6728 6729 @end itemize 6730 6731 @item all 6732 All of the above. 6733 6734 @item none 6735 None of the above. (This is useful with @code{cvs edit}, 6736 described below.) 6737 6738 @end table 6739 6740 The @code{-a} option may appear more than once, or not at all. If 6741 omitted, the action defaults to @code{all}. 6742 6743 The @var{files} and options are processed as for 6744 @code{cvs watch on}. 6745 6746 @end deffn 6747 6748 6749 @cindex watch remove (subcommand) 6750 @deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6751 6752 Remove a notification request established using @code{cvs watch add}; 6753 the arguments are the same. If the @code{-a} option is present, only 6754 watches for the specified actions are removed. 6755 6756 @end deffn 6757 6758 @cindex notify (admin file) 6759 When the conditions exist for notification, @sc{cvs} 6760 calls the @file{notify} administrative file. Edit 6761 @file{notify} as one edits the other administrative 6762 files (@pxref{Intro administrative files}). This 6763 file follows the usual conventions for administrative 6764 files (@pxref{syntax}), where each line is a regular 6765 expression followed by a command to execute. The 6766 command should contain a single occurrence of @samp{%s} 6767 which will be replaced by the user to notify; the rest 6768 of the information regarding the notification will be 6769 supplied to the command on standard input. The 6770 standard thing to put in the @code{notify} file is the 6771 single line: 6772 6773 @example 6774 ALL mail %s -s "CVS notification" 6775 @end example 6776 6777 @noindent 6778 This causes users to be notified by electronic mail. 6779 @c FIXME: should it be this hard to set up this 6780 @c behavior (and the result when one fails to do so, 6781 @c silent failure to notify, so non-obvious)? Should 6782 @c CVS give a warning if no line in notify matches (and 6783 @c document the use of "DEFAULT :" for the case where 6784 @c skipping the notification is indeed desired)? 6785 6786 @cindex users (admin file) 6787 Note that if you set this up in the straightforward 6788 way, users receive notifications on the server machine. 6789 One could of course write a @file{notify} script which 6790 directed notifications elsewhere, but to make this 6791 easy, @sc{cvs} allows you to associate a notification 6792 address for each user. To do so create a file 6793 @file{users} in @file{CVSROOT} with a line for each 6794 user in the format @var{user}:@var{value}. Then 6795 instead of passing the name of the user to be notified 6796 to @file{notify}, @sc{cvs} will pass the @var{value} 6797 (normally an email address on some other machine). 6798 6799 @sc{cvs} does not notify you for your own changes. 6800 Currently this check is done based on whether the user 6801 name of the person taking the action which triggers 6802 notification matches the user name of the person 6803 getting notification. In fact, in general, the watches 6804 features only track one edit by each user. It probably 6805 would be more useful if watches tracked each working 6806 directory separately, so this behavior might be worth 6807 changing. 6808 @c "behavior might be worth changing" is an effort to 6809 @c point to future directions while also not promising 6810 @c that "they" (as in "why don't they fix CVS to....") 6811 @c will do this. 6812 @c one implementation issue is identifying whether a 6813 @c working directory is same or different. Comparing 6814 @c pathnames/hostnames is hopeless, but having the server 6815 @c supply a serial number which the client stores in the 6816 @c CVS directory as a magic cookie should work. 6817 6818 @node Editing files 6819 @subsection How to edit a file which is being watched 6820 6821 @cindex Checkout, as term for getting ready to edit 6822 Since a file which is being watched is checked out 6823 read-only, you cannot simply edit it. To make it 6824 read-write, and inform others that you are planning to 6825 edit it, use the @code{cvs edit} command. Some systems 6826 call this a @dfn{checkout}, but @sc{cvs} uses that term 6827 for obtaining a copy of the sources (@pxref{Getting the 6828 source}), an operation which those systems call a 6829 @dfn{get} or a @dfn{fetch}. 6830 @c Issue to think about: should we transition CVS 6831 @c towards the "get" terminology? "cvs get" is already a 6832 @c synonym for "cvs checkout" and that section of the 6833 @c manual refers to "Getting the source". If this is 6834 @c done, needs to be done gingerly (for example, we should 6835 @c still accept "checkout" in .cvsrc files indefinitely 6836 @c even if the CVS's messages are changed from "cvs checkout: " 6837 @c to "cvs get: "). 6838 @c There is a concern about whether "get" is not as 6839 @c good for novices because it is a more general term 6840 @c than "checkout" (and thus arguably harder to assign 6841 @c a technical meaning for). 6842 6843 @cindex edit (subcommand) 6844 @deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6845 6846 Prepare to edit the working files @var{files}. @sc{cvs} makes the 6847 @var{files} read-write, and notifies users who have requested 6848 @code{edit} notification for any of @var{files}. 6849 6850 The @code{cvs edit} command accepts the same options as the 6851 @code{cvs watch add} command, and establishes a temporary watch for the 6852 user on @var{files}; @sc{cvs} will remove the watch when @var{files} are 6853 @code{unedit}ed or @code{commit}ted. If the user does not wish to 6854 receive notifications, she should specify @code{-a none}. 6855 6856 The @var{files} and the options are processed as for the @code{cvs 6857 watch} commands. 6858 6859 There are two additional options that @code{cvs edit} understands as of 6860 @sc{cvs} client and server versions 1.12.10 but @code{cvs watch} does not. 6861 The first is @code{-c}, which causes @code{cvs edit} to fail if anyone else 6862 is editting the file. This is probably only useful when @samp{edit -c} and 6863 @samp{commit -c} are specified in all developers' @file{.cvsrc} files. This 6864 behavior may be overriden this via the @code{-f} option, which overrides 6865 @code{-c} and allows multiple edits to succeed. 6866 6867 @ignore 6868 @strong{Caution: If the @code{PreservePermissions} 6869 option is enabled in the repository (@pxref{config}), 6870 @sc{cvs} will not change the permissions on any of the 6871 @var{files}. The reason for this change is to ensure 6872 that using @samp{cvs edit} does not interfere with the 6873 ability to store file permissions in the @sc{cvs} 6874 repository.} 6875 @end ignore 6876 6877 @end deffn 6878 6879 Normally when you are done with a set of changes, you 6880 use the @code{cvs commit} command, which checks in your 6881 changes and returns the watched files to their usual 6882 read-only state. But if you instead decide to abandon 6883 your changes, or not to make any changes, you can use 6884 the @code{cvs unedit} command. 6885 6886 @cindex unedit (subcommand) 6887 @cindex Abandoning work 6888 @cindex Reverting to repository version 6889 @deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 6890 6891 Abandon work on the working files @var{files}, and revert them to the 6892 repository versions on which they are based. @sc{cvs} makes those 6893 @var{files} read-only for which users have requested notification using 6894 @code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 6895 notification for any of @var{files}. 6896 6897 The @var{files} and options are processed as for the 6898 @code{cvs watch} commands. 6899 6900 If watches are not in use, the @code{unedit} command 6901 probably does not work, and the way to revert to the 6902 repository version is with the command @code{cvs update -C file} 6903 (@pxref{update}). 6904 The meaning is 6905 not precisely the same; the latter may also 6906 bring in some changes which have been made in the 6907 repository since the last time you updated. 6908 @c It would be a useful enhancement to CVS to make 6909 @c unedit work in the non-watch case as well. 6910 @end deffn 6911 6912 When using client/server @sc{cvs}, you can use the 6913 @code{cvs edit} and @code{cvs unedit} commands even if 6914 @sc{cvs} is unable to successfully communicate with the 6915 server; the notifications will be sent upon the next 6916 successful @sc{cvs} command. 6917 6918 @node Watch information 6919 @subsection Information about who is watching and editing 6920 6921 @cindex watchers (subcommand) 6922 @deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 6923 6924 List the users currently watching changes to @var{files}. The report 6925 includes the files being watched, and the mail address of each watcher. 6926 6927 The @var{files} and options are processed as for the 6928 @code{cvs watch} commands. 6929 6930 @end deffn 6931 6932 6933 @cindex editors (subcommand) 6934 @deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 6935 6936 List the users currently working on @var{files}. The report 6937 includes the mail address of each user, the time when the user began 6938 working with the file, and the host and path of the working directory 6939 containing the file. 6940 6941 The @var{files} and options are processed as for the 6942 @code{cvs watch} commands. 6943 6944 @end deffn 6945 6946 @node Watches Compatibility 6947 @subsection Using watches with old versions of CVS 6948 6949 @cindex CVS 1.6, and watches 6950 If you use the watch features on a repository, it 6951 creates @file{CVS} directories in the repository and 6952 stores the information about watches in that directory. 6953 If you attempt to use @sc{cvs} 1.6 or earlier with the 6954 repository, you get an error message such as the 6955 following (all on one line): 6956 6957 @example 6958 cvs update: cannot open CVS/Entries for reading: 6959 No such file or directory 6960 @end example 6961 6962 @noindent 6963 and your operation will likely be aborted. To use the 6964 watch features, you must upgrade all copies of @sc{cvs} 6965 which use that repository in local or server mode. If 6966 you cannot upgrade, use the @code{watch off} and 6967 @code{watch remove} commands to remove all watches, and 6968 that will restore the repository to a state which 6969 @sc{cvs} 1.6 can cope with. 6970 6971 @node Choosing a model 6972 @section Choosing between reserved or unreserved checkouts 6973 @cindex Choosing, reserved or unreserved checkouts 6974 6975 Reserved and unreserved checkouts each have pros and 6976 cons. Let it be said that a lot of this is a matter of 6977 opinion or what works given different groups' working 6978 styles, but here is a brief description of some of the 6979 issues. There are many ways to organize a team of 6980 developers. @sc{cvs} does not try to enforce a certain 6981 organization. It is a tool that can be used in several 6982 ways. 6983 6984 Reserved checkouts can be very counter-productive. If 6985 two persons want to edit different parts of a file, 6986 there may be no reason to prevent either of them from 6987 doing so. Also, it is common for someone to take out a 6988 lock on a file, because they are planning to edit it, 6989 but then forget to release the lock. 6990 6991 @c "many groups"? specifics? cites to papers on this? 6992 @c some way to weasel-word it a bit more so we don't 6993 @c need facts :-)? 6994 People, especially people who are familiar with 6995 reserved checkouts, often wonder how often conflicts 6996 occur if unreserved checkouts are used, and how 6997 difficult they are to resolve. The experience with 6998 many groups is that they occur rarely and usually are 6999 relatively straightforward to resolve. 7000 7001 The rarity of serious conflicts may be surprising, until one realizes 7002 that they occur only when two developers disagree on the proper design 7003 for a given section of code; such a disagreement suggests that the 7004 team has not been communicating properly in the first place. In order 7005 to collaborate under @emph{any} source management regimen, developers 7006 must agree on the general design of the system; given this agreement, 7007 overlapping changes are usually straightforward to merge. 7008 7009 In some cases unreserved checkouts are clearly 7010 inappropriate. If no merge tool exists for the kind of 7011 file you are managing (for example word processor files 7012 or files edited by Computer Aided Design programs), and 7013 it is not desirable to change to a program which uses a 7014 mergeable data format, then resolving conflicts is 7015 going to be unpleasant enough that you generally will 7016 be better off to simply avoid the conflicts instead, by 7017 using reserved checkouts. 7018 7019 The watches features described above in @ref{Watches} 7020 can be considered to be an intermediate model between 7021 reserved checkouts and unreserved checkouts. When you 7022 go to edit a file, it is possible to find out who else 7023 is editing it. And rather than having the system 7024 simply forbid both people editing the file, it can tell 7025 you what the situation is and let you figure out 7026 whether it is a problem in that particular case or not. 7027 Therefore, for some groups watches can be 7028 considered the best of both the reserved checkout and unreserved 7029 checkout worlds. 7030 7031 As of @sc{cvs} client and server versions 1.12.10, you may also enable 7032 advisory locks by putting @samp{edit -c} and @samp{commit -c} in all 7033 developers' @file{.cvsrc} files. After this is done, @code{cvs edit} 7034 will fail if there are any other editors, and @code{cvs commit} will 7035 fail if the committer has not registered to edit the file via @code{cvs edit}. 7036 This is most effective in conjunction with files checked out read-only by 7037 default, which may be enabled by turning on watches in the repository or by 7038 putting @samp{cvs -r} in all @file{.cvsrc} files. 7039 7040 7041 @c --------------------------------------------------------------------- 7042 @node Revision management 7043 @chapter Revision management 7044 @cindex Revision management 7045 7046 @c -- This chapter could be expanded a lot. 7047 @c -- Experiences are very welcome! 7048 7049 If you have read this far, you probably have a pretty 7050 good grasp on what @sc{cvs} can do for you. This 7051 chapter talks a little about things that you still have 7052 to decide. 7053 7054 If you are doing development on your own using @sc{cvs} 7055 you could probably skip this chapter. The questions 7056 this chapter takes up become more important when more 7057 than one person is working in a repository. 7058 7059 @menu 7060 * When to commit:: Some discussion on the subject 7061 @end menu 7062 7063 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7064 @node When to commit 7065 @section When to commit? 7066 @cindex When to commit 7067 @cindex Committing, when to 7068 @cindex Policy 7069 7070 Your group should decide which policy to use regarding 7071 commits. Several policies are possible, and as your 7072 experience with @sc{cvs} grows you will probably find 7073 out what works for you. 7074 7075 If you commit files too quickly you might commit files 7076 that do not even compile. If your partner updates his 7077 working sources to include your buggy file, he will be 7078 unable to compile the code. On the other hand, other 7079 persons will not be able to benefit from the 7080 improvements you make to the code if you commit very 7081 seldom, and conflicts will probably be more common. 7082 7083 It is common to only commit files after making sure 7084 that they can be compiled. Some sites require that the 7085 files pass a test suite. Policies like this can be 7086 enforced using the commitinfo file 7087 (@pxref{commitinfo}), but you should think twice before 7088 you enforce such a convention. By making the 7089 development environment too controlled it might become 7090 too regimented and thus counter-productive to the real 7091 goal, which is to get software written. 7092 7093 @c --------------------------------------------------------------------- 7094 @node Keyword substitution 7095 @chapter Keyword substitution 7096 @cindex Keyword substitution 7097 @cindex Keyword expansion 7098 @cindex Identifying files 7099 7100 @comment Be careful when editing this chapter. 7101 @comment Remember that this file is kept under 7102 @comment version control, so we must not accidentally 7103 @comment include a valid keyword in the running text. 7104 7105 As long as you edit source files inside a working 7106 directory you can always find out the state of 7107 your files via @samp{cvs status} and @samp{cvs log}. 7108 But as soon as you export the files from your 7109 development environment it becomes harder to identify 7110 which revisions they are. 7111 7112 @sc{cvs} can use a mechanism known as @dfn{keyword 7113 substitution} (or @dfn{keyword expansion}) to help 7114 identifying the files. Embedded strings of the form 7115 @code{$@var{keyword}$} and 7116 @code{$@var{keyword}:@dots{}$} in a file are replaced 7117 with strings of the form 7118 @code{$@var{keyword}:@var{value}$} whenever you obtain 7119 a new revision of the file. 7120 7121 @menu 7122 * Keyword list:: Keywords 7123 * Using keywords:: Using keywords 7124 * Avoiding substitution:: Avoiding substitution 7125 * Substitution modes:: Substitution modes 7126 * Configuring keyword expansion:: Configuring keyword expansion 7127 * Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword. 7128 @end menu 7129 7130 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7131 @node Keyword list 7132 @section Keyword List 7133 @cindex Keyword List 7134 7135 @c FIXME: need some kind of example here I think, 7136 @c perhaps in a 7137 @c "Keyword intro" node. The intro in the "Keyword 7138 @c substitution" node itself seems OK, but to launch 7139 @c into a list of the keywords somehow seems too abrupt. 7140 7141 This is a list of the keywords: 7142 7143 @table @code 7144 @cindex Author keyword 7145 @item $@splitrcskeyword{Author}$ 7146 The login name of the user who checked in the revision. 7147 7148 @cindex CVSHeader keyword 7149 @item $@splitrcskeyword{CVSHeader}$ 7150 A standard header (similar to $@splitrcskeyword{Header}$, but with 7151 the CVS root stripped off). It contains the relative 7152 pathname of the @sc{rcs} file to the CVS root, the 7153 revision number, the date (UTC), the author, the state, 7154 and the locker (if locked). Files will normally never 7155 be locked when you use @sc{cvs}. 7156 7157 Note that this keyword has only been recently 7158 introduced to @sc{cvs} and may cause problems with 7159 existing installations if $@splitrcskeyword{CVSHeader}$ is already 7160 in the files for a different purpose. This keyword may 7161 be excluded using the @code{KeywordExpand=eCVSHeader} 7162 in the @file{CVSROOT/config} file. 7163 See @ref{Configuring keyword expansion} for more details. 7164 7165 @cindex Date keyword 7166 @item $@splitrcskeyword{Date}$ 7167 The date and time (UTC) the revision was checked in. 7168 7169 @cindex Header keyword 7170 @item $@splitrcskeyword{Header}$ 7171 A standard header containing the full pathname of the 7172 @sc{rcs} file, the revision number, the date (UTC), the 7173 author, the state, and the locker (if locked). Files 7174 will normally never be locked when you use @sc{cvs}. 7175 7176 @cindex Id keyword 7177 @item $@splitrcskeyword{Id}$ 7178 Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs} 7179 filename is without a path. 7180 7181 @cindex Name keyword 7182 @item $@splitrcskeyword{Name}$ 7183 Tag name used to check out this file. The keyword is 7184 expanded only if one checks out with an explicit tag 7185 name. For example, when running the command @code{cvs 7186 co -r first}, the keyword expands to @samp{Name: first}. 7187 7188 @cindex Locker keyword 7189 @item $@splitrcskeyword{Locker}$ 7190 The login name of the user who locked the revision 7191 (empty if not locked, which is the normal case unless 7192 @code{cvs admin -l} is in use). 7193 7194 @cindex Log keyword 7195 @cindex MaxCommentLeaderLength 7196 @cindex UseArchiveCommentLeader 7197 @cindex Log keyword, configuring substitution behavior 7198 @item $@splitrcskeyword{Log}$ 7199 The log message supplied during commit, preceded by a 7200 header containing the @sc{rcs} filename, the revision 7201 number, the author, and the date (UTC). Existing log 7202 messages are @emph{not} replaced. Instead, the new log 7203 message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}. 7204 By default, each new line is prefixed with the same string which 7205 precedes the @code{$@splitrcskeyword{Log}$} keyword, unless it exceeds the 7206 @code{MaxCommentLeaderLength} set in @file{CVSROOT/config}. 7207 7208 For example, if the file contains: 7209 7210 @example 7211 /* Here is what people have been up to: 7212 * 7213 * $@splitrcskeyword{Log}: frob.c,v $ 7214 * Revision 1.1 1997/01/03 14:23:51 joe 7215 * Add the superfrobnicate option 7216 * 7217 */ 7218 @end example 7219 7220 @noindent 7221 then additional lines which are added when expanding 7222 the @code{$@splitrcskeyword{Log}$} keyword will be preceded by @samp{ * }. 7223 Unlike previous versions of @sc{cvs} and @sc{rcs}, the 7224 @dfn{comment leader} from the @sc{rcs} file is not used. 7225 The @code{$@splitrcskeyword{Log}$} keyword is useful for 7226 accumulating a complete change log in a source file, 7227 but for several reasons it can be problematic. 7228 7229 If the prefix of the @code{$@splitrcskeyword{Log}$} keyword turns out to be 7230 longer than @code{MaxCommentLeaderLength}, CVS will skip expansion of this 7231 keyword unless @code{UseArchiveCommentLeader} is also set in 7232 @file{CVSROOT/config} and a @samp{comment leader} is set in the RCS archive 7233 file, in which case the comment leader will be used instead. For more on 7234 setting the comment leader in the RCS archive file, @xref{admin}. For more 7235 on configuring the default @code{$@splitrcskeyword{Log}$} substitution 7236 behavior, @xref{config}. 7237 7238 @xref{Log keyword}. 7239 7240 @cindex RCSfile keyword 7241 @item $@splitrcskeyword{RCSfile}$ 7242 The name of the RCS file without a path. 7243 7244 @cindex Revision keyword 7245 @item $@splitrcskeyword{Revision}$ 7246 The revision number assigned to the revision. 7247 7248 @cindex Source keyword 7249 @item $@splitrcskeyword{Source}$ 7250 The full pathname of the RCS file. 7251 7252 @cindex State keyword 7253 @item $@splitrcskeyword{State}$ 7254 The state assigned to the revision. States can be 7255 assigned with @code{cvs admin -s}---see @ref{admin options}. 7256 7257 @cindex Local keyword 7258 @item Local keyword 7259 The @code{LocalKeyword} option in the @file{CVSROOT/config} file 7260 may be used to specify a local keyword which is to be 7261 used as an alias for one of the keywords: $@splitrcskeyword{Id}$, 7262 $@splitrcskeyword{Header}$, or $@splitrcskeyword{CVSHeader}$. For 7263 example, if the @file{CVSROOT/config} file contains 7264 a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a 7265 file with the local keyword $@splitrcskeyword{MYBSD}$ will be 7266 expanded as if it were a $@splitrcskeyword{CVSHeader}$ keyword. If 7267 the src/frob.c file contained this keyword, it might 7268 look something like this: 7269 7270 @example 7271 /* 7272 * $@splitrcskeyword{MYBSD}: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 7273 */ 7274 @end example 7275 7276 Many repositories make use of a such a ``local 7277 keyword'' feature. An old patch to @sc{cvs} provided 7278 the @code{LocalKeyword} feature using a @code{tag=} 7279 option and called this the ``custom tag'' or ``local 7280 tag'' feature. It was used in conjunction with the 7281 what they called the @code{tagexpand=} option. In 7282 @sc{cvs} this other option is known as the 7283 @code{KeywordExpand} option. 7284 See @ref{Configuring keyword expansion} for more 7285 details. 7286 7287 Examples from popular projects include: 7288 $@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7289 $@splitrcskeyword{OpenBSD}$, $@splitrcskeyword{XFree86}$, 7290 $@splitrcskeyword{Xorg}$. 7291 7292 The advantage of this is that you can include your 7293 local version information in a file using this local 7294 keyword without disrupting the upstream version 7295 information (which may be a different local keyword or 7296 a standard keyword). Allowing bug reports and the like 7297 to more properly identify the source of the original 7298 bug to the third-party and reducing the number of 7299 conflicts that arise during an import of a new version. 7300 7301 All keyword expansion except the local keyword may be 7302 disabled using the @code{KeywordExpand} option in 7303 the @file{CVSROOT/config} file---see 7304 @ref{Configuring keyword expansion} for more details. 7305 7306 @end table 7307 7308 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7309 @node Using keywords 7310 @section Using keywords 7311 7312 To include a keyword string you simply include the 7313 relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the 7314 file, and commit the file. @sc{cvs} will automatically (Or, 7315 more accurately, as part of the update run that 7316 automatically happens after a commit.) 7317 expand the string as part of the commit operation. 7318 7319 It is common to embed the @code{$@splitrcskeyword{Id}$} string in 7320 the source files so that it gets passed through to 7321 generated files. For example, if you are managing 7322 computer program source code, you might include a 7323 variable which is initialized to contain that string. 7324 Or some C compilers may provide a @code{#pragma ident} 7325 directive. Or a document management system might 7326 provide a way to pass a string through to generated 7327 files. 7328 7329 @c Would be nice to give an example, but doing this in 7330 @c portable C is not possible and the problem with 7331 @c picking any one language (VMS HELP files, Ada, 7332 @c troff, whatever) is that people use CVS for all 7333 @c kinds of files. 7334 7335 @cindex Ident (shell command) 7336 The @code{ident} command (which is part of the @sc{rcs} 7337 package) can be used to extract keywords and their 7338 values from a file. This can be handy for text files, 7339 but it is even more useful for extracting keywords from 7340 binary files. 7341 7342 @example 7343 $ ident samp.c 7344 samp.c: 7345 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7346 $ gcc samp.c 7347 $ ident a.out 7348 a.out: 7349 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 7350 @end example 7351 7352 @cindex What (shell command) 7353 S@sc{ccs} is another popular revision control system. 7354 It has a command, @code{what}, which is very similar to 7355 @code{ident} and used for the same purpose. Many sites 7356 without @sc{rcs} have @sc{sccs}. Since @code{what} 7357 looks for the character sequence @code{@@(#)} it is 7358 easy to include keywords that are detected by either 7359 command. Simply prefix the keyword with the 7360 magic @sc{sccs} phrase, like this: 7361 7362 @example 7363 static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 7364 @end example 7365 7366 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7367 @node Avoiding substitution 7368 @section Avoiding substitution 7369 7370 Keyword substitution has its disadvantages. Sometimes 7371 you might want the literal text string 7372 @samp{$@splitrcskeyword{Author}$} to appear inside a file without 7373 @sc{cvs} interpreting it as a keyword and expanding it 7374 into something like @samp{$@splitrcskeyword{Author}: ceder $}. 7375 7376 There is unfortunately no way to selectively turn off 7377 keyword substitution. You can use @samp{-ko} 7378 (@pxref{Substitution modes}) to turn off keyword 7379 substitution entirely. 7380 7381 In many cases you can avoid using keywords in 7382 the source, even though they appear in the final 7383 product. For example, the source for this manual 7384 contains @samp{$@@asis@{@}Author$} whenever the text 7385 @samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff} 7386 and @code{troff} you can embed the null-character 7387 @code{\&} inside the keyword for a similar effect. 7388 7389 It is also possible to specify an explicit list of 7390 keywords to include or exclude using the 7391 @code{KeywordExpand} option in the 7392 @file{CVSROOT/config} file--see @ref{Configuring keyword expansion} 7393 for more details. This feature is intended primarily 7394 for use with the @code{LocalKeyword} option--see 7395 @ref{Keyword list}. 7396 7397 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7398 @node Substitution modes 7399 @section Substitution modes 7400 @cindex Keyword substitution, changing modes 7401 @cindex -k (keyword substitution) 7402 @cindex Kflag 7403 7404 @c FIXME: This could be made more coherent, by expanding it 7405 @c with more examples or something. 7406 Each file has a stored default substitution mode, and 7407 each working directory copy of a file also has a 7408 substitution mode. The former is set by the @samp{-k} 7409 option to @code{cvs add} and @code{cvs admin}; the 7410 latter is set by the @samp{-k} or @samp{-A} options to @code{cvs 7411 checkout} or @code{cvs update}. 7412 @code{cvs diff} and @code{cvs rdiff} also 7413 have @samp{-k} options. 7414 For some examples, 7415 see @ref{Binary files}, and @ref{Merging and keywords}. 7416 @c The fact that -A is overloaded to mean both reset 7417 @c sticky options and reset sticky tags/dates is 7418 @c somewhat questionable. Perhaps there should be 7419 @c separate options to reset sticky options (e.g. -k 7420 @c A") and tags/dates (someone suggested -r HEAD could 7421 @c do this instead of setting a sticky tag of "HEAD" 7422 @c as in the status quo but I haven't thought much 7423 @c about that idea. Of course -r .reset or something 7424 @c could be coined if this needs to be a new option). 7425 @c On the other hand, having -A mean "get things back 7426 @c into the state after a fresh checkout" has a certain 7427 @c appeal, and maybe there is no sufficient reason for 7428 @c creeping featurism in this area. 7429 7430 The modes available are: 7431 7432 @table @samp 7433 @item -kkv 7434 Generate keyword strings using the default form, e.g. 7435 @code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision} 7436 keyword. 7437 7438 @item -kkvl 7439 Like @samp{-kkv}, except that a locker's name is always 7440 inserted if the given revision is currently locked. 7441 The locker's name is only relevant if @code{cvs admin 7442 -l} is in use. 7443 7444 @item -kk 7445 Generate only keyword names in keyword strings; omit 7446 their values. For example, for the @code{Revision} 7447 keyword, generate the string @code{$@splitrcskeyword{Revision}$} 7448 instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option 7449 is useful to ignore differences due to keyword 7450 substitution when comparing different revisions of a 7451 file (@pxref{Merging and keywords}). 7452 7453 @item -ko 7454 Generate the old keyword string, present in the working 7455 file just before it was checked in. For example, for 7456 the @code{Revision} keyword, generate the string 7457 @code{$@splitrcskeyword{Revision}: 1.1 $} instead of 7458 @code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the 7459 string appeared when the file was checked in. 7460 7461 @item -kb 7462 Like @samp{-ko}, but also inhibit conversion of line 7463 endings between the canonical form in which they are 7464 stored in the repository (linefeed only), and the form 7465 appropriate to the operating system in use on the 7466 client. For systems, like unix, which use linefeed 7467 only to terminate lines, this is very similar to 7468 @samp{-ko}. For more information on binary files, see 7469 @ref{Binary files}. In @sc{cvs} version 1.12.2 and later 7470 @samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or 7471 @code{cvs import} may not be overridden by a @samp{-k} option 7472 specified on the command line. 7473 7474 @item -kv 7475 Generate only keyword values for keyword strings. For 7476 example, for the @code{Revision} keyword, generate the string 7477 @code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. 7478 This can help generate files in programming languages 7479 where it is hard to strip keyword delimiters like 7480 @code{$@splitrcskeyword{Revision}: $} from a string. However, 7481 further keyword substitution cannot be performed once 7482 the keyword names are removed, so this option should be 7483 used with care. 7484 7485 One often would like to use @samp{-kv} with @code{cvs 7486 export}---@pxref{export}. But be aware that doesn't 7487 handle an export containing binary files correctly. 7488 7489 @end table 7490 7491 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7492 @node Configuring keyword expansion 7493 @section Configuring Keyword Expansion 7494 @cindex Configuring keyword expansion 7495 7496 In a repository that includes third-party software on 7497 vendor branches, it is sometimes helpful to configure 7498 CVS to use a local keyword instead of the standard 7499 $@splitrcskeyword{Id}$ or $@splitrcskeyword{Header}$ keywords. Examples from 7500 real projects include $@splitrcskeyword{Xorg}$, $@splitrcskeyword{XFree86}$, 7501 $@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$, 7502 $@splitrcskeyword{OpenBSD}$, and even $@splitrcskeyword{dotat}$. 7503 The advantage of this is that 7504 you can include your local version information in a 7505 file using this local keyword (sometimes called a 7506 ``custom tag'' or a ``local tag'') without disrupting 7507 the upstream version information (which may be a 7508 different local keyword or a standard keyword). In 7509 these cases, it is typically desirable to disable the 7510 expansion of all keywords except the configured local 7511 keyword. 7512 7513 The @code{KeywordExpand} option in the 7514 @file{CVSROOT/config} file is intended to allow for the 7515 either the explicit exclusion of a keyword or list of 7516 keywords, or for the explicit inclusion of a keyword or 7517 a list of keywords. This list may include the 7518 @code{LocalKeyword} that has been configured. 7519 7520 The @code{KeywordExpand} option is followed by 7521 @code{=} and the next character may either be @code{i} 7522 to start an inclusion list or @code{e} to start an 7523 exclusion list. If the following lines were added to 7524 the @file{CVSROOT/config} file: 7525 7526 @example 7527 # Add a "MyBSD" keyword and restrict keyword 7528 # expansion 7529 LocalKeyword=MyBSD=CVSHeader 7530 KeywordExpand=iMyBSD 7531 @end example 7532 7533 then only the $@splitrcskeyword{MyBSD}$ keyword would be expanded. 7534 A list may be used. The this example: 7535 7536 @example 7537 # Add a "MyBSD" keyword and restrict keyword 7538 # expansion to the MyBSD, Name and Date keywords. 7539 LocalKeyword=MyBSD=CVSHeader 7540 KeywordExpand=iMyBSD,Name,Date 7541 @end example 7542 7543 would allow $@splitrcskeyword{MyBSD}$, $@splitrcskeyword{Name}$, and 7544 $@splitrcskeyword{Date}$ to be expanded. 7545 7546 It is also possible to configure an exclusion list 7547 using the following: 7548 7549 @example 7550 # Do not expand the non-RCS keyword CVSHeader 7551 KeywordExpand=eCVSHeader 7552 @end example 7553 7554 This allows @sc{cvs} to ignore the recently introduced 7555 $@splitrcskeyword{CVSHeader}$ keyword and retain all of the 7556 others. The exclusion entry could also contain the 7557 standard RCS keyword list, but this could be confusing 7558 to users that expect RCS keywords to be expanded, so 7559 care should be taken to properly set user expectations 7560 for a repository that is configured in that manner. 7561 7562 If there is a desire to not have any RCS keywords 7563 expanded and not use the @code{-ko} flags everywhere, 7564 an administrator may disable all keyword expansion 7565 using the @file{CVSROOT/config} line: 7566 7567 @example 7568 # Do not expand any RCS keywords 7569 KeywordExpand=i 7570 @end example 7571 7572 this could be confusing to users that expect RCS 7573 keywords like $@splitrcskeyword{Id}$ to be expanded properly, 7574 so care should be taken to properly set user 7575 expectations for a repository so configured. 7576 7577 It should be noted that a patch to provide both the 7578 @code{KeywordExpand} and @code{LocalKeyword} features 7579 has been around a long time. However, that patch 7580 implemented these features using @code{tag=} and 7581 @code{tagexpand=} keywords and those keywords are NOT 7582 recognized. 7583 7584 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7585 @node Log keyword 7586 @section Problems with the $@splitrcskeyword{Log}$ keyword. 7587 7588 The @code{$@splitrcskeyword{Log}$} keyword is somewhat 7589 controversial. As long as you are working on your 7590 development system the information is easily accessible 7591 even if you do not use the @code{$@splitrcskeyword{Log}$} 7592 keyword---just do a @code{cvs log}. Once you export 7593 the file the history information might be useless 7594 anyhow. 7595 7596 A more serious concern is that @sc{cvs} is not good at 7597 handling @code{$@splitrcskeyword{Log}$} entries when a branch is 7598 merged onto the main trunk. Conflicts often result 7599 from the merging operation. 7600 @c Might want to check whether the CVS implementation 7601 @c of RCS_merge has this problem the same way rcsmerge 7602 @c does. I would assume so.... 7603 7604 People also tend to "fix" the log entries in the file 7605 (correcting spelling mistakes and maybe even factual 7606 errors). If that is done the information from 7607 @code{cvs log} will not be consistent with the 7608 information inside the file. This may or may not be a 7609 problem in real life. 7610 7611 It has been suggested that the @code{$@splitrcskeyword{Log}$} 7612 keyword should be inserted @emph{last} in the file, and 7613 not in the files header, if it is to be used at all. 7614 That way the long list of change messages will not 7615 interfere with everyday source file browsing. 7616 7617 @c --------------------------------------------------------------------- 7618 @node Tracking sources 7619 @chapter Tracking third-party sources 7620 @cindex Third-party sources 7621 @cindex Tracking sources 7622 7623 @c FIXME: Need discussion of added and removed files. 7624 @c FIXME: This doesn't really adequately introduce the 7625 @c concepts of "vendor" and "you". They don't *have* 7626 @c to be separate organizations or separate people. 7627 @c We want a description which is somewhat more based on 7628 @c the technical issues of which sources go where, but 7629 @c also with enough examples of how this relates to 7630 @c relationships like customer-supplier, developer-QA, 7631 @c maintainer-contributor, or whatever, to make it 7632 @c seem concrete. 7633 If you modify a program to better fit your site, you 7634 probably want to include your modifications when the next 7635 release of the program arrives. @sc{cvs} can help you with 7636 this task. 7637 7638 @cindex Vendor 7639 @cindex Vendor branch 7640 @cindex Branch, vendor- 7641 In the terminology used in @sc{cvs}, the supplier of the 7642 program is called a @dfn{vendor}. The unmodified 7643 distribution from the vendor is checked in on its own 7644 branch, the @dfn{vendor branch}. @sc{cvs} reserves branch 7645 1.1.1 for this use. 7646 7647 When you modify the source and commit it, your revision 7648 will end up on the main trunk. When a new release is 7649 made by the vendor, you commit it on the vendor branch 7650 and copy the modifications onto the main trunk. 7651 7652 Use the @code{import} command to create and update 7653 the vendor branch. When you import a new file, 7654 (usually) the vendor branch is made the `head' revision, so 7655 anyone that checks out a copy of the file gets that 7656 revision. When a local modification is committed it is 7657 placed on the main trunk, and made the `head' 7658 revision. 7659 7660 @menu 7661 * First import:: Importing for the first time 7662 * Update imports:: Updating with the import command 7663 * Reverting local changes:: Reverting to the latest vendor release 7664 * Binary files in imports:: Binary files require special handling 7665 * Keywords in imports:: Keyword substitution might be undesirable 7666 * Multiple vendor branches:: What if you get sources from several places? 7667 @end menu 7668 7669 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7670 @node First import 7671 @section Importing for the first time 7672 @cindex Importing modules 7673 7674 @c Should mention naming conventions for vendor tags, 7675 @c release tags, and perhaps directory names. 7676 Use the @code{import} command to check in the sources 7677 for the first time. When you use the @code{import} 7678 command to track third-party sources, the @dfn{vendor 7679 tag} and @dfn{release tags} are useful. The 7680 @dfn{vendor tag} is a symbolic name for the branch 7681 (which is always 1.1.1, unless you use the @samp{-b 7682 @var{branch}} flag---see @ref{Multiple vendor branches}.). The 7683 @dfn{release tags} are symbolic names for a particular 7684 release, such as @samp{FSF_0_04}. 7685 7686 @c I'm not completely sure this belongs here. But 7687 @c we need to say it _somewhere_ reasonably obvious; it 7688 @c is a common misconception among people first learning CVS 7689 Note that @code{import} does @emph{not} change the 7690 directory in which you invoke it. In particular, it 7691 does not set up that directory as a @sc{cvs} working 7692 directory; if you want to work with the sources import 7693 them first and then check them out into a different 7694 directory (@pxref{Getting the source}). 7695 7696 @cindex wdiff (import example) 7697 Suppose you have the sources to a program called 7698 @code{wdiff} in a directory @file{wdiff-0.04}, 7699 and are going to make private modifications that you 7700 want to be able to use even when new releases are made 7701 in the future. You start by importing the source to 7702 your repository: 7703 7704 @example 7705 $ cd wdiff-0.04 7706 $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 7707 @end example 7708 7709 The vendor tag is named @samp{FSF_DIST} in the above 7710 example, and the only release tag assigned is 7711 @samp{WDIFF_0_04}. 7712 @c FIXME: Need to say where fsf/wdiff comes from. 7713 7714 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7715 @node Update imports 7716 @section Updating with the import command 7717 7718 When a new release of the source arrives, you import it into the 7719 repository with the same @code{import} command that you used to set up 7720 the repository in the first place. The only difference is that you 7721 specify a different release tag this time: 7722 7723 @example 7724 $ tar xfz wdiff-0.05.tar.gz 7725 $ cd wdiff-0.05 7726 $ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 7727 @end example 7728 7729 @strong{WARNING: If you use a release tag that already exists in one of the 7730 repository archives, files removed by an import may not be detected.} 7731 7732 For files that have not been modified locally, the newly created 7733 revision becomes the head revision. If you have made local 7734 changes, @code{import} will warn you that you must merge the changes 7735 into the main trunk, and tell you to use @samp{checkout -j} to do so: 7736 7737 @c FIXME: why "wdiff" here and "fsf/wdiff" in the 7738 @c "import"? I think the assumption is that one has 7739 @c "wdiff fsf/wdiff" or some such in modules, but it 7740 @c would be better to not use modules in this example. 7741 @example 7742 $ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 7743 @end example 7744 7745 @noindent 7746 The above command will check out the latest revision of 7747 @samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 7748 since yesterday into the working copy. If any conflicts arise during 7749 the merge they should be resolved in the normal way (@pxref{Conflicts 7750 example}). Then, the modified files may be committed. 7751 7752 However, it is much better to use the two release tags rather than using 7753 a date on the branch as suggested above: 7754 7755 @example 7756 $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 7757 @end example 7758 7759 @noindent 7760 The reason this is better is that 7761 using a date, as suggested above, assumes that you do 7762 not import more than one release of a product per day. 7763 More importantly, using the release tags allows @sc{cvs} to detect files 7764 that were removed between the two vendor releases and mark them for 7765 removal. Since @code{import} has no way to detect removed files, you 7766 should do a merge like this even if @code{import} doesn't tell you to. 7767 7768 @node Reverting local changes 7769 @section Reverting to the latest vendor release 7770 7771 You can also revert local changes completely and return 7772 to the latest vendor release by changing the `head' 7773 revision back to the vendor branch on all files. For 7774 example, if you have a checked-out copy of the sources 7775 in @file{~/work.d/wdiff}, and you want to revert to the 7776 vendor's version for all the files in that directory, 7777 you would type: 7778 7779 @example 7780 $ cd ~/work.d/wdiff 7781 $ cvs admin -bFSF_DIST . 7782 @end example 7783 7784 @noindent 7785 You must specify the @samp{-bFSF_DIST} without any space 7786 after the @samp{-b}. @xref{admin options}. 7787 7788 @node Binary files in imports 7789 @section How to handle binary files with cvs import 7790 7791 Use the @samp{-k} wrapper option to tell import which 7792 files are binary. @xref{Wrappers}. 7793 7794 @node Keywords in imports 7795 @section How to handle keyword substitution with cvs import 7796 7797 The sources which you are importing may contain 7798 keywords (@pxref{Keyword substitution}). For example, 7799 the vendor may use @sc{cvs} or some other system 7800 which uses similar keyword expansion syntax. If you 7801 just import the files in the default fashion, then 7802 the keyword expansions supplied by the vendor will 7803 be replaced by keyword expansions supplied by your 7804 own copy of @sc{cvs}. It may be more convenient to 7805 maintain the expansions supplied by the vendor, so 7806 that this information can supply information about 7807 the sources that you imported from the vendor. 7808 7809 To maintain the keyword expansions supplied by the 7810 vendor, supply the @samp{-ko} option to @code{cvs 7811 import} the first time you import the file. 7812 This will turn off keyword expansion 7813 for that file entirely, so if you want to be more 7814 selective you'll have to think about what you want 7815 and use the @samp{-k} option to @code{cvs update} or 7816 @code{cvs admin} as appropriate. 7817 @c Supplying -ko to import if the file already existed 7818 @c has no effect. Not clear to me whether it should 7819 @c or not. 7820 7821 @node Multiple vendor branches 7822 @section Multiple vendor branches 7823 7824 All the examples so far assume that there is only one 7825 vendor from which you are getting sources. In some 7826 situations you might get sources from a variety of 7827 places. For example, suppose that you are dealing with 7828 a project where many different people and teams are 7829 modifying the software. There are a variety of ways to 7830 handle this, but in some cases you have a bunch of 7831 source trees lying around and what you want to do more 7832 than anything else is just to all put them in @sc{cvs} so 7833 that you at least have them in one place. 7834 7835 For handling situations in which there may be more than 7836 one vendor, you may specify the @samp{-b} option to 7837 @code{cvs import}. It takes as an argument the vendor 7838 branch to import to. The default is @samp{-b 1.1.1}. 7839 7840 For example, suppose that there are two teams, the red 7841 team and the blue team, that are sending you sources. 7842 You want to import the red team's efforts to branch 7843 1.1.1 and use the vendor tag RED. You want to import 7844 the blue team's efforts to branch 1.1.3 and use the 7845 vendor tag BLUE. So the commands you might use are: 7846 7847 @example 7848 $ cvs import dir RED RED_1-0 7849 $ cvs import -b 1.1.3 dir BLUE BLUE_1-5 7850 @end example 7851 7852 Note that if your vendor tag does not match your 7853 @samp{-b} option, @sc{cvs} will not detect this case! For 7854 example, 7855 7856 @example 7857 $ cvs import -b 1.1.3 dir RED RED_1-0 7858 @end example 7859 7860 @noindent 7861 Be careful; this kind of mismatch is sure to sow 7862 confusion or worse. I can't think of a useful purpose 7863 for the ability to specify a mismatch here, but if you 7864 discover such a use, don't. @sc{cvs} is likely to make this 7865 an error in some future release. 7866 7867 @c Probably should say more about the semantics of 7868 @c multiple branches. What about the default branch? 7869 @c What about joining (perhaps not as useful with 7870 @c multiple branches, or perhaps it is. Either way 7871 @c should be mentioned). 7872 7873 @c I'm not sure about the best location for this. In 7874 @c one sense, it might belong right after we've introduced 7875 @c CVS's basic version control model, because people need 7876 @c to figure out builds right away. The current location 7877 @c is based on the theory that it kind of akin to the 7878 @c "Revision management" section. 7879 @node Builds 7880 @chapter How your build system interacts with CVS 7881 @cindex Builds 7882 @cindex make 7883 7884 As mentioned in the introduction, @sc{cvs} does not 7885 contain software for building your software from source 7886 code. This section describes how various aspects of 7887 your build system might interact with @sc{cvs}. 7888 7889 @c Is there a way to discuss this without reference to 7890 @c tools other than CVS? I'm not sure there is; I 7891 @c wouldn't think that people who learn CVS first would 7892 @c even have this concern. 7893 One common question, especially from people who are 7894 accustomed to @sc{rcs}, is how to make their build get 7895 an up to date copy of the sources. The answer to this 7896 with @sc{cvs} is two-fold. First of all, since 7897 @sc{cvs} itself can recurse through directories, there 7898 is no need to modify your @file{Makefile} (or whatever 7899 configuration file your build tool uses) to make sure 7900 each file is up to date. Instead, just use two 7901 commands, first @code{cvs -q update} and then 7902 @code{make} or whatever the command is to invoke your 7903 build tool. Secondly, you do not necessarily 7904 @emph{want} to get a copy of a change someone else made 7905 until you have finished your own work. One suggested 7906 approach is to first update your sources, then 7907 implement, build and 7908 test the change you were thinking of, and then commit 7909 your sources (updating first if necessary). By 7910 periodically (in between changes, using the approach 7911 just described) updating your entire tree, you ensure 7912 that your sources are sufficiently up to date. 7913 7914 @cindex Bill of materials 7915 One common need is to record which versions of which 7916 source files went into a particular build. This kind 7917 of functionality is sometimes called @dfn{bill of 7918 materials} or something similar. The best way to do 7919 this with @sc{cvs} is to use the @code{tag} command to 7920 record which versions went into a given build 7921 (@pxref{Tags}). 7922 7923 Using @sc{cvs} in the most straightforward manner 7924 possible, each developer will have a copy of the entire 7925 source tree which is used in a particular build. If 7926 the source tree is small, or if developers are 7927 geographically dispersed, this is the preferred 7928 solution. In fact one approach for larger projects is 7929 to break a project down into smaller 7930 @c I say subsystem instead of module because they may or 7931 @c may not use the modules file. 7932 separately-compiled subsystems, and arrange a way of 7933 releasing them internally so that each developer need 7934 check out only those subsystems which they are 7935 actively working on. 7936 7937 Another approach is to set up a structure which allows 7938 developers to have their own copies of some files, and 7939 for other files to access source files from a central 7940 location. Many people have come up with some such a 7941 @c two such people are paul (a] sander.cupertino.ca.us (for 7942 @c a previous employer) 7943 @c and gunnar.tornblom (a] se.abb.com (spicm and related tools), 7944 @c but as far as I know 7945 @c no one has nicely packaged or released such a system (or 7946 @c instructions for constructing one). 7947 system using features such as the symbolic link feature 7948 found in many operating systems, or the @code{VPATH} 7949 feature found in many versions of @code{make}. One build 7950 tool which is designed to help with this kind of thing 7951 is Odin (see 7952 @code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 7953 @c Should we be saying more about Odin? Or how you use 7954 @c it with CVS? Also, the Prime Time Freeware for Unix 7955 @c disk (see http://www.ptf.com/) has Odin (with a nice 7956 @c paragraph summarizing it on the web), so that might be a 7957 @c semi-"official" place to point people. 7958 @c 7959 @c Of course, many non-CVS systems have this kind of 7960 @c functionality, for example OSF's ODE 7961 @c (http://www.osf.org/ode/) or mk 7962 @c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 7963 @c He has changed providers in the past; a search engine search 7964 @c for "Peter Ziobrzynski" probably won't get too many 7965 @c spurious hits :-). A more stable URL might be 7966 @c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 7967 @c there is any point in mentioning them here unless they 7968 @c can work with CVS. 7969 7970 @c --------------------------------------------------------------------- 7971 @node Special Files 7972 @chapter Special Files 7973 7974 @cindex Special files 7975 @cindex Device nodes 7976 @cindex Ownership, saving in CVS 7977 @cindex Permissions, saving in CVS 7978 @cindex Hard links 7979 @cindex Symbolic links 7980 7981 In normal circumstances, @sc{cvs} works only with regular 7982 files. Every file in a project is assumed to be 7983 persistent; it must be possible to open, read and close 7984 them; and so on. @sc{cvs} also ignores file permissions and 7985 ownerships, leaving such issues to be resolved by the 7986 developer at installation time. In other words, it is 7987 not possible to "check in" a device into a repository; 7988 if the device file cannot be opened, @sc{cvs} will refuse to 7989 handle it. Files also lose their ownerships and 7990 permissions during repository transactions. 7991 7992 @ignore 7993 If the configuration variable @code{PreservePermissions} 7994 (@pxref{config}) is set in the repository, @sc{cvs} will 7995 save the following file characteristics in the 7996 repository: 7997 7998 @itemize @bullet 7999 @item user and group ownership 8000 @item permissions 8001 @item major and minor device numbers 8002 @item symbolic links 8003 @item hard link structure 8004 @end itemize 8005 8006 Using the @code{PreservePermissions} option affects the 8007 behavior of @sc{cvs} in several ways. First, some of the 8008 new operations supported by @sc{cvs} are not accessible to 8009 all users. In particular, file ownership and special 8010 file characteristics may only be changed by the 8011 superuser. When the @code{PreservePermissions} 8012 configuration variable is set, therefore, users will 8013 have to be `root' in order to perform @sc{cvs} operations. 8014 8015 When @code{PreservePermissions} is in use, some @sc{cvs} 8016 operations (such as @samp{cvs status}) will not 8017 recognize a file's hard link structure, and so will 8018 emit spurious warnings about mismatching hard links. 8019 The reason is that @sc{cvs}'s internal structure does not 8020 make it easy for these operations to collect all the 8021 necessary data about hard links, so they check for file 8022 conflicts with inaccurate data. 8023 8024 A more subtle difference is that @sc{cvs} considers a file 8025 to have changed only if its contents have changed 8026 (specifically, if the modification time of the working 8027 file does not match that of the repository's file). 8028 Therefore, if only the permissions, ownership or hard 8029 linkage have changed, or if a device's major or minor 8030 numbers have changed, @sc{cvs} will not notice. In order to 8031 commit such a change to the repository, you must force 8032 the commit with @samp{cvs commit -f}. This also means 8033 that if a file's permissions have changed and the 8034 repository file is newer than the working copy, 8035 performing @samp{cvs update} will silently change the 8036 permissions on the working copy. 8037 8038 Changing hard links in a @sc{cvs} repository is particularly 8039 delicate. Suppose that file @file{foo} is linked to 8040 file @file{old}, but is later relinked to file 8041 @file{new}. You can wind up in the unusual situation 8042 where, although @file{foo}, @file{old} and @file{new} 8043 have all had their underlying link patterns changed, 8044 only @file{foo} and @file{new} have been modified, so 8045 @file{old} is not considered a candidate for checking 8046 in. It can be very easy to produce inconsistent 8047 results this way. Therefore, we recommend that when it 8048 is important to save hard links in a repository, the 8049 prudent course of action is to @code{touch} any file 8050 whose linkage or status has changed since the last 8051 checkin. Indeed, it may be wise to @code{touch *} 8052 before each commit in a directory with complex hard 8053 link structures. 8054 8055 It is worth noting that only regular files may 8056 be merged, for reasons that hopefully are obvious. If 8057 @samp{cvs update} or @samp{cvs checkout -j} attempts to 8058 merge a symbolic link with a regular file, or two 8059 device files for different kinds of devices, @sc{cvs} will 8060 report a conflict and refuse to perform the merge. At 8061 the same time, @samp{cvs diff} will not report any 8062 differences between these files, since no meaningful 8063 textual comparisons can be made on files which contain 8064 no text. 8065 8066 The @code{PreservePermissions} features do not work 8067 with client/server @sc{cvs}. Another limitation is 8068 that hard links must be to other files within the same 8069 directory; hard links across directories are not 8070 supported. 8071 @end ignore 8072 8073 @c --------------------------------------------------------------------- 8074 @c ----- START MAN 1 ----- 8075 @node CVS commands 8076 @appendix Guide to CVS commands 8077 8078 This appendix describes the overall structure of 8079 @sc{cvs} commands, and describes some commands in 8080 detail (others are described elsewhere; for a quick 8081 reference to @sc{cvs} commands, @pxref{Invoking CVS}). 8082 @c The idea is that we want to move the commands which 8083 @c are described here into the main body of the manual, 8084 @c in the process reorganizing the manual to be 8085 @c organized around what the user wants to do, not 8086 @c organized around CVS commands. 8087 @c 8088 @c Note that many users do expect a manual which is 8089 @c organized by command. At least some users do. 8090 @c One good addition to the "organized by command" 8091 @c section (if any) would be "see also" links. 8092 @c The awk manual might be a good example; it has a 8093 @c reference manual which is more verbose than Invoking 8094 @c CVS but probably somewhat less verbose than CVS 8095 @c Commands. 8096 8097 @menu 8098 * Structure:: Overall structure of CVS commands 8099 * Exit status:: Indicating CVS's success or failure 8100 * ~/.cvsrc:: Default options with the ~/.cvsrc file 8101 * Global options:: Options you give to the left of cvs_command 8102 * Common options:: Options you give to the right of cvs_command 8103 * Date input formats:: Acceptable formats for date specifications 8104 * add:: Add files and directories to the repository 8105 * admin:: Administration 8106 * annotate & rannotate:: What revision modified each line of a file? 8107 * checkout:: Checkout sources for editing 8108 * commit:: Check files into the repository 8109 * diff:: Show differences between revisions 8110 * export:: Export sources from CVS, similar to checkout 8111 * history:: Show status of files and users 8112 * import:: Import sources into CVS, using vendor branches 8113 * init:: Initialize a repository 8114 * log & rlog:: Show log messages for files 8115 * ls & rls:: List files in the repository 8116 * rdiff:: 'patch' format diffs between releases 8117 * release:: Indicate that a directory is no longer in use 8118 * remove:: Remove files from active development 8119 * server & pserver:: Act as a server for a client on stdin/stdout 8120 * tag & rtag:: Mark project snapshot for later retrieval 8121 * update:: Bring work tree in sync with repository 8122 @end menu 8123 8124 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8125 @node Structure 8126 @appendixsec Overall structure of CVS commands 8127 @cindex Structure 8128 @cindex CVS command structure 8129 @cindex Command structure 8130 @cindex Format of CVS commands 8131 8132 The overall format of all @sc{cvs} commands is: 8133 8134 @example 8135 cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 8136 @end example 8137 8138 @table @code 8139 @item cvs 8140 The name of the @sc{cvs} program. 8141 8142 @item cvs_options 8143 Some options that affect all sub-commands of @sc{cvs}. These are 8144 described below. 8145 8146 @item cvs_command 8147 One of several different sub-commands. Some of the commands have 8148 aliases that can be used instead; those aliases are noted in the 8149 reference manual for that command. There are only two situations 8150 where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 8151 list of available commands, and @samp{cvs -v} displays version 8152 information on @sc{cvs} itself. 8153 8154 @item command_options 8155 Options that are specific for the command. 8156 8157 @item command_args 8158 Arguments to the commands. 8159 @end table 8160 8161 There is unfortunately some confusion between 8162 @code{cvs_options} and @code{command_options}. 8163 When given as a @code{cvs_option}, some options only 8164 affect some of the commands. When given as a 8165 @code{command_option} it may have a different meaning, and 8166 be accepted by more commands. In other words, do not 8167 take the above categorization too seriously. Look at 8168 the documentation instead. 8169 8170 @node Exit status 8171 @appendixsec CVS's exit status 8172 @cindex Exit status, of CVS 8173 8174 @sc{cvs} can indicate to the calling environment whether it 8175 succeeded or failed by setting its @dfn{exit status}. 8176 The exact way of testing the exit status will vary from 8177 one operating system to another. For example in a unix 8178 shell script the @samp{$?} variable will be 0 if the 8179 last command returned a successful exit status, or 8180 greater than 0 if the exit status indicated failure. 8181 8182 If @sc{cvs} is successful, it returns a successful status; 8183 if there is an error, it prints an error message and 8184 returns a failure status. The one exception to this is 8185 the @code{cvs diff} command. It will return a 8186 successful status if it found no differences, or a 8187 failure status if there were differences or if there 8188 was an error. Because this behavior provides no good 8189 way to detect errors, in the future it is possible that 8190 @code{cvs diff} will be changed to behave like the 8191 other @sc{cvs} commands. 8192 @c It might seem like checking whether cvs -q diff 8193 @c produces empty or non-empty output can tell whether 8194 @c there were differences or not. But it seems like 8195 @c there are cases with output but no differences 8196 @c (testsuite basica-8b). It is not clear to me how 8197 @c useful it is for a script to be able to check 8198 @c whether there were differences. 8199 @c FIXCVS? In previous versions of CVS, cvs diff 8200 @c returned 0 for no differences, 1 for differences, or 8201 @c 2 for errors. Is this behavior worth trying to 8202 @c bring back (but what does it mean for VMS?)? 8203 8204 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8205 @node ~/.cvsrc 8206 @appendixsec Default options and the ~/.cvsrc file 8207 @cindex .cvsrc file 8208 @cindex Option defaults 8209 8210 There are some @code{command_options} that are used so 8211 often that you might have set up an alias or some other 8212 means to make sure you always specify that option. One 8213 example (the one that drove the implementation of the 8214 @file{.cvsrc} support, actually) is that many people find the 8215 default output of the @samp{diff} command to be very 8216 hard to read, and that either context diffs or unidiffs 8217 are much easier to understand. 8218 8219 The @file{~/.cvsrc} file is a way that you can add 8220 default options to @code{cvs_commands} within cvs, 8221 instead of relying on aliases or other shell scripts. 8222 8223 The format of the @file{~/.cvsrc} file is simple. The 8224 file is searched for a line that begins with the same 8225 name as the @code{cvs_command} being executed. If a 8226 match is found, then the remainder of the line is split 8227 up (at whitespace characters) into separate options and 8228 added to the command arguments @emph{before} any 8229 options from the command line. 8230 8231 If a command has two names (e.g., @code{checkout} and 8232 @code{co}), the official name, not necessarily the one 8233 used on the command line, will be used to match against 8234 the file. So if this is the contents of the user's 8235 @file{~/.cvsrc} file: 8236 8237 @example 8238 log -N 8239 diff -uN 8240 rdiff -u 8241 update -Pd 8242 checkout -P 8243 release -d 8244 @end example 8245 8246 @noindent 8247 the command @samp{cvs checkout foo} would have the 8248 @samp{-P} option added to the arguments, as well as 8249 @samp{cvs co foo}. 8250 8251 With the example file above, the output from @samp{cvs 8252 diff foobar} will be in unidiff format. @samp{cvs diff 8253 -c foobar} will provide context diffs, as usual. 8254 Getting "old" format diffs would be slightly more 8255 complicated, because @code{diff} doesn't have an option 8256 to specify use of the "old" format, so you would need 8257 @samp{cvs -f diff foobar}. 8258 8259 In place of the command name you can use @code{cvs} to 8260 specify global options (@pxref{Global options}). For 8261 example the following line in @file{.cvsrc} 8262 8263 @example 8264 cvs -z6 8265 @end example 8266 8267 @noindent 8268 causes @sc{cvs} to use compression level 6. 8269 8270 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8271 @node Global options 8272 @appendixsec Global options 8273 @cindex Options, global 8274 @cindex Global options 8275 @cindex Left-hand options 8276 8277 The available @samp{cvs_options} (that are given to the 8278 left of @samp{cvs_command}) are: 8279 8280 @table @code 8281 @item --allow-root=@var{rootdir} 8282 May be invoked multiple times to specify one legal @sc{cvsroot} directory with 8283 each invocation. Also causes CVS to preparse the configuration file for each 8284 specified root, which can be useful when configuring write proxies, See 8285 @ref{Password authentication server} & @ref{Write proxies}. 8286 8287 @cindex Authentication, stream 8288 @cindex Stream authentication 8289 @item -a 8290 Authenticate all communication between the client and 8291 the server. Only has an effect on the @sc{cvs} client. 8292 As of this writing, this is only implemented when using 8293 a GSSAPI connection (@pxref{GSSAPI authenticated}). 8294 Authentication prevents certain sorts of attacks 8295 involving hijacking the active @sc{tcp} connection. 8296 Enabling authentication does not enable encryption. 8297 8298 @cindex RCSBIN, overriding 8299 @cindex Overriding RCSBIN 8300 @item -b @var{bindir} 8301 In @sc{cvs} 1.9.18 and older, this specified that 8302 @sc{rcs} programs are in the @var{bindir} directory. 8303 Current versions of @sc{cvs} do not run @sc{rcs} 8304 programs; for compatibility this option is accepted, 8305 but it does nothing. 8306 8307 @cindex TMPDIR, environment variable 8308 @cindex temporary file directory, set via command line 8309 @cindex temporary file directory, set via environment variable 8310 @cindex temporary file directory, set via config 8311 @cindex temporary files, location of 8312 @item -T @var{tempdir} 8313 Use @var{tempdir} as the directory where temporary files are 8314 located. 8315 8316 The @sc{cvs} client and server store temporary files in a temporary directory. 8317 The path to this temporary directory is set via, in order of precedence: 8318 8319 @itemize @bullet 8320 @item 8321 The argument to the global @samp{-T} option. 8322 8323 @item 8324 The value set for @code{TmpDir} in the config file (server only - 8325 @pxref{config}). 8326 8327 @item 8328 The contents of the @code{$TMPDIR} environment variable (@code{%TMPDIR%} on 8329 Windows - @pxref{Environment variables}). 8330 8331 @item 8332 /tmp 8333 8334 @end itemize 8335 8336 Temporary directories should always be specified as an absolute pathname. 8337 When running a CVS client, @samp{-T} affects only the local process; 8338 specifying @samp{-T} for the client has no effect on the server and 8339 vice versa. 8340 8341 @cindex CVS directory, overriding 8342 @cindex Overriding CVS directory 8343 @item -D @var{cvs_directory} 8344 Use @var{cvs_directory} as the location of the CVS internal files, instead 8345 of the default @file{CVS}. 8346 8347 @cindex CVSROOT, overriding 8348 @cindex Overriding CVSROOT 8349 @item -d @var{cvs_root_directory} 8350 Use @var{cvs_root_directory} as the root directory 8351 pathname of the repository. Overrides the setting of 8352 the @code{$CVSROOT} environment variable. @xref{Repository}. 8353 8354 @cindex EDITOR, overriding 8355 @cindex Overriding EDITOR 8356 @item -e @var{editor} 8357 Use @var{editor} to enter revision log information. Overrides the 8358 setting of the @code{$CVSEDITOR} and @code{$EDITOR} 8359 environment variables. For more information, see 8360 @ref{Committing your changes}. 8361 8362 @item -f 8363 Do not read the @file{~/.cvsrc} file. This 8364 option is most often used because of the 8365 non-orthogonality of the @sc{cvs} option set. For 8366 example, the @samp{cvs log} option @samp{-N} (turn off 8367 display of tag names) does not have a corresponding 8368 option to turn the display on. So if you have 8369 @samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 8370 you may need to use @samp{-f} to show the tag names. 8371 8372 @item -H 8373 @itemx --help 8374 Display usage information about the specified @samp{cvs_command} 8375 (but do not actually execute the command). If you don't specify 8376 a command name, @samp{cvs -H} displays overall help for 8377 @sc{cvs}, including a list of other help options. 8378 @c It seems to me it is better to document it this way 8379 @c rather than trying to update this documentation 8380 @c every time that we add a --help-foo option. But 8381 @c perhaps that is confusing... 8382 8383 @cindex Read-only repository mode 8384 @item -R 8385 Turns on read-only repository mode. This allows one to check out from a 8386 read-only repository, such as within an anoncvs server, or from a @sc{cd-rom} 8387 repository. 8388 8389 Same effect as if the @code{CVSREADONLYFS} environment 8390 variable is set. Using @samp{-R} can also considerably 8391 speed up checkouts over NFS. 8392 8393 @cindex Read-only mode 8394 @item -n 8395 Do not change any files. Attempt to execute the 8396 @samp{cvs_command}, but only to issue reports; do not remove, 8397 update, or merge any existing files, or create any new files. 8398 8399 Note that @sc{cvs} will not necessarily produce exactly 8400 the same output as without @samp{-n}. In some cases 8401 the output will be the same, but in other cases 8402 @sc{cvs} will skip some of the processing that would 8403 have been required to produce the exact same output. 8404 8405 @item -Q 8406 Cause the command to be really quiet; the command will only 8407 generate output for serious problems. 8408 8409 @item -q 8410 Cause the command to be somewhat quiet; informational messages, 8411 such as reports of recursion through subdirectories, are 8412 suppressed. 8413 8414 @cindex Read-only files, and -r 8415 @item -r 8416 Make new working files read-only. Same effect 8417 as if the @code{$CVSREAD} environment variable is set 8418 (@pxref{Environment variables}). The default is to 8419 make working files writable, unless watches are on 8420 (@pxref{Watches}). 8421 8422 @item -s @var{variable}=@var{value} 8423 Set a user variable (@pxref{Variables}). 8424 8425 @cindex Trace 8426 @item -t 8427 Trace program execution; display messages showing the steps of 8428 @sc{cvs} activity. Particularly useful with @samp{-n} to explore the 8429 potential impact of an unfamiliar command. 8430 8431 @item -u 8432 Do not take internal locks (for transactional integrity) during read 8433 and write operations. (Note this is unrelated to releasing reserved 8434 checkouts, as accomplished with the @code{cvs admin -u} command, 8435 @pxref{admin options}.) 8436 8437 @item -v 8438 @item --version 8439 Display version and copyright information for @sc{cvs}. 8440 8441 @cindex CVSREAD, overriding 8442 @cindex Overriding CVSREAD 8443 @item -w 8444 Make new working files read-write. Overrides the 8445 setting of the @code{$CVSREAD} environment variable. 8446 Files are created read-write by default, unless @code{$CVSREAD} is 8447 set 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 8457 Encrypt all communication between the client and the 8458 server. Only has an effect on the @sc{cvs} client. As 8459 of this writing, this is only implemented when using a 8460 GSSAPI connection (@pxref{GSSAPI authenticated}) or a 8461 Kerberos connection (@pxref{Kerberos authenticated}). 8462 Enabling encryption implies that message traffic is 8463 also authenticated. Encryption support is not 8464 available by default; it must be enabled using a 8465 special configure option, @file{--enable-encryption}, 8466 when you build @sc{cvs}. 8467 8468 @item -z @var{level} 8469 @cindex Compression 8470 @cindex Gzip 8471 Request compression @var{level} for network traffic. 8472 @sc{cvs} interprets @var{level} identically to the @code{gzip} program. 8473 Valid levels are 1 (high speed, low compression) to 8474 9 (low speed, high compression), or 0 to disable 8475 compression (the default). Data sent to the server will 8476 be compressed at the requested level and the client will request 8477 the server use the same compression level for data returned. The 8478 server will use the closest level allowed by the server administrator to 8479 compress returned data. This option only has an effect when passed to 8480 the @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 8489 This section describes the @samp{command_options} that 8490 are available across several @sc{cvs} commands. These 8491 options are always given to the right of 8492 @samp{cvs_command}. Not all 8493 commands support all of these options; each option is 8494 only supported for commands where it makes sense. 8495 However, when a command has one of these options you 8496 can almost always count on the same behavior of the 8497 option as in other commands. (Other command options, 8498 which are listed with the individual commands, may have 8499 different behavior from one @sc{cvs} command to the other). 8500 8501 @strong{Note: the @samp{history} command is an exception; it supports 8502 many 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} 8509 Use the most recent revision no later than @var{date_spec}. 8510 @var{date_spec} is a single argument, a date description 8511 specifying a date in the past. 8512 8513 The specification is @dfn{sticky} when you use it to make a 8514 private copy of a source file; that is, when you get a working 8515 file using @samp{-D}, @sc{cvs} records the date you specified, so that 8516 further 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 8523 slightly different way; @pxref{history options}). 8524 8525 For 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 8585 Remember to quote the argument to the @samp{-D} 8586 flag so that your shell doesn't interpret spaces as 8587 argument separators. A command using the @samp{-D} 8588 flag 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 8596 When you specify a particular date or tag to @sc{cvs} commands, they 8597 normally ignore files that do not contain the tag (or did not 8598 exist prior to the date) that you specified. Use the @samp{-f} option 8599 if you want files retrieved even when there is no match for the 8600 tag or date. (The most recent revision of the file 8601 will be used). 8602 8603 Note that even with @samp{-f}, a tag that you specify 8604 must exist (that is, in some file, not necessary in 8605 every file). This is so that @sc{cvs} will continue to 8606 give 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} 8614 commands also have a 8615 @samp{-f} option, but it has a different behavior for 8616 those commands. See @ref{commit options}, and 8617 @ref{Removing files}.} 8618 8619 @item -k @var{kflag} 8620 Override 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} 8623 commands, your @var{kflag} specification is 8624 @dfn{sticky}; that is, when you use this option 8625 with a @code{checkout} or @code{update} command, 8626 @sc{cvs} associates your selected @var{kflag} with any files 8627 it operates on, and continues to use that @var{kflag} with future 8628 commands on the same files until you specify otherwise. 8629 8630 The @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 8635 overrode the @samp{-kb} indication for a binary file. This could 8636 sometimes corrupt binary files. @xref{Merging and keywords}, for 8637 more.} 8638 8639 @item -l 8640 Local; run only in current working directory, rather than 8641 recursing through subdirectories. 8642 8643 Available 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}, 8647 and @code{watchers}. 8648 8649 @cindex Editor, avoiding invocation of 8650 @cindex Avoiding editor invocation 8651 @item -m @var{message} 8652 Use @var{message} as log information, instead of 8653 invoking an editor. 8654 8655 Available with the following commands: @code{add}, 8656 @code{commit} and @code{import}. 8657 8658 @item -n 8659 Do not run any tag program. (A program can be 8660 specified to run in the modules 8661 database (@pxref{modules}); this option bypasses it). 8662 8663 @strong{Note: this is not the same as the @samp{cvs -n} 8664 program option, which you can specify to the left of a cvs command!} 8665 8666 Available with the @code{checkout}, @code{commit}, @code{export}, 8667 and @code{rtag} commands. 8668 8669 @item -P 8670 Prune empty directories. See @ref{Removing directories}. 8671 8672 @item -p 8673 Pipe the files retrieved from the repository to standard output, 8674 rather than writing them in the current directory. Available 8675 with the @code{checkout} and @code{update} commands. 8676 8677 @item -R 8678 Process directories recursively. This is the default for all @sc{cvs} 8679 commands, with the exception of @code{ls} & @code{rls}. 8680 8681 Available 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}, 8685 and @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 8691 Use the revision specified by the @var{tag} argument (and the @var{date} 8692 argument for the commands which accept it) instead of the 8693 default @dfn{head} revision. As well as arbitrary tags defined 8694 with the @code{tag} or @code{rtag} command, two special tags are 8695 always available: @samp{HEAD} refers to the most recent version 8696 available in the repository, and @samp{BASE} refers to the 8697 revision 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 8722 The tag specification is sticky when you use this 8723 with @code{checkout} or @code{update} to make your own 8724 copy of a file: @sc{cvs} remembers the tag and continues to use it on 8725 future update commands, until you specify otherwise (for more information 8726 on sticky tags/dates, @pxref{Sticky tags}). 8727 8728 The tag can be either a symbolic or numeric tag, as 8729 described in @ref{Tags}, or the name of a branch, as 8730 described in @ref{Branching and merging}. 8731 When @var{tag} is the name of a 8732 branch, some commands accept the optional @var{date} argument to specify 8733 the revision as of the given date on the branch. 8734 When a command expects a specific revision, 8735 the name of a branch is interpreted as the most recent 8736 revision on that branch. 8737 8738 Specifying the @samp{-q} global option along with the 8739 @samp{-r} command option is often useful, to suppress 8740 the warning messages when the @sc{rcs} file 8741 does not contain the specified tag. 8742 8743 @strong{Note: this is not the same as the overall @samp{cvs -r} option, 8744 which 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} 8747 commands. 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}, 8751 and @code{update} commands. 8752 8753 @item -W 8754 Specify file names that should be filtered. You can 8755 use this option repeatedly. The spec can be a file 8756 name pattern of the same type that you can specify in 8757 the @file{.cvswrappers} file. 8758 Available with the following commands: @code{import}, 8759 and @code{update}. 8760 8761 @end table 8762 8763 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8764 @include getdate-cvs.texi 8765 8766 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8767 @node add 8768 @appendixsec add---Add files and directories to the repository 8769 @cindex add (subcommand) 8770 8771 @itemize @bullet 8772 @item 8773 Synopsis: add [-k rcs-kflag] [-m message] files... 8774 @item 8775 Requires: repository, working directory. 8776 @item 8777 Changes: repository, working directory. 8778 @end itemize 8779 8780 The @code{add} command is used to present new files 8781 and directories for addition into the @sc{cvs} 8782 repository. When @code{add} is used on a directory, 8783 a new directory is created in the repository 8784 immediately. When used on a file, only the working 8785 directory is updated. Changes to the repository are 8786 not made until the @code{commit} command is used on 8787 the newly added file. 8788 8789 The @code{add} command also resurrects files that 8790 have been previously removed. This can be done 8791 before or after the @code{commit} command is used 8792 to finalize the removal of files. Resurrected files 8793 are restored into the working directory at the time 8794 the @code{add} command is executed. 8795 8796 @menu 8797 * add options:: add options 8798 * add examples:: add examples 8799 @end menu 8800 8801 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8802 @node add options 8803 @appendixsubsec add options 8804 8805 These standard options are supported by @code{add} 8806 (@pxref{Common options}, for a complete description of 8807 them): 8808 8809 @table @code 8810 @item -k @var{kflag} 8811 Process keywords according to @var{kflag}. See 8812 @ref{Keyword substitution}. 8813 This option is sticky; future updates of 8814 this file in this working directory will use the same 8815 @var{kflag}. The @code{status} command can be viewed 8816 to see the sticky options. For more information on 8817 the @code{status} command, @xref{Invoking CVS}. 8818 8819 @item -m @var{message} 8820 Use @var{message} as the log message, instead of 8821 invoking an editor. 8822 @end table 8823 8824 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8825 @node add examples 8826 @appendixsubsec add examples 8827 8828 @appendixsubsubsec Adding a directory 8829 8830 @example 8831 $ mkdir doc 8832 $ cvs add doc 8833 Directory /path/to/repository/doc added to the repository 8834 @end example 8835 8836 @appendixsubsubsec Adding a file 8837 8838 @example 8839 8840 $ >TODO 8841 $ cvs add TODO 8842 cvs add: scheduling file `TODO' for addition 8843 cvs add: use 'cvs commit' to add this file permanently 8844 @end example 8845 8846 @appendixsubsubsec Undoing a @code{remove} command 8847 8848 @example 8849 $ rm -f makefile 8850 $ cvs remove makefile 8851 cvs remove: scheduling `makefile' for removal 8852 cvs remove: use 'cvs commit' to remove this file permanently 8853 $ cvs add makefile 8854 U makefile 8855 cvs add: makefile, version 1.2, resurrected 8856 @end example 8857 8858 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8859 @node admin 8860 @appendixsec admin---Administration 8861 @cindex Admin (subcommand) 8862 8863 @itemize @bullet 8864 @item 8865 Requires: repository, working directory. 8866 @item 8867 Changes: repository. 8868 @item 8869 Synonym: rcs 8870 @end itemize 8871 8872 This is the @sc{cvs} interface to assorted 8873 administrative facilities. Some of them have 8874 questionable usefulness for @sc{cvs} but exist for 8875 historical purposes. Some of the questionable options 8876 are likely to disappear in the future. This command 8877 @emph{does} work recursively, so extreme care should be 8878 used. 8879 8880 @cindex cvsadmin 8881 @cindex UserAdminOptions, in CVSROOT/config 8882 On unix, if there is a group named @code{cvsadmin}, 8883 only members of that group can run @code{cvs admin} 8884 commands, except for those specified using the 8885 @code{UserAdminOptions} configuration option in the 8886 @file{CVSROOT/config} file. Options specified using 8887 @code{UserAdminOptions} can be run by any user. See 8888 @ref{config} for more on @code{UserAdminOptions}. 8889 8890 The @code{cvsadmin} group should exist on the server, 8891 or any system running the non-client/server @sc{cvs}. 8892 To disallow @code{cvs admin} for all users, create a 8893 group with no users in it. On NT, the @code{cvsadmin} 8894 feature does not exist and all users 8895 can run @code{cvs admin}. 8896 8897 @menu 8898 * admin options:: admin options 8899 @end menu 8900 8901 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8902 @node admin options 8903 @appendixsubsec admin options 8904 8905 Some of these options have questionable usefulness for 8906 @sc{cvs} but exist for historical purposes. Some even 8907 make it impossible to use @sc{cvs} until you undo the 8908 effect! 8909 8910 @table @code 8911 @item -A@var{oldfile} 8912 Might not work together with @sc{cvs}. Append the 8913 access list of @var{oldfile} to the access list of the 8914 @sc{rcs} file. 8915 8916 @item -a@var{logins} 8917 Might not work together with @sc{cvs}. Append the 8918 login names appearing in the comma-separated list 8919 @var{logins} to the access list of the @sc{rcs} file. 8920 8921 @item -b[@var{rev}] 8922 Set the default branch to @var{rev}. In @sc{cvs}, you 8923 normally do not manipulate default branches; sticky 8924 tags (@pxref{Sticky tags}) are a better way to decide 8925 which branch you want to work on. There is one reason 8926 to run @code{cvs admin -b}: to revert to the vendor's 8927 version when using vendor branches (@pxref{Reverting 8928 local changes}). 8929 There can be no space between @samp{-b} and its argument. 8930 @c Hmm, we don't document the usage where rev is 8931 @c omitted. Maybe that usage can/should be deprecated 8932 @c (and replaced with -bHEAD or something?) (so we can toss 8933 @c the optional argument). Note that -bHEAD does not 8934 @c work, as of 17 Sep 1997, but probably will once "cvs 8935 @c admin" is internal to CVS. 8936 8937 @cindex Comment leader 8938 @item -c@var{string} 8939 Sets the comment leader to @var{string}. The comment 8940 leader is not used by current versions of @sc{cvs} or 8941 @sc{rcs} 5.7. Therefore, you can almost surely not 8942 worry about it. @xref{Keyword substitution}. 8943 8944 @item -e[@var{logins}] 8945 Might not work together with @sc{cvs}. Erase the login 8946 names appearing in the comma-separated list 8947 @var{logins} from the access list of the RCS file. If 8948 @var{logins} is omitted, erase the entire access list. 8949 There can be no space between @samp{-e} and its argument. 8950 8951 @item -I 8952 Run interactively, even if the standard input is not a 8953 terminal. This option does not work with the 8954 client/server @sc{cvs} and is likely to disappear in 8955 a future release of @sc{cvs}. 8956 8957 @item -i 8958 Useless with @sc{cvs}. This creates and initializes a 8959 new @sc{rcs} file, without depositing a revision. With 8960 @sc{cvs}, add files with the @code{cvs add} command 8961 (@pxref{Adding files}). 8962 8963 @item -k@var{subst} 8964 Set the default keyword 8965 substitution to @var{subst}. @xref{Keyword 8966 substitution}. Giving an explicit @samp{-k} option to 8967 @code{cvs update}, @code{cvs export}, or @code{cvs 8968 checkout} overrides this default. 8969 8970 @item -l[@var{rev}] 8971 Lock the revision with number @var{rev}. If a branch 8972 is given, lock the latest revision on that branch. If 8973 @var{rev} is omitted, lock the latest revision on the 8974 default branch. There can be no space between 8975 @samp{-l} and its argument. 8976 8977 This can be used in conjunction with the 8978 @file{rcslock.pl} script in the @file{contrib} 8979 directory of the @sc{cvs} source distribution to 8980 provide reserved checkouts (where only one user can be 8981 editing a given file at a time). See the comments in 8982 that file for details (and see the @file{README} file 8983 in that directory for disclaimers about the unsupported 8984 nature of contrib). According to comments in that 8985 file, locking must be set to strict (which is the default). 8986 8987 @item -L 8988 Set locking to strict. Strict locking means that the 8989 owner of an RCS file is not exempt from locking for 8990 checkin. For use with @sc{cvs}, strict locking must be 8991 set; see the discussion under the @samp{-l} option above. 8992 8993 @cindex Changing a log message 8994 @cindex Replacing a log message 8995 @cindex Correcting a log message 8996 @cindex Fixing a log message 8997 @cindex Log message, correcting 8998 @item -m@var{rev}:@var{msg} 8999 Replace the log message of revision @var{rev} with 9000 @var{msg}. 9001 9002 @c The rcs -M option, to suppress sending mail, has never been 9003 @c documented as a cvs admin option. 9004 9005 @item -N@var{name}[:[@var{rev}]] 9006 Act like @samp{-n}, except override any previous 9007 assignment of @var{name}. For use with magic branches, 9008 see @ref{Magic branch numbers}. 9009 9010 @item -n@var{name}[:[@var{rev}]] 9011 Associate the symbolic name @var{name} with the branch 9012 or revision @var{rev}. It is normally better to use 9013 @samp{cvs tag} or @samp{cvs rtag} instead. Delete the 9014 symbolic name if both @samp{:} and @var{rev} are 9015 omitted; otherwise, print an error message if 9016 @var{name} is already associated with another number. 9017 If @var{rev} is symbolic, it is expanded before 9018 association. A @var{rev} consisting of a branch number 9019 followed by a @samp{.} stands for the current latest 9020 revision in the branch. A @samp{:} with an empty 9021 @var{rev} stands for the current latest revision on the 9022 default branch, normally the trunk. For example, 9023 @samp{cvs admin -n@var{name}:} associates @var{name} with the 9024 current latest revision of all the RCS files; 9025 this contrasts with @samp{cvs admin -n@var{name}:$} which 9026 associates @var{name} with the revision numbers 9027 extracted from keyword strings in the corresponding 9028 working files. 9029 9030 @cindex Deleting revisions 9031 @cindex Outdating revisions 9032 @cindex Saving space 9033 @item -o@var{range} 9034 Deletes (@dfn{outdates}) the revisions given by 9035 @var{range}. 9036 9037 Note that this command can be quite dangerous unless 9038 you know @emph{exactly} what you are doing (for example 9039 see the warnings below about how the 9040 @var{rev1}:@var{rev2} syntax is confusing). 9041 9042 If you are short on disc this option might help you. 9043 But think twice before using it---there is no way short 9044 of restoring the latest backup to undo this command! 9045 If you delete different revisions than you planned, 9046 either due to carelessness or (heaven forbid) a @sc{cvs} 9047 bug, there is no opportunity to correct the error 9048 before the revisions are deleted. It probably would be 9049 a good idea to experiment on a copy of the repository 9050 first. 9051 9052 Specify @var{range} in one of the following ways: 9053 9054 @table @code 9055 @item @var{rev1}::@var{rev2} 9056 Collapse all revisions between rev1 and rev2, so that 9057 @sc{cvs} only stores the differences associated with going 9058 from rev1 to rev2, not intermediate steps. For 9059 example, after @samp{-o 1.3::1.5} one can retrieve 9060 revision 1.3, revision 1.5, or the differences to get 9061 from 1.3 to 1.5, but not the revision 1.4, or the 9062 differences between 1.3 and 1.4. Other examples: 9063 @samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 9064 effect, because there are no intermediate revisions to 9065 remove. 9066 9067 @item ::@var{rev} 9068 Collapse revisions between the beginning of the branch 9069 containing @var{rev} and @var{rev} itself. The 9070 branchpoint and @var{rev} are left intact. For 9071 example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 9072 revision 1.3.2.5, and everything in between, but leaves 9073 1.3 and 1.3.2.6 intact. 9074 9075 @item @var{rev}:: 9076 Collapse revisions between @var{rev} and the end of the 9077 branch containing @var{rev}. Revision @var{rev} is 9078 left intact but the head revision is deleted. 9079 9080 @item @var{rev} 9081 Delete the revision @var{rev}. For example, @samp{-o 9082 1.3} is equivalent to @samp{-o 1.2::1.4}. 9083 9084 @item @var{rev1}:@var{rev2} 9085 Delete the revisions from @var{rev1} to @var{rev2}, 9086 inclusive, on the same branch. One will not be able to 9087 retrieve @var{rev1} or @var{rev2} or any of the 9088 revisions in between. For example, the command 9089 @samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 9090 It means to delete revisions up to, and including, the 9091 tag R_1_02. But beware! If there are files that have not 9092 changed between R_1_02 and R_1_03 the file will have 9093 @emph{the same} numerical revision number assigned to 9094 the tags R_1_02 and R_1_03. So not only will it be 9095 impossible to retrieve R_1_02; R_1_03 will also have to 9096 be restored from the tapes! In most cases you want to 9097 specify @var{rev1}::@var{rev2} instead. 9098 9099 @item :@var{rev} 9100 Delete revisions from the beginning of the 9101 branch containing @var{rev} up to and including 9102 @var{rev}. 9103 9104 @item @var{rev}: 9105 Delete revisions from revision @var{rev}, including 9106 @var{rev} itself, to the end of the branch containing 9107 @var{rev}. 9108 @end table 9109 9110 None of the revisions to be deleted may have 9111 branches or locks. 9112 9113 If any of the revisions to be deleted have symbolic 9114 names, and one specifies one of the @samp{::} syntaxes, 9115 then @sc{cvs} will give an error and not delete any 9116 revisions. If you really want to delete both the 9117 symbolic names and the revisions, first delete the 9118 symbolic names with @code{cvs tag -d}, then run 9119 @code{cvs admin -o}. If one specifies the 9120 non-@samp{::} syntaxes, then @sc{cvs} will delete the 9121 revisions but leave the symbolic names pointing to 9122 nonexistent revisions. This behavior is preserved for 9123 compatibility with previous versions of @sc{cvs}, but 9124 because it isn't very useful, in the future it may 9125 change to be like the @samp{::} case. 9126 9127 Due to the way @sc{cvs} handles branches @var{rev} 9128 cannot be specified symbolically if it is a branch. 9129 @xref{Magic branch numbers}, for an explanation. 9130 @c FIXME: is this still true? I suspect not. 9131 9132 Make sure that no-one has checked out a copy of the 9133 revision you outdate. Strange things will happen if he 9134 starts to edit it and tries to check it back in. For 9135 this reason, this option is not a good way to take back 9136 a bogus commit; commit a new revision undoing the bogus 9137 change instead (@pxref{Merging two revisions}). 9138 9139 @item -q 9140 Run quietly; do not print diagnostics. 9141 9142 @item -s@var{state}[:@var{rev}] 9143 Useful with @sc{cvs}. Set the state attribute of the 9144 revision @var{rev} to @var{state}. If @var{rev} is a 9145 branch number, assume the latest revision on that 9146 branch. If @var{rev} is omitted, assume the latest 9147 revision on the default branch. Any identifier is 9148 acceptable for @var{state}. A useful set of states is 9149 @samp{Exp} (for experimental), @samp{Stab} (for 9150 stable), and @samp{Rel} (for released). By default, 9151 the state of a new revision is set to @samp{Exp} when 9152 it is created. The state is visible in the output from 9153 @var{cvs log} (@pxref{log & rlog}), and in the 9154 @samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords 9155 (@pxref{Keyword substitution}). Note that @sc{cvs} 9156 uses the @code{dead} state for its own purposes (@pxref{Attic}); to 9157 take a file to or from the @code{dead} state use 9158 commands like @code{cvs remove} and @code{cvs add} 9159 (@pxref{Adding and removing}), not @code{cvs admin -s}. 9160 9161 @item -t[@var{file}] 9162 Useful with @sc{cvs}. Write descriptive text from the 9163 contents of the named @var{file} into the RCS file, 9164 deleting the existing text. The @var{file} pathname 9165 may not begin with @samp{-}. The descriptive text can be seen in the 9166 output from @samp{cvs log} (@pxref{log & rlog}). 9167 There can be no space between @samp{-t} and its argument. 9168 9169 If @var{file} is omitted, 9170 obtain the text from standard input, terminated by 9171 end-of-file or by a line containing @samp{.} by itself. 9172 Prompt for the text if interaction is possible; see 9173 @samp{-I}. 9174 9175 @item -t-@var{string} 9176 Similar to @samp{-t@var{file}}. Write descriptive text 9177 from the @var{string} into the @sc{rcs} file, deleting 9178 the existing text. 9179 There can be no space between @samp{-t} and its argument. 9180 9181 @c The rcs -T option, do not update last-mod time for 9182 @c minor changes, has never been documented as a 9183 @c cvs admin option. 9184 9185 @item -U 9186 Set locking to non-strict. Non-strict locking means 9187 that the owner of a file need not lock a revision for 9188 checkin. For use with @sc{cvs}, strict locking must be 9189 set; see the discussion under the @samp{-l} option 9190 above. 9191 9192 @item -u[@var{rev}] 9193 See the option @samp{-l} above, for a discussion of 9194 using this option with @sc{cvs}. Unlock the revision 9195 with number @var{rev}. If a branch is given, unlock 9196 the latest revision on that branch. If @var{rev} is 9197 omitted, remove the latest lock held by the caller. 9198 Normally, only the locker of a revision may unlock it; 9199 somebody else unlocking a revision breaks the lock. 9200 This causes the original locker to be sent a @code{commit} 9201 notification (@pxref{Getting Notified}). 9202 There can be no space between @samp{-u} and its argument. 9203 9204 @item -V@var{n} 9205 In previous versions of @sc{cvs}, this option meant to 9206 write an @sc{rcs} file which would be acceptable to 9207 @sc{rcs} version @var{n}, but it is now obsolete and 9208 specifying it will produce an error. 9209 @c Note that -V without an argument has never been 9210 @c documented as a cvs admin option. 9211 9212 @item -x@var{suffixes} 9213 In previous versions of @sc{cvs}, this was documented 9214 as a way of specifying the names of the @sc{rcs} 9215 files. However, @sc{cvs} has always required that the 9216 @sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 9217 this option has never done anything useful. 9218 9219 @c The rcs -z option, to specify the timezone, has 9220 @c never been documented as a cvs admin option. 9221 @end table 9222 9223 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9224 @node annotate & rannotate 9225 @appendixsec annotate & rannotate---What revision modified each line of a file? 9226 @cindex annotate (subcommand) 9227 @cindex rannotate (subcommand) 9228 9229 @itemize @bullet 9230 @item 9231 Synopsis: annotate [options] files@dots{} 9232 @item 9233 Requires: repository. 9234 @item 9235 Changes: nothing. 9236 @end itemize 9237 9238 For each file in @var{files}, print the head revision 9239 of the trunk, together with information on the last 9240 modification for each line. 9241 9242 @menu 9243 * annotate options:: annotate options 9244 * annotate example:: annotate example 9245 @end menu 9246 9247 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9248 @node annotate options 9249 @appendixsubsec annotate options 9250 9251 These standard options are supported by @code{annotate} 9252 (@pxref{Common options}, for a complete description of 9253 them): 9254 9255 @table @code 9256 @item -l 9257 Local directory only, no recursion. 9258 9259 @item -R 9260 Process directories recursively. 9261 9262 @item -f 9263 Use head revision if tag/date not found. 9264 9265 @item -F 9266 Annotate binary files. 9267 9268 @item -r @var{tag}[:@var{date}] 9269 Annotate file as of specified revision/tag or, when @var{date} is specified 9270 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9271 existed on @var{date}. See @ref{Common options}. 9272 9273 @item -D @var{date} 9274 Annotate file as of specified date. 9275 @end table 9276 9277 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9278 @node annotate example 9279 @appendixsubsec annotate example 9280 @cindex annotate (subcommand) 9281 @cindex rannotate (subcommand) 9282 9283 For example: 9284 9285 @example 9286 $ cvs annotate ssfile 9287 Annotations for ssfile 9288 *************** 9289 1.1 (mary 27-Mar-96): ssfile line 1 9290 1.2 (joe 28-Mar-96): ssfile line 2 9291 @end example 9292 9293 The file @file{ssfile} currently contains two lines. 9294 The @code{ssfile line 1} line was checked in by 9295 @code{mary} on March 27. Then, on March 28, @code{joe} 9296 added a line @code{ssfile line 2}, without modifying 9297 the @code{ssfile line 1} line. This report doesn't 9298 tell you anything about lines which have been deleted 9299 or replaced; you need to use @code{cvs diff} for that 9300 (@pxref{diff}). 9301 9302 The options to @code{cvs annotate} are listed in 9303 @ref{Invoking CVS}, and can be used to select the files 9304 and revisions to annotate. The options are described 9305 in more detail there and in @ref{Common options}. 9306 9307 @c FIXME: maybe an example using the options? Just 9308 @c what it means to select a revision might be worth a 9309 @c few words of explanation ("you want to see who 9310 @c changed this line *before* 1.4"...). 9311 9312 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9313 @node checkout 9314 @appendixsec checkout---Check out sources for editing 9315 @cindex checkout (subcommand) 9316 @cindex co (subcommand) 9317 9318 @itemize @bullet 9319 @item 9320 Synopsis: checkout [options] modules@dots{} 9321 @item 9322 Requires: repository. 9323 @item 9324 Changes: working directory. 9325 @item 9326 Synonyms: co, get 9327 @end itemize 9328 9329 Create or update a working directory containing copies of the 9330 source files specified by @var{modules}. You must execute 9331 @code{checkout} before using most of the other @sc{cvs} 9332 commands, since most of them operate on your working 9333 directory. 9334 9335 The @var{modules} are either 9336 symbolic names for some 9337 collection of source directories and files, or paths to 9338 directories or files in the repository. The symbolic 9339 names are defined in the @samp{modules} file. 9340 @xref{modules}. 9341 @c Needs an example, particularly of the non-"modules" 9342 @c case but probably of both. 9343 9344 @c FIXME: this seems like a very odd place to introduce 9345 @c people to how CVS works. The bit about unreserved 9346 @c checkouts is also misleading as it depends on how 9347 @c things are set up. 9348 Depending on the modules you specify, @code{checkout} may 9349 recursively create directories and populate them with 9350 the appropriate source files. You can then edit these 9351 source files at any time (regardless of whether other 9352 software developers are editing their own copies of the 9353 sources); update them to include new changes applied by 9354 others to the source repository; or commit your work as 9355 a permanent change to the source repository. 9356 9357 Note that @code{checkout} is used to create 9358 directories. The top-level directory created is always 9359 added to the directory where @code{checkout} is 9360 invoked, and usually has the same name as the specified 9361 module. In the case of a module alias, the created 9362 sub-directory may have a different name, but you can be 9363 sure that it will be a sub-directory, and that 9364 @code{checkout} will show the relative path leading to 9365 each file as it is extracted into your private work 9366 area (unless you specify the @samp{-Q} global option). 9367 9368 The files created by @code{checkout} are created 9369 read-write, unless the @samp{-r} option to @sc{cvs} 9370 (@pxref{Global options}) is specified, the 9371 @code{CVSREAD} environment variable is specified 9372 (@pxref{Environment variables}), or a watch is in 9373 effect for that file (@pxref{Watches}). 9374 9375 Note that running @code{checkout} on a directory that was already 9376 built by a prior @code{checkout} is also permitted. 9377 This is similar to specifying the @samp{-d} option 9378 to the @code{update} command in the sense that new 9379 directories that have been created in the repository 9380 will appear in your work area. 9381 However, @code{checkout} takes a module name whereas 9382 @code{update} takes a directory name. Also 9383 to use @code{checkout} this way it must be run from the 9384 top level directory (where you originally ran 9385 @code{checkout} from), so before you run 9386 @code{checkout} to update an existing directory, don't 9387 forget to change your directory to the top level 9388 directory. 9389 9390 For the output produced by the @code{checkout} command 9391 see @ref{update output}. 9392 9393 @menu 9394 * checkout options:: checkout options 9395 * checkout examples:: checkout examples 9396 @end menu 9397 9398 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9399 @node checkout options 9400 @appendixsubsec checkout options 9401 9402 These standard options are supported by @code{checkout} 9403 (@pxref{Common options}, for a complete description of 9404 them): 9405 9406 @table @code 9407 @item -D @var{date} 9408 Use the most recent revision no later than @var{date}. 9409 This option is sticky, and implies @samp{-P}. See 9410 @ref{Sticky tags}, for more information on sticky tags/dates. 9411 9412 @item -f 9413 Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision is 9414 found, retrieve the most recent revision (instead of ignoring the file). 9415 9416 @item -k @var{kflag} 9417 Process keywords according to @var{kflag}. See 9418 @ref{Keyword substitution}. 9419 This option is sticky; future updates of 9420 this file in this working directory will use the same 9421 @var{kflag}. The @code{status} command can be viewed 9422 to see the sticky options. See @ref{Invoking CVS}, for 9423 more information on the @code{status} command. 9424 9425 @item -l 9426 Local; run only in current working directory. 9427 9428 @item -n 9429 Do not run any checkout program (as specified 9430 with the @samp{-o} option in the modules file; 9431 @pxref{modules}). 9432 9433 @item -P 9434 Prune empty directories. See @ref{Moving directories}. 9435 9436 @item -p 9437 Pipe files to the standard output. 9438 9439 @item -R 9440 Checkout directories recursively. This option is on by default. 9441 9442 @item -r @var{tag}[:@var{date}] 9443 Checkout the revision specified by @var{tag} or, when @var{date} is specified 9444 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9445 existed on @var{date}. This option is sticky, and implies @samp{-P}. 9446 See @ref{Sticky tags}, for more information on sticky tags/dates. Also, 9447 see @ref{Common options}. 9448 @end table 9449 9450 In addition to those, you can use these special command 9451 options with @code{checkout}: 9452 9453 @table @code 9454 @item -A 9455 Reset any sticky tags, dates, or @samp{-k} options. 9456 See @ref{Sticky tags}, for more information on sticky tags/dates. 9457 9458 @item -c 9459 Copy the module file, sorted, to the standard output, 9460 instead of creating or modifying any files or 9461 directories in your working directory. 9462 9463 @item -d @var{dir} 9464 Create a directory called @var{dir} for the working 9465 files, instead of using the module name. In general, 9466 using this flag is equivalent to using @samp{mkdir 9467 @var{dir}; cd @var{dir}} followed by the checkout 9468 command without the @samp{-d} flag. 9469 9470 There is an important exception, however. It is very 9471 convenient when checking out a single item to have the 9472 output appear in a directory that doesn't contain empty 9473 intermediate directories. In this case @emph{only}, 9474 @sc{cvs} tries to ``shorten'' pathnames to avoid those empty 9475 directories. 9476 9477 For example, given a module @samp{foo} that contains 9478 the file @samp{bar.c}, the command @samp{cvs co -d dir 9479 foo} will create directory @samp{dir} and place 9480 @samp{bar.c} inside. Similarly, given a module 9481 @samp{bar} which has subdirectory @samp{baz} wherein 9482 there is a file @samp{quux.c}, the command @samp{cvs co 9483 -d dir bar/baz} will create directory @samp{dir} and 9484 place @samp{quux.c} inside. 9485 9486 Using the @samp{-N} flag will defeat this behavior. 9487 Given the same module definitions above, @samp{cvs co 9488 -N -d dir foo} will create directories @samp{dir/foo} 9489 and place @samp{bar.c} inside, while @samp{cvs co -N -d 9490 dir bar/baz} will create directories @samp{dir/bar/baz} 9491 and place @samp{quux.c} inside. 9492 9493 @item -j @var{tag} 9494 With two @samp{-j} options, merge changes from the 9495 revision specified with the first @samp{-j} option to 9496 the revision specified with the second @samp{j} option, 9497 into the working directory. 9498 9499 With one @samp{-j} option, merge changes from the 9500 ancestor revision to the revision specified with the 9501 @samp{-j} option, into the working directory. The 9502 ancestor revision is the common ancestor of the 9503 revision which the working directory is based on, and 9504 the revision specified in the @samp{-j} option. 9505 9506 In addition, each -j option can contain an optional 9507 date specification which, when used with branches, can 9508 limit the chosen revision to one within a specific 9509 date. An optional date is specified by adding a colon 9510 (:) to the tag: 9511 @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 9512 9513 @xref{Branching and merging}. 9514 9515 @item -N 9516 Only useful together with @samp{-d @var{dir}}. With 9517 this option, @sc{cvs} will not ``shorten'' module paths 9518 in your working directory when you check out a single 9519 module. See the @samp{-d} flag for examples and a 9520 discussion. 9521 9522 @item -s 9523 Like @samp{-c}, but include the status of all modules, 9524 and sort it by the status string. @xref{modules}, for 9525 info about the @samp{-s} option that is used inside the 9526 modules file to set the module status. 9527 @end table 9528 9529 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9530 @node checkout examples 9531 @appendixsubsec checkout examples 9532 9533 Get a copy of the module @samp{tc}: 9534 9535 @example 9536 $ cvs checkout tc 9537 @end example 9538 9539 Get a copy of the module @samp{tc} as it looked one day 9540 ago: 9541 9542 @example 9543 $ cvs checkout -D yesterday tc 9544 @end example 9545 9546 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9547 @node commit 9548 @appendixsec commit---Check files into the repository 9549 @cindex commit (subcommand) 9550 @cindex ci (subcommand) 9551 9552 @itemize @bullet 9553 @item 9554 Synopsis: commit [-lnRf] [-m 'log_message' | 9555 -F file] [-r revision] [files@dots{}] 9556 @item 9557 Requires: working directory, repository. 9558 @item 9559 Changes: repository. 9560 @item 9561 Synonym: ci 9562 @end itemize 9563 9564 Use @code{commit} when you want to incorporate changes 9565 from your working source files into the source 9566 repository. 9567 9568 If you don't specify particular files to commit, all of 9569 the files in your working current directory are 9570 examined. @code{commit} is careful to change in the 9571 repository only those files that you have really 9572 changed. By default (or if you explicitly specify the 9573 @samp{-R} option), files in subdirectories are also 9574 examined and committed if they have changed; you can 9575 use the @samp{-l} option to limit @code{commit} to the 9576 current directory only. 9577 9578 @code{commit} verifies that the selected files are up 9579 to date with the current revisions in the source 9580 repository; it will notify you, and exit without 9581 committing, if any of the specified files must be made 9582 current first with @code{update} (@pxref{update}). 9583 @code{commit} does not call the @code{update} command 9584 for you, but rather leaves that for you to do when the 9585 time is right. 9586 9587 When all is well, an editor is invoked to allow you to 9588 enter a log message that will be written to one or more 9589 logging programs (@pxref{modules}, and @pxref{loginfo}) 9590 and placed in the @sc{rcs} file inside the 9591 repository. This log message can be retrieved with the 9592 @code{log} command (@pxref{log & rlog}). You can specify the 9593 log message on the command line with the @samp{-m 9594 @var{message}} option, and thus avoid the editor invocation, 9595 or use the @samp{-F @var{file}} option to specify 9596 that the argument file contains the log message. 9597 9598 At @code{commit}, a unique commitid is placed in the @sc{rcs} 9599 file inside the repository. All files committed at once 9600 get the same commitid. The commitid can be retrieved with 9601 the @code{log} and @code{status} command (@pxref{log & rlog}, 9602 @pxref{File status}). 9603 9604 @menu 9605 * commit options:: commit options 9606 * commit examples:: commit examples 9607 @end menu 9608 9609 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9610 @node commit options 9611 @appendixsubsec commit options 9612 9613 These standard options are supported by @code{commit} 9614 (@pxref{Common options}, for a complete description of 9615 them): 9616 9617 @table @code 9618 @item -l 9619 Local; run only in current working directory. 9620 9621 @item -R 9622 Commit directories recursively. This is on by default. 9623 9624 @item -r @var{revision} 9625 Commit to @var{revision}. @var{revision} must be 9626 either a branch, or a revision on the main trunk that 9627 is higher than any existing revision number 9628 (@pxref{Assigning revisions}). You 9629 cannot commit to a specific revision on a branch. 9630 @c FIXME: Need xref for branch case. 9631 @end table 9632 9633 @code{commit} also supports these options: 9634 9635 @table @code 9636 @item -c 9637 Refuse to commit files unless the user has registered a valid edit on the 9638 file via @code{cvs edit}. This is most useful when @samp{commit -c} 9639 and @samp{edit -c} have been placed in all @file{.cvsrc} files. 9640 A commit can be forced anyways by either registering an edit retroactively 9641 via @code{cvs edit} (no changes to the file will be lost) or using the 9642 @code{-f} option to commit. Support for @code{commit -c} requires both 9643 client and a server versions 1.12.10 or greater. 9644 9645 @item -F @var{file} 9646 Read the log message from @var{file}, instead 9647 of invoking an editor. 9648 9649 @item -f 9650 Note that this is not the standard behavior of 9651 the @samp{-f} option as defined in @ref{Common options}. 9652 9653 Force @sc{cvs} to commit a new revision even if you haven't 9654 made any changes to the file. As of @sc{cvs} version 1.12.10, 9655 it also causes the @code{-c} option to be ignored. If the current revision 9656 of @var{file} is 1.7, then the following two commands 9657 are equivalent: 9658 9659 @example 9660 $ cvs commit -f @var{file} 9661 $ cvs commit -r 1.8 @var{file} 9662 @end example 9663 9664 @c This is odd, but it's how CVS has worked for some 9665 @c time. 9666 The @samp{-f} option disables recursion (i.e., it 9667 implies @samp{-l}). To force @sc{cvs} to commit a new 9668 revision for all files in all subdirectories, you must 9669 use @samp{-f -R}. 9670 9671 @item -m @var{message} 9672 Use @var{message} as the log message, instead of 9673 invoking an editor. 9674 @end table 9675 9676 @need 2000 9677 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9678 @node commit examples 9679 @appendixsubsec commit examples 9680 9681 @c FIXME: this material wants to be somewhere 9682 @c in "Branching and merging". 9683 9684 @appendixsubsubsec Committing to a branch 9685 9686 You can commit to a branch revision (one that has an 9687 even number of dots) with the @samp{-r} option. To 9688 create a branch revision, use the @samp{-b} option 9689 of the @code{rtag} or @code{tag} commands 9690 (@pxref{Branching and merging}). Then, either @code{checkout} or 9691 @code{update} can be used to base your sources on the 9692 newly created branch. From that point on, all 9693 @code{commit} changes made within these working sources 9694 will be automatically added to a branch revision, 9695 thereby not disturbing main-line development in any 9696 way. For example, if you had to create a patch to the 9697 1.2 version of the product, even though the 2.0 version 9698 is already under development, you might do: 9699 9700 @example 9701 $ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 9702 $ cvs checkout -r FCS1_2_Patch product_module 9703 $ cd product_module 9704 [[ hack away ]] 9705 $ cvs commit 9706 @end example 9707 9708 @noindent 9709 This works automatically since the @samp{-r} option is 9710 sticky. 9711 9712 @appendixsubsubsec Creating the branch after editing 9713 9714 Say you have been working on some extremely 9715 experimental software, based on whatever revision you 9716 happened to checkout last week. If others in your 9717 group would like to work on this software with you, but 9718 without disturbing main-line development, you could 9719 commit your change to a new branch. Others can then 9720 checkout your experimental stuff and utilize the full 9721 benefit of @sc{cvs} conflict resolution. The scenario might 9722 look like: 9723 9724 @c FIXME: Should we be recommending tagging the branchpoint? 9725 @example 9726 [[ hacked sources are present ]] 9727 $ cvs tag -b EXPR1 9728 $ cvs update -r EXPR1 9729 $ cvs commit 9730 @end example 9731 9732 The @code{update} command will make the @samp{-r 9733 EXPR1} option sticky on all files. Note that your 9734 changes to the files will never be removed by the 9735 @code{update} command. The @code{commit} will 9736 automatically commit to the correct branch, because the 9737 @samp{-r} is sticky. You could also do like this: 9738 9739 @c FIXME: Should we be recommending tagging the branchpoint? 9740 @example 9741 [[ hacked sources are present ]] 9742 $ cvs tag -b EXPR1 9743 $ cvs commit -r EXPR1 9744 @end example 9745 9746 @noindent 9747 but then, only those files that were changed by you 9748 will have the @samp{-r EXPR1} sticky flag. If you hack 9749 away, and commit without specifying the @samp{-r EXPR1} 9750 flag, some files may accidentally end up on the main 9751 trunk. 9752 9753 To work with you on the experimental change, others 9754 would simply do 9755 9756 @example 9757 $ cvs checkout -r EXPR1 whatever_module 9758 @end example 9759 9760 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9761 @node diff 9762 @appendixsec diff---Show differences between revisions 9763 @cindex diff (subcommand) 9764 9765 @itemize @bullet 9766 @item 9767 Synopsis: diff [-lR] [-k kflag] [format_options] [(-r rev1[:date1] | -D date1) [-r rev2[:date2] | -D date2]] [files@dots{}] 9768 @item 9769 Requires: working directory, repository. 9770 @item 9771 Changes: nothing. 9772 @end itemize 9773 9774 The @code{diff} command is used to compare different 9775 revisions of files. The default action is to compare 9776 your working files with the revisions they were based 9777 on, and report any differences that are found. 9778 9779 If any file names are given, only those files are 9780 compared. If any directories are given, all files 9781 under them will be compared. 9782 9783 The exit status for diff is different than for other 9784 @sc{cvs} commands; for details @ref{Exit status}. 9785 9786 @menu 9787 * diff options:: diff options 9788 * diff examples:: diff examples 9789 @end menu 9790 9791 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9792 @node diff options 9793 @appendixsubsec diff options 9794 9795 These standard options are supported by @code{diff} 9796 (@pxref{Common options}, for a complete description of 9797 them): 9798 9799 @table @code 9800 @item -D @var{date} 9801 Use the most recent revision no later than @var{date}. 9802 See @samp{-r} for how this affects the comparison. 9803 9804 @item -k @var{kflag} 9805 Process keywords according to @var{kflag}. See 9806 @ref{Keyword substitution}. 9807 9808 @item -l 9809 Local; run only in current working directory. 9810 9811 @item -R 9812 Examine directories recursively. This option is on by 9813 default. 9814 9815 @item -r @var{tag}[:@var{date}] 9816 Compare with revision specified by @var{tag} or, when @var{date} is specified 9817 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 9818 existed on @var{date}. Zero, one or two 9819 @samp{-r} options can be present. With no @samp{-r} 9820 option, the working file will be compared with the 9821 revision it was based on. With one @samp{-r}, that 9822 revision will be compared to your current working file. 9823 With two @samp{-r} options those two revisions will be 9824 compared (and your working file will not affect the 9825 outcome in any way). 9826 @c We should be a lot more explicit, with examples, 9827 @c about the difference between "cvs diff" and "cvs 9828 @c diff -r HEAD". This often confuses new users. 9829 9830 One or both @samp{-r} options can be replaced by a 9831 @samp{-D @var{date}} option, described above. 9832 @end table 9833 9834 @c Conceptually, this is a disaster. There are 3 9835 @c zillion diff formats that we support via the diff 9836 @c library. It is not obvious to me that we should 9837 @c document them all. Maybe just the most common ones 9838 @c like -c and -u, and think about phasing out the 9839 @c obscure ones. 9840 @c FIXCVS: also should be a way to specify an external 9841 @c diff program (which can be different for different 9842 @c file types) and pass through 9843 @c arbitrary options, so that the user can do 9844 @c "--pass=-Z --pass=foo" or something even if CVS 9845 @c doesn't know about the "-Z foo" option to diff. 9846 @c This would fit nicely with deprecating/eliminating 9847 @c the obscure options of the diff library, because it 9848 @c would let people specify an external GNU diff if 9849 @c they are into that sort of thing. 9850 The following options specify the format of the 9851 output. They have the same meaning as in GNU diff. 9852 Most options have two equivalent names, one of which is a single letter 9853 preceded by @samp{-}, and the other of which is a long name preceded by 9854 @samp{--}. 9855 9856 @table @samp 9857 @item -@var{lines} 9858 Show @var{lines} (an integer) lines of context. This option does not 9859 specify an output format by itself; it has no effect unless it is 9860 combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9861 operation, @code{patch} typically needs at least two lines of context. 9862 9863 @item -a 9864 Treat all files as text and compare them line-by-line, even if they 9865 do not seem to be text. 9866 9867 @item -b 9868 Ignore trailing white space and consider all other sequences of one or 9869 more white space characters to be equivalent. 9870 9871 @item -B 9872 Ignore changes that just insert or delete blank lines. 9873 9874 @item --binary 9875 Read and write data in binary mode. 9876 9877 @item --brief 9878 Report only whether the files differ, not the details of the 9879 differences. 9880 9881 @item -c 9882 Use the context output format. 9883 9884 @item -C @var{lines} 9885 @itemx --context@r{[}=@var{lines}@r{]} 9886 Use the context output format, showing @var{lines} (an integer) lines of 9887 context, or three if @var{lines} is not given. 9888 For proper operation, @code{patch} typically needs at least two lines of 9889 context. 9890 9891 @item --changed-group-format=@var{format} 9892 Use @var{format} to output a line group containing differing lines from 9893 both files in if-then-else format. @xref{Line group formats}. 9894 9895 @item -d 9896 Change the algorithm to perhaps find a smaller set of changes. This makes 9897 @code{diff} slower (sometimes much slower). 9898 9899 @item -e 9900 @itemx --ed 9901 Make output that is a valid @code{ed} script. 9902 9903 @item --expand-tabs 9904 Expand tabs to spaces in the output, to preserve the alignment of tabs 9905 in the input files. 9906 9907 @item -f 9908 Make output that looks vaguely like an @code{ed} script but has changes 9909 in the order they appear in the file. 9910 9911 @item -F @var{regexp} 9912 In context and unified format, for each hunk of differences, show some 9913 of the last preceding line that matches @var{regexp}. 9914 9915 @item --forward-ed 9916 Make output that looks vaguely like an @code{ed} script but has changes 9917 in the order they appear in the file. 9918 9919 @item -H 9920 Use heuristics to speed handling of large files that have numerous 9921 scattered small changes. 9922 9923 @item --horizon-lines=@var{lines} 9924 Do not discard the last @var{lines} lines of the common prefix 9925 and the first @var{lines} lines of the common suffix. 9926 9927 @item -i 9928 Ignore changes in case; consider upper- and lower-case letters 9929 equivalent. 9930 9931 @item -I @var{regexp} 9932 Ignore changes that just insert or delete lines that match @var{regexp}. 9933 9934 @item --ifdef=@var{name} 9935 Make merged if-then-else output using @var{name}. 9936 9937 @item --ignore-all-space 9938 Ignore white space when comparing lines. 9939 9940 @item --ignore-blank-lines 9941 Ignore changes that just insert or delete blank lines. 9942 9943 @item --ignore-case 9944 Ignore changes in case; consider upper- and lower-case to be the same. 9945 9946 @item --ignore-matching-lines=@var{regexp} 9947 Ignore changes that just insert or delete lines that match @var{regexp}. 9948 9949 @item --ignore-space-change 9950 Ignore trailing white space and consider all other sequences of one or 9951 more white space characters to be equivalent. 9952 9953 @item --initial-tab 9954 Output a tab rather than a space before the text of a line in normal or 9955 context format. This causes the alignment of tabs in the line to look 9956 normal. 9957 9958 @item -L @var{label} 9959 Use @var{label} instead of the file name in the context format 9960 and unified format headers. 9961 9962 @item --label=@var{label} 9963 Use @var{label} instead of the file name in the context format 9964 and unified format headers. 9965 9966 @item --left-column 9967 Print only the left column of two common lines in side by side format. 9968 9969 @item --line-format=@var{format} 9970 Use @var{format} to output all input lines in if-then-else format. 9971 @xref{Line formats}. 9972 9973 @item --minimal 9974 Change the algorithm to perhaps find a smaller set of changes. This 9975 makes @code{diff} slower (sometimes much slower). 9976 9977 @item -n 9978 Output RCS-format diffs; like @samp{-f} except that each command 9979 specifies the number of lines affected. 9980 9981 @item -N 9982 @itemx --new-file 9983 In directory comparison, if a file is found in only one directory, 9984 treat it as present but empty in the other directory. 9985 9986 @item --new-group-format=@var{format} 9987 Use @var{format} to output a group of lines taken from just the second 9988 file in if-then-else format. @xref{Line group formats}. 9989 9990 @item --new-line-format=@var{format} 9991 Use @var{format} to output a line taken from just the second file in 9992 if-then-else format. @xref{Line formats}. 9993 9994 @item --old-group-format=@var{format} 9995 Use @var{format} to output a group of lines taken from just the first 9996 file in if-then-else format. @xref{Line group formats}. 9997 9998 @item --old-line-format=@var{format} 9999 Use @var{format} to output a line taken from just the first file in 10000 if-then-else format. @xref{Line formats}. 10001 10002 @item -p 10003 Show which C function each change is in. 10004 10005 @item --rcs 10006 Output RCS-format diffs; like @samp{-f} except that each command 10007 specifies the number of lines affected. 10008 10009 @item --report-identical-files 10010 @itemx -s 10011 Report when two files are the same. 10012 10013 @item --show-c-function 10014 Show which C function each change is in. 10015 10016 @item --show-function-line=@var{regexp} 10017 In context and unified format, for each hunk of differences, show some 10018 of the last preceding line that matches @var{regexp}. 10019 10020 @item --side-by-side 10021 Use the side by side output format. 10022 10023 @item --speed-large-files 10024 Use heuristics to speed handling of large files that have numerous 10025 scattered small changes. 10026 10027 @item --suppress-common-lines 10028 Do not print common lines in side by side format. 10029 10030 @item -t 10031 Expand tabs to spaces in the output, to preserve the alignment of tabs 10032 in the input files. 10033 10034 @item -T 10035 Output a tab rather than a space before the text of a line in normal or 10036 context format. This causes the alignment of tabs in the line to look 10037 normal. 10038 10039 @item --text 10040 Treat all files as text and compare them line-by-line, even if they 10041 do not appear to be text. 10042 10043 @item -u 10044 Use the unified output format. 10045 10046 @item --unchanged-group-format=@var{format} 10047 Use @var{format} to output a group of common lines taken from both files 10048 in if-then-else format. @xref{Line group formats}. 10049 10050 @item --unchanged-line-format=@var{format} 10051 Use @var{format} to output a line common to both files in if-then-else 10052 format. @xref{Line formats}. 10053 10054 @item -U @var{lines} 10055 @itemx --unified@r{[}=@var{lines}@r{]} 10056 Use the unified output format, showing @var{lines} (an integer) lines of 10057 context, or three if @var{lines} is not given. 10058 For proper operation, @code{patch} typically needs at least two lines of 10059 context. 10060 10061 @item -w 10062 Ignore white space when comparing lines. 10063 10064 @item -W @var{columns} 10065 @itemx --width=@var{columns} 10066 Use an output width of @var{columns} in side by side format. 10067 10068 @item -y 10069 Use the side by side output format. 10070 @end table 10071 10072 @menu 10073 * Line group formats:: Line group formats 10074 * Line formats:: Line formats 10075 @end menu 10076 10077 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10078 @node Line group formats 10079 @appendixsubsubsec Line group formats 10080 10081 Line group formats let you specify formats suitable for many 10082 applications that allow if-then-else input, including programming 10083 languages and text formatting languages. A line group format specifies 10084 the output format for a contiguous group of similar lines. 10085 10086 For example, the following command compares the TeX file @file{myfile} 10087 with the original version from the repository, 10088 and outputs a merged file in which old regions are 10089 surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 10090 regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 10091 10092 @example 10093 cvs diff \ 10094 --old-group-format='\begin@{em@} 10095 %<\end@{em@} 10096 ' \ 10097 --new-group-format='\begin@{bf@} 10098 %>\end@{bf@} 10099 ' \ 10100 myfile 10101 @end example 10102 10103 The following command is equivalent to the above example, but it is a 10104 little more verbose, because it spells out the default line group formats. 10105 10106 @example 10107 cvs diff \ 10108 --old-group-format='\begin@{em@} 10109 %<\end@{em@} 10110 ' \ 10111 --new-group-format='\begin@{bf@} 10112 %>\end@{bf@} 10113 ' \ 10114 --unchanged-group-format='%=' \ 10115 --changed-group-format='\begin@{em@} 10116 %<\end@{em@} 10117 \begin@{bf@} 10118 %>\end@{bf@} 10119 ' \ 10120 myfile 10121 @end example 10122 10123 Here is a more advanced example, which outputs a diff listing with 10124 headers containing line numbers in a ``plain English'' style. 10125 10126 @example 10127 cvs diff \ 10128 --unchanged-group-format='' \ 10129 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 10130 %<' \ 10131 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 10132 %>' \ 10133 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 10134 %<-------- to: 10135 %>' \ 10136 myfile 10137 @end example 10138 10139 To specify a line group format, use one of the options 10140 listed below. You can specify up to four line group formats, one for 10141 each kind of line group. You should quote @var{format}, because it 10142 typically contains shell metacharacters. 10143 10144 @table @samp 10145 @item --old-group-format=@var{format} 10146 These line groups are hunks containing only lines from the first file. 10147 The default old group format is the same as the changed group format if 10148 it is specified; otherwise it is a format that outputs the line group as-is. 10149 10150 @item --new-group-format=@var{format} 10151 These line groups are hunks containing only lines from the second 10152 file. The default new group format is same as the changed group 10153 format if it is specified; otherwise it is a format that outputs the 10154 line group as-is. 10155 10156 @item --changed-group-format=@var{format} 10157 These line groups are hunks containing lines from both files. The 10158 default changed group format is the concatenation of the old and new 10159 group formats. 10160 10161 @item --unchanged-group-format=@var{format} 10162 These line groups contain lines common to both files. The default 10163 unchanged group format is a format that outputs the line group as-is. 10164 @end table 10165 10166 In a line group format, ordinary characters represent themselves; 10167 conversion specifications start with @samp{%} and have one of the 10168 following forms. 10169 10170 @table @samp 10171 @item %< 10172 stands for the lines from the first file, including the trailing newline. 10173 Each line is formatted according to the old line format (@pxref{Line formats}). 10174 10175 @item %> 10176 stands for the lines from the second file, including the trailing newline. 10177 Each line is formatted according to the new line format. 10178 10179 @item %= 10180 stands for the lines common to both files, including the trailing newline. 10181 Each line is formatted according to the unchanged line format. 10182 10183 @item %% 10184 stands for @samp{%}. 10185 10186 @item %c'@var{C}' 10187 where @var{C} is a single character, stands for @var{C}. 10188 @var{C} may not be a backslash or an apostrophe. 10189 For example, @samp{%c':'} stands for a colon, even inside 10190 the then-part of an if-then-else format, which a colon would 10191 normally terminate. 10192 10193 @item %c'\@var{O}' 10194 where @var{O} is a string of 1, 2, or 3 octal digits, 10195 stands for the character with octal code @var{O}. 10196 For example, @samp{%c'\0'} stands for a null character. 10197 10198 @item @var{F}@var{n} 10199 where @var{F} is a @code{printf} conversion specification and @var{n} is one 10200 of the following letters, stands for @var{n}'s value formatted with @var{F}. 10201 10202 @table @samp 10203 @item e 10204 The line number of the line just before the group in the old file. 10205 10206 @item f 10207 The line number of the first line in the group in the old file; 10208 equals @var{e} + 1. 10209 10210 @item l 10211 The line number of the last line in the group in the old file. 10212 10213 @item m 10214 The line number of the line just after the group in the old file; 10215 equals @var{l} + 1. 10216 10217 @item n 10218 The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 10219 10220 @item E, F, L, M, N 10221 Likewise, for lines in the new file. 10222 10223 @end table 10224 10225 The @code{printf} conversion specification can be @samp{%d}, 10226 @samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 10227 lower case hexadecimal, or upper case hexadecimal output 10228 respectively. After the @samp{%} the following options can appear in 10229 sequence: a @samp{-} specifying left-justification; an integer 10230 specifying the minimum field width; and a period followed by an 10231 optional integer specifying the minimum number of digits. 10232 For example, @samp{%5dN} prints the number of new lines in the group 10233 in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 10234 10235 @item (@var{A}=@var{B}?@var{T}:@var{E}) 10236 If @var{A} equals @var{B} then @var{T} else @var{E}. 10237 @var{A} and @var{B} are each either a decimal constant 10238 or a single letter interpreted as above. 10239 This format spec is equivalent to @var{T} if 10240 @var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 10241 10242 For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 10243 @samp{no lines} if @var{N} (the number of lines in the group in the 10244 new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 10245 otherwise. 10246 @end table 10247 10248 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10249 @node Line formats 10250 @appendixsubsubsec Line formats 10251 10252 Line formats control how each line taken from an input file is 10253 output as part of a line group in if-then-else format. 10254 10255 For example, the following command outputs text with a one-column 10256 change indicator to the left of the text. The first column of output 10257 is @samp{-} for deleted lines, @samp{|} for added lines, and a space 10258 for unchanged lines. The formats contain newline characters where 10259 newlines are desired on output. 10260 10261 @example 10262 cvs diff \ 10263 --old-line-format='-%l 10264 ' \ 10265 --new-line-format='|%l 10266 ' \ 10267 --unchanged-line-format=' %l 10268 ' \ 10269 myfile 10270 @end example 10271 10272 To specify a line format, use one of the following options. You should 10273 quote @var{format}, since it often contains shell metacharacters. 10274 10275 @table @samp 10276 @item --old-line-format=@var{format} 10277 formats lines just from the first file. 10278 10279 @item --new-line-format=@var{format} 10280 formats lines just from the second file. 10281 10282 @item --unchanged-line-format=@var{format} 10283 formats lines common to both files. 10284 10285 @item --line-format=@var{format} 10286 formats all lines; in effect, it sets all three above options simultaneously. 10287 @end table 10288 10289 In a line format, ordinary characters represent themselves; 10290 conversion specifications start with @samp{%} and have one of the 10291 following forms. 10292 10293 @table @samp 10294 @item %l 10295 stands for the contents of the line, not counting its trailing 10296 newline (if any). This format ignores whether the line is incomplete. 10297 10298 @item %L 10299 stands for the contents of the line, including its trailing newline 10300 (if any). If a line is incomplete, this format preserves its 10301 incompleteness. 10302 10303 @item %% 10304 stands for @samp{%}. 10305 10306 @item %c'@var{C}' 10307 where @var{C} is a single character, stands for @var{C}. 10308 @var{C} may not be a backslash or an apostrophe. 10309 For example, @samp{%c':'} stands for a colon. 10310 10311 @item %c'\@var{O}' 10312 where @var{O} is a string of 1, 2, or 3 octal digits, 10313 stands for the character with octal code @var{O}. 10314 For example, @samp{%c'\0'} stands for a null character. 10315 10316 @item @var{F}n 10317 where @var{F} is a @code{printf} conversion specification, 10318 stands for the line number formatted with @var{F}. 10319 For example, @samp{%.5dn} prints the line number using the 10320 @code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 10321 more about printf conversion specifications. 10322 10323 @end table 10324 10325 The default line format is @samp{%l} followed by a newline character. 10326 10327 If the input contains tab characters and it is important that they line 10328 up on output, you should ensure that @samp{%l} or @samp{%L} in a line 10329 format is just after a tab stop (e.g.@: by preceding @samp{%l} or 10330 @samp{%L} with a tab character), or you should use the @samp{-t} or 10331 @samp{--expand-tabs} option. 10332 10333 Taken together, the line and line group formats let you specify many 10334 different formats. For example, the following command uses a format 10335 similar to @code{diff}'s normal format. You can tailor this command 10336 to get fine control over @code{diff}'s output. 10337 10338 @example 10339 cvs diff \ 10340 --old-line-format='< %l 10341 ' \ 10342 --new-line-format='> %l 10343 ' \ 10344 --old-group-format='%df%(f=l?:,%dl)d%dE 10345 %<' \ 10346 --new-group-format='%dea%dF%(F=L?:,%dL) 10347 %>' \ 10348 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 10349 %<--- 10350 %>' \ 10351 --unchanged-group-format='' \ 10352 myfile 10353 @end example 10354 10355 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10356 @node diff examples 10357 @appendixsubsec diff examples 10358 10359 The following line produces a Unidiff (@samp{-u} flag) 10360 between revision 1.14 and 1.19 of 10361 @file{backend.c}. Due to the @samp{-kk} flag no 10362 keywords are substituted, so differences that only depend 10363 on keyword substitution are ignored. 10364 10365 @example 10366 $ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 10367 @end example 10368 10369 Suppose the experimental branch EXPR1 was based on a 10370 set of files tagged RELEASE_1_0. To see what has 10371 happened on that branch, the following can be used: 10372 10373 @example 10374 $ cvs diff -r RELEASE_1_0 -r EXPR1 10375 @end example 10376 10377 A command like this can be used to produce a context 10378 diff between two releases: 10379 10380 @example 10381 $ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 10382 @end example 10383 10384 If you are maintaining ChangeLogs, a command like the following 10385 just before you commit your changes may help you write 10386 the ChangeLog entry. All local modifications that have 10387 not yet been committed will be printed. 10388 10389 @example 10390 $ cvs diff -u | less 10391 @end example 10392 10393 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10394 @node export 10395 @appendixsec export---Export sources from CVS, similar to checkout 10396 @cindex export (subcommand) 10397 10398 @itemize @bullet 10399 @item 10400 Synopsis: export [-flNnR] (-r rev[:date] | -D date) [-k subst] [-d dir] module@dots{} 10401 @item 10402 Requires: repository. 10403 @item 10404 Changes: current directory. 10405 @end itemize 10406 10407 This command is a variant of @code{checkout}; use it 10408 when you want a copy of the source for module without 10409 the @sc{cvs} administrative directories. For example, you 10410 might use @code{export} to prepare source for shipment 10411 off-site. This command requires that you specify a 10412 date or tag (with @samp{-D} or @samp{-r}), so that you 10413 can count on reproducing the source you ship to others 10414 (and thus it always prunes empty directories). 10415 10416 One often would like to use @samp{-kv} with @code{cvs 10417 export}. This causes any keywords to be 10418 expanded such that an import done at some other site 10419 will not lose the keyword revision information. But be 10420 aware that doesn't handle an export containing binary 10421 files correctly. Also be aware that after having used 10422 @samp{-kv}, one can no longer use the @code{ident} 10423 command (which is part of the @sc{rcs} suite---see 10424 ident(1)) which looks for keyword strings. If 10425 you want to be able to use @code{ident} you must not 10426 use @samp{-kv}. 10427 10428 @menu 10429 * export options:: export options 10430 @end menu 10431 10432 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10433 @node export options 10434 @appendixsubsec export options 10435 10436 These standard options are supported by @code{export} 10437 (@pxref{Common options}, for a complete description of 10438 them): 10439 10440 @table @code 10441 @item -D @var{date} 10442 Use the most recent revision no later than @var{date}. 10443 10444 @item -f 10445 If no matching revision is found, retrieve the most 10446 recent revision (instead of ignoring the file). 10447 10448 @item -l 10449 Local; run only in current working directory. 10450 10451 @item -n 10452 Do not run any checkout program. 10453 10454 @item -R 10455 Export directories recursively. This is on by default. 10456 10457 @item -r @var{tag}[:@var{date}] 10458 Export the revision specified by @var{tag} or, when @var{date} is specified 10459 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 10460 existed on @var{date}. See @ref{Common options}. 10461 @end table 10462 10463 In addition, these options (that are common to 10464 @code{checkout} and @code{export}) are also supported: 10465 10466 @table @code 10467 @item -d @var{dir} 10468 Create a directory called @var{dir} for the working 10469 files, instead of using the module name. 10470 @xref{checkout options}, for complete details on how 10471 @sc{cvs} handles this flag. 10472 10473 @item -k @var{subst} 10474 Set keyword expansion mode (@pxref{Substitution modes}). 10475 10476 @item -N 10477 Only useful together with @samp{-d @var{dir}}. 10478 @xref{checkout options}, for complete details on how 10479 @sc{cvs} handles this flag. 10480 @end table 10481 10482 @ignore 10483 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10484 @c @node export examples 10485 @appendixsubsec export examples 10486 10487 Contributed examples are gratefully accepted. 10488 @c -- Examples here!! 10489 @end ignore 10490 10491 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10492 @node history 10493 @appendixsec history---Show status of files and users 10494 @cindex history (subcommand) 10495 10496 @itemize @bullet 10497 @item 10498 Synopsis: history [-report] [-flags] [-options args] [files@dots{}] 10499 @item 10500 Requires: the file @file{$CVSROOT/CVSROOT/history} 10501 @item 10502 Changes: nothing. 10503 @end itemize 10504 10505 @sc{cvs} can keep a history log that tracks each use of most @sc{cvs} 10506 commands. You can use @code{history} to display this information in 10507 various formats. 10508 10509 To enable logging, the @samp{LogHistory} config option must be set to 10510 some value other than the empty string and the history file specified by 10511 the @samp{HistoryLogPath} option must be writable by all users who may run 10512 the @sc{cvs} executable (@pxref{config}). 10513 10514 To enable the @code{history} command, logging must be enabled as above and 10515 the @samp{HistorySearchPath} config option (@pxref{config}) must be set to 10516 specify some number of the history logs created thereby and these files must 10517 be readable by each user who might run the @code{history} command. 10518 10519 Creating a repository via the @code{cvs init} command will enable logging of 10520 all possible events to a single history log file 10521 (@file{$CVSROOT/CVSROOT/history}) with read and write permissions for all 10522 users (@pxref{Creating a repository}). 10523 10524 @strong{Note: @code{history} uses @samp{-f}, @samp{-l}, 10525 @samp{-n}, and @samp{-p} in ways that conflict with the 10526 normal use inside @sc{cvs} (@pxref{Common options}).} 10527 10528 @menu 10529 * history options:: history options 10530 @end menu 10531 10532 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10533 @node history options 10534 @appendixsubsec history options 10535 10536 Several options (shown above as @samp{-report}) control what 10537 kind of report is generated: 10538 10539 @table @code 10540 @item -c 10541 Report on each time commit was used (i.e., each time 10542 the repository was modified). 10543 10544 @item -e 10545 Everything (all record types). Equivalent to 10546 specifying @samp{-x} with all record types. Of course, 10547 @samp{-e} will also include record types which are 10548 added in a future version of @sc{cvs}; if you are 10549 writing a script which can only handle certain record 10550 types, you'll want to specify @samp{-x}. 10551 10552 @item -m @var{module} 10553 Report on a particular module. (You can meaningfully 10554 use @samp{-m} more than once on the command line.) 10555 10556 @item -o 10557 Report on checked-out modules. This is the default report type. 10558 10559 @item -T 10560 Report on all tags. 10561 10562 @item -x @var{type} 10563 Extract a particular set of record types @var{type} from the @sc{cvs} 10564 history. The types are indicated by single letters, 10565 which you may specify in combination. 10566 10567 Certain commands have a single record type: 10568 10569 @table @code 10570 @item F 10571 release 10572 @item O 10573 checkout 10574 @item E 10575 export 10576 @item T 10577 tag and rtag 10578 @end table 10579 10580 @noindent 10581 One of five record types may result from an update: 10582 10583 @table @code 10584 @item C 10585 A merge was necessary but collisions were 10586 detected (requiring manual merging). 10587 @item G 10588 A merge was necessary and it succeeded. 10589 @item U 10590 A working file was copied from the repository. 10591 @item P 10592 A working file was patched to match the repository. 10593 @item W 10594 The working copy of a file was deleted during 10595 update (because it was gone from the repository). 10596 @end table 10597 10598 @noindent 10599 One of three record types results from commit: 10600 10601 @table @code 10602 @item A 10603 A file was added for the first time. 10604 @item M 10605 A file was modified. 10606 @item R 10607 A file was removed. 10608 @end table 10609 10610 @noindent 10611 One record type results from the admin command: 10612 @table @code 10613 @item X 10614 The admin command. 10615 @end table 10616 @end table 10617 10618 The options shown as @samp{-flags} constrain or expand 10619 the report without requiring option arguments: 10620 10621 @table @code 10622 @item -a 10623 Show data for all users (the default is to show data 10624 only for the user executing @code{history}). 10625 10626 @item -l 10627 Show last modification only. 10628 10629 @item -w 10630 Show only the records for modifications done from the 10631 same working directory where @code{history} is 10632 executing. 10633 @end table 10634 10635 The options shown as @samp{-options @var{args}} constrain the report 10636 based on an argument: 10637 10638 @table @code 10639 @item -b @var{str} 10640 Show data back to a record containing the string 10641 @var{str} in either the module name, the file name, or 10642 the repository path. 10643 10644 @item -D @var{date} 10645 Show data since @var{date}. This is slightly different 10646 from the normal use of @samp{-D @var{date}}, which 10647 selects the newest revision older than @var{date}. 10648 10649 @item -f @var{file} 10650 Show data for a particular file 10651 (you can specify several @samp{-f} options on the same command line). 10652 This is equivalent to specifying the file on the command line. 10653 10654 @item -n @var{module} 10655 Show data for a particular module 10656 (you can specify several @samp{-n} options on the same command line). 10657 10658 @item -p @var{repository} 10659 Show data for a particular source repository (you 10660 can specify several @samp{-p} options on the same command 10661 line). 10662 10663 @item -r @var{rev} 10664 Show records referring to revisions since the revision 10665 or tag named @var{rev} appears in individual @sc{rcs} 10666 files. Each @sc{rcs} file is searched for the revision or 10667 tag. 10668 10669 @item -t @var{tag} 10670 Show records since tag @var{tag} was last added to the 10671 history file. This differs from the @samp{-r} flag 10672 above in that it reads only the history file, not the 10673 @sc{rcs} files, and is much faster. 10674 10675 @item -u @var{name} 10676 Show records for user @var{name}. 10677 10678 @item -z @var{timezone} 10679 Show times in the selected records using the specified 10680 time zone instead of UTC. 10681 @end table 10682 10683 @ignore 10684 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10685 @c @node history examples 10686 @appendixsubsec history examples 10687 10688 Contributed examples will gratefully be accepted. 10689 @c -- Examples here! 10690 @end ignore 10691 10692 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10693 @node import 10694 @appendixsec import---Import sources into CVS, using vendor branches 10695 @cindex import (subcommand) 10696 10697 @c FIXME: This node is way too long for one which has subnodes. 10698 10699 @itemize @bullet 10700 @item 10701 Synopsis: import [-options] repository vendortag releasetag@dots{} 10702 @item 10703 Requires: Repository, source distribution directory. 10704 @item 10705 Changes: repository. 10706 @end itemize 10707 10708 Use @code{import} to incorporate an entire source 10709 distribution from an outside source (e.g., a source 10710 vendor) into your source repository directory. You can 10711 use this command both for initial creation of a 10712 repository, and for wholesale updates to the module 10713 from the outside source. @xref{Tracking sources}, for 10714 a discussion on this subject. 10715 10716 The @var{repository} argument gives a directory name 10717 (or a path to a directory) under the @sc{cvs} root directory 10718 for repositories; if the directory did not exist, 10719 import creates it. 10720 10721 When you use import for updates to source that has been 10722 modified in your source repository (since a prior 10723 import), it will notify you of any files that conflict 10724 in the two branches of development; use @samp{checkout 10725 -j} to reconcile the differences, as import instructs 10726 you to do. 10727 10728 If @sc{cvs} decides a file should be ignored 10729 (@pxref{cvsignore}), it does not import it and prints 10730 @samp{I } followed by the filename (@pxref{import output}, for a 10731 complete description of the output). 10732 10733 If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 10734 any file whose names match the specifications in that 10735 file will be treated as packages and the appropriate 10736 filtering will be performed on the file/directory 10737 before being imported. @xref{Wrappers}. 10738 10739 The outside source is saved in a first-level 10740 branch, by default 1.1.1. Updates are leaves of this 10741 branch; for example, files from the first imported 10742 collection of source will be revision 1.1.1.1, then 10743 files from the first imported update will be revision 10744 1.1.1.2, and so on. 10745 10746 At least three arguments are required. 10747 @var{repository} is needed to identify the collection 10748 of source. @var{vendortag} is a tag for the entire 10749 branch (e.g., for 1.1.1). You must also specify at 10750 least one @var{releasetag} to uniquely identify the files at 10751 the leaves created each time you execute @code{import}. The 10752 @var{releasetag} should be new, not previously existing in the 10753 repository file, and uniquely identify the imported release, 10754 10755 @c I'm not completely sure this belongs here. But 10756 @c we need to say it _somewhere_ reasonably obvious; it 10757 @c is a common misconception among people first learning CVS 10758 Note that @code{import} does @emph{not} change the 10759 directory in which you invoke it. In particular, it 10760 does not set up that directory as a @sc{cvs} working 10761 directory; if you want to work with the sources import 10762 them first and then check them out into a different 10763 directory (@pxref{Getting the source}). 10764 10765 @menu 10766 * import options:: import options 10767 * import output:: import output 10768 * import examples:: import examples 10769 @end menu 10770 10771 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10772 @node import options 10773 @appendixsubsec import options 10774 10775 This standard option is supported by @code{import} 10776 (@pxref{Common options}, for a complete description): 10777 10778 @table @code 10779 @item -m @var{message} 10780 Use @var{message} as log information, instead of 10781 invoking an editor. 10782 @end table 10783 10784 There are the following additional special options. 10785 10786 @table @code 10787 @item -b @var{branch} 10788 See @ref{Multiple vendor branches}. 10789 10790 @item -k @var{subst} 10791 Indicate the keyword expansion mode desired. This 10792 setting will apply to all files created during the 10793 import, but not to any files that previously existed in 10794 the repository. See @ref{Substitution modes}, for a 10795 list of valid @samp{-k} settings. 10796 10797 @item -I @var{name} 10798 Specify file names that should be ignored during 10799 import. You can use this option repeatedly. To avoid 10800 ignoring any files at all (even those ignored by 10801 default), specify `-I !'. 10802 10803 @var{name} can be a file name pattern of the same type 10804 that you can specify in the @file{.cvsignore} file. 10805 @xref{cvsignore}. 10806 @c -- Is this really true? 10807 10808 @item -W @var{spec} 10809 Specify file names that should be filtered during 10810 import. You can use this option repeatedly. 10811 10812 @var{spec} can be a file name pattern of the same type 10813 that you can specify in the @file{.cvswrappers} 10814 file. @xref{Wrappers}. 10815 10816 @item -X 10817 Modify the algorithm used by @sc{cvs} when importing new files 10818 so that new files do not immediately appear on the main trunk. 10819 10820 Specifically, this flag causes @sc{cvs} to mark new files as 10821 if they were deleted on the main trunk, by taking the following 10822 steps for each file in addition to those normally taken on import: 10823 creating a new revision on the main trunk indicating that 10824 the new file is @code{dead}, resetting the new file's default branch, 10825 and placing the file in the Attic (@pxref{Attic}) directory. 10826 10827 Use of this option can be forced on a repository-wide basis 10828 by setting the @samp{ImportNewFilesToVendorBranchOnly} option in 10829 CVSROOT/config (@pxref{config}). 10830 @end table 10831 10832 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10833 @node import output 10834 @appendixsubsec import output 10835 10836 @code{import} keeps you informed of its progress by printing a line 10837 for each file, preceded by one character indicating the status of the file: 10838 10839 @table @code 10840 @item U @var{file} 10841 The file already exists in the repository and has not been locally 10842 modified; a new revision has been created (if necessary). 10843 10844 @item N @var{file} 10845 The file is a new file which has been added to the repository. 10846 10847 @item C @var{file} 10848 The file already exists in the repository but has been locally modified; 10849 you will have to merge the changes. 10850 10851 @item I @var{file} 10852 The file is being ignored (@pxref{cvsignore}). 10853 10854 @cindex Symbolic link, importing 10855 @cindex Link, symbolic, importing 10856 @c FIXME: also (somewhere else) probably 10857 @c should be documenting what happens if you "cvs add" 10858 @c a symbolic link. Also maybe what happens if 10859 @c you manually create symbolic links within the 10860 @c repository (? - not sure why we'd want to suggest 10861 @c doing that). 10862 @item L @var{file} 10863 The file is a symbolic link; @code{cvs import} ignores symbolic links. 10864 People periodically suggest that this behavior should 10865 be changed, but if there is a consensus on what it 10866 should be changed to, it is not apparent. 10867 (Various options in the @file{modules} file can be used 10868 to recreate symbolic links on checkout, update, etc.; 10869 @pxref{modules}.) 10870 @end table 10871 10872 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10873 @node import examples 10874 @appendixsubsec import examples 10875 10876 See @ref{Tracking sources}, and @ref{From files}. 10877 10878 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10879 @node init 10880 @appendixsec init---Initialize a repository 10881 @cindex init (subcommand) 10882 10883 @itemize @bullet 10884 @item 10885 Synopsis: init 10886 @item 10887 Requires: working directory. 10888 @item 10889 Changes: repository, working directory. 10890 @end itemize 10891 10892 The @code{init} command initializes a repository by adding the 10893 @file{CVSROOT} subdirectory and some default control files. You must 10894 use this command or initialize the repository in some other way before 10895 you can use it. Specify the root of the repository with the general 10896 @code{-d} option. This will set up an empty repository in the 10897 @sc{cvs} root specified in the usual way (@pxref{Repository}). 10898 10899 @code{init} is careful to never overwrite any existing files in the 10900 repository, so no harm is done if you run @code{init} on an already 10901 set-up repository. Note you may need to be a member of the group 10902 @code{cvsadmin} to do this. 10903 10904 Note @code{init} will enable history logging; if you don't want that, 10905 remove the history file after running @code{init} (@pxref{history file}). 10906 10907 @menu 10908 * init examples: init examples 10909 @end menu 10910 10911 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10912 @node init examples 10913 @appendixsubsec init examples 10914 10915 @example 10916 $ cvs -d /usr/local/cvsroot init 10917 @end example 10918 10919 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10920 @node log & rlog 10921 @appendixsec log & rlog---Print out log information for files 10922 @cindex log (subcommand) 10923 @cindex rlog (subcommand) 10924 10925 @itemize @bullet 10926 @item 10927 Synopsis: log [options] [files@dots{}] 10928 @item 10929 Requires: repository, working directory. 10930 @item 10931 Changes: nothing. 10932 @end itemize 10933 10934 Display log information for files. @code{log} used to 10935 call the @sc{rcs} utility @code{rlog}. Although this 10936 is no longer true in the current sources, this history 10937 determines the format of the output and the options, 10938 which are not quite in the style of the other @sc{cvs} 10939 commands. 10940 10941 @cindex Timezone, in output 10942 @cindex Zone, time, in output 10943 The output includes the location of the @sc{rcs} file, 10944 the @dfn{head} revision (the latest revision on the 10945 trunk), all symbolic names (tags) and some other 10946 things. For each revision, the revision number, the 10947 date, the author, the number of lines added/deleted, the commitid 10948 and the log message are printed. All dates are displayed 10949 in local time at the client. This is typically specified in 10950 the @code{$TZ} environment variable, which can be set to 10951 govern how @code{log} displays dates. 10952 10953 @strong{Note: @code{log} uses @samp{-R} in a way that conflicts 10954 with the normal use inside @sc{cvs} (@pxref{Common options}).} 10955 10956 @menu 10957 * log options:: log options 10958 * log examples:: log examples 10959 @end menu 10960 10961 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10962 @node log options 10963 @appendixsubsec log options 10964 10965 By default, @code{log} prints all information that is 10966 available. All other options restrict the output. Note that the revision 10967 selection options (@code{-d}, @code{-r}, @code{-s}, and @code{-w}) have no 10968 effect, other than possibly causing a search for files in Attic directories, 10969 when used in conjunction with the options that restrict the output to only 10970 @code{log} header fields (@code{-b}, @code{-h}, @code{-R}, and @code{-t}) 10971 unless the @code{-S} option is also specified. 10972 10973 @table @code 10974 @item -b 10975 Print information about the revisions on the default 10976 branch, normally the highest branch on the trunk. 10977 10978 @item -d @var{dates} 10979 Print information about revisions with a checkin 10980 date/time in the range given by the 10981 semicolon-separated list of dates. The date formats 10982 accepted are those accepted by the @samp{-D} option to 10983 many other @sc{cvs} commands (@pxref{Common options}). 10984 Dates can be combined into ranges as follows: 10985 10986 @c Should we be thinking about accepting ISO8601 10987 @c ranges? For example "1972-09-10/1972-09-12". 10988 @table @code 10989 @item @var{d1}<@var{d2} 10990 @itemx @var{d2}>@var{d1} 10991 Select the revisions that were deposited between 10992 @var{d1} and @var{d2}. 10993 10994 @item <@var{d} 10995 @itemx @var{d}> 10996 Select all revisions dated @var{d} or earlier. 10997 10998 @item @var{d}< 10999 @itemx >@var{d} 11000 Select all revisions dated @var{d} or later. 11001 11002 @item @var{d} 11003 Select the single, latest revision dated @var{d} or 11004 earlier. 11005 @end table 11006 11007 The @samp{>} or @samp{<} characters may be followed by 11008 @samp{=} to indicate an inclusive range rather than an 11009 exclusive one. 11010 11011 Note that the separator is a semicolon (;). 11012 11013 @item -h 11014 Print only the name of the @sc{rcs} file, name 11015 of the file in the working directory, head, 11016 default branch, access list, locks, symbolic names, and 11017 suffix. 11018 11019 @item -l 11020 Local; run only in current working directory. (Default 11021 is to run recursively). 11022 11023 @item -N 11024 Do not print the list of tags for this file. This 11025 option can be very useful when your site uses a lot of 11026 tags, so rather than "more"'ing over 3 pages of tag 11027 information, the log information is presented without 11028 tags at all. 11029 11030 @item -R 11031 Print only the name of the @sc{rcs} file. 11032 11033 @c Note that using a bare revision (in addition to not 11034 @c being explicitly documented here) is potentially 11035 @c confusing; it shows the log message to get from the 11036 @c previous revision to that revision. "-r1.3 -r1.6" 11037 @c (equivalent to "-r1.3,1.6") is even worse; it 11038 @c prints the messages to get from 1.2 to 1.3 and 1.5 11039 @c to 1.6. By analogy with "cvs diff", users might 11040 @c expect that it is more like specifying a range. 11041 @c It is not 100% clear to me how much of this should 11042 @c be documented (for example, multiple -r options 11043 @c perhaps could/should be deprecated given the false 11044 @c analogy with "cvs diff"). 11045 @c In general, this section should be rewritten to talk 11046 @c about messages to get from revision rev1 to rev2, 11047 @c rather than messages for revision rev2 (that is, the 11048 @c messages are associated with a change not a static 11049 @c revision and failing to make this distinction causes 11050 @c much confusion). 11051 @item -r@var{revisions} 11052 Print information about revisions given in the 11053 comma-separated list @var{revisions} of revisions and 11054 ranges. The following table explains the available 11055 range formats: 11056 11057 @table @code 11058 @item @var{rev1}:@var{rev2} 11059 Revisions @var{rev1} to @var{rev2} (which must be on 11060 the same branch). 11061 11062 @item @var{rev1}::@var{rev2} 11063 The same, but excluding @var{rev1}. 11064 11065 @item :@var{rev} 11066 @itemx ::@var{rev} 11067 Revisions from the beginning of the branch up to 11068 and including @var{rev}. 11069 11070 @item @var{rev}: 11071 Revisions starting with @var{rev} to the end of the 11072 branch containing @var{rev}. 11073 11074 @item @var{rev}:: 11075 Revisions starting just after @var{rev} to the end of the 11076 branch containing @var{rev}. 11077 11078 @item @var{branch} 11079 An argument that is a branch means all revisions on 11080 that branch. 11081 11082 @item @var{branch1}:@var{branch2} 11083 @itemx @var{branch1}::@var{branch2} 11084 A range of branches means all revisions 11085 on the branches in that range. 11086 11087 @item @var{branch}. 11088 The latest revision in @var{branch}. 11089 @end table 11090 11091 A bare @samp{-r} with no revisions means the latest 11092 revision on the default branch, normally the trunk. 11093 There can be no space between the @samp{-r} option and 11094 its argument. 11095 11096 @item -S 11097 Suppress the header if no revisions are selected. 11098 11099 @item -s @var{states} 11100 Print information about revisions whose state 11101 attributes match one of the states given in the 11102 comma-separated list @var{states}. Individual states may 11103 be any text string, though @sc{cvs} commonly only uses two 11104 states, @samp{Exp} and @samp{dead}. See @ref{admin options} 11105 for more information. 11106 11107 @item -t 11108 Print the same as @samp{-h}, plus the descriptive text. 11109 11110 @item -w@var{logins} 11111 Print information about revisions checked in by users 11112 with login names appearing in the comma-separated list 11113 @var{logins}. If @var{logins} is omitted, the user's 11114 login is assumed. There can be no space between the 11115 @samp{-w} option and its argument. 11116 @end table 11117 11118 @code{log} prints the intersection of the revisions 11119 selected with the options @samp{-d}, @samp{-s}, and 11120 @samp{-w}, intersected with the union of the revisions 11121 selected by @samp{-b} and @samp{-r}. 11122 11123 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11124 @node log examples 11125 @appendixsubsec log examples 11126 11127 @cindex Timezone, in output 11128 @cindex Zone, time, in output 11129 Since @code{log} shows dates in local time, 11130 you might want to see them in Coordinated Universal Time (UTC) or 11131 some other timezone. 11132 To do this you can set your @code{$TZ} environment 11133 variable before invoking @sc{cvs}: 11134 11135 @example 11136 $ TZ=UTC cvs log foo.c 11137 $ TZ=EST cvs log bar.c 11138 @end example 11139 11140 (If you are using a @code{csh}-style shell, like @code{tcsh}, 11141 you would need to prefix the examples above with @code{env}.) 11142 11143 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11144 @node ls & rls 11145 @appendixsec ls & rls 11146 @cindex ls (subcommand) 11147 @cindex rls (subcommand) 11148 11149 @itemize @bullet 11150 @item 11151 ls [-e | -l] [-RP] [-r tag[:date]] [-D date] [path@dots{}] 11152 @item 11153 Requires: repository for @code{rls}, repository & working directory for 11154 @code{ls}. 11155 @item 11156 Changes: nothing. 11157 @item 11158 Synonym: @code{dir} & @code{list} are synonyms for @code{ls} and @code{rdir} 11159 & @code{rlist} are synonyms for @code{rls}. 11160 @end itemize 11161 11162 The @code{ls} and @code{rls} commands are used to list 11163 files and directories in the repository. 11164 11165 By default @code{ls} lists the files and directories 11166 that belong in your working directory, what would be 11167 there after an @code{update}. 11168 11169 By default @code{rls} lists the files and directories 11170 on the tip of the trunk in the topmost directory of the 11171 repository. 11172 11173 Both commands accept an optional list of file and 11174 directory names, relative to the working directory for 11175 @code{ls} and the topmost directory of the repository 11176 for @code{rls}. Neither is recursive by default. 11177 11178 @menu 11179 * ls & rls options:: ls & rls options 11180 * rls examples: rls examples 11181 @end menu 11182 11183 @node ls & rls options 11184 @appendixsubsec ls & rls options 11185 11186 These standard options are supported by @code{ls} & @code{rls}: 11187 11188 @table @code 11189 @item -d 11190 Show dead revisions (with tag when specified). 11191 11192 @item -e 11193 Display in CVS/Entries format. This format is meant to remain easily parsable 11194 by automation. 11195 11196 @item -l 11197 Display all details. 11198 11199 @item -P 11200 Don't list contents of empty directories when recursing. 11201 11202 @item -R 11203 List recursively. 11204 11205 @item -r @var{tag}[:@var{date}] 11206 Show files specified by @var{tag} or, when @var{date} is specified 11207 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11208 existed on @var{date}. See @ref{Common options}. 11209 11210 @item -D @var{date} 11211 Show files from date. 11212 @end table 11213 11214 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11215 @node rls examples 11216 @appendixsubsec rls examples 11217 11218 @example 11219 $ cvs rls 11220 cvs rls: Listing module: `.' 11221 CVSROOT 11222 first-dir 11223 @end example 11224 11225 @example 11226 $ cvs rls CVSROOT 11227 cvs rls: Listing module: `CVSROOT' 11228 checkoutlist 11229 commitinfo 11230 config 11231 cvswrappers 11232 loginfo 11233 modules 11234 notify 11235 rcsinfo 11236 taginfo 11237 verifymsg 11238 11239 @end example 11240 11241 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11242 @node rdiff 11243 @appendixsec rdiff---'patch' format diffs between releases 11244 @cindex rdiff (subcommand) 11245 11246 @itemize @bullet 11247 @item 11248 rdiff [options] @{-r tag1[:date1] | -D date1@} [-r tag2[:date2] | -D date2] modules@dots{} 11249 @item 11250 Requires: repository. 11251 @item 11252 Changes: nothing. 11253 @item 11254 Synonym: patch 11255 @end itemize 11256 11257 Builds a Larry Wall format patch(1) file between two 11258 releases, that can be fed directly into the @code{patch} 11259 program to bring an old release up-to-date with the new 11260 release. The diff output is sent to the standard output device. 11261 11262 You can specify (using the standard @samp{-r} and 11263 @samp{-D} options) any combination of one or two 11264 revisions or dates. If only one revision or date is 11265 specified, the patch file reflects differences between 11266 that revision or date and the current head revisions in 11267 the @sc{rcs} file. 11268 11269 Note that if the patch created by rdiff spans multiple directories, 11270 then it may be necessary to specify the @samp{-p} option when feeding 11271 the patch back to the @code{patch} command, so that @code{patch} is able 11272 to update files that are located in directories other than the one 11273 patch is run in. 11274 11275 @menu 11276 * rdiff options:: rdiff options 11277 * rdiff examples:: rdiff examples 11278 @end menu 11279 11280 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11281 @node rdiff options 11282 @appendixsubsec rdiff options 11283 11284 These standard options are supported by @code{rdiff} 11285 (@pxref{Common options}, for a complete description of 11286 them): 11287 11288 @table @code 11289 @item -D @var{date} 11290 Use the most recent revision no later than @var{date}. 11291 11292 @item -f 11293 If no matching revision is found, retrieve the most 11294 recent revision (instead of ignoring the file). 11295 11296 @item -k @var{kflag} 11297 Process keywords according to @var{kflag}. See 11298 @ref{Keyword substitution}. 11299 11300 @item -l 11301 Local; don't descend subdirectories. 11302 11303 @item -p 11304 Show which C function each change is in. 11305 11306 @item -R 11307 Examine directories recursively. This option is on by default. 11308 11309 @item -r @var{tag} 11310 Use the revision specified by @var{tag}, or when @var{date} is specified 11311 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11312 existed on @var{date}. See @ref{Common options}. 11313 @end table 11314 11315 In addition to the above, these options are available: 11316 11317 @table @code 11318 @item -c 11319 Use the context diff format. This is the default format. 11320 11321 @item -s 11322 Create a summary change report instead of a patch. The 11323 summary includes information about files that were 11324 changed or added between the releases. It is sent to 11325 the standard output device. This is useful for finding 11326 out, for example, which files have changed between two 11327 dates or revisions. 11328 11329 @item -t 11330 A diff of the top two revisions is sent to the standard 11331 output device. This is most useful for seeing what the 11332 last change to a file was. 11333 11334 @item -u 11335 Use the unidiff format for the context diffs. 11336 Remember that old versions 11337 of the @code{patch} program can't handle the unidiff 11338 format, so if you plan to post this patch to the net 11339 you should probably not use @samp{-u}. 11340 @end table 11341 11342 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11343 @node rdiff examples 11344 @appendixsubsec rdiff examples 11345 11346 Suppose you receive mail from @t{foo@@example.net} asking for an 11347 update from release 1.2 to 1.4 of the tc compiler. You 11348 have no such patches on hand, but with @sc{cvs} that can 11349 easily be fixed with a command such as this: 11350 11351 @example 11352 $ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 11353 $$ Mail -s 'The patches you asked for' foo@@example.net 11354 @end example 11355 11356 Suppose you have made release 1.3, and forked a branch 11357 called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1} 11358 corresponds to release 1.3.1, which was made some time 11359 ago. Now, you want to see how much development has been 11360 done on the branch. This command can be used: 11361 11362 @example 11363 $ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 11364 cvs rdiff: Diffing module-name 11365 File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 11366 File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 11367 File bar.h,v changed from revision 1.29.2.1 to 1.2 11368 @end example 11369 11370 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11371 @node release 11372 @appendixsec release---Indicate that a Module is no longer in use 11373 @cindex release (subcommand) 11374 11375 @itemize @bullet 11376 @item 11377 release [-d] directories@dots{} 11378 @item 11379 Requires: Working directory. 11380 @item 11381 Changes: Working directory, history log. 11382 @end itemize 11383 11384 This command is meant to safely cancel the effect of 11385 @samp{cvs checkout}. Since @sc{cvs} doesn't lock files 11386 (except for the @code{cvs admin -l} command, @pxref{admin options}), 11387 it isn't strictly necessary to use this command. You can 11388 always simply delete your working directory, if you 11389 like; but you risk losing changes you may have 11390 forgotten, and you leave no trace in the @sc{cvs} history 11391 file (@pxref{history file}) that you've abandoned your 11392 checkout. 11393 11394 Use @samp{cvs release} to avoid these problems. This 11395 command checks that no uncommitted changes are 11396 present; that you are executing it from immediately 11397 above a @sc{cvs} working directory; and that the repository 11398 recorded for your files is the same as the repository 11399 defined in the module database. 11400 11401 If all these conditions are true, @samp{cvs release} 11402 leaves a record of its execution (attesting to your 11403 intentionally abandoning your checkout) in the @sc{cvs} 11404 history log. 11405 11406 @menu 11407 * release options:: release options 11408 * release output:: release output 11409 * release examples:: release examples 11410 @end menu 11411 11412 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11413 @node release options 11414 @appendixsubsec release options 11415 11416 The @code{release} command supports one command option: 11417 11418 @table @code 11419 @item -d 11420 Delete your working copy of the file if the release 11421 succeeds. If this flag is not given your files will 11422 remain in your working directory. 11423 11424 @strong{WARNING: The @code{release} command deletes 11425 all directories and files recursively. This 11426 has the very serious side-effect that any directory 11427 that you have created inside your checked-out sources, 11428 and not added to the repository (using the @code{add} 11429 command; @pxref{Adding files}) will be silently deleted---even 11430 if it is non-empty!} 11431 @end table 11432 11433 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11434 @node release output 11435 @appendixsubsec release output 11436 11437 Before @code{release} releases your sources it will 11438 print a one-line message for any file that is not 11439 up-to-date. 11440 11441 @table @code 11442 @item U @var{file} 11443 @itemx P @var{file} 11444 There exists a newer revision of this file in the 11445 repository, and you have not modified your local copy 11446 of the file (@samp{U} and @samp{P} mean the same thing). 11447 11448 @item A @var{file} 11449 The file has been added to your private copy of the 11450 sources, but has not yet been committed to the 11451 repository. If you delete your copy of the sources 11452 this file will be lost. 11453 11454 @item R @var{file} 11455 The file has been removed from your private copy of the 11456 sources, but has not yet been removed from the 11457 repository, since you have not yet committed the 11458 removal. @xref{commit}. 11459 11460 @item M @var{file} 11461 The file is modified in your working directory. There 11462 might also be a newer revision inside the repository. 11463 11464 @item ? @var{file} 11465 @var{file} is in your working directory, but does not 11466 correspond to anything in the source repository, and is 11467 not in the list of files for @sc{cvs} to ignore (see the 11468 description of the @samp{-I} option, and 11469 @pxref{cvsignore}). If you remove your working 11470 sources, this file will be lost. 11471 @end table 11472 11473 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11474 @node release examples 11475 @appendixsubsec release examples 11476 11477 Release the @file{tc} directory, and delete your local working copy 11478 of the files. 11479 11480 @example 11481 $ cd .. # @r{You must stand immediately above the} 11482 # @r{sources when you issue @samp{cvs release}.} 11483 $ cvs release -d tc 11484 You have [0] altered files in this repository. 11485 Are you sure you want to release (and delete) directory `tc': y 11486 $ 11487 @end example 11488 11489 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11490 @node remove 11491 @appendixsec remove---Remove files from active use 11492 @cindex remove (subcommand) 11493 11494 @itemize @bullet 11495 @item 11496 Synopsis: remove [-flR] [files...] 11497 @item 11498 Requires: repository, working directory. 11499 @item 11500 Changes: working directory. 11501 @end itemize 11502 11503 The @code{remove} command is used to remove unwanted 11504 files from active use. The user normally deletes the 11505 files from the working directory prior to invocation 11506 of the @code{remove} command. Only the working 11507 directory is updated. Changes to the repository are 11508 not made until the @code{commit} command is run. 11509 11510 The @code{remove} command does not delete files from 11511 from the repository. @sc{cvs} keeps all historical 11512 data in the repository so that it is possible to 11513 reconstruct previous states of the projects under 11514 revision control. 11515 11516 To undo @sc{cvs} @code{remove} or to resurrect files 11517 that were previously removed, @xref{add}. 11518 11519 @menu 11520 * remove options:: remove options 11521 * remove examples:: remove examples 11522 @end menu 11523 11524 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11525 @node remove options 11526 @appendixsubsec remove options 11527 11528 These standard options are supported by @code{remove} 11529 (@pxref{Common options} for a complete description of 11530 them): 11531 11532 @table @code 11533 @item -l 11534 Local; run only in current working directory. See @ref{Recursive behavior}. 11535 11536 @item -R 11537 Process directories recursively. See @ref{Recursive behavior}. 11538 11539 @end table 11540 11541 In addition, these options are also supported: 11542 11543 @table @code 11544 @item -f 11545 Note that this is not the standard behavior of 11546 the @samp{-f} option as defined in @ref{Common options}. 11547 11548 Delete files before removing them. 11549 11550 Entire directory hierarchies are easily removed 11551 using @samp{-f}, but take note that it is not as 11552 easy to resurrect directory hierarchies as it is 11553 to remove them. 11554 11555 @end table 11556 11557 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11558 @node remove examples 11559 @appendixsubsec remove examples 11560 11561 @appendixsubsubsec Removing a file 11562 11563 @example 11564 $ cvs remove remove.me 11565 cvs remove: file `remove.me' still in working directory 11566 cvs remove: 1 file exists; remove it first 11567 $ rm -f remove.me 11568 $ cvs remove remove.me 11569 cvs remove: scheduling `remove.me' for removal 11570 cvs remove: use 'cvs commit' to remove this file permanently 11571 11572 $ ls remove.it 11573 remove.it 11574 $ cvs remove -f remove.it 11575 cvs remove: scheduling `remove.it' for removal 11576 cvs remove: use 'cvs commit' to remove this file permanently 11577 @end example 11578 11579 @appendixsubsubsec Removing entire directories 11580 @example 11581 $ tree -d a 11582 a 11583 |-- CVS 11584 `-- b 11585 `-- CVS 11586 11587 3 directories 11588 $ cvs remove -f a 11589 cvs remove: Removing a 11590 cvs remove: Removing a/b 11591 cvs remove: scheduling `a/b/c' for removal 11592 cvs remove: use 'cvs commit' to remove this file permanently 11593 @end example 11594 11595 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11596 @node server & pserver 11597 @appendixsec server & pserver---Act as a server for a client on stdin/stdout 11598 @cindex pserver (subcommand) 11599 @cindex server (subcommand) 11600 11601 @itemize @bullet 11602 @item 11603 pserver [-c path] 11604 11605 server [-c path] 11606 @item 11607 Requires: repository, client conversation on stdin/stdout 11608 @item 11609 Changes: Repository or, indirectly, client working directory. 11610 @end itemize 11611 11612 The @sc{cvs} @code{server} and @code{pserver} commands are used to provide 11613 repository access to remote clients and expect a client conversation on 11614 stdin & stdout. Typically these commands are launched from @code{inetd} or 11615 via @code{ssh} (@pxref{Remote repositories}). 11616 11617 @code{server} expects that the client has already been authenticated somehow, 11618 typically via @sc{ssh}, and @code{pserver} attempts to authenticate the client 11619 itself. 11620 11621 Only one option is available with the @code{server} and @code{pserver} 11622 commands: 11623 11624 @cindex configuration file 11625 @table @code 11626 @item -c path 11627 Load configuration from @var{path} rather than the default location 11628 @file{$CVSROOT/CVSROOT/config} (@pxref{config}). @var{path} must be 11629 @file{/etc/cvs.conf} or prefixed by @file{/etc/cvs/}. This option is 11630 supported beginning with @sc{cvs} release 1.12.13. 11631 @end table 11632 11633 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11634 @node tag & rtag 11635 @appendixsec tag & rtag---Mark project snapshot for later retrieval. 11636 @cindex tag (subcommand) 11637 @cindex freeze (subcommand) 11638 @cindex rtag (subcommand) 11639 @cindex rfreeze (subcommand) 11640 11641 @itemize @bullet 11642 @item 11643 tag [-bBcdFflR] [-r tag] [-D date] new_tag [files@dots{}] 11644 @item 11645 Requires: working directory, repository. 11646 @item 11647 Changes: repository. 11648 @item 11649 Synonym: ta, freeze 11650 @end itemize 11651 11652 @noindent 11653 and 11654 11655 @itemize @bullet 11656 @item 11657 rtag [-abBdFflnR] [-r tag | -D date] new_tag module@dots{} 11658 @item 11659 Requires: repository. 11660 @item 11661 Changes: repository. 11662 @item 11663 Synonym: rt, rfreeze 11664 @end itemize 11665 11666 Use @code{tag} to assign symbolic tags to the revisions of files 11667 checked out into your sandbox. The tags are applied immediately 11668 to the repository, with the revision numbers to attach the tag 11669 to supplied implicitly by the @sc{cvs} records of your working files. 11670 11671 @code{rtag} works similarly, but does not need a sandbox to operate 11672 in, requiring an explicitly supplied tag or date instead (or assuming 11673 the tip of the trunk when one is not supplied explicitly). @sc{cvs} 11674 uses this preexisting tag or date to determine which revisions of 11675 files in the repository to attach the new symbolic tag to. 11676 11677 The symbolic tags are meant to permanently record which 11678 revisions of which files were used for some purpose. The @code{checkout} 11679 and @code{update} commands allow you to extract an exact 11680 copy of a tagged release at any time in the future, 11681 regardless of whether files have been changed, added, 11682 or removed on the trunk or other branches since the release was tagged. 11683 For more, @xref{Branching and merging}. 11684 11685 These commands may also be used to delete a symbolic tag, 11686 or to create a branch. See the options section below. 11687 11688 Note if you wish to run destructive commands such as tag deletion, you may 11689 need to be a member of the group @code{cvsadmin} to do this. 11690 11691 If you attempt to create a tag that already exists, 11692 CVS will complain and not overwrite that tag. Use 11693 the @samp{-F} option to move the tag to a new set of 11694 revisions. 11695 11696 These standard options are supported by @code{tag} or @code{rtag} 11697 (@pxref{Common options}, for a complete description of them): 11698 11699 @table @code 11700 @item -D @var{date} 11701 Tag the most recent revision no later than @var{date}. This option is 11702 not valid when deleting tags (see @samp{-d} option, below). 11703 11704 @item -l 11705 Local; run only in current working directory. @xref{Recursive behavior}. 11706 11707 @item -R 11708 Update directories recursively (default). @xref{Recursive behavior}. 11709 11710 @item -r @var{tag}[:@var{date}] 11711 Tag the revisions specified by @var{tag} or, when @var{date} is specified 11712 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11713 existed on @var{date}. This option is not valid when deleting tags 11714 (see @samp{-d} option, below). 11715 @end table 11716 11717 Several tag specific options are also available. When an option is only 11718 available with one of @code{tag} or @code{rtag}, it is noted below: 11719 11720 @table @code 11721 @item -a 11722 Clear @var{new_tag} from removed files that would not otherwise be tagged 11723 (@code{rtag} only). 11724 11725 @item -B 11726 Allows @code{-d} or @code{-F} to delete or move branch tags. 11727 11728 @strong{WARNING: Recovering the information stored by branch tags is 11729 a very hard problem, more so than regular tags. Be absolutely sure you 11730 understand what you are doing before using this option.} 11731 11732 @item -b 11733 The @code{-b} option makes the new tag a branch tag (@pxref{Branching and 11734 merging}), allowing concurrent, isolated development. This is commonly used 11735 to create patches to a previously released software distribution. 11736 11737 @item -c 11738 Abort if any tagged files are locally modified (@code{tag} only). 11739 11740 @item -d 11741 Delete @var{new_tag}, instead of creating it. 11742 11743 @strong{WARNING: Be very certain of your ground before you delete a tag; doing 11744 this permanently discards some historical information, which could later turn 11745 out to be valuable.} 11746 11747 @item -F 11748 When a tag already exists, move it to the new revision. When the tag 11749 does not exist, create it as normal. This option is new in @sc{cvs} 1.4. 11750 The pre-1.4 behavior is identical to @samp{cvs tag -F}. 11751 11752 @strong{WARNING: Be very certain of your ground before you delete a tag; doing 11753 this permanently discards some historical information, which could later turn 11754 out to be valuable.} 11755 11756 @item -f 11757 With @code{-r @var{tag}} or @code{-d @var{date}}, force a head revision match 11758 if @var{tag} and @var{date} are not found (in other words, attach @var{new_tag} 11759 to the most recent trunk revision when @var{tag} and @var{date} do not 11760 resolve to an existing revision). 11761 11762 @item -n 11763 Do not execute the tag program specified in the @file{modules} file 11764 (@code{rtag} only). @xref{modules}, for more. 11765 @end table 11766 11767 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11768 @node update 11769 @appendixsec update---Bring work tree in sync with repository 11770 @cindex update (subcommand) 11771 11772 @itemize @bullet 11773 @item 11774 update [-ACdflPpRt] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag[:date] | -D date] [-W spec] [files@dots{}] 11775 @item 11776 Requires: repository, working directory. 11777 @item 11778 Changes: working directory. 11779 @end itemize 11780 11781 After you've run @code{checkout} to create your private copy 11782 of source from the common repository, other developers 11783 will continue changing the central source. From time 11784 to time, when it is convenient in your development 11785 process, you can use the @code{update} command from 11786 within your working directory to reconcile your work 11787 with any revisions applied to the source repository 11788 since your last checkout or update. Without the @code{-C} 11789 option, @code{update} will also merge any differences 11790 between the local copy of files and their base revisions 11791 into any destination revisions specified with @code{-r}, 11792 @code{-D}, or @code{-A}. 11793 11794 @menu 11795 * update options:: update options 11796 * update output:: update output 11797 @end menu 11798 11799 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11800 @node update options 11801 @appendixsubsec update options 11802 11803 These standard options are available with @code{update} 11804 (@pxref{Common options}, for a complete description of 11805 them): 11806 11807 @table @code 11808 @item -D date 11809 Use the most recent revision no later than @var{date}. 11810 This option is sticky. 11811 See @ref{Sticky tags}, for more information on sticky tags/dates. 11812 11813 @item -f 11814 Only useful with the @samp{-D} or @samp{-r} flags. If no matching revision 11815 is found, retrieve the most recent revision (instead of ignoring the file). 11816 11817 @item -k @var{kflag} 11818 Process keywords according to @var{kflag}. See 11819 @ref{Keyword substitution}. 11820 This option is sticky; future updates of 11821 this file in this working directory will use the same 11822 @var{kflag}. The @code{status} command can be viewed 11823 to see the sticky options. See @ref{Invoking CVS}, for 11824 more information on the @code{status} command. 11825 11826 @item -l 11827 Local; run only in current working directory. @xref{Recursive behavior}. 11828 11829 @item -P 11830 Prune empty directories. See @ref{Moving directories}. 11831 11832 @item -p 11833 Pipe files to the standard output. 11834 11835 @item -R 11836 Update directories recursively (default). @xref{Recursive 11837 behavior}. 11838 11839 @item -r @var{tag}[:@var{date}] 11840 Retrieve the revisions specified by @var{tag} or, when @var{date} is specified 11841 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 11842 existed on @var{date}. This option is sticky, and implies @samp{-P}. 11843 See @ref{Sticky tags}, for more information on sticky tags/dates. Also 11844 see @ref{Common options}. 11845 11846 @item -t 11847 Preserve source timestamps. Unlike @code{checkout}, where files are created 11848 using the original timestamp of the file in the repository, @code{update} 11849 updates files using the current time of the machine. This is convenient 11850 because updated files appear newer than any other files on the system so 11851 @code{make(1)} knows that their corresponding built artifacts are out of date 11852 and they will get rebuilt. The @samp{-t} flag instead preserves the timestamps 11853 of the original repository files, behaving exactly like @code{checkout}. 11854 This is useful for maintaining a tree in the original checked-out state. 11855 @end table 11856 11857 @need 800 11858 These special options are also available with 11859 @code{update}. 11860 11861 @table @code 11862 @item -A 11863 Reset any sticky tags, dates, or @samp{-k} options. 11864 See @ref{Sticky tags}, for more information on sticky tags/dates. 11865 11866 @item -C 11867 Overwrite locally modified files with clean copies from 11868 the repository (the modified file is saved in 11869 @file{.#@var{file}.@var{revision}}, however). 11870 11871 @item -d 11872 Create any directories that exist in the repository if 11873 they're missing from the working directory. Normally, 11874 @code{update} acts only on directories and files that 11875 were already enrolled in your working directory. 11876 11877 This is useful for updating directories that were 11878 created in the repository since the initial checkout; 11879 but it has an unfortunate side effect. If you 11880 deliberately avoided certain directories in the 11881 repository when you created your working directory 11882 (either through use of a module name or by listing 11883 explicitly the files and directories you wanted on the 11884 command line), then updating with @samp{-d} will create 11885 those directories, which may not be what you want. 11886 11887 @item -I @var{name} 11888 Ignore files whose names match @var{name} (in your 11889 working directory) during the update. You can specify 11890 @samp{-I} more than once on the command line to specify 11891 several files to ignore. Use @samp{-I !} to avoid 11892 ignoring any files at all. @xref{cvsignore}, for other 11893 ways to make @sc{cvs} ignore some files. 11894 11895 @item -W@var{spec} 11896 Specify file names that should be filtered during 11897 update. You can use this option repeatedly. 11898 11899 @var{spec} can be a file name pattern of the same type 11900 that you can specify in the @file{.cvswrappers} 11901 file. @xref{Wrappers}. 11902 11903 @item -j@var{revision} 11904 With two @samp{-j} options, merge changes from the 11905 revision specified with the first @samp{-j} option to 11906 the revision specified with the second @samp{j} option, 11907 into the working directory. 11908 11909 With one @samp{-j} option, merge changes from the 11910 ancestor revision to the revision specified with the 11911 @samp{-j} option, into the working directory. The 11912 ancestor revision is the common ancestor of the 11913 revision which the working directory is based on, and 11914 the revision specified in the @samp{-j} option. 11915 11916 Note that using a single @samp{-j @var{tagname}} option rather than 11917 @samp{-j @var{branchname}} to merge changes from a branch will 11918 often not remove files which were removed on the branch. 11919 @xref{Merging adds and removals}, for more. 11920 11921 In addition, each @samp{-j} option can contain an optional 11922 date specification which, when used with branches, can 11923 limit the chosen revision to one within a specific 11924 date. An optional date is specified by adding a colon 11925 (:) to the tag: 11926 @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 11927 11928 @xref{Branching and merging}. 11929 11930 @end table 11931 11932 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11933 @node update output 11934 @appendixsubsec update output 11935 11936 @code{update} and @code{checkout} keep you informed of 11937 their progress by printing a line for each file, preceded 11938 by one character indicating the status of the file: 11939 11940 @table @code 11941 @item U @var{file} 11942 The file was brought up to date with respect to the 11943 repository. This is done for any file that exists in 11944 the repository but not in your working directory, and for files 11945 that you haven't changed but are not the most recent 11946 versions available in the repository. 11947 11948 @item P @var{file} 11949 Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 11950 file. This accomplishes the same thing as @samp{U} using less bandwidth. 11951 11952 @item A @var{file} 11953 The file has been added to your private copy of the 11954 sources, and will be added to the source repository 11955 when you run @code{commit} on the file. This is a 11956 reminder to you that the file needs to be committed. 11957 11958 @item R @var{file} 11959 The file has been removed from your private copy of the 11960 sources, and will be removed from the source repository 11961 when you run @code{commit} on the file. This is a 11962 reminder to you that the file needs to be committed. 11963 11964 @item M @var{file} 11965 The file is modified in your working directory. 11966 11967 @samp{M} can indicate one of two states for a file 11968 you're working on: either there were no modifications 11969 to the same file in the repository, so that your file 11970 remains as you last saw it; or there were modifications 11971 in the repository as well as in your copy, but they 11972 were merged successfully, without conflict, in your 11973 working directory. 11974 11975 @sc{cvs} will print some messages if it merges your work, 11976 and a backup copy of your working file (as it looked 11977 before you ran @code{update}) will be made. The exact 11978 name of that file is printed while @code{update} runs. 11979 11980 @item C @var{file} 11981 @cindex .# files 11982 @cindex __ files (VMS) 11983 A conflict was detected while trying to merge your 11984 changes to @var{file} with changes from the source 11985 repository. @var{file} (the copy in your working 11986 directory) is now the result of attempting to merge 11987 the two revisions; an unmodified copy of your file 11988 is also in your working directory, with the name 11989 @file{.#@var{file}.@var{revision}} where @var{revision} 11990 is the revision that your modified file started 11991 from. Resolve the conflict as described in 11992 @ref{Conflicts example}. 11993 @c "some systems" as in out-of-the-box OSes? Not as 11994 @c far as I know. We need to advise sysadmins as well 11995 @c as users how to set up this kind of purge, if that is 11996 @c what they want. 11997 @c We also might want to think about cleaner solutions, 11998 @c like having CVS remove the .# file once the conflict 11999 @c has been resolved or something like that. 12000 (Note that some systems automatically purge 12001 files that begin with @file{.#} if they have not been 12002 accessed for a few days. If you intend to keep a copy 12003 of your original file, it is a very good idea to rename 12004 it.) Under @sc{vms}, the file name starts with 12005 @file{__} rather than @file{.#}. 12006 12007 @item ? @var{file} 12008 @var{file} is in your working directory, but does not 12009 correspond to anything in the source repository, and is 12010 not in the list of files for @sc{cvs} to ignore (see the 12011 description of the @samp{-I} option, and 12012 @pxref{cvsignore}). 12013 @end table 12014 12015 @c ----- END MAN 1 ----- 12016 @c --------------------------------------------------------------------- 12017 @node Invoking CVS 12018 @appendix Quick reference to CVS commands 12019 @cindex Command reference 12020 @cindex Reference, commands 12021 @cindex Invoking CVS 12022 12023 This appendix describes how to invoke @sc{cvs}, with 12024 references to where each command or feature is 12025 described in detail. For other references run the 12026 @code{cvs --help} command, or see @ref{Index}. 12027 12028 A @sc{cvs} command looks like: 12029 12030 @example 12031 cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 12032 @end example 12033 12034 Global options: 12035 12036 @table @code 12037 @item --allow-root=@var{rootdir} 12038 Specify legal @sc{cvsroot} directory (server only) (not 12039 in @sc{cvs} 1.9 and older). See @ref{Password 12040 authentication server}. 12041 12042 @item -a 12043 Authenticate all communication (client only) (not in @sc{cvs} 12044 1.9 and older). See @ref{Global options}. 12045 12046 @item -b 12047 Specify RCS location (@sc{cvs} 1.9 and older). See 12048 @ref{Global options}. 12049 12050 @item -d @var{root} 12051 Specify the @sc{cvsroot}. See @ref{Repository}. 12052 12053 @item -e @var{editor} 12054 Edit messages with @var{editor}. See @ref{Committing 12055 your changes}. 12056 12057 @item -f 12058 Do not read the @file{~/.cvsrc} file. See @ref{Global 12059 options}. 12060 12061 @item -H 12062 @itemx --help 12063 Print a help message. See @ref{Global options}. 12064 12065 @item -n 12066 Do not change any files. See @ref{Global options}. 12067 12068 @item -Q 12069 Be really quiet. See @ref{Global options}. 12070 12071 @item -q 12072 Be somewhat quiet. See @ref{Global options}. 12073 12074 @item -r 12075 Make new working files read-only. See @ref{Global options}. 12076 12077 @item -s @var{variable}=@var{value} 12078 Set a user variable. See @ref{Variables}. 12079 12080 @item -T @var{tempdir} 12081 Put temporary files in @var{tempdir}. See @ref{Global 12082 options}. 12083 12084 @item -t 12085 Trace @sc{cvs} execution. See @ref{Global options}. 12086 12087 @item -v 12088 @item --version 12089 Display version and copyright information for @sc{cvs}. 12090 12091 @item -w 12092 Make new working files read-write. See @ref{Global 12093 options}. 12094 12095 @item -x 12096 Encrypt all communication (client only). 12097 See @ref{Global options}. 12098 12099 @item -z @var{gzip-level} 12100 @cindex Compression 12101 @cindex Gzip 12102 Set the compression level (client only). 12103 See @ref{Global options}. 12104 @end table 12105 12106 Keyword expansion modes (@pxref{Substitution modes}): 12107 12108 @example 12109 -kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 12110 -kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12111 -kk $@splitrcskeyword{Id}$ 12112 -kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 12113 -ko @i{no expansion} 12114 -kb @i{no expansion, file is binary} 12115 @end example 12116 12117 Keywords (@pxref{Keyword list}): 12118 12119 @example 12120 $@splitrcskeyword{Author}: joe $ 12121 $@splitrcskeyword{Date}: 1993/12/09 03:21:13 $ 12122 $@splitrcskeyword{CVSHeader}: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12123 $@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12124 $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 12125 $@splitrcskeyword{Locker}: harry $ 12126 $@splitrcskeyword{Name}: snapshot_1_14 $ 12127 $@splitrcskeyword{RCSfile}: file1,v $ 12128 $@splitrcskeyword{Revision}: 1.1 $ 12129 $@splitrcskeyword{Source}: /home/files/file1,v $ 12130 $@splitrcskeyword{State}: Exp $ 12131 $@splitrcskeyword{Log}: file1,v $ 12132 Revision 1.1 1993/12/09 03:30:17 joe 12133 Initial revision 12134 12135 @end example 12136 12137 @c The idea behind this table is that we want each item 12138 @c to be a sentence or two at most. Preferably a 12139 @c single line. 12140 @c 12141 @c In some cases refs to "foo options" are just to get 12142 @c this thing written quickly, not because the "foo 12143 @c options" node is really the best place to point. 12144 Commands, command options, and command arguments: 12145 12146 @table @code 12147 @c ------------------------------------------------------------ 12148 @item add [@var{options}] [@var{files}@dots{}] 12149 Add a new file/directory. See @ref{Adding files}. 12150 12151 @table @code 12152 @item -k @var{kflag} 12153 Set keyword expansion. 12154 12155 @item -m @var{msg} 12156 Set file description. 12157 @end table 12158 12159 @c ------------------------------------------------------------ 12160 @item admin [@var{options}] [@var{files}@dots{}] 12161 Administration of history files in the repository. See 12162 @ref{admin}. 12163 @c This list omits those options which are not 12164 @c documented as being useful with CVS. That might be 12165 @c a mistake... 12166 12167 @table @code 12168 @item -b[@var{rev}] 12169 Set default branch. See @ref{Reverting local changes}. 12170 12171 @item -c@var{string} 12172 Set comment leader. 12173 12174 @item -k@var{subst} 12175 Set keyword substitution. See @ref{Keyword 12176 substitution}. 12177 12178 @item -l[@var{rev}] 12179 Lock revision @var{rev}, or latest revision. 12180 12181 @item -m@var{rev}:@var{msg} 12182 Replace the log message of revision @var{rev} with 12183 @var{msg}. 12184 12185 @item -o@var{range} 12186 Delete revisions from the repository. See 12187 @ref{admin options}. 12188 12189 @item -q 12190 Run quietly; do not print diagnostics. 12191 12192 @item -s@var{state}[:@var{rev}] 12193 Set the state. See @ref{admin options} for more information on possible 12194 states. 12195 12196 @c Does not work for client/server CVS 12197 @item -t 12198 Set file description from standard input. 12199 12200 @item -t@var{file} 12201 Set file description from @var{file}. 12202 12203 @item -t-@var{string} 12204 Set file description to @var{string}. 12205 12206 @item -u[@var{rev}] 12207 Unlock revision @var{rev}, or latest revision. 12208 @end table 12209 12210 @c ------------------------------------------------------------ 12211 @item annotate [@var{options}] [@var{files}@dots{}] 12212 Show last revision where each line was modified. See 12213 @ref{annotate & rannotate}. 12214 12215 @table @code 12216 @item -D @var{date} 12217 Annotate the most recent revision no later than 12218 @var{date}. See @ref{Common options}. 12219 12220 @item -F 12221 Force annotation of binary files. (Without this option, 12222 binary files are skipped with a message.) 12223 12224 @item -f 12225 Use head revision if tag/date not found. See 12226 @ref{Common options}. 12227 12228 @item -l 12229 Local; run only in current working directory. @xref{Recursive behavior}. 12230 12231 @item -R 12232 Operate recursively (default). @xref{Recursive 12233 behavior}. 12234 12235 @item -r @var{tag}[:@var{date}] 12236 Annotate revisions specified by @var{tag} or, when @var{date} is specified 12237 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12238 existed on @var{date}. See @ref{Common options}. 12239 @end table 12240 12241 @c ------------------------------------------------------------ 12242 @item checkout [@var{options}] @var{modules}@dots{} 12243 Get a copy of the sources. See @ref{checkout}. 12244 12245 @table @code 12246 @item -A 12247 Reset any sticky tags/date/options. See @ref{Sticky 12248 tags} and @ref{Keyword substitution}. 12249 12250 @item -c 12251 Output the module database. See @ref{checkout options}. 12252 12253 @item -D @var{date} 12254 Check out revisions as of @var{date} (is sticky). See 12255 @ref{Common options}. 12256 12257 @item -d @var{dir} 12258 Check out into @var{dir}. See @ref{checkout options}. 12259 12260 @item -f 12261 Use head revision if tag/date not found. See 12262 @ref{Common options}. 12263 12264 @c Probably want to use rev1/rev2 style like for diff 12265 @c -r. Here and in on-line help. 12266 @item -j @var{tag}[:@var{date}] 12267 Merge in the change specified by @var{tag}, or when @var{date} is specified 12268 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12269 existed on @var{date}. See @ref{checkout options}. 12270 12271 @item -k @var{kflag} 12272 Use @var{kflag} keyword expansion. See 12273 @ref{Substitution modes}. 12274 12275 @item -l 12276 Local; run only in current working directory. @xref{Recursive behavior}. 12277 12278 @item -N 12279 Don't ``shorten'' module paths if -d specified. See 12280 @ref{checkout options}. 12281 12282 @item -n 12283 Do not run module program (if any). See @ref{checkout options}. 12284 12285 @item -P 12286 Prune empty directories. See @ref{Moving directories}. 12287 12288 @item -p 12289 Check out files to standard output (avoids 12290 stickiness). See @ref{checkout options}. 12291 12292 @item -R 12293 Operate recursively (default). @xref{Recursive 12294 behavior}. 12295 12296 @item -r @var{tag}[:@var{date}] 12297 Checkout the revision already tagged with @var{tag} or, when @var{date} is 12298 specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12299 as it existed on @var{date}. This . See @ref{Common options}. 12300 12301 @item -s 12302 Like -c, but include module status. See @ref{checkout options}. 12303 @end table 12304 12305 @c ------------------------------------------------------------ 12306 @item commit [@var{options}] [@var{files}@dots{}] 12307 Check changes into the repository. See @ref{commit}. 12308 12309 @table @code 12310 @item -c 12311 Check for valid edits before committing. Requires a @sc{cvs} client and server 12312 both version 1.12.10 or greater. 12313 12314 @item -F @var{file} 12315 Read log message from @var{file}. See @ref{commit options}. 12316 12317 @item -f 12318 @c What is this "disables recursion"? It is from the 12319 @c on-line help; is it documented in this manual? 12320 Force the file to be committed; disables recursion. 12321 See @ref{commit options}. 12322 12323 @item -l 12324 Local; run only in current working directory. See @ref{Recursive behavior}. 12325 12326 @item -m @var{msg} 12327 Use @var{msg} as log message. See @ref{commit options}. 12328 12329 @item -n 12330 Do not run module program (if any). See @ref{commit options}. 12331 12332 @item -R 12333 Operate recursively (default). @xref{Recursive 12334 behavior}. 12335 12336 @item -r @var{rev} 12337 Commit to @var{rev}. See @ref{commit options}. 12338 @c FIXME: should be dragging over text from 12339 @c commit options, especially if it can be cleaned up 12340 @c and made concise enough. 12341 @end table 12342 12343 @c ------------------------------------------------------------ 12344 @item diff [@var{options}] [@var{files}@dots{}] 12345 Show differences between revisions. See @ref{diff}. 12346 In addition to the options shown below, accepts a wide 12347 variety of options to control output style, for example 12348 @samp{-c} for context diffs. 12349 12350 @table @code 12351 @item -D @var{date1} 12352 Diff revision for date against working file. See 12353 @ref{diff options}. 12354 12355 @item -D @var{date2} 12356 Diff @var{rev1}/@var{date1} against @var{date2}. See 12357 @ref{diff options}. 12358 12359 @item -l 12360 Local; run only in current working directory. See @ref{Recursive behavior}. 12361 12362 @item -N 12363 Include diffs for added and removed files. See 12364 @ref{diff options}. 12365 12366 @item -R 12367 Operate recursively (default). @xref{Recursive 12368 behavior}. 12369 12370 @item -r @var{tag1}[:@var{date1}] 12371 Diff the revisions specified by @var{tag1} or, when @var{date1} is specified 12372 and @var{tag1} is a branch tag, the version from the branch @var{tag1} as it 12373 existed on @var{date1}, against the working file. See @ref{diff options} 12374 and @ref{Common options}. 12375 12376 @item -r @var{tag2}[:@var{date2}] 12377 Diff the revisions specified by @var{tag2} or, when @var{date2} is specified 12378 and @var{tag2} is a branch tag, the version from the branch @var{tag2} as it 12379 existed on @var{date2}, against @var{rev1}/@var{date1}. See @ref{diff options} 12380 and @ref{Common options}. 12381 @end table 12382 12383 @c ------------------------------------------------------------ 12384 @item edit [@var{options}] [@var{files}@dots{}] 12385 Get ready to edit a watched file. See @ref{Editing files}. 12386 12387 @table @code 12388 @item -a @var{actions} 12389 Specify actions for temporary watch, where 12390 @var{actions} is @code{edit}, @code{unedit}, 12391 @code{commit}, @code{all}, or @code{none}. See 12392 @ref{Editing files}. 12393 12394 @item -c 12395 Check edits: Edit fails if someone else is already editting the file. 12396 Requires a @sc{cvs} client and server both of version 1.12.10 or greater. 12397 12398 @item -f 12399 Force edit; ignore other edits. Added in CVS 1.12.10. 12400 12401 @item -l 12402 Local; run only in current working directory. See @ref{Recursive behavior}. 12403 12404 @item -R 12405 Operate recursively (default). @xref{Recursive 12406 behavior}. 12407 @end table 12408 12409 @c ------------------------------------------------------------ 12410 @item editors [@var{options}] [@var{files}@dots{}] 12411 See who is editing a watched file. See @ref{Watch information}. 12412 12413 @table @code 12414 @item -l 12415 Local; run only in current working directory. See @ref{Recursive behavior}. 12416 12417 @item -R 12418 Operate recursively (default). @xref{Recursive 12419 behavior}. 12420 @end table 12421 12422 @c ------------------------------------------------------------ 12423 @item export [@var{options}] @var{modules}@dots{} 12424 Export files from @sc{cvs}. See @ref{export}. 12425 12426 @table @code 12427 @item -D @var{date} 12428 Check out revisions as of @var{date}. See 12429 @ref{Common options}. 12430 12431 @item -d @var{dir} 12432 Check out into @var{dir}. See @ref{export options}. 12433 12434 @item -f 12435 Use head revision if tag/date not found. See 12436 @ref{Common options}. 12437 12438 @item -k @var{kflag} 12439 Use @var{kflag} keyword expansion. See 12440 @ref{Substitution modes}. 12441 12442 @item -l 12443 Local; run only in current working directory. @xref{Recursive behavior}. 12444 12445 @item -N 12446 Don't ``shorten'' module paths if -d specified. See 12447 @ref{export options}. 12448 12449 @item -n 12450 Do not run module program (if any). See @ref{export options}. 12451 12452 @item -R 12453 Operate recursively (default). @xref{Recursive 12454 behavior}. 12455 12456 @item -r @var{tag}[:@var{date}] 12457 Export the revisions specified by @var{tag} or, when @var{date} is specified 12458 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12459 existed on @var{date}. See @ref{Common options}. 12460 @end table 12461 12462 @c ------------------------------------------------------------ 12463 @item history [@var{options}] [@var{files}@dots{}] 12464 Show repository access history. See @ref{history}. 12465 12466 @table @code 12467 @item -a 12468 All users (default is self). See @ref{history options}. 12469 12470 @item -b @var{str} 12471 Back to record with @var{str} in module/file/repos 12472 field. See @ref{history options}. 12473 12474 @item -c 12475 Report on committed (modified) files. See @ref{history options}. 12476 12477 @item -D @var{date} 12478 Since @var{date}. See @ref{history options}. 12479 12480 @item -e 12481 Report on all record types. See @ref{history options}. 12482 12483 @item -l 12484 Last modified (committed or modified report). See @ref{history options}. 12485 12486 @item -m @var{module} 12487 Report on @var{module} (repeatable). See @ref{history options}. 12488 12489 @item -n @var{module} 12490 In @var{module}. See @ref{history options}. 12491 12492 @item -o 12493 Report on checked out modules. See @ref{history options}. 12494 12495 @item -p @var{repository} 12496 In @var{repository}. See @ref{history options}. 12497 12498 @item -r @var{rev} 12499 Since revision @var{rev}. See @ref{history options}. 12500 12501 @item -T 12502 @c What the @#$@# is a TAG? Same as a tag? This 12503 @c wording is also in the online-line help. 12504 Produce report on all TAGs. See @ref{history options}. 12505 12506 @item -t @var{tag} 12507 Since tag record placed in history file (by anyone). 12508 See @ref{history options}. 12509 12510 @item -u @var{user} 12511 For user @var{user} (repeatable). See @ref{history options}. 12512 12513 @item -w 12514 Working directory must match. See @ref{history options}. 12515 12516 @item -x @var{types} 12517 Report on @var{types}, one or more of 12518 @code{TOEFWUPCGMAR}. See @ref{history options}. 12519 12520 @item -z @var{zone} 12521 Output for time zone @var{zone}. See @ref{history options}. 12522 @end table 12523 12524 @c ------------------------------------------------------------ 12525 @item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 12526 Import files into @sc{cvs}, using vendor branches. See 12527 @ref{import}. 12528 12529 @table @code 12530 @item -b @var{bra} 12531 Import to vendor branch @var{bra}. See 12532 @ref{Multiple vendor branches}. 12533 12534 @item -d 12535 Use the file's modification time as the time of 12536 import. See @ref{import options}. 12537 12538 @item -k @var{kflag} 12539 Set default keyword substitution mode. See 12540 @ref{import options}. 12541 12542 @item -m @var{msg} 12543 Use @var{msg} for log message. See 12544 @ref{import options}. 12545 12546 @item -I @var{ign} 12547 More files to ignore (! to reset). See 12548 @ref{import options}. 12549 12550 @item -W @var{spec} 12551 More wrappers. See @ref{import options}. 12552 @end table 12553 12554 @c ------------------------------------------------------------ 12555 @item init 12556 Create a @sc{cvs} repository if it doesn't exist. See 12557 @ref{Creating a repository}. 12558 12559 @c ------------------------------------------------------------ 12560 @item kserver 12561 Kerberos authenticated server. 12562 See @ref{Kerberos authenticated}. 12563 12564 @c ------------------------------------------------------------ 12565 @item log [@var{options}] [@var{files}@dots{}] 12566 Print out history information for files. See @ref{log & rlog}. 12567 12568 @table @code 12569 @item -b 12570 Only list revisions on the default branch. See @ref{log options}. 12571 12572 @item -d @var{dates} 12573 Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12574 latest before). See @ref{log options}. 12575 12576 @item -h 12577 Only print header. See @ref{log options}. 12578 12579 @item -l 12580 Local; run only in current working directory. See @ref{Recursive behavior}. 12581 12582 @item -N 12583 Do not list tags. See @ref{log options}. 12584 12585 @item -R 12586 Only print name of RCS file. See @ref{log options}. 12587 12588 @item -r@var{revs} 12589 Only list revisions @var{revs}. See @ref{log options}. 12590 12591 @item -s @var{states} 12592 Only list revisions with specified states. See @ref{log options}. 12593 12594 @item -t 12595 Only print header and descriptive text. See @ref{log 12596 options}. 12597 12598 @item -w@var{logins} 12599 Only list revisions checked in by specified logins. See @ref{log options}. 12600 @end table 12601 12602 @c ------------------------------------------------------------ 12603 @item login 12604 Prompt for password for authenticating server. See 12605 @ref{Password authentication client}. 12606 12607 @c ------------------------------------------------------------ 12608 @item logout 12609 Remove stored password for authenticating server. See 12610 @ref{Password authentication client}. 12611 12612 @c ------------------------------------------------------------ 12613 @item pserver 12614 Password authenticated server. 12615 See @ref{Password authentication server}. 12616 12617 @c ------------------------------------------------------------ 12618 @item rannotate [@var{options}] [@var{modules}@dots{}] 12619 Show last revision where each line was modified. See 12620 @ref{annotate & rannotate}. 12621 12622 @table @code 12623 @item -D @var{date} 12624 Annotate the most recent revision no later than 12625 @var{date}. See @ref{Common options}. 12626 12627 @item -F 12628 Force annotation of binary files. (Without this option, 12629 binary files are skipped with a message.) 12630 12631 @item -f 12632 Use head revision if tag/date not found. See 12633 @ref{Common options}. 12634 12635 @item -l 12636 Local; run only in current working directory. @xref{Recursive behavior}. 12637 12638 @item -R 12639 Operate recursively (default). @xref{Recursive behavior}. 12640 12641 @item -r @var{tag}[:@var{date}] 12642 Annotate the revision specified by @var{tag} or, when @var{date} is specified 12643 and @var{tag} is a branch tag, the version from the branch @var{tag} 12644 as it existed on @var{date}. See @ref{Common options}. 12645 @end table 12646 12647 @c ------------------------------------------------------------ 12648 @item rdiff [@var{options}] @var{modules}@dots{} 12649 Show differences between releases. See @ref{rdiff}. 12650 12651 @table @code 12652 @item -c 12653 Context diff output format (default). See @ref{rdiff options}. 12654 12655 @item -D @var{date} 12656 Select revisions based on @var{date}. See @ref{Common options}. 12657 12658 @item -f 12659 Use head revision if tag/date not found. See 12660 @ref{Common options}. 12661 12662 @item -l 12663 Local; run only in current working directory. See @ref{Recursive behavior}. 12664 12665 @item -R 12666 Operate recursively (default). @xref{Recursive 12667 behavior}. 12668 12669 @item -r @var{tag}[:@var{date}] 12670 Select the revisions specified by @var{tag} or, when @var{date} is specified 12671 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12672 existed on @var{date}. See @ref{diff options} and @ref{Common options}. 12673 12674 @item -s 12675 Short patch - one liner per file. See @ref{rdiff options}. 12676 12677 @item -t 12678 Top two diffs - last change made to the file. See 12679 @ref{diff options}. 12680 12681 @item -u 12682 Unidiff output format. See @ref{rdiff options}. 12683 12684 @item -V @var{vers} 12685 Use RCS Version @var{vers} for keyword expansion (obsolete). See 12686 @ref{rdiff options}. 12687 @end table 12688 12689 @c ------------------------------------------------------------ 12690 @item release [@var{options}] @var{directory} 12691 Indicate that a directory is no longer in use. See 12692 @ref{release}. 12693 12694 @table @code 12695 @item -d 12696 Delete the given directory. See @ref{release options}. 12697 @end table 12698 12699 @c ------------------------------------------------------------ 12700 @item remove [@var{options}] [@var{files}@dots{}] 12701 Remove an entry from the repository. See @ref{Removing files}. 12702 12703 @table @code 12704 @item -f 12705 Delete the file before removing it. See @ref{Removing files}. 12706 12707 @item -l 12708 Local; run only in current working directory. See @ref{Recursive behavior}. 12709 12710 @item -R 12711 Operate recursively (default). @xref{Recursive 12712 behavior}. 12713 @end table 12714 12715 @c ------------------------------------------------------------ 12716 @item rlog [@var{options}] [@var{files}@dots{}] 12717 Print out history information for modules. See @ref{log & rlog}. 12718 12719 @table @code 12720 @item -b 12721 Only list revisions on the default branch. See @ref{log options}. 12722 12723 @item -d @var{dates} 12724 Specify dates (@var{d1}<@var{d2} for range, @var{d} for 12725 latest before). See @ref{log options}. 12726 12727 @item -h 12728 Only print header. See @ref{log options}. 12729 12730 @item -l 12731 Local; run only in current working directory. See @ref{Recursive behavior}. 12732 12733 @item -N 12734 Do not list tags. See @ref{log options}. 12735 12736 @item -R 12737 Only print name of RCS file. See @ref{log options}. 12738 12739 @item -r@var{revs} 12740 Only list revisions @var{revs}. See @ref{log options}. 12741 12742 @item -s @var{states} 12743 Only list revisions with specified states. See @ref{log options}. 12744 12745 @item -t 12746 Only print header and descriptive text. See @ref{log options}. 12747 12748 @item -w@var{logins} 12749 Only list revisions checked in by specified logins. See @ref{log options}. 12750 @end table 12751 12752 @c ------------------------------------------------------------ 12753 @item rtag [@var{options}] @var{tag} @var{modules}@dots{} 12754 Add a symbolic tag to a module. 12755 See @ref{Revisions} and @ref{Branching and merging}. 12756 12757 @table @code 12758 @item -a 12759 Clear tag from removed files that would not otherwise 12760 be tagged. See @ref{Tagging add/remove}. 12761 12762 @item -b 12763 Create a branch named @var{tag}. See @ref{Branching and merging}. 12764 12765 @item -B 12766 Used in conjunction with -F or -d, enables movement and deletion of 12767 branch tags. Use with extreme caution. 12768 12769 @item -D @var{date} 12770 Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12771 12772 @item -d 12773 Delete @var{tag}. See @ref{Modifying tags}. 12774 12775 @item -F 12776 Move @var{tag} if it already exists. See @ref{Modifying tags}. 12777 12778 @item -f 12779 Force a head revision match if tag/date not found. 12780 See @ref{Tagging by date/tag}. 12781 12782 @item -l 12783 Local; run only in current working directory. See @ref{Recursive behavior}. 12784 12785 @item -n 12786 No execution of tag program. See @ref{Common options}. 12787 12788 @item -R 12789 Operate recursively (default). @xref{Recursive 12790 behavior}. 12791 12792 @item -r @var{tag}[:@var{date}] 12793 Tag the revision already tagged with @var{tag} or, when @var{date} is specified 12794 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12795 existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12796 @end table 12797 12798 @c ------------------------------------------------------------ 12799 @item server 12800 Rsh server. See @ref{Connecting via rsh}. 12801 12802 @c ------------------------------------------------------------ 12803 @item status [@var{options}] @var{files}@dots{} 12804 Display status information in a working directory. See 12805 @ref{File status}. 12806 12807 @table @code 12808 @item -l 12809 Local; run only in current working directory. See @ref{Recursive behavior}. 12810 12811 @item -R 12812 Operate recursively (default). @xref{Recursive behavior}. 12813 12814 @item -v 12815 Include tag information for file. See @ref{Tags}. 12816 @end table 12817 12818 @c ------------------------------------------------------------ 12819 @item tag [@var{options}] @var{tag} [@var{files}@dots{}] 12820 Add a symbolic tag to checked out version of files. 12821 See @ref{Revisions} and @ref{Branching and merging}. 12822 12823 @table @code 12824 @item -b 12825 Create a branch named @var{tag}. See @ref{Branching and merging}. 12826 12827 @item -c 12828 Check that working files are unmodified. See 12829 @ref{Tagging the working directory}. 12830 12831 @item -D @var{date} 12832 Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 12833 12834 @item -d 12835 Delete @var{tag}. See @ref{Modifying tags}. 12836 12837 @item -F 12838 Move @var{tag} if it already exists. See @ref{Modifying tags}. 12839 12840 @item -f 12841 Force a head revision match if tag/date not found. 12842 See @ref{Tagging by date/tag}. 12843 12844 @item -l 12845 Local; run only in current working directory. See @ref{Recursive behavior}. 12846 12847 @item -R 12848 Operate recursively (default). @xref{Recursive behavior}. 12849 12850 @item -r @var{tag}[:@var{date}] 12851 Tag the revision already tagged with @var{tag}, or when @var{date} is specified 12852 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12853 existed on @var{date}. See @ref{Tagging by date/tag} and @ref{Common options}. 12854 @end table 12855 12856 @c ------------------------------------------------------------ 12857 @item unedit [@var{options}] [@var{files}@dots{}] 12858 Undo an edit command. See @ref{Editing files}. 12859 12860 @table @code 12861 @item -l 12862 Local; run only in current working directory. See @ref{Recursive behavior}. 12863 12864 @item -R 12865 Operate recursively (default). @xref{Recursive behavior}. 12866 @end table 12867 12868 @c ------------------------------------------------------------ 12869 @item update [@var{options}] [@var{files}@dots{}] 12870 Bring work tree in sync with repository. See 12871 @ref{update}. 12872 12873 @table @code 12874 @item -A 12875 Reset any sticky tags/date/options. See @ref{Sticky 12876 tags} and @ref{Keyword substitution}. 12877 12878 @item -C 12879 Overwrite locally modified files with clean copies from 12880 the repository (the modified file is saved in 12881 @file{.#@var{file}.@var{revision}}, however). 12882 12883 @item -D @var{date} 12884 Check out revisions as of @var{date} (is sticky). See 12885 @ref{Common options}. 12886 12887 @item -d 12888 Create directories. See @ref{update options}. 12889 12890 @item -f 12891 Use head revision if tag/date not found. See 12892 @ref{Common options}. 12893 12894 @item -I @var{ign} 12895 More files to ignore (! to reset). See 12896 @ref{import options}. 12897 12898 @c Probably want to use rev1/rev2 style like for diff 12899 @c -r. Here and in on-line help. 12900 @item -j @var{tag}[:@var{date}] 12901 Merge in changes from revisions specified by @var{tag} or, when @var{date} is 12902 specified and @var{tag} is a branch tag, the version from the branch @var{tag} 12903 as it existed on @var{date}. See @ref{update options}. 12904 12905 @item -k @var{kflag} 12906 Use @var{kflag} keyword expansion. See 12907 @ref{Substitution modes}. 12908 12909 @item -l 12910 Local; run only in current working directory. @xref{Recursive behavior}. 12911 12912 @item -P 12913 Prune empty directories. See @ref{Moving directories}. 12914 12915 @item -p 12916 Check out files to standard output (avoids 12917 stickiness). See @ref{update options}. 12918 12919 @item -R 12920 Operate recursively (default). @xref{Recursive 12921 behavior}. 12922 12923 @item -r @var{tag}[:@var{date}] 12924 Checkout the revisions specified by @var{tag} or, when @var{date} is specified 12925 and @var{tag} is a branch tag, the version from the branch @var{tag} as it 12926 existed on @var{date}. See @ref{Common options}. 12927 12928 @item -W @var{spec} 12929 More wrappers. See @ref{import options}. 12930 @end table 12931 12932 @c ------------------------------------------------------------ 12933 @item version 12934 @cindex version (subcommand) 12935 12936 Display the version of @sc{cvs} being used. If the repository 12937 is remote, display both the client and server versions. 12938 12939 @c ------------------------------------------------------------ 12940 @item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 12941 12942 on/off: turn on/off read-only checkouts of files. See 12943 @ref{Setting a watch}. 12944 12945 add/remove: add or remove notification on actions. See 12946 @ref{Getting Notified}. 12947 12948 @table @code 12949 @item -a @var{actions} 12950 Specify actions for temporary watch, where 12951 @var{actions} is @code{edit}, @code{unedit}, 12952 @code{commit}, @code{all}, or @code{none}. See 12953 @ref{Editing files}. 12954 12955 @item -l 12956 Local; run only in current working directory. See @ref{Recursive behavior}. 12957 12958 @item -R 12959 Operate recursively (default). @xref{Recursive 12960 behavior}. 12961 @end table 12962 12963 @c ------------------------------------------------------------ 12964 @item watchers [@var{options}] [@var{files}@dots{}] 12965 See who is watching a file. See @ref{Watch information}. 12966 12967 @table @code 12968 @item -l 12969 Local; run only in current working directory. See @ref{Recursive behavior}. 12970 12971 @item -R 12972 Operate recursively (default). @xref{Recursive 12973 behavior}. 12974 @end table 12975 12976 @end table 12977 12978 @c --------------------------------------------------------------------- 12979 @node Administrative files 12980 @appendix Reference manual for Administrative files 12981 @cindex Administrative files (reference) 12982 @cindex Files, reference manual 12983 @cindex Reference manual (files) 12984 @cindex CVSROOT (file) 12985 12986 Inside the repository, in the directory 12987 @file{$CVSROOT/CVSROOT}, there are a number of 12988 supportive files for @sc{cvs}. You can use @sc{cvs} in a limited 12989 fashion without any of them, but if they are set up 12990 properly they can help make life easier. For a 12991 discussion of how to edit them, see @ref{Intro 12992 administrative files}. 12993 12994 The most important of these files is the @file{modules} 12995 file, which defines the modules inside the repository. 12996 12997 @menu 12998 * modules:: Defining modules 12999 * Wrappers:: Specify binary-ness based on file name 13000 * Trigger Scripts:: Launch scripts in response to server events 13001 * rcsinfo:: Templates for the log messages 13002 * cvsignore:: Ignoring files via cvsignore 13003 * checkoutlist:: Adding your own administrative files 13004 * history file:: History information 13005 * Variables:: Various variables are expanded 13006 * config:: Miscellaneous CVS configuration 13007 @end menu 13008 13009 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13010 @node modules 13011 @appendixsec The modules file 13012 @cindex Modules (admin file) 13013 @cindex Defining modules (reference manual) 13014 13015 The @file{modules} file records your definitions of 13016 names for collections of source code. @sc{cvs} will 13017 use these definitions if you use @sc{cvs} to update the 13018 modules file (use normal commands like @code{add}, 13019 @code{commit}, etc). 13020 13021 The @file{modules} file may contain blank lines and 13022 comments (lines beginning with @samp{#}) as well as 13023 module definitions. Long lines can be continued on the 13024 next line by specifying a backslash (@samp{\}) as the 13025 last character on the line. 13026 13027 There are three basic types of modules: alias modules, 13028 regular modules, and ampersand modules. The difference 13029 between them is the way that they map files in the 13030 repository to files in the working directory. In all 13031 of the following examples, the top-level repository 13032 contains a directory called @file{first-dir}, which 13033 contains two files, @file{file1} and @file{file2}, and a 13034 directory @file{sdir}. @file{first-dir/sdir} contains 13035 a file @file{sfile}. 13036 13037 @c FIXME: should test all the examples in this section. 13038 13039 @menu 13040 * Alias modules:: The simplest kind of module 13041 * Regular modules:: 13042 * Ampersand modules:: 13043 * Excluding directories:: Excluding directories from a module 13044 * Module options:: Regular and ampersand modules can take options 13045 * Module program options:: How the modules ``program options'' programs 13046 are run. 13047 @end menu 13048 13049 @node Alias modules 13050 @appendixsubsec Alias modules 13051 @cindex Alias modules 13052 @cindex -a, in modules file 13053 13054 Alias modules are the simplest kind of module: 13055 13056 @table @code 13057 @item @var{mname} -a @var{aliases}@dots{} 13058 This represents the simplest way of defining a module 13059 @var{mname}. The @samp{-a} flags the definition as a 13060 simple alias: @sc{cvs} will treat any use of @var{mname} (as 13061 a command argument) as if the list of names 13062 @var{aliases} had been specified instead. 13063 @var{aliases} may contain either other module names or 13064 paths. When you use paths in aliases, @code{checkout} 13065 creates all intermediate directories in the working 13066 directory, just as if the path had been specified 13067 explicitly in the @sc{cvs} arguments. 13068 @end table 13069 13070 For example, if the modules file contains: 13071 13072 @example 13073 amodule -a first-dir 13074 @end example 13075 13076 @noindent 13077 then the following two commands are equivalent: 13078 13079 @example 13080 $ cvs co amodule 13081 $ cvs co first-dir 13082 @end example 13083 13084 @noindent 13085 and they each would provide output such as: 13086 13087 @example 13088 cvs checkout: Updating first-dir 13089 U first-dir/file1 13090 U first-dir/file2 13091 cvs checkout: Updating first-dir/sdir 13092 U first-dir/sdir/sfile 13093 @end example 13094 13095 @node Regular modules 13096 @appendixsubsec Regular modules 13097 @cindex Regular modules 13098 13099 @table @code 13100 @item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 13101 In the simplest case, this form of module definition 13102 reduces to @samp{@var{mname} @var{dir}}. This defines 13103 all the files in directory @var{dir} as module mname. 13104 @var{dir} is a relative path (from @code{$CVSROOT}) to a 13105 directory of source in the source repository. In this 13106 case, on checkout, a single directory called 13107 @var{mname} is created as a working directory; no 13108 intermediate directory levels are used by default, even 13109 if @var{dir} was a path involving several directory 13110 levels. 13111 @end table 13112 13113 For example, if a module is defined by: 13114 13115 @example 13116 regmodule first-dir 13117 @end example 13118 13119 @noindent 13120 then regmodule will contain the files from first-dir: 13121 13122 @example 13123 $ cvs co regmodule 13124 cvs checkout: Updating regmodule 13125 U regmodule/file1 13126 U regmodule/file2 13127 cvs checkout: Updating regmodule/sdir 13128 U regmodule/sdir/sfile 13129 $ 13130 @end example 13131 13132 By explicitly specifying files in the module definition 13133 after @var{dir}, you can select particular files from 13134 directory @var{dir}. Here is 13135 an example: 13136 13137 @example 13138 regfiles first-dir/sdir sfile 13139 @end example 13140 13141 @noindent 13142 With this definition, getting the regfiles module 13143 will create a single working directory 13144 @file{regfiles} containing the file listed, which 13145 comes from a directory deeper 13146 in the @sc{cvs} source repository: 13147 13148 @example 13149 $ cvs co regfiles 13150 U regfiles/sfile 13151 $ 13152 @end example 13153 13154 @node Ampersand modules 13155 @appendixsubsec Ampersand modules 13156 @cindex Ampersand modules 13157 @cindex &, in modules file 13158 13159 A module definition can refer to other modules by 13160 including @samp{&@var{module}} in its definition. 13161 @example 13162 @var{mname} [ options ] @var{&module}@dots{} 13163 @end example 13164 13165 Then getting the module creates a subdirectory for each such 13166 module, in the directory containing the module. For 13167 example, if modules contains 13168 13169 @example 13170 ampermod &first-dir 13171 @end example 13172 13173 @noindent 13174 then a checkout will create an @code{ampermod} directory 13175 which contains a directory called @code{first-dir}, 13176 which in turns contains all the directories and files 13177 which live there. For example, the command 13178 13179 @example 13180 $ cvs co ampermod 13181 @end example 13182 13183 @noindent 13184 will create the following files: 13185 13186 @example 13187 ampermod/first-dir/file1 13188 ampermod/first-dir/file2 13189 ampermod/first-dir/sdir/sfile 13190 @end example 13191 13192 There is one quirk/bug: the messages that @sc{cvs} 13193 prints omit the @file{ampermod}, and thus do not 13194 correctly display the location to which it is checking 13195 out the files: 13196 13197 @example 13198 $ cvs co ampermod 13199 cvs checkout: Updating first-dir 13200 U first-dir/file1 13201 U first-dir/file2 13202 cvs checkout: Updating first-dir/sdir 13203 U first-dir/sdir/sfile 13204 $ 13205 @end example 13206 13207 Do not rely on this buggy behavior; it may get fixed in 13208 a future release of @sc{cvs}. 13209 13210 @c FIXCVS: What happens if regular and & modules are 13211 @c combined, as in "ampermodule first-dir &second-dir"? 13212 @c When I tried it, it seemed to just ignore the 13213 @c "first-dir". I think perhaps it should be an error 13214 @c (but this needs further investigation). 13215 @c In addition to discussing what each one does, we 13216 @c should put in a few words about why you would use one or 13217 @c the other in various situations. 13218 13219 @node Excluding directories 13220 @appendixsubsec Excluding directories 13221 @cindex Excluding directories, in modules file 13222 @cindex !, in modules file 13223 13224 An alias module may exclude particular directories from 13225 other modules by using an exclamation mark (@samp{!}) 13226 before the name of each directory to be excluded. 13227 13228 For example, if the modules file contains: 13229 13230 @example 13231 exmodule -a !first-dir/sdir first-dir 13232 @end example 13233 13234 @noindent 13235 then checking out the module @samp{exmodule} will check 13236 out everything in @samp{first-dir} except any files in 13237 the subdirectory @samp{first-dir/sdir}. 13238 @c Note that the "!first-dir/sdir" sometimes must be listed 13239 @c before "first-dir". That seems like a probable bug, in which 13240 @c case perhaps it should be fixed (to allow either 13241 @c order) rather than documented. See modules4 in testsuite. 13242 13243 @node Module options 13244 @appendixsubsec Module options 13245 @cindex Options, in modules file 13246 13247 Either regular modules or ampersand modules can contain 13248 options, which supply additional information concerning 13249 the module. 13250 13251 @table @code 13252 @cindex -d, in modules file 13253 @item -d @var{name} 13254 Name the working directory something other than the 13255 module name. 13256 @c FIXME: Needs a bunch of examples, analogous to the 13257 @c examples for alias, regular, and ampersand modules 13258 @c which show where the files go without -d. 13259 13260 @cindex Export program 13261 @cindex -e, in modules file 13262 @item -e @var{prog} 13263 Specify a program @var{prog} to run whenever files in a 13264 module are exported. @var{prog} runs with a single 13265 argument, the module name. 13266 @c FIXME: Is it run on server? client? 13267 13268 @cindex Checkout program 13269 @cindex -o, in modules file 13270 @item -o @var{prog} 13271 Specify a program @var{prog} to run whenever files in a 13272 module are checked out. @var{prog} runs with a single 13273 argument, the module name. See @ref{Module program options} for 13274 information on how @var{prog} is called. 13275 @c FIXME: Is it run on server? client? 13276 13277 @cindex Status of a module 13278 @cindex Module status 13279 @cindex -s, in modules file 13280 @item -s @var{status} 13281 Assign a status to the module. When the module file is 13282 printed with @samp{cvs checkout -s} the modules are 13283 sorted according to primarily module status, and 13284 secondarily according to the module name. This option 13285 has no other meaning. You can use this option for 13286 several things besides status: for instance, list the 13287 person that is responsible for this module. 13288 13289 @cindex Tag program 13290 @cindex -t, in modules file 13291 @item -t @var{prog} 13292 Specify a program @var{prog} to run whenever files in a 13293 module are tagged with @code{rtag}. @var{prog} runs 13294 with two arguments: the module name and the symbolic 13295 tag specified to @code{rtag}. It is not run 13296 when @code{tag} is executed. Generally you will find 13297 that the @file{taginfo} file is a better solution (@pxref{taginfo}). 13298 @c FIXME: Is it run on server? client? 13299 @c Problems with -t include: 13300 @c * It is run after the tag not before 13301 @c * It doesn't get passed all the information that 13302 @c taginfo does ("mov", &c). 13303 @c * It only is run for rtag, not tag. 13304 @end table 13305 13306 You should also see @pxref{Module program options} about how the 13307 ``program options'' programs are run. 13308 13309 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13310 13311 @node Module program options 13312 @appendixsubsec How the modules file ``program options'' programs are run 13313 @cindex Modules file program options 13314 @cindex -t, in modules file 13315 @cindex -o, in modules file 13316 @cindex -e, in modules file 13317 13318 @noindent 13319 For checkout, rtag, and export, the program is server-based, and as such the 13320 following applies:- 13321 13322 If using remote access methods (pserver, ext, etc.), 13323 @sc{cvs} will execute this program on the server from a temporary 13324 directory. The path is searched for this program. 13325 13326 If using ``local access'' (on a local or remote NFS file system, i.e. 13327 repository set just to a path), 13328 the program will be executed from the newly checked-out tree, if 13329 found there, or alternatively searched for in the path if not. 13330 13331 The programs are all run after the operation has effectively 13332 completed. 13333 13334 13335 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13336 @node Wrappers 13337 @appendixsec The cvswrappers file 13338 @cindex cvswrappers (admin file) 13339 @cindex CVSWRAPPERS, environment variable 13340 @cindex Wrappers 13341 13342 @c FIXME: need some better way of separating this out 13343 @c by functionality. -m is 13344 @c one feature, and -k is a another. And this discussion 13345 @c should be better motivated (e.g. start with the 13346 @c problems, then explain how the feature solves it). 13347 13348 Wrappers refers to a @sc{cvs} feature which lets you 13349 control certain settings based on the name of the file 13350 which is being operated on. The settings are @samp{-k} 13351 for binary files, and @samp{-m} for nonmergeable text 13352 files. 13353 13354 The @samp{-m} option 13355 specifies the merge methodology that should be used when 13356 a non-binary file is updated. @code{MERGE} means the usual 13357 @sc{cvs} behavior: try to merge the files. @code{COPY} 13358 means that @code{cvs update} will refuse to merge 13359 files, as it also does for files specified as binary 13360 with @samp{-kb} (but if the file is specified as 13361 binary, there is no need to specify @samp{-m 'COPY'}). 13362 @sc{cvs} will provide the user with the 13363 two versions of the files, and require the user using 13364 mechanisms outside @sc{cvs}, to insert any necessary 13365 changes. 13366 13367 @strong{WARNING: do not use @code{COPY} with 13368 @sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 13369 copy one version of your file over the other, wiping 13370 out the previous contents.} 13371 @c Ordinarily we don't document the behavior of old 13372 @c versions. But this one is so dangerous, I think we 13373 @c must. I almost renamed it to -m 'NOMERGE' so we 13374 @c could say "never use -m 'COPY'". 13375 The @samp{-m} wrapper option only affects behavior when 13376 merging is done on update; it does not affect how files 13377 are stored. See @ref{Binary files}, for more on 13378 binary files. 13379 13380 The basic format of the file @file{cvswrappers} is: 13381 13382 @c FIXME: @example is all wrong for this. Use @deffn or 13383 @c something more sensible. 13384 @example 13385 wildcard [option value][option value]... 13386 13387 where option is one of 13388 -m update methodology value: MERGE or COPY 13389 -k keyword expansion value: expansion mode 13390 13391 and value is a single-quote delimited value. 13392 @end example 13393 13394 @ignore 13395 @example 13396 *.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' 13397 *.c -t 'indent %s %s' 13398 @end example 13399 @c When does the filter need to be an absolute pathname 13400 @c and when will something like the above work? I 13401 @c suspect it relates to the PATH of the server (which 13402 @c in turn depends on all kinds of stuff, e.g. inetd 13403 @c for pserver). I'm not sure whether/where to discuss 13404 @c this. 13405 @c FIXME: What do the %s's stand for? 13406 13407 @noindent 13408 The above example of a @file{cvswrappers} file 13409 states that all files/directories that end with a @code{.nib} 13410 should be filtered with the @file{wrap} program before 13411 checking the file into the repository. The file should 13412 be filtered though the @file{unwrap} program when the 13413 file is checked out of the repository. The 13414 @file{cvswrappers} file also states that a @code{COPY} 13415 methodology should be used when updating the files in 13416 the repository (that is, no merging should be performed). 13417 13418 @c What pitfalls arise when using indent this way? Is 13419 @c it a winning thing to do? Would be nice to at least 13420 @c hint at those issues; we want our examples to tell 13421 @c how to solve problems, not just to say that cvs can 13422 @c do certain things. 13423 The last example line says that all files that end with 13424 @code{.c} should be filtered with @file{indent} 13425 before being checked into the repository. Unlike the previous 13426 example, no filtering of the @code{.c} file is done when 13427 it is checked out of the repository. 13428 @noindent 13429 The @code{-t} filter is called with two arguments, 13430 the first is the name of the file/directory to filter 13431 and the second is the pathname to where the resulting 13432 filtered file should be placed. 13433 13434 @noindent 13435 The @code{-f} filter is called with one argument, 13436 which is the name of the file to filter from. The end 13437 result of this filter will be a file in the users directory 13438 that they can work on as they normally would. 13439 13440 Note that the @samp{-t}/@samp{-f} features do not 13441 conveniently handle one portion of @sc{cvs}'s operation: 13442 determining when files are modified. @sc{cvs} will still 13443 want a file (or directory) to exist, and it will use 13444 its modification time to determine whether a file is 13445 modified. If @sc{cvs} erroneously thinks a file is 13446 unmodified (for example, a directory is unchanged but 13447 one of the files within it is changed), you can force 13448 it to check in the file anyway by specifying the 13449 @samp{-f} option to @code{cvs commit} (@pxref{commit 13450 options}). 13451 @c This is, of course, a serious design flaw in -t/-f. 13452 @c Probably the whole functionality needs to be 13453 @c redesigned (starting from requirements) to fix this. 13454 @end ignore 13455 13456 @c FIXME: We don't document -W or point to where it is 13457 @c documented. Or .cvswrappers. 13458 For example, the following command imports a 13459 directory, treating files whose name ends in 13460 @samp{.exe} as binary: 13461 13462 @example 13463 cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 13464 @end example 13465 13466 @c Another good example, would be storing files 13467 @c (e.g. binary files) compressed in the repository. 13468 @c :::::::::::::::::: 13469 @c cvswrappers 13470 @c :::::::::::::::::: 13471 @c *.t12 -m 'COPY' 13472 @c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 13473 @c 13474 @c :::::::::::::::::: 13475 @c gunzipcp 13476 @c :::::::::::::::::: 13477 @c : 13478 @c [ -f $1 ] || exit 1 13479 @c zcat $1 > /tmp/.#$1.$$ 13480 @c mv /tmp/.#$1.$$ $1 13481 @c 13482 @c :::::::::::::::::: 13483 @c gzipcp 13484 @c :::::::::::::::::: 13485 @c : 13486 @c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 13487 @c if [ ! -d $DIRNAME ] ; then 13488 @c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 13489 @c fi 13490 @c gzip -c $DIRNAME > $2 13491 @c One catch--"cvs diff" will not invoke the wrappers 13492 @c (probably a CVS bug, although I haven't thought it out). 13493 13494 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13495 @node Trigger Scripts 13496 @appendixsec The Trigger Scripts 13497 @cindex info files 13498 @cindex trigger scripts 13499 @cindex script hooks 13500 13501 @c FIXME 13502 @c Somewhere there needs to be a more "how-to" guide to writing these. 13503 @c One particular issue that people sometimes are worried about is performance, 13504 @c and the impact of writing in perl or sh or ____. Performance comparisons 13505 @c should probably remain outside the scope of this document, but at least 13506 @c _that_ much could be referenced, perhaps with links to other sources. 13507 13508 Several of the administrative files support triggers, or the launching external 13509 scripts or programs at specific times before or after particular events, during 13510 the execution of @sc{cvs} commands. These hooks can be used to prevent certain 13511 actions, log them, and/or maintain anything else you deem practical. 13512 13513 All the trigger scripts are launched in a copy of the user sandbox being 13514 committed, on the server, in client-server mode. In local mode, the scripts 13515 are actually launched directly from the user sandbox directory being committed. 13516 For most intents and purposes, the same scripts can be run in both locations 13517 without alteration. 13518 13519 @menu 13520 * syntax:: The common syntax 13521 * Trigger Script Security:: Trigger script security 13522 13523 * commit files:: The commit support files (commitinfo, 13524 verifymsg, loginfo) 13525 * commitinfo:: Pre-commit checking 13526 * verifymsg:: How are log messages evaluated? 13527 * loginfo:: Where should log messages be sent? 13528 13529 * postadmin:: Logging admin commands 13530 * taginfo:: Verifying/Logging tags 13531 * posttag:: Logging tags 13532 * postwatch:: Logging watch commands 13533 13534 * preproxy:: Launch a script on a secondary server prior 13535 to becoming a write proxy 13536 * postproxy:: Launch a script on a secondary server after 13537 completing proxy operations 13538 @end menu 13539 13540 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13541 @node syntax 13542 @appendixsubsec The common syntax 13543 @cindex info files, common syntax 13544 @cindex script hooks, common syntax 13545 @cindex trigger script hooks, common syntax 13546 @cindex syntax of trigger script hooks 13547 13548 @c FIXME: having this so totally separate from the 13549 @c Variables node is rather bogus. 13550 13551 The administrative files such as @file{commitinfo}, 13552 @file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 13553 all have a common format. The purpose of the files are 13554 described later on. The common syntax is described 13555 here. 13556 13557 @cindex Regular expression syntax 13558 Each line contains the following: 13559 13560 @itemize @bullet 13561 @cindex @samp{ALL} keyword, in lieu of regular expressions in script hooks 13562 @cindex @samp{DEFAULT} keyword, in lieu of regular expressions in script hooks 13563 @item 13564 A regular expression or the literal string @samp{DEFAULT}. Some script hooks 13565 also support the literal string @samp{ALL}. Other than the @samp{ALL} and 13566 @samp{DEFAULT} keywords, this is a basic regular expression in the syntax used 13567 by GNU emacs. See the descriptions of the individual script hooks for 13568 information on whether the @samp{ALL} keyword is supported 13569 (@pxref{Trigger Scripts}). 13570 @c FIXME: What we probably should be saying is "POSIX Basic 13571 @c Regular Expression with the following extensions (`\(' 13572 @c `\|' '+' etc)" 13573 @c rather than define it with reference to emacs. 13574 @c The reference to emacs is not strictly speaking 13575 @c true, as we don't support \=, \s, or \S. Also it isn't 13576 @c clear we should document and/or promise to continue to 13577 @c support all the obscure emacs extensions like \<. 13578 @c Also need to better cite (or include) full 13579 @c documentation for the syntax. 13580 @c Also see comment in configure.in about what happens to the 13581 @c syntax if we pick up a system-supplied regexp matcher. 13582 13583 @item 13584 A whitespace separator---one or more spaces and/or tabs. 13585 13586 @item 13587 A file name or command-line template. 13588 @end itemize 13589 13590 @noindent 13591 Blank lines are ignored. Lines that start with the 13592 character @samp{#} are treated as comments. Long lines 13593 unfortunately can @emph{not} be broken in two parts in 13594 any way. 13595 13596 The first regular expression that matches the current 13597 directory name in the repository or the first line containing @samp{DEFAULT} 13598 in lieu of a regular expression is used and all lines containing @samp{ALL} is 13599 used for the hooks which support the @samp{ALL} keyword. The rest of the line 13600 is used as a file name or command-line template as appropriate. See the 13601 descriptions of the individual script hooks for information on whether the 13602 @samp{ALL} keyword is supported (@pxref{Trigger Scripts}). 13603 13604 @cindex format strings 13605 @cindex format strings, common syntax 13606 @cindex info files, common syntax, format strings 13607 @cindex Common syntax of info files, format strings 13608 @noindent 13609 @emph{Note: The following information on format strings is valid 13610 as long as the line @code{UseNewInfoFmtStrings=yes} appears in 13611 your repository's config file (@pxref{config}). Otherwise, 13612 default format strings may be appended to the command line and 13613 the @samp{loginfo} file, especially, can exhibit slightly 13614 different behavior. For more information, 13615 @xref{Updating Commit Files}.} 13616 13617 In the cases where the second segment of the matched line is a 13618 command line template (e.g. @file{commitinfo}, @file{loginfo}, 13619 & @file{verifymsg}), the command line template may contain format 13620 strings which will be replaced with specific values before the 13621 script is run. 13622 @c FIXCVS then FIXME - it really would make sense to allow %r & maybe even %p 13623 @c to be used in rcsinfo to construct a path, but I haven't 13624 @c coded this yet. 13625 13626 Format strings can represent a single variable or one or more 13627 attributes of a list variable. An example of a list variable 13628 would be the list available to scripts hung on the loginfo hooks 13629 - the list of files which were just committed. In the case of 13630 loginfo, three attributes are available for each list item: file 13631 name, precommit version, and postcommit version. 13632 13633 Format strings consist of a @samp{%} character followed by an optional 13634 @samp{@{} (required in the multiple list attribute case), a 13635 single format character representing a variable or a single attribute of 13636 list elements or multiple format characters representing attributes of 13637 list elements, and a closing @samp{@}} when the open bracket was present. 13638 13639 @emph{Flat format strings}, or single format characters which get replaced 13640 with a single value, will generate a single argument 13641 to the called script, regardless of whether the replacement variable contains 13642 white space or other special characters. 13643 13644 @emph{List attributes} will generate an argument for each attribute 13645 requested for each list item. For example, @samp{%@{sVv@}} 13646 in a @file{loginfo} command template will generate three 13647 arguments (file name, precommit version, postcommit version, 13648 ...) for each file committed. As in the flat format string 13649 case, each attribute will be passed in as a single argument 13650 regardless of whether it contains white space or other 13651 special characters. 13652 13653 @samp{%%} will be replaced with a literal @samp{%}. 13654 13655 The format strings available to all script hooks are: 13656 13657 @table @t 13658 @item c 13659 The canonical name of the command being executed. For instance, in the case of 13660 a hook run from @code{cvs up}, @sc{cvs} would replace @samp{%c} with the string 13661 @samp{update} and, in the case of a hook run from @code{cvs ci}, @sc{cvs} would 13662 replace @samp{%c} with the string @samp{commit}. 13663 @item n 13664 The null, or empty, string. 13665 @item p 13666 The name of the directory being operated on within the repository. 13667 @item r 13668 The name of the repository (the path portion of @code{$CVSROOT}). 13669 @item R 13670 On a server, the name of the referrer, if any. The referrer is the CVSROOT the 13671 client reports it used to contact a server which then referred it to this 13672 server. Should usually be set on a primary server with a write proxy setup. 13673 @end table 13674 13675 Other format strings are file specific. See the docs on the 13676 particular script hooks for more information 13677 (@pxref{Trigger Scripts}). 13678 13679 As an example, the following line in a @file{loginfo} file would 13680 match only the directory @file{module} and any subdirectories of 13681 @file{module}: 13682 13683 @example 13684 ^module\(/\|$\) (echo; echo %p; echo %@{sVv@}; cat) >>$CVSROOT/CVSROOT/commitlog 13685 @end example 13686 13687 Using this same line and assuming a commit of new revisions 13688 1.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27, 13689 respectively, of file1 and file2 in module, something like the 13690 following log message should be appended to commitlog: 13691 13692 @example 13693 13694 module 13695 file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1 13696 Update of /cvsroot/module 13697 In directory localhost.localdomain:/home/jrandom/work/module 13698 13699 Modified Files: 13700 file1 file2 13701 Log Message: 13702 A log message. 13703 @end example 13704 13705 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13706 @node Trigger Script Security 13707 @appendixsubsec Security and the Trigger Scripts 13708 @cindex info files, security 13709 @cindex script hooks, security 13710 @cindex trigger scripts, security 13711 13712 Security is a huge subject, and implementing a secure system is a non-trivial 13713 task. This section will barely touch on all the issues involved, but it is 13714 well to note that, as with any script you will be allowing an untrusted 13715 user to run on your server, there are measures you can take to help prevent 13716 your trigger scripts from being abused. 13717 13718 For instance, since the CVS trigger scripts all run in a copy of the user's 13719 sandbox on the server, a naively coded Perl trigger script which attempts to 13720 use a Perl module that is not installed on the system can be hijacked by any 13721 user with commit access who is checking in a file with the correct name. Other 13722 scripting languages may be vulnerable to similar hacks. 13723 13724 One way to make a script more secure, at least with Perl, is to use scripts 13725 which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line. 13726 In the most basic terms, this causes Perl to avoid running code that may have 13727 come from an external source. Please run the @code{perldoc perlsec} command 13728 for more on Perl security. Again, other languages may implement other security 13729 verification hooks which look more or less like Perl's "taint-check" mechanism. 13730 13731 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13732 @node commit files 13733 @appendixsubsec The commit support files 13734 @cindex Commits, administrative support files 13735 @cindex commit files, see Info files 13736 13737 The @samp{-i} flag in the @file{modules} file can be 13738 used to run a certain program whenever files are 13739 committed (@pxref{modules}). The files described in 13740 this section provide other, more flexible, ways to run 13741 programs whenever something is committed. 13742 13743 There are three kinds of programs that can be run on 13744 commit. They are specified in files in the repository, 13745 as described below. The following table summarizes the 13746 file names and the purpose of the corresponding 13747 programs. 13748 13749 @table @file 13750 @item commitinfo 13751 The program is responsible for checking that the commit 13752 is allowed. If it exits with a non-zero exit status 13753 the commit will be aborted. @xref{commitinfo}. 13754 13755 @item verifymsg 13756 The specified program is used to evaluate the log message, 13757 and possibly verify that it contains all required 13758 fields. This is most useful in combination with the 13759 @file{rcsinfo} file, which can hold a log message 13760 template (@pxref{rcsinfo}). @xref{verifymsg}. 13761 13762 @item loginfo 13763 The specified program is called when the commit is 13764 complete. It receives the log message and some 13765 additional information and can store the log message in 13766 a file, or mail it to appropriate persons, or maybe 13767 post it to a local newsgroup, or@dots{} Your 13768 imagination is the limit! @xref{loginfo}. 13769 @end table 13770 13771 @menu 13772 * Updating Commit Files:: Updating legacy repositories to stop using 13773 deprecated command line template formats 13774 @end menu 13775 13776 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13777 @node Updating Commit Files 13778 @appendixsubsubsec Updating legacy repositories to stop using deprecated command line template formats 13779 @cindex info files, common syntax, updating legacy repositories 13780 @cindex Syntax of info files, updating legacy repositories 13781 @cindex Common syntax of info files, updating legacy repositories 13782 New repositories are created set to use the new format strings by default, so 13783 if you are creating a new repository, you shouldn't have to worry about this 13784 section. 13785 13786 If you are attempting to maintain a legacy repository which was 13787 making use of the @file{commitinfo}, @file{editinfo}, @file{verifymsg}, 13788 @file{loginfo}, and/or @file{taginfo} script hooks, you should have no 13789 immediate problems with using the current @sc{cvs} executable, but your users 13790 will probably start to see deprecation warnings. 13791 13792 The reason for this is that all of the script hooks have been updated to 13793 use a new command line parser that extensibly supports multiple 13794 @file{loginfo} & @file{notify} style format strings (@pxref{syntax}) 13795 and this support is not completely compatible with the old style format 13796 strings. 13797 13798 The quick upgrade method is to stick a @samp{1} after each format string 13799 in your old @file{loginfo} file. For example: 13800 13801 @example 13802 DEFAULT (echo ""; id; echo %@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13803 @end example 13804 13805 would become: 13806 13807 @example 13808 DEFAULT (echo ""; id; echo %1@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog 13809 @end example 13810 13811 If you were counting on the fact that only the first @samp{%} in the line was 13812 replaced as a format string, you may also have to double up any further 13813 percent signs on the line. 13814 13815 If you did this all at once and checked it in, everything should still be 13816 running properly. 13817 13818 Now add the following line to your config file (@pxref{config}): 13819 @example 13820 UseNewInfoFmtStrings=yes 13821 @end example 13822 13823 Everything should still be running properly, but your users will probably 13824 start seeing new deprecation warnings. 13825 13826 Dealing with the deprecation warnings now generated by @file{commitinfo}, 13827 @file{editinfo}, @file{verifymsg}, and @file{taginfo} should be easy. Simply 13828 specify what are currently implicit arguments explicitly. This means appending 13829 the following strings to each active command line template in each file: 13830 @table @code 13831 @item commitinfo 13832 @samp{ %r/%p %s} 13833 @item editinfo 13834 @samp{ %l} 13835 @item taginfo 13836 @samp{ %t %o %p %@{sv@}} 13837 @item verifymsg 13838 @samp{ %l} 13839 @end table 13840 13841 If you don't desire that any of the newly available information be passed to 13842 the scripts hanging off of these hooks, no further modifications to these 13843 files should be necessary to insure current and future compatibility with 13844 @sc{cvs}'s format strings. 13845 13846 Fixing @file{loginfo} could be a little tougher. The old style 13847 @file{loginfo} format strings caused a single space and comma separated 13848 argument to be passed in in place of the format string. This is what will 13849 continue to be generated due to the deprecated @samp{1} you inserted into 13850 the format strings. 13851 13852 Since the new format separates each individual item and passes it into the 13853 script as a separate argument (for a good reason - arguments containing commas 13854 and/or white space are now parsable), to remove the deprecated @samp{1} from 13855 your @file{loginfo} command line templates, you will most likely have to 13856 rewrite any scripts called by the hook to handle the new argument format. 13857 13858 Also note that the way @samp{%} followed by unrecognized characters and by 13859 @samp{@{@}} was treated in past versions of CVS is not strictly adhered to as 13860 there were bugs in the old versions. Specifically, @samp{%@{@}} would eat the 13861 next character and unrecognized strings resolved only to the empty string, 13862 which was counter to what was stated in the documentation. This version will 13863 do what the documentation said it should have (if you were using only some 13864 combination of @samp{%@{sVv@}}, e.g. @samp{%@{sVv@}}, @samp{%@{sV@}}, or 13865 @samp{%v}, you should have no troubles). 13866 13867 On the bright side, you should have plenty of time to do this before all 13868 support for the old format strings is removed from @sc{cvs}, so you can just 13869 put up with the deprecation warnings for awhile if you like. 13870 13871 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13872 @node commitinfo 13873 @appendixsubsec Commitinfo 13874 @cindex @file{commitinfo} 13875 @cindex Commits, precommit verification of 13876 @cindex commitinfo (admin file) 13877 @cindex info files, commitinfo 13878 @cindex script hooks, commitinfo 13879 @cindex trigger scripts, commitinfo 13880 @cindex info files, precommit verification of commits 13881 @cindex script hooks, precommit verification of commits 13882 @cindex trigger scripts, precommit verification of commits 13883 13884 The @file{commitinfo} file defines programs to execute 13885 whenever @samp{cvs commit} is about to execute. These 13886 programs are used for pre-commit checking to verify 13887 that the modified, added and removed files are really 13888 ready to be committed. This could be used, for 13889 instance, to verify that the changed files conform to 13890 to your site's standards for coding practice. 13891 13892 The @file{commitinfo} file has the standard form for script hooks 13893 (@pxref{Trigger Scripts}), where each line is a regular expression followed by 13894 a command to execute. It supports only the DEFAULT keywords. 13895 13896 @cindex format strings, commitinfo admin file 13897 In addition to the common format strings (@pxref{syntax}), 13898 @file{commitinfo} supports: 13899 13900 @table @t 13901 @item @{s@} 13902 a list of the names of files to be committed 13903 @end table 13904 13905 @cindex commitinfo (admin file), updating legacy repositories 13906 @cindex compatibility notes, commitinfo admin file 13907 Currently, if no format strings are specified, a default 13908 string of @samp{ %r/%p %@{s@}} will be appended to the command 13909 line template before replacement is performed, but this 13910 feature is deprecated. It is simply in place so that legacy 13911 repositories will remain compatible with the new @sc{cvs} application. 13912 For information on updating, @pxref{Updating Commit Files}. 13913 13914 @cindex Exit status, of commitinfo 13915 @cindex commitinfo (admin file), exit status 13916 The first line with a regular expression matching the 13917 directory within the repository will be used. If the 13918 command returns a non-zero exit status the commit will 13919 be aborted. 13920 @c FIXME: need example(s) of what "directory within the 13921 @c repository" means. 13922 13923 @cindex @file{commitinfo}, working directory 13924 @cindex @file{commitinfo}, command environment 13925 The command will be run in the root of the workspace 13926 containing the new versions of any files the user would like 13927 to modify (commit), @emph{or in a copy of the workspace on 13928 the server (@pxref{Remote repositories})}. If a file is 13929 being removed, there will be no copy of the file under the 13930 current directory. If a file is being added, there will be 13931 no corresponding archive file in the repository unless the 13932 file is being resurrected. 13933 13934 Note that both the repository directory and the corresponding 13935 Attic (@pxref{Attic}) directory may need to be checked to 13936 locate the archive file corresponding to any given file being 13937 committed. Much of the information about the specific commit 13938 request being made, including the destination branch, commit 13939 message, and command line options specified, is not available 13940 to the command. 13941 13942 @c FIXME: should discuss using commitinfo to control 13943 @c who has checkin access to what (e.g. Joe can check into 13944 @c directories a, b, and c, and Mary can check into 13945 @c directories b, c, and d--note this case cannot be 13946 @c conveniently handled with unix groups). Of course, 13947 @c adding a new set of features to CVS might be a more 13948 @c natural way to fix this problem than telling people to 13949 @c use commitinfo. 13950 @c FIXME: Should make some reference, especially in 13951 @c the context of controlling who has access, to the fact 13952 @c that commitinfo can be circumvented. Perhaps 13953 @c mention SETXID (but has it been carefully examined 13954 @c for holes?). This fits in with the discussion of 13955 @c general CVS security in "Password authentication 13956 @c security" (the bit which is not pserver-specific). 13957 13958 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13959 @node verifymsg 13960 @appendixsubsec Verifying log messages 13961 @cindex @file{verifymsg} (admin file) 13962 @cindex Log message, verifying 13963 @cindex logging, commits 13964 13965 Once you have entered a log message, you can evaluate 13966 that message to check for specific content, such as 13967 a bug ID. Use the @file{verifymsg} file to 13968 specify a program that is used to verify the log message. 13969 This program could be a simple script that checks 13970 that the entered message contains the required fields. 13971 13972 The @file{verifymsg} file is often most useful together 13973 with the @file{rcsinfo} file, which can be used to 13974 specify a log message template (@pxref{rcsinfo}). 13975 13976 The @file{verifymsg} file has the standard form for script hooks 13977 (@pxref{Trigger Scripts}), where each line is a regular expression followed by 13978 a command to execute. It supports only the DEFAULT keywords. 13979 13980 @cindex format strings, verifymsg admin file 13981 In addition to the common format strings (@pxref{syntax}), 13982 @file{verifymsg} supports: 13983 13984 @table @t 13985 @item l 13986 the full path to the file containing the log message to be verified 13987 @item @{sV@} 13988 File attributes, where: 13989 @table @t 13990 @item s 13991 file name 13992 @item V 13993 old version number (pre-checkin) 13994 @end table 13995 @end table 13996 13997 @cindex verifymsg (admin/commit file), updating legacy repositories 13998 @cindex compatibility notes, verifymsg admin file 13999 Currently, if no format strings are specified, a default 14000 string of @samp{ %l} will be appended to the command 14001 line template before replacement is performed, but this 14002 feature is deprecated. It is simply in place so that legacy 14003 repositories will remain compatible with the new @sc{cvs} application. 14004 For information on updating, @pxref{Updating Commit Files}. 14005 14006 One thing that should be noted is that the @samp{ALL} 14007 keyword is not supported. If more than one matching 14008 line is found, the first one is used. This can be 14009 useful for specifying a default verification script in a 14010 directory, and then overriding it in a subdirectory. 14011 14012 @cindex Exit status, of @file{verifymsg} 14013 If the verification script exits with a non-zero exit status, 14014 the commit is aborted. 14015 14016 @cindex @file{verifymsg}, changing the log message 14017 In the default configuration, CVS allows the 14018 verification script to change the log message. This is 14019 controlled via the RereadLogAfterVerify CVSROOT/config 14020 option. 14021 14022 When @samp{RereadLogAfterVerify=always} or 14023 @samp{RereadLogAfterVerify=stat}, the log message will 14024 either always be reread after the verification script 14025 is run or reread only if the log message file status 14026 has changed. 14027 14028 @xref{config}, for more on CVSROOT/config options. 14029 14030 It is NOT a good idea for a @file{verifymsg} script to 14031 interact directly with the user in the various 14032 client/server methods. For the @code{pserver} method, 14033 there is no protocol support for communicating between 14034 @file{verifymsg} and the client on the remote end. For the 14035 @code{ext} and @code{server} methods, it is possible 14036 for CVS to become confused by the characters going 14037 along the same channel as the CVS protocol 14038 messages. See @ref{Remote repositories}, for more 14039 information on client/server setups. In addition, at the time 14040 the @file{verifymsg} script runs, the CVS 14041 server has locks in place in the repository. If control is 14042 returned to the user here then other users may be stuck waiting 14043 for access to the repository. 14044 14045 This option can be useful if you find yourself using an 14046 rcstemplate that needs to be modified to remove empty 14047 elements or to fill in default values. It can also be 14048 useful if the rcstemplate has changed in the repository 14049 and the CVS/Template was not updated, but is able to be 14050 adapted to the new format by the verification script 14051 that is run by @file{verifymsg}. 14052 14053 An example of an update might be to change all 14054 occurrences of 'BugId:' to be 'DefectId:' (which can be 14055 useful if the rcstemplate has recently been changed and 14056 there are still checked-out user trees with cached 14057 copies in the CVS/Template file of the older version). 14058 14059 Another example of an update might be to delete a line 14060 that contains 'BugID: none' from the log message after 14061 validation of that value as being allowed is made. 14062 14063 @menu 14064 * verifymsg example:: Verifymsg example 14065 @end menu 14066 14067 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14068 @node verifymsg example 14069 @appendixsubsubsec Verifying log messages 14070 @cindex verifymsg, example 14071 The following is a little silly example of a 14072 @file{verifymsg} file, together with the corresponding 14073 @file{rcsinfo} file, the log message template and a 14074 verification script. We begin with the log message template. 14075 We want to always record a bug-id number on the first 14076 line of the log message. The rest of log message is 14077 free text. The following template is found in the file 14078 @file{/usr/cvssupport/tc.template}. 14079 14080 @example 14081 BugId: 14082 @end example 14083 14084 The script @file{/usr/cvssupport/bugid.verify} is used to 14085 evaluate the log message. 14086 14087 @example 14088 #!/bin/sh 14089 # 14090 # bugid.verify filename 14091 # 14092 # Verify that the log message contains a valid bugid 14093 # on the first line. 14094 # 14095 if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 14096 exit 0 14097 elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 14098 # It is okay to allow commits with 'BugId: none', 14099 # but do not put that text into the real log message. 14100 grep -v '^BugId:[ ]*none$' > $1.rewrite 14101 mv $1.rewrite $1 14102 exit 0 14103 else 14104 echo "No BugId found." 14105 exit 1 14106 fi 14107 @end example 14108 14109 The @file{verifymsg} file contains this line: 14110 14111 @example 14112 ^tc /usr/cvssupport/bugid.verify %l 14113 @end example 14114 14115 The @file{rcsinfo} file contains this line: 14116 14117 @example 14118 ^tc /usr/cvssupport/tc.template 14119 @end example 14120 14121 The @file{config} file contains this line: 14122 14123 @example 14124 RereadLogAfterVerify=always 14125 @end example 14126 14127 14128 14129 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14130 @node loginfo 14131 @appendixsubsec Loginfo 14132 @cindex loginfo (admin file) 14133 @cindex logging, commits 14134 @cindex Storing log messages 14135 @cindex Mailing log messages 14136 @cindex Distributing log messages 14137 @cindex Log messages 14138 14139 The @file{loginfo} file is used to control where log information is sent after 14140 versioned changes are made to repository archive files and after directories 14141 are added ot the repository. @ref{posttag} for how to log tagging 14142 information and @ref{postadmin} for how to log changes due to the @code{admin} 14143 command. 14144 14145 The @file{loginfo} file has the standard form for script hooks 14146 (@pxref{Trigger Scripts}), where each line is a regular expression followed by 14147 a command to execute. It supports the ALL and DEFAULT keywords. 14148 14149 Any specified scripts are called: 14150 14151 @table @code 14152 @item commit 14153 Once per directory, immediately after a successfully completing the commit of 14154 all files within that directory. 14155 @item import 14156 Once per import, immediately after completion of all write operations. 14157 @item add 14158 Immediately after the successful @code{add} of a directory. 14159 @end table 14160 14161 Any script called via @file{loginfo} will be fed the log information on its 14162 standard input. Note that the filter program @strong{must} read @strong{all} 14163 of the log information from its standard input or @sc{cvs} may fail with a 14164 broken pipe signal. 14165 14166 @cindex format strings, loginfo admin file 14167 In addition to the common format strings (@pxref{syntax}), 14168 @file{loginfo} supports: 14169 14170 @table @t 14171 @item @{stVv@} 14172 File attributes, where: 14173 @table @t 14174 @item s 14175 file name 14176 @item T 14177 tag name of destination, or the empty string when there is no associated 14178 tag name (this usually means the trunk) 14179 @item V 14180 old version number (pre-checkin) 14181 @item v 14182 new version number (post-checkin) 14183 @end table 14184 @end table 14185 14186 For example, some valid format strings are @samp{%%}, 14187 @samp{%s}, @samp{%@{s@}}, and @samp{%@{stVv@}}. 14188 14189 @cindex loginfo (admin file), updating legacy repositories 14190 @cindex compatibility notes, loginfo admin file 14191 Currently, if @samp{UseNewInfoFmtStrings} is not set in the @file{config} 14192 administration file (@pxref{config}), the format strings will be substituted 14193 as they were in past versions of @sc{cvs}, but this feature is deprecated. 14194 It is simply in place so that legacy repositories will remain compatible with 14195 the new @sc{cvs} application. For information on updating, 14196 please see @ref{Updating Commit Files}. 14197 14198 As an example, if @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%p} 14199 and @samp{%@{sVv@}} are the format strings, and three files (@t{ChangeLog}, 14200 @t{Makefile}, @t{foo.c}) were modified, the output might be: 14201 14202 @example 14203 yoyodyne/tc ChangeLog 1.1 1.2 Makefile 1.3 1.4 foo.c 1.12 1.13 14204 @end example 14205 14206 Note: when @sc{cvs} is accessing a remote repository, 14207 @file{loginfo} will be run on the @emph{remote} 14208 (i.e., server) side, not the client side (@pxref{Remote 14209 repositories}). 14210 14211 @menu 14212 * loginfo example:: Loginfo example 14213 * Keeping a checked out copy:: Updating a tree on every checkin 14214 @end menu 14215 14216 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14217 @node loginfo example 14218 @appendixsubsubsec Loginfo example 14219 14220 The following @file{loginfo} file, together with the 14221 tiny shell-script below, appends all log messages 14222 to the file @file{$CVSROOT/CVSROOT/commitlog}, 14223 and any commits to the administrative files (inside 14224 the @file{CVSROOT} directory) are also logged in 14225 @file{/usr/adm/cvsroot-log}. 14226 Commits to the @file{prog1} directory are mailed to @t{ceder}. 14227 14228 @c FIXME: is it a CVS feature or bug that only the 14229 @c first matching line is used? It is documented 14230 @c above, but is it useful? For example, if we wanted 14231 @c to run both "cvs-log" and "Mail" for the CVSROOT 14232 @c directory, it is kind of awkward if 14233 @c only the first matching line is used. 14234 @example 14235 ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 14236 ^CVSROOT\(/\|$\) /usr/local/bin/cvs-log /usr/adm/cvsroot-log $USER 14237 ^prog1\(/\|$\) Mail -s "%p %s" ceder 14238 @end example 14239 14240 The shell-script @file{/usr/local/bin/cvs-log} looks 14241 like this: 14242 14243 @example 14244 #!/bin/sh 14245 (echo "------------------------------------------------------"; 14246 echo -n "$2 "; 14247 date; 14248 echo; 14249 cat) >> $1 14250 @end example 14251 14252 14253 14254 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14255 @node Keeping a checked out copy 14256 @appendixsubsubsec Keeping a checked out copy 14257 14258 @c What other index entries? It seems like 14259 @c people might want to use a lot of different 14260 @c words for this functionality. 14261 @cindex Keeping a checked out copy 14262 @cindex Checked out copy, keeping 14263 @cindex Web pages, maintaining with CVS 14264 14265 It is often useful to maintain a directory tree which 14266 contains files which correspond to the latest version 14267 in the repository. For example, other developers might 14268 want to refer to the latest sources without having to 14269 check them out, or you might be maintaining a web site 14270 with @sc{cvs} and want every checkin to cause the files 14271 used by the web server to be updated. 14272 @c Can we offer more details on the web example? Or 14273 @c point the user at how to figure it out? This text 14274 @c strikes me as sufficient for someone who already has 14275 @c some idea of what we mean but not enough for the naive 14276 @c user/sysadmin to understand it and set it up. 14277 14278 The way to do this is by having loginfo invoke 14279 @code{cvs update}. Doing so in the naive way will 14280 cause a problem with locks, so the @code{cvs update} 14281 must be run in the background. 14282 @c Should we try to describe the problem with locks? 14283 @c It seems like a digression for someone who just 14284 @c wants to know how to make it work. 14285 @c Another choice which might work for a single file 14286 @c is to use "cvs -n update -p" which doesn't take 14287 @c out locks (I think) but I don't see many advantages 14288 @c of that and we might as well document something which 14289 @c works for multiple files. 14290 Here is an example for unix (this should all be on one line): 14291 14292 @example 14293 ^cyclic-pages\(/\|$\) (date; cat; (sleep 2; cd /u/www/local-docs; 14294 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 14295 @end example 14296 14297 This will cause checkins to repository directory @code{cyclic-pages} 14298 and its subdirectories to update the checked 14299 out tree in @file{/u/www/local-docs}. 14300 @c More info on some of the details? The "sleep 2" is 14301 @c so if we are lucky the lock will be gone by the time 14302 @c we start and we can wait 2 seconds instead of 30. 14303 14304 14305 14306 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14307 @node postadmin 14308 @appendixsubsec Logging admin commands 14309 @cindex postadmin (admin file) 14310 @cindex script hook, postadmin 14311 @cindex Admin commands, logging 14312 14313 The @file{postadmin} file defines programs to execute after an @code{admin} 14314 command modifies files. The @file{postadmin} file has the standard form 14315 for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14316 expression followed by a command to execute. It supports the ALL and DEFAULT 14317 keywords. 14318 14319 @cindex format strings, postadmin admin file 14320 The @file{postadmin} file supports no format strings other than the common 14321 ones (@pxref{syntax}), 14322 14323 14324 14325 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14326 @node taginfo 14327 @appendixsubsec Taginfo 14328 @cindex taginfo (admin file) 14329 @cindex script hook, taginfo 14330 @cindex Tags, logging 14331 @cindex Tags, verifying 14332 The @file{taginfo} file defines programs to execute 14333 when someone executes a @code{tag} or @code{rtag} 14334 command. The @file{taginfo} file has the standard form 14335 for script hooks (@pxref{Trigger Scripts}), where each line 14336 is a regular expression followed by a command to execute. 14337 It supports the ALL and DEFAULT keywords. 14338 14339 @cindex format strings, taginfo admin file 14340 In addition to the common format strings (@pxref{syntax}), 14341 @file{taginfo} supports: 14342 14343 @table @t 14344 @item b 14345 tag type (@code{T} for branch, @code{N} for not-branch, or @code{?} for 14346 unknown, as during delete operations) 14347 @item o 14348 operation (@code{add} for @code{tag}, @code{mov} for @code{tag -F}, or 14349 @code{del} for @code{tag -d}) 14350 @item t 14351 new tag name 14352 @item @{sTVv@} 14353 file attributes, where: 14354 @table @t 14355 @item s 14356 file name 14357 @item T 14358 tag name of destination, or the empty string when there is no associated 14359 tag name (this usually means the trunk) 14360 @item V 14361 old version number (for a move or delete operation) 14362 @item v 14363 new version number (for an add or move operation) 14364 @end table 14365 @end table 14366 14367 For example, some valid format strings are @samp{%%}, @samp{%p}, @samp{%t}, 14368 @samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 14369 14370 @cindex taginfo (admin file), updating legacy repositories 14371 @cindex compatibility notes, taginfo admin file 14372 Currently, if no format strings are specified, a default 14373 string of @samp{ %t %o %p %@{sv@}} will be appended to the command 14374 line template before replacement is performed, but this 14375 feature is deprecated. It is simply in place so that legacy 14376 repositories will remain compatible with the new @sc{cvs} application. 14377 For information on updating, @pxref{Updating Commit Files}. 14378 14379 @cindex Exit status, of taginfo admin file 14380 @cindex taginfo (admin file), exit status 14381 A non-zero exit of the filter program will cause the tag to be 14382 aborted. 14383 14384 Here is an example of using @file{taginfo} to log @code{tag} and @code{rtag} 14385 commands. In the @file{taginfo} file put: 14386 14387 @example 14388 ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %@{sVv@} 14389 @end example 14390 14391 @noindent 14392 Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 14393 following script: 14394 14395 @example 14396 #!/bin/sh 14397 echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 14398 @end example 14399 14400 14401 14402 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14403 @node posttag 14404 @appendixsubsec Logging tags 14405 @cindex posttag (admin file) 14406 @cindex script hook, posttag 14407 @cindex Tags, logging 14408 14409 The @file{posttag} file defines programs to execute after a @code{tag} or 14410 @code{rtag} command modifies files. The @file{posttag} file has the standard 14411 form for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14412 expression followed by a command to execute. It supports the ALL and DEFAULT 14413 keywords. 14414 14415 @cindex format strings, posttag admin file 14416 The @file{posttag} admin file supports the same format strings as the 14417 @file{taginfo} file (@pxref{taginfo}), 14418 14419 14420 14421 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14422 @node postwatch 14423 @appendixsubsec Logging watch commands 14424 @cindex postwatch (admin file) 14425 @cindex script hook, postwatch 14426 @cindex Watch family of commands, logging 14427 14428 The @file{postwatch} file defines programs to execute after any command (for 14429 instance, @code{watch}, @code{edit}, @code{unedit}, or @code{commit}) modifies 14430 any @file{CVS/fileattr} file in the repository (@pxref{Watches}). The 14431 @file{postwatch} file has the standard form for script hooks 14432 (@pxref{Trigger Scripts}), where each line is a regular expression followed by 14433 a command to execute. It supports the ALL and DEFAULT keywords. 14434 14435 @cindex format strings, postwatch admin file 14436 The @file{postwatch} file supports no format strings other than the common 14437 ones (@pxref{syntax}), but it is worth noting that the @code{%c} format string 14438 may not be replaced as you might expect. Client runs of @code{edit} and 14439 @code{unedit} can sometimes skip contacting the @sc{cvs} server and cache the 14440 notification of the file attribute change to be sent the next time the client 14441 contacts the server for whatever other reason, 14442 14443 14444 14445 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14446 @node preproxy 14447 @appendixsubsec Launch a Script before Proxying 14448 @cindex preproxy (admin file) 14449 @cindex script hook, preproxy 14450 @cindex Write proxy, verifying 14451 @cindex Write proxy, logging 14452 14453 The @file{preproxy} file defines programs to execute after a secondary 14454 server receives a write request from a client, just before it starts up the 14455 primary server and becomes a write proxy. This hook could be used to 14456 dial a modem, launch an SSH tunnel, establish a VPN, or anything else that 14457 might be necessary to do before contacting the primary server. 14458 14459 @file{preproxy} scripts are called once, at the time of the write request, with 14460 the repository argument (if requested) set from the topmost directory sent by 14461 the client. 14462 14463 The @file{preproxy} file has the standard form 14464 for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14465 expression followed by a command to execute. It supports the ALL and DEFAULT 14466 keywords. 14467 14468 @cindex format strings, preproxy admin file 14469 In addition to the common format strings, the @file{preproxy} file supports the 14470 following format string: 14471 14472 @table @t 14473 @item P 14474 the CVSROOT string which specifies the primary server 14475 @end table 14476 14477 14478 14479 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14480 @node postproxy 14481 @appendixsubsec Launch a Script after Proxying 14482 @cindex postproxy (admin file) 14483 @cindex script hook, postproxy 14484 @cindex Write proxy, logging 14485 @cindex Write proxy, pull updates 14486 @cindex secondary server, pull updates 14487 14488 The @file{postproxy} file defines programs to execute after a secondary 14489 server notes that the connection to the primary server has shut down and before 14490 it releases the client by shutting down the connection to the client. 14491 This could hook could be used to 14492 disconnect a modem, an SSH tunnel, a VPN, or anything else that 14493 might be necessary to do after contacting the primary server. This hook should 14494 also be used to pull updates from the primary server before allowing the client 14495 which did the write to disconnect since otherwise the client's next read 14496 request may generate error messages and fail upon encountering an out of date 14497 repository on the secondary server. 14498 14499 @file{postproxy} scripts are called once per directory. 14500 14501 The @file{postproxy} file has the standard form 14502 for script hooks (@pxref{Trigger Scripts}), where each line is a regular 14503 expression followed by a command to execute. It supports the ALL and DEFAULT 14504 keywords. 14505 14506 @cindex format strings, postproxy admin file 14507 In addition to the common format strings, the @file{postproxy} file supports 14508 the following format string: 14509 14510 @table @t 14511 @item P 14512 the CVSROOT string which specifies the primary server 14513 @end table 14514 14515 14516 14517 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14518 @node rcsinfo 14519 @appendixsec Rcsinfo 14520 @cindex rcsinfo (admin file) 14521 @cindex Form for log message 14522 @cindex Log message template 14523 @cindex Template for log message 14524 @cindex logging, commits 14525 14526 The @file{rcsinfo} file can be used to specify a form to 14527 edit when filling out the commit log. The 14528 @file{rcsinfo} file has a syntax similar to the 14529 @file{verifymsg}, @file{commitinfo} and @file{loginfo} 14530 files. @xref{syntax}. Unlike the other files the second 14531 part is @emph{not} a command-line template. Instead, 14532 the part after the regular expression should be a full pathname to 14533 a file containing the log message template. 14534 14535 If the repository name does not match any of the 14536 regular expressions in this file, the @samp{DEFAULT} 14537 line is used, if it is specified. 14538 14539 All occurrences of the name @samp{ALL} appearing as a 14540 regular expression are used in addition to the first 14541 matching regular expression or @samp{DEFAULT}. 14542 14543 @c FIXME: should be offering advice, somewhere around 14544 @c here, about where to put the template file. The 14545 @c verifymsg example uses /usr/cvssupport but doesn't 14546 @c say anything about what that directory is for or 14547 @c whether it is hardwired into CVS or who creates 14548 @c it or anything. In particular we should say 14549 @c how to version control the template file. A 14550 @c probably better answer than the /usr/cvssupport 14551 @c stuff is to use checkoutlist (with xref to the 14552 @c checkoutlist doc). 14553 @c Also I am starting to see a connection between 14554 @c this and the Keeping a checked out copy node. 14555 @c Probably want to say something about that. 14556 The log message template will be used as a default log 14557 message. If you specify a log message with @samp{cvs 14558 commit -m @var{message}} or @samp{cvs commit -f 14559 @var{file}} that log message will override the 14560 template. 14561 14562 @xref{verifymsg}, for an example @file{rcsinfo} 14563 file. 14564 14565 When @sc{cvs} is accessing a remote repository, 14566 the contents of @file{rcsinfo} at the time a directory 14567 is first checked out will specify a template. This 14568 template will be updated on all @samp{cvs update} 14569 commands. It will also be added to new directories 14570 added with a @samp{cvs add new-directory} command. 14571 In versions of @sc{cvs} prior to version 1.12, the 14572 @file{CVS/Template} file was not updated. If the 14573 @sc{cvs} server is at version 1.12 or higher an older 14574 client may be used and the @file{CVS/Template} will 14575 be updated from the server. 14576 14577 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14578 @node cvsignore 14579 @appendixsec Ignoring files via cvsignore 14580 @cindex cvsignore (admin file), global 14581 @cindex Global cvsignore 14582 @cindex Ignoring files 14583 @c -- This chapter should maybe be moved to the 14584 @c tutorial part of the manual? 14585 14586 There are certain file names that frequently occur 14587 inside your working copy, but that you don't want to 14588 put under @sc{cvs} control. Examples are all the object 14589 files that you get while you compile your sources. 14590 Normally, when you run @samp{cvs update}, it prints a 14591 line for each file it encounters that it doesn't know 14592 about (@pxref{update output}). 14593 14594 @sc{cvs} has a list of files (or sh(1) file name patterns) 14595 that it should ignore while running @code{update}, 14596 @code{import} and @code{release}. 14597 @c -- Are those the only three commands affected? 14598 This list is constructed in the following way. 14599 14600 @itemize @bullet 14601 @item 14602 The list is initialized to include certain file name 14603 patterns: names associated with @sc{cvs} 14604 administration, or with other common source control 14605 systems; common names for patch files, object files, 14606 archive files, and editor backup files; and other names 14607 that are usually artifacts of assorted utilities. 14608 Currently, the default list of ignored file name 14609 patterns is: 14610 14611 @cindex Ignored files 14612 @cindex Automatically ignored files 14613 @example 14614 RCS SCCS CVS CVS.adm 14615 RCSLOG cvslog.* 14616 tags TAGS 14617 .make.state .nse_depinfo 14618 *~ #* .#* ,* _$* *$ 14619 *.old *.bak *.BAK *.orig *.rej .del-* 14620 *.a *.olb *.o *.obj *.so *.exe 14621 *.Z *.elc *.ln 14622 core 14623 @end example 14624 14625 @item 14626 The per-repository list in 14627 @file{$CVSROOT/CVSROOT/cvsignore} is appended to 14628 the list, if that file exists. 14629 14630 @item 14631 The per-user list in @file{.cvsignore} in your home 14632 directory is appended to the list, if it exists. 14633 14634 @item 14635 Any entries in the environment variable 14636 @code{$CVSIGNORE} is appended to the list. 14637 14638 @item 14639 Any @samp{-I} options given to @sc{cvs} is appended. 14640 14641 @item 14642 As @sc{cvs} traverses through your directories, the contents 14643 of any @file{.cvsignore} will be appended to the list. 14644 The patterns found in @file{.cvsignore} are only valid 14645 for the directory that contains them, not for 14646 any sub-directories. 14647 @end itemize 14648 14649 In any of the 5 places listed above, a single 14650 exclamation mark (@samp{!}) clears the ignore list. 14651 This can be used if you want to store any file which 14652 normally is ignored by @sc{cvs}. 14653 14654 Specifying @samp{-I !} to @code{cvs import} will import 14655 everything, which is generally what you want to do if 14656 you are importing files from a pristine distribution or 14657 any other source which is known to not contain any 14658 extraneous files. However, looking at the rules above 14659 you will see there is a fly in the ointment; if the 14660 distribution contains any @file{.cvsignore} files, then 14661 the patterns from those files will be processed even if 14662 @samp{-I !} is specified. The only workaround is to 14663 remove the @file{.cvsignore} files in order to do the 14664 import. Because this is awkward, in the future 14665 @samp{-I !} might be modified to override 14666 @file{.cvsignore} files in each directory. 14667 14668 Note that the syntax of the ignore files consists of a 14669 series of lines, each of which contains a space 14670 separated list of filenames. This offers no clean way 14671 to specify filenames which contain spaces, but you can 14672 use a workaround like @file{foo?bar} to match a file 14673 named @file{foo bar} (it also matches @file{fooxbar} 14674 and the like). Also note that there is currently no 14675 way to specify comments. 14676 @c FIXCVS? I don't _like_ this syntax at all, but 14677 @c changing it raises all the usual compatibility 14678 @c issues and I'm also not sure what to change it to. 14679 14680 @node checkoutlist 14681 @appendixsec The checkoutlist file 14682 @cindex checkoutlist 14683 14684 It may be helpful to use @sc{cvs} to maintain your own 14685 files in the @file{CVSROOT} directory. For example, 14686 suppose that you have a script @file{logcommit.pl} 14687 which you run by including the following line in the 14688 @file{commitinfo} administrative file: 14689 14690 @example 14691 ALL $CVSROOT/CVSROOT/logcommit.pl %r/%p %s 14692 @end example 14693 14694 To maintain @file{logcommit.pl} with @sc{cvs} you would 14695 add the following line to the @file{checkoutlist} 14696 administrative file: 14697 14698 @example 14699 logcommit.pl 14700 @end example 14701 14702 The format of @file{checkoutlist} is one line for each 14703 file that you want to maintain using @sc{cvs}, giving 14704 the name of the file, followed optionally by more whitespace 14705 and any error message that should print if the file cannot be 14706 checked out into CVSROOT after a commit: 14707 14708 @example 14709 logcommit.pl Could not update CVSROOT/logcommit.pl. 14710 @end example 14711 14712 After setting up @file{checkoutlist} in this fashion, 14713 the files listed there will function just like 14714 @sc{cvs}'s built-in administrative files. For example, 14715 when checking in one of the files you should get a 14716 message such as: 14717 14718 @example 14719 cvs commit: Rebuilding administrative file database 14720 @end example 14721 14722 @noindent 14723 and the checked out copy in the @file{CVSROOT} 14724 directory should be updated. 14725 14726 Note that listing @file{passwd} (@pxref{Password 14727 authentication server}) in @file{checkoutlist} is not 14728 recommended for security reasons. 14729 14730 For information about keeping a checkout out copy in a 14731 more general context than the one provided by 14732 @file{checkoutlist}, see @ref{Keeping a checked out 14733 copy}. 14734 14735 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 14736 @node history file 14737 @appendixsec The history file 14738 @cindex History file 14739 @cindex Log information, saving 14740 14741 By default, the file @file{$CVSROOT/CVSROOT/history} is used 14742 to log information for the @code{history} command (@pxref{history}). 14743 This file name may be changed with the @samp{HistoryLogPath} and 14744 @samp{HistorySearchPath} config options (@pxref{config}). 14745 14746 The file format of the @file{history} file is 14747 documented only in comments in the @sc{cvs} source 14748 code, but generally programs should use the @code{cvs 14749 history} command to access it anyway, in case the 14750 format changes with future releases of @sc{cvs}. 14751 14752 @node Variables 14753 @appendixsec Expansions in administrative files 14754 @cindex Internal variables 14755 @cindex Variables 14756 14757 Sometimes in writing an administrative file, you might 14758 want the file to be able to know various things based 14759 on environment @sc{cvs} is running in. There are 14760 several mechanisms to do that. 14761 14762 To find the home directory of the user running @sc{cvs} 14763 (from the @code{HOME} environment variable), use 14764 @samp{~} followed by @samp{/} or the end of the line. 14765 Likewise for the home directory of @var{user}, use 14766 @samp{~@var{user}}. These variables are expanded on 14767 the server machine, and don't get any reasonable 14768 expansion if pserver (@pxref{Password authenticated}) 14769 is in use; therefore user variables (see below) may be 14770 a better choice to customize behavior based on the user 14771 running @sc{cvs}. 14772 @c Based on these limitations, should we deprecate ~? 14773 @c What is it good for? Are people using it? 14774 14775 One may want to know about various pieces of 14776 information internal to @sc{cvs}. A @sc{cvs} internal 14777 variable has the syntax @code{$@{@var{variable}@}}, 14778 where @var{variable} starts with a letter and consists 14779 of alphanumeric characters and @samp{_}. If the 14780 character following @var{variable} is a 14781 non-alphanumeric character other than @samp{_}, the 14782 @samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 14783 internal variables are: 14784 14785 @table @code 14786 @item CVSROOT 14787 @cindex CVSROOT, internal variable 14788 This is the absolute path to the current @sc{cvs} root directory. 14789 @xref{Repository}, for a description of the various 14790 ways to specify this, but note that the internal 14791 variable contains just the directory and not any 14792 of the access method information. 14793 14794 @item RCSBIN 14795 @cindex RCSBIN, internal variable 14796 In @sc{cvs} 1.9.18 and older, this specified the 14797 directory where @sc{cvs} was looking for @sc{rcs} 14798 programs. Because @sc{cvs} no longer runs @sc{rcs} 14799 programs, specifying this internal variable is now an 14800 error. 14801 14802 @item CVSEDITOR 14803 @cindex CVSEDITOR, internal variable 14804 @itemx EDITOR 14805 @cindex EDITOR, internal variable 14806 @itemx VISUAL 14807 @cindex VISUAL, internal variable 14808 These all expand to the same value, which is the editor 14809 that @sc{cvs} is using. @xref{Global options}, for how 14810 to specify this. 14811 14812 @item USER 14813 @cindex USER, internal variable 14814 Username of the user running @sc{cvs} (on the @sc{cvs} 14815 server machine). 14816 When using pserver, this is the user specified in the repository 14817 specification which need not be the same as the username the 14818 server is running as (@pxref{Password authentication server}). 14819 Do not confuse this with the environment variable of the same name. 14820 14821 @item SESSIONID 14822 @cindex COMMITID, internal variable 14823 Unique Session ID of the @sc{cvs} process. This is a 14824 random string of printable characters of at least 16 14825 characters length. Users should assume that it may 14826 someday grow to at most 256 characters in length. 14827 14828 @item COMMITID 14829 @cindex COMMITID, internal variable 14830 Unique Session ID of the @sc{cvs} process. This is a 14831 random string of printable characters of at least 16 14832 characters length. Users should assume that it may 14833 someday grow to at most 256 characters in length. 14834 @end table 14835 14836 If you want to pass a value to the administrative files 14837 which the user who is running @sc{cvs} can specify, 14838 use a user variable. 14839 @cindex User variables 14840 To expand a user variable, the 14841 administrative file contains 14842 @code{$@{=@var{variable}@}}. To set a user variable, 14843 specify the global option @samp{-s} to @sc{cvs}, with 14844 argument @code{@var{variable}=@var{value}}. It may be 14845 particularly useful to specify this option via 14846 @file{.cvsrc} (@pxref{~/.cvsrc}). 14847 14848 For example, if you want the administrative file to 14849 refer to a test directory you might create a user 14850 variable @code{TESTDIR}. Then if @sc{cvs} is invoked 14851 as 14852 14853 @example 14854 cvs -s TESTDIR=/work/local/tests 14855 @end example 14856 14857 @noindent 14858 and the 14859 administrative file contains @code{sh 14860 $@{=TESTDIR@}/runtests}, then that string is expanded 14861 to @code{sh /work/local/tests/runtests}. 14862 14863 All other strings containing @samp{$} are reserved; 14864 there is no way to quote a @samp{$} character so that 14865 @samp{$} represents itself. 14866 14867 Environment variables passed to administrative files are: 14868 14869 @table @code 14870 @cindex environment variables, passed to administrative files 14871 14872 @item CVS_USER 14873 @cindex CVS_USER, environment variable 14874 The @sc{cvs}-specific username provided by the user, if it 14875 can be provided (currently just for the pserver access 14876 method), and to the empty string otherwise. (@code{CVS_USER} 14877 and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 14878 is used to map @sc{cvs} usernames to system usernames.) 14879 14880 @item LOGNAME 14881 @cindex LOGNAME, environment variable 14882 The username of the system user. 14883 14884 @item USER 14885 @cindex USER, environment variable 14886 Same as @code{LOGNAME}. 14887 Do not confuse this with the internal variable of the same name. 14888 @end table 14889 14890 @node config 14891 @appendixsec The CVSROOT/config configuration file 14892 14893 @cindex configuration file 14894 @cindex config, in CVSROOT 14895 @cindex CVSROOT/config 14896 14897 Usually, the @file{config} file is found at @file{$CVSROOT/CVSROOT/config}, 14898 but this may be overridden on the @code{pserver} and @code{server} command 14899 lines (@pxref{server & pserver}). 14900 14901 The administrative file @file{config} contains various 14902 miscellaneous settings which affect the behavior of 14903 @sc{cvs}. The syntax is slightly different from the 14904 other administrative files. 14905 14906 Leading white space on any line is ignored, though the syntax is very strict 14907 and will reject spaces and tabs almost anywhere else. 14908 14909 Empty lines, lines containing nothing but white space, and lines which start 14910 with @samp{#} (discounting any leading white space) are ignored. 14911 14912 @c FIXME: where do we define comments for the other 14913 @c administrative files. 14914 Other lines consist of the optional leading white space, a keyword, @samp{=}, 14915 and a value. Please note again that this syntax is very strict. 14916 Extraneous spaces or tabs, other than the leading white space, are not 14917 permitted on these lines. 14918 @c See comments in parseinfo.c:parse_config for more 14919 @c discussion of this strictness. 14920 14921 As of CVS 1.12.13, lines of the form @samp{[@var{CVSROOT}]} mark the subsequent 14922 section of the config file as applying only to certain repositories. Multiple 14923 @samp{[@var{CVSROOT}]} lines without intervening 14924 @samp{@var{KEYWORD}=@var{VALUE}} pairs cause processing to fall through, 14925 processing subsequent keywords for any root in the list. Finally, keywords 14926 and values which appear before any @samp{[@var{CVSROOT}]} lines are defaults, 14927 and may to apply to any repository. For example, consider the following file: 14928 14929 @example 14930 # Defaults 14931 LogHistory=TMAR 14932 14933 [/cvsroots/team1] 14934 LockDir=/locks/team1 14935 14936 [/cvsroots/team2] 14937 LockDir=/locks/team2 14938 14939 [/cvsroots/team3] 14940 LockDir=/locks/team3 14941 14942 [/cvsroots/team4] 14943 LockDir=/locks/team4 14944 14945 [/cvsroots/team3] 14946 [/cvsroots/team4] 14947 # Override logged commands for teams 3 & 4. 14948 LogHistory=all 14949 @end example 14950 14951 This example file sets up separate lock directories for each project, as well 14952 as a default set of logged commands overridden for the example's team 3 & 14953 team 4. This syntax could be useful, for instance, if you wished to share a 14954 single config file, for instance @file{/etc/cvs.conf}, among several 14955 repositories. 14956 14957 Currently defined keywords are: 14958 14959 @table @code 14960 @cindex HistoryLogPath, in CVSROOT/config 14961 @item HistorySearchPath=@var{pattern} 14962 Request that @sc{cvs} look for its history information in files matching 14963 @var{pattern}, which is a standard UNIX file glob. If @var{pattern} matches 14964 multiple files, all will be searched in lexicographically sorted order. 14965 @xref{history}, and @ref{history file}, for more. 14966 14967 If no value is supplied for this option, it defaults to 14968 @file{$CVSROOT/CVSROOT/history}. 14969 14970 @cindex HistorySearchPath, in CVSROOT/config 14971 @item HistoryLogPath=@var{path} 14972 Control where @sc{cvs} logs its history. If the file does not exist, @sc{cvs} 14973 will attempt to create it. Format strings, as available to the GNU C 14974 @code{strftime} function and often the UNIX date command, and the string 14975 @var{$CVSROOT} will be substituted in this path. For example, consider the 14976 line: 14977 14978 @example 14979 HistoryLogPath=$CVSROOT/CVSROOT/history/%Y-%m-%d 14980 @end example 14981 14982 This line would cause @sc{cvs} to attempt to create its history file in a 14983 subdirectory (@file{history}) of the configuration directory (@file{CVSROOT}) 14984 with a name equal to the current date representation in the ISO8601 format (for 14985 example, on May 11, 2005, @sc{cvs} would attempt to log its history under the 14986 repository root directory in a file named @file{CVSROOT/history/2005-05-11}). 14987 @xref{history}, and @ref{history file}, for more. 14988 14989 If no value is supplied for this option, it defaults to 14990 @file{$CVSROOT/CVSROOT/history}. 14991 14992 @cindex ImportNewFilesToVendorBranchOnly, in CVSROOT/config 14993 @cindex import, config admin file 14994 @cindex config (admin file), import 14995 @item ImportNewFilesToVendorBranchOnly=@var{value} 14996 Specify whether @code{cvs import} should always behave as if the 14997 @samp{-X} flag was specified on the command line. 14998 @var{value} may be either @samp{yes} or @samp{no}. If set to @samp{yes}, 14999 all uses of @code{cvs import} on the repository will behave as if the 15000 @samp{-X} flag was set. The default value is @samp{no}. 15001 15002 @cindex KeywordExpand, in CVSROOT/config 15003 @item KeywordExpand=@var{value} 15004 Specify @samp{i} followed by a list of keywords to be expanded 15005 (for example, @samp{KeywordExpand=iMYCVS,Name,Date}), 15006 or @samp{e} followed by a list of keywords not to be expanded 15007 (for example, @samp{KeywordExpand=eCVSHeader}). 15008 For more on keyword expansion, see @ref{Configuring keyword expansion}. 15009 15010 @cindex LocalKeyword, in CVSROOT/config 15011 @item LocalKeyword=@var{value} 15012 Specify a local alias for a standard keyword. 15013 For example, @samp{LocalKeyword=MYCVS=CVSHeader}. 15014 For more on local keywords, see @ref{Keyword substitution}. 15015 15016 @cindex LockDir, in CVSROOT/config 15017 @item LockDir=@var{directory} 15018 Put @sc{cvs} lock files in @var{directory} rather than 15019 directly in the repository. This is useful if you want 15020 to let users read from the repository while giving them 15021 write access only to @var{directory}, not to the 15022 repository. 15023 It can also be used to put the locks on a very fast 15024 in-memory file system to speed up locking and unlocking 15025 the repository. 15026 You need to create @var{directory}, but 15027 @sc{cvs} will create subdirectories of @var{directory} as it 15028 needs them. For information on @sc{cvs} locks, see 15029 @ref{Concurrency}. 15030 15031 @c Mention this in Compatibility section? 15032 Before enabling the LockDir option, make sure that you 15033 have tracked down and removed any copies of @sc{cvs} 1.9 or 15034 older. Such versions neither support LockDir, nor will 15035 give an error indicating that they don't support it. 15036 The result, if this is allowed to happen, is that some 15037 @sc{cvs} users will put the locks one place, and others will 15038 put them another place, and therefore the repository 15039 could become corrupted. @sc{cvs} 1.10 does not support 15040 LockDir but it will print a warning if run on a 15041 repository with LockDir enabled. 15042 15043 @cindex LogHistory, in CVSROOT/config 15044 @item LogHistory=@var{value} 15045 Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). 15046 Default of @samp{TOEFWUPCGMARX} (or simply @samp{all}) will log 15047 all transactions. Any subset of the default is 15048 legal. (For example, to only log transactions that modify the 15049 @file{*,v} files, use @samp{LogHistory=TMAR}.) To disable history logging 15050 completely, use @samp{LogHistory=}. 15051 15052 @cindex MaxCommentLeaderLength, in CVSROOT/config 15053 @cindex Log keyword, configuring substitution behavior 15054 @item MaxCommentLeaderLength=@var{length} 15055 Set to some length, in bytes, where a trailing @samp{k}, @samp{M}, @samp{G}, 15056 or @samp{T} causes the preceding nubmer to be interpreted as kilobytes, 15057 megabytes, gigabytes, or terrabytes, respectively, will cause 15058 @code{$@splitrcskeyword{Log}$} keywords (@pxref{Keyword substitution}), with 15059 more than @var{length} bytes preceding it on a line to be ignored (or to fall 15060 back on the comment leader set in the RCS archive file - see 15061 @code{UseArchiveCommentLeader} below). Defaults to 20 bytes to allow checkouts 15062 to proceed normally when they include binary files containing 15063 @code{$@splitrcskeyword{Log}$} keywords and which users have neglected to mark 15064 as binary. 15065 15066 @cindex MinCompressionLevel, in CVSROOT/config 15067 @cindex MaxCompressionLevel, in CVSROOT/config 15068 @cindex Compression levels, restricting on server 15069 @item MinCompressionLevel=@var{value} 15070 @itemx MaxCompressionLevel=@var{value} 15071 Restricts the level of compression used by the @sc{cvs} server to a @var{value} 15072 between 0 and 9. @var{value}s 1 through 9 are the same @sc{zlib} compression 15073 levels accepted by the @samp{-z} option (@pxref{Global options}), and 0 means 15074 no compression. When one or both of these keys are set and a client requests a 15075 level outside the specified range, the server will simply use the closest 15076 permissable level. Clients will continue compressing at the level requested by 15077 the user. 15078 15079 The exception is when level 0 (no compression) is not available and the client 15080 fails to request any compression. The @sc{cvs} server will then exit with an 15081 error message when it becomes apparent that the client is not going to request 15082 compression. This will not happen with clients version 1.12.13 and later since 15083 these client versions allow the server to notify them that they must request 15084 some level of compression. 15085 15086 @ignore 15087 @cindex PreservePermissions, in CVSROOT/config 15088 @item PreservePermissions=@var{value} 15089 Enable support for saving special device files, 15090 symbolic links, file permissions and ownerships in the 15091 repository. The default value is @samp{no}. 15092 @xref{Special Files}, for the full implications of using 15093 this keyword. 15094 @end ignore 15095 15096 @cindex PrimaryServer, in CVSROOT/config 15097 @cindex Primary server 15098 @cindex Secondary server 15099 @cindex proxy, write 15100 @cindex write proxy 15101 @item PrimaryServer=@var{CVSROOT} 15102 When specified, and the repository specified by @var{CVSROOT} is not the one 15103 currently being accessed, then the server will turn itself into a transparent 15104 proxy to @var{CVSROOT} for write requests. The @var{hostname} configured as 15105 part of @var{CVSROOT} must resolve to the same string returned by the 15106 @command{uname} command on the primary server for this to work. Host name 15107 resolution is performed via some combination of @command{named}, a broken out 15108 line from @file{/etc/hosts}, and the Network Information Service (NIS or YP), 15109 depending on the configuration of the particular system. 15110 15111 Only the @samp{:ext:} method is 15112 currently supported for primaries (actually, @samp{:fork:} is supported as 15113 well, but only for testing - if you find another use for accessing a primary 15114 via the @samp{:fork:} method, please send a note to @email{bug-cvs@@nongnu.org} 15115 about it). See @ref{Write proxies} for more on configuring and using write 15116 proxies. 15117 15118 @cindex RCSBIN, in CVSROOT/config 15119 @item RCSBIN=@var{bindir} 15120 For @sc{cvs} 1.9.12 through 1.9.18, this setting told 15121 @sc{cvs} to look for @sc{rcs} programs in the 15122 @var{bindir} directory. Current versions of @sc{cvs} 15123 do not run @sc{rcs} programs; for compatibility this 15124 setting is accepted, but it does nothing. 15125 15126 @cindex RereadLogAfterVerify, in CVSROOT/config 15127 @cindex @file{verifymsg}, changing the log message 15128 @item RereadLogAfterVerify=@var{value} 15129 Modify the @samp{commit} command such that CVS will reread the 15130 log message after running the program specified by @file{verifymsg}. 15131 @var{value} may be one of @samp{yes} or @samp{always}, indicating that 15132 the log message should always be reread; @samp{no} 15133 or @samp{never}, indicating that it should never be 15134 reread; or @var{value} may be @samp{stat}, indicating 15135 that the file should be checked with the file system 15136 @samp{stat()} function to see if it has changed (see warning below) 15137 before rereading. The default value is @samp{always}. 15138 15139 @strong{Note: the `stat' mode can cause CVS to pause for up to 15140 one extra second per directory committed. This can be less IO and 15141 CPU intensive but is not recommended for use with large repositories} 15142 15143 @xref{verifymsg}, for more information on how verifymsg 15144 may be used. 15145 15146 @cindex SystemAuth, in CVSROOT/config 15147 @item SystemAuth=@var{value} 15148 If @var{value} is @samp{yes}, then pserver should check 15149 for users in the system's user database if not found in 15150 @file{CVSROOT/passwd}. If it is @samp{no}, then all 15151 pserver users must exist in @file{CVSROOT/passwd}. 15152 The default is @samp{yes}. For more on pserver, see 15153 @ref{Password authenticated}. 15154 15155 @cindex TmpDir, in config 15156 @cindex temporary files, location of 15157 @cindex temporary directory, set in config 15158 @item TmpDir=@var{path} 15159 Specify @var{path} as the directory to create temporary files in. 15160 @xref{Global options}, for more on setting the path to the temporary 15161 directory. This option first appeared with @sc{cvs} release 1.12.13. 15162 15163 @cindex TopLevelAdmin, in CVSROOT/config 15164 @item TopLevelAdmin=@var{value} 15165 Modify the @samp{checkout} command to create a 15166 @samp{CVS} directory at the top level of the new 15167 working directory, in addition to @samp{CVS} 15168 directories created within checked-out directories. 15169 The default value is @samp{no}. 15170 15171 This option is useful if you find yourself performing 15172 many commands at the top level of your working 15173 directory, rather than in one of the checked out 15174 subdirectories. The @file{CVS} directory created there 15175 will mean you don't have to specify @code{CVSROOT} for 15176 each command. It also provides a place for the 15177 @file{CVS/Template} file (@pxref{Working directory 15178 storage}). 15179 15180 @cindex UseArchiveCommentLeader, in CVSROOT/config 15181 @cindex Log keyword, configuring substitution behavior 15182 @item UseArchiveCommentLeader=@var{value} 15183 Set to @code{true}, if the text preceding a @code{$@splitrcskeyword{Log}$} 15184 keyword is found to exceed @code{MaxCommentLeaderLength} (above) bytes, then 15185 the comment leader set in the RCS archive file (@pxref{admin}), if any, will 15186 be used instead. If there is no comment leader set in the archive file or 15187 @var{value} is set to @samp{false}, then the keyword will not be expanded 15188 (@pxref{Keyword list}). To force the comment leader in the RCS archive file to 15189 be used exclusively (and @code{$@splitrcskeyword{Log}$} expansion skipped in 15190 files where the comment leader has not been set in the archive file), set 15191 @var{value} and set @code{MaxCommentLeaderLength} to @code{0}. 15192 15193 @cindex UseNewInfoFmtStrings, in CVSROOT/config 15194 @cindex format strings, config admin file 15195 @cindex config (admin file), updating legacy repositories 15196 @cindex compatibility notes, config admin file 15197 @item UseNewInfoFmtStrings=@var{value} 15198 Specify whether @sc{cvs} should support the new or old command line 15199 template model for the commit support files (@pxref{commit files}). 15200 This configuration variable began life in deprecation and is only here 15201 in order to give people time to update legacy repositories to use the new 15202 format string syntax before support for the old syntax is removed. For 15203 information on updating your repository to support the new model, 15204 please see @ref{Updating Commit Files}. 15205 15206 @emph{Note that new repositories (created with the @code{cvs init} command) 15207 will have this value set to @samp{yes}, but the default value is @samp{no}.} 15208 15209 @cindex UserAdminOptions, in CVSROOT/config 15210 @item UserAdminOptions=@var{value} 15211 Control what options will be allowed with the @code{cvs admin} 15212 command (@pxref{admin}) for users not in the @code{cvsadmin} group. 15213 The @var{value} string is a list of single character options 15214 which should be allowed. If a user who is not a member of the 15215 @code{cvsadmin} group tries to execute any @code{cvs admin} 15216 option which is not listed they will will receive an error message 15217 reporting that the option is restricted. 15218 15219 If no @code{cvsadmin} group exists on the server, @sc{cvs} will 15220 ignore the @code{UserAdminOptions} keyword (@pxref{admin}). 15221 15222 When not specified, @code{UserAdminOptions} defaults to 15223 @samp{k}. In other words, it defaults to allowing 15224 users outside of the @code{cvsadmin} group to use the 15225 @code{cvs admin} command only to change the default keyword 15226 expansion mode for files. 15227 15228 As an example, to restrict users not in the @code{cvsadmin} 15229 group to using @code{cvs admin} to change the default keyword 15230 substitution mode, lock revisions, unlock revisions, and 15231 replace the log message, use @samp{UserAdminOptions=klum}. 15232 @end table 15233 15234 15235 15236 @c --------------------------------------------------------------------- 15237 @node Environment variables 15238 @appendix All environment variables which affect CVS 15239 @cindex Environment variables 15240 @cindex Reference manual for variables 15241 15242 This is a complete list of all environment variables 15243 that affect @sc{cvs} (Windows users, please bear with this list; 15244 $VAR is equivalent to %VAR% at the Windows command prompt). 15245 15246 @table @code 15247 @cindex CVSIGNORE, environment variable 15248 @item $CVSIGNORE 15249 A whitespace-separated list of file name patterns that 15250 @sc{cvs} should ignore. @xref{cvsignore}. 15251 15252 @cindex CVSWRAPPERS, environment variable 15253 @item $CVSWRAPPERS 15254 A whitespace-separated list of file name patterns that 15255 @sc{cvs} should treat as wrappers. @xref{Wrappers}. 15256 15257 @cindex CVSREAD, environment variable 15258 @cindex Read-only files, and CVSREAD 15259 @item $CVSREAD 15260 If this is set, @code{checkout} and @code{update} will 15261 try hard to make the files in your working directory 15262 read-only. When this is not set, the default behavior 15263 is to permit modification of your working files. 15264 15265 @cindex CVSREADONLYFS, environment variable 15266 @item $CVSREADONLYFS 15267 Turns on read-only repository mode. This allows one to 15268 check out from a read-only repository, such as within 15269 an anoncvs server, or from a @sc{cd-rom} repository. 15270 15271 It has the same effect as if the @samp{-R} command-line 15272 option is used. This can also allow the use of 15273 read-only NFS repositories. 15274 15275 @item $CVSUMASK 15276 Controls permissions of files in the repository. See 15277 @ref{File permissions}. 15278 15279 @item $CVSROOT 15280 Should contain the full pathname to the root of the @sc{cvs} 15281 source repository (where the @sc{rcs} files are 15282 kept). This information must be available to @sc{cvs} for 15283 most commands to execute; if @code{$CVSROOT} is not set, 15284 or if you wish to override it for one invocation, you 15285 can supply it on the command line: @samp{cvs -d cvsroot 15286 cvs_command@dots{}} Once you have checked out a working 15287 directory, @sc{cvs} stores the appropriate root (in 15288 the file @file{CVS/Root}), so normally you only need to 15289 worry about this when initially checking out a working 15290 directory. 15291 15292 @item $CVSEDITOR 15293 @cindex CVSEDITOR, environment variable 15294 @itemx $EDITOR 15295 @cindex EDITOR, environment variable 15296 @itemx $VISUAL 15297 @cindex VISUAL, environment variable 15298 Specifies the program to use for recording log messages 15299 during commit. @code{$CVSEDITOR} overrides 15300 @code{$EDITOR}, which overrides @code{$VISUAL}. 15301 See @ref{Committing your changes} for more or 15302 @ref{Global options} for alternative ways of specifying a 15303 log editor. 15304 15305 @cindex PATH, environment variable 15306 @item $PATH 15307 If @code{$RCSBIN} is not set, and no path is compiled 15308 into @sc{cvs}, it will use @code{$PATH} to try to find all 15309 programs it uses. 15310 15311 @cindex HOME, environment variable 15312 @item $HOME 15313 @cindex HOMEPATH, environment variable 15314 @item $HOMEPATH 15315 @cindex HOMEDRIVE, environment variable 15316 @item $HOMEDRIVE 15317 Used to locate the directory where the @file{.cvsrc} 15318 file, and other such files, are searched. On Unix, @sc{cvs} 15319 just checks for @code{HOME}. On Windows NT, the system will 15320 set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 15321 for example to @file{\joe}. On Windows 95, you'll 15322 probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 15323 @c We are being vague about whether HOME works on 15324 @c Windows; see long comment in windows-NT/filesubr.c. 15325 15326 @cindex CVS_RSH, environment variable 15327 @item $CVS_RSH 15328 Specifies the external program which @sc{cvs} connects with, 15329 when @code{:ext:} access method is specified. 15330 @pxref{Connecting via rsh}. 15331 15332 @item $CVS_SERVER 15333 Used in client-server mode when accessing a remote 15334 repository using @sc{rsh}. It specifies the name of 15335 the program to start on the server side (and any 15336 necessary arguments) when accessing a remote repository 15337 using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 15338 The default value for @code{:ext:} and @code{:server:} is @code{cvs}; 15339 the default value for @code{:fork:} is the name used to run the client. 15340 @pxref{Connecting via rsh} 15341 15342 @item $CVS_PASSFILE 15343 Used in client-server mode when accessing the @code{cvs 15344 login server}. Default value is @file{$HOME/.cvspass}. 15345 @pxref{Password authentication client} 15346 15347 @cindex CVS_CLIENT_PORT 15348 @item $CVS_CLIENT_PORT 15349 Used in client-server mode to set the port to use when accessing the server 15350 via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 15351 if the port is not specified in the CVSROOT. 15352 @pxref{Remote repositories} 15353 15354 @cindex CVS_PROXY_PORT 15355 @item $CVS_PROXY_PORT 15356 Used in client-server mode to set the port to use when accessing a server 15357 via a web proxy, if the port is not specified in the CVSROOT. Works with 15358 GSSAPI, and the password authentication protocol. 15359 @pxref{Remote repositories} 15360 15361 @cindex CVS_RCMD_PORT, environment variable 15362 @item $CVS_RCMD_PORT 15363 Used in client-server mode. If set, specifies the port 15364 number to be used when accessing the @sc{rcmd} demon on 15365 the server side. (Currently not used for Unix clients). 15366 15367 @cindex CVS_CLIENT_LOG, environment variable 15368 @item $CVS_CLIENT_LOG 15369 Used for debugging only in client-server 15370 mode. If set, everything sent to the server is logged 15371 into @file{@code{$CVS_CLIENT_LOG}.in} and everything 15372 sent from the server is logged into 15373 @file{@code{$CVS_CLIENT_LOG}.out}. 15374 15375 @cindex CVS_SERVER_SLEEP, environment variable 15376 @item $CVS_SERVER_SLEEP 15377 Used only for debugging the server side in 15378 client-server mode. If set, delays the start of the 15379 server child process the specified amount of 15380 seconds so that you can attach to it with a debugger. 15381 15382 @cindex CVS_IGNORE_REMOTE_ROOT, environment variable 15383 @item $CVS_IGNORE_REMOTE_ROOT 15384 For @sc{cvs} 1.10 and older, setting this variable 15385 prevents @sc{cvs} from overwriting the @file{CVS/Root} 15386 file when the @samp{-d} global option is specified. 15387 Later versions of @sc{cvs} do not rewrite 15388 @file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 15389 effect. 15390 15391 @cindex CVS_LOCAL_BRANCH_NUM, environment variable 15392 @item $CVS_LOCAL_BRANCH_NUM 15393 Setting this variable allows some control over the 15394 branch number that is assigned. This is specifically to 15395 support the local commit feature of CVSup. If one sets 15396 @code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches 15397 the local repository, the revision numbers will look 15398 like 1.66.1000.xx. There is almost a dead-set certainty 15399 that there will be no conflicts with version numbers. 15400 15401 @cindex COMSPEC, environment variable 15402 @item $COMSPEC 15403 Used under OS/2 only. It specifies the name of the 15404 command interpreter and defaults to @sc{cmd.exe}. 15405 15406 @cindex TMPDIR, environment variable 15407 @cindex temporary file directory, set via environment variable 15408 @cindex temporary files, location of 15409 @item $TMPDIR 15410 Directory in which temporary files are located. 15411 @xref{Global options}, for more on setting the temporary directory. 15412 15413 @cindex CVS_PID, environment variable 15414 @item $CVS_PID 15415 This is the process identification (aka pid) number of 15416 the @sc{cvs} process. It is often useful in the 15417 programs and/or scripts specified by the 15418 @file{commitinfo}, @file{verifymsg}, @file{loginfo} 15419 files. 15420 @end table 15421 15422 @node Compatibility 15423 @appendix Compatibility between CVS Versions 15424 15425 @cindex CVS, versions of 15426 @cindex Versions, of CVS 15427 @cindex Compatibility, between CVS versions 15428 @c We don't mention versions older than CVS 1.3 15429 @c on the theory that it would clutter it up for the vast 15430 @c majority of people, who don't have anything that old. 15431 @c 15432 The repository format is compatible going back to 15433 @sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 15434 you have copies of @sc{cvs} 1.6 or older and you want 15435 to use the optional developer communication features. 15436 @c If you "cvs rm" and commit using 1.3, then you'll 15437 @c want to run "rcs -sdead <file,v>" on each of the 15438 @c files in the Attic if you then want 1.5 and 15439 @c later to recognize those files as dead (I think the 15440 @c symptom if this is not done is that files reappear 15441 @c in joins). (Wait: the above will work but really to 15442 @c be strictly correct we should suggest checking 15443 @c in a new revision rather than just changing the 15444 @c state of the head revision, shouldn't we?). 15445 @c The old convert.sh script was for this, but it never 15446 @c did get updated to reflect use of the RCS "dead" 15447 @c state. 15448 @c Note: this is tricky to document without confusing 15449 @c people--need to carefully say what CVS version we 15450 @c are talking about and keep in mind the distinction 15451 @c between a 15452 @c repository created with 1.3 and on which one now 15453 @c uses 1.5+, and a repository on which one wants to 15454 @c use both versions side by side (e.g. during a 15455 @c transition period). 15456 @c Wait, can't CVS just detect the case in which a file 15457 @c is in the Attic but the head revision is not dead? 15458 @c Not sure whether this should produce a warning or 15459 @c something, and probably needs further thought, but 15460 @c it would appear that the situation can be detected. 15461 @c 15462 @c We might want to separate out the 1.3 compatibility 15463 @c section (for repository & working directory) from the 15464 @c rest--that might help avoid confusing people who 15465 @c are upgrading (for example) from 1.6 to 1.8. 15466 @c 15467 @c A minor incompatibility is if a current version of CVS 15468 @c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 15469 @c see this as if there is no tag. Seems to me this is 15470 @c too obscure to mention. 15471 15472 The working directory format is compatible going back 15473 to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 15474 and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 15475 a working directory checked out with @sc{cvs} 1.3, 15476 @sc{cvs} will convert it, but to go back to @sc{cvs} 15477 1.3 you need to check out a new working directory with 15478 @sc{cvs} 1.3. 15479 15480 The remote protocol is interoperable going back to @sc{cvs} 1.5, but no 15481 further (1.5 was the first official release with the remote protocol, 15482 but some older versions might still be floating around). In many 15483 cases you need to upgrade both the client and the server to take 15484 advantage of new features and bug fixes, however. 15485 15486 @c Perhaps should be saying something here about the 15487 @c "D" lines in Entries (written by CVS 1.9; 1.8 and 15488 @c older don't use them). These are supposed to be 15489 @c compatible in both directions, but I'm not sure 15490 @c they quite are 100%. One common gripe is if you 15491 @c "rm -r" a directory and 1.9 gets confused, as it 15492 @c still sees it in Entries. That one is fixed in 15493 @c (say) 1.9.6. Someone else reported problems with 15494 @c starting with a directory which was checked out with 15495 @c an old version, and then using a new version, and 15496 @c some "D" lines appeared, but not for every 15497 @c directory, causing some directories to be skipped. 15498 @c They weren't sure how to reproduce this, though. 15499 15500 @c --------------------------------------------------------------------- 15501 @node Troubleshooting 15502 @appendix Troubleshooting 15503 15504 If you are having trouble with @sc{cvs}, this appendix 15505 may help. If there is a particular error message which 15506 you are seeing, then you can look up the message 15507 alphabetically. If not, you can look through the 15508 section on other problems to see if your problem is 15509 mentioned there. 15510 15511 @menu 15512 * Error messages:: Partial list of CVS errors 15513 * Connection:: Trouble making a connection to a CVS server 15514 * Other problems:: Problems not readily listed by error message 15515 @end menu 15516 15517 @ignore 15518 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 15519 @c @node Bad administrative files 15520 @appendixsec Bad administrative files 15521 15522 @c -- Give hints on how to fix them 15523 @end ignore 15524 15525 @node Error messages 15526 @appendixsec Partial list of error messages 15527 15528 Here is a partial list of error messages that you may 15529 see from @sc{cvs}. It is not a complete list---@sc{cvs} 15530 is capable of printing many, many error messages, often 15531 with parts of them supplied by the operating system, 15532 but the intention is to list the common and/or 15533 potentially confusing error messages. 15534 15535 The messages are alphabetical, but introductory text 15536 such as @samp{cvs update: } is not considered in 15537 ordering them. 15538 15539 In some cases the list includes messages printed by old 15540 versions of @sc{cvs} (partly because users may not be 15541 sure which version of @sc{cvs} they are using at any 15542 particular moment). 15543 @c If we want to start retiring messages, perhaps we 15544 @c should pick a cutoff version (for example, no more 15545 @c messages which are specific to versions before 1.9) 15546 @c and then move the old messages to an "old messages" 15547 @c node rather than deleting them completely. 15548 15549 @table @code 15550 @c FIXME: What is the correct way to format a multiline 15551 @c error message here? Maybe @table is the wrong 15552 @c choice? Texinfo gurus? 15553 @item @var{file}:@var{line}: Assertion '@var{text}' failed 15554 The exact format of this message may vary depending on 15555 your system. It indicates a bug in @sc{cvs}, which can 15556 be handled as described in @ref{BUGS}. 15557 15558 @item cvs @var{command}: authorization failed: server @var{host} rejected access 15559 This is a generic response when trying to connect to a 15560 pserver server which chooses not to provide a 15561 specific reason for denying authorization. Check that 15562 the username and password specified are correct and 15563 that the @code{CVSROOT} specified is allowed by @samp{--allow-root} 15564 in @file{inetd.conf}. See @ref{Password authenticated}. 15565 15566 @item cvs @var{command}: conflict: removed @var{file} was modified by second party 15567 This message indicates that you removed a file, and 15568 someone else modified it. To resolve the conflict, 15569 first run @samp{cvs add @var{file}}. If desired, look 15570 at the other party's modification to decide whether you 15571 still want to remove it. If you don't want to remove 15572 it, stop here. If you do want to remove it, proceed 15573 with @samp{cvs remove @var{file}} and commit your 15574 removal. 15575 @c Tests conflicts2-142b* in sanity.sh test for this. 15576 15577 @item cannot change permissions on temporary directory 15578 @example 15579 Operation not permitted 15580 @end example 15581 This message has been happening in a non-reproducible, 15582 occasional way when we run the client/server testsuite, 15583 both on Red Hat Linux 3.0.3 and 4.1. We haven't been 15584 able to figure out what causes it, nor is it known 15585 whether it is specific to Linux (or even to this 15586 particular machine!). If the problem does occur on 15587 other unices, @samp{Operation not permitted} would be 15588 likely to read @samp{Not owner} or whatever the system 15589 in question uses for the unix @code{EPERM} error. If 15590 you have any information to add, please let us know as 15591 described in @ref{BUGS}. If you experience this error 15592 while using @sc{cvs}, retrying the operation which 15593 produced it should work fine. 15594 @c This has been seen in a variety of tests, including 15595 @c multibranch-2, multibranch-5, and basic1-24-rm-rm, 15596 @c so it doesn't seem particularly specific to any one 15597 @c test. 15598 15599 @item cvs [server aborted]: Cannot check out files into the repository itself 15600 The obvious cause for this message (especially for 15601 non-client/server @sc{cvs}) is that the @sc{cvs} root 15602 is, for example, @file{/usr/local/cvsroot} and you try 15603 to check out files when you are in a subdirectory, such 15604 as @file{/usr/local/cvsroot/test}. However, there is a 15605 more subtle cause, which is that the temporary 15606 directory on the server is set to a subdirectory of the 15607 root (which is also not allowed). If this is the 15608 problem, set the temporary directory to somewhere else, 15609 for example @file{/var/tmp}; see @code{TMPDIR} in 15610 @ref{Environment variables}, for how to set the 15611 temporary directory. 15612 15613 @item cannot commit files as 'root' 15614 See @samp{'root' is not allowed to commit files}. 15615 15616 @c For one example see basica-1a10 in the testsuite 15617 @c For another example, "cvs co ." on NT; see comment 15618 @c at windows-NT/filesubr.c (expand_wild). 15619 @c For another example, "cvs co foo/bar" where foo exists. 15620 @item cannot open CVS/Entries for reading: No such file or directory 15621 This generally indicates a @sc{cvs} internal error, and 15622 can be handled as with other @sc{cvs} bugs 15623 (@pxref{BUGS}). Usually there is a workaround---the 15624 exact nature of which would depend on the situation but 15625 which hopefully could be figured out. 15626 15627 @c This is more obscure than it might sound; it only 15628 @c happens if you run "cvs init" from a directory which 15629 @c contains a CVS/Root file at the start. 15630 @item cvs [init aborted]: cannot open CVS/Root: No such file or directory 15631 This message is harmless. Provided it is not 15632 accompanied by other errors, the operation has 15633 completed successfully. This message should not occur 15634 with current versions of @sc{cvs}, but it is documented 15635 here for the benefit of @sc{cvs} 1.9 and older. 15636 15637 @item cvs server: cannot open /root/.cvsignore: Permission denied 15638 @itemx cvs [server aborted]: can't chdir(/root): Permission denied 15639 See @ref{Connection}. 15640 15641 @item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 15642 This message has been reported as intermittently 15643 happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 15644 unknown; if you know more about what causes it, let us 15645 know as described in @ref{BUGS}. 15646 15647 @item cvs [@var{command} aborted]: cannot start server via rcmd 15648 This, unfortunately, is a rather nonspecific error 15649 message which @sc{cvs} 1.9 will print if you are 15650 running the @sc{cvs} client and it is having trouble 15651 connecting to the server. Current versions of @sc{cvs} 15652 should print a much more specific error message. If 15653 you get this message when you didn't mean to run the 15654 client at all, you probably forgot to specify 15655 @code{:local:}, as described in @ref{Repository}. 15656 15657 @item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 15658 @sc{cvs} 1.9 and older will print this message 15659 when trying to check in a binary file if 15660 @sc{rcs} is not correctly installed. Re-read the 15661 instructions that came with your @sc{rcs} distribution 15662 and the @sc{install} file in the @sc{cvs} 15663 distribution. Alternately, upgrade to a current 15664 version of @sc{cvs}, which checks in files itself 15665 rather than via @sc{rcs}. 15666 15667 @item cvs checkout: could not check out @var{file} 15668 With @sc{cvs} 1.9, this can mean that the @code{co} program 15669 (part of @sc{rcs}) returned a failure. It should be 15670 preceded by another error message, however it has been 15671 observed without another error message and the cause is 15672 not well-understood. With the current version of @sc{cvs}, 15673 which does not run @code{co}, if this message occurs 15674 without another error message, it is definitely a @sc{cvs} 15675 bug (@pxref{BUGS}). 15676 @c My current suspicion is that the RCS in the rcs (not 15677 @c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 15678 @c CD is bad (remains to be confirmed). 15679 @c There is also a report of something which looks 15680 @c very similar on SGI, Irix 5.2, so I dunno. 15681 15682 @item cvs [login aborted]: could not find out home directory 15683 This means that you need to set the environment 15684 variables that @sc{cvs} uses to locate your home directory. 15685 See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 15686 @ref{Environment variables}. 15687 15688 @item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 15689 @sc{cvs} 1.9 and older will print this message if there was 15690 a problem finding the @code{rcsmerge} program. Make 15691 sure that it is in your @code{PATH}, or upgrade to a 15692 current version of @sc{cvs}, which does not require 15693 an external @code{rcsmerge} program. 15694 15695 @item cvs [update aborted]: could not patch @var{file}: No such file or directory 15696 This means that there was a problem finding the 15697 @code{patch} program. Make sure that it is in your 15698 @code{PATH}. Note that despite appearances the message 15699 is @emph{not} referring to whether it can find @var{file}. 15700 If both the client and the server are running a current 15701 version of @sc{cvs}, then there is no need for an 15702 external patch program and you should not see this 15703 message. But if either client or server is running 15704 @sc{cvs} 1.9, then you need @code{patch}. 15705 15706 @item cvs update: could not patch @var{file}; will refetch 15707 This means that for whatever reason the client was 15708 unable to apply a patch that the server sent. The 15709 message is nothing to be concerned about, because 15710 inability to apply the patch only slows things down and 15711 has no effect on what @sc{cvs} does. 15712 @c xref to update output. Or File status? 15713 @c Or some place else that 15714 @c explains this whole "patch"/P/Needs Patch thing? 15715 15716 @item dying gasps from @var{server} unexpected 15717 There is a known bug in the server for @sc{cvs} 1.9.18 15718 and older which can cause this. For me, this was 15719 reproducible if I used the @samp{-t} global option. It 15720 was fixed by Andy Piper's 14 Nov 1997 change to 15721 src/filesubr.c, if anyone is curious. 15722 If you see the message, 15723 you probably can just retry the operation which failed, 15724 or if you have discovered information concerning its 15725 cause, please let us know as described in @ref{BUGS}. 15726 15727 @item end of file from server (consult above messages if any) 15728 The most common cause for this message is if you are 15729 using an external @code{rsh} program and it exited with 15730 an error. In this case the @code{rsh} program should 15731 have printed a message, which will appear before the 15732 above message. For more information on setting up a 15733 @sc{cvs} client and server, see @ref{Remote repositories}. 15734 15735 @item cvs [update aborted]: EOF in key in RCS file @var{file},v 15736 @itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 15737 This means that there is a syntax error in the given 15738 @sc{rcs} file. Note that this might be true even if @sc{rcs} can 15739 read the file OK; @sc{cvs} does more error checking of 15740 errors in the RCS file. That is why you may see this 15741 message when upgrading from @sc{cvs} 1.9 to @sc{cvs} 15742 1.10. The likely cause for the original corruption is 15743 hardware, the operating system, or the like. Of 15744 course, if you find a case in which @sc{cvs} seems to 15745 corrupting the file, by all means report it, 15746 (@pxref{BUGS}). 15747 There are quite a few variations of this error message, 15748 depending on exactly where in the @sc{rcs} file @sc{cvs} 15749 finds the syntax error. 15750 15751 @cindex mkmodules 15752 @item cvs commit: Executing 'mkmodules' 15753 This means that your repository is set up for a version 15754 of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 15755 1.8 or later, the above message will be preceded by 15756 15757 @example 15758 cvs commit: Rebuilding administrative file database 15759 @end example 15760 15761 If you see both messages, the database is being rebuilt 15762 twice, which is unnecessary but harmless. If you wish 15763 to avoid the duplication, and you have no versions of 15764 @sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 15765 every place it appears in your @code{modules} 15766 file. For more information on the @code{modules} file, 15767 see @ref{modules}. 15768 15769 @c This message comes from "co", and I believe is 15770 @c possible only with older versions of CVS which call 15771 @c co. The problem with being able to create the bogus 15772 @c RCS file still exists, though (and I think maybe 15773 @c there is a different symptom(s) now). 15774 @c FIXME: Would be nice to have a more exact wording 15775 @c for this message. 15776 @item missing author 15777 Typically this can happen if you created an RCS file 15778 with your username set to empty. @sc{cvs} will, bogusly, 15779 create an illegal RCS file with no value for the author 15780 field. The solution is to make sure your username is 15781 set to a non-empty value and re-create the RCS file. 15782 @c "make sure your username is set" is complicated in 15783 @c and of itself, as there are the environment 15784 @c variables the system login name, &c, and it depends 15785 @c on the version of CVS. 15786 15787 @item cvs [checkout aborted]: no such tag @var{tag} 15788 This message means that @sc{cvs} isn't familiar with 15789 the tag @var{tag}. Usually the root cause is that you have 15790 mistyped a tag name. Ocassionally this can also occur because the 15791 users creating tags do not have permissions to write to the 15792 @file{CVSROOT/val-tags} file (@pxref{File permissions}, for more). 15793 15794 Prior to @sc{cvs} version 1.12.10, there were a few relatively 15795 obscure cases where a given tag could be created in an archive 15796 file in the repository but @sc{cvs} would require the user to 15797 @c Search sanity.sh for "no such tag" to see some of 15798 @c the relatively obscure cases. 15799 try a few other @sc{cvs} commands involving that tag 15800 until one was found whch caused @sc{cvs} to update 15801 @cindex CVSROOT/val-tags file, forcing tags into 15802 @cindex val-tags file, forcing tags into 15803 the @file{val-tags} file, at which point the originally failing command 15804 would begin to work. This same method can be used to repair a @file{val-tags} 15805 file that becomes out of date due to the permissions problem mentioned above. 15806 This updating is only required once per tag - once a tag is listed in 15807 @file{val-tags}, it stays there. 15808 15809 Note that using @samp{tag -f} to not require tag matches did not and 15810 does not override this check (@pxref{Common options}). 15811 15812 @item *PANIC* administration files missing 15813 This typically means that there is a directory named 15814 @sc{cvs} but it does not contain the administrative files 15815 which @sc{cvs} puts in a CVS directory. If the problem is 15816 that you created a CVS directory via some mechanism 15817 other than @sc{cvs}, then the answer is simple, use a name 15818 other than @sc{cvs}. If not, it indicates a @sc{cvs} bug 15819 (@pxref{BUGS}). 15820 15821 @item rcs error: Unknown option: -x,v/ 15822 This message will be followed by a usage message for 15823 @sc{rcs}. It means that you have an old version of 15824 @sc{rcs} (probably supplied with your operating 15825 system), as well as an old version of @sc{cvs}. 15826 @sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 15827 later; current versions of @sc{cvs} do not run @sc{rcs} programs. 15828 @c For more information on installing @sc{cvs}, see 15829 @c (FIXME: where? it depends on whether you are 15830 @c getting binaries or sources or what). 15831 @c The message can also say "ci error" or something 15832 @c instead of "rcs error", I suspect. 15833 15834 @item cvs [server aborted]: received broken pipe signal 15835 This message can be caused by a loginfo program that fails to 15836 read all of the log information from its standard input. 15837 If you find it happening in any other circumstances, 15838 please let us know as described in @ref{BUGS}. 15839 15840 @item 'root' is not allowed to commit files 15841 When committing a permanent change, @sc{cvs} makes a log entry of 15842 who committed the change. If you are committing the change logged 15843 in as "root" (not under "su" or other root-priv giving program), 15844 @sc{cvs} cannot determine who is actually making the change. 15845 As such, by default, @sc{cvs} disallows changes to be committed by users 15846 logged in as "root". (You can disable this option by passing the 15847 @code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 15848 On some systems this means editing the appropriate @file{config.h} file 15849 before building @sc{cvs}.) 15850 15851 @item cvs [server aborted]: Secondary out of sync with primary! 15852 15853 This usually means that the version of @sc{cvs} running on a secondary 15854 server is incompatible with the version running on the primary server 15855 (@pxref{Write proxies}). 15856 This will not occur if the client supports redirection. 15857 15858 It is not the version number that is significant here, but the list of 15859 supported requests that the servers provide to the client. 15860 For example, even if both servers were the same version, 15861 if the secondary was compiled with GSSAPI support and the primary was not, 15862 the list of supported requests provided by the two servers 15863 would be different and the secondary would not work as a transparent 15864 proxy to the primary. 15865 Conversely, even if the two servers were radically different versions 15866 but both provided the same list of valid requests to the client, 15867 the transparent proxy would succeed. 15868 15869 @item Terminated with fatal signal 11 15870 This message usually indicates that @sc{cvs} (the server, if you're 15871 using client/server mode) has run out of (virtual) memory. 15872 Although @sc{cvs} tries to catch the error and issue a more meaningful 15873 message, there are many circumstances where that is not possible. 15874 If you appear to have lots of memory available to the system, 15875 the problem is most likely that you're running into a system-wide 15876 limit on the amount of memory a single process can use or a 15877 similar process-specific limit. 15878 The mechanisms for displaying and setting such limits vary from 15879 system to system, so you'll have to consult an expert for your 15880 particular system if you don't know how to do that. 15881 15882 @item Too many arguments! 15883 This message is typically printed by the @file{log.pl} 15884 script which is in the @file{contrib} directory in the 15885 @sc{cvs} source distribution. In some versions of 15886 @sc{cvs}, @file{log.pl} has been part of the default 15887 @sc{cvs} installation. The @file{log.pl} script gets 15888 called from the @file{loginfo} administrative file. 15889 Check that the arguments passed in @file{loginfo} match 15890 what your version of @file{log.pl} expects. In 15891 particular, the @file{log.pl} from @sc{cvs} 1.3 and 15892 older expects the log file as an argument whereas the 15893 @file{log.pl} from @sc{cvs} 1.5 and newer expects the 15894 log file to be specified with a @samp{-f} option. Of 15895 course, if you don't need @file{log.pl} you can just 15896 comment it out of @file{loginfo}. 15897 15898 @item cvs [update aborted]: unexpected EOF reading @var{file},v 15899 See @samp{EOF in key in RCS file}. 15900 15901 @item cvs [login aborted]: unrecognized auth response from @var{server} 15902 This message typically means that the server is not set 15903 up properly. For example, if @file{inetd.conf} points 15904 to a nonexistent cvs executable. To debug it further, 15905 find the log file which inetd writes 15906 (@file{/var/log/messages} or whatever inetd uses on 15907 your system). For details, see @ref{Connection}, and 15908 @ref{Password authentication server}. 15909 15910 @item cvs commit: Up-to-date check failed for `@var{file}' 15911 This means that someone else has committed a change to 15912 that file since the last time that you did a @code{cvs 15913 update}. So before proceeding with your @code{cvs 15914 commit} you need to @code{cvs update}. @sc{cvs} will merge 15915 the changes that you made and the changes that the 15916 other person made. If it does not detect any conflicts 15917 it will report @samp{M @var{file}} and you are ready 15918 to @code{cvs commit}. If it detects conflicts it will 15919 print a message saying so, will report @samp{C @var{file}}, 15920 and you need to manually resolve the 15921 conflict. For more details on this process see 15922 @ref{Conflicts example}. 15923 15924 @item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 15925 @example 15926 Only one of [exEX3] allowed 15927 @end example 15928 This indicates a problem with the installation of 15929 @code{diff3} and @code{rcsmerge}. Specifically 15930 @code{rcsmerge} was compiled to look for GNU diff3, but 15931 it is finding unix diff3 instead. The exact text of 15932 the message will vary depending on the system. The 15933 simplest solution is to upgrade to a current version of 15934 @sc{cvs}, which does not rely on external 15935 @code{rcsmerge} or @code{diff3} programs. 15936 15937 @item warning: unrecognized response `@var{text}' from cvs server 15938 If @var{text} contains a valid response (such as 15939 @samp{ok}) followed by an extra carriage return 15940 character (on many systems this will cause the second 15941 part of the message to overwrite the first part), then 15942 it probably means that you are using the @samp{:ext:} 15943 access method with a version of rsh, such as most 15944 non-unix rsh versions, which does not by default 15945 provide a transparent data stream. In such cases you 15946 probably want to try @samp{:server:} instead of 15947 @samp{:ext:}. If @var{text} is something else, this 15948 may signify a problem with your @sc{cvs} server. 15949 Double-check your installation against the instructions 15950 for setting up the @sc{cvs} server. 15951 @c FIXCVS: should be printing CR as \r or \015 or some 15952 @c such, probably. 15953 15954 @item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 15955 This is a normal message, not an error. See 15956 @ref{Concurrency}, for more details. 15957 15958 @item cvs commit: warning: editor session failed 15959 @cindex Exit status, of editor 15960 This means that the editor which @sc{cvs} is using exits with a nonzero 15961 exit status. Some versions of vi will do this even when there was not 15962 a problem editing the file. If so, point the 15963 @code{CVSEDITOR} environment variable to a small script 15964 such as: 15965 15966 @example 15967 #!/bin/sh 15968 vi $* 15969 exit 0 15970 @end example 15971 15972 @item cvs update: warning: @var{file} was lost 15973 This means that the working copy of @var{file} has been deleted 15974 but it has not been removed from @sc{cvs}. 15975 This is nothing to be concerned about, 15976 the update will just recreate the local file from the repository. 15977 (This is a convenient way to discard local changes to a file: 15978 just delete it and then run @code{cvs update}.) 15979 15980 @item cvs update: warning: @var{file} is not (any longer) pertinent 15981 This means that the working copy of @var{file} has been deleted, 15982 it has not been removed from @sc{cvs} in the current working directory, 15983 but it has been removed from @sc{cvs} in some other working directory. 15984 This is nothing to be concerned about, 15985 the update would have removed the local file anyway. 15986 15987 @end table 15988 15989 @node Connection 15990 @appendixsec Trouble making a connection to a CVS server 15991 15992 This section concerns what to do if you are having 15993 trouble making a connection to a @sc{cvs} server. If 15994 you are running the @sc{cvs} command line client 15995 running on Windows, first upgrade the client to 15996 @sc{cvs} 1.9.12 or later. The error reporting in 15997 earlier versions provided much less information about 15998 what the problem was. If the client is non-Windows, 15999 @sc{cvs} 1.9 should be fine. 16000 16001 If the error messages are not sufficient to track down 16002 the problem, the next steps depend largely on which 16003 access method you are using. 16004 16005 @table @code 16006 @cindex :ext:, troubleshooting 16007 @item :ext: 16008 Try running the rsh program from the command line. For 16009 example: "rsh servername cvs -v" should print @sc{cvs} 16010 version information. If this doesn't work, you need to 16011 fix it before you can worry about @sc{cvs} problems. 16012 16013 @cindex :server:, troubleshooting 16014 @item :server: 16015 You don't need a command line rsh program to use this 16016 access method, but if you have an rsh program around, 16017 it may be useful as a debugging tool. Follow the 16018 directions given for :ext:. 16019 16020 @cindex :pserver:, troubleshooting 16021 @item :pserver: 16022 Errors along the lines of "connection refused" typically indicate 16023 that inetd isn't even listening for connections on port 2401 16024 whereas errors like "connection reset by peer", 16025 "received broken pipe signal", "recv() from server: EOF", 16026 or "end of file from server" 16027 typically indicate that inetd is listening for 16028 connections but is unable to start @sc{cvs} (this is frequently 16029 caused by having an incorrect path in @file{inetd.conf} 16030 or by firewall software rejecting the connection). 16031 "unrecognized auth response" errors are caused by a bad command 16032 line in @file{inetd.conf}, typically an invalid option or forgetting 16033 to put the @samp{pserver} command at the end of the line. 16034 Another less common problem is invisible control characters that 16035 your editor "helpfully" added without you noticing. 16036 16037 One good debugging tool is to "telnet servername 16038 2401". After connecting, send any text (for example 16039 "foo" followed by return). If @sc{cvs} is working 16040 correctly, it will respond with 16041 16042 @example 16043 cvs [pserver aborted]: bad auth protocol start: foo 16044 @end example 16045 16046 If instead you get: 16047 16048 @example 16049 Usage: cvs [cvs-options] command [command-options-and-arguments] 16050 ... 16051 @end example 16052 16053 @noindent 16054 then you're missing the @samp{pserver} command at the end of the 16055 line in @file{inetd.conf}; check to make sure that the entire command 16056 is on one line and that it's complete. 16057 16058 Likewise, if you get something like: 16059 16060 @example 16061 Unknown command: `pserved' 16062 16063 CVS commands are: 16064 add Add a new file/directory to the repository 16065 ... 16066 @end example 16067 16068 @noindent 16069 then you've misspelled @samp{pserver} in some way. If it isn't 16070 obvious, check for invisible control characters (particularly 16071 carriage returns) in @file{inetd.conf}. 16072 16073 If it fails to work at all, then make sure inetd is working 16074 right. Change the invocation in @file{inetd.conf} to run the 16075 echo program instead of cvs. For example: 16076 16077 @example 16078 2401 stream tcp nowait root /bin/echo echo hello 16079 @end example 16080 16081 After making that change and instructing inetd to 16082 re-read its configuration file, "telnet servername 16083 2401" should show you the text hello and then the 16084 server should close the connection. If this doesn't 16085 work, you need to fix it before you can worry about 16086 @sc{cvs} problems. 16087 16088 On AIX systems, the system will often have its own 16089 program trying to use port 2401. This is AIX's problem 16090 in the sense that port 2401 is registered for use with 16091 @sc{cvs}. I hear that there is an AIX patch available 16092 to address this problem. 16093 16094 Another good debugging tool is the @samp{-d} 16095 (debugging) option to inetd. Consult your system 16096 documentation for more information. 16097 16098 If you seem to be connecting but get errors like: 16099 16100 @example 16101 cvs server: cannot open /root/.cvsignore: Permission denied 16102 cvs [server aborted]: can't chdir(/root): Permission denied 16103 @end example 16104 16105 @noindent 16106 then you probably haven't specified @samp{-f} in @file{inetd.conf}. 16107 (In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 16108 your system setting the @code{$HOME} environment variable 16109 for programs being run by inetd. In this case, you can either 16110 have inetd run a shell script that unsets @code{$HOME} and then runs 16111 @sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 16112 environment.) 16113 16114 If you can connect successfully for a while but then can't, 16115 you've probably hit inetd's rate limit. 16116 (If inetd receives too many requests for the same service 16117 in a short period of time, it assumes that something is wrong 16118 and temporarily disables the service.) 16119 Check your inetd documentation to find out how to adjust the 16120 rate limit (some versions of inetd have a single rate limit, 16121 others allow you to set the limit for each service separately.) 16122 @end table 16123 16124 @node Other problems 16125 @appendixsec Other common problems 16126 16127 Here is a list of problems which do not fit into the 16128 above categories. They are in no particular order. 16129 16130 @itemize @bullet 16131 @item 16132 On Windows, if there is a 30 second or so delay when 16133 you run a @sc{cvs} command, it may mean that you have 16134 your home directory set to @file{C:/}, for example (see 16135 @code{HOMEDRIVE} and @code{HOMEPATH} in 16136 @ref{Environment variables}). @sc{cvs} expects the home 16137 directory to not end in a slash, for example @file{C:} 16138 or @file{C:\cvs}. 16139 @c FIXCVS: CVS should at least detect this and print an 16140 @c error, presumably. 16141 16142 @item 16143 If you are running @sc{cvs} 1.9.18 or older, and 16144 @code{cvs update} finds a conflict and tries to 16145 merge, as described in @ref{Conflicts example}, but 16146 doesn't tell you there were conflicts, then you may 16147 have an old version of @sc{rcs}. The easiest solution 16148 probably is to upgrade to a current version of 16149 @sc{cvs}, which does not rely on external @sc{rcs} 16150 programs. 16151 @end itemize 16152 16153 @c --------------------------------------------------------------------- 16154 @node Credits 16155 @appendix Credits 16156 16157 @cindex Contributors (manual) 16158 @cindex Credits (manual) 16159 Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 16160 wrote the manual pages which were distributed with 16161 @sc{cvs} 1.3. Much of their text was copied into this 16162 manual. He also read an early draft 16163 of this manual and contributed many ideas and 16164 corrections. 16165 16166 The mailing-list @code{info-cvs} is sometimes 16167 informative. I have included information from postings 16168 made by the following persons: 16169 David G. Grubbs <@t{dgg@@think.com}>. 16170 16171 Some text has been extracted from the man pages for 16172 @sc{rcs}. 16173 16174 The @sc{cvs} @sc{faq} by David G. Grubbs has provided 16175 useful material. The @sc{faq} is no longer maintained, 16176 however, and this manual is about the closest thing there 16177 is to a successor (with respect to documenting how to 16178 use @sc{cvs}, at least). 16179 16180 In addition, the following persons have helped by 16181 telling me about mistakes I've made: 16182 16183 @display 16184 Roxanne Brunskill <@t{rbrunski@@datap.ca}>, 16185 Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 16186 Karl Pingle <@t{pingle@@acuson.com}>, 16187 Thomas A Peterson <@t{tap@@src.honeywell.com}>, 16188 Inge Wallin <@t{ingwa@@signum.se}>, 16189 Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 16190 and Michael Brown <@t{brown@@wi.extrel.com}>. 16191 @end display 16192 16193 The list of contributors here is not comprehensive; for a more 16194 complete list of who has contributed to this manual see 16195 the file @file{doc/ChangeLog} in the @sc{cvs} source 16196 distribution. 16197 16198 @c --------------------------------------------------------------------- 16199 @node BUGS 16200 @appendix Dealing with bugs in CVS or this manual 16201 16202 @cindex Bugs in this manual or CVS 16203 Neither @sc{cvs} nor this manual is perfect, and they 16204 probably never will be. If you are having trouble 16205 using @sc{cvs}, or think you have found a bug, there 16206 are a number of things you can do about it. Note that 16207 if the manual is unclear, that can be considered a bug 16208 in the manual, so these problems are often worth doing 16209 something about as well as problems with @sc{cvs} itself. 16210 16211 @cindex Reporting bugs 16212 @cindex Bugs, reporting 16213 @cindex Errors, reporting 16214 @itemize @bullet 16215 @item 16216 If you want someone to help you and fix bugs that you 16217 report, there are companies which will do that for a 16218 fee. One such company is: 16219 16220 @cindex Ximbiot 16221 @cindex Support, getting CVS support 16222 @example 16223 Ximbiot 16224 319 S. River St. 16225 Harrisburg, PA 17104-1657 16226 USA 16227 Email: info@@ximbiot.com 16228 Phone: (717) 579-6168 16229 Fax: (717) 234-3125 16230 @url{http://ximbiot.com/} 16231 16232 @end example 16233 16234 @item 16235 If you got @sc{cvs} through a distributor, such as an 16236 operating system vendor or a vendor of freeware 16237 @sc{cd-rom}s, you may wish to see whether the 16238 distributor provides support. Often, they will provide 16239 no support or minimal support, but this may vary from 16240 distributor to distributor. 16241 16242 @item 16243 If you have the skills and time to do so, you may wish 16244 to fix the bug yourself. If you wish to submit your 16245 fix for inclusion in future releases of @sc{cvs}, see 16246 the file @sc{hacking} in the @sc{cvs} source 16247 distribution. It contains much more information on the 16248 process of submitting fixes. 16249 16250 @item 16251 There may be resources on the net which can help. A 16252 good place to start is: 16253 16254 @example 16255 @url{http://cvs.nongnu.org/} 16256 @end example 16257 16258 If you are so inspired, increasing the information 16259 available on the net is likely to be appreciated. For 16260 example, before the standard @sc{cvs} distribution 16261 worked on Windows 95, there was a web page with some 16262 explanation and patches for running @sc{cvs} on Windows 16263 95, and various people helped out by mentioning this 16264 page on mailing lists or newsgroups when the subject 16265 came up. 16266 16267 @item 16268 It is also possible to report bugs to @email{bug-cvs@@nongnu.org}. 16269 Note that someone may or may not want to do anything 16270 with your bug report---if you need a solution consider 16271 one of the options mentioned above. People probably do 16272 want to hear about bugs which are particularly severe 16273 in consequences and/or easy to fix, however. You can 16274 also increase your odds by being as clear as possible 16275 about the exact nature of the bug and any other 16276 relevant information. The way to report bugs is to 16277 send email to @email{bug-cvs@@nongnu.org}. Note 16278 that submissions to @email{bug-cvs@@nongnu.org} may be distributed 16279 under the terms of the @sc{gnu} Public License, so if 16280 you don't like this, don't submit them. There is 16281 usually no justification for sending mail directly to 16282 one of the @sc{cvs} maintainers rather than to 16283 @email{bug-cvs@@nongnu.org}; those maintainers who want to hear 16284 about such bug reports read @email{bug-cvs@@nongnu.org}. Also note 16285 that sending a bug report to other mailing lists or 16286 newsgroups is @emph{not} a substitute for sending it to 16287 @email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on 16288 whatever forum you prefer, but there are not 16289 necessarily any maintainers reading bug reports sent 16290 anywhere except @email{bug-cvs@@nongnu.org}. 16291 @end itemize 16292 16293 @cindex Known bugs in this manual or CVS 16294 People often ask if there is a list of known bugs or 16295 whether a particular bug is a known one. The file 16296 @sc{bugs} in the @sc{cvs} source distribution is one 16297 list of known bugs, but it doesn't necessarily try to 16298 be comprehensive. Perhaps there will never be a 16299 comprehensive, detailed list of known bugs. 16300 16301 @c --------------------------------------------------------------------- 16302 @node Index 16303 @unnumbered Index 16304 @cindex Index 16305 16306 @printindex cp 16307 16308 @bye 16309 16311 Local Variables: 16312 fill-column: 55 16313 End: 16314
Indexes created Wed Apr 15 00:22:22 UTC 2026