1\input texinfo @c -*-texinfo-*- 2@comment Documentation for CVS. 3@setfilename cvs.info 4@macro copyleftnotice 5@noindent 6Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 7 2001, 2002, 2003 Free Software Foundation, Inc. 8 9@multitable @columnfractions .12 .88 10@item Portions 11@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek R. Price, 12@item @tab Copyright @copyright{} 2002, 2003 Ximbiot <http://ximbiot.com>, 13@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 14@item @tab and Copyright @copyright{} others. 15@end multitable 16 17@ignore 18Permission is granted to process this file through Tex and print the 19results, provided the printed document carries copying permission 20notice identical to this one except for the removal of this paragraph 21(this paragraph not being relevant to the printed manual). 22 23@end ignore 24Permission is granted to make and distribute verbatim copies of 25this manual provided the copyright notice and this permission notice 26are preserved on all copies. 27 28Permission is granted to copy and distribute modified versions of this 29manual under the conditions for verbatim copying, provided also that the 30entire resulting derived work is distributed under the terms of a 31permission notice identical to this one. 32 33Permission is granted to copy and distribute translations of this manual 34into another language, under the above conditions for modified versions, 35except that this permission notice may be stated in a translation 36approved by the Free Software Foundation. 37@end macro 38 39@comment This file is part of the CVS distribution. 40 41@comment CVS is free software; you can redistribute it and/or modify 42@comment it under the terms of the GNU General Public License as published by 43@comment the Free Software Foundation; either version 2, or (at your option) 44@comment any later version. 45 46@comment CVS is distributed in the hope that it will be useful, 47@comment but WITHOUT ANY WARRANTY; without even the implied warranty of 48@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 49@comment GNU General Public License for more details. 50 51@c See ../README for A4 vs. US letter size. 52@c When we provided A4 postscript, and people tried to 53@c print it on US letter, the usual complaint was that the 54@c page numbers would get cut off. 55@c If one prints US letter on A4, reportedly there is 56@c some extra space at the top and/or bottom, and the side 57@c margins are a bit narrow, but no text is lost. 58@c 59@c See 60@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html 61@c for more on paper sizes. Insuring that margins are 62@c big enough to print on either A4 or US letter does 63@c indeed seem to be the usual approach (RFC2346). 64 65@c This document seems to get overfull hboxes with some 66@c frequency (probably because the tendency is to 67@c sanity-check it with "make info" and run TeX less 68@c often). The big ugly boxes just seem to add insult 69@c to injury, and I'm not aware of them helping to fix 70@c the overfull hboxes at all. 71@finalout 72 73@set UPDATED 28 March 2002 74@set UPDATED-MONTH March 2002 75@set EDITION 4.2 76@set VERSION 4.2 77@settitle CVS---Concurrent Versions System v4.2 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 89@macro splitrcskeyword {arg} 90 \arg\ 91@end macro 92 93 94@macro splitrcskeyword {arg} 95@i{}\arg\ 96@end macro 97 98 99@dircategory GNU Packages 100@direntry 101* CVS: (cvs). Concurrent Versions System 102@end direntry 103@dircategory Individual utilities 104@direntry 105* cvs: (cvs)CVS commands. Concurrent Versions System 106@end direntry 107 108@comment The titlepage section does not appear in the Info file. 109 110@comment ================================================================ 111@comment The real text starts here 112@comment ================================================================ 113 114@c --------------------------------------------------------------------- 115@node Top 116@top 117 118This info manual describes how to use and administer 119@sc{cvs} version 4.2. 120 121 122@c This menu is pretty long. Not sure how easily that 123@c can be fixed (no brilliant ideas right away)... 124@menu 125* Overview:: An introduction to CVS 126* Repository:: Where all your sources are stored 127* Starting a new project:: Starting a project with CVS 128* Revisions:: Numeric and symbolic names for revisions 129* Branching and merging:: Diverging/rejoining branches of development 130* Recursive behavior:: CVS descends directories 131* Adding and removing:: Adding/removing/renaming files/directories 132* History browsing:: Viewing the history of files in various ways 133 134CVS and the Real World. 135----------------------- 136* Binary files:: CVS can handle binary files 137* Multiple developers:: How CVS helps a group of developers 138* Revision management:: Policy questions for revision management 139* Keyword substitution:: CVS can include the revision inside the file 140* Tracking sources:: Tracking third-party sources 141* Builds:: Issues related to CVS and builds 142* Special Files:: Devices, links and other non-regular files 143 144References. 145----------- 146* CVS commands:: CVS commands share some things 147* Invoking CVS:: Quick reference to CVS commands 148* Administrative files:: Reference manual for the Administrative files 149* Environment variables:: All environment variables which affect CVS 150* Compatibility:: Upgrading CVS versions 151* Troubleshooting:: Some tips when nothing works 152* Credits:: Some of the contributors to this manual 153* BUGS:: Dealing with bugs in CVS or this manual 154* Index:: Index 155@end menu 156 157@c --------------------------------------------------------------------- 158@node Overview 159@chapter Overview 160@cindex Overview 161 162This chapter is for people who have never used 163@sc{cvs}, and perhaps have never used version control 164software before. 165 166If you are already familiar with @sc{cvs} and are just 167trying to learn a particular feature or remember a 168certain command, you can probably skip everything here. 169 170@menu 171* What is CVS?:: What you can do with @sc{cvs} 172* What is CVS not?:: Problems @sc{cvs} doesn't try to solve 173* A sample session:: A tour of basic @sc{cvs} usage 174@end menu 175 176@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 177@node What is CVS? 178@section What is CVS? 179@cindex What is CVS? 180@cindex Introduction to CVS 181@cindex CVS, introduction to 182 183@sc{cvs} is a version control system. Using it, you can 184record the history of your source files. 185 186@c -- /// 187@c -- ///Those who cannot remember the past are condemned to repeat it. 188@c -- /// -- George Santayana 189@c -- ////// 190 191@c -- Insert history quote here! 192For example, bugs sometimes creep in when 193software is modified, and you might not detect the bug 194until a long time after you make the modification. 195With @sc{cvs}, you can easily retrieve old versions to see 196exactly which change caused the bug. This can 197sometimes be a big help. 198 199You could of course save every version of every file 200you have ever created. This would 201however waste an enormous amount of disk space. @sc{cvs} 202stores all the versions of a file in a single file in a 203clever way that only stores the differences between 204versions. 205 206@sc{cvs} also helps you if you are part of a group of people working 207on the same project. It is all too easy to overwrite 208each others' changes unless you are extremely careful. 209Some editors, like @sc{gnu} Emacs, try to make sure that 210the same file is never modified by two people at the 211same time. Unfortunately, if someone is using another 212editor, that safeguard will not work. @sc{cvs} solves this problem 213by insulating the different developers from each other. Every 214developer works in his own directory, and @sc{cvs} merges 215the work when each developer is done. 216 217@cindex History of CVS 218@cindex CVS, history of 219@cindex Credits (CVS program) 220@cindex Contributors (CVS program) 221@sc{cvs} started out as a bunch of shell scripts written by 222Dick Grune, posted to the newsgroup 223@code{comp.sources.unix} in the volume 6 224release of July, 1986. While no actual code from 225these shell scripts is present in the current version 226of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms 227come from them. 228 229In April, 1989, Brian Berliner designed and coded @sc{cvs}. 230Jeff Polk later helped Brian with the design of the @sc{cvs} 231module and vendor branch support. 232 233@cindex Source, getting CVS source 234You can get @sc{cvs} in a variety of ways, including 235free download from the internet. For more information 236on downloading @sc{cvs} and other @sc{cvs} topics, see: 237 238@example 239http://www.cvshome.org/ 240http://www.loria.fr/~molli/cvs-index.html 241@end example 242 243@cindex Mailing list 244@cindex List, mailing list 245@cindex Newsgroups 246There is a mailing list, known as @w{@code{info-cvs}}, 247devoted to @sc{cvs}. To subscribe or 248unsubscribe 249write to 250@w{@code{info-cvs-request@@gnu.org}}. 251If you prefer a usenet group, the right 252group is @code{comp.software.config-mgmt} which is for 253@sc{cvs} discussions (along with other configuration 254management systems). In the future, it might be 255possible to create a 256@code{comp.software.config-mgmt.cvs}, but probably only 257if there is sufficient @sc{cvs} traffic on 258@code{comp.software.config-mgmt}. 259@c Other random data is that past attempts to create a 260@c gnu.* group have failed (the relevant authorities 261@c say they'll do it, but don't), and that tale was very 262@c skeptical of comp.software.config-mgmt.cvs when the 263@c subject came up around 1995 or so (for one 264@c thing, because creating it would be a "reorg" which 265@c would need to take a more comprehensive look at the 266@c whole comp.software.config-mgmt.* hierarchy). 267 268You can also subscribe to the @code{bug-cvs} mailing list, 269described in more detail in @ref{BUGS}. To subscribe 270send mail to @code{bug-cvs-request@@gnu.org}. 271 272@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 273@node What is CVS not? 274@section What is CVS not? 275@cindex What is CVS not? 276 277@sc{cvs} can do a lot of things for you, but it does 278not try to be everything for everyone. 279 280@table @asis 281@item @sc{cvs} is not a build system. 282 283Though the structure of your repository and modules 284file interact with your build system 285(e.g. @file{Makefile}s), they are essentially 286independent. 287 288@sc{cvs} does not dictate how you build anything. It 289merely stores files for retrieval in a tree structure 290you devise. 291 292@sc{cvs} does not dictate how to use disk space in the 293checked out working directories. If you write your 294@file{Makefile}s or scripts in every directory so they 295have to know the relative positions of everything else, 296you wind up requiring the entire repository to be 297checked out. 298 299If you modularize your work, and construct a build 300system that will share files (via links, mounts, 301@code{VPATH} in @file{Makefile}s, etc.), you can 302arrange your disk usage however you like. 303 304But you have to remember that @emph{any} such system is 305a lot of work to construct and maintain. @sc{cvs} does 306not address the issues involved. 307 308Of course, you should place the tools created to 309support such a build system (scripts, @file{Makefile}s, 310etc) under @sc{cvs}. 311 312Figuring out what files need to be rebuilt when 313something changes is, again, something to be handled 314outside the scope of @sc{cvs}. One traditional 315approach is to use @code{make} for building, and use 316some automated tool for generating the dependencies which 317@code{make} uses. 318 319See @ref{Builds}, for more information on doing builds 320in conjunction with @sc{cvs}. 321 322@item @sc{cvs} is not a substitute for management. 323 324Your managers and project leaders are expected to talk 325to you frequently enough to make certain you are aware 326of schedules, merge points, branch names and release 327dates. If they don't, @sc{cvs} can't help. 328 329@sc{cvs} is an instrument for making sources dance to 330your tune. But you are the piper and the composer. No 331instrument plays itself or writes its own music. 332 333@item @sc{cvs} is not a substitute for developer communication. 334 335When faced with conflicts within a single file, most 336developers manage to resolve them without too much 337effort. But a more general definition of ``conflict'' 338includes problems too difficult to solve without 339communication between developers. 340 341@sc{cvs} cannot determine when simultaneous changes 342within a single file, or across a whole collection of 343files, will logically conflict with one another. Its 344concept of a @dfn{conflict} is purely textual, arising 345when two changes to the same base file are near enough 346to spook the merge (i.e. @code{diff3}) command. 347 348@sc{cvs} does not claim to help at all in figuring out 349non-textual or distributed conflicts in program logic. 350 351For example: Say you change the arguments to function 352@code{X} defined in file @file{A}. At the same time, 353someone edits file @file{B}, adding new calls to 354function @code{X} using the old arguments. You are 355outside the realm of @sc{cvs}'s competence. 356 357Acquire the habit of reading specs and talking to your 358peers. 359 360 361@item @sc{cvs} does not have change control 362 363Change control refers to a number of things. First of 364all it can mean @dfn{bug-tracking}, that is being able 365to keep a database of reported bugs and the status of 366each one (is it fixed? in what release? has the bug 367submitter agreed that it is fixed?). For interfacing 368@sc{cvs} to an external bug-tracking system, see the 369@file{rcsinfo} and @file{verifymsg} files 370(@pxref{Administrative files}). 371 372Another aspect of change control is keeping track of 373the fact that changes to several files were in fact 374changed together as one logical change. If you check 375in several files in a single @code{cvs commit} 376operation, @sc{cvs} then forgets that those files were 377checked in together, and the fact that they have the 378same log message is the only thing tying them 379together. Keeping a @sc{gnu} style @file{ChangeLog} 380can help somewhat. 381@c FIXME: should have an xref to a section which talks 382@c more about keeping ChangeLog's with CVS, but that 383@c section hasn't been written yet. 384 385Another aspect of change control, in some systems, is 386the ability to keep track of the status of each 387change. Some changes have been written by a developer, 388others have been reviewed by a second developer, and so 389on. Generally, the way to do this with @sc{cvs} is to 390generate a diff (using @code{cvs diff} or @code{diff}) 391and email it to someone who can then apply it using the 392@code{patch} utility. This is very flexible, but 393depends on mechanisms outside @sc{cvs} to make sure 394nothing falls through the cracks. 395 396@item @sc{cvs} is not an automated testing program 397 398It should be possible to enforce mandatory use of a 399testsuite using the @code{commitinfo} file. I haven't 400heard a lot about projects trying to do that or whether 401there are subtle gotchas, however. 402 403@item @sc{cvs} does not have a builtin process model 404 405Some systems provide ways to ensure that changes or 406releases go through various steps, with various 407approvals as needed. Generally, one can accomplish 408this with @sc{cvs} but it might be a little more work. 409In some cases you'll want to use the @file{commitinfo}, 410@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} 411files, to require that certain steps be performed 412before cvs will allow a checkin. Also consider whether 413features such as branches and tags can be used to 414perform tasks such as doing work in a development tree 415and then merging certain changes over to a stable tree 416only once they have been proven. 417@end table 418 419@c --------------------------------------------------------------------- 420@node A sample session 421@section A sample session 422@cindex Example of a work-session 423@cindex Getting started 424@cindex Work-session, example of 425@cindex tc, Trivial Compiler (example) 426@cindex Trivial Compiler (example) 427 428@c I think an example is a pretty good way to start. But 429@c somewhere in here, maybe after the sample session, 430@c we need something which is kind of 431@c a "roadmap" which is more directed at sketching out 432@c the functionality of CVS and pointing people to 433@c various other parts of the manual. As it stands now 434@c people who read in order get dumped right into all 435@c manner of hair regarding remote repositories, 436@c creating a repository, etc. 437@c 438@c The following was in the old Basic concepts node. I don't 439@c know how good a job it does at introducing modules, 440@c or whether they need to be introduced so soon, but 441@c something of this sort might go into some 442@c introductory material somewhere. 443 444As a way of introducing @sc{cvs}, we'll go through a 445typical work-session using @sc{cvs}. The first thing 446to understand is that @sc{cvs} stores all files in a 447centralized @dfn{repository} (@pxref{Repository}); this 448section assumes that a repository is set up. 449@c I'm not sure that the sentence concerning the 450@c repository quite tells the user what they need to 451@c know at this point. Might need to expand on "centralized" 452@c slightly (maybe not here, maybe further down in the example?) 453 454Suppose you are working on a simple compiler. The source 455consists of a handful of C files and a @file{Makefile}. 456The compiler is called @samp{tc} (Trivial Compiler), 457and the repository is set up so that there is a module 458called @samp{tc}. 459 460@menu 461* Getting the source:: Creating a workspace 462* Committing your changes:: Making your work available to others 463* Cleaning up:: Cleaning up 464* Viewing differences:: Viewing differences 465@end menu 466 467@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 468@node Getting the source 469@subsection Getting the source 470@cindex Getting the source 471@cindex Checking out source 472@cindex Fetching source 473@cindex Source, getting from CVS 474@cindex Checkout, example 475 476The first thing you must do is to get your own working copy of the 477source for @samp{tc}. For this, you use the @code{checkout} command: 478 479@example 480$ cvs checkout tc 481@end example 482 483@noindent 484This will create a new directory called @file{tc} and populate it with 485the source files. 486 487@example 488$ cd tc 489$ ls 490CVS Makefile backend.c driver.c frontend.c parser.c 491@end example 492 493The @file{CVS} directory is used internally by 494@sc{cvs}. Normally, you should not modify or remove 495any of the files in it. 496 497You start your favorite editor, hack away at @file{backend.c}, and a couple 498of hours later you have added an optimization pass to the compiler. 499A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that 500you want to edit. @xref{Multiple developers}, for an explanation. 501 502@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 503@node Committing your changes 504@subsection Committing your changes 505@cindex Committing changes to files 506@cindex Log message entry 507 508When you have checked that the compiler is still compilable you decide 509to make a new version of @file{backend.c}. This will 510store your new @file{backend.c} in the repository and 511make it available to anyone else who is using that same 512repository. 513 514@example 515$ cvs commit backend.c 516@end example 517 518@noindent 519@sc{cvs} starts an editor, to allow you to enter a log 520message. You type in ``Added an optimization pass.'', 521save the temporary file, and exit the editor. 522 523@cindex CVSEDITOR, environment variable 524@cindex EDITOR, environment variable 525The environment variable @code{$CVSEDITOR} determines 526which editor is started. If @code{$CVSEDITOR} is not 527set, then if the environment variable @code{$EDITOR} is 528set, it will be used. If both @code{$CVSEDITOR} and 529@code{$EDITOR} are not set then there is a default 530which will vary with your operating system, for example 531@code{vi} for unix or @code{notepad} for Windows 532NT/95. 533 534@cindex VISUAL, environment variable 535In addition, @sc{cvs} checks the @code{$VISUAL} environment 536variable. Opinions vary on whether this behavior is desirable and 537whether future releases of @sc{cvs} should check @code{$VISUAL} or 538ignore it. You will be OK either way if you make sure that 539@code{$VISUAL} is either unset or set to the same thing as 540@code{$EDITOR}. 541 542@c This probably should go into some new node 543@c containing detailed info on the editor, rather than 544@c the intro. In fact, perhaps some of the stuff with 545@c CVSEDITOR and -m and so on should too. 546When @sc{cvs} starts the editor, it includes a list of 547files which are modified. For the @sc{cvs} client, 548this list is based on comparing the modification time 549of the file against the modification time that the file 550had when it was last gotten or updated. Therefore, if 551a file's modification time has changed but its contents 552have not, it will show up as modified. The simplest 553way to handle this is simply not to worry about it---if 554you proceed with the commit @sc{cvs} will detect that 555the contents are not modified and treat it as an 556unmodified file. The next @code{update} will clue 557@sc{cvs} in to the fact that the file is unmodified, 558and it will reset its stored timestamp so that the file 559will not show up in future editor sessions. 560@c FIXCVS: Might be nice if "commit" and other commands 561@c would reset that timestamp too, but currently commit 562@c doesn't. 563@c FIXME: Need to talk more about the process of 564@c prompting for the log message. Like show an example 565@c of what it pops up in the editor, for example. Also 566@c a discussion of how to get the "a)bort, c)ontinue, 567@c e)dit" prompt and what to do with it. Might also 568@c work in the suggestion that if you want a diff, you 569@c should make it before running commit (someone 570@c suggested that the diff pop up in the editor. I'm 571@c not sure that is better than telling people to run 572@c "cvs diff" first if that is what they want, but if 573@c we want to tell people that, the manual possibly 574@c should say it). 575 576If you want to avoid 577starting an editor you can specify the log message on 578the command line using the @samp{-m} flag instead, like 579this: 580 581@example 582$ cvs commit -m "Added an optimization pass" backend.c 583@end example 584 585@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 586@node Cleaning up 587@subsection Cleaning up 588@cindex Cleaning up 589@cindex Working copy, removing 590@cindex Removing your working copy 591@cindex Releasing your working copy 592 593Before you turn to other tasks you decide to remove your working copy of 594tc. One acceptable way to do that is of course 595 596@example 597$ cd .. 598$ rm -r tc 599@end example 600 601@noindent 602but a better way is to use the @code{release} command (@pxref{release}): 603 604@example 605$ cd .. 606$ cvs release -d tc 607M driver.c 608? tc 609You have [1] altered files in this repository. 610Are you sure you want to release (and delete) directory `tc': n 611** `release' aborted by user choice. 612@end example 613 614The @code{release} command checks that all your modifications have been 615committed. If history logging is enabled it also makes a note in the 616history file. @xref{history file}. 617 618When you use the @samp{-d} flag with @code{release}, it 619also removes your working copy. 620 621In the example above, the @code{release} command wrote a couple of lines 622of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. 623That is nothing to worry about: @file{tc} is the executable compiler, 624and it should not be stored in the repository. @xref{cvsignore}, 625for information about how to make that warning go away. 626@xref{release output}, for a complete explanation of 627all possible output from @code{release}. 628 629@samp{M driver.c} is more serious. It means that the 630file @file{driver.c} has been modified since it was 631checked out. 632 633The @code{release} command always finishes by telling 634you how many modified files you have in your working 635copy of the sources, and then asks you for confirmation 636before deleting any files or making any note in the 637history file. 638 639You decide to play it safe and answer @kbd{n @key{RET}} 640when @code{release} asks for confirmation. 641 642@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 643@node Viewing differences 644@subsection Viewing differences 645@cindex Viewing differences 646@cindex Diff 647 648You do not remember modifying @file{driver.c}, so you want to see what 649has happened to that file. 650 651@example 652$ cd tc 653$ cvs diff driver.c 654@end example 655 656This command runs @code{diff} to compare the version of @file{driver.c} 657that you checked out with your working copy. When you see the output 658you remember that you added a command line option that enabled the 659optimization pass. You check it in, and release the module. 660@c FIXME: we haven't yet defined the term "check in". 661 662@example 663$ cvs commit -m "Added an optimization pass" driver.c 664Checking in driver.c; 665/usr/local/cvsroot/tc/driver.c,v <-- driver.c 666new revision: 1.2; previous revision: 1.1 667done 668$ cd .. 669$ cvs release -d tc 670? tc 671You have [0] altered files in this repository. 672Are you sure you want to release (and delete) directory `tc': y 673@end example 674 675@c --------------------------------------------------------------------- 676@node Repository 677@chapter The Repository 678@cindex Repository (intro) 679@cindex Repository, example 680@cindex Layout of repository 681@cindex Typical repository 682@cindex /usr/local/cvsroot, as example repository 683@cindex cvsroot 684 685The @sc{cvs} @dfn{repository} stores a complete copy of 686all the files and directories which are under version 687control. 688 689Normally, you never access any of the files in the 690repository directly. Instead, you use @sc{cvs} 691commands to get your own copy of the files into a 692@dfn{working directory}, and then 693work on that copy. When you've finished a set of 694changes, you check (or @dfn{commit}) them back into the 695repository. The repository then contains the changes 696which you have made, as well as recording exactly what 697you changed, when you changed it, and other such 698information. Note that the repository is not a 699subdirectory of the working directory, or vice versa; 700they should be in separate locations. 701@c Need some example, e.g. repository 702@c /usr/local/cvsroot; working directory 703@c /home/joe/sources. But this node is too long 704@c as it is; need a little reorganization... 705 706@cindex :local:, setting up 707@sc{cvs} can access a repository by a variety of 708means. It might be on the local computer, or it might 709be on a computer across the room or across the world. 710To distinguish various ways to access a repository, the 711repository name can start with an @dfn{access method}. 712For example, the access method @code{:local:} means to 713access a repository directory, so the repository 714@code{:local:/usr/local/cvsroot} means that the 715repository is in @file{/usr/local/cvsroot} on the 716computer running @sc{cvs}. For information on other 717access methods, see @ref{Remote repositories}. 718 719@c Can se say this more concisely? Like by passing 720@c more of the buck to the Remote repositories node? 721If the access method is omitted, then if the repository 722starts with @samp{/}, then @code{:local:} is 723assumed. If it does not start with @samp{/} then either 724@code{:ext:} or @code{:server:} is assumed. For 725example, if you have a local repository in 726@file{/usr/local/cvsroot}, you can use 727@code{/usr/local/cvsroot} instead of 728@code{:local:/usr/local/cvsroot}. But if (under 729Windows NT, for example) your local repository is 730@file{c:\src\cvsroot}, then you must specify the access 731method, as in @code{:local:c:/src/cvsroot}. 732 733@c This might appear to go in Repository storage, but 734@c actually it is describing something which is quite 735@c user-visible, when you do a "cvs co CVSROOT". This 736@c isn't necessary the perfect place for that, though. 737The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains 738administrative files for @sc{cvs}. The other directories contain the actual 739user-defined modules. 740 741@menu 742* Specifying a repository:: Telling CVS where your repository is 743* Repository storage:: The structure of the repository 744* Working directory storage:: The structure of working directories 745* Intro administrative files:: Defining modules 746* Multiple repositories:: Multiple repositories 747* Creating a repository:: Creating a repository 748* Backing up:: Backing up a repository 749* Moving a repository:: Moving a repository 750* Remote repositories:: Accessing repositories on remote machines 751* Read-only access:: Granting read-only access to the repository 752* Server temporary directory:: The server creates temporary directories 753@end menu 754 755@node Specifying a repository 756@section Telling CVS where your repository is 757 758There are several ways to tell @sc{cvs} 759where to find the repository. You can name the 760repository on the command line explicitly, with the 761@code{-d} (for "directory") option: 762 763@example 764cvs -d /usr/local/cvsroot checkout yoyodyne/tc 765@end example 766 767@cindex .profile, setting CVSROOT in 768@cindex .cshrc, setting CVSROOT in 769@cindex .tcshrc, setting CVSROOT in 770@cindex .bashrc, setting CVSROOT in 771@cindex CVSROOT, environment variable 772 Or you can set the @code{$CVSROOT} environment 773variable to an absolute path to the root of the 774repository, @file{/usr/local/cvsroot} in this example. 775To set @code{$CVSROOT}, @code{csh} and @code{tcsh} 776users should have this line in their @file{.cshrc} or 777@file{.tcshrc} files: 778 779@example 780setenv CVSROOT /usr/local/cvsroot 781@end example 782 783@noindent 784@code{sh} and @code{bash} users should instead have these lines in their 785@file{.profile} or @file{.bashrc}: 786 787@example 788CVSROOT=/usr/local/cvsroot 789export CVSROOT 790@end example 791 792@cindex Root file, in CVS directory 793@cindex CVS/Root file 794 A repository specified with @code{-d} will 795override the @code{$CVSROOT} environment variable. 796Once you've checked a working copy out from the 797repository, it will remember where its repository is 798(the information is recorded in the 799@file{CVS/Root} file in the working copy). 800 801The @code{-d} option and the @file{CVS/Root} file both 802override the @code{$CVSROOT} environment variable. If 803@code{-d} option differs from @file{CVS/Root}, the 804former is used. Of course, for proper operation they 805should be two ways of referring to the same repository. 806 807@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 808@node Repository storage 809@section How data is stored in the repository 810@cindex Repository, how data is stored 811 812For most purposes it isn't important @emph{how} 813@sc{cvs} stores information in the repository. In 814fact, the format has changed in the past, and is likely 815to change in the future. Since in almost all cases one 816accesses the repository via @sc{cvs} commands, such 817changes need not be disruptive. 818 819However, in some cases it may be necessary to 820understand how @sc{cvs} stores data in the repository, 821for example you might need to track down @sc{cvs} locks 822(@pxref{Concurrency}) or you might need to deal with 823the file permissions appropriate for the repository. 824 825@menu 826* Repository files:: What files are stored in the repository 827* File permissions:: File permissions 828* Windows permissions:: Issues specific to Windows 829* Attic:: Some files are stored in the Attic 830* CVS in repository:: Additional information in CVS directory 831* Locks:: CVS locks control concurrent accesses 832* CVSROOT storage:: A few things about CVSROOT are different 833@end menu 834 835@node Repository files 836@subsection Where files are stored within the repository 837 838@c @cindex Filenames, legal 839@c @cindex Legal filenames 840@c Somewhere we need to say something about legitimate 841@c characters in filenames in working directory and 842@c repository. Not "/" (not even on non-unix). And 843@c here is a specific set of issues: 844@c Files starting with a - are handled inconsistently. They can not 845@c be added to a repository with an add command, because it they are 846@c interpreted as a switch. They can appear in a repository if they are 847@c part of a tree that is imported. They can not be removed from the tree 848@c once they are there. 849@c Note that "--" *is* supported (as a 850@c consequence of using GNU getopt). Should document 851@c this somewhere ("Common options"?). The other usual technique, 852@c "./-foo", isn't as effective, at least for "cvs add" 853@c which doesn't support pathnames containing "/". 854 855The overall structure of the repository is a directory 856tree corresponding to the directories in the working 857directory. For example, supposing the repository is in 858 859@example 860/usr/local/cvsroot 861@end example 862 863@noindent 864here is a possible directory tree (showing only the 865directories): 866 867@example 868@t{/usr} 869 | 870 +--@t{local} 871 | | 872 | +--@t{cvsroot} 873 | | | 874 | | +--@t{CVSROOT} 875 | (administrative files) 876 | 877 +--@t{gnu} 878 | | 879 | +--@t{diff} 880 | | (source code to @sc{gnu} diff) 881 | | 882 | +--@t{rcs} 883 | | (source code to @sc{rcs}) 884 | | 885 | +--@t{cvs} 886 | (source code to @sc{cvs}) 887 | 888 +--@t{yoyodyne} 889 | 890 +--@t{tc} 891 | | 892 | +--@t{man} 893 | | 894 | +--@t{testing} 895 | 896 +--(other Yoyodyne software) 897@end example 898 899With the directories are @dfn{history files} for each file 900under version control. The name of the history file is 901the name of the corresponding file with @samp{,v} 902appended to the end. Here is what the repository for 903the @file{yoyodyne/tc} directory might look like: 904@c FIXME: Should also mention CVS (CVSREP) 905@c FIXME? Should we introduce Attic with an xref to 906@c Attic? Not sure whether that is a good idea or not. 907@example 908 @code{$CVSROOT} 909 | 910 +--@t{yoyodyne} 911 | | 912 | +--@t{tc} 913 | | | 914 +--@t{Makefile,v} 915 +--@t{backend.c,v} 916 +--@t{driver.c,v} 917 +--@t{frontend.c,v} 918 +--@t{parser.c,v} 919 +--@t{man} 920 | | 921 | +--@t{tc.1,v} 922 | 923 +--@t{testing} 924 | 925 +--@t{testpgm.t,v} 926 +--@t{test2.t,v} 927@end example 928 929@cindex History files 930@cindex RCS history files 931@c The first sentence, about what history files 932@c contain, is kind of redundant with our intro to what the 933@c repository does in node Repository.... 934The history files contain, among other things, enough 935information to recreate any revision of the file, a log 936of all commit messages and the user-name of the person 937who committed the revision. The history files are 938known as @dfn{RCS files}, because the first program to 939store files in that format was a version control system 940known as @sc{rcs}. For a full 941description of the file format, see the @code{man} page 942@cite{rcsfile(5)}, distributed with @sc{rcs}, or the 943file @file{doc/RCSFILES} in the @sc{cvs} source 944distribution. This 945file format has become very common---many systems other 946than @sc{cvs} or @sc{rcs} can at least import history 947files in this format. 948@c FIXME: Think about including documentation for this 949@c rather than citing it? In the long run, getting 950@c this to be a standard (not sure if we can cope with 951@c a standards process as formal as IEEE/ANSI/ISO/etc, 952@c though...) is the way to go, so maybe citing is 953@c better. 954 955The @sc{rcs} files used in @sc{cvs} differ in a few 956ways from the standard format. The biggest difference 957is magic branches; for more information see @ref{Magic 958branch numbers}. Also in @sc{cvs} the valid tag names 959are a subset of what @sc{rcs} accepts; for @sc{cvs}'s 960rules see @ref{Tags}. 961 962@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963@node File permissions 964@subsection File permissions 965@c -- Move this to @node Creating a repository or similar 966@cindex Security, file permissions in repository 967@cindex File permissions, general 968@cindex Permissions, general 969@c FIXME: we need to somehow reflect "permissions in 970@c repository" versus "permissions in working 971@c directory" in the index entries. 972@cindex Group 973@cindex Read-only files, in repository 974All @samp{,v} files are created read-only, and you 975should not change the permission of those files. The 976directories inside the repository should be writable by 977the persons that have permission to modify the files in 978each directory. This normally means that you must 979create a UNIX group (see group(5)) consisting of the 980persons that are to edit the files in a project, and 981set up the repository so that it is that group that 982owns the directory. 983(On some systems, you also need to set the set-group-ID-on-execution bit 984on the repository directories (see chmod(1)) so that newly-created files 985and directories get the group-ID of the parent directory rather than 986that of the current process.) 987 988@c See also comment in commitinfo node regarding cases 989@c which are really awkward with unix groups. 990 991This means that you can only control access to files on 992a per-directory basis. 993 994Note that users must also have write access to check 995out files, because @sc{cvs} needs to create lock files 996(@pxref{Concurrency}). You can use LockDir in CVSROOT/config 997to put the lock files somewhere other than in the repository 998if you want to allow read-only access to some directories 999(@pxref{config}). 1000 1001@c CVS seems to use CVSUMASK in picking permissions for 1002@c val-tags, but maybe we should say more about this. 1003@c Like val-tags gets created by someone who doesn't 1004@c have CVSUMASK set right? 1005Also note that users must have write access to the 1006@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep 1007track of what tags are valid tag names (it is sometimes 1008updated when tags are used, as well as when they are 1009created). 1010 1011Each @sc{rcs} file will be owned by the user who last 1012checked it in. This has little significance; what 1013really matters is who owns the directories. 1014 1015@cindex CVSUMASK, environment variable 1016@cindex Umask, for repository files 1017@sc{cvs} tries to set up reasonable file permissions 1018for new directories that are added inside the tree, but 1019you must fix the permissions manually when a new 1020directory should have different permissions than its 1021parent directory. If you set the @code{CVSUMASK} 1022environment variable that will control the file 1023permissions which @sc{cvs} uses in creating directories 1024and/or files in the repository. @code{CVSUMASK} does 1025not affect the file permissions in the working 1026directory; such files have the permissions which are 1027typical for newly created files, except that sometimes 1028@sc{cvs} creates them read-only (see the sections on 1029watches, @ref{Setting a watch}; -r, @ref{Global 1030options}; or @code{CVSREAD}, @ref{Environment variables}). 1031@c FIXME: Need more discussion of which 1032@c group should own the file in the repository. 1033@c Include a somewhat detailed example of the usual 1034@c case where CVSUMASK is 007, the developers are all 1035@c in a group, and that group owns stuff in the 1036@c repository. Need to talk about group ownership of 1037@c newly-created directories/files (on some unices, 1038@c such as SunOS4, setting the setgid bit on the 1039@c directories will make files inherit the directory's 1040@c group. On other unices, your mileage may vary. I 1041@c can't remember what POSIX says about this, if 1042@c anything). 1043 1044Note that using the client/server @sc{cvs} 1045(@pxref{Remote repositories}), there is no good way to 1046set @code{CVSUMASK}; the setting on the client machine 1047has no effect. If you are connecting with @code{rsh}, you 1048can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as 1049described in the documentation for your operating 1050system. This behavior might change in future versions 1051of @sc{cvs}; do not rely on the setting of 1052@code{CVSUMASK} on the client having no effect. 1053@c FIXME: need to explain what a umask is or cite 1054@c someplace which does. 1055@c 1056@c There is also a larger (largely separate) issue 1057@c about the meaning of CVSUMASK in a non-unix context. 1058@c For example, whether there is 1059@c an equivalent which fits better into other 1060@c protection schemes like POSIX.6, VMS, &c. 1061@c 1062@c FIXME: Need one place which discusses this 1063@c read-only files thing. Why would one use -r or 1064@c CVSREAD? Why would one use watches? How do they 1065@c interact? 1066@c 1067@c FIXME: We need to state 1068@c whether using CVSUMASK removes the need for manually 1069@c fixing permissions (in fact, if we are going to mention 1070@c manually fixing permission, we better document a lot 1071@c better just what we mean by "fix"). 1072 1073Using pserver, you will generally need stricter 1074permissions on the @sc{cvsroot} directory and 1075directories above it in the tree; see @ref{Password 1076authentication security}. 1077 1078@cindex Setuid 1079@cindex Setgid 1080@cindex Security, setuid 1081@cindex Installed images (VMS) 1082Some operating systems have features which allow a 1083particular program to run with the ability to perform 1084operations which the caller of the program could not. 1085For example, the set user ID (setuid) or set group ID 1086(setgid) features of unix or the installed image 1087feature of VMS. @sc{cvs} was not written to use such 1088features and therefore attempting to install @sc{cvs} in 1089this fashion will provide protection against only 1090accidental lapses; anyone who is trying to circumvent 1091the measure will be able to do so, and depending on how 1092you have set it up may gain access to more than just 1093@sc{cvs}. You may wish to instead consider pserver. It 1094shares some of the same attributes, in terms of 1095possibly providing a false sense of security or opening 1096security holes wider than the ones you are trying to 1097fix, so read the documentation on pserver security 1098carefully if you are considering this option 1099(@ref{Password authentication security}). 1100 1101@node Windows permissions 1102@subsection File Permission issues specific to Windows 1103@cindex Windows, and permissions 1104@cindex File permissions, Windows-specific 1105@cindex Permissions, Windows-specific 1106 1107Some file permission issues are specific to Windows 1108operating systems (Windows 95, Windows NT, and 1109presumably future operating systems in this family. 1110Some of the following might apply to OS/2 but I'm not 1111sure). 1112 1113If you are using local @sc{cvs} and the repository is on a 1114networked file system which is served by the Samba SMB 1115server, some people have reported problems with 1116permissions. Enabling WRITE=YES in the samba 1117configuration is said to fix/workaround it. 1118Disclaimer: I haven't investigated enough to know the 1119implications of enabling that option, nor do I know 1120whether there is something which @sc{cvs} could be doing 1121differently in order to avoid the problem. If you find 1122something out, please let us know as described in 1123@ref{BUGS}. 1124 1125@node Attic 1126@subsection The attic 1127@cindex Attic 1128 1129You will notice that sometimes @sc{cvs} stores an 1130@sc{rcs} file in the @code{Attic}. For example, if the 1131@sc{cvsroot} is @file{/usr/local/cvsroot} and we are 1132talking about the file @file{backend.c} in the 1133directory @file{yoyodyne/tc}, then the file normally 1134would be in 1135 1136@example 1137/usr/local/cvsroot/yoyodyne/tc/backend.c,v 1138@end example 1139 1140@noindent 1141but if it goes in the attic, it would be in 1142 1143@example 1144/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v 1145@end example 1146 1147@noindent 1148@cindex Dead state 1149instead. It should not matter from a user point of 1150view whether a file is in the attic; @sc{cvs} keeps 1151track of this and looks in the attic when it needs to. 1152But in case you want to know, the rule is that the RCS 1153file is stored in the attic if and only if the head 1154revision on the trunk has state @code{dead}. A 1155@code{dead} state means that file has been removed, or 1156never added, for that revision. For example, if you 1157add a file on a branch, it will have a trunk revision 1158in @code{dead} state, and a branch revision in a 1159non-@code{dead} state. 1160@c Probably should have some more concrete examples 1161@c here, or somewhere (not sure exactly how we should 1162@c arrange the discussion of the dead state, versus 1163@c discussion of the attic). 1164 1165@node CVS in repository 1166@subsection The CVS directory in the repository 1167@cindex CVS directory, in repository 1168 1169The @file{CVS} directory in each repository directory 1170contains information such as file attributes (in a file 1171called @file{CVS/fileattr}. In the 1172future additional files may be added to this directory, 1173so implementations should silently ignore additional 1174files. 1175 1176This behavior is implemented only by @sc{cvs} 1.7 and 1177later; for details see @ref{Watches Compatibility}. 1178 1179The format of the fileattr file is a series of entries 1180of the following form (where @samp{@{} and @samp{@}} 1181means the text between the braces can be repeated zero 1182or more times): 1183 1184@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} 1185 @{; @var{attrname} = @var{attrval}@} <linefeed> 1186 1187@var{ent-type} is @samp{F} for a file, in which case the entry specifies the 1188attributes for that file. 1189 1190@var{ent-type} is @samp{D}, 1191and @var{filename} empty, to specify default attributes 1192to be used for newly added files. 1193 1194Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older 1195will delete them any time it writes file attributes. 1196@sc{cvs} 1.10 and later will preserve them. 1197 1198Note that the order of the lines is not significant; 1199a program writing the fileattr file may 1200rearrange them at its convenience. 1201 1202There is currently no way of quoting tabs or linefeeds in the 1203filename, @samp{=} in @var{attrname}, 1204@samp{;} in @var{attrval}, etc. Note: some implementations also 1205don't handle a NUL character in any of the fields, but 1206implementations are encouraged to allow it. 1207 1208By convention, @var{attrname} starting with @samp{_} is for an attribute given 1209special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes 1210(or will be, once implementations start supporting user-defined attributes). 1211 1212Builtin attributes: 1213 1214@table @code 1215@item _watched 1216Present means the file is watched and should be checked out 1217read-only. 1218 1219@item _watchers 1220Users with watches for this file. Value is 1221@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} 1222where @var{watcher} is a username, and @var{type} 1223is zero or more of edit,unedit,commit separated by 1224@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). 1225 1226@item _editors 1227Users editing this file. Value is 1228@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} 1229where @var{editor} is a username, and @var{val} is 1230@var{time}+@var{hostname}+@var{pathname}, where 1231@var{time} is when the @code{cvs edit} command (or 1232equivalent) happened, 1233and @var{hostname} and @var{pathname} are for the working directory. 1234@end table 1235 1236Example: 1237 1238@c FIXME: sanity.sh should contain a similar test case 1239@c so we can compare this example from something from 1240@c Real Life(TM). See cvsclient.texi (under Notify) for more 1241@c discussion of the date format of _editors. 1242@example 1243Ffile1 _watched=;_watchers=joe>edit,mary>commit 1244Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs 1245D _watched= 1246@end example 1247 1248@noindent 1249means that the file @file{file1} should be checked out 1250read-only. Furthermore, joe is watching for edits and 1251mary is watching for commits. The file @file{file2} 1252should be checked out read-only; sue started editing it 1253on 8 Jan 1975 in the directory @file{/home/sue/cvs} on 1254the machine @code{workstn1}. Future files which are 1255added should be checked out read-only. To represent 1256this example here, we have shown a space after 1257@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact 1258there must be a single tab character there and no spaces. 1259 1260@node Locks 1261@subsection CVS locks in the repository 1262 1263@cindex #cvs.rfl, technical details 1264@cindex #cvs.wfl, technical details 1265@cindex #cvs.lock, technical details 1266@cindex Locks, cvs, technical details 1267For an introduction to @sc{cvs} locks focusing on 1268user-visible behavior, see @ref{Concurrency}. The 1269following section is aimed at people who are writing 1270tools which want to access a @sc{cvs} repository without 1271interfering with other tools accessing the same 1272repository. If you find yourself confused by concepts 1273described here, like @dfn{read lock}, @dfn{write lock}, 1274and @dfn{deadlock}, you might consult the literature on 1275operating systems or databases. 1276 1277@cindex #cvs.tfl 1278Any file in the repository with a name starting 1279with @file{#cvs.rfl.} is a read lock. Any file in 1280the repository with a name starting with 1281@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} 1282(before @sc{cvs} 1.5) also created files with names starting 1283with @file{#cvs.tfl}, but they are not discussed here. 1284The directory @file{#cvs.lock} serves as a master 1285lock. That is, one must obtain this lock first before 1286creating any of the other locks. 1287 1288To obtain a readlock, first create the @file{#cvs.lock} 1289directory. This operation must be atomic (which should 1290be true for creating a directory under most operating 1291systems). If it fails because the directory already 1292existed, wait for a while and try again. After 1293obtaining the @file{#cvs.lock} lock, create a file 1294whose name is @file{#cvs.rfl.} followed by information 1295of your choice (for example, hostname and process 1296identification number). Then remove the 1297@file{#cvs.lock} directory to release the master lock. 1298Then proceed with reading the repository. When you are 1299done, remove the @file{#cvs.rfl} file to release the 1300read lock. 1301 1302To obtain a writelock, first create the 1303@file{#cvs.lock} directory, as with a readlock. Then 1304check that there are no files whose names start with 1305@file{#cvs.rfl.}. If there are, remove 1306@file{#cvs.lock}, wait for a while, and try again. If 1307there are no readers, then create a file whose name is 1308@file{#cvs.wfl} followed by information of your choice 1309(for example, hostname and process identification 1310number). Hang on to the @file{#cvs.lock} lock. Proceed 1311with writing the repository. When you are done, first 1312remove the @file{#cvs.wfl} file and then the 1313@file{#cvs.lock} directory. Note that unlike the 1314@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just 1315informational; it has no effect on the locking operation 1316beyond what is provided by holding on to the 1317@file{#cvs.lock} lock itself. 1318 1319Note that each lock (writelock or readlock) only locks 1320a single directory in the repository, including 1321@file{Attic} and @file{CVS} but not including 1322subdirectories which represent other directories under 1323version control. To lock an entire tree, you need to 1324lock each directory (note that if you fail to obtain 1325any lock you need, you must release the whole tree 1326before waiting and trying again, to avoid deadlocks). 1327 1328Note also that @sc{cvs} expects writelocks to control 1329access to individual @file{foo,v} files. @sc{rcs} has 1330a scheme where the @file{,foo,} file serves as a lock, 1331but @sc{cvs} does not implement it and so taking out a 1332@sc{cvs} writelock is recommended. See the comments at 1333rcs_internal_lockfile in the @sc{cvs} source code for 1334further discussion/rationale. 1335 1336@node CVSROOT storage 1337@subsection How files are stored in the CVSROOT directory 1338@cindex CVSROOT, storage of files 1339 1340The @file{$CVSROOT/CVSROOT} directory contains the 1341various administrative files. In some ways this 1342directory is just like any other directory in the 1343repository; it contains @sc{rcs} files whose names end 1344in @samp{,v}, and many of the @sc{cvs} commands operate 1345on it the same way. However, there are a few 1346differences. 1347 1348For each administrative file, in addition to the 1349@sc{rcs} file, there is also a checked out copy of the 1350file. For example, there is an @sc{rcs} file 1351@file{loginfo,v} and a file @file{loginfo} which 1352contains the latest revision contained in 1353@file{loginfo,v}. When you check in an administrative 1354file, @sc{cvs} should print 1355 1356@example 1357cvs commit: Rebuilding administrative file database 1358@end example 1359 1360@noindent 1361and update the checked out copy in 1362@file{$CVSROOT/CVSROOT}. If it does not, there is 1363something wrong (@pxref{BUGS}). To add your own files 1364to the files to be updated in this fashion, you can add 1365them to the @file{checkoutlist} administrative file 1366(@pxref{checkoutlist}). 1367 1368@cindex modules.db 1369@cindex modules.pag 1370@cindex modules.dir 1371By default, the @file{modules} file behaves as 1372described above. If the modules file is very large, 1373storing it as a flat text file may make looking up 1374modules slow (I'm not sure whether this is as much of a 1375concern now as when @sc{cvs} first evolved this 1376feature; I haven't seen benchmarks). Therefore, by 1377making appropriate edits to the @sc{cvs} source code 1378one can store the modules file in a database which 1379implements the @code{ndbm} interface, such as Berkeley 1380db or GDBM. If this option is in use, then the modules 1381database will be stored in the files @file{modules.db}, 1382@file{modules.pag}, and/or @file{modules.dir}. 1383@c I think fileattr also will use the database stuff. 1384@c Anything else? 1385 1386For information on the meaning of the various 1387administrative files, see @ref{Administrative files}. 1388 1389@node Working directory storage 1390@section How data is stored in the working directory 1391 1392@c FIXME: Somewhere we should discuss timestamps (test 1393@c case "stamps" in sanity.sh). But not here. Maybe 1394@c in some kind of "working directory" chapter which 1395@c would encompass the "Builds" one? But I'm not sure 1396@c whether that is a good organization (is it based on 1397@c what the user wants to do?). 1398 1399@cindex CVS directory, in working directory 1400While we are discussing @sc{cvs} internals which may 1401become visible from time to time, we might as well talk 1402about what @sc{cvs} puts in the @file{CVS} directories 1403in the working directories. As with the repository, 1404@sc{cvs} handles this information and one can usually 1405access it via @sc{cvs} commands. But in some cases it 1406may be useful to look at it, and other programs, such 1407as the @code{jCVS} graphical user interface or the 1408@code{VC} package for emacs, may need to look at it. 1409Such programs should follow the recommendations in this 1410section if they hope to be able to work with other 1411programs which use those files, including future 1412versions of the programs just mentioned and the 1413command-line @sc{cvs} client. 1414 1415The @file{CVS} directory contains several files. 1416Programs which are reading this directory should 1417silently ignore files which are in the directory but 1418which are not documented here, to allow for future 1419expansion. 1420 1421The files are stored according to the text file 1422convention for the system in question. This means that 1423working directories are not portable between systems 1424with differing conventions for storing text files. 1425This is intentional, on the theory that the files being 1426managed by @sc{cvs} probably will not be portable between 1427such systems either. 1428 1429@table @file 1430@item Root 1431This file contains the current @sc{cvs} root, as 1432described in @ref{Specifying a repository}. 1433 1434@cindex Repository file, in CVS directory 1435@cindex CVS/Repository file 1436@item Repository 1437This file contains the directory within the repository 1438which the current directory corresponds with. It can 1439be either an absolute pathname or a relative pathname; 1440@sc{cvs} has had the ability to read either format 1441since at least version 1.3 or so. The relative 1442pathname is relative to the root, and is the more 1443sensible approach, but the absolute pathname is quite 1444common and implementations should accept either. For 1445example, after the command 1446 1447@example 1448cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc 1449@end example 1450 1451@noindent 1452@file{Root} will contain 1453 1454@example 1455:local:/usr/local/cvsroot 1456@end example 1457 1458@noindent 1459and @file{Repository} will contain either 1460 1461@example 1462/usr/local/cvsroot/yoyodyne/tc 1463@end example 1464 1465@noindent 1466or 1467 1468@example 1469yoyodyne/tc 1470@end example 1471 1472If the particular working directory does not correspond 1473to a directory in the repository, then @file{Repository} 1474should contain @file{CVSROOT/Emptydir}. 1475@cindex Emptydir, in CVSROOT directory 1476@cindex CVSROOT/Emptydir directory 1477 1478@cindex Entries file, in CVS directory 1479@cindex CVS/Entries file 1480@item Entries 1481This file lists the files and directories in the 1482working directory. 1483The first character of each line indicates what sort of 1484line it is. If the character is unrecognized, programs 1485reading the file should silently skip that line, to 1486allow for future expansion. 1487 1488If the first character is @samp{/}, then the format is: 1489 1490@example 1491/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate} 1492@end example 1493 1494@noindent 1495where @samp{[} and @samp{]} are not part of the entry, 1496but instead indicate that the @samp{+} and conflict 1497marker are optional. @var{name} is the name of the 1498file within the directory. @var{revision} is the 1499revision that the file in the working derives from, or 1500@samp{0} for an added file, or @samp{-} followed by a 1501revision for a removed file. @var{timestamp} is the 1502timestamp of the file at the time that @sc{cvs} created 1503it; if the timestamp differs with the actual 1504modification time of the file it means the file has 1505been modified. It is stored in 1506the format used by the ISO C asctime() function (for 1507example, @samp{Sun Apr 7 01:29:26 1996}). One may 1508write a string which is not in that format, for 1509example, @samp{Result of merge}, to indicate that the 1510file should always be considered to be modified. This 1511is not a special case; to see whether a file is 1512modified a program should take the timestamp of the file 1513and simply do a string compare with @var{timestamp}. 1514If there was a conflict, @var{conflict} can be set to 1515the modification time of the file after the file has been 1516written with conflict markers (@pxref{Conflicts example}). 1517Thus if @var{conflict} is subsequently the same as the actual 1518modification time of the file it means that the user 1519has obviously not resolved the conflict. @var{options} 1520contains sticky options (for example @samp{-kb} for a 1521binary file). @var{tagdate} contains @samp{T} followed 1522by a tag name, or @samp{D} for a date, followed by a 1523sticky tag or date. Note that if @var{timestamp} 1524contains a pair of timestamps separated by a space, 1525rather than a single timestamp, you are dealing with a 1526version of @sc{cvs} earlier than @sc{cvs} 1.5 (not 1527documented here). 1528 1529The timezone on the timestamp in CVS/Entries (local or 1530universal) should be the same as the operating system 1531stores for the timestamp of the file itself. For 1532example, on Unix the file's timestamp is in universal 1533time (UT), so the timestamp in CVS/Entries should be 1534too. On @sc{vms}, the file's timestamp is in local 1535time, so @sc{cvs} on @sc{vms} should use local time. 1536This rule is so that files do not appear to be modified 1537merely because the timezone changed (for example, to or 1538from summer time). 1539@c See comments and calls to gmtime() and friends in 1540@c src/vers_ts.c (function time_stamp). 1541 1542If the first character of a line in @file{Entries} is 1543@samp{D}, then it indicates a subdirectory. @samp{D} 1544on a line all by itself indicates that the program 1545which wrote the @file{Entries} file does record 1546subdirectories (therefore, if there is such a line and 1547no other lines beginning with @samp{D}, one knows there 1548are no subdirectories). Otherwise, the line looks 1549like: 1550 1551@example 1552D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} 1553@end example 1554 1555@noindent 1556where @var{name} is the name of the subdirectory, and 1557all the @var{filler} fields should be silently ignored, 1558for future expansion. Programs which modify 1559@code{Entries} files should preserve these fields. 1560 1561The lines in the @file{Entries} file can be in any order. 1562 1563@cindex Entries.Log file, in CVS directory 1564@cindex CVS/Entries.Log file 1565@item Entries.Log 1566This file does not record any information beyond that 1567in @file{Entries}, but it does provide a way to update 1568the information without having to rewrite the entire 1569@file{Entries} file, including the ability to preserve 1570the information even if the program writing 1571@file{Entries} and @file{Entries.Log} abruptly aborts. 1572Programs which are reading the @file{Entries} file 1573should also check for @file{Entries.Log}. If the latter 1574exists, they should read @file{Entries} and then apply 1575the changes mentioned in @file{Entries.Log}. After 1576applying the changes, the recommended practice is to 1577rewrite @file{Entries} and then delete @file{Entries.Log}. 1578The format of a line in @file{Entries.Log} is a single 1579character command followed by a space followed by a 1580line in the format specified for a line in 1581@file{Entries}. The single character command is 1582@samp{A} to indicate that the entry is being added, 1583@samp{R} to indicate that the entry is being removed, 1584or any other character to indicate that the entire line 1585in @file{Entries.Log} should be silently ignored (for 1586future expansion). If the second character of the line 1587in @file{Entries.Log} is not a space, then it was 1588written by an older version of @sc{cvs} (not documented 1589here). 1590 1591Programs which are writing rather than reading can 1592safely ignore @file{Entries.Log} if they so choose. 1593 1594@cindex Entries.Backup file, in CVS directory 1595@cindex CVS/Entries.Backup file 1596@item Entries.Backup 1597This is a temporary file. Recommended usage is to 1598write a new entries file to @file{Entries.Backup}, and 1599then to rename it (atomically, where possible) to @file{Entries}. 1600 1601@cindex Entries.Static file, in CVS directory 1602@cindex CVS/Entries.Static file 1603@item Entries.Static 1604The only relevant thing about this file is whether it 1605exists or not. If it exists, then it means that only 1606part of a directory was gotten and @sc{cvs} will 1607not create additional files in that directory. To 1608clear it, use the @code{update} command with the 1609@samp{-d} option, which will get the additional files 1610and remove @file{Entries.Static}. 1611@c FIXME: This needs to be better documented, in places 1612@c other than Working Directory Storage. 1613@c FIXCVS: The fact that this setting exists needs to 1614@c be more visible to the user. For example "cvs 1615@c status foo", in the case where the file would be 1616@c gotten except for Entries.Static, might say 1617@c something to distinguish this from other cases. 1618@c One thing that periodically gets suggested is to 1619@c have "cvs update" print something when it skips 1620@c files due to Entries.Static, but IMHO that kind of 1621@c noise pretty much makes the Entries.Static feature 1622@c useless. 1623 1624@cindex Tag file, in CVS directory 1625@cindex CVS/Tag file 1626@cindex Sticky tags/dates, per-directory 1627@cindex Per-directory sticky tags/dates 1628@item Tag 1629This file contains per-directory sticky tags or dates. 1630The first character is @samp{T} for a branch tag, 1631@samp{N} for a non-branch tag, or @samp{D} for a date, 1632or another character to mean the file should be 1633silently ignored, for future expansion. This character 1634is followed by the tag or date. Note that 1635per-directory sticky tags or dates are used for things 1636like applying to files which are newly added; they 1637might not be the same as the sticky tags or dates on 1638individual files. For general information on sticky 1639tags and dates, see @ref{Sticky tags}. 1640@c FIXME: This needs to be much better documented, 1641@c preferably not in the context of "working directory 1642@c storage". 1643@c FIXME: The Sticky tags node needs to discuss, or xref to 1644@c someplace which discusses, per-directory sticky 1645@c tags and the distinction with per-file sticky tags. 1646 1647@cindex Notify file, in CVS directory 1648@cindex CVS/Notify file 1649@item Notify 1650This file stores notifications (for example, for 1651@code{edit} or @code{unedit}) which have not yet been 1652sent to the server. Its format is not yet documented 1653here. 1654 1655@cindex Notify.tmp file, in CVS directory 1656@cindex CVS/Notify.tmp file 1657@item Notify.tmp 1658This file is to @file{Notify} as @file{Entries.Backup} 1659is to @file{Entries}. That is, to write @file{Notify}, 1660first write the new contents to @file{Notify.tmp} and 1661then (atomically where possible), rename it to 1662@file{Notify}. 1663 1664@cindex Base directory, in CVS directory 1665@cindex CVS/Base directory 1666@item Base 1667If watches are in use, then an @code{edit} command 1668stores the original copy of the file in the @file{Base} 1669directory. This allows the @code{unedit} command to 1670operate even if it is unable to communicate with the 1671server. 1672 1673@cindex Baserev file, in CVS directory 1674@cindex CVS/Baserev file 1675@item Baserev 1676The file lists the revision for each of the files in 1677the @file{Base} directory. The format is: 1678 1679@example 1680B@var{name}/@var{rev}/@var{expansion} 1681@end example 1682 1683@noindent 1684where @var{expansion} should be ignored, to allow for 1685future expansion. 1686 1687@cindex Baserev.tmp file, in CVS directory 1688@cindex CVS/Baserev.tmp file 1689@item Baserev.tmp 1690This file is to @file{Baserev} as @file{Entries.Backup} 1691is to @file{Entries}. That is, to write @file{Baserev}, 1692first write the new contents to @file{Baserev.tmp} and 1693then (atomically where possible), rename it to 1694@file{Baserev}. 1695 1696@cindex Template file, in CVS directory 1697@cindex CVS/Template file 1698@item Template 1699This file contains the template specified by the 1700@file{rcsinfo} file (@pxref{rcsinfo}). It is only used 1701by the client; the non-client/server @sc{cvs} consults 1702@file{rcsinfo} directly. 1703@end table 1704 1705@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1706@node Intro administrative files 1707@section The administrative files 1708@cindex Administrative files (intro) 1709@cindex Modules file 1710@cindex CVSROOT, module name 1711@cindex Defining modules (intro) 1712 1713@c FIXME: this node should be reorganized into "general 1714@c information about admin files" and put the "editing 1715@c admin files" stuff up front rather than jumping into 1716@c the details of modules right away. Then the 1717@c Administrative files node can go away, the information 1718@c on each admin file distributed to a place appropriate 1719@c to its function, and this node can contain a table 1720@c listing each file and a @ref to its detailed description. 1721 1722The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative 1723files}. @xref{Administrative files}, for a complete description. 1724You can use @sc{cvs} without any of these files, but 1725some commands work better when at least the 1726@file{modules} file is properly set up. 1727 1728The most important of these files is the @file{modules} 1729file. It defines all modules in the repository. This 1730is a sample @file{modules} file. 1731 1732@c FIXME: The CVSROOT line is a goofy example now that 1733@c mkmodules doesn't exist. 1734@example 1735CVSROOT CVSROOT 1736modules CVSROOT modules 1737cvs gnu/cvs 1738rcs gnu/rcs 1739diff gnu/diff 1740tc yoyodyne/tc 1741@end example 1742 1743The @file{modules} file is line oriented. In its 1744simplest form each line contains the name of the 1745module, whitespace, and the directory where the module 1746resides. The directory is a path relative to 1747@code{$CVSROOT}. The last four lines in the example 1748above are examples of such lines. 1749 1750@c FIXME: might want to introduce the concept of options in modules file 1751@c (the old example which was here, -i mkmodules, is obsolete). 1752 1753The line that defines the module called @samp{modules} 1754uses features that are not explained here. 1755@xref{modules}, for a full explanation of all the 1756available features. 1757 1758@c FIXME: subsection without node is bogus 1759@subsection Editing administrative files 1760@cindex Editing administrative files 1761@cindex Administrative files, editing them 1762 1763You edit the administrative files in the same way that you would edit 1764any other module. Use @samp{cvs checkout CVSROOT} to get a working 1765copy, edit it, and commit your changes in the normal way. 1766 1767It is possible to commit an erroneous administrative 1768file. You can often fix the error and check in a new 1769revision, but sometimes a particularly bad error in the 1770administrative file makes it impossible to commit new 1771revisions. 1772@c @xref{Bad administrative files} for a hint 1773@c about how to solve such situations. 1774@c -- administrative file checking-- 1775 1776@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1777@node Multiple repositories 1778@section Multiple repositories 1779@cindex Multiple repositories 1780@cindex Repositories, multiple 1781@cindex Many repositories 1782@cindex Parallel repositories 1783@cindex Disjoint repositories 1784@cindex CVSROOT, multiple repositories 1785 1786In some situations it is a good idea to have more than 1787one repository, for instance if you have two 1788development groups that work on separate projects 1789without sharing any code. All you have to do to have 1790several repositories is to specify the appropriate 1791repository, using the @code{CVSROOT} environment 1792variable, the @samp{-d} option to @sc{cvs}, or (once 1793you have checked out a working directory) by simply 1794allowing @sc{cvs} to use the repository that was used 1795to check out the working directory 1796(@pxref{Specifying a repository}). 1797 1798The big advantage of having multiple repositories is 1799that they can reside on different servers. With @sc{cvs} 1800version 1.10, a single command cannot recurse into 1801directories from different repositories. With development 1802versions of @sc{cvs}, you can check out code from multiple 1803servers into your working directory. @sc{cvs} will 1804recurse and handle all the details of making 1805connections to as many server machines as necessary to 1806perform the requested command. Here is an example of 1807how to set up a working directory: 1808 1809@example 1810cvs -d server1:/cvs co dir1 1811cd dir1 1812cvs -d server2:/root co sdir 1813cvs update 1814@end example 1815 1816The @code{cvs co} commands set up the working 1817directory, and then the @code{cvs update} command will 1818contact server2, to update the dir1/sdir subdirectory, 1819and server1, to update everything else. 1820 1821@c FIXME: Does the FAQ have more about this? I have a 1822@c dim recollection, but I'm too lazy to check right now. 1823 1824@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1825@node Creating a repository 1826@section Creating a repository 1827 1828@cindex Repository, setting up 1829@cindex Creating a repository 1830@cindex Setting up a repository 1831 1832To set up a @sc{cvs} repository, first choose the 1833machine and disk on which you want to store the 1834revision history of the source files. CPU and memory 1835requirements are modest, so most machines should be 1836adequate. For details see @ref{Server requirements}. 1837@c Possible that we should be providing a quick rule of 1838@c thumb, like the 32M memory for the server. That 1839@c might increase the number of people who are happy 1840@c with the answer, without following the xref. 1841 1842To estimate disk space 1843requirements, if you are importing RCS files from 1844another system, the size of those files is the 1845approximate initial size of your repository, or if you 1846are starting without any version history, a rule of 1847thumb is to allow for the server approximately three 1848times the size of the code to be under @sc{cvs} for the 1849repository (you will eventually outgrow this, but not 1850for a while). On the machines on which the developers 1851will be working, you'll want disk space for 1852approximately one working directory for each developer 1853(either the entire tree or a portion of it, depending 1854on what each developer uses). 1855 1856The repository should be accessible 1857(directly or via a networked file system) from all 1858machines which want to use @sc{cvs} in server or local 1859mode; the client machines need not have any access to 1860it other than via the @sc{cvs} protocol. It is not 1861possible to use @sc{cvs} to read from a repository 1862which one only has read access to; @sc{cvs} needs to be 1863able to create lock files (@pxref{Concurrency}). 1864 1865@cindex init (subcommand) 1866To create a repository, run the @code{cvs init} 1867command. It will set up an empty repository in the 1868@sc{cvs} root specified in the usual way 1869(@pxref{Repository}). For example, 1870 1871@example 1872cvs -d /usr/local/cvsroot init 1873@end example 1874 1875@code{cvs init} is careful to never overwrite any 1876existing files in the repository, so no harm is done if 1877you run @code{cvs init} on an already set-up 1878repository. 1879 1880@code{cvs init} will enable history logging; if you 1881don't want that, remove the history file after running 1882@code{cvs init}. @xref{history file}. 1883 1884@node Backing up 1885@section Backing up a repository 1886@cindex Repository, backing up 1887@cindex Backing up, repository 1888 1889There is nothing particularly magical about the files 1890in the repository; for the most part it is possible to 1891back them up just like any other files. However, there 1892are a few issues to consider. 1893 1894@cindex Locks, cvs, and backups 1895@cindex #cvs.rfl, and backups 1896The first is that to be paranoid, one should either not 1897use @sc{cvs} during the backup, or have the backup 1898program lock @sc{cvs} while doing the backup. To not 1899use @sc{cvs}, you might forbid logins to machines which 1900can access the repository, turn off your @sc{cvs} 1901server, or similar mechanisms. The details would 1902depend on your operating system and how you have 1903@sc{cvs} set up. To lock @sc{cvs}, you would create 1904@file{#cvs.rfl} locks in each repository directory. 1905See @ref{Concurrency}, for more on @sc{cvs} locks. 1906Having said all this, if you just back up without any 1907of these precautions, the results are unlikely to be 1908particularly dire. Restoring from backup, the 1909repository might be in an inconsistent state, but this 1910would not be particularly hard to fix manually. 1911 1912When you restore a repository from backup, assuming 1913that changes in the repository were made after the time 1914of the backup, working directories which were not 1915affected by the failure may refer to revisions which no 1916longer exist in the repository. Trying to run @sc{cvs} 1917in such directories will typically produce an error 1918message. One way to get those changes back into the 1919repository is as follows: 1920 1921@itemize @bullet 1922@item 1923Get a new working directory. 1924 1925@item 1926Copy the files from the working directory from before 1927the failure over to the new working directory (do not 1928copy the contents of the @file{CVS} directories, of 1929course). 1930 1931@item 1932Working in the new working directory, use commands such 1933as @code{cvs update} and @code{cvs diff} to figure out 1934what has changed, and then when you are ready, commit 1935the changes into the repository. 1936@end itemize 1937 1938@node Moving a repository 1939@section Moving a repository 1940@cindex Repository, moving 1941@cindex Moving a repository 1942@cindex Copying a repository 1943 1944Just as backing up the files in the repository is 1945pretty much like backing up any other files, if you 1946need to move a repository from one place to another it 1947is also pretty much like just moving any other 1948collection of files. 1949 1950The main thing to consider is that working directories 1951point to the repository. The simplest way to deal with 1952a moved repository is to just get a fresh working 1953directory after the move. Of course, you'll want to 1954make sure that the old working directory had been 1955checked in before the move, or you figured out some 1956other way to make sure that you don't lose any 1957changes. If you really do want to reuse the existing 1958working directory, it should be possible with manual 1959surgery on the @file{CVS/Repository} files. You can 1960see @ref{Working directory storage}, for information on 1961the @file{CVS/Repository} and @file{CVS/Root} files, but 1962unless you are sure you want to bother, it probably 1963isn't worth it. 1964@c FIXME: Surgery on CVS/Repository should be avoided 1965@c by making RELATIVE_REPOS the default. 1966@c FIXME-maybe: might want some documented way to 1967@c change the CVS/Root files in some particular tree. 1968@c But then again, I don't know, maybe just having 1969@c people do this in perl/shell/&c isn't so bad... 1970 1971@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1972@node Remote repositories 1973@section Remote repositories 1974@cindex Repositories, remote 1975@cindex Remote repositories 1976@cindex Client/Server Operation 1977@cindex Server, CVS 1978@cindex Remote repositories, port specification 1979@cindex Repositories, remote, port specification 1980@cindex Client/Server Operation, port specification 1981@cindex pserver (client/server connection method), port specification 1982@cindex kserver (client/server connection method), port specification 1983@cindex gserver (client/server connection method), port specification 1984@cindex port, specifying for remote repositories 1985 1986 Your working copy of the sources can be on a 1987different machine than the repository. Using @sc{cvs} 1988in this manner is known as @dfn{client/server} 1989operation. You run @sc{cvs} on a machine which can 1990mount your working directory, known as the 1991@dfn{client}, and tell it to communicate to a machine 1992which can mount the repository, known as the 1993@dfn{server}. Generally, using a remote 1994repository is just like using a local one, except that 1995the format of the repository name is: 1996 1997@example 1998[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 1999@end example 2000 2001Specifying a password in the repository name is not recommended during 2002checkout, since this will cause @sc{cvs} to store a cleartext copy of the 2003password in each created directory. @code{cvs login} first instead 2004(@pxref{Password authentication client}). 2005 2006The details of exactly what needs to be set up depend 2007on how you are connecting to the server. 2008 2009If @var{method} is not specified, and the repository 2010name contains @samp{:}, then the default is @code{ext} 2011or @code{server}, depending on your platform; both are 2012described in @ref{Connecting via rsh}. 2013@c Should we try to explain which platforms are which? 2014@c Platforms like unix and VMS, which only allow 2015@c privileged programs to bind to sockets <1024 lose on 2016@c :server: 2017@c Platforms like Mac and VMS, whose rsh program is 2018@c unusable or nonexistent, lose on :ext: 2019@c Platforms like OS/2 and NT probably could plausibly 2020@c default either way (modulo -b troubles). 2021 2022@c FIXME: We need to have a better way of explaining 2023@c what method to use. This presentation totally 2024@c obscures the fact that :ext: and CVS_RSH is the way to 2025@c use SSH, for example. Plus it incorrectly implies 2026@c that you need an @code{rsh} binary on the client to use 2027@c :server:. 2028@c Also note that rsh not pserver is the right choice if you want 2029@c users to be able to create their own repositories 2030@c (because of the --allow-root related issues). 2031@menu 2032* Server requirements:: Memory and other resources for servers 2033* Connecting via rsh:: Using the @code{rsh} program to connect 2034* Password authenticated:: Direct connections using passwords 2035* GSSAPI authenticated:: Direct connections using GSSAPI 2036* Kerberos authenticated:: Direct connections with kerberos 2037* Connecting via fork:: Using a forked @code{cvs server} to connect 2038@end menu 2039 2040@node Server requirements 2041@subsection Server requirements 2042 2043The quick answer to what sort of machine is suitable as 2044a server is that requirements are modest---a server 2045with 32M of memory or even less can handle a fairly 2046large source tree with a fair amount of activity. 2047@c Say something about CPU speed too? I'm even less sure 2048@c what to say on that subject... 2049 2050The real answer, of course, is more complicated. 2051Estimating the known areas of large memory consumption 2052should be sufficient to estimate memory requirements. 2053There are two such areas documented here; other memory 2054consumption should be small by comparison (if you find 2055that is not the case, let us know, as described in 2056@ref{BUGS}, so we can update this documentation). 2057 2058The first area of big memory consumption is large 2059checkouts, when using the @sc{cvs} server. The server 2060consists of two processes for each client that it is 2061serving. Memory consumption on the child process 2062should remain fairly small. Memory consumption on the 2063parent process, particularly if the network connection 2064to the client is slow, can be expected to grow to 2065slightly more than the size of the sources in a single 2066directory, or two megabytes, whichever is larger. 2067@c "two megabytes" of course is SERVER_HI_WATER. But 2068@c we don't mention that here because we are 2069@c documenting the default configuration of CVS. If it 2070@c is a "standard" thing to change that value, it 2071@c should be some kind of run-time configuration. 2072@c 2073@c See cvsclient.texi for more on the design decision 2074@c to not have locks in place while waiting for the 2075@c client, which is what results in memory consumption 2076@c as high as this. 2077 2078Multiplying the size of each @sc{cvs} server by the 2079number of servers which you expect to have active at 2080one time should give an idea of memory requirements for 2081the server. For the most part, the memory consumed by 2082the parent process probably can be swap space rather 2083than physical memory. 2084@c Has anyone verified that notion about swap space? 2085@c I say it based pretty much on guessing that the 2086@c ->text of the struct buffer_data only gets accessed 2087@c in a first in, first out fashion, but I haven't 2088@c looked very closely. 2089 2090@c What about disk usage in /tmp on the server? I think that 2091@c it can be substantial, but I haven't looked at this 2092@c again and tried to figure it out ("cvs import" is 2093@c probably the worst case...). 2094 2095The second area of large memory consumption is 2096@code{diff}, when checking in large files. This is 2097required even for binary files. The rule of thumb is 2098to allow about ten times the size of the largest file 2099you will want to check in, although five times may be 2100adequate. For example, if you want to check in a file 2101which is 10 megabytes, you should have 100 megabytes of 2102memory on the machine doing the checkin (the server 2103machine for client/server, or the machine running 2104@sc{cvs} for non-client/server). This can be swap 2105space rather than physical memory. Because the memory 2106is only required briefly, there is no particular need 2107to allow memory for more than one such checkin at a 2108time. 2109@c The 5-10 times rule of thumb is from Paul Eggert for 2110@c GNU diff. I don't think it is in the GNU diff 2111@c manual or anyplace like that. 2112@c 2113@c Probably we could be saying more about 2114@c non-client/server CVS. 2115@c I would guess for non-client/server CVS in an NFS 2116@c environment the biggest issues are the network and 2117@c the NFS server. 2118 2119Resource consumption for the client is even more 2120modest---any machine with enough capacity to run the 2121operating system in question should have little 2122trouble. 2123@c Is that true? I think the client still wants to 2124@c (bogusly) store entire files in memory at times. 2125 2126For information on disk space requirements, see 2127@ref{Creating a repository}. 2128 2129@node Connecting via rsh 2130@subsection Connecting with rsh 2131 2132@cindex rsh 2133@sc{cvs} uses the @samp{rsh} protocol to perform these 2134operations, so the remote user host needs to have a 2135@file{.rhosts} file which grants access to the local 2136user. Note that the program that @sc{cvs} uses for this 2137purpose may be specified using the @file{--with-rsh} 2138flag to configure. 2139 2140For example, suppose you are the user @samp{mozart} on 2141the local machine @samp{toe.example.com}, and the 2142server machine is @samp{faun.example.org}. On 2143faun, put the following line into the file 2144@file{.rhosts} in @samp{bach}'s home directory: 2145 2146@example 2147toe.example.com mozart 2148@end example 2149 2150@noindent 2151Then test that @samp{rsh} is working with 2152 2153@example 2154rsh -l bach faun.example.org 'echo $PATH' 2155@end example 2156 2157@cindex CVS_SERVER, environment variable 2158Next you have to make sure that @code{rsh} will be able 2159to find the server. Make sure that the path which 2160@code{rsh} printed in the above example includes the 2161directory containing a program named @code{cvs} which 2162is the server. You need to set the path in 2163@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 2164or @file{.profile}. Alternately, you can set the 2165environment variable @code{CVS_SERVER} on the client 2166machine to the filename of the server you want to use, 2167for example @file{/usr/local/bin/cvs-1.6}. 2168@c FIXME: there should be a way to specify the 2169@c program in CVSROOT, not CVS_SERVER, so that one can use 2170@c different ones for different roots. e.g. ":server;cvs=cvs-1.6:" 2171@c instead of ":server:". 2172 2173There is no need to edit @file{inetd.conf} or start a 2174@sc{cvs} server daemon. 2175 2176@cindex :server:, setting up 2177@cindex :ext:, setting up 2178@cindex Kerberos, using kerberized rsh 2179@cindex SSH (rsh replacement) 2180@cindex rsh replacements (Kerberized, SSH, &c) 2181There are two access methods that you use in @code{CVSROOT} 2182for rsh. @code{:server:} specifies an internal rsh 2183client, which is supported only by some @sc{cvs} ports. 2184@code{:ext:} specifies an external rsh program. By 2185default this is @code{rsh} (unless otherwise specified 2186by the @file{--with-rsh} flag to configure) but you may set the 2187@code{CVS_RSH} environment variable to invoke another 2188program which can access the remote server (for 2189example, @code{remsh} on HP-UX 9 because @code{rsh} is 2190something different). It must be a program which can 2191transmit data to and from the server without modifying 2192it; for example the Windows NT @code{rsh} is not 2193suitable since it by default translates between CRLF 2194and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 2195to @code{rsh} to get around this, but since this could 2196potentially cause problems for programs other than the 2197standard @code{rsh}, it may change in the future. If 2198you set @code{CVS_RSH} to @code{SSH} or some other rsh 2199replacement, the instructions in the rest of this 2200section concerning @file{.rhosts} and so on are likely 2201to be inapplicable; consult the documentation for your rsh 2202replacement. 2203@c FIXME: there should be a way to specify the 2204@c program in CVSROOT, not CVS_RSH, so that one can use 2205@c different ones for different roots. e.g. ":ext;rsh=remsh:" 2206@c instead of ":ext:". 2207@c See also the comment in src/client.c for rationale 2208@c concerning "rsh" being the default and never 2209@c "remsh". 2210 2211Continuing our example, supposing you want to access 2212the module @file{foo} in the repository 2213@file{/usr/local/cvsroot/}, on machine 2214@file{faun.example.org}, you are ready to go: 2215 2216@example 2217cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2218@end example 2219 2220@noindent 2221(The @file{bach@@} can be omitted if the username is 2222the same on both the local and remote hosts.) 2223 2224@c Should we mention "rsh host echo hi" and "rsh host 2225@c cat" (the latter followed by typing text and ^D) 2226@c as troubleshooting techniques? Probably yes 2227@c (people tend to have trouble setting this up), 2228@c but this kind of thing can be hard to spell out. 2229 2230@node Password authenticated 2231@subsection Direct connection with password authentication 2232 2233The @sc{cvs} client can also connect to the server 2234using a password protocol. This is particularly useful 2235if using @code{rsh} is not feasible (for example, 2236the server is behind a firewall), and Kerberos also is 2237not available. 2238 2239 To use this method, it is necessary to make 2240some adjustments on both the server and client sides. 2241 2242@menu 2243* Password authentication server:: Setting up the server 2244* Password authentication client:: Using the client 2245* Password authentication security:: What this method does and does not do 2246@end menu 2247 2248@node Password authentication server 2249@subsubsection Setting up the server for password authentication 2250 2251First of all, you probably want to tighten the 2252permissions on the @file{$CVSROOT} and 2253@file{$CVSROOT/CVSROOT} directories. See @ref{Password 2254authentication security}, for more details. 2255 2256@cindex pserver (subcommand) 2257@cindex Remote repositories, port specification 2258@cindex Repositories, remote, port specification 2259@cindex Client/Server Operation, port specification 2260@cindex pserver (client/server connection method), port specification 2261@cindex kserver (client/server connection method), port specification 2262@cindex gserver (client/server connection method), port specification 2263@cindex port, specifying for remote repositories 2264@cindex Password server, setting up 2265@cindex Authenticating server, setting up 2266@cindex inetd, configuring for pserver 2267@cindex xinetd, configuring for pserver 2268@c FIXME: this isn't quite right regarding port 2269@c numbers; CVS looks up "cvspserver" in 2270@c /etc/services (on unix, but what about non-unix?). 2271On the server side, the file @file{/etc/inetd.conf} 2272needs to be edited so @code{inetd} knows to run the 2273command @code{cvs pserver} when it receives a 2274connection on the right port. By default, the port 2275number is 2401; it would be different if your client 2276were compiled with @code{CVS_AUTH_PORT} defined to 2277something else, though. This can also be specified in the CVSROOT variable 2278(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 2279environment variable (@pxref{Environment variables}). 2280 2281 If your @code{inetd} allows raw port numbers in 2282@file{/etc/inetd.conf}, then the following (all on a 2283single line in @file{inetd.conf}) should be sufficient: 2284 2285@example 22862401 stream tcp nowait root /usr/local/bin/cvs 2287cvs -f --allow-root=/usr/cvsroot pserver 2288@end example 2289 2290@noindent 2291(You could also use the 2292@samp{-T} option to specify a temporary directory.) 2293 2294The @samp{--allow-root} option specifies the allowable 2295@sc{cvsroot} directory. Clients which attempt to use a 2296different @sc{cvsroot} directory will not be allowed to 2297connect. If there is more than one @sc{cvsroot} 2298directory which you want to allow, repeat the option. 2299(Unfortunately, many versions of @code{inetd} have very small 2300limits on the number of arguments and/or the total length 2301of the command. The usual solution to this problem is 2302to have @code{inetd} run a shell script which then invokes 2303@sc{cvs} with the necessary arguments.) 2304 2305 If your @code{inetd} wants a symbolic service 2306name instead of a raw port number, then put this in 2307@file{/etc/services}: 2308 2309@example 2310cvspserver 2401/tcp 2311@end example 2312 2313@noindent 2314and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 2315 2316If your system uses @code{xinetd} instead of @code{inetd}, 2317the procedure is slightly different. 2318Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2319 2320@example 2321service cvspserver 2322@{ 2323 port = 2401 2324 socket_type = stream 2325 protocol = tcp 2326 wait = no 2327 user = root 2328 passenv = PATH 2329 server = /usr/local/bin/cvs 2330 server_args = -f --allow-root=/usr/cvsroot pserver 2331@} 2332@end example 2333 2334@noindent 2335(If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2336the @code{port} line.) 2337 2338 Once the above is taken care of, restart your 2339@code{inetd}, or do whatever is necessary to force it 2340to reread its initialization files. 2341 2342If you are having trouble setting this up, see 2343@ref{Connection}. 2344 2345@cindex CVS passwd file 2346@cindex passwd (admin file) 2347Because the client stores and transmits passwords in 2348cleartext (almost---see @ref{Password authentication 2349security}, for details), a separate @sc{cvs} password 2350file is generally used, so people don't compromise 2351their regular passwords when they access the 2352repository. This file is 2353@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 2354administrative files}). It uses a colon-separated 2355format, similar to @file{/etc/passwd} on Unix systems, 2356except that it has fewer fields: @sc{cvs} username, 2357optional password, and an optional system username for 2358@sc{cvs} to run as if authentication succeeds. Here is 2359an example @file{passwd} file with five entries: 2360 2361@example 2362anonymous: 2363bach:ULtgRLXo7NRxs 2364spwang:1sOp854gDF3DY 2365melissa:tGX1fS8sun6rY:pubcvs 2366qproj:XR4EZcEs0szik:pubcvs 2367@end example 2368 2369@noindent 2370(The passwords are encrypted according to the standard 2371Unix @code{crypt()} function, so it is possible to 2372paste in passwords directly from regular Unix 2373@file{/etc/passwd} files.) 2374 2375The first line in the example will grant access to any 2376@sc{cvs} client attempting to authenticate as user 2377@code{anonymous}, no matter what password they use, 2378including an empty password. (This is typical for 2379sites granting anonymous read-only access; for 2380information on how to do the "read-only" part, see 2381@ref{Read-only access}.) 2382 2383The second and third lines will grant access to 2384@code{bach} and @code{spwang} if they supply their 2385respective plaintext passwords. 2386 2387@cindex User aliases 2388The fourth line will grant access to @code{melissa}, if 2389she supplies the correct password, but her @sc{cvs} 2390operations will actually run on the server side under 2391the system user @code{pubcvs}. Thus, there need not be 2392any system user named @code{melissa}, but there 2393@emph{must} be one named @code{pubcvs}. 2394 2395The fifth line shows that system user identities can be 2396shared: any client who successfully authenticates as 2397@code{qproj} will actually run as @code{pubcvs}, just 2398as @code{melissa} does. That way you could create a 2399single, shared system user for each project in your 2400repository, and give each developer their own line in 2401the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 2402username on each line would be different, but the 2403system username would be the same. The reason to have 2404different @sc{cvs} usernames is that @sc{cvs} will log their 2405actions under those names: when @code{melissa} commits 2406a change to a project, the checkin is recorded in the 2407project's history under the name @code{melissa}, not 2408@code{pubcvs}. And the reason to have them share a 2409system username is so that you can arrange permissions 2410in the relevant area of the repository such that only 2411that account has write-permission there. 2412 2413If the system-user field is present, all 2414password-authenticated @sc{cvs} commands run as that 2415user; if no system user is specified, @sc{cvs} simply 2416takes the @sc{cvs} username as the system username and 2417runs commands as that user. In either case, if there 2418is no such user on the system, then the @sc{cvs} 2419operation will fail (regardless of whether the client 2420supplied a valid password). 2421 2422The password and system-user fields can both be omitted 2423(and if the system-user field is omitted, then also 2424omit the colon that would have separated it from the 2425encrypted password). For example, this would be a 2426valid @file{$CVSROOT/CVSROOT/passwd} file: 2427 2428@example 2429anonymous::pubcvs 2430fish:rKa5jzULzmhOo:kfogel 2431sussman:1sOp854gDF3DY 2432@end example 2433 2434@noindent 2435When the password field is omitted or empty, then the 2436client's authentication attempt will succeed with any 2437password, including the empty string. However, the 2438colon after the @sc{cvs} username is always necessary, 2439even if the password is empty. 2440 2441@sc{cvs} can also fall back to use system authentication. 2442When authenticating a password, the server first checks 2443for the user in the @file{$CVSROOT/CVSROOT/passwd} 2444file. If it finds the user, it will use that entry for 2445authentication as described above. But if it does not 2446find the user, or if the @sc{cvs} @file{passwd} file 2447does not exist, then the server can try to authenticate 2448the username and password using the operating system's 2449user-lookup routines (this "fallback" behavior can be 2450disabled by setting @code{SystemAuth=no} in the 2451@sc{cvs} @file{config} file, @pxref{config}). 2452 2453The default fallback behaviour is to look in 2454@file{/etc/passwd} for this system password unless your 2455system has PAM (Pluggable Authentication Modules) 2456and your @sc{cvs} server executable was configured to 2457use it at compile time (using @code{./configure --enable-pam} - see the 2458INSTALL file for more). In this case, PAM will be consulted instead. 2459This means that @sc{cvs} can be configured to use any password 2460authentication source PAM can be configured to use (possibilities 2461include a simple UNIX password, NIS, LDAP, and others) in its 2462global configuration file (usually @file{/etc/pam.conf} 2463or possibly @file{/etc/pam.d/cvs}). See your PAM documentation 2464for more details on PAM configuration. 2465 2466Note that PAM is an experimental feature in @sc{cvs} and feedback is 2467encouraged. Please send a mail to one of the @sc{cvs} mailing lists 2468(@code{info-cvs@@gnu.org} or @code{bug-cvs@@gnu.org}) if you use the 2469@sc{cvs} PAM support. 2470 2471@strong{WARNING: Using PAM gives the system administrator much more 2472flexibility about how @sc{cvs} users are authenticated but 2473no more security than other methods. See below for more.} 2474 2475CVS needs an "auth" and "account" module in the 2476PAM configuration file. A typical PAM configuration 2477would therefore have the following lines 2478in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 2479system @file{/etc/passwd} authentication: 2480 2481@example 2482cvs auth required pam_unix.so 2483cvs account required pam_unix.so 2484@end example 2485 2486The the equivalent @file{/etc/pam.d/cvs} would contain 2487 2488@example 2489auth required pam_unix.so 2490account required pam_unix.so 2491@end example 2492 2493Some systems require a full path to the module so that 2494@file{pam_unix.so} (Linux) would become something like 2495@file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris). 2496See the @file{contrib/pam} subdirectory of the @sc{cvs} 2497source distribution for further example configurations. 2498 2499The PAM service name given above as "cvs" is just 2500the service name in the default configuration amd can be 2501set using 2502@code{./configure --with-hardcoded-pam-service-name=<pam-service-name>} 2503before compiling. @sc{cvs} can also be configured to use whatever 2504name it is invoked as as its PAM service name using 2505@code{./configure --without-hardcoded-pam-service-name}, but this 2506feature should not be used if you may not have control of the name 2507@sc{cvs} will be invoked as. 2508 2509Be aware, also, that falling back to system 2510authentication might be a security risk: @sc{cvs} 2511operations would then be authenticated with that user's 2512regular login password, and the password flies across 2513the network in plaintext. See @ref{Password 2514authentication security} for more on this. 2515This may be more of a problem with PAM authentication 2516because it is likely that the source of the system 2517password is some central authentication service like 2518LDAP which is also used to authenticate other services. 2519 2520On the other hand, PAM makes it very easy to change your password 2521regularly. If they are given the option of a one-password system for 2522all of their activities, users are often more willing to change their 2523password on a regular basis. 2524 2525In the non-PAM configuration where the password is stored in the 2526@file{CVSROOT/passwd} file, it is difficult to change passwords on a 2527regular basis since only administrative users (or in some cases 2528processes that act as an administrative user) are typicaly given 2529access to modify this file. Either there needs to be some 2530hand-crafted web page or set-uid program to update the file, or the 2531update needs to be done by submitting a request to an administrator to 2532perform the duty by hand. In the first case, having to remember to 2533update a separate password on a periodic basis can be difficult. In 2534the second case, the manual nature of the change will typically mean 2535that the password will not be changed unless it is absolutely 2536necessary. 2537 2538Note that PAM administrators should probably avoid configuring 2539one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If 2540OTPs are desired, the administrator may wish to encourage the use of 2541one of the other Client/Server access methods. See the section on 2542@pxref{Remote repositories} for a list of other methods. 2543 2544Right now, the only way to put a password in the 2545@sc{cvs} @file{passwd} file is to paste it there from 2546somewhere else. Someday, there may be a @code{cvs 2547passwd} command. 2548 2549Unlike many of the files in @file{$CVSROOT/CVSROOT}, it 2550is normal to edit the @file{passwd} file in-place, 2551rather than via @sc{cvs}. This is because of the 2552possible security risks of having the @file{passwd} 2553file checked out to people's working copies. If you do 2554want to include the @file{passwd} file in checkouts of 2555@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 2556 2557@c We might also suggest using the @code{htpasswd} command 2558@c from freely available web servers as well, but that 2559@c would open up a can of worms in that the users next 2560@c questions are likely to be "where do I get it?" and 2561@c "how do I use it?" 2562@c Also note that htpasswd, at least the version I had, 2563@c likes to clobber the third field. 2564 2565@node Password authentication client 2566@subsubsection Using the client with password authentication 2567@cindex Login (subcommand) 2568@cindex Password client, using 2569@cindex Authenticated client, using 2570@cindex :pserver:, setting up 2571To run a @sc{cvs} command on a remote repository via 2572the password-authenticating server, one specifies the 2573@code{pserver} protocol, optional username, repository host, an 2574optional port number, and path to the repository. For example: 2575 2576@example 2577cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 2578@end example 2579 2580@noindent 2581or 2582 2583@example 2584CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 2585cvs checkout someproj 2586@end example 2587 2588However, unless you're connecting to a public-access 2589repository (i.e., one where that username doesn't 2590require a password), you'll need to supply a password or @dfn{log in} first. 2591Logging in verifies your password with the repository and stores it in a file. 2592It's done with the @code{login} command, which will 2593prompt you interactively for the password if you didn't supply one as part of 2594@var{$CVSROOT}: 2595 2596@example 2597cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 2598CVS password: 2599@end example 2600 2601@noindent 2602or 2603 2604@example 2605cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 2606@end example 2607 2608After you enter the password, @sc{cvs} verifies it with 2609the server. If the verification succeeds, then that 2610combination of username, host, repository, and password 2611is permanently recorded, so future transactions with 2612that repository won't require you to run @code{cvs 2613login}. (If verification fails, @sc{cvs} will exit 2614complaining that the password was incorrect, and 2615nothing will be recorded.) 2616 2617The records are stored, by default, in the file 2618@file{$HOME/.cvspass}. That file's format is 2619human-readable, and to a degree human-editable, but 2620note that the passwords are not stored in 2621cleartext---they are trivially encoded to protect them 2622from "innocent" compromise (i.e., inadvertent viewing 2623by a system administrator or other non-malicious 2624person). 2625 2626@cindex CVS_PASSFILE, environment variable 2627You can change the default location of this file by 2628setting the @code{CVS_PASSFILE} environment variable. 2629If you use this variable, make sure you set it 2630@emph{before} @code{cvs login} is run. If you were to 2631set it after running @code{cvs login}, then later 2632@sc{cvs} commands would be unable to look up the 2633password for transmission to the server. 2634 2635Once you have logged in, all @sc{cvs} commands using 2636that remote repository and username will authenticate 2637with the stored password. So, for example 2638 2639@example 2640cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2641@end example 2642 2643@noindent 2644should just work (unless the password changes on the 2645server side, in which case you'll have to re-run 2646@code{cvs login}). 2647 2648Note that if the @samp{:pserver:} were not present in 2649the repository specification, @sc{cvs} would assume it 2650should use @code{rsh} to connect with the server 2651instead (@pxref{Connecting via rsh}). 2652 2653Of course, once you have a working copy checked out and 2654are running @sc{cvs} commands from within it, there is 2655no longer any need to specify the repository 2656explicitly, because @sc{cvs} can deduce the repository 2657from the working copy's @file{CVS} subdirectory. 2658 2659@c FIXME: seems to me this needs somewhat more 2660@c explanation. 2661@cindex Logout (subcommand) 2662The password for a given remote repository can be 2663removed from the @code{CVS_PASSFILE} by using the 2664@code{cvs logout} command. 2665 2666@node Password authentication security 2667@subsubsection Security considerations with password authentication 2668 2669@cindex Security, of pserver 2670The passwords are stored on the client side in a 2671trivial encoding of the cleartext, and transmitted in 2672the same encoding. The encoding is done only to 2673prevent inadvertent password compromises (i.e., a 2674system administrator accidentally looking at the file), 2675and will not prevent even a naive attacker from gaining 2676the password. 2677 2678@c FIXME: The bit about "access to the repository 2679@c implies general access to the system is *not* specific 2680@c to pserver; it applies to kerberos and SSH and 2681@c everything else too. Should reorganize the 2682@c documentation to make this clear. 2683The separate @sc{cvs} password file (@pxref{Password 2684authentication server}) allows people 2685to use a different password for repository access than 2686for login access. On the other hand, once a user has 2687non-read-only 2688access to the repository, she can execute programs on 2689the server system through a variety of means. Thus, repository 2690access implies fairly broad system access as well. It 2691might be possible to modify @sc{cvs} to prevent that, 2692but no one has done so as of this writing. 2693@c OpenBSD uses chroot() and copies the repository to 2694@c provide anonymous read-only access (for details see 2695@c http://www.openbsd.org/anoncvs.shar). While this 2696@c closes the most obvious holes, I'm not sure it 2697@c closes enough holes to recommend it (plus it is 2698@c *very* easy to accidentally screw up a setup of this 2699@c type). 2700 2701Note that because the @file{$CVSROOT/CVSROOT} directory 2702contains @file{passwd} and other files which are used 2703to check security, you must control the permissions on 2704this directory as tightly as the permissions on 2705@file{/etc}. The same applies to the @file{$CVSROOT} 2706directory itself and any directory 2707above it in the tree. Anyone who has write access to 2708such a directory will have the ability to become any 2709user on the system. Note that these permissions are 2710typically tighter than you would use if you are not 2711using pserver. 2712@c TODO: Would be really nice to document/implement a 2713@c scheme where the CVS server can run as some non-root 2714@c user, e.g. "cvs". CVSROOT/passwd would contain a 2715@c bunch of entries of the form foo:xxx:cvs (or the "cvs" 2716@c would be implicit). This would greatly reduce 2717@c security risks such as those hinted at in the 2718@c previous paragraph. I think minor changes to CVS 2719@c might be required but mostly this would just need 2720@c someone who wants to play with it, document it, &c. 2721 2722In summary, anyone who gets the password gets 2723repository access (which may imply some measure of general system 2724access as well). The password is available to anyone 2725who can sniff network packets or read a protected 2726(i.e., user read-only) file. If you want real 2727security, get Kerberos. 2728 2729@node GSSAPI authenticated 2730@subsection Direct connection with GSSAPI 2731 2732@cindex GSSAPI 2733@cindex Security, GSSAPI 2734@cindex :gserver:, setting up 2735@cindex Kerberos, using :gserver: 2736GSSAPI is a generic interface to network security 2737systems such as Kerberos 5. 2738If you have a working GSSAPI library, you can have 2739@sc{cvs} connect via a direct @sc{tcp} connection, 2740authenticating with GSSAPI. 2741 2742To do this, @sc{cvs} needs to be compiled with GSSAPI 2743support; when configuring @sc{cvs} it tries to detect 2744whether GSSAPI libraries using kerberos version 5 are 2745present. You can also use the @file{--with-gssapi} 2746flag to configure. 2747 2748The connection is authenticated using GSSAPI, but the 2749message stream is @emph{not} authenticated by default. 2750You must use the @code{-a} global option to request 2751stream authentication. 2752 2753The data transmitted is @emph{not} encrypted by 2754default. Encryption support must be compiled into both 2755the client and the server; use the 2756@file{--enable-encrypt} configure option to turn it on. 2757You must then use the @code{-x} global option to 2758request encryption. 2759 2760GSSAPI connections are handled on the server side by 2761the same server which handles the password 2762authentication server; see @ref{Password authentication 2763server}. If you are using a GSSAPI mechanism such as 2764Kerberos which provides for strong authentication, you 2765will probably want to disable the ability to 2766authenticate via cleartext passwords. To do so, create 2767an empty @file{CVSROOT/passwd} password file, and set 2768@code{SystemAuth=no} in the config file 2769(@pxref{config}). 2770 2771The GSSAPI server uses a principal name of 2772cvs/@var{hostname}, where @var{hostname} is the 2773canonical name of the server host. You will have to 2774set this up as required by your GSSAPI mechanism. 2775 2776To connect using GSSAPI, use @samp{:gserver:}. For 2777example, 2778 2779@example 2780cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 2781@end example 2782 2783@node Kerberos authenticated 2784@subsection Direct connection with kerberos 2785 2786@cindex Kerberos, using :kserver: 2787@cindex Security, kerberos 2788@cindex :kserver:, setting up 2789The easiest way to use kerberos is to use the kerberos 2790@code{rsh}, as described in @ref{Connecting via rsh}. 2791The main disadvantage of using rsh is that all the data 2792needs to pass through additional programs, so it may be 2793slower. So if you have kerberos installed you can 2794connect via a direct @sc{tcp} connection, 2795authenticating with kerberos. 2796 2797This section concerns the kerberos network security 2798system, version 4. Kerberos version 5 is supported via 2799the GSSAPI generic network security interface, as 2800described in the previous section. 2801 2802To do this, @sc{cvs} needs to be compiled with kerberos 2803support; when configuring @sc{cvs} it tries to detect 2804whether kerberos is present or you can use the 2805@file{--with-krb4} flag to configure. 2806 2807The data transmitted is @emph{not} encrypted by 2808default. Encryption support must be compiled into both 2809the client and server; use the 2810@file{--enable-encryption} configure option to turn it 2811on. You must then use the @code{-x} global option to 2812request encryption. 2813 2814@cindex CVS_CLIENT_PORT 2815You need to edit @file{inetd.conf} on the server 2816machine to run @code{cvs kserver}. The client uses 2817port 1999 by default; if you want to use another port 2818specify it in the @code{CVSROOT} (@pxref{Remote repositories}) 2819or the @code{CVS_CLIENT_PORT} environment variable 2820(@pxref{Environment variables}) on the client. 2821 2822@cindex kinit 2823When you want to use @sc{cvs}, get a ticket in the 2824usual way (generally @code{kinit}); it must be a ticket 2825which allows you to log into the server machine. Then 2826you are ready to go: 2827 2828@example 2829cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 2830@end example 2831 2832Previous versions of @sc{cvs} would fall back to a 2833connection via rsh; this version will not do so. 2834 2835@node Connecting via fork 2836@subsection Connecting with fork 2837 2838@cindex fork, access method 2839@cindex :fork:, setting up 2840This access method allows you to connect to a 2841repository on your local disk via the remote protocol. 2842In other words it does pretty much the same thing as 2843@code{:local:}, but various quirks, bugs and the like are 2844those of the remote @sc{cvs} rather than the local 2845@sc{cvs}. 2846 2847For day-to-day operations you might prefer either 2848@code{:local:} or @code{:fork:}, depending on your 2849preferences. Of course @code{:fork:} comes in 2850particularly handy in testing or 2851debugging @code{cvs} and the remote protocol. 2852Specifically, we avoid all of the network-related 2853setup/configuration, timeouts, and authentication 2854inherent in the other remote access methods but still 2855create a connection which uses the remote protocol. 2856 2857To connect using the @code{fork} method, use 2858@samp{:fork:} and the pathname to your local 2859repository. For example: 2860 2861@example 2862cvs -d :fork:/usr/local/cvsroot checkout foo 2863@end example 2864 2865@cindex CVS_SERVER, and :fork: 2866As with @code{:ext:}, the server is called @samp{cvs} 2867by default, or the value of the @code{CVS_SERVER} 2868environment variable. 2869 2870@c --------------------------------------------------------------------- 2871@node Read-only access 2872@section Read-only repository access 2873@cindex Read-only repository access 2874@cindex readers (admin file) 2875@cindex writers (admin file) 2876 2877 It is possible to grant read-only repository 2878access to people using the password-authenticated 2879server (@pxref{Password authenticated}). (The 2880other access methods do not have explicit support for 2881read-only users because those methods all assume login 2882access to the repository machine anyway, and therefore 2883the user can do whatever local file permissions allow 2884her to do.) 2885 2886 A user who has read-only access can do only 2887those @sc{cvs} operations which do not modify the 2888repository, except for certain ``administrative'' files 2889(such as lock files and the history file). It may be 2890desirable to use this feature in conjunction with 2891user-aliasing (@pxref{Password authentication server}). 2892 2893Unlike with previous versions of @sc{cvs}, read-only 2894users should be able merely to read the repository, and 2895not to execute programs on the server or otherwise gain 2896unexpected levels of access. Or to be more accurate, 2897the @emph{known} holes have been plugged. Because this 2898feature is new and has not received a comprehensive 2899security audit, you should use whatever level of 2900caution seems warranted given your attitude concerning 2901security. 2902 2903 There are two ways to specify read-only access 2904for a user: by inclusion, and by exclusion. 2905 2906 "Inclusion" means listing that user 2907specifically in the @file{$CVSROOT/CVSROOT/readers} 2908file, which is simply a newline-separated list of 2909users. Here is a sample @file{readers} file: 2910 2911@example 2912melissa 2913splotnik 2914jrandom 2915@end example 2916 2917@noindent 2918 (Don't forget the newline after the last user.) 2919 2920 "Exclusion" means explicitly listing everyone 2921who has @emph{write} access---if the file 2922 2923@example 2924$CVSROOT/CVSROOT/writers 2925@end example 2926 2927@noindent 2928exists, then only 2929those users listed in it have write access, and 2930everyone else has read-only access (of course, even the 2931read-only users still need to be listed in the 2932@sc{cvs} @file{passwd} file). The 2933@file{writers} file has the same format as the 2934@file{readers} file. 2935 2936 Note: if your @sc{cvs} @file{passwd} 2937file maps cvs users onto system users (@pxref{Password 2938authentication server}), make sure you deny or grant 2939read-only access using the @emph{cvs} usernames, not 2940the system usernames. That is, the @file{readers} and 2941@file{writers} files contain cvs usernames, which may 2942or may not be the same as system usernames. 2943 2944 Here is a complete description of the server's 2945behavior in deciding whether to grant read-only or 2946read-write access: 2947 2948 If @file{readers} exists, and this user is 2949listed in it, then she gets read-only access. Or if 2950@file{writers} exists, and this user is NOT listed in 2951it, then she also gets read-only access (this is true 2952even if @file{readers} exists but she is not listed 2953there). Otherwise, she gets full read-write access. 2954 2955 Of course there is a conflict if the user is 2956listed in both files. This is resolved in the more 2957conservative way, it being better to protect the 2958repository too much than too little: such a user gets 2959read-only access. 2960 2961@node Server temporary directory 2962@section Temporary directories for the server 2963@cindex Temporary directories, and server 2964@cindex Server, temporary directories 2965 2966While running, the @sc{cvs} server creates temporary 2967directories. They are named 2968 2969@example 2970cvs-serv@var{pid} 2971@end example 2972 2973@noindent 2974where @var{pid} is the process identification number of 2975the server. 2976They are located in the directory specified by 2977the @samp{-T} global option (@pxref{Global options}), 2978the @code{TMPDIR} environment variable (@pxref{Environment variables}), 2979or, failing that, @file{/tmp}. 2980 2981In most cases the server will remove the temporary 2982directory when it is done, whether it finishes normally 2983or abnormally. However, there are a few cases in which 2984the server does not or cannot remove the temporary 2985directory, for example: 2986 2987@itemize @bullet 2988@item 2989If the server aborts due to an internal server error, 2990it may preserve the directory to aid in debugging 2991 2992@item 2993If the server is killed in a way that it has no way of 2994cleaning up (most notably, @samp{kill -KILL} on unix). 2995 2996@item 2997If the system shuts down without an orderly shutdown, 2998which tells the server to clean up. 2999@end itemize 3000 3001In cases such as this, you will need to manually remove 3002the @file{cvs-serv@var{pid}} directories. As long as 3003there is no server running with process identification 3004number @var{pid}, it is safe to do so. 3005 3006@c --------------------------------------------------------------------- 3007@node Starting a new project 3008@chapter Starting a project with CVS 3009@cindex Starting a project with CVS 3010@cindex Creating a project 3011 3012@comment --moduledb-- 3013Because renaming files and moving them between 3014directories is somewhat inconvenient, the first thing 3015you do when you start a new project should be to think 3016through your file organization. It is not impossible 3017to rename or move files, but it does increase the 3018potential for confusion and @sc{cvs} does have some 3019quirks particularly in the area of renaming 3020directories. @xref{Moving files}. 3021 3022What to do next depends on the situation at hand. 3023 3024@menu 3025* Setting up the files:: Getting the files into the repository 3026* Defining the module:: How to make a module of the files 3027@end menu 3028@c -- File permissions! 3029 3030@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3031@node Setting up the files 3032@section Setting up the files 3033 3034The first step is to create the files inside the repository. This can 3035be done in a couple of different ways. 3036 3037@c -- The contributed scripts 3038@menu 3039* From files:: This method is useful with old projects 3040 where files already exists. 3041* From other version control systems:: Old projects where you want to 3042 preserve history from another system. 3043* From scratch:: Creating a directory tree from scratch. 3044@end menu 3045 3046@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3047@node From files 3048@subsection Creating a directory tree from a number of files 3049@cindex Importing files 3050 3051When you begin using @sc{cvs}, you will probably already have several 3052projects that can be 3053put under @sc{cvs} control. In these cases the easiest way is to use the 3054@code{import} command. An example is probably the easiest way to 3055explain how to use it. If the files you want to install in 3056@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 3057repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 3058 3059@example 3060$ cd @var{wdir} 3061$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 3062@end example 3063 3064Unless you supply a log message with the @samp{-m} 3065flag, @sc{cvs} starts an editor and prompts for a 3066message. The string @samp{yoyo} is a @dfn{vendor tag}, 3067and @samp{start} is a @dfn{release tag}. They may fill 3068no purpose in this context, but since @sc{cvs} requires 3069them they must be present. @xref{Tracking sources}, for 3070more information about them. 3071 3072You can now verify that it worked, and remove your 3073original source directory. 3074@c FIXME: Need to say more about "verify that it 3075@c worked". What should the user look for in the output 3076@c from "diff -r"? 3077 3078@example 3079$ cd .. 3080$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 3081$ diff -r @var{wdir} yoyodyne/@var{rdir} 3082$ rm -r @var{wdir} 3083@end example 3084 3085@noindent 3086Erasing the original sources is a good idea, to make sure that you do 3087not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 3088Of course, it would be wise to make sure that you have 3089a backup of the sources before you remove them. 3090 3091The @code{checkout} command can either take a module 3092name as argument (as it has done in all previous 3093examples) or a path name relative to @code{$CVSROOT}, 3094as it did in the example above. 3095 3096It is a good idea to check that the permissions 3097@sc{cvs} sets on the directories inside @code{$CVSROOT} 3098are reasonable, and that they belong to the proper 3099groups. @xref{File permissions}. 3100 3101If some of the files you want to import are binary, you 3102may want to use the wrappers features to specify which 3103files are binary and which are not. @xref{Wrappers}. 3104 3105@c The node name is too long, but I am having trouble 3106@c thinking of something more concise. 3107@node From other version control systems 3108@subsection Creating Files From Other Version Control Systems 3109@cindex Importing files, from other version control systems 3110 3111If you have a project which you are maintaining with 3112another version control system, such as @sc{rcs}, you 3113may wish to put the files from that project into 3114@sc{cvs}, and preserve the revision history of the 3115files. 3116 3117@table @asis 3118@cindex RCS, importing files from 3119@item From RCS 3120If you have been using @sc{rcs}, find the @sc{rcs} 3121files---usually a file named @file{foo.c} will have its 3122@sc{rcs} file in @file{RCS/foo.c,v} (but it could be 3123other places; consult the @sc{rcs} documentation for 3124details). Then create the appropriate directories in 3125@sc{cvs} if they do not already exist. Then copy the 3126files into the appropriate directories in the @sc{cvs} 3127repository (the name in the repository must be the name 3128of the source file with @samp{,v} added; the files go 3129directly in the appropriate directory of the repository, 3130not in an @file{RCS} subdirectory). This is one of the 3131few times when it is a good idea to access the @sc{cvs} 3132repository directly, rather than using @sc{cvs} 3133commands. Then you are ready to check out a new 3134working directory. 3135@c Someday there probably should be a "cvs import -t 3136@c rcs" or some such. It could even create magic 3137@c branches. It could also do something about the case 3138@c where the RCS file had a (non-magic) "0" branch. 3139 3140The @sc{rcs} file should not be locked when you move it 3141into @sc{cvs}; if it is, @sc{cvs} will have trouble 3142letting you operate on it. 3143@c What is the easiest way to unlock your files if you 3144@c have them locked? Especially if you have a lot of them? 3145@c This is a CVS bug/misfeature; importing RCS files 3146@c should ignore whether they are locked and leave them in 3147@c an unlocked state. Yet another reason for a separate 3148@c "import RCS file" command. 3149 3150@c How many is "many"? Or do they just import RCS files? 3151@item From another version control system 3152Many version control systems have the ability to export 3153@sc{rcs} files in the standard format. If yours does, 3154export the @sc{rcs} files and then follow the above 3155instructions. 3156 3157Failing that, probably your best bet is to write a 3158script that will check out the files one revision at a 3159time using the command line interface to the other 3160system, and then check the revisions into @sc{cvs}. 3161The @file{sccs2rcs} script mentioned below may be a 3162useful example to follow. 3163 3164@cindex SCCS, importing files from 3165@item From SCCS 3166There is a script in the @file{contrib} directory of 3167the @sc{cvs} source distribution called @file{sccs2rcs} 3168which converts @sc{sccs} files to @sc{rcs} files. 3169Note: you must run it on a machine which has both 3170@sc{sccs} and @sc{rcs} installed, and like everything 3171else in contrib it is unsupported (your mileage may 3172vary). 3173 3174@cindex PVCS, importing files from 3175@item From PVCS 3176There is a script in the @file{contrib} directory of 3177the @sc{cvs} source distribution called @file{pvcs_to_rcs} 3178which converts @sc{pvcs} archives to @sc{rcs} files. 3179You must run it on a machine which has both 3180@sc{pvcs} and @sc{rcs} installed, and like everything 3181else in contrib it is unsupported (your mileage may 3182vary). See the comments in the script for details. 3183@end table 3184@c CMZ and/or PATCHY were systems that were used in the 3185@c high energy physics community (especially for 3186@c CERNLIB). CERN has replaced them with CVS, but the 3187@c CAR format seems to live on as a way to submit 3188@c changes. There is a program car2cvs which converts 3189@c but I'm not sure where one gets a copy. 3190@c Not sure it is worth mentioning here, since it would 3191@c appear to affect only one particular community. 3192@c Best page for more information is: 3193@c http://wwwcn1.cern.ch/asd/cvs/index.html 3194@c See also: 3195@c http://ecponion.cern.ch/ecpsa/cernlib.html 3196 3197@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3198@node From scratch 3199@subsection Creating a directory tree from scratch 3200 3201@c Also/instead should be documenting 3202@c $ cvs co -l . 3203@c $ mkdir tc 3204@c $ cvs add tc 3205@c $ cd tc 3206@c $ mkdir man 3207@c $ cvs add man 3208@c etc. 3209@c Using import to create the directories only is 3210@c probably a somewhat confusing concept. 3211For a new project, the easiest thing to do is probably 3212to create an empty directory structure, like this: 3213 3214@example 3215$ mkdir tc 3216$ mkdir tc/man 3217$ mkdir tc/testing 3218@end example 3219 3220After that, you use the @code{import} command to create 3221the corresponding (empty) directory structure inside 3222the repository: 3223 3224@example 3225$ cd tc 3226$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 3227@end example 3228 3229Then, use @code{add} to add files (and new directories) 3230as they appear. 3231 3232Check that the permissions @sc{cvs} sets on the 3233directories inside @code{$CVSROOT} are reasonable. 3234 3235@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3236@node Defining the module 3237@section Defining the module 3238@cindex Defining a module 3239@cindex Editing the modules file 3240@cindex Module, defining 3241@cindex Modules file, changing 3242 3243The next step is to define the module in the 3244@file{modules} file. This is not strictly necessary, 3245but modules can be convenient in grouping together 3246related files and directories. 3247 3248In simple cases these steps are sufficient to define a module. 3249 3250@enumerate 3251@item 3252Get a working copy of the modules file. 3253 3254@example 3255$ cvs checkout CVSROOT/modules 3256$ cd CVSROOT 3257@end example 3258 3259@item 3260Edit the file and insert a line that defines the module. @xref{Intro 3261administrative files}, for an introduction. @xref{modules}, for a full 3262description of the modules file. You can use the 3263following line to define the module @samp{tc}: 3264 3265@example 3266tc yoyodyne/tc 3267@end example 3268 3269@item 3270Commit your changes to the modules file. 3271 3272@example 3273$ cvs commit -m "Added the tc module." modules 3274@end example 3275 3276@item 3277Release the modules module. 3278 3279@example 3280$ cd .. 3281$ cvs release -d CVSROOT 3282@end example 3283@end enumerate 3284 3285@c --------------------------------------------------------------------- 3286@node Revisions 3287@chapter Revisions 3288 3289For many uses of @sc{cvs}, one doesn't need to worry 3290too much about revision numbers; @sc{cvs} assigns 3291numbers such as @code{1.1}, @code{1.2}, and so on, and 3292that is all one needs to know. However, some people 3293prefer to have more knowledge and control concerning 3294how @sc{cvs} assigns revision numbers. 3295 3296If one wants to keep track of a set of revisions 3297involving more than one file, such as which revisions 3298went into a particular release, one uses a @dfn{tag}, 3299which is a symbolic revision which can be assigned to a 3300numeric revision in each file. 3301 3302@menu 3303* Revision numbers:: The meaning of a revision number 3304* Versions revisions releases:: Terminology used in this manual 3305* Assigning revisions:: Assigning revisions 3306* Tags:: Tags--Symbolic revisions 3307* Tagging the working directory:: The cvs tag command 3308* Tagging by date/tag:: The cvs rtag command 3309* Modifying tags:: Adding, renaming, and deleting tags 3310* Tagging add/remove:: Tags with adding and removing files 3311* Sticky tags:: Certain tags are persistent 3312@end menu 3313 3314@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3315@node Revision numbers 3316@section Revision numbers 3317@cindex Revision numbers 3318@cindex Revision tree 3319@cindex Linear development 3320@cindex Number, revision- 3321@cindex Decimal revision number 3322@cindex Branch number 3323@cindex Number, branch 3324 3325Each version of a file has a unique @dfn{revision 3326number}. Revision numbers look like @samp{1.1}, 3327@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 3328A revision number always has an even number of 3329period-separated decimal integers. By default revision 33301.1 is the first revision of a file. Each successive 3331revision is given a new number by increasing the 3332rightmost number by one. The following figure displays 3333a few revisions, with newer revisions to the right. 3334 3335@example 3336 +-----+ +-----+ +-----+ +-----+ +-----+ 3337 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 3338 +-----+ +-----+ +-----+ +-----+ +-----+ 3339@end example 3340 3341It is also possible to end up with numbers containing 3342more than one period, for example @samp{1.3.2.2}. Such 3343revisions represent revisions on branches 3344(@pxref{Branching and merging}); such revision numbers 3345are explained in detail in @ref{Branches and 3346revisions}. 3347 3348@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3349@node Versions revisions releases 3350@section Versions, revisions and releases 3351@cindex Revisions, versions and releases 3352@cindex Versions, revisions and releases 3353@cindex Releases, revisions and versions 3354 3355A file can have several versions, as described above. 3356Likewise, a software product can have several versions. 3357A software product is often given a version number such 3358as @samp{4.1.1}. 3359 3360Versions in the first sense are called @dfn{revisions} 3361in this document, and versions in the second sense are 3362called @dfn{releases}. To avoid confusion, the word 3363@dfn{version} is almost never used in this document. 3364 3365@node Assigning revisions 3366@section Assigning revisions 3367 3368@c We avoid the "major revision" terminology. It seems 3369@c like jargon. Hopefully "first number" is clear enough. 3370@c 3371@c Well, in the context of software release numbers, 3372@c "major" and "minor" release or version numbers are 3373@c documented in at least the GNU Coding Standards, but I'm 3374@c still not sure I find that a valid reason to apply the 3375@c terminology to RCS revision numbers. "First", "Second", 3376@c "subsequent", and so on is almost surely clearer, 3377@c especially to a novice reader. -DRP 3378By default, @sc{cvs} will assign numeric revisions by 3379leaving the first number the same and incrementing the 3380second number. For example, @code{1.1}, @code{1.2}, 3381@code{1.3}, etc. 3382 3383When adding a new file, the second number will always 3384be one and the first number will equal the highest 3385first number of any file in that directory. For 3386example, the current directory contains files whose 3387highest numbered revisions are @code{1.7}, @code{3.1}, 3388and @code{4.12}, then an added file will be given the 3389numeric revision @code{4.1}. 3390 3391@c This is sort of redundant with something we said a 3392@c while ago. Somewhere we need a better way of 3393@c introducing how the first number can be anything 3394@c except "1", perhaps. Also I don't think this 3395@c presentation is clear on why we are discussing releases 3396@c and first numbers of numeric revisions in the same 3397@c breath. 3398Normally there is no reason to care 3399about the revision numbers---it is easier to treat them 3400as internal numbers that @sc{cvs} maintains, and tags 3401provide a better way to distinguish between things like 3402release 1 versus release 2 of your product 3403(@pxref{Tags}). However, if you want to set the 3404numeric revisions, the @samp{-r} option to @code{cvs 3405commit} can do that. The @samp{-r} option implies the 3406@samp{-f} option, in the sense that it causes the 3407files to be committed even if they are not modified. 3408 3409For example, to bring all your files up to 3410revision 3.0 (including those that haven't changed), 3411you might invoke: 3412 3413@example 3414$ cvs commit -r 3.0 3415@end example 3416 3417Note that the number you specify with @samp{-r} must be 3418larger than any existing revision number. That is, if 3419revision 3.0 exists, you cannot @samp{cvs commit 3420-r 1.3}. If you want to maintain several releases in 3421parallel, you need to use a branch (@pxref{Branching and merging}). 3422 3423@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3424@node Tags 3425@section Tags--Symbolic revisions 3426@cindex Tags 3427 3428The revision numbers live a life of their own. They 3429need not have anything at all to do with the release 3430numbers of your software product. Depending 3431on how you use @sc{cvs} the revision numbers might change several times 3432between two releases. As an example, some of the 3433source files that make up @sc{rcs} 5.6 have the following 3434revision numbers: 3435@cindex RCS revision numbers 3436 3437@example 3438ci.c 5.21 3439co.c 5.9 3440ident.c 5.3 3441rcs.c 5.12 3442rcsbase.h 5.11 3443rcsdiff.c 5.10 3444rcsedit.c 5.11 3445rcsfcmp.c 5.9 3446rcsgen.c 5.10 3447rcslex.c 5.11 3448rcsmap.c 5.2 3449rcsutil.c 5.10 3450@end example 3451 3452@cindex tag (subcommand), introduction 3453@cindex Tags, symbolic name 3454@cindex Symbolic name (tag) 3455@cindex Name, symbolic (tag) 3456@cindex HEAD, as reserved tag name 3457@cindex BASE, as reserved tag name 3458You can use the @code{tag} command to give a symbolic name to a 3459certain revision of a file. You can use the @samp{-v} flag to the 3460@code{status} command to see all tags that a file has, and 3461which revision numbers they represent. Tag names must 3462start with an uppercase or lowercase letter and can 3463contain uppercase and lowercase letters, digits, 3464@samp{-}, and @samp{_}. The two tag names @code{BASE} 3465and @code{HEAD} are reserved for use by @sc{cvs}. It 3466is expected that future names which are special to 3467@sc{cvs} will be specially named, for example by 3468starting with @samp{.}, rather than being named analogously to 3469@code{BASE} and @code{HEAD}, to avoid conflicts with 3470actual tag names. 3471@c Including a character such as % or = has also been 3472@c suggested as the naming convention for future 3473@c special tag names. Starting with . is nice because 3474@c that is not a legal tag name as far as RCS is concerned. 3475@c FIXME: CVS actually accepts quite a few characters 3476@c in tag names, not just the ones documented above 3477@c (see RCS_check_tag). RCS 3478@c defines legitimate tag names by listing illegal 3479@c characters rather than legal ones. CVS is said to lose its 3480@c mind if you try to use "/" (try making such a tag sticky 3481@c and using "cvs status" client/server--see remote 3482@c protocol format for entries line for probable cause). 3483@c TODO: The testsuite 3484@c should test for whatever are documented above as 3485@c officially-OK tag names, and CVS should at least reject 3486@c characters that won't work, like "/". 3487 3488You'll want to choose some convention for naming tags, 3489based on information such as the name of the program 3490and the version number of the release. For example, 3491one might take the name of the program, immediately 3492followed by the version number with @samp{.} changed to 3493@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 3494@code{cvs1-9}. If you choose a consistent convention, 3495then you won't constantly be guessing whether a tag is 3496@code{cvs-1-9} or @code{cvs1_9} or what. You might 3497even want to consider enforcing your convention in the 3498taginfo file (@pxref{user-defined logging}). 3499@c Might be nice to say more about using taginfo this 3500@c way, like giving an example, or pointing out any particular 3501@c issues which arise. 3502 3503@cindex Adding a tag 3504@cindex Tags, example 3505The following example shows how you can add a tag to a 3506file. The commands must be issued inside your working 3507directory. That is, you should issue the 3508command in the directory where @file{backend.c} 3509resides. 3510 3511@example 3512$ cvs tag rel-0-4 backend.c 3513T backend.c 3514$ cvs status -v backend.c 3515=================================================================== 3516File: backend.c Status: Up-to-date 3517 3518 Version: 1.4 Tue Dec 1 14:39:01 1992 3519 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 3520 Sticky Tag: (none) 3521 Sticky Date: (none) 3522 Sticky Options: (none) 3523 3524 Existing Tags: 3525 rel-0-4 (revision: 1.4) 3526 3527@end example 3528 3529For a complete summary of the syntax of @code{cvs tag}, 3530including the various options, see @ref{Invoking CVS}. 3531 3532There is seldom reason to tag a file in isolation. A more common use is 3533to tag all the files that constitute a module with the same tag at 3534strategic points in the development life-cycle, such as when a release 3535is made. 3536 3537@example 3538$ cvs tag rel-1-0 . 3539cvs tag: Tagging . 3540T Makefile 3541T backend.c 3542T driver.c 3543T frontend.c 3544T parser.c 3545@end example 3546 3547@noindent 3548(When you give @sc{cvs} a directory as argument, it generally applies the 3549operation to all the files in that directory, and (recursively), to any 3550subdirectories that it may contain. @xref{Recursive behavior}.) 3551 3552@cindex Retrieving an old revision using tags 3553@cindex Tags, retrieving old revisions 3554The @code{checkout} command has a flag, @samp{-r}, that lets you check out 3555a certain revision of a module. This flag makes it easy to 3556retrieve the sources that make up release 1.0 of the module @samp{tc} at 3557any time in the future: 3558 3559@example 3560$ cvs checkout -r rel-1-0 tc 3561@end example 3562 3563@noindent 3564This is useful, for instance, if someone claims that there is a bug in 3565that release, but you cannot find the bug in the current working copy. 3566 3567You can also check out a module as it was at any given date. 3568@xref{checkout options}. When specifying @samp{-r} to 3569any of these commands, you will need beware of sticky 3570tags; see @ref{Sticky tags}. 3571 3572When you tag more than one file with the same tag you 3573can think about the tag as "a curve drawn through a 3574matrix of filename vs. revision number." Say we have 5 3575files with the following revisions: 3576 3577@example 3578@group 3579 file1 file2 file3 file4 file5 3580 3581 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 3582 1.2*- 1.2 1.2 -1.2*- 3583 1.3 \- 1.3*- 1.3 / 1.3 3584 1.4 \ 1.4 / 1.4 3585 \-1.5*- 1.5 3586 1.6 3587@end group 3588@end example 3589 3590At some time in the past, the @code{*} versions were tagged. 3591You can think of the tag as a handle attached to the curve 3592drawn through the tagged revisions. When you pull on 3593the handle, you get all the tagged revisions. Another 3594way to look at it is that you "sight" through a set of 3595revisions that is "flat" along the tagged revisions, 3596like this: 3597 3598@example 3599@group 3600 file1 file2 file3 file4 file5 3601 3602 1.1 3603 1.2 3604 1.1 1.3 _ 3605 1.1 1.2 1.4 1.1 / 3606 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here 3607 1.3 1.6 1.3 \_ 3608 1.4 1.4 3609 1.5 3610@end group 3611@end example 3612 3613@node Tagging the working directory 3614@section Specifying what to tag from the working directory 3615 3616@cindex tag (subcommand) 3617The example in the previous section demonstrates one of 3618the most common ways to choose which revisions to tag. 3619Namely, running the @code{cvs tag} command without 3620arguments causes @sc{cvs} to select the revisions which 3621are checked out in the current working directory. For 3622example, if the copy of @file{backend.c} in working 3623directory was checked out from revision 1.4, then 3624@sc{cvs} will tag revision 1.4. Note that the tag is 3625applied immediately to revision 1.4 in the repository; 3626tagging is not like modifying a file, or other 3627operations in which one first modifies the working 3628directory and then runs @code{cvs commit} to transfer 3629that modification to the repository. 3630 3631One potentially surprising aspect of the fact that 3632@code{cvs tag} operates on the repository is that you 3633are tagging the checked-in revisions, which may differ 3634from locally modified files in your working directory. 3635If you want to avoid doing this by mistake, specify the 3636@samp{-c} option to @code{cvs tag}. If there are any 3637locally modified files, @sc{cvs} will abort with an 3638error before it tags any files: 3639 3640@example 3641$ cvs tag -c rel-0-4 3642cvs tag: backend.c is locally modified 3643cvs [tag aborted]: correct the above errors first! 3644@end example 3645 3646@node Tagging by date/tag 3647@section Specifying what to tag by date or revision 3648@cindex rtag (subcommand) 3649 3650The @code{cvs rtag} command tags the repository as of a 3651certain date or time (or can be used to tag the latest 3652revision). @code{rtag} works directly on the 3653repository contents (it requires no prior checkout and 3654does not look for a working directory). 3655 3656The following options specify which date or revision to 3657tag. See @ref{Common options}, for a complete 3658description of them. 3659 3660@table @code 3661@item -D @var{date} 3662Tag the most recent revision no later than @var{date}. 3663 3664@item -f 3665Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}} 3666flags. If no matching revision is found, use the most 3667recent revision (instead of ignoring the file). 3668 3669@item -r @var{tag} 3670Only tag those files that contain existing tag @var{tag}. 3671@end table 3672 3673The @code{cvs tag} command also allows one to specify 3674files by revision or date, using the same @samp{-r}, 3675@samp{-D}, and @samp{-f} options. However, this 3676feature is probably not what you want. The reason is 3677that @code{cvs tag} chooses which files to tag based on 3678the files that exist in the working directory, rather 3679than the files which existed as of the given tag/date. 3680Therefore, you are generally better off using @code{cvs 3681rtag}. The exceptions might be cases like: 3682 3683@example 3684cvs tag -r 1.4 stable backend.c 3685@end example 3686 3687@node Modifying tags 3688@section Deleting, moving, and renaming tags 3689 3690@c Also see: 3691@c "How do I move or rename a magic branch tag?" 3692@c in the FAQ (I think the issues it talks about still 3693@c apply, but this could use some sanity.sh work). 3694 3695Normally one does not modify tags. They exist in order 3696to record the history of the repository and so deleting 3697them or changing their meaning would, generally, not be 3698what you want. 3699 3700However, there might be cases in which one uses a tag 3701temporarily or accidentally puts one in the wrong 3702place. Therefore, one might delete, move, or rename a 3703tag. 3704 3705@noindent 3706@strong{WARNING: the commands in this section are 3707dangerous; they permanently discard historical 3708information and it can be difficult or impossible to 3709recover from errors. If you are a @sc{cvs} 3710administrator, you may consider restricting these 3711commands with taginfo (@pxref{user-defined logging}).} 3712 3713@cindex Deleting tags 3714@cindex Deleting branch tags 3715@cindex Removing tags 3716@cindex Removing branch tags 3717@cindex Tags, deleting 3718@cindex Branch tags, deleting 3719To delete a tag, specify the @samp{-d} option to either 3720@code{cvs tag} or @code{cvs rtag}. For example: 3721 3722@example 3723cvs rtag -d rel-0-4 tc 3724@end example 3725 3726@noindent 3727deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 3728In the event that branch tags are encountered within the repository 3729with the given name, a warning message will be issued and the branch 3730tag will not be deleted. If you are absolutely certain you know what 3731you are doing, the @code{-B} option may be specified to allow deletion 3732of branch tags. In that case, any non-branch tags encountered will 3733trigger warnings and will not be deleted. 3734 3735@noindent 3736@strong{WARNING: Moving branch tags is very dangerous! If you think 3737you need the @code{-B} option, think again and ask your @sc{cvs} 3738administrator about it (if that isn't you). There is almost certainly 3739another way to accomplish what you want to accomplish.} 3740 3741@cindex Moving tags 3742@cindex Moving branch tags 3743@cindex Tags, moving 3744@cindex Branch tags, moving 3745When we say @dfn{move} a tag, we mean to make the same 3746name point to different revisions. For example, the 3747@code{stable} tag may currently point to revision 1.4 3748of @file{backend.c} and perhaps we want to make it 3749point to revision 1.6. To move a non-branch tag, specify the 3750@samp{-F} option to either @code{cvs tag} or @code{cvs 3751rtag}. For example, the task just mentioned might be 3752accomplished as: 3753 3754@example 3755cvs tag -r 1.6 -F stable backend.c 3756@end example 3757 3758@noindent 3759If any branch tags are encountered in the repository 3760with the given name, a warning is issued and the branch 3761tag is not disturbed. If you are absolutely certain you 3762wish to move the branch tag, the @code{-B} option may be specified. 3763In that case, non-branch tags encountered with the given 3764name are ignored with a warning message. 3765 3766@noindent 3767@strong{WARNING: Moving branch tags is very dangerous! If you think you 3768need the @code{-B} option, think again and ask your @sc{cvs} 3769administrator about it (if that isn't you). There is almost certainly 3770another way to accomplish what you want to accomplish.} 3771 3772@cindex Renaming tags 3773@cindex Tags, renaming 3774When we say @dfn{rename} a tag, we mean to make a 3775different name point to the same revisions as the old 3776tag. For example, one may have misspelled the tag name 3777and want to correct it (hopefully before others are 3778relying on the old spelling). To rename a tag, first 3779create a new tag using the @samp{-r} option to 3780@code{cvs rtag}, and then delete the old name. (Caution: 3781this method will not work with branch tags.) 3782This leaves the new tag on exactly the 3783same files as the old tag. For example: 3784 3785@example 3786cvs rtag -r old-name-0-4 rel-0-4 tc 3787cvs rtag -d old-name-0-4 tc 3788@end example 3789 3790@node Tagging add/remove 3791@section Tagging and adding and removing files 3792 3793The subject of exactly how tagging interacts with 3794adding and removing files is somewhat obscure; for the 3795most part @sc{cvs} will keep track of whether files 3796exist or not without too much fussing. By default, 3797tags are applied to only files which have a revision 3798corresponding to what is being tagged. Files which did 3799not exist yet, or which were already removed, simply 3800omit the tag, and @sc{cvs} knows to treat the absence 3801of a tag as meaning that the file didn't exist as of 3802that tag. 3803 3804However, this can lose a small amount of information. 3805For example, suppose a file was added and then removed. 3806Then, if the tag is missing for that file, there is no 3807way to know whether the tag refers to the time before 3808the file was added, or the time after it was removed. 3809If you specify the @samp{-r} option to @code{cvs rtag}, 3810then @sc{cvs} tags the files which have been removed, 3811and thereby avoids this problem. For example, one 3812might specify @code{-r HEAD} to tag the head. 3813 3814On the subject of adding and removing files, the 3815@code{cvs rtag} command has a @samp{-a} option which 3816means to clear the tag from removed files that would 3817not otherwise be tagged. For example, one might 3818specify this option in conjunction with @samp{-F} when 3819moving a tag. If one moved a tag without @samp{-a}, 3820then the tag in the removed files might still refer to 3821the old revision, rather than reflecting the fact that 3822the file had been removed. I don't think this is 3823necessary if @samp{-r} is specified, as noted above. 3824 3825@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3826@node Sticky tags 3827@section Sticky tags 3828@cindex Sticky tags 3829@cindex Tags, sticky 3830 3831@c A somewhat related issue is per-directory sticky 3832@c tags (see comment at CVS/Tag in node Working 3833@c directory storage); we probably want to say 3834@c something like "you can set a sticky tag for only 3835@c some files, but you don't want to" or some such. 3836 3837Sometimes a working copy's revision has extra data 3838associated with it, for example it might be on a branch 3839(@pxref{Branching and merging}), or restricted to 3840versions prior to a certain date by @samp{checkout -D} 3841or @samp{update -D}. Because this data persists -- 3842that is, it applies to subsequent commands in the 3843working copy -- we refer to it as @dfn{sticky}. 3844 3845Most of the time, stickiness is an obscure aspect of 3846@sc{cvs} that you don't need to think about. However, 3847even if you don't want to use the feature, you may need 3848to know @emph{something} about sticky tags (for 3849example, how to avoid them!). 3850 3851You can use the @code{status} command to see if any 3852sticky tags or dates are set: 3853 3854@example 3855$ cvs status driver.c 3856=================================================================== 3857File: driver.c Status: Up-to-date 3858 3859 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 3860 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 3861 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 3862 Sticky Date: (none) 3863 Sticky Options: (none) 3864 3865@end example 3866 3867@cindex Resetting sticky tags 3868@cindex Sticky tags, resetting 3869@cindex Deleting sticky tags 3870The sticky tags will remain on your working files until 3871you delete them with @samp{cvs update -A}. The 3872@samp{-A} option merges local changes into the version of the 3873file from the head of the trunk, removing any sticky tags, 3874dates, or options. See @ref{update} for more on the operation 3875of @code{cvs update}. 3876 3877@cindex Sticky date 3878The most common use of sticky tags is to identify which 3879branch one is working on, as described in 3880@ref{Accessing branches}. However, non-branch 3881sticky tags have uses as well. For example, 3882suppose that you want to avoid updating your working 3883directory, to isolate yourself from possibly 3884destabilizing changes other people are making. You 3885can, of course, just refrain from running @code{cvs 3886update}. But if you want to avoid updating only a 3887portion of a larger tree, then sticky tags can help. 3888If you check out a certain revision (such as 1.4) it 3889will become sticky. Subsequent @code{cvs update} 3890commands will 3891not retrieve the latest revision until you reset the 3892tag with @code{cvs update -A}. Likewise, use of the 3893@samp{-D} option to @code{update} or @code{checkout} 3894sets a @dfn{sticky date}, which, similarly, causes that 3895date to be used for future retrievals. 3896 3897People often want to retrieve an old version of 3898a file without setting a sticky tag. This can 3899be done with the @samp{-p} option to @code{checkout} or 3900@code{update}, which sends the contents of the file to 3901standard output. For example: 3902@example 3903$ cvs update -p -r 1.1 file1 >file1 3904=================================================================== 3905Checking out file1 3906RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 3907VERS: 1.1 3908*************** 3909$ 3910@end example 3911 3912However, this isn't the easiest way, if you are asking 3913how to undo a previous checkin (in this example, put 3914@file{file1} back to the way it was as of revision 39151.1). In that case you are better off using the 3916@samp{-j} option to @code{update}; for further 3917discussion see @ref{Merging two revisions}. 3918 3919@c --------------------------------------------------------------------- 3920@node Branching and merging 3921@chapter Branching and merging 3922@cindex Branching 3923@cindex Merging 3924@cindex Copying changes 3925@cindex Main trunk and branches 3926@cindex Revision tree, making branches 3927@cindex Branches, copying changes between 3928@cindex Changes, copying between branches 3929@cindex Modifications, copying between branches 3930 3931@sc{cvs} allows you to isolate changes onto a separate 3932line of development, known as a @dfn{branch}. When you 3933change files on a branch, those changes do not appear 3934on the main trunk or other branches. 3935 3936Later you can move changes from one branch to another 3937branch (or the main trunk) by @dfn{merging}. Merging 3938involves first running @code{cvs update -j}, to merge 3939the changes into the working directory. 3940You can then commit that revision, and thus effectively 3941copy the changes onto another branch. 3942 3943@menu 3944* Branches motivation:: What branches are good for 3945* Creating a branch:: Creating a branch 3946* Accessing branches:: Checking out and updating branches 3947* Branches and revisions:: Branches are reflected in revision numbers 3948* Magic branch numbers:: Magic branch numbers 3949* Merging a branch:: Merging an entire branch 3950* Merging more than once:: Merging from a branch several times 3951* Merging two revisions:: Merging differences between two revisions 3952* Merging adds and removals:: What if files are added or removed? 3953* Merging and keywords:: Avoiding conflicts due to keyword substitution 3954@end menu 3955 3956@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3957@node Branches motivation 3958@section What branches are good for 3959@cindex Branches motivation 3960@cindex What branches are good for 3961@cindex Motivation for branches 3962 3963@c FIXME: this node mentions one way to use branches, 3964@c but it is by no means the only way. For example, 3965@c the technique of committing a new feature on a branch, 3966@c until it is ready for the main trunk. The whole 3967@c thing is generally speaking more akin to the 3968@c "Revision management" node although it isn't clear to 3969@c me whether policy matters should be centralized or 3970@c distributed throughout the relevant sections. 3971Suppose that release 1.0 of tc has been made. You are continuing to 3972develop tc, planning to create release 1.1 in a couple of months. After a 3973while your customers start to complain about a fatal bug. You check 3974out release 1.0 (@pxref{Tags}) and find the bug 3975(which turns out to have a trivial fix). However, the current revision 3976of the sources are in a state of flux and are not expected to be stable 3977for at least another month. There is no way to make a 3978bugfix release based on the newest sources. 3979 3980The thing to do in a situation like this is to create a @dfn{branch} on 3981the revision trees for all the files that make up 3982release 1.0 of tc. You can then make 3983modifications to the branch without disturbing the main trunk. When the 3984modifications are finished you can elect to either incorporate them on 3985the main trunk, or leave them on the branch. 3986 3987@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3988@node Creating a branch 3989@section Creating a branch 3990@cindex Creating a branch 3991@cindex Branch, creating a 3992@cindex tag (subcommand), creating a branch using 3993@cindex rtag (subcommand), creating a branch using 3994 3995You can create a branch with @code{tag -b}; for 3996example, assuming you're in a working copy: 3997 3998@example 3999$ cvs tag -b rel-1-0-patches 4000@end example 4001 4002@c FIXME: we should be more explicit about the value of 4003@c having a tag on the branchpoint. For example 4004@c "cvs tag rel-1-0-patches-branchpoint" before 4005@c the "cvs tag -b". This points out that 4006@c rel-1-0-patches is a pretty awkward name for 4007@c this example (more so than for the rtag example 4008@c below). 4009 4010This splits off a branch based on the current revisions 4011in the working copy, assigning that branch the name 4012@samp{rel-1-0-patches}. 4013 4014It is important to understand that branches get created 4015in the repository, not in the working copy. Creating a 4016branch based on current revisions, as the above example 4017does, will @emph{not} automatically switch the working 4018copy to be on the new branch. For information on how 4019to do that, see @ref{Accessing branches}. 4020 4021You can also create a branch without reference to any 4022working copy, by using @code{rtag}: 4023 4024@example 4025$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 4026@end example 4027 4028@samp{-r rel-1-0} says that this branch should be 4029rooted at the revision that 4030corresponds to the tag @samp{rel-1-0}. It need not 4031be the most recent revision -- it's often useful to 4032split a branch off an old revision (for example, when 4033fixing a bug in a past release otherwise known to be 4034stable). 4035 4036As with @samp{tag}, the @samp{-b} flag tells 4037@code{rtag} to create a branch (rather than just a 4038symbolic revision name). Note that the numeric 4039revision number that matches @samp{rel-1-0} will 4040probably be different from file to file. 4041 4042So, the full effect of the command is to create a new 4043branch -- named @samp{rel-1-0-patches} -- in module 4044@samp{tc}, rooted in the revision tree at the point tagged 4045by @samp{rel-1-0}. 4046 4047@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4048@node Accessing branches 4049@section Accessing branches 4050@cindex Check out a branch 4051@cindex Retrieve a branch 4052@cindex Access a branch 4053@cindex Identifying a branch 4054@cindex Branch, check out 4055@cindex Branch, retrieving 4056@cindex Branch, accessing 4057@cindex Branch, identifying 4058 4059You can retrieve a branch in one of two ways: by 4060checking it out fresh from the repository, or by 4061switching an existing working copy over to the branch. 4062 4063To check out a branch from the repository, invoke 4064@samp{checkout} with the @samp{-r} flag, followed by 4065the tag name of the branch (@pxref{Creating a branch}): 4066 4067@example 4068$ cvs checkout -r rel-1-0-patches tc 4069@end example 4070 4071Or, if you already have a working copy, you can switch 4072it to a given branch with @samp{update -r}: 4073 4074@example 4075$ cvs update -r rel-1-0-patches tc 4076@end example 4077 4078@noindent 4079or equivalently: 4080 4081@example 4082$ cd tc 4083$ cvs update -r rel-1-0-patches 4084@end example 4085 4086It does not matter if the working copy was originally 4087on the main trunk or on some other branch -- the above 4088command will switch it to the named branch. And 4089similarly to a regular @samp{update} command, 4090@samp{update -r} merges any changes you have made, 4091notifying you of conflicts where they occur. 4092 4093Once you have a working copy tied to a particular 4094branch, it remains there until you tell it otherwise. 4095This means that changes checked in from the working 4096copy will add new revisions on that branch, while 4097leaving the main trunk and other branches unaffected. 4098 4099@cindex Branches, sticky 4100To find out what branch a working copy is on, you can 4101use the @samp{status} command. In its output, look for 4102the field named @samp{Sticky tag} (@pxref{Sticky tags}) 4103-- that's @sc{cvs}'s way of telling you the branch, if 4104any, of the current working files: 4105 4106@example 4107$ cvs status -v driver.c backend.c 4108=================================================================== 4109File: driver.c Status: Up-to-date 4110 4111 Version: 1.7 Sat Dec 5 18:25:54 1992 4112 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 4113 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4114 Sticky Date: (none) 4115 Sticky Options: (none) 4116 4117 Existing Tags: 4118 rel-1-0-patches (branch: 1.7.2) 4119 rel-1-0 (revision: 1.7) 4120 4121=================================================================== 4122File: backend.c Status: Up-to-date 4123 4124 Version: 1.4 Tue Dec 1 14:39:01 1992 4125 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 4126 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 4127 Sticky Date: (none) 4128 Sticky Options: (none) 4129 4130 Existing Tags: 4131 rel-1-0-patches (branch: 1.4.2) 4132 rel-1-0 (revision: 1.4) 4133 rel-0-4 (revision: 1.4) 4134 4135@end example 4136 4137Don't be confused by the fact that the branch numbers 4138for each file are different (@samp{1.7.2} and 4139@samp{1.4.2} respectively). The branch tag is the 4140same, @samp{rel-1-0-patches}, and the files are 4141indeed on the same branch. The numbers simply reflect 4142the point in each file's revision history at which the 4143branch was made. In the above example, one can deduce 4144that @samp{driver.c} had been through more changes than 4145@samp{backend.c} before this branch was created. 4146 4147See @ref{Branches and revisions} for details about how 4148branch numbers are constructed. 4149 4150@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4151@node Branches and revisions 4152@section Branches and revisions 4153@cindex Branch number 4154@cindex Number, branch 4155@cindex Revision numbers (branches) 4156 4157Ordinarily, a file's revision history is a linear 4158series of increments (@pxref{Revision numbers}): 4159 4160@example 4161 +-----+ +-----+ +-----+ +-----+ +-----+ 4162 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 4163 +-----+ +-----+ +-----+ +-----+ +-----+ 4164@end example 4165 4166However, @sc{cvs} is not limited to linear development. The 4167@dfn{revision tree} can be split into @dfn{branches}, 4168where each branch is a self-maintained line of 4169development. Changes made on one branch can easily be 4170moved back to the main trunk. 4171 4172Each branch has a @dfn{branch number}, consisting of an 4173odd number of period-separated decimal integers. The 4174branch number is created by appending an integer to the 4175revision number where the corresponding branch forked 4176off. Having branch numbers allows more than one branch 4177to be forked off from a certain revision. 4178 4179@need 3500 4180All revisions on a branch have revision numbers formed 4181by appending an ordinal number to the branch number. 4182The following figure illustrates branching with an 4183example. 4184 4185@example 4186@c This example used to have a 1.2.2.4 revision, which 4187@c might help clarify that development can continue on 4188@c 1.2.2. Might be worth reinstating if it can be done 4189@c without overfull hboxes. 4190@group 4191 +-------------+ 4192 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 4193 / +-------------+ 4194 / 4195 / 4196 +---------+ +---------+ +---------+ 4197Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4198 / +---------+ +---------+ +---------+ 4199 / 4200 / 4201+-----+ +-----+ +-----+ +-----+ +-----+ 4202! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4203+-----+ +-----+ +-----+ +-----+ +-----+ 4204 ! 4205 ! 4206 ! +---------+ +---------+ +---------+ 4207Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 4208 +---------+ +---------+ +---------+ 4209 4210@end group 4211@end example 4212 4213@c -- However, at least for me the figure is not enough. I suggest more 4214@c -- text to accompany it. "A picture is worth a thousand words", so you 4215@c -- have to make sure the reader notices the couple of hundred words 4216@c -- *you* had in mind more than the others! 4217 4218@c -- Why an even number of segments? This section implies that this is 4219@c -- how the main trunk is distinguished from branch roots, but you never 4220@c -- explicitly say that this is the purpose of the [by itself rather 4221@c -- surprising] restriction to an even number of segments. 4222 4223The exact details of how the branch number is 4224constructed is not something you normally need to be 4225concerned about, but here is how it works: When 4226@sc{cvs} creates a branch number it picks the first 4227unused even integer, starting with 2. So when you want 4228to create a branch from revision 6.4 it will be 4229numbered 6.4.2. All branch numbers ending in a zero 4230(such as 6.4.0) are used internally by @sc{cvs} 4231(@pxref{Magic branch numbers}). The branch 1.1.1 has a 4232special meaning. @xref{Tracking sources}. 4233 4234@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4235@node Magic branch numbers 4236@section Magic branch numbers 4237 4238@c Want xref to here from "log"? 4239 4240This section describes a @sc{cvs} feature called 4241@dfn{magic branches}. For most purposes, you need not 4242worry about magic branches; @sc{cvs} handles them for 4243you. However, they are visible to you in certain 4244circumstances, so it may be useful to have some idea of 4245how it works. 4246 4247Externally, branch numbers consist of an odd number of 4248dot-separated decimal integers. @xref{Revision 4249numbers}. That is not the whole truth, however. For 4250efficiency reasons @sc{cvs} sometimes inserts an extra 0 4251in the second rightmost position (1.2.4 becomes 42521.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 4253on). 4254 4255@sc{cvs} does a pretty good job at hiding these so 4256called magic branches, but in a few places the hiding 4257is incomplete: 4258 4259@itemize @bullet 4260@item 4261The magic branch number appears in the output from 4262@code{cvs log}. 4263@c What output should appear instead? 4264 4265@item 4266You cannot specify a symbolic branch name to @code{cvs 4267admin}. 4268 4269@end itemize 4270 4271@c Can CVS do this automatically the first time 4272@c you check something in to that branch? Should 4273@c it? 4274You can use the @code{admin} command to reassign a 4275symbolic name to a branch the way @sc{rcs} expects it 4276to be. If @code{R4patches} is assigned to the branch 42771.4.2 (magic branch number 1.4.0.2) in file 4278@file{numbers.c} you can do this: 4279 4280@example 4281$ cvs admin -NR4patches:1.4.2 numbers.c 4282@end example 4283 4284It only works if at least one revision is already 4285committed on the branch. Be very careful so that you 4286do not assign the tag to the wrong number. (There is 4287no way to see how the tag was assigned yesterday). 4288 4289@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4290@node Merging a branch 4291@section Merging an entire branch 4292@cindex Merging a branch 4293@cindex -j (merging branches) 4294 4295You can merge changes made on a branch into your working copy by giving 4296the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 4297@samp{-j @var{branchname}} option it merges the changes made between the 4298greatest common ancestor (GCA) of the branch and the destination revision (in 4299the simple case below the GCA is the point where the branch forked) and the 4300newest revision on that branch into your working copy. 4301 4302@cindex Join 4303The @samp{-j} stands for ``join''. 4304 4305@cindex Branch merge example 4306@cindex Example, branch merge 4307@cindex Merge, branch example 4308Consider this revision tree: 4309 4310@example 4311+-----+ +-----+ +-----+ +-----+ 4312! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 4313+-----+ +-----+ +-----+ +-----+ 4314 ! 4315 ! 4316 ! +---------+ +---------+ 4317Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4318 +---------+ +---------+ 4319@end example 4320 4321@noindent 4322The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 4323following example assumes that the module @samp{mod} contains only one 4324file, @file{m.c}. 4325 4326@example 4327$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 4328 4329$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 4330 # @r{i.e. the changes between revision 1.2} 4331 # @r{and 1.2.2.2, into your working copy} 4332 # @r{of the file.} 4333 4334$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 4335@end example 4336 4337A conflict can result from a merge operation. If that 4338happens, you should resolve it before committing the 4339new revision. @xref{Conflicts example}. 4340 4341If your source files contain keywords (@pxref{Keyword substitution}), 4342you might be getting more conflicts than strictly necessary. See 4343@ref{Merging and keywords}, for information on how to avoid this. 4344 4345The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 4346same effect as above could be achieved with this: 4347 4348@example 4349$ cvs checkout -j R1fix mod 4350$ cvs commit -m "Included R1fix" 4351@end example 4352 4353It should be noted that @code{update -j @var{tagname}} will also work but may 4354not produce the desired result. @xref{Merging adds and removals}, for more. 4355 4356@node Merging more than once 4357@section Merging from a branch several times 4358 4359Continuing our example, the revision tree now looks 4360like this: 4361 4362@example 4363+-----+ +-----+ +-----+ +-----+ +-----+ 4364! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4365+-----+ +-----+ +-----+ +-----+ +-----+ 4366 ! * 4367 ! * 4368 ! +---------+ +---------+ 4369Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4370 +---------+ +---------+ 4371@end example 4372 4373@noindent 4374where the starred line represents the merge from the 4375@samp{R1fix} branch to the main trunk, as just 4376discussed. 4377 4378Now suppose that development continues on the 4379@samp{R1fix} branch: 4380 4381@example 4382+-----+ +-----+ +-----+ +-----+ +-----+ 4383! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4384+-----+ +-----+ +-----+ +-----+ +-----+ 4385 ! * 4386 ! * 4387 ! +---------+ +---------+ +---------+ 4388Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4389 +---------+ +---------+ +---------+ 4390@end example 4391 4392@noindent 4393and then you want to merge those new changes onto the 4394main trunk. If you just use the @code{cvs update -j 4395R1fix m.c} command again, @sc{cvs} will attempt to 4396merge again the changes which you have already merged, 4397which can have undesirable side effects. 4398 4399So instead you need to specify that you only want to 4400merge the changes on the branch which have not yet been 4401merged into the trunk. To do that you specify two 4402@samp{-j} options, and @sc{cvs} merges the changes from 4403the first revision to the second revision. For 4404example, in this case the simplest way would be 4405 4406@example 4407cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 4408 # @r{head of the R1fix branch} 4409@end example 4410 4411The problem with this is that you need to specify the 44121.2.2.2 revision manually. A slightly better approach 4413might be to use the date the last merge was done: 4414 4415@example 4416cvs update -j R1fix:yesterday -j R1fix m.c 4417@end example 4418 4419Better yet, tag the R1fix branch after every merge into 4420the trunk, and then use that tag for subsequent merges: 4421 4422@example 4423cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 4424@end example 4425 4426@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4427@node Merging two revisions 4428@section Merging differences between any two revisions 4429@cindex Merging two revisions 4430@cindex Revisions, merging differences between 4431@cindex Differences, merging 4432 4433With two @samp{-j @var{revision}} flags, the @code{update} 4434(and @code{checkout}) command can merge the differences 4435between any two revisions into your working file. 4436 4437@cindex Undoing a change 4438@cindex Removing a change 4439@example 4440$ cvs update -j 1.5 -j 1.3 backend.c 4441@end example 4442 4443@noindent 4444will undo all changes made between revision 44451.3 and 1.5. Note the order of the revisions! 4446 4447If you try to use this option when operating on 4448multiple files, remember that the numeric revisions will 4449probably be very different between the various files. 4450You almost always use symbolic 4451tags rather than revision numbers when operating on 4452multiple files. 4453 4454@cindex Restoring old version of removed file 4455@cindex Resurrecting old version of dead file 4456Specifying two @samp{-j} options can also undo file 4457removals or additions. For example, suppose you have 4458a file 4459named @file{file1} which existed as revision 1.1, and 4460you then removed it (thus adding a dead revision 1.2). 4461Now suppose you want to add it again, with the same 4462contents it had previously. Here is how to do it: 4463 4464@example 4465$ cvs update -j 1.2 -j 1.1 file1 4466U file1 4467$ cvs commit -m test 4468Checking in file1; 4469/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 4470new revision: 1.3; previous revision: 1.2 4471done 4472$ 4473@end example 4474 4475@node Merging adds and removals 4476@section Merging can add or remove files 4477 4478If the changes which you are merging involve removing 4479or adding some files, @code{update -j} will reflect 4480such additions or removals. 4481 4482@c FIXME: This example needs a lot more explanation. 4483@c We also need other examples for some of the other 4484@c cases (not all--there are too many--as long as we present a 4485@c coherent general principle). 4486For example: 4487@example 4488cvs update -A 4489touch a b c 4490cvs add a b c ; cvs ci -m "added" a b c 4491cvs tag -b branchtag 4492cvs update -r branchtag 4493touch d ; cvs add d 4494rm a ; cvs rm a 4495cvs ci -m "added d, removed a" 4496cvs update -A 4497cvs update -jbranchtag 4498@end example 4499 4500After these commands are executed and a @samp{cvs commit} is done, 4501file @file{a} will be removed and file @file{d} added in the main branch. 4502@c (which was determined by trying it) 4503 4504Note that using a single static tag (@samp{-j @var{tagname}}) 4505rather than a dynamic tag (@samp{-j @var{branchname}}) to merge 4506changes from a branch will usually not remove files which were removed on the 4507branch since @sc{cvs} does not automatically add static tags to dead revisions. 4508The exception to this rule occurs when 4509a static tag has been attached to a dead revision manually. Use the branch tag 4510to merge all changes from the branch or use two static tags as merge endpoints 4511to be sure that all intended changes are propagated in the merge. 4512 4513@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4514@node Merging and keywords 4515@section Merging and keywords 4516@cindex Merging, and keyword substitution 4517@cindex Keyword substitution, and merging 4518@cindex -j (merging branches), and keyword substitution 4519@cindex -kk, to avoid conflicts during a merge 4520 4521If you merge files containing keywords (@pxref{Keyword 4522substitution}), you will normally get numerous 4523conflicts during the merge, because the keywords are 4524expanded differently in the revisions which you are 4525merging. 4526 4527Therefore, you will often want to specify the 4528@samp{-kk} (@pxref{Substitution modes}) switch to the 4529merge command line. By substituting just the name of 4530the keyword, not the expanded value of that keyword, 4531this option ensures that the revisions which you are 4532merging will be the same as each other, and avoid 4533spurious conflicts. 4534 4535For example, suppose you have a file like this: 4536 4537@example 4538 +---------+ 4539 _! 1.1.2.1 ! <- br1 4540 / +---------+ 4541 / 4542 / 4543+-----+ +-----+ 4544! 1.1 !----! 1.2 ! 4545+-----+ +-----+ 4546@end example 4547 4548@noindent 4549and your working directory is currently on the trunk 4550(revision 1.2). Then you might get the following 4551results from a merge: 4552 4553@example 4554$ cat file1 4555key $@i{}Revision: 1.2 $ 4556. . . 4557$ cvs update -j br1 4558U file1 4559RCS file: /cvsroot/first-dir/file1,v 4560retrieving revision 1.1 4561retrieving revision 1.1.2.1 4562Merging differences between 1.1 and 1.1.2.1 into file1 4563rcsmerge: warning: conflicts during merge 4564$ cat file1 4565@asis{}<<<<<<< file1 4566key $@i{}Revision: 1.2 $ 4567@asis{}======= 4568key $@i{}Revision: 1.1.2.1 $ 4569@asis{}>>>>>>> 1.1.2.1 4570. . . 4571@end example 4572 4573What happened was that the merge tried to merge the 4574differences between 1.1 and 1.1.2.1 into your working 4575directory. So, since the keyword changed from 4576@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 4577@sc{cvs} tried to merge that change into your working 4578directory, which conflicted with the fact that your 4579working directory had contained @code{Revision: 1.2}. 4580 4581Here is what happens if you had used @samp{-kk}: 4582 4583@example 4584$ cat file1 4585key $@i{}Revision: 1.2 $ 4586. . . 4587$ cvs update -kk -j br1 4588U file1 4589RCS file: /cvsroot/first-dir/file1,v 4590retrieving revision 1.1 4591retrieving revision 1.1.2.1 4592Merging differences between 1.1 and 1.1.2.1 into file1 4593$ cat file1 4594key $@i{}Revision$ 4595. . . 4596@end example 4597 4598What is going on here is that revision 1.1 and 1.1.2.1 4599both expand as plain @code{Revision}, and therefore 4600merging the changes between them into the working 4601directory need not change anything. Therefore, there 4602is no conflict. 4603 4604@strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a 4605major problem with using @samp{-kk} on merges. Namely, @samp{-kk} 4606overrode any default keyword expansion mode set in the archive file in 4607the repository. This could, unfortunately for some users, cause data 4608corruption in binary files (with a default keyword expansion mode set 4609to @samp{-kb}). Therefore, when a repository contained binary files, 4610conflicts had to be dealt with manually rather than using @samp{-kk} in 4611a merge command.} 4612 4613In @sc{cvs} version 1.12.2 and later, the keyword expansion mode 4614provided on the command line to any @sc{cvs} command no longer 4615overrides the @samp{-kb} keyword expansion mode setting for binary 4616files, though it will still override other default keyword expansion 4617modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts 4618on lines containing RCS keywords, even when your repository contains 4619binary files. 4620 4621@c --------------------------------------------------------------------- 4622@node Recursive behavior 4623@chapter Recursive behavior 4624@cindex Recursive (directory descending) 4625@cindex Directory, descending 4626@cindex Descending directories 4627@cindex Subdirectories 4628 4629Almost all of the subcommands of @sc{cvs} work 4630recursively when you specify a directory as an 4631argument. For instance, consider this directory 4632structure: 4633 4634@example 4635 @code{$HOME} 4636 | 4637 +--@t{tc} 4638 | | 4639 +--@t{CVS} 4640 | (internal @sc{cvs} files) 4641 +--@t{Makefile} 4642 +--@t{backend.c} 4643 +--@t{driver.c} 4644 +--@t{frontend.c} 4645 +--@t{parser.c} 4646 +--@t{man} 4647 | | 4648 | +--@t{CVS} 4649 | | (internal @sc{cvs} files) 4650 | +--@t{tc.1} 4651 | 4652 +--@t{testing} 4653 | 4654 +--@t{CVS} 4655 | (internal @sc{cvs} files) 4656 +--@t{testpgm.t} 4657 +--@t{test2.t} 4658@end example 4659 4660@noindent 4661If @file{tc} is the current working directory, the 4662following is true: 4663 4664@itemize @bullet 4665@item 4666@samp{cvs update testing} is equivalent to 4667 4668@example 4669cvs update testing/testpgm.t testing/test2.t 4670@end example 4671 4672@item 4673@samp{cvs update testing man} updates all files in the 4674subdirectories 4675 4676@item 4677@samp{cvs update .} or just @samp{cvs update} updates 4678all files in the @code{tc} directory 4679@end itemize 4680 4681If no arguments are given to @code{update} it will 4682update all files in the current working directory and 4683all its subdirectories. In other words, @file{.} is a 4684default argument to @code{update}. This is also true 4685for most of the @sc{cvs} subcommands, not only the 4686@code{update} command. 4687 4688The recursive behavior of the @sc{cvs} subcommands can be 4689turned off with the @samp{-l} option. 4690Conversely, the @samp{-R} option can be used to force recursion if 4691@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 4692 4693@example 4694$ cvs update -l # @r{Don't update files in subdirectories} 4695@end example 4696 4697@c --------------------------------------------------------------------- 4698@node Adding and removing 4699@chapter Adding, removing, and renaming files and directories 4700 4701In the course of a project, one will often add new 4702files. Likewise with removing or renaming, or with 4703directories. The general concept to keep in mind in 4704all these cases is that instead of making an 4705irreversible change you want @sc{cvs} to record the 4706fact that a change has taken place, just as with 4707modifying an existing file. The exact mechanisms to do 4708this in @sc{cvs} vary depending on the situation. 4709 4710@menu 4711* Adding files:: Adding files 4712* Removing files:: Removing files 4713* Removing directories:: Removing directories 4714* Moving files:: Moving and renaming files 4715* Moving directories:: Moving and renaming directories 4716@end menu 4717 4718@node Adding files 4719@section Adding files to a directory 4720@cindex Adding files 4721 4722To add a new file to a directory, follow these steps. 4723 4724@itemize @bullet 4725@item 4726You must have a working copy of the directory. 4727@xref{Getting the source}. 4728 4729@item 4730Create the new file inside your working copy of the directory. 4731 4732@item 4733Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you 4734want to version control the file. If the file contains 4735binary data, specify @samp{-kb} (@pxref{Binary files}). 4736 4737@item 4738Use @samp{cvs commit @var{filename}} to actually check 4739in the file into the repository. Other developers 4740cannot see the file until you perform this step. 4741@end itemize 4742 4743You can also use the @code{add} command to add a new 4744directory. 4745@c FIXCVS and/or FIXME: Adding a directory doesn't 4746@c require the commit step. This probably can be 4747@c considered a CVS bug, but it is possible we should 4748@c warn people since this behavior probably won't be 4749@c changing right away. 4750 4751Unlike most other commands, the @code{add} command is 4752not recursive. You cannot even type @samp{cvs add 4753foo/bar}! Instead, you have to 4754@c FIXCVS: This is, of course, not a feature. It is 4755@c just that no one has gotten around to fixing "cvs add 4756@c foo/bar". 4757 4758@example 4759$ cd foo 4760$ cvs add bar 4761@end example 4762 4763@cindex add (subcommand) 4764@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 4765 4766Schedule @var{files} to be added to the repository. 4767The files or directories specified with @code{add} must 4768already exist in the current directory. To add a whole 4769new directory hierarchy to the source repository (for 4770example, files received from a third-party vendor), use 4771the @code{import} command instead. @xref{import}. 4772 4773The added files are not placed in the source repository 4774until you use @code{commit} to make the change 4775permanent. Doing an @code{add} on a file that was 4776removed with the @code{remove} command will undo the 4777effect of the @code{remove}, unless a @code{commit} 4778command intervened. @xref{Removing files}, for an 4779example. 4780 4781The @samp{-k} option specifies the default way that 4782this file will be checked out; for more information see 4783@ref{Substitution modes}. 4784 4785@c As noted in BUGS, -m is broken client/server (Nov 4786@c 96). Also see testsuite log2-* tests. 4787The @samp{-m} option specifies a description for the 4788file. This description appears in the history log (if 4789it is enabled, @pxref{history file}). It will also be 4790saved in the version history inside the repository when 4791the file is committed. The @code{log} command displays 4792this description. The description can be changed using 4793@samp{admin -t}. @xref{admin}. If you omit the 4794@samp{-m @var{description}} flag, an empty string will 4795be used. You will not be prompted for a description. 4796@end deffn 4797 4798For example, the following commands add the file 4799@file{backend.c} to the repository: 4800 4801@c This example used to specify 4802@c -m "Optimizer and code generation passes." 4803@c to the cvs add command, but that doesn't work 4804@c client/server (see log2 in sanity.sh). Should fix CVS, 4805@c but also seems strange to document things which 4806@c don't work... 4807@example 4808$ cvs add backend.c 4809$ cvs commit -m "Early version. Not yet compilable." backend.c 4810@end example 4811 4812When you add a file it is added only on the branch 4813which you are working on (@pxref{Branching and merging}). You can 4814later merge the additions to another branch if you want 4815(@pxref{Merging adds and removals}). 4816@c Should we mention that earlier versions of CVS 4817@c lacked this feature (1.3) or implemented it in a buggy 4818@c way (well, 1.8 had many bugs in cvs update -j)? 4819@c Should we mention the bug/limitation regarding a 4820@c file being a regular file on one branch and a directory 4821@c on another? 4822@c FIXME: This needs an example, or several, here or 4823@c elsewhere, for it to make much sense. 4824@c Somewhere we need to discuss the aspects of death 4825@c support which don't involve branching, I guess. 4826@c Like the ability to re-create a release from a tag. 4827 4828@c --------------------------------------------------------------------- 4829@node Removing files 4830@section Removing files 4831@cindex Removing files 4832@cindex Deleting files 4833 4834@c FIXME: this node wants to be split into several 4835@c smaller nodes. Could make these children of 4836@c "Adding and removing", probably (death support could 4837@c be its own section, for example, as could the 4838@c various bits about undoing mistakes in adding and 4839@c removing). 4840Directories change. New files are added, and old files 4841disappear. Still, you want to be able to retrieve an 4842exact copy of old releases. 4843 4844Here is what you can do to remove a file, 4845but remain able to retrieve old revisions: 4846 4847@itemize @bullet 4848@c FIXME: should probably be saying something about 4849@c having a working directory in the first place. 4850@item 4851Make sure that you have not made any uncommitted 4852modifications to the file. @xref{Viewing differences}, 4853for one way to do that. You can also use the 4854@code{status} or @code{update} command. If you remove 4855the file without committing your changes, you will of 4856course not be able to retrieve the file as it was 4857immediately before you deleted it. 4858 4859@item 4860Remove the file from your working copy of the directory. 4861You can for instance use @code{rm}. 4862 4863@item 4864Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that 4865you really want to delete the file. 4866 4867@item 4868Use @samp{cvs commit @var{filename}} to actually 4869perform the removal of the file from the repository. 4870@end itemize 4871 4872@c FIXME: Somehow this should be linked in with a more 4873@c general discussion of death support. I don't know 4874@c whether we want to use the term "death support" or 4875@c not (we can perhaps get by without it), but we do 4876@c need to discuss the "dead" state in "cvs log" and 4877@c related subjects. The current discussion is 4878@c scattered around, and not xref'd to each other. 4879@c FIXME: I think this paragraph wants to be moved 4880@c later down, at least after the first example. 4881When you commit the removal of the file, @sc{cvs} 4882records the fact that the file no longer exists. It is 4883possible for a file to exist on only some branches and 4884not on others, or to re-add another file with the same 4885name later. @sc{cvs} will correctly create or not create 4886the file, based on the @samp{-r} and @samp{-D} options 4887specified to @code{checkout} or @code{update}. 4888 4889@c FIXME: This style seems to clash with how we 4890@c document things in general. 4891@cindex Remove (subcommand) 4892@deffn Command {cvs remove} [options] files @dots{} 4893 4894Schedule file(s) to be removed from the repository 4895(files which have not already been removed from the 4896working directory are not processed). This command 4897does not actually remove the file from the repository 4898until you commit the removal. For a full list of 4899options, see @ref{Invoking CVS}. 4900@end deffn 4901 4902Here is an example of removing several files: 4903 4904@example 4905$ cd test 4906$ rm *.c 4907$ cvs remove 4908cvs remove: Removing . 4909cvs remove: scheduling a.c for removal 4910cvs remove: scheduling b.c for removal 4911cvs remove: use 'cvs commit' to remove these files permanently 4912$ cvs ci -m "Removed unneeded files" 4913cvs commit: Examining . 4914cvs commit: Committing . 4915@end example 4916 4917As a convenience you can remove the file and @code{cvs 4918remove} it in one step, by specifying the @samp{-f} 4919option. For example, the above example could also be 4920done like this: 4921 4922@example 4923$ cd test 4924$ cvs remove -f *.c 4925cvs remove: scheduling a.c for removal 4926cvs remove: scheduling b.c for removal 4927cvs remove: use 'cvs commit' to remove these files permanently 4928$ cvs ci -m "Removed unneeded files" 4929cvs commit: Examining . 4930cvs commit: Committing . 4931@end example 4932 4933If you execute @code{remove} for a file, and then 4934change your mind before you commit, you can undo the 4935@code{remove} with an @code{add} command. 4936 4937@c FIXME: what if you change your mind after you commit 4938@c it? (answer is also "cvs add" but we don't say that...). 4939@c We need some index entries for thinks like "undoing 4940@c removal" too. 4941 4942@example 4943$ ls 4944CVS ja.h oj.c 4945$ rm oj.c 4946$ cvs remove oj.c 4947cvs remove: scheduling oj.c for removal 4948cvs remove: use 'cvs commit' to remove this file permanently 4949$ cvs add oj.c 4950U oj.c 4951cvs add: oj.c, version 1.1.1.1, resurrected 4952@end example 4953 4954If you realize your mistake before you run the 4955@code{remove} command you can use @code{update} to 4956resurrect the file: 4957 4958@example 4959$ rm oj.c 4960$ cvs update oj.c 4961cvs update: warning: oj.c was lost 4962U oj.c 4963@end example 4964 4965When you remove a file it is removed only on the branch 4966which you are working on (@pxref{Branching and merging}). You can 4967later merge the removals to another branch if you want 4968(@pxref{Merging adds and removals}). 4969 4970@node Removing directories 4971@section Removing directories 4972@cindex Removing directories 4973@cindex Directories, removing 4974 4975In concept removing directories is somewhat similar to 4976removing files---you want the directory to not exist in 4977your current working directories, but you also want to 4978be able to retrieve old releases in which the directory 4979existed. 4980 4981The way that you remove a directory is to remove all 4982the files in it. You don't remove the directory 4983itself; there is no way to do that. 4984Instead you specify the @samp{-P} option to 4985@code{cvs update} or @code{cvs checkout}, 4986which will cause @sc{cvs} to remove empty 4987directories from working directories. 4988(Note that @code{cvs export} always removes empty directories.) 4989Probably the 4990best way to do this is to always specify @samp{-P}; if 4991you want an empty directory then put a dummy file (for 4992example @file{.keepme}) in it to prevent @samp{-P} from 4993removing it. 4994 4995@c I'd try to give a rationale for this, but I'm not 4996@c sure there is a particularly convincing one. What 4997@c we would _like_ is for CVS to do a better job of version 4998@c controlling whether directories exist, to eliminate the 4999@c need for -P and so that a file can be a directory in 5000@c one revision and a regular file in another. 5001Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5002options of @code{checkout}. This way 5003@sc{cvs} will be able to correctly create the directory 5004or not depending on whether the particular version you 5005are checking out contains any files in that directory. 5006 5007@c --------------------------------------------------------------------- 5008@node Moving files 5009@section Moving and renaming files 5010@cindex Moving files 5011@cindex Renaming files 5012@cindex Files, moving 5013 5014Moving files to a different directory or renaming them 5015is not difficult, but some of the ways in which this 5016works may be non-obvious. (Moving or renaming a 5017directory is even harder. @xref{Moving directories}.). 5018 5019The examples below assume that the file @var{old} is renamed to 5020@var{new}. 5021 5022@menu 5023* Outside:: The normal way to Rename 5024* Inside:: A tricky, alternative way 5025* Rename by copying:: Another tricky, alternative way 5026@end menu 5027 5028@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5029@node Outside 5030@subsection The Normal way to Rename 5031 5032@c More rename issues. Not sure whether these are 5033@c worth documenting; I'm putting them here because 5034@c it seems to be as good a place as any to try to 5035@c set down the issues. 5036@c * "cvs annotate" will annotate either the new 5037@c file or the old file; it cannot annotate _each 5038@c line_ based on whether it was last changed in the 5039@c new or old file. Unlike "cvs log", where the 5040@c consequences of having to select either the new 5041@c or old name seem fairly benign, this may be a 5042@c real advantage to having CVS know about renames 5043@c other than as a deletion and an addition. 5044 5045The normal way to move a file is to copy @var{old} to 5046@var{new}, and then issue the normal @sc{cvs} commands 5047to remove @var{old} from the repository, and add 5048@var{new} to it. 5049@c The following sentence is not true: one must cd into 5050@c the directory to run "cvs add". 5051@c (Both @var{old} and @var{new} could 5052@c contain relative paths, for example @file{foo/bar.c}). 5053 5054@example 5055$ mv @var{old} @var{new} 5056$ cvs remove @var{old} 5057$ cvs add @var{new} 5058$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 5059@end example 5060 5061This is the simplest way to move a file, it is not 5062error-prone, and it preserves the history of what was 5063done. Note that to access the history of the file you 5064must specify the old or the new name, depending on what 5065portion of the history you are accessing. For example, 5066@code{cvs log @var{old}} will give the log up until the 5067time of the rename. 5068 5069When @var{new} is committed its revision numbers will 5070start again, usually at 1.1, so if that bothers you, 5071use the @samp{-r rev} option to commit. For more 5072information see @ref{Assigning revisions}. 5073 5074@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5075@node Inside 5076@subsection Moving the history file 5077 5078This method is more dangerous, since it involves moving 5079files inside the repository. Read this entire section 5080before trying it out! 5081 5082@example 5083$ cd $CVSROOT/@var{dir} 5084$ mv @var{old},v @var{new},v 5085@end example 5086 5087@noindent 5088Advantages: 5089 5090@itemize @bullet 5091@item 5092The log of changes is maintained intact. 5093 5094@item 5095The revision numbers are not affected. 5096@end itemize 5097 5098@noindent 5099Disadvantages: 5100 5101@itemize @bullet 5102@item 5103Old releases cannot easily be fetched from the 5104repository. (The file will show up as @var{new} even 5105in revisions from the time before it was renamed). 5106 5107@item 5108There is no log information of when the file was renamed. 5109 5110@item 5111Nasty things might happen if someone accesses the history file 5112while you are moving it. Make sure no one else runs any of the @sc{cvs} 5113commands while you move it. 5114@end itemize 5115 5116@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5117@node Rename by copying 5118@subsection Copying the history file 5119 5120This way also involves direct modifications to the 5121repository. It is safe, but not without drawbacks. 5122 5123@example 5124# @r{Copy the @sc{rcs} file inside the repository} 5125$ cd $CVSROOT/@var{dir} 5126$ cp @var{old},v @var{new},v 5127# @r{Remove the old file} 5128$ cd ~/@var{dir} 5129$ rm @var{old} 5130$ cvs remove @var{old} 5131$ cvs commit @var{old} 5132# @r{Remove all tags from @var{new}} 5133$ cvs update @var{new} 5134$ cvs log @var{new} # @r{Remember the non-branch tag names} 5135$ cvs tag -d @var{tag1} @var{new} 5136$ cvs tag -d @var{tag2} @var{new} 5137@dots{} 5138@end example 5139 5140By removing the tags you will be able to check out old 5141revisions. 5142 5143@noindent 5144Advantages: 5145 5146@itemize @bullet 5147@item 5148@c FIXME: Is this true about -D now that we have death 5149@c support? See 5B.3 in the FAQ. 5150Checking out old revisions works correctly, as long as 5151you use @samp{-r@var{tag}} and not @samp{-D@var{date}} 5152to retrieve the revisions. 5153 5154@item 5155The log of changes is maintained intact. 5156 5157@item 5158The revision numbers are not affected. 5159@end itemize 5160 5161@noindent 5162Disadvantages: 5163 5164@itemize @bullet 5165@item 5166You cannot easily see the history of the file across the rename. 5167 5168@end itemize 5169 5170@c --------------------------------------------------------------------- 5171@node Moving directories 5172@section Moving and renaming directories 5173@cindex Moving directories 5174@cindex Renaming directories 5175@cindex Directories, moving 5176 5177The normal way to rename or move a directory is to 5178rename or move each file within it as described in 5179@ref{Outside}. Then check out with the @samp{-P} 5180option, as described in @ref{Removing directories}. 5181 5182If you really want to hack the repository to rename or 5183delete a directory in the repository, you can do it 5184like this: 5185 5186@enumerate 5187@item 5188Inform everyone who has a checked out copy of the directory that the 5189directory will be renamed. They should commit all 5190their changes, and remove their working copies, 5191before you take the steps below. 5192 5193@item 5194Rename the directory inside the repository. 5195 5196@example 5197$ cd $CVSROOT/@var{parent-dir} 5198$ mv @var{old-dir} @var{new-dir} 5199@end example 5200 5201@item 5202Fix the @sc{cvs} administrative files, if necessary (for 5203instance if you renamed an entire module). 5204 5205@item 5206Tell everyone that they can check out again and continue 5207working. 5208 5209@end enumerate 5210 5211If someone had a working copy the @sc{cvs} commands will 5212cease to work for him, until he removes the directory 5213that disappeared inside the repository. 5214 5215It is almost always better to move the files in the 5216directory instead of moving the directory. If you move the 5217directory you are unlikely to be able to retrieve old 5218releases correctly, since they probably depend on the 5219name of the directories. 5220 5221@c --------------------------------------------------------------------- 5222@node History browsing 5223@chapter History browsing 5224@cindex History browsing 5225@cindex Traceability 5226@cindex Isolation 5227 5228 5229@c kind of lame, in a lot of ways the above text inside 5230@c the @ignore motivates this chapter better 5231Once you have used @sc{cvs} to store a version control 5232history---what files have changed when, how, and by 5233whom, there are a variety of mechanisms for looking 5234through the history. 5235 5236@c FIXME: should also be talking about how you look at 5237@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 5238@menu 5239* log messages:: Log messages 5240* history database:: The history database 5241* user-defined logging:: User-defined logging 5242* annotate:: What revision modified each line of a file? 5243@end menu 5244 5245@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5246@node log messages 5247@section Log messages 5248 5249@c FIXME: @xref to place where we talk about how to 5250@c specify message to commit. 5251Whenever you commit a file you specify a log message. 5252 5253@c FIXME: bring the information here, and get rid of or 5254@c greatly shrink the "log" node. 5255To look through the log messages which have been 5256specified for every revision which has been committed, 5257use the @code{cvs log} command (@pxref{log}). 5258 5259@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5260@node history database 5261@section The history database 5262 5263@c FIXME: bring the information from the history file 5264@c and history nodes here. Rewrite it to be motivated 5265@c better (start out by clearly explaining what gets 5266@c logged in history, for example). 5267You can use the history file (@pxref{history file}) to 5268log various @sc{cvs} actions. To retrieve the 5269information from the history file, use the @code{cvs 5270history} command (@pxref{history}). 5271 5272Note: you can control what is logged to this file by using the 5273@samp{LogHistory} keyword in the @file{CVSROOT/config} file 5274(@pxref{config}). 5275 5276@c 5277@c The history database has many problems: 5278@c * It is very unclear what field means what. This 5279@c could be improved greatly by better documentation, 5280@c but there are still non-orthogonalities (for 5281@c example, tag does not record the "repository" 5282@c field but most records do). 5283@c * Confusion about files, directories, and modules. 5284@c Some commands record one, some record others. 5285@c * File removal is not logged. There is an 'R' 5286@c record type documented, but CVS never uses it. 5287@c * Tags are only logged for the "cvs rtag" command, 5288@c not "cvs tag". The fix for this is not completely 5289@c clear (see above about modules vs. files). 5290@c * Are there other cases of operations that are not 5291@c logged? One would hope for all changes to the 5292@c repository to be logged somehow (particularly 5293@c operations like tagging, "cvs admin -k", and other 5294@c operations which do not record a history that one 5295@c can get with "cvs log"). Operations on the working 5296@c directory, like export, get, and release, are a 5297@c second category also covered by the current "cvs 5298@c history". 5299@c * The history file does not record the options given 5300@c to a command. The most serious manifestation of 5301@c this is perhaps that it doesn't record whether a command 5302@c was recursive. It is not clear to me whether one 5303@c wants to log at a level very close to the command 5304@c line, as a sort of way of logging each command 5305@c (more or less), or whether one wants 5306@c to log more at the level of what was changed (or 5307@c something in between), but either way the current 5308@c information has pretty big gaps. 5309@c * Further details about a tag--like whether it is a 5310@c branch tag or, if a non-branch tag, which branch it 5311@c is on. One can find out this information about the 5312@c tag as it exists _now_, but if the tag has been 5313@c moved, one doesn't know what it was like at the time 5314@c the history record was written. 5315@c * Whether operating on a particular tag, date, or 5316@c options was implicit (sticky) or explicit. 5317@c 5318@c Another item, only somewhat related to the above, is a 5319@c way to control what is logged in the history file. 5320@c This is probably the only good way to handle 5321@c different people having different ideas about 5322@c information/space tradeoffs. 5323@c 5324@c It isn't really clear that it makes sense to try to 5325@c patch up the history file format as it exists now to 5326@c include all that stuff. It might be better to 5327@c design a whole new CVSROOT/nhistory file and "cvs 5328@c nhistory" command, or some such, or in some other 5329@c way trying to come up with a clean break from the 5330@c past, which can address the above concerns. Another 5331@c open question is how/whether this relates to 5332@c taginfo/loginfo/etc. 5333 5334@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5335@node user-defined logging 5336@section User-defined logging 5337 5338@c FIXME: should probably also mention the fact the -l 5339@c global option can disable most of the mechanisms 5340@c discussed here (why? What is the -l global option for?). 5341@c 5342@c FIXME: probably should centralize this information 5343@c here, at least to some extent. Maybe by moving the 5344@c loginfo, etc., nodes here and replacing 5345@c the "user-defined logging" node with one node for 5346@c each method. 5347You can customize @sc{cvs} to log various kinds of 5348actions, in whatever manner you choose. These 5349mechanisms operate by executing a script at various 5350times. The script might append a message to a file 5351listing the information and the programmer who created 5352it, or send mail to a group of developers, or, perhaps, 5353post a message to a particular newsgroup. To log 5354commits, use the @file{loginfo} file (@pxref{loginfo}). 5355@c FIXME: What is difference between doing it in the 5356@c modules file and using loginfo/taginfo? Why should 5357@c user use one or the other? 5358To log commits, checkouts, exports, and tags, 5359respectively, you can also use the @samp{-i}, 5360@samp{-o}, @samp{-e}, and @samp{-t} options in the 5361modules file. For a more flexible way of giving 5362notifications to various users, which requires less in 5363the way of keeping centralized scripts up to date, use 5364the @code{cvs watch add} command (@pxref{Getting 5365Notified}); this command is useful even if you are not 5366using @code{cvs watch on}. 5367 5368@cindex taginfo 5369@cindex Exit status, of taginfo 5370The @file{taginfo} file defines programs to execute 5371when someone executes a @code{tag} or @code{rtag} 5372command. The @file{taginfo} file has the standard form 5373for administrative files (@pxref{Administrative 5374files}), where each line is a regular expression 5375followed by a command to execute. The arguments passed 5376to the command are, in order, the @var{tagname}, 5377@var{operation} (@code{add} for @code{tag}, 5378@code{mov} for @code{tag -F}, and @code{del} for 5379@code{tag -d}), @var{repository}, and any remaining are 5380pairs of @var{filename} @var{revision}. A non-zero 5381exit of the filter program will cause the tag to be 5382aborted. 5383 5384Here is an example of using taginfo to log tag and rtag 5385commands. In the taginfo file put: 5386 5387@example 5388ALL /usr/local/cvsroot/CVSROOT/loggit 5389@end example 5390 5391@noindent 5392Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 5393following script: 5394 5395@example 5396#!/bin/sh 5397echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 5398@end example 5399 5400@node annotate 5401@section Annotate command 5402@cindex annotate (subcommand) 5403 5404@deffn Command {cvs annotate} [@code{-FflR}] [@code{-r rev}|@code{-D date}] files @dots{} 5405 5406For each file in @var{files}, print the head revision 5407of the trunk, together with information on the last 5408modification for each line. For example: 5409 5410@example 5411$ cvs annotate ssfile 5412Annotations for ssfile 5413*************** 54141.1 (mary 27-Mar-96): ssfile line 1 54151.2 (joe 28-Mar-96): ssfile line 2 5416@end example 5417 5418The file @file{ssfile} currently contains two lines. 5419The @code{ssfile line 1} line was checked in by 5420@code{mary} on March 27. Then, on March 28, @code{joe} 5421added a line @code{ssfile line 2}, without modifying 5422the @code{ssfile line 1} line. This report doesn't 5423tell you anything about lines which have been deleted 5424or replaced; you need to use @code{cvs diff} for that 5425(@pxref{diff}). 5426 5427@end deffn 5428 5429The options to @code{cvs annotate} are listed in 5430@ref{Invoking CVS}, and can be used to select the files 5431and revisions to annotate. The options are described 5432in more detail there and in @ref{Common options}. 5433 5434@c FIXME: maybe an example using the options? Just 5435@c what it means to select a revision might be worth a 5436@c few words of explanation ("you want to see who 5437@c changed this line *before* 1.4"...). 5438 5439@c --------------------------------------------------------------------- 5440@node Binary files 5441@chapter Handling binary files 5442@cindex Binary files 5443 5444The most common use for @sc{cvs} is to store text 5445files. With text files, @sc{cvs} can merge revisions, 5446display the differences between revisions in a 5447human-visible fashion, and other such operations. 5448However, if you are willing to give up a few of these 5449abilities, @sc{cvs} can store binary files. For 5450example, one might store a web site in @sc{cvs} 5451including both text files and binary images. 5452 5453@menu 5454* Binary why:: More details on issues with binary files 5455* Binary howto:: How to store them 5456@end menu 5457 5458@node Binary why 5459@section The issues with binary files 5460 5461While the need to manage binary files may seem obvious 5462if the files that you customarily work with are binary, 5463putting them into version control does present some 5464additional issues. 5465 5466One basic function of version control is to show the 5467differences between two revisions. For example, if 5468someone else checked in a new version of a file, you 5469may wish to look at what they changed and determine 5470whether their changes are good. For text files, 5471@sc{cvs} provides this functionality via the @code{cvs 5472diff} command. For binary files, it may be possible to 5473extract the two revisions and then compare them with a 5474tool external to @sc{cvs} (for example, word processing 5475software often has such a feature). If there is no 5476such tool, one must track changes via other mechanisms, 5477such as urging people to write good log messages, and 5478hoping that the changes they actually made were the 5479changes that they intended to make. 5480 5481Another ability of a version control system is the 5482ability to merge two revisions. For @sc{cvs} this 5483happens in two contexts. The first is when users make 5484changes in separate working directories 5485(@pxref{Multiple developers}). The second is when one 5486merges explicitly with the @samp{update -j} command 5487(@pxref{Branching and merging}). 5488 5489In the case of text 5490files, @sc{cvs} can merge changes made independently, 5491and signal a conflict if the changes conflict. With 5492binary files, the best that @sc{cvs} can do is present 5493the two different copies of the file, and leave it to 5494the user to resolve the conflict. The user may choose 5495one copy or the other, or may run an external merge 5496tool which knows about that particular file format, if 5497one exists. 5498Note that having the user merge relies primarily on the 5499user to not accidentally omit some changes, and thus is 5500potentially error prone. 5501 5502If this process is thought to be undesirable, the best 5503choice may be to avoid merging. To avoid the merges 5504that result from separate working directories, see the 5505discussion of reserved checkouts (file locking) in 5506@ref{Multiple developers}. To avoid the merges 5507resulting from branches, restrict use of branches. 5508 5509@node Binary howto 5510@section How to store binary files 5511 5512There are two issues with using @sc{cvs} to store 5513binary files. The first is that @sc{cvs} by default 5514converts line endings between the canonical form in 5515which they are stored in the repository (linefeed 5516only), and the form appropriate to the operating system 5517in use on the client (for example, carriage return 5518followed by line feed for Windows NT). 5519 5520The second is that a binary file might happen to 5521contain data which looks like a keyword (@pxref{Keyword 5522substitution}), so keyword expansion must be turned 5523off. 5524 5525@c FIXME: the third is that one can't do merges with 5526@c binary files. xref to Multiple Developers and the 5527@c reserved checkout issues. 5528 5529The @samp{-kb} option available with some @sc{cvs} 5530commands insures that neither line ending conversion 5531nor keyword expansion will be done. 5532 5533Here is an example of how you can create a new file 5534using the @samp{-kb} flag: 5535 5536@example 5537$ echo '$@i{}Id$' > kotest 5538$ cvs add -kb -m"A test file" kotest 5539$ cvs ci -m"First checkin; contains a keyword" kotest 5540@end example 5541 5542If a file accidentally gets added without @samp{-kb}, 5543one can use the @code{cvs admin} command to recover. 5544For example: 5545 5546@example 5547$ echo '$@i{}Id$' > kotest 5548$ cvs add -m"A test file" kotest 5549$ cvs ci -m"First checkin; contains a keyword" kotest 5550$ cvs admin -kb kotest 5551$ cvs update -A kotest 5552# @r{For non-unix systems:} 5553# @r{Copy in a good copy of the file from outside CVS} 5554$ cvs commit -m "make it binary" kotest 5555@end example 5556 5557@c Trying to describe this for both unix and non-unix 5558@c in the same description is very confusing. Might 5559@c want to split the two, or just ditch the unix "shortcut" 5560@c (unixheads don't do much with binary files, anyway). 5561@c This used to say "(Try the above example, and do a 5562@c @code{cat kotest} after every command)". But that 5563@c only really makes sense for the unix case. 5564When you check in the file @file{kotest} the file is 5565not preserved as a binary file, because you did not 5566check it in as a binary file. The @code{cvs 5567admin -kb} command sets the default keyword 5568substitution method for this file, but it does not 5569alter the working copy of the file that you have. If you need to 5570cope with line endings (that is, you are using 5571@sc{cvs} on a non-unix system), then you need to 5572check in a new copy of the file, as shown by the 5573@code{cvs commit} command above. 5574On unix, the @code{cvs update -A} command suffices. 5575@c FIXME: should also describe what the *other users* 5576@c need to do, if they have checked out copies which 5577@c have been corrupted by lack of -kb. I think maybe 5578@c "cvs update -kb" or "cvs 5579@c update -A" would suffice, although the user who 5580@c reported this suggested removing the file, manually 5581@c removing it from CVS/Entries, and then "cvs update" 5582(Note that you can use @code{cvs log} to determine the default keyword 5583substitution method for a file and @code{cvs status} to determine 5584the keyword substitution method for a working copy.) 5585 5586However, in using @code{cvs admin -k} to change the 5587keyword expansion, be aware that the keyword expansion 5588mode is not version controlled. This means that, for 5589example, that if you have a text file in old releases, 5590and a binary file with the same name in new releases, 5591@sc{cvs} provides no way to check out the file in text 5592or binary mode depending on what version you are 5593checking out. There is no good workaround for this 5594problem. 5595 5596You can also set a default for whether @code{cvs add} 5597and @code{cvs import} treat a file as binary based on 5598its name; for example you could say that files who 5599names end in @samp{.exe} are binary. @xref{Wrappers}. 5600There is currently no way to have @sc{cvs} detect 5601whether a file is binary based on its contents. The 5602main difficulty with designing such a feature is that 5603it is not clear how to distinguish between binary and 5604non-binary files, and the rules to apply would vary 5605considerably with the operating system. 5606@c For example, it would be good on MS-DOS-family OSes 5607@c for anything containing ^Z to be binary. Having 5608@c characters with the 8th bit set imply binary is almost 5609@c surely a bad idea in the context of ISO-8859-* and 5610@c other such character sets. On VMS or the Mac, we 5611@c could use the OS's file typing. This is a 5612@c commonly-desired feature, and something of this sort 5613@c may make sense. But there are a lot of pitfalls here. 5614@c 5615@c Another, probably better, way to tell is to read the 5616@c file in text mode, write it to a temp file in text 5617@c mode, and then do a binary mode compare of the two 5618@c files. If they differ, it is a binary file. This 5619@c might have problems on VMS (or some other system 5620@c with several different text modes), but in general 5621@c should be relatively portable. The only other 5622@c downside I can think of is that it would be fairly 5623@c slow, but that is perhaps a small price to pay for 5624@c not having your files corrupted. Another issue is 5625@c what happens if you import a text file with bare 5626@c linefeeds on Windows. Such files will show up on 5627@c Windows sometimes (I think some native windows 5628@c programs even write them, on occasion). Perhaps it 5629@c is reasonable to treat such files as binary; after 5630@c all it is something of a presumption to assume that 5631@c the user would want the linefeeds converted to CRLF. 5632 5633@c --------------------------------------------------------------------- 5634@node Multiple developers 5635@chapter Multiple developers 5636@cindex Multiple developers 5637@cindex Team of developers 5638@cindex File locking 5639@cindex Locking files 5640@cindex Working copy 5641@cindex Reserved checkouts 5642@cindex Unreserved checkouts 5643@cindex RCS-style locking 5644 5645When more than one person works on a software project 5646things often get complicated. Often, two people try to 5647edit the same file simultaneously. One solution, known 5648as @dfn{file locking} or @dfn{reserved checkouts}, is 5649to allow only one person to edit each file at a time. 5650This is the only solution with some version control 5651systems, including @sc{rcs} and @sc{sccs}. Currently 5652the usual way to get reserved checkouts with @sc{cvs} 5653is the @code{cvs admin -l} command (@pxref{admin 5654options}). This is not as nicely integrated into 5655@sc{cvs} as the watch features, described below, but it 5656seems that most people with a need for reserved 5657checkouts find it adequate. 5658@c Or "find it better than worrying about implementing 5659@c nicely integrated reserved checkouts" or ...? 5660It also may be possible to use the watches 5661features described below, together with suitable 5662procedures (not enforced by software), to avoid having 5663two people edit at the same time. 5664 5665@c Our unreserved checkout model might not 5666@c be quite the same as others. For example, I 5667@c think that some systems will tend to create a branch 5668@c in the case where CVS prints "up-to-date check failed". 5669@c It isn't clear to me whether we should try to 5670@c explore these subtleties; it could easily just 5671@c confuse people. 5672The default model with @sc{cvs} is known as 5673@dfn{unreserved checkouts}. In this model, developers 5674can edit their own @dfn{working copy} of a file 5675simultaneously. The first person that commits his 5676changes has no automatic way of knowing that another 5677has started to edit it. Others will get an error 5678message when they try to commit the file. They must 5679then use @sc{cvs} commands to bring their working copy 5680up to date with the repository revision. This process 5681is almost automatic. 5682 5683@c FIXME? should probably use the word "watch" here, to 5684@c tie this into the text below and above. 5685@sc{cvs} also supports mechanisms which facilitate 5686various kinds of communication, without actually 5687enforcing rules like reserved checkouts do. 5688 5689The rest of this chapter describes how these various 5690models work, and some of the issues involved in 5691choosing between them. 5692 5693 5694@menu 5695* File status:: A file can be in several states 5696* Updating a file:: Bringing a file up-to-date 5697* Conflicts example:: An informative example 5698* Informing others:: To cooperate you must inform 5699* Concurrency:: Simultaneous repository access 5700* Watches:: Mechanisms to track who is editing files 5701* Choosing a model:: Reserved or unreserved checkouts? 5702@end menu 5703 5704@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5705@node File status 5706@section File status 5707@cindex File status 5708@cindex Status of a file 5709 5710@c Shouldn't this start with an example or something, 5711@c introducing the unreserved checkout model? Before we 5712@c dive into listing states? 5713Based on what operations you have performed on a 5714checked out file, and what operations others have 5715performed to that file in the repository, one can 5716classify a file in a number of states. The states, as 5717reported by the @code{status} command, are: 5718 5719@c The order of items is chosen to group logically 5720@c similar outputs together. 5721@c People who want alphabetical can use the index... 5722@table @asis 5723@cindex Up-to-date 5724@item Up-to-date 5725The file is identical with the latest revision in the 5726repository for the branch in use. 5727@c FIXME: should we clarify "in use"? The answer is 5728@c sticky tags, and trying to distinguish branch sticky 5729@c tags from non-branch sticky tags seems rather awkward 5730@c here. 5731@c FIXME: What happens with non-branch sticky tags? Is 5732@c a stuck file "Up-to-date" or "Needs checkout" or what? 5733 5734@item Locally Modified 5735@cindex Locally Modified 5736You have edited the file, and not yet committed your changes. 5737 5738@item Locally Added 5739@cindex Locally Added 5740You have added the file with @code{add}, and not yet 5741committed your changes. 5742@c There are many cases involving the file being 5743@c added/removed/modified in the working directory, and 5744@c added/removed/modified in the repository, which we 5745@c don't try to describe here. I'm not sure that "cvs 5746@c status" produces a non-confusing output in most of 5747@c those cases. 5748 5749@item Locally Removed 5750@cindex Locally Removed 5751You have removed the file with @code{remove}, and not yet 5752committed your changes. 5753 5754@item Needs Checkout 5755@cindex Needs Checkout 5756Someone else has committed a newer revision to the 5757repository. The name is slightly misleading; you will 5758ordinarily use @code{update} rather than 5759@code{checkout} to get that newer revision. 5760 5761@item Needs Patch 5762@cindex Needs Patch 5763@c See also newb-123j0 in sanity.sh (although that case 5764@c should probably be changed rather than documented). 5765Like Needs Checkout, but the @sc{cvs} server will send 5766a patch rather than the entire file. Sending a patch or 5767sending an entire file accomplishes the same thing. 5768 5769@item Needs Merge 5770@cindex Needs Merge 5771Someone else has committed a newer revision to the repository, and you 5772have also made modifications to the file. 5773 5774@item Unresolved Conflict 5775@cindex Unresolved Conflict 5776@c FIXCVS - This file status needs to be changed to some more informative 5777@c text that distinguishes it more clearly from each of the Locally Added, 5778@c File had conflicts on merge, and Unknown status types, but an exact and 5779@c succinct wording escapes me at the moment. 5780A file with the same name as this new file has been added to the repository 5781from a second workspace. This file will need to be moved out of the way 5782to allow an @code{update} to complete. 5783 5784@item File had conflicts on merge 5785@cindex File had conflicts on merge 5786@c is it worth saying that this message was "Unresolved 5787@c Conflict" in CVS 1.9 and earlier? I'm inclined to 5788@c think that is unnecessarily confusing to new users. 5789This is like Locally Modified, except that a previous 5790@code{update} command gave a conflict. If you have not 5791already done so, you need to 5792resolve the conflict as described in @ref{Conflicts example}. 5793 5794@item Unknown 5795@cindex Unknown 5796@sc{cvs} doesn't know anything about this file. For 5797example, you have created a new file and have not run 5798@code{add}. 5799@c 5800@c "Entry Invalid" and "Classify Error" are also in the 5801@c status.c. The latter definitely indicates a CVS bug 5802@c (should it be worded more like "internal error" so 5803@c people submit bug reports if they see it?). The former 5804@c I'm not as sure; I haven't tracked down whether/when it 5805@c appears in "cvs status" output. 5806 5807@end table 5808 5809To help clarify the file status, @code{status} also 5810reports the @code{Working revision} which is the 5811revision that the file in the working directory derives 5812from, and the @code{Repository revision} which is the 5813latest revision in the repository for the branch in 5814use. 5815@c FIXME: should we clarify "in use"? The answer is 5816@c sticky tags, and trying to distinguish branch sticky 5817@c tags from non-branch sticky tags seems rather awkward 5818@c here. 5819@c FIXME: What happens with non-branch sticky tags? 5820@c What is the Repository Revision there? See the 5821@c comment at vn_rcs in cvs.h, which is kind of 5822@c confused--we really need to document better what this 5823@c field contains. 5824@c Q: Should we document "New file!" and other such 5825@c outputs or are they self-explanatory? 5826@c FIXME: what about the date to the right of "Working 5827@c revision"? It doesn't appear with client/server and 5828@c seems unnecessary (redundant with "ls -l") so 5829@c perhaps it should be removed for non-client/server too? 5830@c FIXME: Need some examples. 5831@c FIXME: Working revision can also be something like 5832@c "-1.3" for a locally removed file. Not at all 5833@c self-explanatory (and it is possible that CVS should 5834@c be changed rather than documenting this). 5835 5836@c Would be nice to have an @example showing output 5837@c from cvs status, with comments showing the xref 5838@c where each part of the output is described. This 5839@c might fit in nicely if it is desirable to split this 5840@c node in two; one to introduce "cvs status" and one 5841@c to list each of the states. 5842The options to @code{status} are listed in 5843@ref{Invoking CVS}. For information on its @code{Sticky tag} 5844and @code{Sticky date} output, see @ref{Sticky tags}. 5845For information on its @code{Sticky options} output, 5846see the @samp{-k} option in @ref{update options}. 5847 5848You can think of the @code{status} and @code{update} 5849commands as somewhat complementary. You use 5850@code{update} to bring your files up to date, and you 5851can use @code{status} to give you some idea of what an 5852@code{update} would do (of course, the state of the 5853repository might change before you actually run 5854@code{update}). In fact, if you want a command to 5855display file status in a more brief format than is 5856displayed by the @code{status} command, you can invoke 5857 5858@cindex update, to display file status 5859@example 5860$ cvs -n -q update 5861@end example 5862 5863The @samp{-n} option means to not actually do the 5864update, but merely to display statuses; the @samp{-q} 5865option avoids printing the name of each directory. For 5866more information on the @code{update} command, and 5867these options, see @ref{Invoking CVS}. 5868 5869@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5870@node Updating a file 5871@section Bringing a file up to date 5872@cindex Bringing a file up to date 5873@cindex Updating a file 5874@cindex Merging a file 5875@cindex Update, introduction 5876 5877When you want to update or merge a file, use the @code{update} 5878command. For files that are not up to date this is roughly equivalent 5879to a @code{checkout} command: the newest revision of the file is 5880extracted from the repository and put in your working directory. 5881 5882Your modifications to a file are never lost when you 5883use @code{update}. If no newer revision exists, 5884running @code{update} has no effect. If you have 5885edited the file, and a newer revision is available, 5886@sc{cvs} will merge all changes into your working copy. 5887 5888For instance, imagine that you checked out revision 1.4 and started 5889editing it. In the meantime someone else committed revision 1.5, and 5890shortly after that revision 1.6. If you run @code{update} on the file 5891now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 5892your file. 5893 5894@cindex Overlap 5895If any of the changes between 1.4 and 1.6 were made too 5896close to any of the changes you have made, an 5897@dfn{overlap} occurs. In such cases a warning is 5898printed, and the resulting file includes both 5899versions of the lines that overlap, delimited by 5900special markers. 5901@xref{update}, for a complete description of the 5902@code{update} command. 5903 5904@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5905@node Conflicts example 5906@section Conflicts example 5907@cindex Merge, an example 5908@cindex Example of merge 5909@cindex driver.c (merge example) 5910 5911Suppose revision 1.4 of @file{driver.c} contains this: 5912 5913@example 5914#include <stdio.h> 5915 5916void main() 5917@{ 5918 parse(); 5919 if (nerr == 0) 5920 gencode(); 5921 else 5922 fprintf(stderr, "No code generated.\n"); 5923 exit(nerr == 0 ? 0 : 1); 5924@} 5925@end example 5926 5927@noindent 5928Revision 1.6 of @file{driver.c} contains this: 5929 5930@example 5931#include <stdio.h> 5932 5933int main(int argc, 5934 char **argv) 5935@{ 5936 parse(); 5937 if (argc != 1) 5938 @{ 5939 fprintf(stderr, "tc: No args expected.\n"); 5940 exit(1); 5941 @} 5942 if (nerr == 0) 5943 gencode(); 5944 else 5945 fprintf(stderr, "No code generated.\n"); 5946 exit(!!nerr); 5947@} 5948@end example 5949 5950@noindent 5951Your working copy of @file{driver.c}, based on revision 59521.4, contains this before you run @samp{cvs update}: 5953@c -- Really include "cvs"? 5954 5955@example 5956#include <stdlib.h> 5957#include <stdio.h> 5958 5959void main() 5960@{ 5961 init_scanner(); 5962 parse(); 5963 if (nerr == 0) 5964 gencode(); 5965 else 5966 fprintf(stderr, "No code generated.\n"); 5967 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 5968@} 5969@end example 5970 5971@noindent 5972You run @samp{cvs update}: 5973@c -- Really include "cvs"? 5974 5975@example 5976$ cvs update driver.c 5977RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 5978retrieving revision 1.4 5979retrieving revision 1.6 5980Merging differences between 1.4 and 1.6 into driver.c 5981rcsmerge warning: overlaps during merge 5982cvs update: conflicts found in driver.c 5983C driver.c 5984@end example 5985 5986@noindent 5987@cindex Conflicts (merge example) 5988@sc{cvs} tells you that there were some conflicts. 5989Your original working file is saved unmodified in 5990@file{.#driver.c.1.4}. The new version of 5991@file{driver.c} contains this: 5992 5993@example 5994#include <stdlib.h> 5995#include <stdio.h> 5996 5997int main(int argc, 5998 char **argv) 5999@{ 6000 init_scanner(); 6001 parse(); 6002 if (argc != 1) 6003 @{ 6004 fprintf(stderr, "tc: No args expected.\n"); 6005 exit(1); 6006 @} 6007 if (nerr == 0) 6008 gencode(); 6009 else 6010 fprintf(stderr, "No code generated.\n"); 6011@asis{}<<<<<<< driver.c 6012 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6013@asis{}======= 6014 exit(!!nerr); 6015@asis{}>>>>>>> 1.6 6016@} 6017@end example 6018 6019@noindent 6020@cindex Markers, conflict 6021@cindex Conflict markers 6022@cindex <<<<<<< 6023@cindex >>>>>>> 6024@cindex ======= 6025 6026Note how all non-overlapping modifications are incorporated in your working 6027copy, and that the overlapping section is clearly marked with 6028@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 6029 6030@cindex Resolving a conflict 6031@cindex Conflict resolution 6032You resolve the conflict by editing the file, removing the markers and 6033the erroneous line. Suppose you end up with this file: 6034@c -- Add xref to the pcl-cvs manual when it talks 6035@c -- about this. 6036@example 6037#include <stdlib.h> 6038#include <stdio.h> 6039 6040int main(int argc, 6041 char **argv) 6042@{ 6043 init_scanner(); 6044 parse(); 6045 if (argc != 1) 6046 @{ 6047 fprintf(stderr, "tc: No args expected.\n"); 6048 exit(1); 6049 @} 6050 if (nerr == 0) 6051 gencode(); 6052 else 6053 fprintf(stderr, "No code generated.\n"); 6054 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6055@} 6056@end example 6057 6058@noindent 6059You can now go ahead and commit this as revision 1.7. 6060 6061@example 6062$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 6063Checking in driver.c; 6064/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 6065new revision: 1.7; previous revision: 1.6 6066done 6067@end example 6068 6069For your protection, @sc{cvs} will refuse to check in a 6070file if a conflict occurred and you have not resolved 6071the conflict. Currently to resolve a conflict, you 6072must change the timestamp on the file. In previous 6073versions of @sc{cvs}, you also needed to 6074insure that the file contains no conflict markers. 6075Because 6076your file may legitimately contain conflict markers (that 6077is, occurrences of @samp{>>>>>>> } at the start of a 6078line that don't mark a conflict), the current 6079version of @sc{cvs} will print a warning and proceed to 6080check in the file. 6081@c The old behavior was really icky; the only way out 6082@c was to start hacking on 6083@c the @code{CVS/Entries} file or other such workarounds. 6084@c 6085@c If the timestamp thing isn't considered nice enough, 6086@c maybe there should be a "cvs resolved" command 6087@c which clears the conflict indication. For a nice user 6088@c interface, this should be invoked by an interactive 6089@c merge tool like emerge rather than by the user 6090@c directly--such a tool can verify that the user has 6091@c really dealt with each conflict. 6092 6093@cindex emerge 6094If you use release 1.04 or later of pcl-cvs (a @sc{gnu} 6095Emacs front-end for @sc{cvs}) you can use an Emacs 6096package called emerge to help you resolve conflicts. 6097See the documentation for pcl-cvs. 6098 6099@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6100@node Informing others 6101@section Informing others about commits 6102@cindex Informing others 6103@cindex Spreading information 6104@cindex Mail, automatic mail on commit 6105 6106It is often useful to inform others when you commit a 6107new revision of a file. The @samp{-i} option of the 6108@file{modules} file, or the @file{loginfo} file, can be 6109used to automate this process. @xref{modules}. 6110@xref{loginfo}. You can use these features of @sc{cvs} 6111to, for instance, instruct @sc{cvs} to mail a 6112message to all developers, or post a message to a local 6113newsgroup. 6114@c -- More text would be nice here. 6115 6116@node Concurrency 6117@section Several developers simultaneously attempting to run CVS 6118 6119@cindex Locks, cvs, introduction 6120@c For a discussion of *why* CVS creates locks, see 6121@c the comment at the start of src/lock.c 6122If several developers try to run @sc{cvs} at the same 6123time, one may get the following message: 6124 6125@example 6126[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 6127@end example 6128 6129@cindex #cvs.rfl, removing 6130@cindex #cvs.wfl, removing 6131@cindex #cvs.lock, removing 6132@sc{cvs} will try again every 30 seconds, and either 6133continue with the operation or print the message again, 6134if it still needs to wait. If a lock seems to stick 6135around for an undue amount of time, find the person 6136holding the lock and ask them about the cvs command 6137they are running. If they aren't running a cvs 6138command, look in the repository directory mentioned in 6139the message and remove files which they own whose names 6140start with @file{#cvs.rfl}, 6141@file{#cvs.wfl}, or @file{#cvs.lock}. 6142 6143Note that these locks are to protect @sc{cvs}'s 6144internal data structures and have no relationship to 6145the word @dfn{lock} in the sense used by 6146@sc{rcs}---which refers to reserved checkouts 6147(@pxref{Multiple developers}). 6148 6149Any number of people can be reading from a given 6150repository at a time; only when someone is writing do 6151the locks prevent other people from reading or writing. 6152 6153@cindex Atomic transactions, lack of 6154@cindex Transactions, atomic, lack of 6155@c the following talks about what one might call commit/update 6156@c atomicity. 6157@c Probably also should say something about 6158@c commit/commit atomicity, that is, "An update will 6159@c not get partial versions of more than one commit". 6160@c CVS currently has this property and I guess we can 6161@c make it a documented feature. 6162@c For example one person commits 6163@c a/one.c and b/four.c and another commits a/two.c and 6164@c b/three.c. Then an update cannot get the new a/one.c 6165@c and a/two.c and the old b/four.c and b/three.c. 6166One might hope for the following property: 6167 6168@quotation 6169If someone commits some changes in one cvs command, 6170then an update by someone else will either get all the 6171changes, or none of them. 6172@end quotation 6173 6174@noindent 6175but @sc{cvs} does @emph{not} have this property. For 6176example, given the files 6177 6178@example 6179a/one.c 6180a/two.c 6181b/three.c 6182b/four.c 6183@end example 6184 6185@noindent 6186if someone runs 6187 6188@example 6189cvs ci a/two.c b/three.c 6190@end example 6191 6192@noindent 6193and someone else runs @code{cvs update} at the same 6194time, the person running @code{update} might get only 6195the change to @file{b/three.c} and not the change to 6196@file{a/two.c}. 6197 6198@node Watches 6199@section Mechanisms to track who is editing files 6200@cindex Watches 6201 6202For many groups, use of @sc{cvs} in its default mode is 6203perfectly satisfactory. Users may sometimes go to 6204check in a modification only to find that another 6205modification has intervened, but they deal with it and 6206proceed with their check in. Other groups prefer to be 6207able to know who is editing what files, so that if two 6208people try to edit the same file they can choose to 6209talk about who is doing what when rather than be 6210surprised at check in time. The features in this 6211section allow such coordination, while retaining the 6212ability of two developers to edit the same file at the 6213same time. 6214 6215@c Some people might ask why CVS does not enforce the 6216@c rule on chmod, by requiring a cvs edit before a cvs 6217@c commit. The main reason is that it could always be 6218@c circumvented--one could edit the file, and 6219@c then when ready to check it in, do the cvs edit and put 6220@c in the new contents and do the cvs commit. One 6221@c implementation note: if we _do_ want to have cvs commit 6222@c require a cvs edit, we should store the state on 6223@c whether the cvs edit has occurred in the working 6224@c directory, rather than having the server try to keep 6225@c track of what working directories exist. 6226@c FIXME: should the above discussion be part of the 6227@c manual proper, somewhere, not just in a comment? 6228For maximum benefit developers should use @code{cvs 6229edit} (not @code{chmod}) to make files read-write to 6230edit them, and @code{cvs release} (not @code{rm}) to 6231discard a working directory which is no longer in use, 6232but @sc{cvs} is not able to enforce this behavior. 6233 6234@c I'm a little dissatisfied with this presentation, 6235@c because "watch on"/"edit"/"editors" are one set of 6236@c functionality, and "watch add"/"watchers" is another 6237@c which is somewhat orthogonal even though they interact in 6238@c various ways. But I think it might be 6239@c confusing to describe them separately (e.g. "watch 6240@c add" with loginfo). I don't know. 6241 6242@menu 6243* Setting a watch:: Telling CVS to watch certain files 6244* Getting Notified:: Telling CVS to notify you 6245* Editing files:: How to edit a file which is being watched 6246* Watch information:: Information about who is watching and editing 6247* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 6248@end menu 6249 6250@node Setting a watch 6251@subsection Telling CVS to watch certain files 6252 6253To enable the watch features, you first specify that 6254certain files are to be watched. 6255 6256@cindex watch on (subcommand) 6257@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 6258 6259@cindex Read-only files, and watches 6260Specify that developers should run @code{cvs edit} 6261before editing @var{files}. @sc{cvs} will create working 6262copies of @var{files} read-only, to remind developers 6263to run the @code{cvs edit} command before working on 6264them. 6265 6266If @var{files} includes the name of a directory, @sc{cvs} 6267arranges to watch all files added to the corresponding 6268repository directory, and sets a default for files 6269added in the future; this allows the user to set 6270notification policies on a per-directory basis. The 6271contents of the directory are processed recursively, 6272unless the @code{-l} option is given. 6273The @code{-R} option can be used to force recursion if the @code{-l} 6274option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 6275 6276If @var{files} is omitted, it defaults to the current directory. 6277 6278@cindex watch off (subcommand) 6279@end deffn 6280 6281@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 6282 6283Do not create @var{files} read-only on checkout; thus, 6284developers will not be reminded to use @code{cvs edit} 6285and @code{cvs unedit}. 6286 6287The @var{files} and options are processed as for @code{cvs 6288watch on}. 6289 6290@end deffn 6291 6292@node Getting Notified 6293@subsection Telling CVS to notify you 6294 6295You can tell @sc{cvs} that you want to receive 6296notifications about various actions taken on a file. 6297You can do this without using @code{cvs watch on} for 6298the file, but generally you will want to use @code{cvs 6299watch on}, to remind developers to use the @code{cvs edit} 6300command. 6301 6302@cindex watch add (subcommand) 6303@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6304 6305Add the current user to the list of people to receive notification of 6306work done on @var{files}. 6307 6308The @code{-a} option specifies what kinds of events @sc{cvs} should notify 6309the user about. @var{action} is one of the following: 6310 6311@table @code 6312 6313@item edit 6314Another user has applied the @code{cvs edit} command (described 6315below) to a watched file. 6316 6317@item commit 6318Another user has committed changes to one of the named @var{files}. 6319 6320@item unedit 6321Another user has abandoned editing a file (other than by committing changes). 6322They can do this in several ways, by: 6323 6324@itemize @bullet 6325 6326@item 6327applying the @code{cvs unedit} command (described below) to the file 6328 6329@item 6330applying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6331(or recursively to a directory more than one level up) 6332 6333@item 6334deleting the file and allowing @code{cvs update} to recreate it 6335 6336@end itemize 6337 6338@item all 6339All of the above. 6340 6341@item none 6342None of the above. (This is useful with @code{cvs edit}, 6343described below.) 6344 6345@end table 6346 6347The @code{-a} option may appear more than once, or not at all. If 6348omitted, the action defaults to @code{all}. 6349 6350The @var{files} and options are processed as for 6351@code{cvs watch on}. 6352 6353@end deffn 6354 6355 6356@cindex watch remove (subcommand) 6357@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6358 6359Remove a notification request established using @code{cvs watch add}; 6360the arguments are the same. If the @code{-a} option is present, only 6361watches for the specified actions are removed. 6362 6363@end deffn 6364 6365@cindex notify (admin file) 6366When the conditions exist for notification, @sc{cvs} 6367calls the @file{notify} administrative file. Edit 6368@file{notify} as one edits the other administrative 6369files (@pxref{Intro administrative files}). This 6370file follows the usual conventions for administrative 6371files (@pxref{syntax}), where each line is a regular 6372expression followed by a command to execute. The 6373command should contain a single occurrence of @samp{%s} 6374which will be replaced by the user to notify; the rest 6375of the information regarding the notification will be 6376supplied to the command on standard input. The 6377standard thing to put in the @code{notify} file is the 6378single line: 6379 6380@example 6381ALL mail %s -s "CVS notification" 6382@end example 6383 6384@noindent 6385This causes users to be notified by electronic mail. 6386@c FIXME: should it be this hard to set up this 6387@c behavior (and the result when one fails to do so, 6388@c silent failure to notify, so non-obvious)? Should 6389@c CVS give a warning if no line in notify matches (and 6390@c document the use of "DEFAULT :" for the case where 6391@c skipping the notification is indeed desired)? 6392 6393@cindex users (admin file) 6394Note that if you set this up in the straightforward 6395way, users receive notifications on the server machine. 6396One could of course write a @file{notify} script which 6397directed notifications elsewhere, but to make this 6398easy, @sc{cvs} allows you to associate a notification 6399address for each user. To do so create a file 6400@file{users} in @file{CVSROOT} with a line for each 6401user in the format @var{user}:@var{value}. Then 6402instead of passing the name of the user to be notified 6403to @file{notify}, @sc{cvs} will pass the @var{value} 6404(normally an email address on some other machine). 6405 6406@sc{cvs} does not notify you for your own changes. 6407Currently this check is done based on whether the user 6408name of the person taking the action which triggers 6409notification matches the user name of the person 6410getting notification. In fact, in general, the watches 6411features only track one edit by each user. It probably 6412would be more useful if watches tracked each working 6413directory separately, so this behavior might be worth 6414changing. 6415@c "behavior might be worth changing" is an effort to 6416@c point to future directions while also not promising 6417@c that "they" (as in "why don't they fix CVS to....") 6418@c will do this. 6419@c one implementation issue is identifying whether a 6420@c working directory is same or different. Comparing 6421@c pathnames/hostnames is hopeless, but having the server 6422@c supply a serial number which the client stores in the 6423@c CVS directory as a magic cookie should work. 6424 6425@node Editing files 6426@subsection How to edit a file which is being watched 6427 6428@cindex Checkout, as term for getting ready to edit 6429Since a file which is being watched is checked out 6430read-only, you cannot simply edit it. To make it 6431read-write, and inform others that you are planning to 6432edit it, use the @code{cvs edit} command. Some systems 6433call this a @dfn{checkout}, but @sc{cvs} uses that term 6434for obtaining a copy of the sources (@pxref{Getting the 6435source}), an operation which those systems call a 6436@dfn{get} or a @dfn{fetch}. 6437@c Issue to think about: should we transition CVS 6438@c towards the "get" terminology? "cvs get" is already a 6439@c synonym for "cvs checkout" and that section of the 6440@c manual refers to "Getting the source". If this is 6441@c done, needs to be done gingerly (for example, we should 6442@c still accept "checkout" in .cvsrc files indefinitely 6443@c even if the CVS's messages are changed from "cvs checkout: " 6444@c to "cvs get: "). 6445@c There is a concern about whether "get" is not as 6446@c good for novices because it is a more general term 6447@c than "checkout" (and thus arguably harder to assign 6448@c a technical meaning for). 6449 6450@cindex edit (subcommand) 6451@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6452 6453Prepare to edit the working files @var{files}. @sc{cvs} makes the 6454@var{files} read-write, and notifies users who have requested 6455@code{edit} notification for any of @var{files}. 6456 6457The @code{cvs edit} command accepts the same options as the 6458@code{cvs watch add} command, and establishes a temporary watch for the 6459user on @var{files}; @sc{cvs} will remove the watch when @var{files} are 6460@code{unedit}ed or @code{commit}ted. If the user does not wish to 6461receive notifications, she should specify @code{-a none}. 6462 6463The @var{files} and the options are processed as for the @code{cvs 6464watch} commands. 6465 6466 6467@end deffn 6468 6469Normally when you are done with a set of changes, you 6470use the @code{cvs commit} command, which checks in your 6471changes and returns the watched files to their usual 6472read-only state. But if you instead decide to abandon 6473your changes, or not to make any changes, you can use 6474the @code{cvs unedit} command. 6475 6476@cindex unedit (subcommand) 6477@cindex Abandoning work 6478@cindex Reverting to repository version 6479@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 6480 6481Abandon work on the working files @var{files}, and revert them to the 6482repository versions on which they are based. @sc{cvs} makes those 6483@var{files} read-only for which users have requested notification using 6484@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 6485notification for any of @var{files}. 6486 6487The @var{files} and options are processed as for the 6488@code{cvs watch} commands. 6489 6490If watches are not in use, the @code{unedit} command 6491probably does not work, and the way to revert to the 6492repository version is with the command @code{cvs update -C file} 6493(@pxref{update}). 6494The meaning is 6495not precisely the same; the latter may also 6496bring in some changes which have been made in the 6497repository since the last time you updated. 6498@c It would be a useful enhancement to CVS to make 6499@c unedit work in the non-watch case as well. 6500@end deffn 6501 6502When using client/server @sc{cvs}, you can use the 6503@code{cvs edit} and @code{cvs unedit} commands even if 6504@sc{cvs} is unable to successfully communicate with the 6505server; the notifications will be sent upon the next 6506successful @sc{cvs} command. 6507 6508@node Watch information 6509@subsection Information about who is watching and editing 6510 6511@cindex watchers (subcommand) 6512@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 6513 6514List the users currently watching changes to @var{files}. The report 6515includes the files being watched, and the mail address of each watcher. 6516 6517The @var{files} and options are processed as for the 6518@code{cvs watch} commands. 6519 6520@end deffn 6521 6522 6523@cindex editors (subcommand) 6524@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 6525 6526List the users currently working on @var{files}. The report 6527includes the mail address of each user, the time when the user began 6528working with the file, and the host and path of the working directory 6529containing the file. 6530 6531The @var{files} and options are processed as for the 6532@code{cvs watch} commands. 6533 6534@end deffn 6535 6536@node Watches Compatibility 6537@subsection Using watches with old versions of CVS 6538 6539@cindex CVS 1.6, and watches 6540If you use the watch features on a repository, it 6541creates @file{CVS} directories in the repository and 6542stores the information about watches in that directory. 6543If you attempt to use @sc{cvs} 1.6 or earlier with the 6544repository, you get an error message such as the 6545following (all on one line): 6546 6547@example 6548cvs update: cannot open CVS/Entries for reading: 6549No such file or directory 6550@end example 6551 6552@noindent 6553and your operation will likely be aborted. To use the 6554watch features, you must upgrade all copies of @sc{cvs} 6555which use that repository in local or server mode. If 6556you cannot upgrade, use the @code{watch off} and 6557@code{watch remove} commands to remove all watches, and 6558that will restore the repository to a state which 6559@sc{cvs} 1.6 can cope with. 6560 6561@node Choosing a model 6562@section Choosing between reserved or unreserved checkouts 6563@cindex Choosing, reserved or unreserved checkouts 6564 6565Reserved and unreserved checkouts each have pros and 6566cons. Let it be said that a lot of this is a matter of 6567opinion or what works given different groups' working 6568styles, but here is a brief description of some of the 6569issues. There are many ways to organize a team of 6570developers. @sc{cvs} does not try to enforce a certain 6571organization. It is a tool that can be used in several 6572ways. 6573 6574Reserved checkouts can be very counter-productive. If 6575two persons want to edit different parts of a file, 6576there may be no reason to prevent either of them from 6577doing so. Also, it is common for someone to take out a 6578lock on a file, because they are planning to edit it, 6579but then forget to release the lock. 6580 6581@c "many groups"? specifics? cites to papers on this? 6582@c some way to weasel-word it a bit more so we don't 6583@c need facts :-)? 6584People, especially people who are familiar with 6585reserved checkouts, often wonder how often conflicts 6586occur if unreserved checkouts are used, and how 6587difficult they are to resolve. The experience with 6588many groups is that they occur rarely and usually are 6589relatively straightforward to resolve. 6590 6591The rarity of serious conflicts may be surprising, until one realizes 6592that they occur only when two developers disagree on the proper design 6593for a given section of code; such a disagreement suggests that the 6594team has not been communicating properly in the first place. In order 6595to collaborate under @emph{any} source management regimen, developers 6596must agree on the general design of the system; given this agreement, 6597overlapping changes are usually straightforward to merge. 6598 6599In some cases unreserved checkouts are clearly 6600inappropriate. If no merge tool exists for the kind of 6601file you are managing (for example word processor files 6602or files edited by Computer Aided Design programs), and 6603it is not desirable to change to a program which uses a 6604mergeable data format, then resolving conflicts is 6605going to be unpleasant enough that you generally will 6606be better off to simply avoid the conflicts instead, by 6607using reserved checkouts. 6608 6609The watches features described above in @ref{Watches} 6610can be considered to be an intermediate model between 6611reserved checkouts and unreserved checkouts. When you 6612go to edit a file, it is possible to find out who else 6613is editing it. And rather than having the system 6614simply forbid both people editing the file, it can tell 6615you what the situation is and let you figure out 6616whether it is a problem in that particular case or not. 6617Therefore, for some groups it can be considered the 6618best of both the reserved checkout and unreserved 6619checkout worlds. 6620 6621@c --------------------------------------------------------------------- 6622@node Revision management 6623@chapter Revision management 6624@cindex Revision management 6625 6626@c -- This chapter could be expanded a lot. 6627@c -- Experiences are very welcome! 6628 6629If you have read this far, you probably have a pretty 6630good grasp on what @sc{cvs} can do for you. This 6631chapter talks a little about things that you still have 6632to decide. 6633 6634If you are doing development on your own using @sc{cvs} 6635you could probably skip this chapter. The questions 6636this chapter takes up become more important when more 6637than one person is working in a repository. 6638 6639@menu 6640* When to commit:: Some discussion on the subject 6641@end menu 6642 6643@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6644@node When to commit 6645@section When to commit? 6646@cindex When to commit 6647@cindex Committing, when to 6648@cindex Policy 6649 6650Your group should decide which policy to use regarding 6651commits. Several policies are possible, and as your 6652experience with @sc{cvs} grows you will probably find 6653out what works for you. 6654 6655If you commit files too quickly you might commit files 6656that do not even compile. If your partner updates his 6657working sources to include your buggy file, he will be 6658unable to compile the code. On the other hand, other 6659persons will not be able to benefit from the 6660improvements you make to the code if you commit very 6661seldom, and conflicts will probably be more common. 6662 6663It is common to only commit files after making sure 6664that they can be compiled. Some sites require that the 6665files pass a test suite. Policies like this can be 6666enforced using the commitinfo file 6667(@pxref{commitinfo}), but you should think twice before 6668you enforce such a convention. By making the 6669development environment too controlled it might become 6670too regimented and thus counter-productive to the real 6671goal, which is to get software written. 6672 6673@c --------------------------------------------------------------------- 6674@node Keyword substitution 6675@chapter Keyword substitution 6676@cindex Keyword substitution 6677@cindex Keyword expansion 6678@cindex Identifying files 6679 6680@comment Be careful when editing this chapter. 6681@comment Remember that this file is kept under 6682@comment version control, so we must not accidentally 6683@comment include a valid keyword in the running text. 6684 6685As long as you edit source files inside a working 6686directory you can always find out the state of 6687your files via @samp{cvs status} and @samp{cvs log}. 6688But as soon as you export the files from your 6689development environment it becomes harder to identify 6690which revisions they are. 6691 6692@sc{cvs} can use a mechanism known as @dfn{keyword 6693substitution} (or @dfn{keyword expansion}) to help 6694identifying the files. Embedded strings of the form 6695@code{$@var{keyword}$} and 6696@code{$@var{keyword}:@dots{}$} in a file are replaced 6697with strings of the form 6698@code{$@var{keyword}:@var{value}$} whenever you obtain 6699a new revision of the file. 6700 6701@menu 6702* Keyword list:: Keywords 6703* Using keywords:: Using keywords 6704* Avoiding substitution:: Avoiding substitution 6705* Substitution modes:: Substitution modes 6706* Configuring keyword expansion:: Configuring keyword expansion 6707* Log keyword:: Problems with the $@i{}Log$ keyword. 6708@end menu 6709 6710@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6711@node Keyword list 6712@section Keyword List 6713@cindex Keyword List 6714 6715@c FIXME: need some kind of example here I think, 6716@c perhaps in a 6717@c "Keyword intro" node. The intro in the "Keyword 6718@c substitution" node itself seems OK, but to launch 6719@c into a list of the keywords somehow seems too abrupt. 6720 6721This is a list of the keywords: 6722 6723@table @code 6724@cindex Author keyword 6725@item $@i{}Author$ 6726The login name of the user who checked in the revision. 6727 6728@cindex CVSHeader keyword 6729@item $@i{}CVSHeader 6730A standard header (similar to $@i{}Header$, but with 6731the CVS root stripped off). It contains the relative 6732pathname of the @sc{rcs} file to the CVS root, the 6733revision number, the date (UTC), the author, the state, 6734and the locker (if locked). Files will normally never 6735be locked when you use @sc{cvs}. 6736 6737Note that this keyword has only been recently 6738introduced to @sc{cvs} and may cause problems with 6739existing installations if $@i{}CVSHeader$ is already 6740in the files for a different purpose. This keyword may 6741be excluded using the @code{KeywordExpansion=eCVSHeader} 6742in the @file{CVSROOT/config} file. 6743See @ref{Configuring keyword expansion} for more details. 6744 6745@cindex Date keyword 6746@item $@i{}Date$ 6747The date and time (UTC) the revision was checked in. 6748 6749@cindex Header keyword 6750@item $@i{}Header$ 6751A standard header containing the full pathname of the 6752@sc{rcs} file, the revision number, the date (UTC), the 6753author, the state, and the locker (if locked). Files 6754will normally never be locked when you use @sc{cvs}. 6755 6756@cindex Id keyword 6757@item $@i{}Id$ 6758Same as @code{$@i{}Header$}, except that the @sc{rcs} 6759filename is without a path. 6760 6761@cindex Name keyword 6762@item $@i{}Name$ 6763Tag name used to check out this file. The keyword is 6764expanded only if one checks out with an explicit tag 6765name. For example, when running the command @code{cvs 6766co -r first}, the keyword expands to @samp{Name: first}. 6767 6768@cindex Locker keyword 6769@item $@i{}Locker$ 6770The login name of the user who locked the revision 6771(empty if not locked, which is the normal case unless 6772@code{cvs admin -l} is in use). 6773 6774@cindex Log keyword 6775@item $@i{}Log$ 6776The log message supplied during commit, preceded by a 6777header containing the @sc{rcs} filename, the revision 6778number, the author, and the date (UTC). Existing log 6779messages are @emph{not} replaced. Instead, the new log 6780message is inserted after @code{$@i{}Log:@dots{}$}. 6781Each new line is prefixed with the same string which 6782precedes the @code{$Log} keyword. For example, if the 6783file contains: 6784 6785@example 6786 /* Here is what people have been up to: 6787 * 6788 * $@i{}Log: frob.c,v $ 6789 * Revision 1.1 1997/01/03 14:23:51 joe 6790 * Add the superfrobnicate option 6791 * 6792 */ 6793@end example 6794 6795@noindent 6796then additional lines which are added when expanding 6797the @code{$Log} keyword will be preceded by @samp{ * }. 6798Unlike previous versions of @sc{cvs} and @sc{rcs}, the 6799@dfn{comment leader} from the @sc{rcs} file is not used. 6800The @code{$Log} keyword is useful for 6801accumulating a complete change log in a source file, 6802but for several reasons it can be problematic. 6803@xref{Log keyword}. 6804 6805@cindex RCSfile keyword 6806@item $@i{}RCSfile$ 6807The name of the RCS file without a path. 6808 6809@cindex Revision keyword 6810@item $@i{}Revision$ 6811The revision number assigned to the revision. 6812 6813@cindex Source keyword 6814@item $@i{}Source$ 6815The full pathname of the RCS file. 6816 6817@cindex State keyword 6818@item $@i{}State$ 6819The state assigned to the revision. States can be 6820assigned with @code{cvs admin -s}---see @ref{admin options}. 6821 6822@cindex Local keyword 6823@item Local keyword 6824The @code{LocalKeyword} option in the @file{CVSROOT/config} file 6825may be used to specify a local keyword which is to be 6826used as an alias for one of the other keywords. For 6827example, if the @file{CVSROOT/config} file contains 6828a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a 6829file with the local keyword $@i{}MYBSD$ will be 6830expanded as if it were a $@i{}CVSHeader$ keyword. If 6831the src/frob.c file contained this keyword, it might 6832look something like this: 6833 6834@example 6835 /* 6836 * $@i{}MYBSD: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 6837 */ 6838@end example 6839 6840Many repositories make use of a such a ``local 6841keyword'' feature. An old patch to @sc{cvs} provided 6842the @code{LocalKeyword} feature using a @code{tag=} 6843option and called this the ``custom tag'' or ``local 6844tag'' feature. It was used in conjunction with the 6845what they called the @code{tagexpand=} option. In 6846@sc{cvs} this other option is known as the 6847@code{KeywordExpand} option. 6848See @ref{Configuring keyword expansion} for more 6849details. 6850 6851Examples from popular projects include: 6852$@i{}FreeBSD$, $@i{}NetBSD$, 6853$@i{}OpenBSD$, $@i{}XFree86$, 6854$@i{}Xorg$. 6855 6856The advantage of this is that you can include your 6857local version information in a file using this local 6858keyword without disrupting the upstream version 6859information (which may be a different local keyword or 6860a standard keyword). Allowing bug reports and the like 6861to more properly identify the source of the original 6862bug to the third-party and reducing the number of 6863conflicts that arise during an import of a new version. 6864 6865All keyword expansion except the local keyword may be 6866disabled using the @code{KeywordExpansion} option in 6867the @file{CVSROOT/config} file---see 6868@ref{Configuring keyword expansion} for more details. 6869 6870@end table 6871 6872@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6873@node Using keywords 6874@section Using keywords 6875 6876To include a keyword string you simply include the 6877relevant text string, such as @code{$@i{}Id$}, inside the 6878file, and commit the file. @sc{cvs} will automatically 6879expand the string as part of the commit operation. 6880 6881It is common to embed the @code{$@i{}Id$} string in 6882the source files so that it gets passed through to 6883generated files. For example, if you are managing 6884computer program source code, you might include a 6885variable which is initialized to contain that string. 6886Or some C compilers may provide a @code{#pragma ident} 6887directive. Or a document management system might 6888provide a way to pass a string through to generated 6889files. 6890 6891@c Would be nice to give an example, but doing this in 6892@c portable C is not possible and the problem with 6893@c picking any one language (VMS HELP files, Ada, 6894@c troff, whatever) is that people use CVS for all 6895@c kinds of files. 6896 6897@cindex Ident (shell command) 6898The @code{ident} command (which is part of the @sc{rcs} 6899package) can be used to extract keywords and their 6900values from a file. This can be handy for text files, 6901but it is even more useful for extracting keywords from 6902binary files. 6903 6904@example 6905$ ident samp.c 6906samp.c: 6907 $@i{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 6908$ gcc samp.c 6909$ ident a.out 6910a.out: 6911 $@i{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 6912@end example 6913 6914@cindex What (shell command) 6915S@sc{ccs} is another popular revision control system. 6916It has a command, @code{what}, which is very similar to 6917@code{ident} and used for the same purpose. Many sites 6918without @sc{rcs} have @sc{sccs}. Since @code{what} 6919looks for the character sequence @code{@@(#)} it is 6920easy to include keywords that are detected by either 6921command. Simply prefix the keyword with the 6922magic @sc{sccs} phrase, like this: 6923 6924@example 6925static char *id="@@(#) $@i{}Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 6926@end example 6927 6928@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6929@node Avoiding substitution 6930@section Avoiding substitution 6931 6932Keyword substitution has its disadvantages. Sometimes 6933you might want the literal text string 6934@samp{$@i{}Author$} to appear inside a file without 6935@sc{cvs} interpreting it as a keyword and expanding it 6936into something like @samp{$@i{}Author: ceder $}. 6937 6938There is unfortunately no way to selectively turn off 6939keyword substitution. You can use @samp{-ko} 6940(@pxref{Substitution modes}) to turn off keyword 6941substitution entirely. 6942 6943In many cases you can avoid using keywords in 6944the source, even though they appear in the final 6945product. For example, the source for this manual 6946contains @samp{$@@asis@{@}Author$} whenever the text 6947@samp{$@i{}Author$} should appear. In @code{nroff} 6948and @code{troff} you can embed the null-character 6949@code{\&} inside the keyword for a similar effect. 6950 6951It is also possible to specify an explicit list of 6952keywords to include or exclude using the 6953@code{KeywordExpand} option in the 6954@file{CVSROOT/config} file--see @ref{Configuring keyword expansion} 6955for more details. This feature is intended primarily 6956for use with the @code{LocalKeyword} option--see 6957@ref{Keyword list}. 6958 6959@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6960@node Substitution modes 6961@section Substitution modes 6962@cindex Keyword substitution, changing modes 6963@cindex -k (keyword substitution) 6964@cindex Kflag 6965 6966@c FIXME: This could be made more coherent, by expanding it 6967@c with more examples or something. 6968Each file has a stored default substitution mode, and 6969each working directory copy of a file also has a 6970substitution mode. The former is set by the @samp{-k} 6971option to @code{cvs add} and @code{cvs admin}; the 6972latter is set by the @samp{-k} or @samp{-A} options to @code{cvs 6973checkout} or @code{cvs update}. @code{cvs diff} also 6974has a @samp{-k} option. For some examples, 6975see @ref{Binary files}, and @ref{Merging and keywords}. 6976@c The fact that -A is overloaded to mean both reset 6977@c sticky options and reset sticky tags/dates is 6978@c somewhat questionable. Perhaps there should be 6979@c separate options to reset sticky options (e.g. -k 6980@c A") and tags/dates (someone suggested -r HEAD could 6981@c do this instead of setting a sticky tag of "HEAD" 6982@c as in the status quo but I haven't thought much 6983@c about that idea. Of course -r .reset or something 6984@c could be coined if this needs to be a new option). 6985@c On the other hand, having -A mean "get things back 6986@c into the state after a fresh checkout" has a certain 6987@c appeal, and maybe there is no sufficient reason for 6988@c creeping featurism in this area. 6989 6990The modes available are: 6991 6992@table @samp 6993@item -kkv 6994Generate keyword strings using the default form, e.g. 6995@code{$@i{}Revision: 5.7 $} for the @code{Revision} 6996keyword. 6997 6998@item -kkvl 6999Like @samp{-kkv}, except that a locker's name is always 7000inserted if the given revision is currently locked. 7001The locker's name is only relevant if @code{cvs admin 7002-l} is in use. 7003 7004@item -kk 7005Generate only keyword names in keyword strings; omit 7006their values. For example, for the @code{Revision} 7007keyword, generate the string @code{$@i{}Revision$} 7008instead of @code{$@i{}Revision: 5.7 $}. This option 7009is useful to ignore differences due to keyword 7010substitution when comparing different revisions of a 7011file (@pxref{Merging and keywords}). 7012 7013@item -ko 7014Generate the old keyword string, present in the working 7015file just before it was checked in. For example, for 7016the @code{Revision} keyword, generate the string 7017@code{$@i{}Revision: 1.1 $} instead of 7018@code{$@i{}Revision: 5.7 $} if that is how the 7019string appeared when the file was checked in. 7020 7021@item -kb 7022Like @samp{-ko}, but also inhibit conversion of line 7023endings between the canonical form in which they are 7024stored in the repository (linefeed only), and the form 7025appropriate to the operating system in use on the 7026client. For systems, like unix, which use linefeed 7027only to terminate lines, this is very similar to 7028@samp{-ko}. For more information on binary files, see 7029@ref{Binary files}. In @sc{cvs} version 1.12.2 and later 7030@samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or 7031@code{cvs import} may not be overridden by a @samp{-k} option 7032specified on the command line. 7033 7034@item -kv 7035Generate only keyword values for keyword strings. For 7036example, for the @code{Revision} keyword, generate the string 7037@code{5.7} instead of @code{$@i{}Revision: 5.7 $}. 7038This can help generate files in programming languages 7039where it is hard to strip keyword delimiters like 7040@code{$@i{}Revision: $} from a string. However, 7041further keyword substitution cannot be performed once 7042the keyword names are removed, so this option should be 7043used with care. 7044 7045One often would like to use @samp{-kv} with @code{cvs 7046export}---@pxref{export}. But be aware that doesn't 7047handle an export containing binary files correctly. 7048 7049@end table 7050 7051@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7052@node Configuring keyword expansion 7053@section Configuring Keyord Expansion 7054@cindex Configuring keyword expansion 7055 7056In a repository that includes third-party software on 7057vendor branches, it is sometimes helpful to configure 7058CVS to use a local keyword instead of the standard 7059$@i{}Id$ or $@i{}Header$ keywords. Examples from 7060real projects includ, $@i{}Xorg$, $@i{}XFree86$, 7061$@i{}FreeBSD$, $@i{}NetBSD$, 7062$@i{}OpenBSD$, and even $@i{}dotat$. 7063The advantage of this is that 7064you can include your local version information in a 7065file using this local keyword (sometimes called a 7066``custom tag'' or a ``local tag'') without disrupting 7067the upstream version information (which may be a 7068different local keyword or a standard keyword). In 7069these cases, it is typically desirable to disable the 7070expansion of all keywords except the configured local 7071keyword. 7072 7073The @code{KeywordExpansion} option in the 7074@file{CVSROOT/config} file is intended to allow for the 7075either the explicit exclusion of a keyword or list of 7076keywords, or for the explicit inclusion of a keyword or 7077a list of keywords. This list may include the 7078@code{LocalKeyword} that has been configured. 7079 7080The @code{KeywordExpansion} option is followed by 7081@code{=} and the next character may either be @code{i} 7082to start an inclusion list or @code{e} to start an 7083exclusion list. If the following lines were added to 7084the @file{CVSROOT/config} file: 7085 7086@example 7087 # Add a "MyBSD" keyword and restrict keyword 7088 # expansion 7089 LocalKeyword=MyBSD=CVSHeader 7090 KeywordExpand=iMyBSD 7091@end example 7092 7093then only the $@i{}MyBSD$ keyword would be expanded. 7094A list may be used. The this example: 7095 7096@example 7097 # Add a "MyBSD" keyword and restrict keyword 7098 # expansion to the MyBSD, Name and Date keywords. 7099 LocalKeyword=MyBSD=CVSHeader 7100 KeywordExpand=iMyBSD,Name,Date 7101@end example 7102 7103would allow $@i{}MyBSD$, $@i{}Name$, and 7104$@i{}Date$ to be expanded. 7105 7106It is also possible to configure an exclusion list 7107using the following: 7108 7109@example 7110 # Do not expand the non-RCS keyword CVSHeader 7111 KeywordExpand=eCVSHeader 7112@end example 7113 7114This allows @sc{cvs} to ignore the recently introduced 7115$@i{}CVSHeader$ keyword and retain all of the 7116others. The exclusion entry could also contain the 7117standard RCS keyword list, but this could be confusing 7118to users that expect RCS keywords to be expanded, so 7119ycare should be taken to properly set user expectations 7120for a repository that is configured in that manner. 7121 7122If there is a desire to not have any RCS keywords 7123expanded and not use the @code{-ko} flags everywhere, 7124an administrator may disable all keyword expansion 7125using the @file{CVSROOT/config} line: 7126 7127@example 7128 # Do not expand any RCS keywords 7129 KeywordExpand=i 7130@end example 7131 7132this could be confusing to users that expect RCS 7133keywords like $@i{}Id$ to be expanded properly, 7134so care should be taken to properly set user 7135expectations for a repository so configured. 7136 7137It should be noted that a patch to provide both the 7138@code{KeywordExpand} and @code{LocalKeyword} features 7139has been around a long time. However, that patch 7140implemented these features using @code{tag=} and 7141@code{tagexpand=} keywords and those keywords are NOT 7142recognized. 7143 7144@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7145@node Log keyword 7146@section Problems with the $ @i{}Log$ keyword. 7147 7148The @code{$@i{}Log$} keyword is somewhat 7149controversial. As long as you are working on your 7150development system the information is easily accessible 7151even if you do not use the @code{$@i{}Log$} 7152keyword---just do a @code{cvs log}. Once you export 7153the file the history information might be useless 7154anyhow. 7155 7156A more serious concern is that @sc{cvs} is not good at 7157handling @code{$@i{}Log$} entries when a branch is 7158merged onto the main trunk. Conflicts often result 7159from the merging operation. 7160@c Might want to check whether the CVS implementation 7161@c of RCS_merge has this problem the same way rcsmerge 7162@c does. I would assume so.... 7163 7164People also tend to "fix" the log entries in the file 7165(correcting spelling mistakes and maybe even factual 7166errors). If that is done the information from 7167@code{cvs log} will not be consistent with the 7168information inside the file. This may or may not be a 7169problem in real life. 7170 7171It has been suggested that the @code{$@i{}Log$} 7172keyword should be inserted @emph{last} in the file, and 7173not in the files header, if it is to be used at all. 7174That way the long list of change messages will not 7175interfere with everyday source file browsing. 7176 7177@c --------------------------------------------------------------------- 7178@node Tracking sources 7179@chapter Tracking third-party sources 7180@cindex Third-party sources 7181@cindex Tracking sources 7182 7183@c FIXME: Need discussion of added and removed files. 7184@c FIXME: This doesn't really adequately introduce the 7185@c concepts of "vendor" and "you". They don't *have* 7186@c to be separate organizations or separate people. 7187@c We want a description which is somewhat more based on 7188@c the technical issues of which sources go where, but 7189@c also with enough examples of how this relates to 7190@c relationships like customer-supplier, developer-QA, 7191@c maintainer-contributor, or whatever, to make it 7192@c seem concrete. 7193If you modify a program to better fit your site, you 7194probably want to include your modifications when the next 7195release of the program arrives. @sc{cvs} can help you with 7196this task. 7197 7198@cindex Vendor 7199@cindex Vendor branch 7200@cindex Branch, vendor- 7201In the terminology used in @sc{cvs}, the supplier of the 7202program is called a @dfn{vendor}. The unmodified 7203distribution from the vendor is checked in on its own 7204branch, the @dfn{vendor branch}. @sc{cvs} reserves branch 72051.1.1 for this use. 7206 7207When you modify the source and commit it, your revision 7208will end up on the main trunk. When a new release is 7209made by the vendor, you commit it on the vendor branch 7210and copy the modifications onto the main trunk. 7211 7212Use the @code{import} command to create and update 7213the vendor branch. When you import a new file, 7214the vendor branch is made the `head' revision, so 7215anyone that checks out a copy of the file gets that 7216revision. When a local modification is committed it is 7217placed on the main trunk, and made the `head' 7218revision. 7219 7220@menu 7221* First import:: Importing for the first time 7222* Update imports:: Updating with the import command 7223* Reverting local changes:: Reverting to the latest vendor release 7224* Binary files in imports:: Binary files require special handling 7225* Keywords in imports:: Keyword substitution might be undesirable 7226* Multiple vendor branches:: What if you get sources from several places? 7227@end menu 7228 7229@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7230@node First import 7231@section Importing for the first time 7232@cindex Importing modules 7233 7234@c Should mention naming conventions for vendor tags, 7235@c release tags, and perhaps directory names. 7236Use the @code{import} command to check in the sources 7237for the first time. When you use the @code{import} 7238command to track third-party sources, the @dfn{vendor 7239tag} and @dfn{release tags} are useful. The 7240@dfn{vendor tag} is a symbolic name for the branch 7241(which is always 1.1.1, unless you use the @samp{-b 7242@var{branch}} flag---see @ref{Multiple vendor branches}.). The 7243@dfn{release tags} are symbolic names for a particular 7244release, such as @samp{FSF_0_04}. 7245 7246@c I'm not completely sure this belongs here. But 7247@c we need to say it _somewhere_ reasonably obvious; it 7248@c is a common misconception among people first learning CVS 7249Note that @code{import} does @emph{not} change the 7250directory in which you invoke it. In particular, it 7251does not set up that directory as a @sc{cvs} working 7252directory; if you want to work with the sources import 7253them first and then check them out into a different 7254directory (@pxref{Getting the source}). 7255 7256@cindex wdiff (import example) 7257Suppose you have the sources to a program called 7258@code{wdiff} in a directory @file{wdiff-0.04}, 7259and are going to make private modifications that you 7260want to be able to use even when new releases are made 7261in the future. You start by importing the source to 7262your repository: 7263 7264@example 7265$ cd wdiff-0.04 7266$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 7267@end example 7268 7269The vendor tag is named @samp{FSF_DIST} in the above 7270example, and the only release tag assigned is 7271@samp{WDIFF_0_04}. 7272@c FIXME: Need to say where fsf/wdiff comes from. 7273 7274@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7275@node Update imports 7276@section Updating with the import command 7277 7278When a new release of the source arrives, you import it into the 7279repository with the same @code{import} command that you used to set up 7280the repository in the first place. The only difference is that you 7281specify a different release tag this time: 7282 7283@example 7284$ tar xfz wdiff-0.05.tar.gz 7285$ cd wdiff-0.05 7286$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 7287@end example 7288 7289For files that have not been modified locally, the newly created 7290revision becomes the head revision. If you have made local 7291changes, @code{import} will warn you that you must merge the changes 7292into the main trunk, and tell you to use @samp{checkout -j} to do so: 7293 7294@c FIXME: why "wdiff" here and "fsf/wdiff" in the 7295@c "import"? I think the assumption is that one has 7296@c "wdiff fsf/wdiff" or some such in modules, but it 7297@c would be better to not use modules in this example. 7298@example 7299$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 7300@end example 7301 7302@noindent 7303The above command will check out the latest revision of 7304@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 7305since yesterday into the working copy. If any conflicts arise during 7306the merge they should be resolved in the normal way (@pxref{Conflicts 7307example}). Then, the modified files may be committed. 7308 7309However, it is much better to use the two release tags rather than using 7310a date on the branch as suggested above: 7311 7312@example 7313$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 7314@end example 7315 7316@noindent 7317The reason this is better is that 7318using a date, as suggested above, assumes that you do 7319not import more than one release of a product per day. 7320More importantly, using the release tags allows @sc{cvs} to detect files 7321that were removed between the two vendor releases and mark them for 7322removal. Since @code{import} has no way to detect removed files, you 7323should do a merge like this even if @code{import} doesn't tell you to. 7324 7325@node Reverting local changes 7326@section Reverting to the latest vendor release 7327 7328You can also revert local changes completely and return 7329to the latest vendor release by changing the `head' 7330revision back to the vendor branch on all files. For 7331example, if you have a checked-out copy of the sources 7332in @file{~/work.d/wdiff}, and you want to revert to the 7333vendor's version for all the files in that directory, 7334you would type: 7335 7336@example 7337$ cd ~/work.d/wdiff 7338$ cvs admin -bWDIFF . 7339@end example 7340 7341@noindent 7342You must specify the @samp{-bWDIFF} without any space 7343after the @samp{-b}. @xref{admin options}. 7344 7345@node Binary files in imports 7346@section How to handle binary files with cvs import 7347 7348Use the @samp{-k} wrapper option to tell import which 7349files are binary. @xref{Wrappers}. 7350 7351@node Keywords in imports 7352@section How to handle keyword substitution with cvs import 7353 7354The sources which you are importing may contain 7355keywords (@pxref{Keyword substitution}). For example, 7356the vendor may use @sc{cvs} or some other system 7357which uses similar keyword expansion syntax. If you 7358just import the files in the default fashion, then 7359the keyword expansions supplied by the vendor will 7360be replaced by keyword expansions supplied by your 7361own copy of @sc{cvs}. It may be more convenient to 7362maintain the expansions supplied by the vendor, so 7363that this information can supply information about 7364the sources that you imported from the vendor. 7365 7366To maintain the keyword expansions supplied by the 7367vendor, supply the @samp{-ko} option to @code{cvs 7368import} the first time you import the file. 7369This will turn off keyword expansion 7370for that file entirely, so if you want to be more 7371selective you'll have to think about what you want 7372and use the @samp{-k} option to @code{cvs update} or 7373@code{cvs admin} as appropriate. 7374@c Supplying -ko to import if the file already existed 7375@c has no effect. Not clear to me whether it should 7376@c or not. 7377 7378@node Multiple vendor branches 7379@section Multiple vendor branches 7380 7381All the examples so far assume that there is only one 7382vendor from which you are getting sources. In some 7383situations you might get sources from a variety of 7384places. For example, suppose that you are dealing with 7385a project where many different people and teams are 7386modifying the software. There are a variety of ways to 7387handle this, but in some cases you have a bunch of 7388source trees lying around and what you want to do more 7389than anything else is just to all put them in @sc{cvs} so 7390that you at least have them in one place. 7391 7392For handling situations in which there may be more than 7393one vendor, you may specify the @samp{-b} option to 7394@code{cvs import}. It takes as an argument the vendor 7395branch to import to. The default is @samp{-b 1.1.1}. 7396 7397For example, suppose that there are two teams, the red 7398team and the blue team, that are sending you sources. 7399You want to import the red team's efforts to branch 74001.1.1 and use the vendor tag RED. You want to import 7401the blue team's efforts to branch 1.1.3 and use the 7402vendor tag BLUE. So the commands you might use are: 7403 7404@example 7405$ cvs import dir RED RED_1-0 7406$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 7407@end example 7408 7409Note that if your vendor tag does not match your 7410@samp{-b} option, @sc{cvs} will not detect this case! For 7411example, 7412 7413@example 7414$ cvs import -b 1.1.3 dir RED RED_1-0 7415@end example 7416 7417@noindent 7418Be careful; this kind of mismatch is sure to sow 7419confusion or worse. I can't think of a useful purpose 7420for the ability to specify a mismatch here, but if you 7421discover such a use, don't. @sc{cvs} is likely to make this 7422an error in some future release. 7423 7424@c Probably should say more about the semantics of 7425@c multiple branches. What about the default branch? 7426@c What about joining (perhaps not as useful with 7427@c multiple branches, or perhaps it is. Either way 7428@c should be mentioned). 7429 7430@c I'm not sure about the best location for this. In 7431@c one sense, it might belong right after we've introduced 7432@c CVS's basic version control model, because people need 7433@c to figure out builds right away. The current location 7434@c is based on the theory that it kind of akin to the 7435@c "Revision management" section. 7436@node Builds 7437@chapter How your build system interacts with CVS 7438@cindex Builds 7439@cindex make 7440 7441As mentioned in the introduction, @sc{cvs} does not 7442contain software for building your software from source 7443code. This section describes how various aspects of 7444your build system might interact with @sc{cvs}. 7445 7446@c Is there a way to discuss this without reference to 7447@c tools other than CVS? I'm not sure there is; I 7448@c wouldn't think that people who learn CVS first would 7449@c even have this concern. 7450One common question, especially from people who are 7451accustomed to @sc{rcs}, is how to make their build get 7452an up to date copy of the sources. The answer to this 7453with @sc{cvs} is two-fold. First of all, since 7454@sc{cvs} itself can recurse through directories, there 7455is no need to modify your @file{Makefile} (or whatever 7456configuration file your build tool uses) to make sure 7457each file is up to date. Instead, just use two 7458commands, first @code{cvs -q update} and then 7459@code{make} or whatever the command is to invoke your 7460build tool. Secondly, you do not necessarily 7461@emph{want} to get a copy of a change someone else made 7462until you have finished your own work. One suggested 7463approach is to first update your sources, then 7464implement, build and 7465test the change you were thinking of, and then commit 7466your sources (updating first if necessary). By 7467periodically (in between changes, using the approach 7468just described) updating your entire tree, you ensure 7469that your sources are sufficiently up to date. 7470 7471@cindex Bill of materials 7472One common need is to record which versions of which 7473source files went into a particular build. This kind 7474of functionality is sometimes called @dfn{bill of 7475materials} or something similar. The best way to do 7476this with @sc{cvs} is to use the @code{tag} command to 7477record which versions went into a given build 7478(@pxref{Tags}). 7479 7480Using @sc{cvs} in the most straightforward manner 7481possible, each developer will have a copy of the entire 7482source tree which is used in a particular build. If 7483the source tree is small, or if developers are 7484geographically dispersed, this is the preferred 7485solution. In fact one approach for larger projects is 7486to break a project down into smaller 7487@c I say subsystem instead of module because they may or 7488@c may not use the modules file. 7489separately-compiled subsystems, and arrange a way of 7490releasing them internally so that each developer need 7491check out only those subsystems which they are 7492actively working on. 7493 7494Another approach is to set up a structure which allows 7495developers to have their own copies of some files, and 7496for other files to access source files from a central 7497location. Many people have come up with some such a 7498@c two such people are paul@sander.cupertino.ca.us (for 7499@c a previous employer) 7500@c and gtornblo@senet.abb.se (spicm and related tools), 7501@c but as far as I know 7502@c no one has nicely packaged or released such a system (or 7503@c instructions for constructing one). 7504system using features such as the symbolic link feature 7505found in many operating systems, or the @code{VPATH} 7506feature found in many versions of @code{make}. One build 7507tool which is designed to help with this kind of thing 7508is Odin (see 7509@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 7510@c Should we be saying more about Odin? Or how you use 7511@c it with CVS? Also, the Prime Time Freeware for Unix 7512@c disk (see http://www.ptf.com/) has Odin (with a nice 7513@c paragraph summarizing it on the web), so that might be a 7514@c semi-"official" place to point people. 7515@c 7516@c Of course, many non-CVS systems have this kind of 7517@c functionality, for example OSF's ODE 7518@c (http://www.osf.org/ode/) or mk 7519@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 7520@c He has changed providers in the past; a search engine search 7521@c for "Peter Ziobrzynski" probably won't get too many 7522@c spurious hits :-). A more stable URL might be 7523@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 7524@c there is any point in mentioning them here unless they 7525@c can work with CVS. 7526 7527@c --------------------------------------------------------------------- 7528@node Special Files 7529@chapter Special Files 7530 7531@cindex Special files 7532@cindex Device nodes 7533@cindex Ownership, saving in CVS 7534@cindex Permissions, saving in CVS 7535@cindex Hard links 7536@cindex Symbolic links 7537 7538In normal circumstances, @sc{cvs} works only with regular 7539files. Every file in a project is assumed to be 7540persistent; it must be possible to open, read and close 7541them; and so on. @sc{cvs} also ignores file permissions and 7542ownerships, leaving such issues to be resolved by the 7543developer at installation time. In other words, it is 7544not possible to "check in" a device into a repository; 7545if the device file cannot be opened, @sc{cvs} will refuse to 7546handle it. Files also lose their ownerships and 7547permissions during repository transactions. 7548 7549 7550@c --------------------------------------------------------------------- 7551@node CVS commands 7552@appendix Guide to CVS commands 7553 7554This appendix describes the overall structure of 7555@sc{cvs} commands, and describes some commands in 7556detail (others are described elsewhere; for a quick 7557reference to @sc{cvs} commands, @pxref{Invoking CVS}). 7558@c The idea is that we want to move the commands which 7559@c are described here into the main body of the manual, 7560@c in the process reorganizing the manual to be 7561@c organized around what the user wants to do, not 7562@c organized around CVS commands. 7563@c 7564@c Note that many users do expect a manual which is 7565@c organized by command. At least some users do. 7566@c One good addition to the "organized by command" 7567@c section (if any) would be "see also" links. 7568@c The awk manual might be a good example; it has a 7569@c reference manual which is more verbose than Invoking 7570@c CVS but probably somewhat less verbose than CVS 7571@c Commands. 7572 7573@menu 7574* Structure:: Overall structure of CVS commands 7575* Exit status:: Indicating CVS's success or failure 7576* ~/.cvsrc:: Default options with the ~/.csvrc file 7577* Global options:: Options you give to the left of cvs_command 7578* Common options:: Options you give to the right of cvs_command 7579* admin:: Administration 7580* checkout:: Checkout sources for editing 7581* commit:: Check files into the repository 7582* diff:: Show differences between revisions 7583* export:: Export sources from CVS, similar to checkout 7584* history:: Show status of files and users 7585* import:: Import sources into CVS, using vendor branches 7586* log:: Show log messages for files 7587* rdiff:: 'patch' format diffs between releases 7588* release:: Indicate that a directory is no longer in use 7589* update:: Bring work tree in sync with repository 7590@end menu 7591 7592@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7593@node Structure 7594@appendixsec Overall structure of CVS commands 7595@cindex Structure 7596@cindex CVS command structure 7597@cindex Command structure 7598@cindex Format of CVS commands 7599 7600The overall format of all @sc{cvs} commands is: 7601 7602@example 7603cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 7604@end example 7605 7606@table @code 7607@item cvs 7608The name of the @sc{cvs} program. 7609 7610@item cvs_options 7611Some options that affect all sub-commands of @sc{cvs}. These are 7612described below. 7613 7614@item cvs_command 7615One of several different sub-commands. Some of the commands have 7616aliases that can be used instead; those aliases are noted in the 7617reference manual for that command. There are only two situations 7618where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 7619list of available commands, and @samp{cvs -v} displays version 7620information on @sc{cvs} itself. 7621 7622@item command_options 7623Options that are specific for the command. 7624 7625@item command_args 7626Arguments to the commands. 7627@end table 7628 7629There is unfortunately some confusion between 7630@code{cvs_options} and @code{command_options}. 7631@samp{-l}, when given as a @code{cvs_option}, only 7632affects some of the commands. When it is given as a 7633@code{command_option} is has a different meaning, and 7634is accepted by more commands. In other words, do not 7635take the above categorization too seriously. Look at 7636the documentation instead. 7637 7638@node Exit status 7639@appendixsec CVS's exit status 7640@cindex Exit status, of CVS 7641 7642@sc{cvs} can indicate to the calling environment whether it 7643succeeded or failed by setting its @dfn{exit status}. 7644The exact way of testing the exit status will vary from 7645one operating system to another. For example in a unix 7646shell script the @samp{$?} variable will be 0 if the 7647last command returned a successful exit status, or 7648greater than 0 if the exit status indicated failure. 7649 7650If @sc{cvs} is successful, it returns a successful status; 7651if there is an error, it prints an error message and 7652returns a failure status. The one exception to this is 7653the @code{cvs diff} command. It will return a 7654successful status if it found no differences, or a 7655failure status if there were differences or if there 7656was an error. Because this behavior provides no good 7657way to detect errors, in the future it is possible that 7658@code{cvs diff} will be changed to behave like the 7659other @sc{cvs} commands. 7660@c It might seem like checking whether cvs -q diff 7661@c produces empty or non-empty output can tell whether 7662@c there were differences or not. But it seems like 7663@c there are cases with output but no differences 7664@c (testsuite basica-8b). It is not clear to me how 7665@c useful it is for a script to be able to check 7666@c whether there were differences. 7667@c FIXCVS? In previous versions of CVS, cvs diff 7668@c returned 0 for no differences, 1 for differences, or 7669@c 2 for errors. Is this behavior worth trying to 7670@c bring back (but what does it mean for VMS?)? 7671 7672@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7673@node ~/.cvsrc 7674@appendixsec Default options and the ~/.cvsrc file 7675@cindex .cvsrc file 7676@cindex Option defaults 7677 7678There are some @code{command_options} that are used so 7679often that you might have set up an alias or some other 7680means to make sure you always specify that option. One 7681example (the one that drove the implementation of the 7682@file{.cvsrc} support, actually) is that many people find the 7683default output of the @samp{diff} command to be very 7684hard to read, and that either context diffs or unidiffs 7685are much easier to understand. 7686 7687The @file{~/.cvsrc} file is a way that you can add 7688default options to @code{cvs_commands} within cvs, 7689instead of relying on aliases or other shell scripts. 7690 7691The format of the @file{~/.cvsrc} file is simple. The 7692file is searched for a line that begins with the same 7693name as the @code{cvs_command} being executed. If a 7694match is found, then the remainder of the line is split 7695up (at whitespace characters) into separate options and 7696added to the command arguments @emph{before} any 7697options from the command line. 7698 7699If a command has two names (e.g., @code{checkout} and 7700@code{co}), the official name, not necessarily the one 7701used on the command line, will be used to match against 7702the file. So if this is the contents of the user's 7703@file{~/.cvsrc} file: 7704 7705@example 7706log -N 7707diff -uN 7708rdiff -u 7709update -Pd 7710checkout -P 7711release -d 7712@end example 7713 7714@noindent 7715the command @samp{cvs checkout foo} would have the 7716@samp{-P} option added to the arguments, as well as 7717@samp{cvs co foo}. 7718 7719With the example file above, the output from @samp{cvs 7720diff foobar} will be in unidiff format. @samp{cvs diff 7721-c foobar} will provide context diffs, as usual. 7722Getting "old" format diffs would be slightly more 7723complicated, because @code{diff} doesn't have an option 7724to specify use of the "old" format, so you would need 7725@samp{cvs -f diff foobar}. 7726 7727In place of the command name you can use @code{cvs} to 7728specify global options (@pxref{Global options}). For 7729example the following line in @file{.cvsrc} 7730 7731@example 7732cvs -z6 7733@end example 7734 7735@noindent 7736causes @sc{cvs} to use compression level 6. 7737 7738@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7739@node Global options 7740@appendixsec Global options 7741@cindex Options, global 7742@cindex Global options 7743@cindex Left-hand options 7744 7745The available @samp{cvs_options} (that are given to the 7746left of @samp{cvs_command}) are: 7747 7748@table @code 7749@item --allow-root=@var{rootdir} 7750Specify legal @sc{cvsroot} directory. See 7751@ref{Password authentication server}. 7752 7753@cindex Authentication, stream 7754@cindex Stream authentication 7755@item -a 7756Authenticate all communication between the client and 7757the server. Only has an effect on the @sc{cvs} client. 7758As of this writing, this is only implemented when using 7759a GSSAPI connection (@pxref{GSSAPI authenticated}). 7760Authentication prevents certain sorts of attacks 7761involving hijacking the active @sc{tcp} connection. 7762Enabling authentication does not enable encryption. 7763 7764@cindex RCSBIN, overriding 7765@cindex Overriding RCSBIN 7766@item -b @var{bindir} 7767In @sc{cvs} 1.9.18 and older, this specified that 7768@sc{rcs} programs are in the @var{bindir} directory. 7769Current versions of @sc{cvs} do not run @sc{rcs} 7770programs; for compatibility this option is accepted, 7771but it does nothing. 7772 7773@cindex TMPDIR, overriding 7774@cindex Overriding TMPDIR 7775@item -T @var{tempdir} 7776Use @var{tempdir} as the directory where temporary files are 7777located. Overrides the setting of the @code{$TMPDIR} environment 7778variable and any precompiled directory. This parameter should be 7779specified as an absolute pathname. 7780(When running client/server, @samp{-T} affects only the local process; 7781specifying @samp{-T} for the client has no effect on the server and 7782vice versa.) 7783 7784@cindex CVSROOT, overriding 7785@cindex Overriding CVSROOT 7786@item -d @var{cvs_root_directory} 7787Use @var{cvs_root_directory} as the root directory 7788pathname of the repository. Overrides the setting of 7789the @code{$CVSROOT} environment variable. @xref{Repository}. 7790 7791@cindex EDITOR, overriding 7792@cindex Overriding EDITOR 7793@item -e @var{editor} 7794Use @var{editor} to enter revision log information. Overrides the 7795setting of the @code{$CVSEDITOR} and @code{$EDITOR} 7796environment variables. For more information, see 7797@ref{Committing your changes}. 7798 7799@item -f 7800Do not read the @file{~/.cvsrc} file. This 7801option is most often used because of the 7802non-orthogonality of the @sc{cvs} option set. For 7803example, the @samp{cvs log} option @samp{-N} (turn off 7804display of tag names) does not have a corresponding 7805option to turn the display on. So if you have 7806@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 7807you may need to use @samp{-f} to show the tag names. 7808 7809@item -H 7810@itemx --help 7811Display usage information about the specified @samp{cvs_command} 7812(but do not actually execute the command). If you don't specify 7813a command name, @samp{cvs -H} displays overall help for 7814@sc{cvs}, including a list of other help options. 7815@c It seems to me it is better to document it this way 7816@c rather than trying to update this documentation 7817@c every time that we add a --help-foo option. But 7818@c perhaps that is confusing... 7819 7820@item -l 7821Do not log the @samp{cvs_command} in the command history (but execute it 7822anyway). @xref{history}, for information on command history. 7823 7824@cindex Read-only repository mode 7825@item -R 7826Turns on read-only repository mode. This allows one to check out from a 7827read-only repository, such as within an anoncvs server, or from a CDROM 7828repository. 7829 7830Same effect as if the @code{CVSREADONLYFS} environment 7831variable is set. Using @samp{-R} can also considerably 7832speed up checkout's over NFS. 7833 7834@cindex Read-only mode 7835@item -n 7836Do not change any files. Attempt to execute the 7837@samp{cvs_command}, but only to issue reports; do not remove, 7838update, or merge any existing files, or create any new files. 7839 7840Note that @sc{cvs} will not necessarily produce exactly 7841the same output as without @samp{-n}. In some cases 7842the output will be the same, but in other cases 7843@sc{cvs} will skip some of the processing that would 7844have been required to produce the exact same output. 7845 7846@item -Q 7847Cause the command to be really quiet; the command will only 7848generate output for serious problems. 7849 7850@item -q 7851Cause the command to be somewhat quiet; informational messages, 7852such as reports of recursion through subdirectories, are 7853suppressed. 7854 7855@cindex Read-only files, and -r 7856@item -r 7857Make new working files read-only. Same effect 7858as if the @code{$CVSREAD} environment variable is set 7859(@pxref{Environment variables}). The default is to 7860make working files writable, unless watches are on 7861(@pxref{Watches}). 7862 7863@item -s @var{variable}=@var{value} 7864Set a user variable (@pxref{Variables}). 7865 7866@cindex Trace 7867@item -t 7868Trace program execution; display messages showing the steps of 7869@sc{cvs} activity. Particularly useful with @samp{-n} to explore the 7870potential impact of an unfamiliar command. 7871 7872@item -v 7873@item --version 7874Display version and copyright information for @sc{cvs}. 7875 7876@cindex CVSREAD, overriding 7877@cindex Overriding CVSREAD 7878@item -w 7879Make new working files read-write. Overrides the 7880setting of the @code{$CVSREAD} environment variable. 7881Files are created read-write by default, unless @code{$CVSREAD} is 7882set or @samp{-r} is given. 7883@c Note that -w only overrides -r and CVSREAD; it has 7884@c no effect on files which are readonly because of 7885@c "cvs watch on". My guess is that is the way it 7886@c should be (or should "cvs -w get" on a watched file 7887@c be the same as a get and a cvs edit?), but I'm not 7888@c completely sure whether to document it this way. 7889 7890@item -x 7891@cindex Encryption 7892Encrypt all communication between the client and the 7893server. Only has an effect on the @sc{cvs} client. As 7894of this writing, this is only implemented when using a 7895GSSAPI connection (@pxref{GSSAPI authenticated}) or a 7896Kerberos connection (@pxref{Kerberos authenticated}). 7897Enabling encryption implies that message traffic is 7898also authenticated. Encryption support is not 7899available by default; it must be enabled using a 7900special configure option, @file{--enable-encryption}, 7901when you build @sc{cvs}. 7902 7903@item -z @var{gzip-level} 7904@cindex Compression 7905@cindex Gzip 7906Set the compression level. 7907Valid levels are 1 (high speed, low compression) to 79089 (low speed, high compression), or 0 to disable 7909compression (the default). 7910Only has an effect on the @sc{cvs} client. 7911 7912@end table 7913 7914@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7915@node Common options 7916@appendixsec Common command options 7917@cindex Common options 7918@cindex Right-hand options 7919 7920This section describes the @samp{command_options} that 7921are available across several @sc{cvs} commands. These 7922options are always given to the right of 7923@samp{cvs_command}. Not all 7924commands support all of these options; each option is 7925only supported for commands where it makes sense. 7926However, when a command has one of these options you 7927can almost always count on the same behavior of the 7928option as in other commands. (Other command options, 7929which are listed with the individual commands, may have 7930different behavior from one @sc{cvs} command to the other). 7931 7932@strong{Note: the @samp{history} command is an exception; it supports 7933many options that conflict even with these standard options.} 7934 7935@table @code 7936@cindex Dates 7937@cindex Time 7938@cindex Specifying dates 7939@item -D @var{date_spec} 7940Use the most recent revision no later than @var{date_spec}. 7941@var{date_spec} is a single argument, a date description 7942specifying a date in the past. 7943 7944The specification is @dfn{sticky} when you use it to make a 7945private copy of a source file; that is, when you get a working 7946file using @samp{-D}, @sc{cvs} records the date you specified, so that 7947further updates in the same directory will use the same date 7948(for more information on sticky tags/dates, @pxref{Sticky tags}). 7949 7950@samp{-D} is available with the @code{annotate}, @code{checkout}, 7951@code{diff}, @code{export}, @code{history}, 7952@code{rdiff}, @code{rtag}, @code{tag}, and @code{update} commands. 7953(The @code{history} command uses this option in a 7954slightly different way; @pxref{history options}). 7955 7956@c What other formats should we accept? I don't want 7957@c to start accepting a whole mess of non-standard 7958@c new formats (there are a lot which are in wide use in 7959@c one context or another), but practicality does 7960@c dictate some level of flexibility. 7961@c * POSIX.2 (e.g. touch, ls output, date) and other 7962@c POSIX and/or de facto unix standards (e.g. at). The 7963@c practice here is too inconsistent to be of any use. 7964@c * VMS dates. This is not a formal standard, but 7965@c there is a published specification (see SYS$ASCTIM 7966@c and SYS$BINTIM in the _VMS System Services Reference 7967@c Manual_), it is implemented consistently in VMS 7968@c utilities, and VMS users will expect CVS running on 7969@c VMS to support this format (and if we're going to do 7970@c that, better to make CVS support it on all 7971@c platforms. Maybe). 7972@c 7973@c NOTE: The tar manual has some documentation for 7974@c getdate.y (just for our info; we don't want to 7975@c attempt to document all the formats accepted by 7976@c getdate.y). 7977@c 7978@c One more note: In output, CVS should consistently 7979@c use one date format, and that format should be one that 7980@c it accepts in input as well. The former isn't 7981@c really true (see survey below), and I'm not 7982@c sure that either of those formats is accepted in 7983@c input. 7984@c 7985@c cvs log 7986@c current 1996/01/02 13:45:31 7987@c Internet 02 Jan 1996 13:45:31 UT 7988@c ISO 1996-01-02 13:45:31 7989@c cvs ann 7990@c current 02-Jan-96 7991@c Internet-like 02 Jan 96 7992@c ISO 96-01-02 7993@c cvs status 7994@c current Tue Jun 11 02:54:53 1996 7995@c Internet [Tue,] 11 Jun 1996 02:54:53 7996@c ISO 1996-06-11 02:54:53 7997@c note: date possibly should be omitted entirely for 7998@c other reasons. 7999@c cvs editors 8000@c current Tue Jun 11 02:54:53 1996 GMT 8001@c cvs history 8002@c current 06/11 02:54 +0000 8003@c any others? 8004@c There is a good chance the proper solution has to 8005@c involve at least some level of letting the user 8006@c decide which format (with the default being the 8007@c formats CVS has always used; changing these might be 8008@c _very_ disruptive since scripts may very well be 8009@c parsing them). 8010@c 8011@c Another random bit of prior art concerning dates is 8012@c the strptime function which takes templates such as 8013@c "%m/%d/%y", and apparent a variant of getdate() 8014@c which also honors them. See 8015@c X/Open CAE Specification, System Interfaces and 8016@c Headers Issue 4, Version 2 (September 1994), in the 8017@c entry for getdate() on page 231 8018 8019@cindex Timezone, in input 8020@cindex Zone, time, in input 8021A wide variety of date formats are supported by 8022@sc{cvs}. The most standard ones are ISO8601 (from the 8023International Standards Organization) and the Internet 8024e-mail standard (specified in RFC822 as amended by 8025RFC1123). 8026 8027@c Probably should be doing more to spell out just what 8028@c the rules are, rather than just giving examples. 8029@c But I want to keep this simple too. 8030@c So I don't know.... 8031@c A few specific issues: (1) Maybe should reassure 8032@c people that years after 2000 8033@c work (they are in the testsuite, so they do indeed 8034@c work). (2) What do two digit years 8035@c mean? Where do we accept them? (3) Local times can 8036@c be ambiguous or nonexistent if they fall during the 8037@c hour when daylight savings time goes into or out of 8038@c effect. Pretty obscure, so I'm not at all sure we 8039@c should be documenting the behavior in that case. 8040ISO8601 dates have many variants but a few examples 8041are: 8042 8043@example 80441972-09-24 80451972-09-24 20:05 8046@end example 8047@c I doubt we really accept all ISO8601 format dates 8048@c (for example, decimal hours like 1972-09-24 20,2) 8049@c I'm not sure we should, many of them are pretty 8050@c bizarre and it has lots of gratuitous multiple ways 8051@c to specify the same thing. 8052 8053There are a lot more ISO8601 date formats, and @sc{cvs} 8054accepts many of them, but you probably don't want to 8055hear the @emph{whole} long story :-). 8056 8057@c Citing a URL here is kind of problematic given how 8058@c much they change and people who have old versions of 8059@c this manual, but in case we want to reinstate an 8060@c ISO8601 URL, a few are: 8061@c http://www.saqqara.demon.co.uk/datefmt.htm 8062@c http://www.cl.cam.ac.uk/~mgk25/iso-time.html 8063@c Citing some other ISO8601 source is probably even 8064@c worse :-). 8065 8066In addition to the dates allowed in Internet e-mail 8067itself, @sc{cvs} also allows some of the fields to be 8068omitted. For example: 8069@c FIXME: Need to figure out better, and document, 8070@c what we want to allow the user to omit. 8071@c NOTE: "omit" does not imply "reorder". 8072@c FIXME: Need to cite a web page describing how to get 8073@c RFC's. 8074 8075@example 807624 Sep 1972 20:05 807724 Sep 8078@end example 8079 8080The date is interpreted as being in the 8081local timezone, unless a specific timezone is 8082specified. 8083 8084These two date formats are preferred. However, 8085@sc{cvs} currently accepts a wide variety of other date 8086formats. They are intentionally not documented here in 8087any detail, and future versions of @sc{cvs} might not 8088accept all of them. 8089@c We should document and testsuite "now" and 8090@c "yesterday". "now" is mentioned in the FAQ and 8091@c "yesterday" is mentioned in this document (and the 8092@c message from "cvs import" suggesting a merge 8093@c command). What else? Probably some/all of the "3 8094@c weeks ago" family. 8095@c 8096@c Maybe at 8097@c some point have CVS start give warnings on "unofficial" 8098@c formats (many of which might be typos or user 8099@c misunderstandings, and/or formats people never/rarely 8100@c use to specify dates)? 8101 8102One such format is 8103@code{@var{month}/@var{day}/@var{year}}. This may 8104confuse people who are accustomed to having the month 8105and day in the other order; @samp{1/4/96} is January 4, 8106not April 1. 8107 8108Remember to quote the argument to the @samp{-D} 8109flag so that your shell doesn't interpret spaces as 8110argument separators. A command using the @samp{-D} 8111flag can look like this: 8112 8113@example 8114$ cvs diff -D "1 hour ago" cvs.texinfo 8115@end example 8116 8117@cindex Forcing a tag match 8118@item -f 8119When you specify a particular date or tag to @sc{cvs} commands, they 8120normally ignore files that do not contain the tag (or did not 8121exist prior to the date) that you specified. Use the @samp{-f} option 8122if you want files retrieved even when there is no match for the 8123tag or date. (The most recent revision of the file 8124will be used). 8125 8126Note that even with @samp{-f}, a tag that you specify 8127must exist (that is, in some file, not necessary in 8128every file). This is so that @sc{cvs} will continue to 8129give an error if you mistype a tag name. 8130 8131@need 800 8132@samp{-f} is available with these commands: 8133@code{annotate}, @code{checkout}, @code{export}, 8134@code{rdiff}, @code{rtag}, and @code{update}. 8135 8136@strong{WARNING: The @code{commit} and @code{remove} 8137commands also have a 8138@samp{-f} option, but it has a different behavior for 8139those commands. See @ref{commit options}, and 8140@ref{Removing files}.} 8141 8142@item -k @var{kflag} 8143Override the default processing of RCS keywords other than 8144@samp{-kb}. @xref{Keyword substitution}, for the meaning of 8145@var{kflag}. Used with the @code{checkout} and @code{update} 8146commands, your @var{kflag} specification is 8147@dfn{sticky}; that is, when you use this option 8148with a @code{checkout} or @code{update} command, 8149@sc{cvs} associates your selected @var{kflag} with any files 8150it operates on, and continues to use that @var{kflag} with future 8151commands on the same files until you specify otherwise. 8152 8153The @samp{-k} option is available with the @code{add}, 8154@code{checkout}, @code{diff}, @code{export}, @code{import} and 8155@code{update} commands. 8156 8157@strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag 8158overrode the @samp{-kb} indication for a binary file. This could 8159sometimes corrupt binary files. @xref{Merging and keywords}, for 8160more.} 8161 8162@item -l 8163Local; run only in current working directory, rather than 8164recursing through subdirectories. 8165 8166Available with the following commands: @code{annotate}, @code{checkout}, 8167@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8168@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, 8169@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8170and @code{watchers}. 8171 8172@cindex Editor, avoiding invocation of 8173@cindex Avoiding editor invocation 8174@item -m @var{message} 8175Use @var{message} as log information, instead of 8176invoking an editor. 8177 8178Available with the following commands: @code{add}, 8179@code{commit} and @code{import}. 8180 8181@item -n 8182Do not run any tag program. (A program can be 8183specified to run in the modules 8184database (@pxref{modules}); this option bypasses it). 8185 8186@strong{Note: this is not the same as the @samp{cvs -n} 8187program option, which you can specify to the left of a cvs command!} 8188 8189Available with the @code{checkout}, @code{commit}, @code{export}, 8190and @code{rtag} commands. 8191 8192@item -P 8193Prune empty directories. See @ref{Removing directories}. 8194 8195@item -p 8196Pipe the files retrieved from the repository to standard output, 8197rather than writing them in the current directory. Available 8198with the @code{checkout} and @code{update} commands. 8199 8200@item -R 8201Process directories recursively. This is on by default. 8202 8203Available with the following commands: @code{annotate}, @code{checkout}, 8204@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8205@code{rdiff}, @code{remove}, @code{rtag}, 8206@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8207and @code{watchers}. 8208 8209@item -r @var{tag} 8210@cindex HEAD, special tag 8211@cindex BASE, special tag 8212Use the revision specified by the @var{tag} argument instead of the 8213default @dfn{head} revision. As well as arbitrary tags defined 8214with the @code{tag} or @code{rtag} command, two special tags are 8215always available: @samp{HEAD} refers to the most recent version 8216available in the repository, and @samp{BASE} refers to the 8217revision you last checked out into the current working directory. 8218 8219@c FIXME: What does HEAD really mean? I believe that 8220@c the current answer is the head of the default branch 8221@c for all cvs commands except diff. For diff, it 8222@c seems to be (a) the head of the trunk (or the default 8223@c branch?) if there is no sticky tag, (b) the head of the 8224@c branch for the sticky tag, if there is a sticky tag. 8225@c (b) is ugly as it differs 8226@c from what HEAD means for other commands, but people 8227@c and/or scripts are quite possibly used to it. 8228@c See "head" tests in sanity.sh. 8229@c Probably the best fix is to introduce two new 8230@c special tags, ".thead" for the head of the trunk, 8231@c and ".bhead" for the head of the current branch. 8232@c Then deprecate HEAD. This has the advantage of 8233@c not surprising people with a change to HEAD, and a 8234@c side benefit of also phasing out the poorly-named 8235@c HEAD (see discussion of reserved tag names in node 8236@c "Tags"). Of course, .thead and .bhead should be 8237@c carefully implemented (with the implementation the 8238@c same for "diff" as for everyone else), test cases 8239@c written (similar to the ones in "head"), new tests 8240@c cases written for things like default branches, &c. 8241 8242The tag specification is sticky when you use this 8243@c option 8244with @code{checkout} or @code{update} to make your own 8245copy of a file: @sc{cvs} remembers the tag and continues to use it on 8246future update commands, until you specify otherwise (for more information 8247on sticky tags/dates, @pxref{Sticky tags}). 8248 8249The tag can be either a symbolic or numeric tag, as 8250described in @ref{Tags}, or the name of a branch, as 8251described in @ref{Branching and merging}. 8252 8253Specifying the @samp{-q} global option along with the 8254@samp{-r} command option is often useful, to suppress 8255the warning messages when the @sc{rcs} file 8256does not contain the specified tag. 8257 8258@strong{Note: this is not the same as the overall @samp{cvs -r} option, 8259which you can specify to the left of a @sc{cvs} command!} 8260 8261@samp{-r} is available with the @code{checkout}, @code{commit}, 8262@code{diff}, @code{history}, @code{export}, @code{rdiff}, 8263@code{rtag}, and @code{update} commands. 8264 8265@item -W 8266Specify file names that should be filtered. You can 8267use this option repeatedly. The spec can be a file 8268name pattern of the same type that you can specify in 8269the @file{.cvswrappers} file. 8270Available with the following commands: @code{import}, 8271and @code{update}. 8272 8273@end table 8274 8275@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8276@node admin 8277@appendixsec admin---Administration 8278@cindex Admin (subcommand) 8279 8280@itemize @bullet 8281@item 8282Requires: repository, working directory. 8283@item 8284Changes: repository. 8285@item 8286Synonym: rcs 8287@end itemize 8288 8289This is the @sc{cvs} interface to assorted 8290administrative facilities. Some of them have 8291questionable usefulness for @sc{cvs} but exist for 8292historical purposes. Some of the questionable options 8293are likely to disappear in the future. This command 8294@emph{does} work recursively, so extreme care should be 8295used. 8296 8297@cindex cvsadmin 8298@cindex UserAdminOptions, in CVSROOT/config 8299On unix, if there is a group named @code{cvsadmin}, 8300only members of that group can run @code{cvs admin} 8301commands, except for those specified using the 8302@code{UserAdminOptions} configuration option in the 8303@file{CVSROOT/config} file. Options specified using 8304@code{UserAdminOptions} can be run by any user. See 8305@ref{config} for more on @code{UserAdminOptions}. 8306 8307The @code{cvsadmin} group should exist on the server, 8308or any system running the non-client/server @sc{cvs}. 8309To disallow @code{cvs admin} for all users, create a 8310group with no users in it. On NT, the @code{cvsadmin} 8311feature does not exist and all users 8312can run @code{cvs admin}. 8313 8314@menu 8315* admin options:: admin options 8316@end menu 8317 8318@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8319@node admin options 8320@appendixsubsec admin options 8321 8322Some of these options have questionable usefulness for 8323@sc{cvs} but exist for historical purposes. Some even 8324make it impossible to use @sc{cvs} until you undo the 8325effect! 8326 8327@table @code 8328@item -A@var{oldfile} 8329Might not work together with @sc{cvs}. Append the 8330access list of @var{oldfile} to the access list of the 8331@sc{rcs} file. 8332 8333@item -a@var{logins} 8334Might not work together with @sc{cvs}. Append the 8335login names appearing in the comma-separated list 8336@var{logins} to the access list of the @sc{rcs} file. 8337 8338@item -b[@var{rev}] 8339Set the default branch to @var{rev}. In @sc{cvs}, you 8340normally do not manipulate default branches; sticky 8341tags (@pxref{Sticky tags}) are a better way to decide 8342which branch you want to work on. There is one reason 8343to run @code{cvs admin -b}: to revert to the vendor's 8344version when using vendor branches (@pxref{Reverting 8345local changes}). 8346There can be no space between @samp{-b} and its argument. 8347@c Hmm, we don't document the usage where rev is 8348@c omitted. Maybe that usage can/should be deprecated 8349@c (and replaced with -bHEAD or something?) (so we can toss 8350@c the optional argument). Note that -bHEAD does not 8351@c work, as of 17 Sep 1997, but probably will once "cvs 8352@c admin" is internal to CVS. 8353 8354@cindex Comment leader 8355@item -c@var{string} 8356Sets the comment leader to @var{string}. The comment 8357leader is not used by current versions of @sc{cvs} or 8358@sc{rcs} 5.7. Therefore, you can almost surely not 8359worry about it. @xref{Keyword substitution}. 8360 8361@item -e[@var{logins}] 8362Might not work together with @sc{cvs}. Erase the login 8363names appearing in the comma-separated list 8364@var{logins} from the access list of the RCS file. If 8365@var{logins} is omitted, erase the entire access list. 8366There can be no space between @samp{-e} and its argument. 8367 8368@item -I 8369Run interactively, even if the standard input is not a 8370terminal. This option does not work with the 8371client/server @sc{cvs} and is likely to disappear in 8372a future release of @sc{cvs}. 8373 8374@item -i 8375Useless with @sc{cvs}. This creates and initializes a 8376new @sc{rcs} file, without depositing a revision. With 8377@sc{cvs}, add files with the @code{cvs add} command 8378(@pxref{Adding files}). 8379 8380@item -k@var{subst} 8381Set the default keyword 8382substitution to @var{subst}. @xref{Keyword 8383substitution}. Giving an explicit @samp{-k} option to 8384@code{cvs update}, @code{cvs export}, or @code{cvs 8385checkout} overrides this default. 8386 8387@item -l[@var{rev}] 8388Lock the revision with number @var{rev}. If a branch 8389is given, lock the latest revision on that branch. If 8390@var{rev} is omitted, lock the latest revision on the 8391default branch. There can be no space between 8392@samp{-l} and its argument. 8393 8394This can be used in conjunction with the 8395@file{rcslock.pl} script in the @file{contrib} 8396directory of the @sc{cvs} source distribution to 8397provide reserved checkouts (where only one user can be 8398editing a given file at a time). See the comments in 8399that file for details (and see the @file{README} file 8400in that directory for disclaimers about the unsupported 8401nature of contrib). According to comments in that 8402file, locking must set to strict (which is the default). 8403 8404@item -L 8405Set locking to strict. Strict locking means that the 8406owner of an RCS file is not exempt from locking for 8407checkin. For use with @sc{cvs}, strict locking must be 8408set; see the discussion under the @samp{-l} option above. 8409 8410@cindex Changing a log message 8411@cindex Replacing a log message 8412@cindex Correcting a log message 8413@cindex Fixing a log message 8414@cindex Log message, correcting 8415@item -m@var{rev}:@var{msg} 8416Replace the log message of revision @var{rev} with 8417@var{msg}. 8418 8419@c The rcs -M option, to suppress sending mail, has never been 8420@c documented as a cvs admin option. 8421 8422@item -N@var{name}[:[@var{rev}]] 8423Act like @samp{-n}, except override any previous 8424assignment of @var{name}. For use with magic branches, 8425see @ref{Magic branch numbers}. 8426 8427@item -n@var{name}[:[@var{rev}]] 8428Associate the symbolic name @var{name} with the branch 8429or revision @var{rev}. It is normally better to use 8430@samp{cvs tag} or @samp{cvs rtag} instead. Delete the 8431symbolic name if both @samp{:} and @var{rev} are 8432omitted; otherwise, print an error message if 8433@var{name} is already associated with another number. 8434If @var{rev} is symbolic, it is expanded before 8435association. A @var{rev} consisting of a branch number 8436followed by a @samp{.} stands for the current latest 8437revision in the branch. A @samp{:} with an empty 8438@var{rev} stands for the current latest revision on the 8439default branch, normally the trunk. For example, 8440@samp{cvs admin -n@var{name}:} associates @var{name} with the 8441current latest revision of all the RCS files; 8442this contrasts with @samp{cvs admin -n@var{name}:$} which 8443associates @var{name} with the revision numbers 8444extracted from keyword strings in the corresponding 8445working files. 8446 8447@cindex Deleting revisions 8448@cindex Outdating revisions 8449@cindex Saving space 8450@item -o@var{range} 8451Deletes (@dfn{outdates}) the revisions given by 8452@var{range}. 8453 8454Note that this command can be quite dangerous unless 8455you know @emph{exactly} what you are doing (for example 8456see the warnings below about how the 8457@var{rev1}:@var{rev2} syntax is confusing). 8458 8459If you are short on disc this option might help you. 8460But think twice before using it---there is no way short 8461of restoring the latest backup to undo this command! 8462If you delete different revisions than you planned, 8463either due to carelessness or (heaven forbid) a @sc{cvs} 8464bug, there is no opportunity to correct the error 8465before the revisions are deleted. It probably would be 8466a good idea to experiment on a copy of the repository 8467first. 8468 8469Specify @var{range} in one of the following ways: 8470 8471@table @code 8472@item @var{rev1}::@var{rev2} 8473Collapse all revisions between rev1 and rev2, so that 8474@sc{cvs} only stores the differences associated with going 8475from rev1 to rev2, not intermediate steps. For 8476example, after @samp{-o 1.3::1.5} one can retrieve 8477revision 1.3, revision 1.5, or the differences to get 8478from 1.3 to 1.5, but not the revision 1.4, or the 8479differences between 1.3 and 1.4. Other examples: 8480@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 8481effect, because there are no intermediate revisions to 8482remove. 8483 8484@item ::@var{rev} 8485Collapse revisions between the beginning of the branch 8486containing @var{rev} and @var{rev} itself. The 8487branchpoint and @var{rev} are left intact. For 8488example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 8489revision 1.3.2.5, and everything in between, but leaves 84901.3 and 1.3.2.6 intact. 8491 8492@item @var{rev}:: 8493Collapse revisions between @var{rev} and the end of the 8494branch containing @var{rev}. Revision @var{rev} is 8495left intact but the head revision is deleted. 8496 8497@item @var{rev} 8498Delete the revision @var{rev}. For example, @samp{-o 84991.3} is equivalent to @samp{-o 1.2::1.4}. 8500 8501@item @var{rev1}:@var{rev2} 8502Delete the revisions from @var{rev1} to @var{rev2}, 8503inclusive, on the same branch. One will not be able to 8504retrieve @var{rev1} or @var{rev2} or any of the 8505revisions in between. For example, the command 8506@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 8507It means to delete revisions up to, and including, the 8508tag R_1_02. But beware! If there are files that have not 8509changed between R_1_02 and R_1_03 the file will have 8510@emph{the same} numerical revision number assigned to 8511the tags R_1_02 and R_1_03. So not only will it be 8512impossible to retrieve R_1_02; R_1_03 will also have to 8513be restored from the tapes! In most cases you want to 8514specify @var{rev1}::@var{rev2} instead. 8515 8516@item :@var{rev} 8517Delete revisions from the beginning of the 8518branch containing @var{rev} up to and including 8519@var{rev}. 8520 8521@item @var{rev}: 8522Delete revisions from revision @var{rev}, including 8523@var{rev} itself, to the end of the branch containing 8524@var{rev}. 8525@end table 8526 8527None of the revisions to be deleted may have 8528branches or locks. 8529 8530If any of the revisions to be deleted have symbolic 8531names, and one specifies one of the @samp{::} syntaxes, 8532then @sc{cvs} will give an error and not delete any 8533revisions. If you really want to delete both the 8534symbolic names and the revisions, first delete the 8535symbolic names with @code{cvs tag -d}, then run 8536@code{cvs admin -o}. If one specifies the 8537non-@samp{::} syntaxes, then @sc{cvs} will delete the 8538revisions but leave the symbolic names pointing to 8539nonexistent revisions. This behavior is preserved for 8540compatibility with previous versions of @sc{cvs}, but 8541because it isn't very useful, in the future it may 8542change to be like the @samp{::} case. 8543 8544Due to the way @sc{cvs} handles branches @var{rev} 8545cannot be specified symbolically if it is a branch. 8546@xref{Magic branch numbers}, for an explanation. 8547@c FIXME: is this still true? I suspect not. 8548 8549Make sure that no-one has checked out a copy of the 8550revision you outdate. Strange things will happen if he 8551starts to edit it and tries to check it back in. For 8552this reason, this option is not a good way to take back 8553a bogus commit; commit a new revision undoing the bogus 8554change instead (@pxref{Merging two revisions}). 8555 8556@item -q 8557Run quietly; do not print diagnostics. 8558 8559@item -s@var{state}[:@var{rev}] 8560Useful with @sc{cvs}. Set the state attribute of the 8561revision @var{rev} to @var{state}. If @var{rev} is a 8562branch number, assume the latest revision on that 8563branch. If @var{rev} is omitted, assume the latest 8564revision on the default branch. Any identifier is 8565acceptable for @var{state}. A useful set of states is 8566@samp{Exp} (for experimental), @samp{Stab} (for 8567stable), and @samp{Rel} (for released). By default, 8568the state of a new revision is set to @samp{Exp} when 8569it is created. The state is visible in the output from 8570@var{cvs log} (@pxref{log}), and in the 8571@samp{$@i{}Log$} and @samp{$@i{}State$} keywords 8572(@pxref{Keyword substitution}). Note that @sc{cvs} 8573uses the @code{dead} state for its own purposes; to 8574take a file to or from the @code{dead} state use 8575commands like @code{cvs remove} and @code{cvs add}, not 8576@code{cvs admin -s}. 8577 8578@item -t[@var{file}] 8579Useful with @sc{cvs}. Write descriptive text from the 8580contents of the named @var{file} into the RCS file, 8581deleting the existing text. The @var{file} pathname 8582may not begin with @samp{-}. The descriptive text can be seen in the 8583output from @samp{cvs log} (@pxref{log}). 8584There can be no space between @samp{-t} and its argument. 8585 8586If @var{file} is omitted, 8587obtain the text from standard input, terminated by 8588end-of-file or by a line containing @samp{.} by itself. 8589Prompt for the text if interaction is possible; see 8590@samp{-I}. 8591 8592@item -t-@var{string} 8593Similar to @samp{-t@var{file}}. Write descriptive text 8594from the @var{string} into the @sc{rcs} file, deleting 8595the existing text. 8596There can be no space between @samp{-t} and its argument. 8597 8598@c The rcs -T option, do not update last-mod time for 8599@c minor changes, has never been documented as a 8600@c cvs admin option. 8601 8602@item -U 8603Set locking to non-strict. Non-strict locking means 8604that the owner of a file need not lock a revision for 8605checkin. For use with @sc{cvs}, strict locking must be 8606set; see the discussion under the @samp{-l} option 8607above. 8608 8609@item -u[@var{rev}] 8610See the option @samp{-l} above, for a discussion of 8611using this option with @sc{cvs}. Unlock the revision 8612with number @var{rev}. If a branch is given, unlock 8613the latest revision on that branch. If @var{rev} is 8614omitted, remove the latest lock held by the caller. 8615Normally, only the locker of a revision may unlock it; 8616somebody else unlocking a revision breaks the lock. 8617This causes the original locker to be sent a @code{commit} 8618notification (@pxref{Getting Notified}). 8619There can be no space between @samp{-u} and its argument. 8620 8621@item -V@var{n} 8622In previous versions of @sc{cvs}, this option meant to 8623write an @sc{rcs} file which would be acceptable to 8624@sc{rcs} version @var{n}, but it is now obsolete and 8625specifying it will produce an error. 8626@c Note that -V without an argument has never been 8627@c documented as a cvs admin option. 8628 8629@item -x@var{suffixes} 8630In previous versions of @sc{cvs}, this was documented 8631as a way of specifying the names of the @sc{rcs} 8632files. However, @sc{cvs} has always required that the 8633@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 8634this option has never done anything useful. 8635 8636@c The rcs -z option, to specify the timezone, has 8637@c never been documented as a cvs admin option. 8638@end table 8639 8640 8641@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8642@node checkout 8643@appendixsec checkout---Check out sources for editing 8644@cindex checkout (subcommand) 8645@cindex co (subcommand) 8646 8647@itemize @bullet 8648@item 8649Synopsis: checkout [options] modules@dots{} 8650@item 8651Requires: repository. 8652@item 8653Changes: working directory. 8654@item 8655Synonyms: co, get 8656@end itemize 8657 8658Create or update a working directory containing copies of the 8659source files specified by @var{modules}. You must execute 8660@code{checkout} before using most of the other @sc{cvs} 8661commands, since most of them operate on your working 8662directory. 8663 8664The @var{modules} are either 8665symbolic names for some 8666collection of source directories and files, or paths to 8667directories or files in the repository. The symbolic 8668names are defined in the @samp{modules} file. 8669@xref{modules}. 8670@c Needs an example, particularly of the non-"modules" 8671@c case but probably of both. 8672 8673@c FIXME: this seems like a very odd place to introduce 8674@c people to how CVS works. The bit about unreserved 8675@c checkouts is also misleading as it depends on how 8676@c things are set up. 8677Depending on the modules you specify, @code{checkout} may 8678recursively create directories and populate them with 8679the appropriate source files. You can then edit these 8680source files at any time (regardless of whether other 8681software developers are editing their own copies of the 8682sources); update them to include new changes applied by 8683others to the source repository; or commit your work as 8684a permanent change to the source repository. 8685 8686Note that @code{checkout} is used to create 8687directories. The top-level directory created is always 8688added to the directory where @code{checkout} is 8689invoked, and usually has the same name as the specified 8690module. In the case of a module alias, the created 8691sub-directory may have a different name, but you can be 8692sure that it will be a sub-directory, and that 8693@code{checkout} will show the relative path leading to 8694each file as it is extracted into your private work 8695area (unless you specify the @samp{-Q} global option). 8696 8697The files created by @code{checkout} are created 8698read-write, unless the @samp{-r} option to @sc{cvs} 8699(@pxref{Global options}) is specified, the 8700@code{CVSREAD} environment variable is specified 8701(@pxref{Environment variables}), or a watch is in 8702effect for that file (@pxref{Watches}). 8703 8704Note that running @code{checkout} on a directory that was already 8705built by a prior @code{checkout} is also permitted. 8706This is similar to specifying the @samp{-d} option 8707to the @code{update} command in the sense that new 8708directories that have been created in the repository 8709will appear in your work area. 8710However, @code{checkout} takes a module name whereas 8711@code{update} takes a directory name. Also 8712to use @code{checkout} this way it must be run from the 8713top level directory (where you originally ran 8714@code{checkout} from), so before you run 8715@code{checkout} to update an existing directory, don't 8716forget to change your directory to the top level 8717directory. 8718 8719For the output produced by the @code{checkout} command 8720see @ref{update output}. 8721 8722@menu 8723* checkout options:: checkout options 8724* checkout examples:: checkout examples 8725@end menu 8726 8727@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8728@node checkout options 8729@appendixsubsec checkout options 8730 8731These standard options are supported by @code{checkout} 8732(@pxref{Common options}, for a complete description of 8733them): 8734 8735@table @code 8736@item -D @var{date} 8737Use the most recent revision no later than @var{date}. 8738This option is sticky, and implies @samp{-P}. See 8739@ref{Sticky tags}, for more information on sticky tags/dates. 8740 8741@item -f 8742Only useful with the @samp{-D @var{date}} or @samp{-r 8743@var{tag}} flags. If no matching revision is found, 8744retrieve the most recent revision (instead of ignoring 8745the file). 8746 8747@item -k @var{kflag} 8748Process keywords according to @var{kflag}. See 8749@ref{Keyword substitution}. 8750This option is sticky; future updates of 8751this file in this working directory will use the same 8752@var{kflag}. The @code{status} command can be viewed 8753to see the sticky options. See @ref{Invoking CVS}, for 8754more information on the @code{status} command. 8755 8756@item -l 8757Local; run only in current working directory. 8758 8759@item -n 8760Do not run any checkout program (as specified 8761with the @samp{-o} option in the modules file; 8762@pxref{modules}). 8763 8764@item -P 8765Prune empty directories. See @ref{Moving directories}. 8766 8767@item -p 8768Pipe files to the standard output. 8769 8770@item -R 8771Checkout directories recursively. This option is on by default. 8772 8773@item -r @var{tag} 8774Use revision @var{tag}. This option is sticky, and implies @samp{-P}. 8775See @ref{Sticky tags}, for more information on sticky tags/dates. 8776@end table 8777 8778In addition to those, you can use these special command 8779options with @code{checkout}: 8780 8781@table @code 8782@item -A 8783Reset any sticky tags, dates, or @samp{-k} options. 8784See @ref{Sticky tags}, for more information on sticky tags/dates. 8785 8786@item -c 8787Copy the module file, sorted, to the standard output, 8788instead of creating or modifying any files or 8789directories in your working directory. 8790 8791@item -d @var{dir} 8792Create a directory called @var{dir} for the working 8793files, instead of using the module name. In general, 8794using this flag is equivalent to using @samp{mkdir 8795@var{dir}; cd @var{dir}} followed by the checkout 8796command without the @samp{-d} flag. 8797 8798There is an important exception, however. It is very 8799convenient when checking out a single item to have the 8800output appear in a directory that doesn't contain empty 8801intermediate directories. In this case @emph{only}, 8802@sc{cvs} tries to ``shorten'' pathnames to avoid those empty 8803directories. 8804 8805For example, given a module @samp{foo} that contains 8806the file @samp{bar.c}, the command @samp{cvs co -d dir 8807foo} will create directory @samp{dir} and place 8808@samp{bar.c} inside. Similarly, given a module 8809@samp{bar} which has subdirectory @samp{baz} wherein 8810there is a file @samp{quux.c}, the command @samp{cvs co 8811-d dir bar/baz} will create directory @samp{dir} and 8812place @samp{quux.c} inside. 8813 8814Using the @samp{-N} flag will defeat this behavior. 8815Given the same module definitions above, @samp{cvs co 8816-N -d dir foo} will create directories @samp{dir/foo} 8817and place @samp{bar.c} inside, while @samp{cvs co -N -d 8818dir bar/baz} will create directories @samp{dir/bar/baz} 8819and place @samp{quux.c} inside. 8820 8821@item -j @var{tag} 8822With two @samp{-j} options, merge changes from the 8823revision specified with the first @samp{-j} option to 8824the revision specified with the second @samp{j} option, 8825into the working directory. 8826 8827With one @samp{-j} option, merge changes from the 8828ancestor revision to the revision specified with the 8829@samp{-j} option, into the working directory. The 8830ancestor revision is the common ancestor of the 8831revision which the working directory is based on, and 8832the revision specified in the @samp{-j} option. 8833 8834In addition, each -j option can contain an optional 8835date specification which, when used with branches, can 8836limit the chosen revision to one within a specific 8837date. An optional date is specified by adding a colon 8838(:) to the tag: 8839@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 8840 8841@xref{Branching and merging}. 8842 8843@item -N 8844Only useful together with @samp{-d @var{dir}}. With 8845this option, @sc{cvs} will not ``shorten'' module paths 8846in your working directory when you check out a single 8847module. See the @samp{-d} flag for examples and a 8848discussion. 8849 8850@item -s 8851Like @samp{-c}, but include the status of all modules, 8852and sort it by the status string. @xref{modules}, for 8853info about the @samp{-s} option that is used inside the 8854modules file to set the module status. 8855@end table 8856 8857@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8858@node checkout examples 8859@appendixsubsec checkout examples 8860 8861Get a copy of the module @samp{tc}: 8862 8863@example 8864$ cvs checkout tc 8865@end example 8866 8867Get a copy of the module @samp{tc} as it looked one day 8868ago: 8869 8870@example 8871$ cvs checkout -D yesterday tc 8872@end example 8873 8874@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8875@node commit 8876@appendixsec commit---Check files into the repository 8877@cindex commit (subcommand) 8878 8879@itemize @bullet 8880@item 8881Synopsis: commit [-lnRf] [-m 'log_message' | 8882-F file] [-r revision] [files@dots{}] 8883@item 8884Requires: working directory, repository. 8885@item 8886Changes: repository. 8887@item 8888Synonym: ci 8889@end itemize 8890 8891Use @code{commit} when you want to incorporate changes 8892from your working source files into the source 8893repository. 8894 8895If you don't specify particular files to commit, all of 8896the files in your working current directory are 8897examined. @code{commit} is careful to change in the 8898repository only those files that you have really 8899changed. By default (or if you explicitly specify the 8900@samp{-R} option), files in subdirectories are also 8901examined and committed if they have changed; you can 8902use the @samp{-l} option to limit @code{commit} to the 8903current directory only. 8904 8905@code{commit} verifies that the selected files are up 8906to date with the current revisions in the source 8907repository; it will notify you, and exit without 8908committing, if any of the specified files must be made 8909current first with @code{update} (@pxref{update}). 8910@code{commit} does not call the @code{update} command 8911for you, but rather leaves that for you to do when the 8912time is right. 8913 8914When all is well, an editor is invoked to allow you to 8915enter a log message that will be written to one or more 8916logging programs (@pxref{modules}, and @pxref{loginfo}) 8917and placed in the @sc{rcs} file inside the 8918repository. This log message can be retrieved with the 8919@code{log} command; see @ref{log}. You can specify the 8920log message on the command line with the @samp{-m 8921@var{message}} option, and thus avoid the editor invocation, 8922or use the @samp{-F @var{file}} option to specify 8923that the argument file contains the log message. 8924 8925@menu 8926* commit options:: commit options 8927* commit examples:: commit examples 8928@end menu 8929 8930@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8931@node commit options 8932@appendixsubsec commit options 8933 8934These standard options are supported by @code{commit} 8935(@pxref{Common options}, for a complete description of 8936them): 8937 8938@table @code 8939@item -l 8940Local; run only in current working directory. 8941 8942@item -R 8943Commit directories recursively. This is on by default. 8944 8945@item -r @var{revision} 8946Commit to @var{revision}. @var{revision} must be 8947either a branch, or a revision on the main trunk that 8948is higher than any existing revision number 8949(@pxref{Assigning revisions}). You 8950cannot commit to a specific revision on a branch. 8951@c FIXME: Need xref for branch case. 8952@end table 8953 8954@code{commit} also supports these options: 8955 8956@table @code 8957@item -F @var{file} 8958Read the log message from @var{file}, instead 8959of invoking an editor. 8960 8961@item -f 8962Note that this is not the standard behavior of 8963the @samp{-f} option as defined in @ref{Common options}. 8964 8965Force @sc{cvs} to commit a new revision even if you haven't 8966made any changes to the file. If the current revision 8967of @var{file} is 1.7, then the following two commands 8968are equivalent: 8969 8970@example 8971$ cvs commit -f @var{file} 8972$ cvs commit -r 1.8 @var{file} 8973@end example 8974 8975@c This is odd, but it's how CVS has worked for some 8976@c time. 8977The @samp{-f} option disables recursion (i.e., it 8978implies @samp{-l}). To force @sc{cvs} to commit a new 8979revision for all files in all subdirectories, you must 8980use @samp{-f -R}. 8981 8982@item -m @var{message} 8983Use @var{message} as the log message, instead of 8984invoking an editor. 8985@end table 8986 8987@need 2000 8988@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8989@node commit examples 8990@appendixsubsec commit examples 8991 8992@c FIXME: this material wants to be somewhere 8993@c in "Branching and merging". 8994 8995@appendixsubsubsec Committing to a branch 8996 8997You can commit to a branch revision (one that has an 8998even number of dots) with the @samp{-r} option. To 8999create a branch revision, use the @samp{-b} option 9000of the @code{rtag} or @code{tag} commands 9001(@pxref{Branching and merging}). Then, either @code{checkout} or 9002@code{update} can be used to base your sources on the 9003newly created branch. From that point on, all 9004@code{commit} changes made within these working sources 9005will be automatically added to a branch revision, 9006thereby not disturbing main-line development in any 9007way. For example, if you had to create a patch to the 90081.2 version of the product, even though the 2.0 version 9009is already under development, you might do: 9010 9011@example 9012$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 9013$ cvs checkout -r FCS1_2_Patch product_module 9014$ cd product_module 9015[[ hack away ]] 9016$ cvs commit 9017@end example 9018 9019@noindent 9020This works automatically since the @samp{-r} option is 9021sticky. 9022 9023@appendixsubsubsec Creating the branch after editing 9024 9025Say you have been working on some extremely 9026experimental software, based on whatever revision you 9027happened to checkout last week. If others in your 9028group would like to work on this software with you, but 9029without disturbing main-line development, you could 9030commit your change to a new branch. Others can then 9031checkout your experimental stuff and utilize the full 9032benefit of @sc{cvs} conflict resolution. The scenario might 9033look like: 9034 9035@c FIXME: Should we be recommending tagging the branchpoint? 9036@example 9037[[ hacked sources are present ]] 9038$ cvs tag -b EXPR1 9039$ cvs update -r EXPR1 9040$ cvs commit 9041@end example 9042 9043The @code{update} command will make the @samp{-r 9044EXPR1} option sticky on all files. Note that your 9045changes to the files will never be removed by the 9046@code{update} command. The @code{commit} will 9047automatically commit to the correct branch, because the 9048@samp{-r} is sticky. You could also do like this: 9049 9050@c FIXME: Should we be recommending tagging the branchpoint? 9051@example 9052[[ hacked sources are present ]] 9053$ cvs tag -b EXPR1 9054$ cvs commit -r EXPR1 9055@end example 9056 9057@noindent 9058but then, only those files that were changed by you 9059will have the @samp{-r EXPR1} sticky flag. If you hack 9060away, and commit without specifying the @samp{-r EXPR1} 9061flag, some files may accidentally end up on the main 9062trunk. 9063 9064To work with you on the experimental change, others 9065would simply do 9066 9067@example 9068$ cvs checkout -r EXPR1 whatever_module 9069@end example 9070 9071@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9072@node diff 9073@appendixsec diff---Show differences between revisions 9074@cindex diff (subcommand) 9075 9076@itemize @bullet 9077@item 9078Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}] 9079@item 9080Requires: working directory, repository. 9081@item 9082Changes: nothing. 9083@end itemize 9084 9085The @code{diff} command is used to compare different 9086revisions of files. The default action is to compare 9087your working files with the revisions they were based 9088on, and report any differences that are found. 9089 9090If any file names are given, only those files are 9091compared. If any directories are given, all files 9092under them will be compared. 9093 9094The exit status for diff is different than for other 9095@sc{cvs} commands; for details @ref{Exit status}. 9096 9097@menu 9098* diff options:: diff options 9099* diff examples:: diff examples 9100@end menu 9101 9102@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9103@node diff options 9104@appendixsubsec diff options 9105 9106These standard options are supported by @code{diff} 9107(@pxref{Common options}, for a complete description of 9108them): 9109 9110@table @code 9111@item -D @var{date} 9112Use the most recent revision no later than @var{date}. 9113See @samp{-r} for how this affects the comparison. 9114 9115@item -k @var{kflag} 9116Process keywords according to @var{kflag}. See 9117@ref{Keyword substitution}. 9118 9119@item -l 9120Local; run only in current working directory. 9121 9122@item -R 9123Examine directories recursively. This option is on by 9124default. 9125 9126@item -r @var{tag} 9127Compare with revision @var{tag}. Zero, one or two 9128@samp{-r} options can be present. With no @samp{-r} 9129option, the working file will be compared with the 9130revision it was based on. With one @samp{-r}, that 9131revision will be compared to your current working file. 9132With two @samp{-r} options those two revisions will be 9133compared (and your working file will not affect the 9134outcome in any way). 9135@c We should be a lot more explicit, with examples, 9136@c about the difference between "cvs diff" and "cvs 9137@c diff -r HEAD". This often confuses new users. 9138 9139One or both @samp{-r} options can be replaced by a 9140@samp{-D @var{date}} option, described above. 9141@end table 9142 9143@c Conceptually, this is a disaster. There are 3 9144@c zillion diff formats that we support via the diff 9145@c library. It is not obvious to me that we should 9146@c document them all. Maybe just the most common ones 9147@c like -c and -u, and think about phasing out the 9148@c obscure ones. 9149@c FIXCVS: also should be a way to specify an external 9150@c diff program (which can be different for different 9151@c file types) and pass through 9152@c arbitrary options, so that the user can do 9153@c "--pass=-Z --pass=foo" or something even if CVS 9154@c doesn't know about the "-Z foo" option to diff. 9155@c This would fit nicely with deprecating/eliminating 9156@c the obscure options of the diff library, because it 9157@c would let people specify an external GNU diff if 9158@c they are into that sort of thing. 9159The following options specify the format of the 9160output. They have the same meaning as in GNU diff. 9161Most options have two equivalent names, one of which is a single letter 9162preceded by @samp{-}, and the other of which is a long name preceded by 9163@samp{--}. 9164 9165@table @samp 9166@item -@var{lines} 9167Show @var{lines} (an integer) lines of context. This option does not 9168specify an output format by itself; it has no effect unless it is 9169combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9170operation, @code{patch} typically needs at least two lines of context. 9171 9172@item -a 9173Treat all files as text and compare them line-by-line, even if they 9174do not seem to be text. 9175 9176@item -b 9177Ignore trailing white space and consider all other sequences of one or 9178more white space characters to be equivalent. 9179 9180@item -B 9181Ignore changes that just insert or delete blank lines. 9182 9183@item --binary 9184Read and write data in binary mode. 9185 9186@item --brief 9187Report only whether the files differ, not the details of the 9188differences. 9189 9190@item -c 9191Use the context output format. 9192 9193@item -C @var{lines} 9194@itemx --context@r{[}=@var{lines}@r{]} 9195Use the context output format, showing @var{lines} (an integer) lines of 9196context, or three if @var{lines} is not given. 9197For proper operation, @code{patch} typically needs at least two lines of 9198context. 9199 9200@item --changed-group-format=@var{format} 9201Use @var{format} to output a line group containing differing lines from 9202both files in if-then-else format. @xref{Line group formats}. 9203 9204@item -d 9205Change the algorithm to perhaps find a smaller set of changes. This makes 9206@code{diff} slower (sometimes much slower). 9207 9208@item -e 9209@itemx --ed 9210Make output that is a valid @code{ed} script. 9211 9212@item --expand-tabs 9213Expand tabs to spaces in the output, to preserve the alignment of tabs 9214in the input files. 9215 9216@item -f 9217Make output that looks vaguely like an @code{ed} script but has changes 9218in the order they appear in the file. 9219 9220@item -F @var{regexp} 9221In context and unified format, for each hunk of differences, show some 9222of the last preceding line that matches @var{regexp}. 9223 9224@item --forward-ed 9225Make output that looks vaguely like an @code{ed} script but has changes 9226in the order they appear in the file. 9227 9228@item -H 9229Use heuristics to speed handling of large files that have numerous 9230scattered small changes. 9231 9232@item --horizon-lines=@var{lines} 9233Do not discard the last @var{lines} lines of the common prefix 9234and the first @var{lines} lines of the common suffix. 9235 9236@item -i 9237Ignore changes in case; consider upper- and lower-case letters 9238equivalent. 9239 9240@item -I @var{regexp} 9241Ignore changes that just insert or delete lines that match @var{regexp}. 9242 9243@item --ifdef=@var{name} 9244Make merged if-then-else output using @var{name}. 9245 9246@item --ignore-all-space 9247Ignore white space when comparing lines. 9248 9249@item --ignore-blank-lines 9250Ignore changes that just insert or delete blank lines. 9251 9252@item --ignore-case 9253Ignore changes in case; consider upper- and lower-case to be the same. 9254 9255@item --ignore-matching-lines=@var{regexp} 9256Ignore changes that just insert or delete lines that match @var{regexp}. 9257 9258@item --ignore-space-change 9259Ignore trailing white space and consider all other sequences of one or 9260more white space characters to be equivalent. 9261 9262@item --initial-tab 9263Output a tab rather than a space before the text of a line in normal or 9264context format. This causes the alignment of tabs in the line to look 9265normal. 9266 9267@item -L @var{label} 9268Use @var{label} instead of the file name in the context format 9269and unified format headers. 9270 9271@item --label=@var{label} 9272Use @var{label} instead of the file name in the context format 9273and unified format headers. 9274 9275@item --left-column 9276Print only the left column of two common lines in side by side format. 9277 9278@item --line-format=@var{format} 9279Use @var{format} to output all input lines in if-then-else format. 9280@xref{Line formats}. 9281 9282@item --minimal 9283Change the algorithm to perhaps find a smaller set of changes. This 9284makes @code{diff} slower (sometimes much slower). 9285 9286@item -n 9287Output RCS-format diffs; like @samp{-f} except that each command 9288specifies the number of lines affected. 9289 9290@item -N 9291@itemx --new-file 9292In directory comparison, if a file is found in only one directory, 9293treat it as present but empty in the other directory. 9294 9295@item --new-group-format=@var{format} 9296Use @var{format} to output a group of lines taken from just the second 9297file in if-then-else format. @xref{Line group formats}. 9298 9299@item --new-line-format=@var{format} 9300Use @var{format} to output a line taken from just the second file in 9301if-then-else format. @xref{Line formats}. 9302 9303@item --old-group-format=@var{format} 9304Use @var{format} to output a group of lines taken from just the first 9305file in if-then-else format. @xref{Line group formats}. 9306 9307@item --old-line-format=@var{format} 9308Use @var{format} to output a line taken from just the first file in 9309if-then-else format. @xref{Line formats}. 9310 9311@item -p 9312Show which C function each change is in. 9313 9314@item --rcs 9315Output RCS-format diffs; like @samp{-f} except that each command 9316specifies the number of lines affected. 9317 9318@item --report-identical-files 9319@itemx -s 9320Report when two files are the same. 9321 9322@item --show-c-function 9323Show which C function each change is in. 9324 9325@item --show-function-line=@var{regexp} 9326In context and unified format, for each hunk of differences, show some 9327of the last preceding line that matches @var{regexp}. 9328 9329@item --side-by-side 9330Use the side by side output format. 9331 9332@item --speed-large-files 9333Use heuristics to speed handling of large files that have numerous 9334scattered small changes. 9335 9336@item --suppress-common-lines 9337Do not print common lines in side by side format. 9338 9339@item -t 9340Expand tabs to spaces in the output, to preserve the alignment of tabs 9341in the input files. 9342 9343@item -T 9344Output a tab rather than a space before the text of a line in normal or 9345context format. This causes the alignment of tabs in the line to look 9346normal. 9347 9348@item --text 9349Treat all files as text and compare them line-by-line, even if they 9350do not appear to be text. 9351 9352@item -u 9353Use the unified output format. 9354 9355@item --unchanged-group-format=@var{format} 9356Use @var{format} to output a group of common lines taken from both files 9357in if-then-else format. @xref{Line group formats}. 9358 9359@item --unchanged-line-format=@var{format} 9360Use @var{format} to output a line common to both files in if-then-else 9361format. @xref{Line formats}. 9362 9363@item -U @var{lines} 9364@itemx --unified@r{[}=@var{lines}@r{]} 9365Use the unified output format, showing @var{lines} (an integer) lines of 9366context, or three if @var{lines} is not given. 9367For proper operation, @code{patch} typically needs at least two lines of 9368context. 9369 9370@item -w 9371Ignore white space when comparing lines. 9372 9373@item -W @var{columns} 9374@itemx --width=@var{columns} 9375Use an output width of @var{columns} in side by side format. 9376 9377@item -y 9378Use the side by side output format. 9379@end table 9380 9381@menu 9382* Line group formats:: Line group formats 9383* Line formats:: Line formats 9384@end menu 9385 9386@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9387@node Line group formats 9388@appendixsubsubsec Line group formats 9389 9390Line group formats let you specify formats suitable for many 9391applications that allow if-then-else input, including programming 9392languages and text formatting languages. A line group format specifies 9393the output format for a contiguous group of similar lines. 9394 9395For example, the following command compares the TeX file @file{myfile} 9396with the original version from the repository, 9397and outputs a merged file in which old regions are 9398surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 9399regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 9400 9401@example 9402cvs diff \ 9403 --old-group-format='\begin@{em@} 9404%<\end@{em@} 9405' \ 9406 --new-group-format='\begin@{bf@} 9407%>\end@{bf@} 9408' \ 9409 myfile 9410@end example 9411 9412The following command is equivalent to the above example, but it is a 9413little more verbose, because it spells out the default line group formats. 9414 9415@example 9416cvs diff \ 9417 --old-group-format='\begin@{em@} 9418%<\end@{em@} 9419' \ 9420 --new-group-format='\begin@{bf@} 9421%>\end@{bf@} 9422' \ 9423 --unchanged-group-format='%=' \ 9424 --changed-group-format='\begin@{em@} 9425%<\end@{em@} 9426\begin@{bf@} 9427%>\end@{bf@} 9428' \ 9429 myfile 9430@end example 9431 9432Here is a more advanced example, which outputs a diff listing with 9433headers containing line numbers in a ``plain English'' style. 9434 9435@example 9436cvs diff \ 9437 --unchanged-group-format='' \ 9438 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 9439%<' \ 9440 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 9441%>' \ 9442 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 9443%<-------- to: 9444%>' \ 9445 myfile 9446@end example 9447 9448To specify a line group format, use one of the options 9449listed below. You can specify up to four line group formats, one for 9450each kind of line group. You should quote @var{format}, because it 9451typically contains shell metacharacters. 9452 9453@table @samp 9454@item --old-group-format=@var{format} 9455These line groups are hunks containing only lines from the first file. 9456The default old group format is the same as the changed group format if 9457it is specified; otherwise it is a format that outputs the line group as-is. 9458 9459@item --new-group-format=@var{format} 9460These line groups are hunks containing only lines from the second 9461file. The default new group format is same as the changed group 9462format if it is specified; otherwise it is a format that outputs the 9463line group as-is. 9464 9465@item --changed-group-format=@var{format} 9466These line groups are hunks containing lines from both files. The 9467default changed group format is the concatenation of the old and new 9468group formats. 9469 9470@item --unchanged-group-format=@var{format} 9471These line groups contain lines common to both files. The default 9472unchanged group format is a format that outputs the line group as-is. 9473@end table 9474 9475In a line group format, ordinary characters represent themselves; 9476conversion specifications start with @samp{%} and have one of the 9477following forms. 9478 9479@table @samp 9480@item %< 9481stands for the lines from the first file, including the trailing newline. 9482Each line is formatted according to the old line format (@pxref{Line formats}). 9483 9484@item %> 9485stands for the lines from the second file, including the trailing newline. 9486Each line is formatted according to the new line format. 9487 9488@item %= 9489stands for the lines common to both files, including the trailing newline. 9490Each line is formatted according to the unchanged line format. 9491 9492@item %% 9493stands for @samp{%}. 9494 9495@item %c'@var{C}' 9496where @var{C} is a single character, stands for @var{C}. 9497@var{C} may not be a backslash or an apostrophe. 9498For example, @samp{%c':'} stands for a colon, even inside 9499the then-part of an if-then-else format, which a colon would 9500normally terminate. 9501 9502@item %c'\@var{O}' 9503where @var{O} is a string of 1, 2, or 3 octal digits, 9504stands for the character with octal code @var{O}. 9505For example, @samp{%c'\0'} stands for a null character. 9506 9507@item @var{F}@var{n} 9508where @var{F} is a @code{printf} conversion specification and @var{n} is one 9509of the following letters, stands for @var{n}'s value formatted with @var{F}. 9510 9511@table @samp 9512@item e 9513The line number of the line just before the group in the old file. 9514 9515@item f 9516The line number of the first line in the group in the old file; 9517equals @var{e} + 1. 9518 9519@item l 9520The line number of the last line in the group in the old file. 9521 9522@item m 9523The line number of the line just after the group in the old file; 9524equals @var{l} + 1. 9525 9526@item n 9527The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 9528 9529@item E, F, L, M, N 9530Likewise, for lines in the new file. 9531 9532@end table 9533 9534The @code{printf} conversion specification can be @samp{%d}, 9535@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 9536lower case hexadecimal, or upper case hexadecimal output 9537respectively. After the @samp{%} the following options can appear in 9538sequence: a @samp{-} specifying left-justification; an integer 9539specifying the minimum field width; and a period followed by an 9540optional integer specifying the minimum number of digits. 9541For example, @samp{%5dN} prints the number of new lines in the group 9542in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 9543 9544@item (@var{A}=@var{B}?@var{T}:@var{E}) 9545If @var{A} equals @var{B} then @var{T} else @var{E}. 9546@var{A} and @var{B} are each either a decimal constant 9547or a single letter interpreted as above. 9548This format spec is equivalent to @var{T} if 9549@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 9550 9551For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 9552@samp{no lines} if @var{N} (the number of lines in the group in the 9553new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 9554otherwise. 9555@end table 9556 9557@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9558@node Line formats 9559@appendixsubsubsec Line formats 9560 9561Line formats control how each line taken from an input file is 9562output as part of a line group in if-then-else format. 9563 9564For example, the following command outputs text with a one-column 9565change indicator to the left of the text. The first column of output 9566is @samp{-} for deleted lines, @samp{|} for added lines, and a space 9567for unchanged lines. The formats contain newline characters where 9568newlines are desired on output. 9569 9570@example 9571cvs diff \ 9572 --old-line-format='-%l 9573' \ 9574 --new-line-format='|%l 9575' \ 9576 --unchanged-line-format=' %l 9577' \ 9578 myfile 9579@end example 9580 9581To specify a line format, use one of the following options. You should 9582quote @var{format}, since it often contains shell metacharacters. 9583 9584@table @samp 9585@item --old-line-format=@var{format} 9586formats lines just from the first file. 9587 9588@item --new-line-format=@var{format} 9589formats lines just from the second file. 9590 9591@item --unchanged-line-format=@var{format} 9592formats lines common to both files. 9593 9594@item --line-format=@var{format} 9595formats all lines; in effect, it sets all three above options simultaneously. 9596@end table 9597 9598In a line format, ordinary characters represent themselves; 9599conversion specifications start with @samp{%} and have one of the 9600following forms. 9601 9602@table @samp 9603@item %l 9604stands for the contents of the line, not counting its trailing 9605newline (if any). This format ignores whether the line is incomplete. 9606 9607@item %L 9608stands for the contents of the line, including its trailing newline 9609(if any). If a line is incomplete, this format preserves its 9610incompleteness. 9611 9612@item %% 9613stands for @samp{%}. 9614 9615@item %c'@var{C}' 9616where @var{C} is a single character, stands for @var{C}. 9617@var{C} may not be a backslash or an apostrophe. 9618For example, @samp{%c':'} stands for a colon. 9619 9620@item %c'\@var{O}' 9621where @var{O} is a string of 1, 2, or 3 octal digits, 9622stands for the character with octal code @var{O}. 9623For example, @samp{%c'\0'} stands for a null character. 9624 9625@item @var{F}n 9626where @var{F} is a @code{printf} conversion specification, 9627stands for the line number formatted with @var{F}. 9628For example, @samp{%.5dn} prints the line number using the 9629@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 9630more about printf conversion specifications. 9631 9632@end table 9633 9634The default line format is @samp{%l} followed by a newline character. 9635 9636If the input contains tab characters and it is important that they line 9637up on output, you should ensure that @samp{%l} or @samp{%L} in a line 9638format is just after a tab stop (e.g.@: by preceding @samp{%l} or 9639@samp{%L} with a tab character), or you should use the @samp{-t} or 9640@samp{--expand-tabs} option. 9641 9642Taken together, the line and line group formats let you specify many 9643different formats. For example, the following command uses a format 9644similar to @code{diff}'s normal format. You can tailor this command 9645to get fine control over @code{diff}'s output. 9646 9647@example 9648cvs diff \ 9649 --old-line-format='< %l 9650' \ 9651 --new-line-format='> %l 9652' \ 9653 --old-group-format='%df%(f=l?:,%dl)d%dE 9654%<' \ 9655 --new-group-format='%dea%dF%(F=L?:,%dL) 9656%>' \ 9657 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 9658%<--- 9659%>' \ 9660 --unchanged-group-format='' \ 9661 myfile 9662@end example 9663 9664@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9665@node diff examples 9666@appendixsubsec diff examples 9667 9668The following line produces a Unidiff (@samp{-u} flag) 9669between revision 1.14 and 1.19 of 9670@file{backend.c}. Due to the @samp{-kk} flag no 9671keywords are substituted, so differences that only depend 9672on keyword substitution are ignored. 9673 9674@example 9675$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 9676@end example 9677 9678Suppose the experimental branch EXPR1 was based on a 9679set of files tagged RELEASE_1_0. To see what has 9680happened on that branch, the following can be used: 9681 9682@example 9683$ cvs diff -r RELEASE_1_0 -r EXPR1 9684@end example 9685 9686A command like this can be used to produce a context 9687diff between two releases: 9688 9689@example 9690$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 9691@end example 9692 9693If you are maintaining ChangeLogs, a command like the following 9694just before you commit your changes may help you write 9695the ChangeLog entry. All local modifications that have 9696not yet been committed will be printed. 9697 9698@example 9699$ cvs diff -u | less 9700@end example 9701 9702@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9703@node export 9704@appendixsec export---Export sources from CVS, similar to checkout 9705@cindex export (subcommand) 9706 9707@itemize @bullet 9708@item 9709Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{} 9710@item 9711Requires: repository. 9712@item 9713Changes: current directory. 9714@end itemize 9715 9716This command is a variant of @code{checkout}; use it 9717when you want a copy of the source for module without 9718the @sc{cvs} administrative directories. For example, you 9719might use @code{export} to prepare source for shipment 9720off-site. This command requires that you specify a 9721date or tag (with @samp{-D} or @samp{-r}), so that you 9722can count on reproducing the source you ship to others 9723(and thus it always prunes empty directories). 9724 9725One often would like to use @samp{-kv} with @code{cvs 9726export}. This causes any keywords to be 9727expanded such that an import done at some other site 9728will not lose the keyword revision information. But be 9729aware that doesn't handle an export containing binary 9730files correctly. Also be aware that after having used 9731@samp{-kv}, one can no longer use the @code{ident} 9732command (which is part of the @sc{rcs} suite---see 9733ident(1)) which looks for keyword strings. If 9734you want to be able to use @code{ident} you must not 9735use @samp{-kv}. 9736 9737@menu 9738* export options:: export options 9739@end menu 9740 9741@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9742@node export options 9743@appendixsubsec export options 9744 9745These standard options are supported by @code{export} 9746(@pxref{Common options}, for a complete description of 9747them): 9748 9749@table @code 9750@item -D @var{date} 9751Use the most recent revision no later than @var{date}. 9752 9753@item -f 9754If no matching revision is found, retrieve the most 9755recent revision (instead of ignoring the file). 9756 9757@item -l 9758Local; run only in current working directory. 9759 9760@item -n 9761Do not run any checkout program. 9762 9763@item -R 9764Export directories recursively. This is on by default. 9765 9766@item -r @var{tag} 9767Use revision @var{tag}. 9768@end table 9769 9770In addition, these options (that are common to 9771@code{checkout} and @code{export}) are also supported: 9772 9773@table @code 9774@item -d @var{dir} 9775Create a directory called @var{dir} for the working 9776files, instead of using the module name. 9777@xref{checkout options}, for complete details on how 9778@sc{cvs} handles this flag. 9779 9780@item -k @var{subst} 9781Set keyword expansion mode (@pxref{Substitution modes}). 9782 9783@item -N 9784Only useful together with @samp{-d @var{dir}}. 9785@xref{checkout options}, for complete details on how 9786@sc{cvs} handles this flag. 9787@end table 9788 9789 9790@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9791@node history 9792@appendixsec history---Show status of files and users 9793@cindex history (subcommand) 9794 9795@itemize @bullet 9796@item 9797Synopsis: history [-report] [-flags] [-options args] [files@dots{}] 9798@item 9799Requires: the file @file{$CVSROOT/CVSROOT/history} 9800@item 9801Changes: nothing. 9802@end itemize 9803 9804@sc{cvs} can keep a history file that tracks each use of the 9805@code{checkout}, @code{commit}, @code{rtag}, 9806@code{update}, and @code{release} commands. You can 9807use @code{history} to display this information in 9808various formats. 9809 9810Logging must be enabled by creating the file 9811@file{$CVSROOT/CVSROOT/history}. 9812 9813@strong{Note: @code{history} uses @samp{-f}, @samp{-l}, 9814@samp{-n}, and @samp{-p} in ways that conflict with the 9815normal use inside @sc{cvs} (@pxref{Common options}).} 9816 9817@menu 9818* history options:: history options 9819@end menu 9820 9821@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9822@node history options 9823@appendixsubsec history options 9824 9825Several options (shown above as @samp{-report}) control what 9826kind of report is generated: 9827 9828@table @code 9829@item -c 9830Report on each time commit was used (i.e., each time 9831the repository was modified). 9832 9833@item -e 9834Everything (all record types). Equivalent to 9835specifying @samp{-x} with all record types. Of course, 9836@samp{-e} will also include record types which are 9837added in a future version of @sc{cvs}; if you are 9838writing a script which can only handle certain record 9839types, you'll want to specify @samp{-x}. 9840 9841@item -m @var{module} 9842Report on a particular module. (You can meaningfully 9843use @samp{-m} more than once on the command line.) 9844 9845@item -o 9846Report on checked-out modules. This is the default report type. 9847 9848@item -T 9849Report on all tags. 9850 9851@item -x @var{type} 9852Extract a particular set of record types @var{type} from the @sc{cvs} 9853history. The types are indicated by single letters, 9854which you may specify in combination. 9855 9856Certain commands have a single record type: 9857 9858@table @code 9859@item F 9860release 9861@item O 9862checkout 9863@item E 9864export 9865@item T 9866rtag 9867@end table 9868 9869@noindent 9870One of four record types may result from an update: 9871 9872@table @code 9873@item C 9874A merge was necessary but collisions were 9875detected (requiring manual merging). 9876@item G 9877A merge was necessary and it succeeded. 9878@item U 9879A working file was copied from the repository. 9880@item W 9881The working copy of a file was deleted during 9882update (because it was gone from the repository). 9883@end table 9884 9885@noindent 9886One of three record types results from commit: 9887 9888@table @code 9889@item A 9890A file was added for the first time. 9891@item M 9892A file was modified. 9893@item R 9894A file was removed. 9895@end table 9896@end table 9897 9898The options shown as @samp{-flags} constrain or expand 9899the report without requiring option arguments: 9900 9901@table @code 9902@item -a 9903Show data for all users (the default is to show data 9904only for the user executing @code{history}). 9905 9906@item -l 9907Show last modification only. 9908 9909@item -w 9910Show only the records for modifications done from the 9911same working directory where @code{history} is 9912executing. 9913@end table 9914 9915The options shown as @samp{-options @var{args}} constrain the report 9916based on an argument: 9917 9918@table @code 9919@item -b @var{str} 9920Show data back to a record containing the string 9921@var{str} in either the module name, the file name, or 9922the repository path. 9923 9924@item -D @var{date} 9925Show data since @var{date}. This is slightly different 9926from the normal use of @samp{-D @var{date}}, which 9927selects the newest revision older than @var{date}. 9928 9929@item -f @var{file} 9930Show data for a particular file 9931(you can specify several @samp{-f} options on the same command line). 9932This is equivalent to specifying the file on the command line. 9933 9934@item -n @var{module} 9935Show data for a particular module 9936(you can specify several @samp{-n} options on the same command line). 9937 9938@item -p @var{repository} 9939Show data for a particular source repository (you 9940can specify several @samp{-p} options on the same command 9941line). 9942 9943@item -r @var{rev} 9944Show records referring to revisions since the revision 9945or tag named @var{rev} appears in individual @sc{rcs} 9946files. Each @sc{rcs} file is searched for the revision or 9947tag. 9948 9949@item -t @var{tag} 9950Show records since tag @var{tag} was last added to the 9951history file. This differs from the @samp{-r} flag 9952above in that it reads only the history file, not the 9953@sc{rcs} files, and is much faster. 9954 9955@item -u @var{name} 9956Show records for user @var{name}. 9957 9958@item -z @var{timezone} 9959Show times in the selected records using the specified 9960time zone instead of UTC. 9961@end table 9962 9963 9964@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9965@node import 9966@appendixsec import---Import sources into CVS, using vendor branches 9967@cindex import (subcommand) 9968 9969@c FIXME: This node is way too long for one which has subnodes. 9970 9971@itemize @bullet 9972@item 9973Synopsis: import [-options] repository vendortag releasetag@dots{} 9974@item 9975Requires: Repository, source distribution directory. 9976@item 9977Changes: repository. 9978@end itemize 9979 9980Use @code{import} to incorporate an entire source 9981distribution from an outside source (e.g., a source 9982vendor) into your source repository directory. You can 9983use this command both for initial creation of a 9984repository, and for wholesale updates to the module 9985from the outside source. @xref{Tracking sources}, for 9986a discussion on this subject. 9987 9988The @var{repository} argument gives a directory name 9989(or a path to a directory) under the @sc{cvs} root directory 9990for repositories; if the directory did not exist, 9991import creates it. 9992 9993When you use import for updates to source that has been 9994modified in your source repository (since a prior 9995import), it will notify you of any files that conflict 9996in the two branches of development; use @samp{checkout 9997-j} to reconcile the differences, as import instructs 9998you to do. 9999 10000If @sc{cvs} decides a file should be ignored 10001(@pxref{cvsignore}), it does not import it and prints 10002@samp{I } followed by the filename (@pxref{import output}, for a 10003complete description of the output). 10004 10005If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 10006any file whose names match the specifications in that 10007file will be treated as packages and the appropriate 10008filtering will be performed on the file/directory 10009before being imported. @xref{Wrappers}. 10010 10011The outside source is saved in a first-level 10012branch, by default 1.1.1. Updates are leaves of this 10013branch; for example, files from the first imported 10014collection of source will be revision 1.1.1.1, then 10015files from the first imported update will be revision 100161.1.1.2, and so on. 10017 10018At least three arguments are required. 10019@var{repository} is needed to identify the collection 10020of source. @var{vendortag} is a tag for the entire 10021branch (e.g., for 1.1.1). You must also specify at 10022least one @var{releasetag} to identify the files at 10023the leaves created each time you execute @code{import}. 10024 10025@c I'm not completely sure this belongs here. But 10026@c we need to say it _somewhere_ reasonably obvious; it 10027@c is a common misconception among people first learning CVS 10028Note that @code{import} does @emph{not} change the 10029directory in which you invoke it. In particular, it 10030does not set up that directory as a @sc{cvs} working 10031directory; if you want to work with the sources import 10032them first and then check them out into a different 10033directory (@pxref{Getting the source}). 10034 10035@menu 10036* import options:: import options 10037* import output:: import output 10038* import examples:: import examples 10039@end menu 10040 10041@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10042@node import options 10043@appendixsubsec import options 10044 10045This standard option is supported by @code{import} 10046(@pxref{Common options}, for a complete description): 10047 10048@table @code 10049@item -m @var{message} 10050Use @var{message} as log information, instead of 10051invoking an editor. 10052@end table 10053 10054There are the following additional special options. 10055 10056@table @code 10057@item -b @var{branch} 10058See @ref{Multiple vendor branches}. 10059 10060@item -k @var{subst} 10061Indicate the keyword expansion mode desired. This 10062setting will apply to all files created during the 10063import, but not to any files that previously existed in 10064the repository. See @ref{Substitution modes}, for a 10065list of valid @samp{-k} settings. 10066 10067@item -I @var{name} 10068Specify file names that should be ignored during 10069import. You can use this option repeatedly. To avoid 10070ignoring any files at all (even those ignored by 10071default), specify `-I !'. 10072 10073@var{name} can be a file name pattern of the same type 10074that you can specify in the @file{.cvsignore} file. 10075@xref{cvsignore}. 10076@c -- Is this really true? 10077 10078@item -W @var{spec} 10079Specify file names that should be filtered during 10080import. You can use this option repeatedly. 10081 10082@var{spec} can be a file name pattern of the same type 10083that you can specify in the @file{.cvswrappers} 10084file. @xref{Wrappers}. 10085@end table 10086 10087@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10088@node import output 10089@appendixsubsec import output 10090 10091@code{import} keeps you informed of its progress by printing a line 10092for each file, preceded by one character indicating the status of the file: 10093 10094@table @code 10095@item U @var{file} 10096The file already exists in the repository and has not been locally 10097modified; a new revision has been created (if necessary). 10098 10099@item N @var{file} 10100The file is a new file which has been added to the repository. 10101 10102@item C @var{file} 10103The file already exists in the repository but has been locally modified; 10104you will have to merge the changes. 10105 10106@item I @var{file} 10107The file is being ignored (@pxref{cvsignore}). 10108 10109@cindex Symbolic link, importing 10110@cindex Link, symbolic, importing 10111@c FIXME: also (somewhere else) probably 10112@c should be documenting what happens if you "cvs add" 10113@c a symbolic link. Also maybe what happens if 10114@c you manually create symbolic links within the 10115@c repository (? - not sure why we'd want to suggest 10116@c doing that). 10117@item L @var{file} 10118The file is a symbolic link; @code{cvs import} ignores symbolic links. 10119People periodically suggest that this behavior should 10120be changed, but if there is a consensus on what it 10121should be changed to, it is not apparent. 10122(Various options in the @file{modules} file can be used 10123to recreate symbolic links on checkout, update, etc.; 10124@pxref{modules}.) 10125@end table 10126 10127@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10128@node import examples 10129@appendixsubsec import examples 10130 10131See @ref{Tracking sources}, and @ref{From files}. 10132 10133@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10134@node log 10135@appendixsec log---Print out log information for files 10136@cindex log (subcommand) 10137 10138@itemize @bullet 10139@item 10140Synopsis: log [options] [files@dots{}] 10141@item 10142Requires: repository, working directory. 10143@item 10144Changes: nothing. 10145@end itemize 10146 10147Display log information for files. @code{log} used to 10148call the @sc{rcs} utility @code{rlog}. Although this 10149is no longer true in the current sources, this history 10150determines the format of the output and the options, 10151which are not quite in the style of the other @sc{cvs} 10152commands. 10153 10154@cindex Timezone, in output 10155@cindex Zone, time, in output 10156@c Kind of a funny place to document the timezone used 10157@c in output from commands other than @code{log}. 10158@c There is also more we need to say about this, 10159@c including what happens in a client/server environment. 10160The output includes the location of the @sc{rcs} file, 10161the @dfn{head} revision (the latest revision on the 10162trunk), all symbolic names (tags) and some other 10163things. For each revision, the revision number, the 10164author, the number of lines added/deleted and the log 10165message are printed. All times are displayed in 10166Coordinated Universal Time (UTC). (Other parts of 10167@sc{cvs} print times in the local timezone). 10168@c FIXCVS: need a better way to control the timezone 10169@c used in output. Previous/current versions of CVS did/do 10170@c sometimes support -z in RCSINIT, and/or an 10171@c undocumented (except by reference to 'rlog') -z option 10172@c to cvs log, but this has not been a consistent, 10173@c documented feature. Perhaps a new global option, 10174@c where LT means the client's timezone, which the 10175@c client then communicates to the server, is the 10176@c right solution. 10177 10178@strong{Note: @code{log} uses @samp{-R} in a way that conflicts 10179with the normal use inside @sc{cvs} (@pxref{Common options}).} 10180 10181@menu 10182* log options:: log options 10183* log examples:: log examples 10184@end menu 10185 10186@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10187@node log options 10188@appendixsubsec log options 10189 10190By default, @code{log} prints all information that is 10191available. All other options restrict the output. 10192 10193@table @code 10194@item -b 10195Print information about the revisions on the default 10196branch, normally the highest branch on the trunk. 10197 10198@item -d @var{dates} 10199Print information about revisions with a checkin 10200date/time in the range given by the 10201semicolon-separated list of dates. The date formats 10202accepted are those accepted by the @samp{-D} option to 10203many other @sc{cvs} commands (@pxref{Common options}). 10204Dates can be combined into ranges as follows: 10205 10206@c Should we be thinking about accepting ISO8601 10207@c ranges? For example "1972-09-10/1972-09-12". 10208@table @code 10209@item @var{d1}<@var{d2} 10210@itemx @var{d2}>@var{d1} 10211Select the revisions that were deposited between 10212@var{d1} and @var{d2}. 10213 10214@item <@var{d} 10215@itemx @var{d}> 10216Select all revisions dated @var{d} or earlier. 10217 10218@item @var{d}< 10219@itemx >@var{d} 10220Select all revisions dated @var{d} or later. 10221 10222@item @var{d} 10223Select the single, latest revision dated @var{d} or 10224earlier. 10225@end table 10226 10227The @samp{>} or @samp{<} characters may be followed by 10228@samp{=} to indicate an inclusive range rather than an 10229exclusive one. 10230 10231Note that the separator is a semicolon (;). 10232 10233@item -h 10234Print only the name of the @sc{rcs} file, name 10235of the file in the working directory, head, 10236default branch, access list, locks, symbolic names, and 10237suffix. 10238 10239@item -l 10240Local; run only in current working directory. (Default 10241is to run recursively). 10242 10243@item -N 10244Do not print the list of tags for this file. This 10245option can be very useful when your site uses a lot of 10246tags, so rather than "more"'ing over 3 pages of tag 10247information, the log information is presented without 10248tags at all. 10249 10250@item -R 10251Print only the name of the @sc{rcs} file. 10252 10253@c Note that using a bare revision (in addition to not 10254@c being explicitly documented here) is potentially 10255@c confusing; it shows the log message to get from the 10256@c previous revision to that revision. "-r1.3 -r1.6" 10257@c (equivalent to "-r1.3,1.6") is even worse; it 10258@c prints the messages to get from 1.2 to 1.3 and 1.5 10259@c to 1.6. By analogy with "cvs diff", users might 10260@c expect that it is more like specifying a range. 10261@c It is not 100% clear to me how much of this should 10262@c be documented (for example, multiple -r options 10263@c perhaps could/should be deprecated given the false 10264@c analogy with "cvs diff"). 10265@c In general, this section should be rewritten to talk 10266@c about messages to get from revision rev1 to rev2, 10267@c rather than messages for revision rev2 (that is, the 10268@c messages are associated with a change not a static 10269@c revision and failing to make this distinction causes 10270@c much confusion). 10271@item -r@var{revisions} 10272Print information about revisions given in the 10273comma-separated list @var{revisions} of revisions and 10274ranges. The following table explains the available 10275range formats: 10276 10277@table @code 10278@item @var{rev1}:@var{rev2} 10279Revisions @var{rev1} to @var{rev2} (which must be on 10280the same branch). 10281 10282@item @var{rev1}::@var{rev2} 10283The same, but excluding @var{rev1}. 10284 10285@item :@var{rev} 10286@itemx ::@var{rev} 10287Revisions from the beginning of the branch up to 10288and including @var{rev}. 10289 10290@item @var{rev}: 10291Revisions starting with @var{rev} to the end of the 10292branch containing @var{rev}. 10293 10294@item @var{rev}:: 10295Revisions starting just after @var{rev} to the end of the 10296branch containing @var{rev}. 10297 10298@item @var{branch} 10299An argument that is a branch means all revisions on 10300that branch. 10301 10302@item @var{branch1}:@var{branch2} 10303@itemx @var{branch1}::@var{branch2} 10304A range of branches means all revisions 10305on the branches in that range. 10306 10307@item @var{branch}. 10308The latest revision in @var{branch}. 10309@end table 10310 10311A bare @samp{-r} with no revisions means the latest 10312revision on the default branch, normally the trunk. 10313There can be no space between the @samp{-r} option and 10314its argument. 10315 10316@item -S 10317Suppress the header if no revisions are selected. 10318 10319@item -s @var{states} 10320Print information about revisions whose state 10321attributes match one of the states given in the 10322comma-separated list @var{states}. 10323 10324@item -t 10325Print the same as @samp{-h}, plus the descriptive text. 10326 10327@item -w@var{logins} 10328Print information about revisions checked in by users 10329with login names appearing in the comma-separated list 10330@var{logins}. If @var{logins} is omitted, the user's 10331login is assumed. There can be no space between the 10332@samp{-w} option and its argument. 10333@end table 10334 10335@code{log} prints the intersection of the revisions 10336selected with the options @samp{-d}, @samp{-s}, and 10337@samp{-w}, intersected with the union of the revisions 10338selected by @samp{-b} and @samp{-r}. 10339 10340@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10341@node log examples 10342@appendixsubsec log examples 10343 10344Contributed examples are gratefully accepted. 10345 10346@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10347@node rdiff 10348@appendixsec rdiff---'patch' format diffs between releases 10349@cindex rdiff (subcommand) 10350 10351@itemize @bullet 10352@item 10353rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{} 10354@item 10355Requires: repository. 10356@item 10357Changes: nothing. 10358@item 10359Synonym: patch 10360@end itemize 10361 10362Builds a Larry Wall format patch(1) file between two 10363releases, that can be fed directly into the @code{patch} 10364program to bring an old release up-to-date with the new 10365release. (This is one of the few @sc{cvs} commands that 10366operates directly from the repository, and doesn't 10367require a prior checkout.) The diff output is sent to 10368the standard output device. 10369 10370You can specify (using the standard @samp{-r} and 10371@samp{-D} options) any combination of one or two 10372revisions or dates. If only one revision or date is 10373specified, the patch file reflects differences between 10374that revision or date and the current head revisions in 10375the @sc{rcs} file. 10376 10377Note that if the software release affected is contained 10378in more than one directory, then it may be necessary to 10379specify the @samp{-p} option to the @code{patch} command when 10380patching the old sources, so that @code{patch} is able to find 10381the files that are located in other directories. 10382 10383@menu 10384* rdiff options:: rdiff options 10385* rdiff examples:: rdiff examples 10386@end menu 10387 10388@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10389@node rdiff options 10390@appendixsubsec rdiff options 10391 10392These standard options are supported by @code{rdiff} 10393(@pxref{Common options}, for a complete description of 10394them): 10395 10396@table @code 10397@item -D @var{date} 10398Use the most recent revision no later than @var{date}. 10399 10400@item -f 10401If no matching revision is found, retrieve the most 10402recent revision (instead of ignoring the file). 10403 10404@item -l 10405Local; don't descend subdirectories. 10406 10407@item -R 10408Examine directories recursively. This option is on by default. 10409 10410@item -r @var{tag} 10411Use revision @var{tag}. 10412@end table 10413 10414In addition to the above, these options are available: 10415 10416@table @code 10417@item -c 10418Use the context diff format. This is the default format. 10419 10420@item -s 10421Create a summary change report instead of a patch. The 10422summary includes information about files that were 10423changed or added between the releases. It is sent to 10424the standard output device. This is useful for finding 10425out, for example, which files have changed between two 10426dates or revisions. 10427 10428@item -t 10429A diff of the top two revisions is sent to the standard 10430output device. This is most useful for seeing what the 10431last change to a file was. 10432 10433@item -u 10434Use the unidiff format for the context diffs. 10435Remember that old versions 10436of the @code{patch} program can't handle the unidiff 10437format, so if you plan to post this patch to the net 10438you should probably not use @samp{-u}. 10439 10440@item -V @var{vn} 10441Expand keywords according to the rules current in 10442@sc{rcs} version @var{vn} (the expansion format changed with 10443@sc{rcs} version 5). Note that this option is no 10444longer accepted. @sc{cvs} will always expand keywords the 10445way that @sc{rcs} version 5 does. 10446@end table 10447 10448@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10449@node rdiff examples 10450@appendixsubsec rdiff examples 10451 10452Suppose you receive mail from @t{foo@@example.net} asking for an 10453update from release 1.2 to 1.4 of the tc compiler. You 10454have no such patches on hand, but with @sc{cvs} that can 10455easily be fixed with a command such as this: 10456 10457@example 10458$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 10459$$ Mail -s 'The patches you asked for' foo@@example.net 10460@end example 10461 10462Suppose you have made release 1.3, and forked a branch 10463called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1} 10464corresponds to release 1.3.1, which was made some time 10465ago. Now, you want to see how much development has been 10466done on the branch. This command can be used: 10467 10468@example 10469$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 10470cvs rdiff: Diffing module-name 10471File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 10472File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 10473File bar.h,v changed from revision 1.29.2.1 to 1.2 10474@end example 10475 10476@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10477@node release 10478@appendixsec release---Indicate that a Module is no longer in use 10479@cindex release (subcommand) 10480 10481@itemize @bullet 10482@item 10483release [-d] directories@dots{} 10484@item 10485Requires: Working directory. 10486@item 10487Changes: Working directory, history log. 10488@end itemize 10489 10490This command is meant to safely cancel the effect of 10491@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it 10492isn't strictly necessary to use this command. You can 10493always simply delete your working directory, if you 10494like; but you risk losing changes you may have 10495forgotten, and you leave no trace in the @sc{cvs} history 10496file (@pxref{history file}) that you've abandoned your 10497checkout. 10498 10499Use @samp{cvs release} to avoid these problems. This 10500command checks that no uncommitted changes are 10501present; that you are executing it from immediately 10502above a @sc{cvs} working directory; and that the repository 10503recorded for your files is the same as the repository 10504defined in the module database. 10505 10506If all these conditions are true, @samp{cvs release} 10507leaves a record of its execution (attesting to your 10508intentionally abandoning your checkout) in the @sc{cvs} 10509history log. 10510 10511@menu 10512* release options:: release options 10513* release output:: release output 10514* release examples:: release examples 10515@end menu 10516 10517@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10518@node release options 10519@appendixsubsec release options 10520 10521The @code{release} command supports one command option: 10522 10523@table @code 10524@item -d 10525Delete your working copy of the file if the release 10526succeeds. If this flag is not given your files will 10527remain in your working directory. 10528 10529@strong{WARNING: The @code{release} command deletes 10530all directories and files recursively. This 10531has the very serious side-effect that any directory 10532that you have created inside your checked-out sources, 10533and not added to the repository (using the @code{add} 10534command; @pxref{Adding files}) will be silently deleted---even 10535if it is non-empty!} 10536@end table 10537 10538@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10539@node release output 10540@appendixsubsec release output 10541 10542Before @code{release} releases your sources it will 10543print a one-line message for any file that is not 10544up-to-date. 10545 10546@table @code 10547@item U @var{file} 10548@itemx P @var{file} 10549There exists a newer revision of this file in the 10550repository, and you have not modified your local copy 10551of the file (@samp{U} and @samp{P} mean the same thing). 10552 10553@item A @var{file} 10554The file has been added to your private copy of the 10555sources, but has not yet been committed to the 10556repository. If you delete your copy of the sources 10557this file will be lost. 10558 10559@item R @var{file} 10560The file has been removed from your private copy of the 10561sources, but has not yet been removed from the 10562repository, since you have not yet committed the 10563removal. @xref{commit}. 10564 10565@item M @var{file} 10566The file is modified in your working directory. There 10567might also be a newer revision inside the repository. 10568 10569@item ? @var{file} 10570@var{file} is in your working directory, but does not 10571correspond to anything in the source repository, and is 10572not in the list of files for @sc{cvs} to ignore (see the 10573description of the @samp{-I} option, and 10574@pxref{cvsignore}). If you remove your working 10575sources, this file will be lost. 10576@end table 10577 10578@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10579@node release examples 10580@appendixsubsec release examples 10581 10582Release the @file{tc} directory, and delete your local working copy 10583of the files. 10584 10585@example 10586$ cd .. # @r{You must stand immediately above the} 10587 # @r{sources when you issue @samp{cvs release}.} 10588$ cvs release -d tc 10589You have [0] altered files in this repository. 10590Are you sure you want to release (and delete) directory `tc': y 10591$ 10592@end example 10593 10594@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10595@node update 10596@appendixsec update---Bring work tree in sync with repository 10597@cindex update (subcommand) 10598 10599@itemize @bullet 10600@item 10601update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files@dots{} 10602@item 10603Requires: repository, working directory. 10604@item 10605Changes: working directory. 10606@end itemize 10607 10608After you've run checkout to create your private copy 10609of source from the common repository, other developers 10610will continue changing the central source. From time 10611to time, when it is convenient in your development 10612process, you can use the @code{update} command from 10613within your working directory to reconcile your work 10614with any revisions applied to the source repository 10615since your last checkout or update. Without the @code{-C} 10616option, @code{update} will also merge any differences 10617between the local copy of files and their base revisions 10618into any destination revisions specified with @code{-r}, 10619@code{-D}, or @code{-A}. 10620 10621@menu 10622* update options:: update options 10623* update output:: update output 10624@end menu 10625 10626@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10627@node update options 10628@appendixsubsec update options 10629 10630These standard options are available with @code{update} 10631(@pxref{Common options}, for a complete description of 10632them): 10633 10634@table @code 10635@item -D date 10636Use the most recent revision no later than @var{date}. 10637This option is sticky, and implies @samp{-P}. 10638See @ref{Sticky tags}, for more information on sticky tags/dates. 10639 10640@item -f 10641Only useful with the @samp{-D @var{date}} or @samp{-r 10642@var{tag}} flags. If no matching revision is found, 10643retrieve the most recent revision (instead of ignoring 10644the file). 10645 10646@item -k @var{kflag} 10647Process keywords according to @var{kflag}. See 10648@ref{Keyword substitution}. 10649This option is sticky; future updates of 10650this file in this working directory will use the same 10651@var{kflag}. The @code{status} command can be viewed 10652to see the sticky options. See @ref{Invoking CVS}, for 10653more information on the @code{status} command. 10654 10655@item -l 10656Local; run only in current working directory. @xref{Recursive behavior}. 10657 10658@item -P 10659Prune empty directories. See @ref{Moving directories}. 10660 10661@item -p 10662Pipe files to the standard output. 10663 10664@item -R 10665Update directories recursively (default). @xref{Recursive 10666behavior}. 10667 10668@item -r rev 10669Retrieve revision/tag @var{rev}. This option is sticky, 10670and implies @samp{-P}. 10671See @ref{Sticky tags}, for more information on sticky tags/dates. 10672@end table 10673 10674@need 800 10675These special options are also available with 10676@code{update}. 10677 10678@table @code 10679@item -A 10680Reset any sticky tags, dates, or @samp{-k} options. 10681See @ref{Sticky tags}, for more information on sticky tags/dates. 10682 10683@item -C 10684Overwrite locally modified files with clean copies from 10685the repository (the modified file is saved in 10686@file{.#@var{file}.@var{revision}}, however). 10687 10688@item -d 10689Create any directories that exist in the repository if 10690they're missing from the working directory. Normally, 10691@code{update} acts only on directories and files that 10692were already enrolled in your working directory. 10693 10694This is useful for updating directories that were 10695created in the repository since the initial checkout; 10696but it has an unfortunate side effect. If you 10697deliberately avoided certain directories in the 10698repository when you created your working directory 10699(either through use of a module name or by listing 10700explicitly the files and directories you wanted on the 10701command line), then updating with @samp{-d} will create 10702those directories, which may not be what you want. 10703 10704@item -I @var{name} 10705Ignore files whose names match @var{name} (in your 10706working directory) during the update. You can specify 10707@samp{-I} more than once on the command line to specify 10708several files to ignore. Use @samp{-I !} to avoid 10709ignoring any files at all. @xref{cvsignore}, for other 10710ways to make @sc{cvs} ignore some files. 10711 10712@item -W@var{spec} 10713Specify file names that should be filtered during 10714update. You can use this option repeatedly. 10715 10716@var{spec} can be a file name pattern of the same type 10717that you can specify in the @file{.cvswrappers} 10718file. @xref{Wrappers}. 10719 10720@item -j@var{revision} 10721With two @samp{-j} options, merge changes from the 10722revision specified with the first @samp{-j} option to 10723the revision specified with the second @samp{j} option, 10724into the working directory. 10725 10726With one @samp{-j} option, merge changes from the 10727ancestor revision to the revision specified with the 10728@samp{-j} option, into the working directory. The 10729ancestor revision is the common ancestor of the 10730revision which the working directory is based on, and 10731the revision specified in the @samp{-j} option. 10732 10733Note that using a single @samp{-j @var{tagname}} option rather than 10734@samp{-j @var{branchname}} to merge changes from a branch will 10735often not remove files which were removed on the branch. 10736@xref{Merging adds and removals}, for more. 10737 10738In addition, each @samp{-j} option can contain an optional 10739date specification which, when used with branches, can 10740limit the chosen revision to one within a specific 10741date. An optional date is specified by adding a colon 10742(:) to the tag: 10743@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 10744 10745@xref{Branching and merging}. 10746 10747@end table 10748 10749@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10750@node update output 10751@appendixsubsec update output 10752 10753@code{update} and @code{checkout} keep you informed of 10754their progress by printing a line for each file, preceded 10755by one character indicating the status of the file: 10756 10757@table @code 10758@item U @var{file} 10759The file was brought up to date with respect to the 10760repository. This is done for any file that exists in 10761the repository but not in your source, and for files 10762that you haven't changed but are not the most recent 10763versions available in the repository. 10764 10765@item P @var{file} 10766Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 10767file. This accomplishes the same thing as @samp{U} using less bandwidth. 10768 10769@item A @var{file} 10770The file has been added to your private copy of the 10771sources, and will be added to the source repository 10772when you run @code{commit} on the file. This is a 10773reminder to you that the file needs to be committed. 10774 10775@item R @var{file} 10776The file has been removed from your private copy of the 10777sources, and will be removed from the source repository 10778when you run @code{commit} on the file. This is a 10779reminder to you that the file needs to be committed. 10780 10781@item M @var{file} 10782The file is modified in your working directory. 10783 10784@samp{M} can indicate one of two states for a file 10785you're working on: either there were no modifications 10786to the same file in the repository, so that your file 10787remains as you last saw it; or there were modifications 10788in the repository as well as in your copy, but they 10789were merged successfully, without conflict, in your 10790working directory. 10791 10792@sc{cvs} will print some messages if it merges your work, 10793and a backup copy of your working file (as it looked 10794before you ran @code{update}) will be made. The exact 10795name of that file is printed while @code{update} runs. 10796 10797@item C @var{file} 10798@cindex .# files 10799@cindex __ files (VMS) 10800A conflict was detected while trying to merge your 10801changes to @var{file} with changes from the source 10802repository. @var{file} (the copy in your working 10803directory) is now the result of attempting to merge 10804the two revisions; an unmodified copy of your file 10805is also in your working directory, with the name 10806@file{.#@var{file}.@var{revision}} where @var{revision} 10807is the revision that your modified file started 10808from. Resolve the conflict as described in 10809@ref{Conflicts example}. 10810@c "some systems" as in out-of-the-box OSes? Not as 10811@c far as I know. We need to advise sysadmins as well 10812@c as users how to set up this kind of purge, if that is 10813@c what they want. 10814@c We also might want to think about cleaner solutions, 10815@c like having CVS remove the .# file once the conflict 10816@c has been resolved or something like that. 10817(Note that some systems automatically purge 10818files that begin with @file{.#} if they have not been 10819accessed for a few days. If you intend to keep a copy 10820of your original file, it is a very good idea to rename 10821it.) Under @sc{vms}, the file name starts with 10822@file{__} rather than @file{.#}. 10823 10824@item ? @var{file} 10825@var{file} is in your working directory, but does not 10826correspond to anything in the source repository, and is 10827not in the list of files for @sc{cvs} to ignore (see the 10828description of the @samp{-I} option, and 10829@pxref{cvsignore}). 10830@end table 10831 10832@node Invoking CVS 10833@appendix Quick reference to CVS commands 10834@cindex Command reference 10835@cindex Reference, commands 10836@cindex Invoking CVS 10837 10838This appendix describes how to invoke @sc{cvs}, with 10839references to where each command or feature is 10840described in detail. For other references run the 10841@code{cvs --help} command, or see @ref{Index}. 10842 10843A @sc{cvs} command looks like: 10844 10845@example 10846cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 10847@end example 10848 10849Global options: 10850 10851@table @code 10852@item --allow-root=@var{rootdir} 10853Specify legal @sc{cvsroot} directory (server only) (not 10854in @sc{cvs} 1.9 and older). See @ref{Password 10855authentication server}. 10856 10857@item -a 10858Authenticate all communication (client only) (not in @sc{cvs} 108591.9 and older). See @ref{Global options}. 10860 10861@item -b 10862Specify RCS location (@sc{cvs} 1.9 and older). See 10863@ref{Global options}. 10864 10865@item -d @var{root} 10866Specify the @sc{cvsroot}. See @ref{Repository}. 10867 10868@item -e @var{editor} 10869Edit messages with @var{editor}. See @ref{Committing 10870your changes}. 10871 10872@item -f 10873Do not read the @file{~/.cvsrc} file. See @ref{Global 10874options}. 10875 10876@item -H 10877@itemx --help 10878Print a help message. See @ref{Global options}. 10879 10880@item -l 10881Do not log in @file{$CVSROOT/CVSROOT/history} file. See @ref{Global 10882options}. 10883 10884@item -n 10885Do not change any files. See @ref{Global options}. 10886 10887@item -Q 10888Be really quiet. See @ref{Global options}. 10889 10890@item -q 10891Be somewhat quiet. See @ref{Global options}. 10892 10893@item -r 10894Make new working files read-only. See @ref{Global options}. 10895 10896@item -s @var{variable}=@var{value} 10897Set a user variable. See @ref{Variables}. 10898 10899@item -T @var{tempdir} 10900Put temporary files in @var{tempdir}. See @ref{Global 10901options}. 10902 10903@item -t 10904Trace @sc{cvs} execution. See @ref{Global options}. 10905 10906@item -v 10907@item --version 10908Display version and copyright information for @sc{cvs}. 10909 10910@item -w 10911Make new working files read-write. See @ref{Global 10912options}. 10913 10914@item -x 10915Encrypt all communication (client only). 10916See @ref{Global options}. 10917 10918@item -z @var{gzip-level} 10919@cindex Compression 10920@cindex Gzip 10921Set the compression level (client only). 10922See @ref{Global options}. 10923@end table 10924 10925Keyword expansion modes (@pxref{Substitution modes}): 10926 10927@example 10928-kkv $@i{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 10929-kkvl $@i{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 10930-kk $@i{}Id$ 10931-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 10932-ko @i{no expansion} 10933-kb @i{no expansion, file is binary} 10934@end example 10935 10936Keywords (@pxref{Keyword list}): 10937 10938@example 10939$@i{}Author: joe $ 10940$@i{}Date: 1993/12/09 03:21:13 $ 10941$@i{}CVSHeader: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 10942$@i{}Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 10943$@i{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 10944$@i{}Locker: harry $ 10945$@i{}Name: snapshot_1_14 $ 10946$@i{}RCSfile: file1,v $ 10947$@i{}Revision: 1.1 $ 10948$@i{}Source: /home/files/file1,v $ 10949$@i{}State: Exp $ 10950$@i{}Log: file1,v $ 10951Revision 1.1 1993/12/09 03:30:17 joe 10952Initial revision 10953 10954@end example 10955 10956@c The idea behind this table is that we want each item 10957@c to be a sentence or two at most. Preferably a 10958@c single line. 10959@c 10960@c In some cases refs to "foo options" are just to get 10961@c this thing written quickly, not because the "foo 10962@c options" node is really the best place to point. 10963Commands, command options, and command arguments: 10964 10965@table @code 10966@c ------------------------------------------------------------ 10967@item add [@var{options}] [@var{files}@dots{}] 10968Add a new file/directory. See @ref{Adding files}. 10969 10970@table @code 10971@item -k @var{kflag} 10972Set keyword expansion. 10973 10974@item -m @var{msg} 10975Set file description. 10976@end table 10977 10978@c ------------------------------------------------------------ 10979@item admin [@var{options}] [@var{files}@dots{}] 10980Administration of history files in the repository. See 10981@ref{admin}. 10982@c This list omits those options which are not 10983@c documented as being useful with CVS. That might be 10984@c a mistake... 10985 10986@table @code 10987@item -b[@var{rev}] 10988Set default branch. See @ref{Reverting local changes}. 10989 10990@item -c@var{string} 10991Set comment leader. 10992 10993@item -k@var{subst} 10994Set keyword substitution. See @ref{Keyword 10995substitution}. 10996 10997@item -l[@var{rev}] 10998Lock revision @var{rev}, or latest revision. 10999 11000@item -m@var{rev}:@var{msg} 11001Replace the log message of revision @var{rev} with 11002@var{msg}. 11003 11004@item -o@var{range} 11005Delete revisions from the repository. See 11006@ref{admin options}. 11007 11008@item -q 11009Run quietly; do not print diagnostics. 11010 11011@item -s@var{state}[:@var{rev}] 11012Set the state. 11013 11014@c Does not work for client/server CVS 11015@item -t 11016Set file description from standard input. 11017 11018@item -t@var{file} 11019Set file description from @var{file}. 11020 11021@item -t-@var{string} 11022Set file description to @var{string}. 11023 11024@item -u[@var{rev}] 11025Unlock revision @var{rev}, or latest revision. 11026@end table 11027 11028@c ------------------------------------------------------------ 11029@item annotate [@var{options}] [@var{files}@dots{}] 11030Show last revision where each line was modified. See 11031@ref{annotate}. 11032 11033@table @code 11034@item -D @var{date} 11035Annotate the most recent revision no later than 11036@var{date}. See @ref{Common options}. 11037 11038@item -F 11039Force annotation of binary files. (Without this option, 11040binary files are skipped with a message.) 11041 11042@item -f 11043Use head revision if tag/date not found. See 11044@ref{Common options}. 11045 11046@item -l 11047Local; run only in current working directory. @xref{Recursive behavior}. 11048 11049@item -R 11050Operate recursively (default). @xref{Recursive 11051behavior}. 11052 11053@item -r @var{tag} 11054Annotate revision @var{tag}. See @ref{Common options}. 11055@end table 11056 11057@c ------------------------------------------------------------ 11058@item checkout [@var{options}] @var{modules}@dots{} 11059Get a copy of the sources. See @ref{checkout}. 11060 11061@table @code 11062@item -A 11063Reset any sticky tags/date/options. See @ref{Sticky 11064tags} and @ref{Keyword substitution}. 11065 11066@item -c 11067Output the module database. See @ref{checkout options}. 11068 11069@item -D @var{date} 11070Check out revisions as of @var{date} (is sticky). See 11071@ref{Common options}. 11072 11073@item -d @var{dir} 11074Check out into @var{dir}. See @ref{checkout options}. 11075 11076@item -f 11077Use head revision if tag/date not found. See 11078@ref{Common options}. 11079 11080@c Probably want to use rev1/rev2 style like for diff 11081@c -r. Here and in on-line help. 11082@item -j @var{rev} 11083Merge in changes. See @ref{checkout options}. 11084 11085@item -k @var{kflag} 11086Use @var{kflag} keyword expansion. See 11087@ref{Substitution modes}. 11088 11089@item -l 11090Local; run only in current working directory. @xref{Recursive behavior}. 11091 11092@item -N 11093Don't ``shorten'' module paths if -d specified. See 11094@ref{checkout options}. 11095 11096@item -n 11097Do not run module program (if any). See @ref{checkout options}. 11098 11099@item -P 11100Prune empty directories. See @ref{Moving directories}. 11101 11102@item -p 11103Check out files to standard output (avoids 11104stickiness). See @ref{checkout options}. 11105 11106@item -R 11107Operate recursively (default). @xref{Recursive 11108behavior}. 11109 11110@item -r @var{tag} 11111Checkout revision @var{tag} (is sticky). See @ref{Common options}. 11112 11113@item -s 11114Like -c, but include module status. See @ref{checkout options}. 11115@end table 11116 11117@c ------------------------------------------------------------ 11118@item commit [@var{options}] [@var{files}@dots{}] 11119Check changes into the repository. See @ref{commit}. 11120 11121@table @code 11122@item -F @var{file} 11123Read log message from @var{file}. See @ref{commit options}. 11124 11125@item -f 11126@c What is this "disables recursion"? It is from the 11127@c on-line help; is it documented in this manual? 11128Force the file to be committed; disables recursion. 11129See @ref{commit options}. 11130 11131@item -l 11132Local; run only in current working directory. See @ref{Recursive behavior}. 11133 11134@item -m @var{msg} 11135Use @var{msg} as log message. See @ref{commit options}. 11136 11137@item -n 11138Do not run module program (if any). See @ref{commit options}. 11139 11140@item -R 11141Operate recursively (default). @xref{Recursive 11142behavior}. 11143 11144@item -r @var{rev} 11145Commit to @var{rev}. See @ref{commit options}. 11146@c FIXME: should be dragging over text from 11147@c commit options, especially if it can be cleaned up 11148@c and made concise enough. 11149@end table 11150 11151@c ------------------------------------------------------------ 11152@item diff [@var{options}] [@var{files}@dots{}] 11153Show differences between revisions. See @ref{diff}. 11154In addition to the options shown below, accepts a wide 11155variety of options to control output style, for example 11156@samp{-c} for context diffs. 11157 11158@table @code 11159@item -D @var{date1} 11160Diff revision for date against working file. See 11161@ref{diff options}. 11162 11163@item -D @var{date2} 11164Diff @var{rev1}/@var{date1} against @var{date2}. See 11165@ref{diff options}. 11166 11167@item -l 11168Local; run only in current working directory. See @ref{Recursive behavior}. 11169 11170@item -N 11171Include diffs for added and removed files. See 11172@ref{diff options}. 11173 11174@item -R 11175Operate recursively (default). @xref{Recursive 11176behavior}. 11177 11178@item -r @var{rev1} 11179Diff revision for @var{rev1} against working file. See 11180@ref{diff options}. 11181 11182@item -r @var{rev2} 11183Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}. 11184@end table 11185 11186@c ------------------------------------------------------------ 11187@item edit [@var{options}] [@var{files}@dots{}] 11188Get ready to edit a watched file. See @ref{Editing files}. 11189 11190@table @code 11191@item -a @var{actions} 11192Specify actions for temporary watch, where 11193@var{actions} is @code{edit}, @code{unedit}, 11194@code{commit}, @code{all}, or @code{none}. See 11195@ref{Editing files}. 11196 11197@item -l 11198Local; run only in current working directory. See @ref{Recursive behavior}. 11199 11200@item -R 11201Operate recursively (default). @xref{Recursive 11202behavior}. 11203@end table 11204 11205@c ------------------------------------------------------------ 11206@item editors [@var{options}] [@var{files}@dots{}] 11207See who is editing a watched file. See @ref{Watch information}. 11208 11209@table @code 11210@item -l 11211Local; run only in current working directory. See @ref{Recursive behavior}. 11212 11213@item -R 11214Operate recursively (default). @xref{Recursive 11215behavior}. 11216@end table 11217 11218@c ------------------------------------------------------------ 11219@item export [@var{options}] @var{modules}@dots{} 11220Export files from @sc{cvs}. See @ref{export}. 11221 11222@table @code 11223@item -D @var{date} 11224Check out revisions as of @var{date}. See 11225@ref{Common options}. 11226 11227@item -d @var{dir} 11228Check out into @var{dir}. See @ref{export options}. 11229 11230@item -f 11231Use head revision if tag/date not found. See 11232@ref{Common options}. 11233 11234@item -k @var{kflag} 11235Use @var{kflag} keyword expansion. See 11236@ref{Substitution modes}. 11237 11238@item -l 11239Local; run only in current working directory. @xref{Recursive behavior}. 11240 11241@item -N 11242Don't ``shorten'' module paths if -d specified. See 11243@ref{export options}. 11244 11245@item -n 11246Do not run module program (if any). See @ref{export options}. 11247 11248@item -R 11249Operate recursively (default). @xref{Recursive 11250behavior}. 11251 11252@item -r @var{tag} 11253Checkout revision @var{tag}. See @ref{Common options}. 11254@end table 11255 11256@c ------------------------------------------------------------ 11257@item history [@var{options}] [@var{files}@dots{}] 11258Show repository access history. See @ref{history}. 11259 11260@table @code 11261@item -a 11262All users (default is self). See @ref{history options}. 11263 11264@item -b @var{str} 11265Back to record with @var{str} in module/file/repos 11266field. See @ref{history options}. 11267 11268@item -c 11269Report on committed (modified) files. See @ref{history options}. 11270 11271@item -D @var{date} 11272Since @var{date}. See @ref{history options}. 11273 11274@item -e 11275Report on all record types. See @ref{history options}. 11276 11277@item -l 11278Last modified (committed or modified report). See @ref{history options}. 11279 11280@item -m @var{module} 11281Report on @var{module} (repeatable). See @ref{history options}. 11282 11283@item -n @var{module} 11284In @var{module}. See @ref{history options}. 11285 11286@item -o 11287Report on checked out modules. See @ref{history options}. 11288 11289@item -p @var{repository} 11290In @var{repository}. See @ref{history options}. 11291 11292@item -r @var{rev} 11293Since revision @var{rev}. See @ref{history options}. 11294 11295@item -T 11296@c What the @#$@# is a TAG? Same as a tag? This 11297@c wording is also in the online-line help. 11298Produce report on all TAGs. See @ref{history options}. 11299 11300@item -t @var{tag} 11301Since tag record placed in history file (by anyone). 11302See @ref{history options}. 11303 11304@item -u @var{user} 11305For user @var{user} (repeatable). See @ref{history options}. 11306 11307@item -w 11308Working directory must match. See @ref{history options}. 11309 11310@item -x @var{types} 11311Report on @var{types}, one or more of 11312@code{TOEFWUCGMAR}. See @ref{history options}. 11313 11314@item -z @var{zone} 11315Output for time zone @var{zone}. See @ref{history options}. 11316@end table 11317 11318@c ------------------------------------------------------------ 11319@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 11320Import files into @sc{cvs}, using vendor branches. See 11321@ref{import}. 11322 11323@table @code 11324@item -b @var{bra} 11325Import to vendor branch @var{bra}. See 11326@ref{Multiple vendor branches}. 11327 11328@item -d 11329Use the file's modification time as the time of 11330import. See @ref{import options}. 11331 11332@item -k @var{kflag} 11333Set default keyword substitution mode. See 11334@ref{import options}. 11335 11336@item -m @var{msg} 11337Use @var{msg} for log message. See 11338@ref{import options}. 11339 11340@item -I @var{ign} 11341More files to ignore (! to reset). See 11342@ref{import options}. 11343 11344@item -W @var{spec} 11345More wrappers. See @ref{import options}. 11346@end table 11347 11348@c ------------------------------------------------------------ 11349@item init 11350Create a @sc{cvs} repository if it doesn't exist. See 11351@ref{Creating a repository}. 11352 11353@c ------------------------------------------------------------ 11354@item kserver 11355Kerberos authenticated server. 11356See @ref{Kerberos authenticated}. 11357 11358@c ------------------------------------------------------------ 11359@item log [@var{options}] [@var{files}@dots{}] 11360Print out history information for files. See @ref{log}. 11361 11362@table @code 11363@item -b 11364Only list revisions on the default branch. See @ref{log options}. 11365 11366@item -d @var{dates} 11367Specify dates (@var{d1}<@var{d2} for range, @var{d} for 11368latest before). See @ref{log options}. 11369 11370@item -h 11371Only print header. See @ref{log options}. 11372 11373@item -l 11374Local; run only in current working directory. See @ref{Recursive behavior}. 11375 11376@item -N 11377Do not list tags. See @ref{log options}. 11378 11379@item -R 11380Only print name of RCS file. See @ref{log options}. 11381 11382@item -r@var{revs} 11383Only list revisions @var{revs}. See @ref{log options}. 11384 11385@item -s @var{states} 11386Only list revisions with specified states. See @ref{log options}. 11387 11388@item -t 11389Only print header and descriptive text. See @ref{log 11390options}. 11391 11392@item -w@var{logins} 11393Only list revisions checked in by specified logins. See @ref{log options}. 11394@end table 11395 11396@c ------------------------------------------------------------ 11397@item login 11398Prompt for password for authenticating server. See 11399@ref{Password authentication client}. 11400 11401@c ------------------------------------------------------------ 11402@item logout 11403Remove stored password for authenticating server. See 11404@ref{Password authentication client}. 11405 11406@c ------------------------------------------------------------ 11407@item pserver 11408Password authenticated server. 11409See @ref{Password authentication server}. 11410 11411@c ------------------------------------------------------------ 11412@item rannotate [@var{options}] [@var{modules}@dots{}] 11413Show last revision where each line was modified. See 11414@ref{annotate}. 11415 11416@table @code 11417@item -D @var{date} 11418Annotate the most recent revision no later than 11419@var{date}. See @ref{Common options}. 11420 11421@item -F 11422Force annotation of binary files. (Without this option, 11423binary files are skipped with a message.) 11424 11425@item -f 11426Use head revision if tag/date not found. See 11427@ref{Common options}. 11428 11429@item -l 11430Local; run only in current working directory. @xref{Recursive behavior}. 11431 11432@item -R 11433Operate recursively (default). @xref{Recursive behavior}. 11434 11435@item -r @var{tag} 11436Annotate revision @var{tag}. See @ref{Common options}. 11437@end table 11438 11439@c ------------------------------------------------------------ 11440@item rdiff [@var{options}] @var{modules}@dots{} 11441Show differences between releases. See @ref{rdiff}. 11442 11443@table @code 11444@item -c 11445Context diff output format (default). See @ref{rdiff options}. 11446 11447@item -D @var{date} 11448Select revisions based on @var{date}. See @ref{Common options}. 11449 11450@item -f 11451Use head revision if tag/date not found. See 11452@ref{Common options}. 11453 11454@item -l 11455Local; run only in current working directory. See @ref{Recursive behavior}. 11456 11457@item -R 11458Operate recursively (default). @xref{Recursive 11459behavior}. 11460 11461@item -r @var{rev} 11462Select revisions based on @var{rev}. See @ref{Common options}. 11463 11464@item -s 11465Short patch - one liner per file. See @ref{rdiff options}. 11466 11467@item -t 11468Top two diffs - last change made to the file. See 11469@ref{diff options}. 11470 11471@item -u 11472Unidiff output format. See @ref{rdiff options}. 11473 11474@item -V @var{vers} 11475Use RCS Version @var{vers} for keyword expansion (obsolete). See 11476@ref{rdiff options}. 11477@end table 11478 11479@c ------------------------------------------------------------ 11480@item release [@var{options}] @var{directory} 11481Indicate that a directory is no longer in use. See 11482@ref{release}. 11483 11484@table @code 11485@item -d 11486Delete the given directory. See @ref{release options}. 11487@end table 11488 11489@c ------------------------------------------------------------ 11490@item remove [@var{options}] [@var{files}@dots{}] 11491Remove an entry from the repository. See @ref{Removing files}. 11492 11493@table @code 11494@item -f 11495Delete the file before removing it. See @ref{Removing files}. 11496 11497@item -l 11498Local; run only in current working directory. See @ref{Recursive behavior}. 11499 11500@item -R 11501Operate recursively (default). @xref{Recursive 11502behavior}. 11503@end table 11504 11505@c ------------------------------------------------------------ 11506@item rlog [@var{options}] [@var{files}@dots{}] 11507Print out history information for modules. See @ref{log}. 11508 11509@table @code 11510@item -b 11511Only list revisions on the default branch. See @ref{log options}. 11512 11513@item -d @var{dates} 11514Specify dates (@var{d1}<@var{d2} for range, @var{d} for 11515latest before). See @ref{log options}. 11516 11517@item -h 11518Only print header. See @ref{log options}. 11519 11520@item -l 11521Local; run only in current working directory. See @ref{Recursive behavior}. 11522 11523@item -N 11524Do not list tags. See @ref{log options}. 11525 11526@item -R 11527Only print name of RCS file. See @ref{log options}. 11528 11529@item -r@var{revs} 11530Only list revisions @var{revs}. See @ref{log options}. 11531 11532@item -s @var{states} 11533Only list revisions with specified states. See @ref{log options}. 11534 11535@item -t 11536Only print header and descriptive text. See @ref{log options}. 11537 11538@item -w@var{logins} 11539Only list revisions checked in by specified logins. See @ref{log options}. 11540@end table 11541 11542@c ------------------------------------------------------------ 11543@item rtag [@var{options}] @var{tag} @var{modules}@dots{} 11544Add a symbolic tag to a module. 11545See @ref{Revisions} and @ref{Branching and merging}. 11546 11547@table @code 11548@item -a 11549Clear tag from removed files that would not otherwise 11550be tagged. See @ref{Tagging add/remove}. 11551 11552@item -b 11553Create a branch named @var{tag}. See @ref{Branching and merging}. 11554 11555@item -B 11556Used in conjunction with -F or -d, enables movement and deletion of 11557branch tags. Use with extreme caution. 11558 11559@item -D @var{date} 11560Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 11561 11562@item -d 11563Delete @var{tag}. See @ref{Modifying tags}. 11564 11565@item -F 11566Move @var{tag} if it already exists. See @ref{Modifying tags}. 11567 11568@item -f 11569Force a head revision match if tag/date not found. 11570See @ref{Tagging by date/tag}. 11571 11572@item -l 11573Local; run only in current working directory. See @ref{Recursive behavior}. 11574 11575@item -n 11576No execution of tag program. See @ref{Common options}. 11577 11578@item -R 11579Operate recursively (default). @xref{Recursive 11580behavior}. 11581 11582@item -r @var{rev} 11583Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. 11584@end table 11585 11586@c ------------------------------------------------------------ 11587@item server 11588Rsh server. See @ref{Connecting via rsh}. 11589 11590@c ------------------------------------------------------------ 11591@item status [@var{options}] @var{files}@dots{} 11592Display status information in a working directory. See 11593@ref{File status}. 11594 11595@table @code 11596@item -l 11597Local; run only in current working directory. See @ref{Recursive behavior}. 11598 11599@item -R 11600Operate recursively (default). @xref{Recursive 11601behavior}. 11602 11603@item -v 11604Include tag information for file. See @ref{Tags}. 11605@end table 11606 11607@c ------------------------------------------------------------ 11608@item tag [@var{options}] @var{tag} [@var{files}@dots{}] 11609Add a symbolic tag to checked out version of files. 11610See @ref{Revisions} and @ref{Branching and merging}. 11611 11612@table @code 11613@item -b 11614Create a branch named @var{tag}. See @ref{Branching and merging}. 11615 11616@item -c 11617Check that working files are unmodified. See 11618@ref{Tagging the working directory}. 11619 11620@item -D @var{date} 11621Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 11622 11623@item -d 11624Delete @var{tag}. See @ref{Modifying tags}. 11625 11626@item -F 11627Move @var{tag} if it already exists. See @ref{Modifying tags}. 11628 11629@item -f 11630Force a head revision match if tag/date not found. 11631See @ref{Tagging by date/tag}. 11632 11633@item -l 11634Local; run only in current working directory. See @ref{Recursive behavior}. 11635 11636@item -R 11637Operate recursively (default). @xref{Recursive 11638behavior}. 11639 11640@item -r @var{rev} 11641Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. 11642@end table 11643 11644@c ------------------------------------------------------------ 11645@item unedit [@var{options}] [@var{files}@dots{}] 11646Undo an edit command. See @ref{Editing files}. 11647 11648@table @code 11649@item -l 11650Local; run only in current working directory. See @ref{Recursive behavior}. 11651 11652@item -R 11653Operate recursively (default). @xref{Recursive behavior}. 11654@end table 11655 11656@c ------------------------------------------------------------ 11657@item update [@var{options}] [@var{files}@dots{}] 11658Bring work tree in sync with repository. See 11659@ref{update}. 11660 11661@table @code 11662@item -A 11663Reset any sticky tags/date/options. See @ref{Sticky 11664tags} and @ref{Keyword substitution}. 11665 11666@item -C 11667Overwrite locally modified files with clean copies from 11668the repository (the modified file is saved in 11669@file{.#@var{file}.@var{revision}}, however). 11670 11671@item -D @var{date} 11672Check out revisions as of @var{date} (is sticky). See 11673@ref{Common options}. 11674 11675@item -d 11676Create directories. See @ref{update options}. 11677 11678@item -f 11679Use head revision if tag/date not found. See 11680@ref{Common options}. 11681 11682@item -I @var{ign} 11683More files to ignore (! to reset). See 11684@ref{import options}. 11685 11686@c Probably want to use rev1/rev2 style like for diff 11687@c -r. Here and in on-line help. 11688@item -j @var{rev} 11689Merge in changes. See @ref{update options}. 11690 11691@item -k @var{kflag} 11692Use @var{kflag} keyword expansion. See 11693@ref{Substitution modes}. 11694 11695@item -l 11696Local; run only in current working directory. @xref{Recursive behavior}. 11697 11698@item -P 11699Prune empty directories. See @ref{Moving directories}. 11700 11701@item -p 11702Check out files to standard output (avoids 11703stickiness). See @ref{update options}. 11704 11705@item -R 11706Operate recursively (default). @xref{Recursive 11707behavior}. 11708 11709@item -r @var{tag} 11710Checkout revision @var{tag} (is sticky). See @ref{Common options}. 11711 11712@item -W @var{spec} 11713More wrappers. See @ref{import options}. 11714@end table 11715 11716@c ------------------------------------------------------------ 11717@item version 11718@cindex version (subcommand) 11719 11720Display the version of @sc{cvs} being used. If the repository 11721is remote, display both the client and server versions. 11722 11723@c ------------------------------------------------------------ 11724@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 11725 11726on/off: turn on/off read-only checkouts of files. See 11727@ref{Setting a watch}. 11728 11729add/remove: add or remove notification on actions. See 11730@ref{Getting Notified}. 11731 11732@table @code 11733@item -a @var{actions} 11734Specify actions for temporary watch, where 11735@var{actions} is @code{edit}, @code{unedit}, 11736@code{commit}, @code{all}, or @code{none}. See 11737@ref{Editing files}. 11738 11739@item -l 11740Local; run only in current working directory. See @ref{Recursive behavior}. 11741 11742@item -R 11743Operate recursively (default). @xref{Recursive 11744behavior}. 11745@end table 11746 11747@c ------------------------------------------------------------ 11748@item watchers [@var{options}] [@var{files}@dots{}] 11749See who is watching a file. See @ref{Watch information}. 11750 11751@table @code 11752@item -l 11753Local; run only in current working directory. See @ref{Recursive behavior}. 11754 11755@item -R 11756Operate recursively (default). @xref{Recursive 11757behavior}. 11758@end table 11759 11760@end table 11761 11762@c --------------------------------------------------------------------- 11763@node Administrative files 11764@appendix Reference manual for Administrative files 11765@cindex Administrative files (reference) 11766@cindex Files, reference manual 11767@cindex Reference manual (files) 11768@cindex CVSROOT (file) 11769 11770@c FIXME? Somewhere there needs to be a more "how-to" 11771@c guide to writing these. I think the triggers 11772@c (commitinfo, loginfo, taginfo, &c) are perhaps a 11773@c different case than files like modules. One 11774@c particular issue that people sometimes are 11775@c (unnecessarily?) worried about is performance, and 11776@c the impact of writing in perl or sh or ____. 11777Inside the repository, in the directory 11778@file{$CVSROOT/CVSROOT}, there are a number of 11779supportive files for @sc{cvs}. You can use @sc{cvs} in a limited 11780fashion without any of them, but if they are set up 11781properly they can help make life easier. For a 11782discussion of how to edit them, see @ref{Intro 11783administrative files}. 11784 11785The most important of these files is the @file{modules} 11786file, which defines the modules inside the repository. 11787 11788@menu 11789* modules:: Defining modules 11790* Wrappers:: Specify binary-ness based on file name 11791* commit files:: The commit support files (commitinfo, 11792 verifymsg, editinfo, loginfo) 11793* rcsinfo:: Templates for the log messages 11794* cvsignore:: Ignoring files via cvsignore 11795* checkoutlist:: Adding your own administrative files 11796* history file:: History information 11797* Variables:: Various variables are expanded 11798* config:: Miscellaneous CVS configuration 11799@end menu 11800 11801@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11802@node modules 11803@appendixsec The modules file 11804@cindex Modules (admin file) 11805@cindex Defining modules (reference manual) 11806 11807The @file{modules} file records your definitions of 11808names for collections of source code. @sc{cvs} will 11809use these definitions if you use @sc{cvs} to update the 11810modules file (use normal commands like @code{add}, 11811@code{commit}, etc). 11812 11813The @file{modules} file may contain blank lines and 11814comments (lines beginning with @samp{#}) as well as 11815module definitions. Long lines can be continued on the 11816next line by specifying a backslash (@samp{\}) as the 11817last character on the line. 11818 11819There are three basic types of modules: alias modules, 11820regular modules, and ampersand modules. The difference 11821between them is the way that they map files in the 11822repository to files in the working directory. In all 11823of the following examples, the top-level repository 11824contains a directory called @file{first-dir}, which 11825contains two files, @file{file1} and @file{file2}, and a 11826directory @file{sdir}. @file{first-dir/sdir} contains 11827a file @file{sfile}. 11828 11829@c FIXME: should test all the examples in this section. 11830 11831@menu 11832* Alias modules:: The simplest kind of module 11833* Regular modules:: 11834* Ampersand modules:: 11835* Excluding directories:: Excluding directories from a module 11836* Module options:: Regular and ampersand modules can take options 11837* Module program options:: How the modules ``program options'' programs 11838 are run. 11839@end menu 11840 11841@node Alias modules 11842@appendixsubsec Alias modules 11843@cindex Alias modules 11844@cindex -a, in modules file 11845 11846Alias modules are the simplest kind of module: 11847 11848@table @code 11849@item @var{mname} -a @var{aliases}@dots{} 11850This represents the simplest way of defining a module 11851@var{mname}. The @samp{-a} flags the definition as a 11852simple alias: @sc{cvs} will treat any use of @var{mname} (as 11853a command argument) as if the list of names 11854@var{aliases} had been specified instead. 11855@var{aliases} may contain either other module names or 11856paths. When you use paths in aliases, @code{checkout} 11857creates all intermediate directories in the working 11858directory, just as if the path had been specified 11859explicitly in the @sc{cvs} arguments. 11860@end table 11861 11862For example, if the modules file contains: 11863 11864@example 11865amodule -a first-dir 11866@end example 11867 11868@noindent 11869then the following two commands are equivalent: 11870 11871@example 11872$ cvs co amodule 11873$ cvs co first-dir 11874@end example 11875 11876@noindent 11877and they each would provide output such as: 11878 11879@example 11880cvs checkout: Updating first-dir 11881U first-dir/file1 11882U first-dir/file2 11883cvs checkout: Updating first-dir/sdir 11884U first-dir/sdir/sfile 11885@end example 11886 11887@node Regular modules 11888@appendixsubsec Regular modules 11889@cindex Regular modules 11890 11891@table @code 11892@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 11893In the simplest case, this form of module definition 11894reduces to @samp{@var{mname} @var{dir}}. This defines 11895all the files in directory @var{dir} as module mname. 11896@var{dir} is a relative path (from @code{$CVSROOT}) to a 11897directory of source in the source repository. In this 11898case, on checkout, a single directory called 11899@var{mname} is created as a working directory; no 11900intermediate directory levels are used by default, even 11901if @var{dir} was a path involving several directory 11902levels. 11903@end table 11904 11905For example, if a module is defined by: 11906 11907@example 11908regmodule first-dir 11909@end example 11910 11911@noindent 11912then regmodule will contain the files from first-dir: 11913 11914@example 11915$ cvs co regmodule 11916cvs checkout: Updating regmodule 11917U regmodule/file1 11918U regmodule/file2 11919cvs checkout: Updating regmodule/sdir 11920U regmodule/sdir/sfile 11921$ 11922@end example 11923 11924By explicitly specifying files in the module definition 11925after @var{dir}, you can select particular files from 11926directory @var{dir}. Here is 11927an example: 11928 11929@example 11930regfiles first-dir/sdir sfile 11931@end example 11932 11933@noindent 11934With this definition, getting the regfiles module 11935will create a single working directory 11936@file{regfiles} containing the file listed, which 11937comes from a directory deeper 11938in the @sc{cvs} source repository: 11939 11940@example 11941$ cvs co regfiles 11942U regfiles/sfile 11943$ 11944@end example 11945 11946@node Ampersand modules 11947@appendixsubsec Ampersand modules 11948@cindex Ampersand modules 11949@cindex &, in modules file 11950 11951A module definition can refer to other modules by 11952including @samp{&@var{module}} in its definition. 11953@example 11954@var{mname} [ options ] @var{&module}@dots{} 11955@end example 11956 11957Then getting the module creates a subdirectory for each such 11958module, in the directory containing the module. For 11959example, if modules contains 11960 11961@example 11962ampermod &first-dir 11963@end example 11964 11965@noindent 11966then a checkout will create an @code{ampermod} directory 11967which contains a directory called @code{first-dir}, 11968which in turns contains all the directories and files 11969which live there. For example, the command 11970 11971@example 11972$ cvs co ampermod 11973@end example 11974 11975@noindent 11976will create the following files: 11977 11978@example 11979ampermod/first-dir/file1 11980ampermod/first-dir/file2 11981ampermod/first-dir/sdir/sfile 11982@end example 11983 11984There is one quirk/bug: the messages that @sc{cvs} 11985prints omit the @file{ampermod}, and thus do not 11986correctly display the location to which it is checking 11987out the files: 11988 11989@example 11990$ cvs co ampermod 11991cvs checkout: Updating first-dir 11992U first-dir/file1 11993U first-dir/file2 11994cvs checkout: Updating first-dir/sdir 11995U first-dir/sdir/sfile 11996$ 11997@end example 11998 11999Do not rely on this buggy behavior; it may get fixed in 12000a future release of @sc{cvs}. 12001 12002@c FIXCVS: What happens if regular and & modules are 12003@c combined, as in "ampermodule first-dir &second-dir"? 12004@c When I tried it, it seemed to just ignore the 12005@c "first-dir". I think perhaps it should be an error 12006@c (but this needs further investigation). 12007@c In addition to discussing what each one does, we 12008@c should put in a few words about why you would use one or 12009@c the other in various situations. 12010 12011@node Excluding directories 12012@appendixsubsec Excluding directories 12013@cindex Excluding directories, in modules file 12014@cindex !, in modules file 12015 12016An alias module may exclude particular directories from 12017other modules by using an exclamation mark (@samp{!}) 12018before the name of each directory to be excluded. 12019 12020For example, if the modules file contains: 12021 12022@example 12023exmodule -a !first-dir/sdir first-dir 12024@end example 12025 12026@noindent 12027then checking out the module @samp{exmodule} will check 12028out everything in @samp{first-dir} except any files in 12029the subdirectory @samp{first-dir/sdir}. 12030@c Note that the "!first-dir/sdir" sometimes must be listed 12031@c before "first-dir". That seems like a probable bug, in which 12032@c case perhaps it should be fixed (to allow either 12033@c order) rather than documented. See modules4 in testsuite. 12034 12035@node Module options 12036@appendixsubsec Module options 12037@cindex Options, in modules file 12038 12039Either regular modules or ampersand modules can contain 12040options, which supply additional information concerning 12041the module. 12042 12043@table @code 12044@cindex -d, in modules file 12045@item -d @var{name} 12046Name the working directory something other than the 12047module name. 12048@c FIXME: Needs a bunch of examples, analogous to the 12049@c examples for alias, regular, and ampersand modules 12050@c which show where the files go without -d. 12051 12052@cindex Export program 12053@cindex -e, in modules file 12054@item -e @var{prog} 12055Specify a program @var{prog} to run whenever files in a 12056module are exported. @var{prog} runs with a single 12057argument, the module name. 12058@c FIXME: Is it run on server? client? 12059 12060@cindex Checkout program 12061@cindex -o, in modules file 12062@item -o @var{prog} 12063Specify a program @var{prog} to run whenever files in a 12064module are checked out. @var{prog} runs with a single 12065argument, the module name. See @ref{Module program options} for 12066information on how @var{prog} is called. 12067@c FIXME: Is it run on server? client? 12068 12069@cindex Status of a module 12070@cindex Module status 12071@cindex -s, in modules file 12072@item -s @var{status} 12073Assign a status to the module. When the module file is 12074printed with @samp{cvs checkout -s} the modules are 12075sorted according to primarily module status, and 12076secondarily according to the module name. This option 12077has no other meaning. You can use this option for 12078several things besides status: for instance, list the 12079person that is responsible for this module. 12080 12081@cindex Tag program 12082@cindex -t, in modules file 12083@item -t @var{prog} 12084Specify a program @var{prog} to run whenever files in a 12085module are tagged with @code{rtag}. @var{prog} runs 12086with two arguments: the module name and the symbolic 12087tag specified to @code{rtag}. It is not run 12088when @code{tag} is executed. Generally you will find 12089that taginfo is a better solution (@pxref{user-defined logging}). 12090@c FIXME: Is it run on server? client? 12091@c Problems with -t include: 12092@c * It is run after the tag not before 12093@c * It doesn't get passed all the information that 12094@c taginfo does ("mov", &c). 12095@c * It only is run for rtag, not tag. 12096@end table 12097 12098You should also see @pxref{Module program options} about how the 12099``program options'' programs are run. 12100 12101@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12102 12103@node Module program options 12104@appendixsubsec How the modules file ``program options'' programs are run 12105@cindex Modules file program options 12106@cindex -t, in modules file 12107@cindex -o, in modules file 12108@cindex -e, in modules file 12109 12110@noindent 12111For checkout, rtag, and export, the program is server-based, and as such the 12112following applies:- 12113 12114If using remote access methods (pserver, ext, etc.), 12115@sc{cvs} will execute this program on the server from a temporary 12116directory. The path is searched for this program. 12117 12118If using ``local access'' (on a local or remote NFS file system, i.e. 12119repository set just to a path), 12120the program will be executed from the newly checked-out tree, if 12121found there, or alternatively searched for in the path if not. 12122 12123The programs are all run after the operation has effectively 12124completed. 12125 12126 12127@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12128@node Wrappers 12129@appendixsec The cvswrappers file 12130@cindex cvswrappers (admin file) 12131@cindex CVSWRAPPERS, environment variable 12132@cindex Wrappers 12133 12134@c FIXME: need some better way of separating this out 12135@c by functionality. -m is 12136@c one feature, and -k is a another. And this discussion 12137@c should be better motivated (e.g. start with the 12138@c problems, then explain how the feature solves it). 12139 12140Wrappers refers to a @sc{cvs} feature which lets you 12141control certain settings based on the name of the file 12142which is being operated on. The settings are @samp{-k} 12143for binary files, and @samp{-m} for nonmergeable text 12144files. 12145 12146The @samp{-m} option 12147specifies the merge methodology that should be used when 12148a non-binary file is updated. @code{MERGE} means the usual 12149@sc{cvs} behavior: try to merge the files. @code{COPY} 12150means that @code{cvs update} will refuse to merge 12151files, as it also does for files specified as binary 12152with @samp{-kb} (but if the file is specified as 12153binary, there is no need to specify @samp{-m 'COPY'}). 12154@sc{cvs} will provide the user with the 12155two versions of the files, and require the user using 12156mechanisms outside @sc{cvs}, to insert any necessary 12157changes. 12158 12159@strong{WARNING: do not use @code{COPY} with 12160@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 12161copy one version of your file over the other, wiping 12162out the previous contents.} 12163@c Ordinarily we don't document the behavior of old 12164@c versions. But this one is so dangerous, I think we 12165@c must. I almost renamed it to -m 'NOMERGE' so we 12166@c could say "never use -m 'COPY'". 12167The @samp{-m} wrapper option only affects behavior when 12168merging is done on update; it does not affect how files 12169are stored. See @ref{Binary files}, for more on 12170binary files. 12171 12172The basic format of the file @file{cvswrappers} is: 12173 12174@c FIXME: @example is all wrong for this. Use @deffn or 12175@c something more sensible. 12176@example 12177wildcard [option value][option value]... 12178 12179where option is one of 12180-m update methodology value: MERGE or COPY 12181-k keyword expansion value: expansion mode 12182 12183and value is a single-quote delimited value. 12184@end example 12185 12186 12187@c FIXME: We don't document -W or point to where it is 12188@c documented. Or .cvswrappers. 12189For example, the following command imports a 12190directory, treating files whose name ends in 12191@samp{.exe} as binary: 12192 12193@example 12194cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 12195@end example 12196 12197@c Another good example, would be storing files 12198@c (e.g. binary files) compressed in the repository. 12199@c :::::::::::::::::: 12200@c cvswrappers 12201@c :::::::::::::::::: 12202@c *.t12 -m 'COPY' 12203@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 12204@c 12205@c :::::::::::::::::: 12206@c gunzipcp 12207@c :::::::::::::::::: 12208@c : 12209@c [ -f $1 ] || exit 1 12210@c zcat $1 > /tmp/.#$1.$$ 12211@c mv /tmp/.#$1.$$ $1 12212@c 12213@c :::::::::::::::::: 12214@c gzipcp 12215@c :::::::::::::::::: 12216@c : 12217@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 12218@c if [ ! -d $DIRNAME ] ; then 12219@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 12220@c fi 12221@c gzip -c $DIRNAME > $2 12222@c One catch--"cvs diff" will not invoke the wrappers 12223@c (probably a CVS bug, although I haven't thought it out). 12224 12225@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12226@node commit files 12227@appendixsec The commit support files 12228@cindex Committing, administrative support files 12229 12230The @samp{-i} flag in the @file{modules} file can be 12231used to run a certain program whenever files are 12232committed (@pxref{modules}). The files described in 12233this section provide other, more flexible, ways to run 12234programs whenever something is committed. 12235 12236There are three kind of programs that can be run on 12237commit. They are specified in files in the repository, 12238as described below. The following table summarizes the 12239file names and the purpose of the corresponding 12240programs. 12241 12242@table @file 12243@item commitinfo 12244The program is responsible for checking that the commit 12245is allowed. If it exits with a non-zero exit status 12246the commit will be aborted. 12247 12248@item verifymsg 12249The specified program is used to evaluate the log message, 12250and possibly verify that it contains all required 12251fields. This is most useful in combination with the 12252@file{rcsinfo} file, which can hold a log message 12253template (@pxref{rcsinfo}). 12254 12255@item editinfo 12256The specified program is used to edit the log message, 12257and possibly verify that it contains all required 12258fields. This is most useful in combination with the 12259@file{rcsinfo} file, which can hold a log message 12260template (@pxref{rcsinfo}). (obsolete) 12261 12262@item loginfo 12263The specified program is called when the commit is 12264complete. It receives the log message and some 12265additional information and can store the log message in 12266a file, or mail it to appropriate persons, or maybe 12267post it to a local newsgroup, or@dots{} Your 12268imagination is the limit! 12269@end table 12270 12271@menu 12272* syntax:: The common syntax 12273* commitinfo:: Pre-commit checking 12274* verifymsg:: How are log messages evaluated? 12275* editinfo:: Specifying how log messages are created 12276 (obsolete) 12277* loginfo:: Where should log messages be sent? 12278@end menu 12279 12280@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12281@node syntax 12282@appendixsubsec The common syntax 12283@cindex Info files (syntax) 12284@cindex Syntax of info files 12285@cindex Common syntax of info files 12286 12287@c FIXME: having this so totally separate from the 12288@c Variables node is rather bogus. 12289 12290The administrative files such as @file{commitinfo}, 12291@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 12292all have a common format. The purpose of the files are 12293described later on. The common syntax is described 12294here. 12295 12296@cindex Regular expression syntax 12297Each line contains the following: 12298@itemize @bullet 12299@item 12300@c Say anything about DEFAULT and ALL? Right now we 12301@c leave that to the description of each file (and in fact 12302@c the practice is inconsistent which is really annoying). 12303A regular expression. This is a basic regular 12304expression in the syntax used by GNU emacs. 12305@c FIXME: What we probably should be saying is "POSIX Basic 12306@c Regular Expression with the following extensions (`\(' 12307@c `\|' '+' etc)" 12308@c rather than define it with reference to emacs. 12309@c The reference to emacs is not strictly speaking 12310@c true, as we don't support \=, \s, or \S. Also it isn't 12311@c clear we should document and/or promise to continue to 12312@c support all the obscure emacs extensions like \<. 12313@c Also need to better cite (or include) full 12314@c documentation for the syntax. 12315@c Also see comment in configure.in about what happens to the 12316@c syntax if we pick up a system-supplied regexp matcher. 12317 12318@item 12319A whitespace separator---one or more spaces and/or tabs. 12320 12321@item 12322A file name or command-line template. 12323@end itemize 12324 12325@noindent 12326Blank lines are ignored. Lines that start with the 12327character @samp{#} are treated as comments. Long lines 12328unfortunately can @emph{not} be broken in two parts in 12329any way. 12330 12331The first regular expression that matches the current 12332directory name in the repository is used. The rest of the line 12333is used as a file name or command-line as appropriate. 12334 12335@c FIXME: need an example. In particular, show what 12336@c the regular expression is matched against (one 12337@c ordinarily clueful person got confused about whether it 12338@c includes the filename--"directory name" above should be 12339@c unambiguous but there is nothing like an example to 12340@c confirm people's understanding of this sort of thing). 12341 12342@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12343@node commitinfo 12344@appendixsubsec Commitinfo 12345@cindex @file{commitinfo} 12346@cindex Commits, precommit verification of 12347@cindex Precommit checking 12348 12349The @file{commitinfo} file defines programs to execute 12350whenever @samp{cvs commit} is about to execute. These 12351programs are used for pre-commit checking to verify 12352that the modified, added and removed files are really 12353ready to be committed. This could be used, for 12354instance, to verify that the changed files conform to 12355to your site's standards for coding practice. 12356 12357As mentioned earlier, each line in the 12358@file{commitinfo} file consists of a regular expression 12359and a command-line template. The template can include 12360a program name and any number of arguments you wish to 12361supply to it. The full path to the current source 12362repository is appended to the template, followed by the 12363file names of any files involved in the commit (added, 12364removed, and modified files). 12365 12366@cindex Exit status, of commitinfo 12367The first line with a regular expression matching the 12368directory within the repository will be used. If the 12369command returns a non-zero exit status the commit will 12370be aborted. 12371@c FIXME: need example(s) of what "directory within the 12372@c repository" means. 12373 12374@cindex DEFAULT in commitinfo 12375If the repository name does not match any of the 12376regular expressions in this file, the @samp{DEFAULT} 12377line is used, if it is specified. 12378 12379@cindex ALL in commitinfo 12380All occurrences of the name @samp{ALL} appearing as a 12381regular expression are used in addition to the first 12382matching regular expression or the name @samp{DEFAULT}. 12383 12384@cindex @file{commitinfo}, working directory 12385@cindex @file{commitinfo}, command environment 12386The command will be run in the root of the workspace 12387containing the new versions of any files the user would like 12388to modify (commit), @emph{or in a copy of the workspace on 12389the server (@pxref{Remote repositories})}. If a file is 12390being removed, there will be no copy of the file under the 12391current directory. If a file is being added, there will be 12392no corresponding archive file in the repository unless the 12393file is being resurrected. 12394 12395Note that both the repository directory and the corresponding 12396Attic (@pxref{Attic}) directory may need to be checked to 12397locate the archive file corresponding to any given file being 12398committed. Much of the information about the specific commit 12399request being made, including the destination branch, commit 12400message, and command line options specified, is not available 12401to the command. 12402 12403@c FIXME: should discuss using commitinfo to control 12404@c who has checkin access to what (e.g. Joe can check into 12405@c directories a, b, and c, and Mary can check into 12406@c directories b, c, and d--note this case cannot be 12407@c conveniently handled with unix groups). Of course, 12408@c adding a new set of features to CVS might be a more 12409@c natural way to fix this problem than telling people to 12410@c use commitinfo. 12411@c FIXME: Should make some reference, especially in 12412@c the context of controlling who has access, to the fact 12413@c that commitinfo can be circumvented. Perhaps 12414@c mention SETXID (but has it been carefully examined 12415@c for holes?). This fits in with the discussion of 12416@c general CVS security in "Password authentication 12417@c security" (the bit which is not pserver-specific). 12418 12419@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12420@node verifymsg 12421@appendixsubsec Verifying log messages 12422@cindex @file{verifymsg} (admin file) 12423@cindex Log message, verifying 12424 12425Once you have entered a log message, you can evaluate 12426that message to check for specific content, such as 12427a bug ID. Use the @file{verifymsg} file to 12428specify a program that is used to verify the log message. 12429This program could be a simple script that checks 12430that the entered message contains the required fields. 12431 12432The @file{verifymsg} file is often most useful together 12433with the @file{rcsinfo} file, which can be used to 12434specify a log message template. 12435 12436Each line in the @file{verifymsg} file consists of a 12437regular expression and a command-line template. The 12438template must include a program name, and can include 12439any number of arguments. The full path to the current 12440log message template file is appended to the template. 12441 12442One thing that should be noted is that the @samp{ALL} 12443keyword is not supported. If more than one matching 12444line is found, the first one is used. This can be 12445useful for specifying a default verification script in a 12446directory, and then overriding it in a subdirectory. 12447 12448@cindex DEFAULT in @file{verifymsg} 12449If the repository name does not match any of the 12450regular expressions in this file, the @samp{DEFAULT} 12451line is used, if it is specified. 12452 12453@cindex Exit status, of @file{verifymsg} 12454If the verification script exits with a non-zero exit status, 12455the commit is aborted. 12456 12457@cindex @file{verifymsg}, changing the log message 12458In the default configuration, CVS allows the 12459verification script to change the log message. This is 12460controlled via the RereadLogAfterVerify CVSROOT/config 12461option. 12462 12463When @samp{RereadLogAfterVerify=always} or 12464@samp{RereadLogAfterVerify=stat}, the log message will 12465either always be reread after the verification script 12466is run or reread only if the log message file status 12467has changed. 12468 12469@xref{config}, for more on CVSROOT/config options. 12470 12471It is NOT a good idea for a @file{verifymsg} script to 12472interact directly with the user in the various 12473client/server methods. For the @code{pserver} method, 12474there is no protocol support for communicating between 12475@file{verifymsg} and the client on the remote end. For the 12476@code{ext} and @code{server} methods, it is possible 12477for CVS to become confused by the characters going 12478along the same channel as the CVS protocol 12479messages. See @ref{Remote repositories}, for more 12480information on client/server setups. In addition, at the time 12481the @file{verifymsg} script runs, the CVS 12482server has locks in place in the repository. If control is 12483returned to the user here then other users may be stuck waiting 12484for access to the repository. 12485 12486This option can be useful if you find yourself using an 12487rcstemplate that needs to be modified to remove empty 12488elements or to fill in default values. It can also be 12489useful if the rcstemplate has changed in the repository 12490and the CVS/Template was not updated, but is able to be 12491adapted to the new format by the verification script 12492that is run by @file{verifymsg}. 12493 12494An example of an update might be to change all 12495occurrences of 'BugId:' to be 'DefectId:' (which can be 12496useful if the rcstemplate has recently been changed and 12497there are still checked-out user trees with cached 12498copies in the CVS/Template file of the older version). 12499 12500Another example of an update might be to delete a line 12501that contains 'BugID: none' from the log message after 12502validation of that value as being allowed is made. 12503 12504The following is a little silly example of a 12505@file{verifymsg} file, together with the corresponding 12506@file{rcsinfo} file, the log message template and an 12507verification script. We begin with the log message template. 12508We want to always record a bug-id number on the first 12509line of the log message. The rest of log message is 12510free text. The following template is found in the file 12511@file{/usr/cvssupport/tc.template}. 12512 12513@example 12514BugId: 12515@end example 12516 12517The script @file{/usr/cvssupport/bugid.verify} is used to 12518evaluate the log message. 12519 12520@example 12521#!/bin/sh 12522# 12523# bugid.verify filename 12524# 12525# Verify that the log message contains a valid bugid 12526# on the first line. 12527# 12528if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 12529 exit 0 12530elif head -1 < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 12531 # It is okay to allow commits with 'BugId: none', 12532 # but do not put that text into the real log message. 12533 grep -v '^BugId:[ ]*none$' > $1.rewrite 12534 mv $1.rewrite $1 12535 exit 0 12536else 12537 echo "No BugId found." 12538 exit 1 12539fi 12540@end example 12541 12542The @file{verifymsg} file contains this line: 12543 12544@example 12545^tc /usr/cvssupport/bugid.verify 12546@end example 12547 12548The @file{rcsinfo} file contains this line: 12549 12550@example 12551^tc /usr/cvssupport/tc.template 12552@end example 12553 12554The @file{config} file contains this line: 12555 12556@example 12557RereadLogAfterVerify=always 12558@end example 12559 12560 12561 12562@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12563@node editinfo 12564@appendixsubsec Editinfo 12565@cindex editinfo (admin file) 12566@cindex Editor, specifying per module 12567@cindex Per-module editor 12568@cindex Log messages, editing 12569 12570@strong{Note: The @file{editinfo} feature has been 12571rendered obsolete. To set a default editor for log 12572messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables 12573(@pxref{Environment variables}) or the @samp{-e} global 12574option (@pxref{Global options}). See @ref{verifymsg}, 12575for information on the use of the @file{verifymsg} 12576feature for evaluating log messages.} 12577 12578If you want to make sure that all log messages look the 12579same way, you can use the @file{editinfo} file to 12580specify a program that is used to edit the log message. 12581This program could be a custom-made editor that always 12582enforces a certain style of the log message, or maybe a 12583simple shell script that calls an editor, and checks 12584that the entered message contains the required fields. 12585 12586If no matching line is found in the @file{editinfo} 12587file, the editor specified in the environment variable 12588@code{$CVSEDITOR} is used instead. If that variable is 12589not set, then the environment variable @code{$EDITOR} 12590is used instead. If that variable is not 12591set a default will be used. See @ref{Committing your changes}. 12592 12593The @file{editinfo} file is often most useful together 12594with the @file{rcsinfo} file, which can be used to 12595specify a log message template. 12596 12597Each line in the @file{editinfo} file consists of a 12598regular expression and a command-line template. The 12599template must include a program name, and can include 12600any number of arguments. The full path to the current 12601log message template file is appended to the template. 12602 12603One thing that should be noted is that the @samp{ALL} 12604keyword is not supported. If more than one matching 12605line is found, the first one is used. This can be 12606useful for specifying a default edit script in a 12607module, and then overriding it in a subdirectory. 12608 12609@cindex DEFAULT in editinfo 12610If the repository name does not match any of the 12611regular expressions in this file, the @samp{DEFAULT} 12612line is used, if it is specified. 12613 12614If the edit script exits with a non-zero exit status, 12615the commit is aborted. 12616 12617Note: when @sc{cvs} is accessing a remote repository, 12618or when the @samp{-m} or @samp{-F} options to @code{cvs 12619commit} are used, @file{editinfo} will not be consulted. 12620There is no good workaround for this; use 12621@file{verifymsg} instead. 12622 12623@menu 12624* editinfo example:: Editinfo example 12625@end menu 12626 12627@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12628@node editinfo example 12629@appendixsubsubsec Editinfo example 12630 12631The following is a little silly example of a 12632@file{editinfo} file, together with the corresponding 12633@file{rcsinfo} file, the log message template and an 12634editor script. We begin with the log message template. 12635We want to always record a bug-id number on the first 12636line of the log message. The rest of log message is 12637free text. The following template is found in the file 12638@file{/usr/cvssupport/tc.template}. 12639 12640@example 12641BugId: 12642@end example 12643 12644The script @file{/usr/cvssupport/bugid.edit} is used to 12645edit the log message. 12646 12647@example 12648#!/bin/sh 12649# 12650# bugid.edit filename 12651# 12652# Call $EDITOR on FILENAME, and verify that the 12653# resulting file contains a valid bugid on the first 12654# line. 12655if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi 12656if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi 12657$CVSEDITOR $1 12658until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1 12659do echo -n "No BugId found. Edit again? ([y]/n)" 12660 read ans 12661 case $@{ans@} in 12662 n*) exit 1;; 12663 esac 12664 $CVSEDITOR $1 12665done 12666@end example 12667 12668The @file{editinfo} file contains this line: 12669 12670@example 12671^tc /usr/cvssupport/bugid.edit 12672@end example 12673 12674The @file{rcsinfo} file contains this line: 12675 12676@example 12677^tc /usr/cvssupport/tc.template 12678@end example 12679 12680@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12681@node loginfo 12682@appendixsubsec Loginfo 12683@cindex loginfo (admin file) 12684@cindex Storing log messages 12685@cindex Mailing log messages 12686@cindex Distributing log messages 12687@cindex Log messages 12688 12689@c "cvs commit" is not quite right. What we 12690@c mean is "when the repository gets changed" which 12691@c also includes "cvs import" and "cvs add" on a directory. 12692The @file{loginfo} file is used to control where 12693@samp{cvs commit} log information is sent. The first 12694entry on a line is a regular expression which is tested 12695against the directory that the change is being made to, 12696relative to the @code{$CVSROOT}. If a match is found, then 12697the remainder of the line is a filter program that 12698should expect log information on its standard input. 12699 12700If the repository name does not match any of the 12701regular expressions in this file, the @samp{DEFAULT} 12702line is used, if it is specified. 12703 12704All occurrences of the name @samp{ALL} appearing as a 12705regular expression are used in addition to the first 12706matching regular expression or @samp{DEFAULT}. 12707 12708The first matching regular expression is used. 12709 12710@xref{commit files}, for a description of the syntax of 12711the @file{loginfo} file. 12712 12713The user may specify a format string as 12714part of the filter. The string is composed of a 12715@samp{%} followed by a space, or followed by a single 12716format character, or followed by a set of format 12717characters surrounded by @samp{@{} and @samp{@}} as 12718separators. The format characters are: 12719 12720@table @t 12721@item s 12722file name 12723@item V 12724old version number (pre-checkin) 12725@item v 12726new version number (post-checkin) 12727@end table 12728 12729All other characters that appear in a format string 12730expand to an empty field (commas separating fields are 12731still provided). 12732 12733For example, some valid format strings are @samp{%}, 12734@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 12735 12736The output will be a space separated string of tokens enclosed in 12737quotation marks (@t{"}). 12738Any embedded dollar signs (@t{$}), backticks (@t{`}), 12739backslashes (@t{\}), or quotation marks will be preceded 12740by a backslash (this allows the shell to correctly parse it 12741as a single string, regardless of the characters it contains). 12742For backwards compatibility, the first 12743token will be the repository subdirectory. The rest of the 12744tokens will be comma-delimited lists of the information 12745requested in the format string. For example, if 12746@samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%@{sVv@}} 12747is the format string, and three files (@t{ChangeLog}, 12748@t{Makefile}, @t{foo.c}) were modified, the output 12749might be: 12750 12751@example 12752"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13" 12753@end example 12754 12755As another example, @samp{%@{@}} means that only the 12756name of the repository will be generated. 12757 12758Note: when @sc{cvs} is accessing a remote repository, 12759@file{loginfo} will be run on the @emph{remote} 12760(i.e., server) side, not the client side (@pxref{Remote 12761repositories}). 12762 12763@menu 12764* loginfo example:: Loginfo example 12765* Keeping a checked out copy:: Updating a tree on every checkin 12766@end menu 12767 12768@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12769@node loginfo example 12770@appendixsubsubsec Loginfo example 12771 12772The following @file{loginfo} file, together with the 12773tiny shell-script below, appends all log messages 12774to the file @file{$CVSROOT/CVSROOT/commitlog}, 12775and any commits to the administrative files (inside 12776the @file{CVSROOT} directory) are also logged in 12777@file{/usr/adm/cvsroot-log}. 12778Commits to the @file{prog1} directory are mailed to @t{ceder}. 12779 12780@c FIXME: is it a CVS feature or bug that only the 12781@c first matching line is used? It is documented 12782@c above, but is it useful? For example, if we wanted 12783@c to run both "cvs-log" and "Mail" for the CVSROOT 12784@c directory, it is kind of awkward if 12785@c only the first matching line is used. 12786@example 12787ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 12788^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log 12789^prog1 Mail -s %s ceder 12790@end example 12791 12792The shell-script @file{/usr/local/bin/cvs-log} looks 12793like this: 12794 12795@example 12796#!/bin/sh 12797(echo "------------------------------------------------------"; 12798 echo -n $2" "; 12799 date; 12800 echo; 12801 cat) >> $1 12802@end example 12803 12804@node Keeping a checked out copy 12805@appendixsubsubsec Keeping a checked out copy 12806 12807@c What other index entries? It seems like 12808@c people might want to use a lot of different 12809@c words for this functionality. 12810@cindex Keeping a checked out copy 12811@cindex Checked out copy, keeping 12812@cindex Web pages, maintaining with CVS 12813 12814It is often useful to maintain a directory tree which 12815contains files which correspond to the latest version 12816in the repository. For example, other developers might 12817want to refer to the latest sources without having to 12818check them out, or you might be maintaining a web site 12819with @sc{cvs} and want every checkin to cause the files 12820used by the web server to be updated. 12821@c Can we offer more details on the web example? Or 12822@c point the user at how to figure it out? This text 12823@c strikes me as sufficient for someone who already has 12824@c some idea of what we mean but not enough for the naive 12825@c user/sysadmin to understand it and set it up. 12826 12827The way to do this is by having loginfo invoke 12828@code{cvs update}. Doing so in the naive way will 12829cause a problem with locks, so the @code{cvs update} 12830must be run in the background. 12831@c Should we try to describe the problem with locks? 12832@c It seems like a digression for someone who just 12833@c wants to know how to make it work. 12834@c Another choice which might work for a single file 12835@c is to use "cvs -n update -p" which doesn't take 12836@c out locks (I think) but I don't see many advantages 12837@c of that and we might as well document something which 12838@c works for multiple files. 12839Here is an example for unix (this should all be on one line): 12840 12841@example 12842^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs; 12843 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 12844@end example 12845 12846This will cause checkins to repository directories 12847starting with @code{cyclic-pages} to update the checked 12848out tree in @file{/u/www/local-docs}. 12849@c More info on some of the details? The "sleep 2" is 12850@c so if we are lucky the lock will be gone by the time 12851@c we start and we can wait 2 seconds instead of 30. 12852 12853@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12854@node rcsinfo 12855@appendixsec Rcsinfo 12856@cindex rcsinfo (admin file) 12857@cindex Form for log message 12858@cindex Log message template 12859@cindex Template for log message 12860 12861The @file{rcsinfo} file can be used to specify a form to 12862edit when filling out the commit log. The 12863@file{rcsinfo} file has a syntax similar to the 12864@file{verifymsg}, @file{commitinfo} and @file{loginfo} 12865files. @xref{syntax}. Unlike the other files the second 12866part is @emph{not} a command-line template. Instead, 12867the part after the regular expression should be a full pathname to 12868a file containing the log message template. 12869 12870If the repository name does not match any of the 12871regular expressions in this file, the @samp{DEFAULT} 12872line is used, if it is specified. 12873 12874All occurrences of the name @samp{ALL} appearing as a 12875regular expression are used in addition to the first 12876matching regular expression or @samp{DEFAULT}. 12877 12878@c FIXME: should be offering advice, somewhere around 12879@c here, about where to put the template file. The 12880@c verifymsg example uses /usr/cvssupport but doesn't 12881@c say anything about what that directory is for or 12882@c whether it is hardwired into CVS or who creates 12883@c it or anything. In particular we should say 12884@c how to version control the template file. A 12885@c probably better answer than the /usr/cvssupport 12886@c stuff is to use checkoutlist (with xref to the 12887@c checkoutlist doc). 12888@c Also I am starting to see a connection between 12889@c this and the Keeping a checked out copy node. 12890@c Probably want to say something about that. 12891The log message template will be used as a default log 12892message. If you specify a log message with @samp{cvs 12893commit -m @var{message}} or @samp{cvs commit -f 12894@var{file}} that log message will override the 12895template. 12896 12897@xref{verifymsg}, for an example @file{rcsinfo} 12898file. 12899 12900When @sc{cvs} is accessing a remote repository, 12901the contents of @file{rcsinfo} at the time a directory 12902is first checked out will specify a template. This 12903template will be updated on all @samp{cvs update} 12904commands. It will also be added to new directories 12905added with a @samp{cvs add new-directry} command. 12906In versions of @sc{cvs} prior to version 1.12, the 12907@file{CVS/Template} file was not updated. If the 12908@sc{cvs} server is at version 1.12 or higher an older 12909client may be used and the @file{CVS/Template} will 12910be updated from the server. 12911 12912@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12913@node cvsignore 12914@appendixsec Ignoring files via cvsignore 12915@cindex cvsignore (admin file), global 12916@cindex Global cvsignore 12917@cindex Ignoring files 12918@c -- This chapter should maybe be moved to the 12919@c tutorial part of the manual? 12920 12921There are certain file names that frequently occur 12922inside your working copy, but that you don't want to 12923put under @sc{cvs} control. Examples are all the object 12924files that you get while you compile your sources. 12925Normally, when you run @samp{cvs update}, it prints a 12926line for each file it encounters that it doesn't know 12927about (@pxref{update output}). 12928 12929@sc{cvs} has a list of files (or sh(1) file name patterns) 12930that it should ignore while running @code{update}, 12931@code{import} and @code{release}. 12932@c -- Are those the only three commands affected? 12933This list is constructed in the following way. 12934 12935@itemize @bullet 12936@item 12937The list is initialized to include certain file name 12938patterns: names associated with @sc{cvs} 12939administration, or with other common source control 12940systems; common names for patch files, object files, 12941archive files, and editor backup files; and other names 12942that are usually artifacts of assorted utilities. 12943Currently, the default list of ignored file name 12944patterns is: 12945 12946@cindex Ignored files 12947@cindex Automatically ignored files 12948@example 12949 RCS SCCS CVS CVS.adm 12950 RCSLOG cvslog.* 12951 tags TAGS 12952 .make.state .nse_depinfo 12953 *~ #* .#* ,* _$* *$ 12954 *.old *.bak *.BAK *.orig *.rej .del-* 12955 *.a *.olb *.o *.obj *.so *.exe 12956 *.Z *.elc *.ln 12957 core 12958@end example 12959 12960@item 12961The per-repository list in 12962@file{$CVSROOT/CVSROOT/cvsignore} is appended to 12963the list, if that file exists. 12964 12965@item 12966The per-user list in @file{.cvsignore} in your home 12967directory is appended to the list, if it exists. 12968 12969@item 12970Any entries in the environment variable 12971@code{$CVSIGNORE} is appended to the list. 12972 12973@item 12974Any @samp{-I} options given to @sc{cvs} is appended. 12975 12976@item 12977As @sc{cvs} traverses through your directories, the contents 12978of any @file{.cvsignore} will be appended to the list. 12979The patterns found in @file{.cvsignore} are only valid 12980for the directory that contains them, not for 12981any sub-directories. 12982@end itemize 12983 12984In any of the 5 places listed above, a single 12985exclamation mark (@samp{!}) clears the ignore list. 12986This can be used if you want to store any file which 12987normally is ignored by @sc{cvs}. 12988 12989Specifying @samp{-I !} to @code{cvs import} will import 12990everything, which is generally what you want to do if 12991you are importing files from a pristine distribution or 12992any other source which is known to not contain any 12993extraneous files. However, looking at the rules above 12994you will see there is a fly in the ointment; if the 12995distribution contains any @file{.cvsignore} files, then 12996the patterns from those files will be processed even if 12997@samp{-I !} is specified. The only workaround is to 12998remove the @file{.cvsignore} files in order to do the 12999import. Because this is awkward, in the future 13000@samp{-I !} might be modified to override 13001@file{.cvsignore} files in each directory. 13002 13003Note that the syntax of the ignore files consists of a 13004series of lines, each of which contains a space 13005separated list of filenames. This offers no clean way 13006to specify filenames which contain spaces, but you can 13007use a workaround like @file{foo?bar} to match a file 13008named @file{foo bar} (it also matches @file{fooxbar} 13009and the like). Also note that there is currently no 13010way to specify comments. 13011@c FIXCVS? I don't _like_ this syntax at all, but 13012@c changing it raises all the usual compatibility 13013@c issues and I'm also not sure what to change it to. 13014 13015@node checkoutlist 13016@appendixsec The checkoutlist file 13017@cindex checkoutlist 13018 13019It may be helpful to use @sc{cvs} to maintain your own 13020files in the @file{CVSROOT} directory. For example, 13021suppose that you have a script @file{logcommit.pl} 13022which you run by including the following line in the 13023@file{commitinfo} administrative file: 13024 13025@example 13026ALL $CVSROOT/CVSROOT/logcommit.pl 13027@end example 13028 13029To maintain @file{logcommit.pl} with @sc{cvs} you would 13030add the following line to the @file{checkoutlist} 13031administrative file: 13032 13033@example 13034logcommit.pl 13035@end example 13036 13037The format of @file{checkoutlist} is one line for each 13038file that you want to maintain using @sc{cvs}, giving 13039the name of the file. 13040 13041After setting up @file{checkoutlist} in this fashion, 13042the files listed there will function just like 13043@sc{cvs}'s built-in administrative files. For example, 13044when checking in one of the files you should get a 13045message such as: 13046 13047@example 13048cvs commit: Rebuilding administrative file database 13049@end example 13050 13051@noindent 13052and the checked out copy in the @file{CVSROOT} 13053directory should be updated. 13054 13055Note that listing @file{passwd} (@pxref{Password 13056authentication server}) in @file{checkoutlist} is not 13057recommended for security reasons. 13058 13059For information about keeping a checkout out copy in a 13060more general context than the one provided by 13061@file{checkoutlist}, see @ref{Keeping a checked out 13062copy}. 13063 13064@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13065@node history file 13066@appendixsec The history file 13067@cindex History file 13068@cindex Log information, saving 13069 13070The file @file{$CVSROOT/CVSROOT/history} is used 13071to log information for the @code{history} command 13072(@pxref{history}). This file must be created to turn 13073on logging. This is done automatically if the 13074@code{cvs init} command is used to set up the 13075repository (@pxref{Creating a repository}). 13076 13077The file format of the @file{history} file is 13078documented only in comments in the @sc{cvs} source 13079code, but generally programs should use the @code{cvs 13080history} command to access it anyway, in case the 13081format changes with future releases of @sc{cvs}. 13082 13083@node Variables 13084@appendixsec Expansions in administrative files 13085@cindex Internal variables 13086@cindex Variables 13087 13088Sometimes in writing an administrative file, you might 13089want the file to be able to know various things based 13090on environment @sc{cvs} is running in. There are 13091several mechanisms to do that. 13092 13093To find the home directory of the user running @sc{cvs} 13094(from the @code{HOME} environment variable), use 13095@samp{~} followed by @samp{/} or the end of the line. 13096Likewise for the home directory of @var{user}, use 13097@samp{~@var{user}}. These variables are expanded on 13098the server machine, and don't get any reasonable 13099expansion if pserver (@pxref{Password authenticated}) 13100is in use; therefore user variables (see below) may be 13101a better choice to customize behavior based on the user 13102running @sc{cvs}. 13103@c Based on these limitations, should we deprecate ~? 13104@c What is it good for? Are people using it? 13105 13106One may want to know about various pieces of 13107information internal to @sc{cvs}. A @sc{cvs} internal 13108variable has the syntax @code{$@{@var{variable}@}}, 13109where @var{variable} starts with a letter and consists 13110of alphanumeric characters and @samp{_}. If the 13111character following @var{variable} is a 13112non-alphanumeric character other than @samp{_}, the 13113@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 13114internal variables are: 13115 13116@table @code 13117@item CVSROOT 13118@cindex CVSROOT, internal variable 13119This is the absolute path to the current @sc{cvs} root directory. 13120@xref{Repository}, for a description of the various 13121ways to specify this, but note that the internal 13122variable contains just the directory and not any 13123of the access method information. 13124 13125@item RCSBIN 13126@cindex RCSBIN, internal variable 13127In @sc{cvs} 1.9.18 and older, this specified the 13128directory where @sc{cvs} was looking for @sc{rcs} 13129programs. Because @sc{cvs} no longer runs @sc{rcs} 13130programs, specifying this internal variable is now an 13131error. 13132 13133@item CVSEDITOR 13134@cindex CVSEDITOR, internal variable 13135@itemx EDITOR 13136@cindex EDITOR, internal variable 13137@itemx VISUAL 13138@cindex VISUAL, internal variable 13139These all expand to the same value, which is the editor 13140that @sc{cvs} is using. @xref{Global options}, for how 13141to specify this. 13142 13143@item USER 13144@cindex USER, internal variable 13145Username of the user running @sc{cvs} (on the @sc{cvs} 13146server machine). 13147When using pserver, this is the user specified in the repository 13148specification which need not be the same as the username the 13149server is running as (@pxref{Password authentication server}). 13150Do not confuse this with the environment variable of the same name. 13151@end table 13152 13153If you want to pass a value to the administrative files 13154which the user who is running @sc{cvs} can specify, 13155use a user variable. 13156@cindex User variables 13157To expand a user variable, the 13158administrative file contains 13159@code{$@{=@var{variable}@}}. To set a user variable, 13160specify the global option @samp{-s} to @sc{cvs}, with 13161argument @code{@var{variable}=@var{value}}. It may be 13162particularly useful to specify this option via 13163@file{.cvsrc} (@pxref{~/.cvsrc}). 13164 13165For example, if you want the administrative file to 13166refer to a test directory you might create a user 13167variable @code{TESTDIR}. Then if @sc{cvs} is invoked 13168as 13169 13170@example 13171cvs -s TESTDIR=/work/local/tests 13172@end example 13173 13174@noindent 13175and the 13176administrative file contains @code{sh 13177$@{=TESTDIR@}/runtests}, then that string is expanded 13178to @code{sh /work/local/tests/runtests}. 13179 13180All other strings containing @samp{$} are reserved; 13181there is no way to quote a @samp{$} character so that 13182@samp{$} represents itself. 13183 13184Environment variables passed to administrative files are: 13185 13186@table @code 13187@cindex environment variables, passed to administrative files 13188 13189@item CVS_USER 13190@cindex CVS_USER, environment variable 13191The @sc{cvs}-specific username provided by the user, if it 13192can be provided (currently just for the pserver access 13193method), and to the empty string otherwise. (@code{CVS_USER} 13194and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 13195is used to map @sc{cvs} usernames to system usernames.) 13196 13197@item LOGNAME 13198@cindex LOGNAME, environment variable 13199The username of the system user. 13200 13201@item USER 13202@cindex USER, environment variable 13203Same as @code{LOGNAME}. 13204Do not confuse this with the internal variable of the same name. 13205@end table 13206 13207@node config 13208@appendixsec The CVSROOT/config configuration file 13209 13210@cindex config, in CVSROOT 13211@cindex CVSROOT/config 13212 13213The administrative file @file{config} contains various 13214miscellaneous settings which affect the behavior of 13215@sc{cvs}. The syntax is slightly different from the 13216other administrative files. Variables are not 13217expanded. Lines which start with @samp{#} are 13218considered comments. 13219@c FIXME: where do we define comments for the other 13220@c administrative files. 13221Other lines consist of a keyword, @samp{=}, and a 13222value. Note that this syntax is very strict. 13223Extraneous spaces or tabs are not permitted. 13224@c See comments in parseinfo.c:parse_config for more 13225@c discussion of this strictness. 13226 13227Currently defined keywords are: 13228 13229@table @code 13230@cindex RCSBIN, in CVSROOT/config 13231@item RCSBIN=@var{bindir} 13232For @sc{cvs} 1.9.12 through 1.9.18, this setting told 13233@sc{cvs} to look for @sc{rcs} programs in the 13234@var{bindir} directory. Current versions of @sc{cvs} 13235do not run @sc{rcs} programs; for compatibility this 13236setting is accepted, but it does nothing. 13237 13238@cindex SystemAuth, in CVSROOT/config 13239@item SystemAuth=@var{value} 13240If @var{value} is @samp{yes}, then pserver should check 13241for users in the system's user database if not found in 13242@file{CVSROOT/passwd}. If it is @samp{no}, then all 13243pserver users must exist in @file{CVSROOT/passwd}. 13244The default is @samp{yes}. For more on pserver, see 13245@ref{Password authenticated}. 13246 13247 13248@cindex TopLevelAdmin, in CVSROOT/config 13249@item TopLevelAdmin=@var{value} 13250Modify the @samp{checkout} command to create a 13251@samp{CVS} directory at the top level of the new 13252working directory, in addition to @samp{CVS} 13253directories created within checked-out directories. 13254The default value is @samp{no}. 13255 13256This option is useful if you find yourself performing 13257many commands at the top level of your working 13258directory, rather than in one of the checked out 13259subdirectories. The @file{CVS} directory created there 13260will mean you don't have to specify @code{CVSROOT} for 13261each command. It also provides a place for the 13262@file{CVS/Template} file (@pxref{Working directory 13263storage}). 13264 13265@cindex LockDir, in CVSROOT/config 13266@item LockDir=@var{directory} 13267Put @sc{cvs} lock files in @var{directory} rather than 13268directly in the repository. This is useful if you want 13269to let users read from the repository while giving them 13270write access only to @var{directory}, not to the 13271repository. 13272It can also be used to put the locks on a very fast 13273in-memory file system to speed up locking and unlocking 13274the repository. 13275You need to create @var{directory}, but 13276@sc{cvs} will create subdirectories of @var{directory} as it 13277needs them. For information on @sc{cvs} locks, see 13278@ref{Concurrency}. 13279 13280@c Mention this in Compatibility section? 13281Before enabling the LockDir option, make sure that you 13282have tracked down and removed any copies of @sc{cvs} 1.9 or 13283older. Such versions neither support LockDir, nor will 13284give an error indicating that they don't support it. 13285The result, if this is allowed to happen, is that some 13286@sc{cvs} users will put the locks one place, and others will 13287put them another place, and therefore the repository 13288could become corrupted. @sc{cvs} 1.10 does not support 13289LockDir but it will print a warning if run on a 13290repository with LockDir enabled. 13291 13292@cindex LogHistory, in CVSROOT/config 13293@item LogHistory=@var{value} 13294Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). 13295Default of @samp{TOEFWUCGMAR} (or simply @samp{all}) will log 13296all transactions. Any subset of the default is 13297legal. (For example, to only log transactions that modify the 13298@file{*,v} files, use @samp{LogHistory=TMAR}.) 13299 13300@cindex RereadLogAfterVerify, in CVSROOT/config 13301@cindex @file{verifymsg}, changing the log message 13302@item RereadLogAfterVerify=@var{value} 13303Modify the @samp{commit} command such that CVS will reread the 13304log message after running the program specified by @file{verifymsg}. 13305@var{value} may be one of @samp{yes} or @samp{always}, indicating that 13306the log message should always be reread; @samp{no} 13307or @samp{never}, indicating that it should never be 13308reread; or @var{value} may be @samp{stat}, indicating 13309that the file should be checked with the filesystem 13310@samp{stat()} function to see if it has changed (see warning below) 13311before rereading. The default value is @samp{always}. 13312 13313@strong{Note: the `stat' mode can cause CVS to pause for up to 13314one extra second per directory committed. This can be less IO and 13315CPU intensive but is not recommended for use with large repositories} 13316 13317@xref{verifymsg}, for more information on how verifymsg 13318may be used. 13319 13320@cindex UserAdminOptions, in CVSROOT/config 13321@item UserAdminOptions=@var{value} 13322Control what options will be allowed with the @code{cvs admin} 13323command (@pxref{admin}) for users not in the @code{cvsadmin} group. 13324The @var{value} string is a list of single character options 13325which should be allowed. If a user who is not a member of the 13326@code{cvsadmin} group tries to execute any @code{cvs admin} 13327option which is not listed they will will receive an error message 13328reporting that the option is restricted. 13329 13330If no @code{cvsadmin} group exists on the server, @sc{cvs} will 13331ignore the @code{UserAdminOptions} keyword (@pxref{admin}). 13332 13333When not specified, @code{UserAdminOptions} defaults to 13334@samp{k}. In other words, it defaults to allowing 13335users outside of the @code{cvsadmin} group to use the 13336@code{cvs admin} command only to change the default keyword 13337expansion mode for files. 13338 13339As an example, to restrict users not in the @code{cvsadmin} 13340group to using @code{cvs admin} to change the default keyword 13341substitution mode, lock revisions, unlock revisions, and 13342replace the log message, use @samp{UserAdminOptions=klum}. 13343@end table 13344 13345@c --------------------------------------------------------------------- 13346@node Environment variables 13347@appendix All environment variables which affect CVS 13348@cindex Environment variables 13349@cindex Reference manual for variables 13350 13351This is a complete list of all environment variables 13352that affect @sc{cvs}. 13353 13354@table @code 13355@cindex CVSIGNORE, environment variable 13356@item $CVSIGNORE 13357A whitespace-separated list of file name patterns that 13358@sc{cvs} should ignore. @xref{cvsignore}. 13359 13360@cindex CVSWRAPPERS, environment variable 13361@item $CVSWRAPPERS 13362A whitespace-separated list of file name patterns that 13363@sc{cvs} should treat as wrappers. @xref{Wrappers}. 13364 13365@cindex CVSREAD, environment variable 13366@cindex Read-only files, and CVSREAD 13367@item $CVSREAD 13368If this is set, @code{checkout} and @code{update} will 13369try hard to make the files in your working directory 13370read-only. When this is not set, the default behavior 13371is to permit modification of your working files. 13372 13373@cindex CVSREADONLYFS, environment variable 13374@item $CVSREADONLYFS 13375Turns on read-only repository mode. This allows one to 13376check out from a read-only repository, such as within 13377an anoncvs server, or from a CDROM repository. 13378 13379It has the same effect as if the @samp{-R} command-line 13380option is used. This can also allow the use of 13381read-only NFS repositories. 13382 13383@item $CVSUMASK 13384Controls permissions of files in the repository. See 13385@ref{File permissions}. 13386 13387@item $CVSROOT 13388Should contain the full pathname to the root of the @sc{cvs} 13389source repository (where the @sc{rcs} files are 13390kept). This information must be available to @sc{cvs} for 13391most commands to execute; if @code{$CVSROOT} is not set, 13392or if you wish to override it for one invocation, you 13393can supply it on the command line: @samp{cvs -d cvsroot 13394cvs_command@dots{}} Once you have checked out a working 13395directory, @sc{cvs} stores the appropriate root (in 13396the file @file{CVS/Root}), so normally you only need to 13397worry about this when initially checking out a working 13398directory. 13399 13400@item $CVSEDITOR 13401@cindex CVSEDITOR, environment variable 13402@itemx $EDITOR 13403@cindex EDITOR, environment variable 13404@itemx $VISUAL 13405@cindex VISUAL, environment variable 13406Specifies the program to use for recording log messages 13407during commit. @code{$CVSEDITOR} overrides 13408@code{$EDITOR}, which overrides @code{$VISUAL}. 13409See @ref{Committing your changes} for more or 13410@ref{Global options} for alternative ways of specifying a 13411log editor. 13412 13413@cindex PATH, environment variable 13414@item $PATH 13415If @code{$RCSBIN} is not set, and no path is compiled 13416into @sc{cvs}, it will use @code{$PATH} to try to find all 13417programs it uses. 13418 13419@cindex HOME, environment variable 13420@item $HOME 13421@cindex HOMEPATH, environment variable 13422@item $HOMEPATH 13423@cindex HOMEDRIVE, environment variable 13424@item $HOMEDRIVE 13425Used to locate the directory where the @file{.cvsrc} 13426file, and other such files, are searched. On Unix, @sc{cvs} 13427just checks for @code{HOME}. On Windows NT, the system will 13428set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 13429for example to @file{\joe}. On Windows 95, you'll 13430probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 13431@c We are being vague about whether HOME works on 13432@c Windows; see long comment in windows-NT/filesubr.c. 13433 13434@cindex CVS_RSH, environment variable 13435@item $CVS_RSH 13436Specifies the external program which @sc{cvs} connects with, 13437when @code{:ext:} access method is specified. 13438@pxref{Connecting via rsh}. 13439 13440@item $CVS_SERVER 13441Used in client-server mode when accessing a remote 13442repository using @sc{rsh}. It specifies the name of 13443the program to start on the server side (and any 13444necessary arguments) when accessing a remote repository 13445using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 13446The default value for @code{:ext:} and @code{:server:} is @code{cvs}; 13447the default value for @code{:fork:} is the name used to run the client. 13448@pxref{Connecting via rsh} 13449 13450@item $CVS_PASSFILE 13451Used in client-server mode when accessing the @code{cvs 13452login server}. Default value is @file{$HOME/.cvspass}. 13453@pxref{Password authentication client} 13454 13455@item $CVS_CLIENT_PORT 13456Used in client-server mode to set the port to use when accessing the server 13457via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 13458if the port is not specified in the CVSROOT. 13459@pxref{Remote repositories} 13460 13461@cindex CVS_RCMD_PORT, environment variable 13462@item $CVS_RCMD_PORT 13463Used in client-server mode. If set, specifies the port 13464number to be used when accessing the @sc{rcmd} demon on 13465the server side. (Currently not used for Unix clients). 13466 13467@cindex CVS_CLIENT_LOG, environment variable 13468@item $CVS_CLIENT_LOG 13469Used for debugging only in client-server 13470mode. If set, everything sent to the server is logged 13471into @file{@code{$CVS_CLIENT_LOG}.in} and everything 13472sent from the server is logged into 13473@file{@code{$CVS_CLIENT_LOG}.out}. 13474 13475@cindex CVS_SERVER_SLEEP, environment variable 13476@item $CVS_SERVER_SLEEP 13477Used only for debugging the server side in 13478client-server mode. If set, delays the start of the 13479server child process the specified amount of 13480seconds so that you can attach to it with a debugger. 13481 13482@cindex CVS_IGNORE_REMOTE_ROOT, environment variable 13483@item $CVS_IGNORE_REMOTE_ROOT 13484For @sc{cvs} 1.10 and older, setting this variable 13485prevents @sc{cvs} from overwriting the @file{CVS/Root} 13486file when the @samp{-d} global option is specified. 13487Later versions of @sc{cvs} do not rewrite 13488@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 13489effect. 13490 13491@cindex CVS_LOCAL_BRANCH_NUM, environment variable 13492@item $CVS_LOCAL_BRANCH_NUM 13493Setting this variable allows some control over the 13494branch number that is assigned. This is specifically to 13495support the local commit feature of CVSup. If one sets 13496@code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches 13497the local repository, the revision numbers will look 13498like 1.66.1000.xx. There is almost a dead-set certainty 13499that there will be no conflicts with version numbers. 13500 13501@cindex COMSPEC, environment variable 13502@item $COMSPEC 13503Used under OS/2 only. It specifies the name of the 13504command interpreter and defaults to @sc{cmd.exe}. 13505 13506@cindex TMPDIR, environment variable 13507@item $TMPDIR 13508@cindex TMP, environment variable 13509@itemx $TMP 13510@cindex TEMP, environment variable 13511@itemx $TEMP 13512@cindex Temporary files, location of 13513@c This is quite nuts. We don't talk about tempnam 13514@c or mkstemp which we sometimes use. The discussion 13515@c of "Global options" is semi-incoherent. 13516@c I'm not even sure those are the only inaccuracies. 13517@c Furthermore, the conventions are 13518@c pretty crazy and they should be simplified. 13519Directory in which temporary files are located. 13520The @sc{cvs} server uses 13521@code{TMPDIR}. @xref{Global options}, for a 13522description of how to specify this. 13523Some parts of @sc{cvs} will always use @file{/tmp} (via 13524the @code{tmpnam} function provided by the system). 13525 13526On Windows NT, @code{TMP} is used (via the @code{_tempnam} 13527function provided by the system). 13528 13529The @code{patch} program which is used by the @sc{cvs} 13530client uses @code{TMPDIR}, and if it is not set, uses 13531@file{/tmp} (at least with GNU patch 2.1). Note that 13532if your server and client are both running @sc{cvs} 135331.9.10 or later, @sc{cvs} will not invoke an external 13534@code{patch} program. 13535 13536@cindex CVS_PID, environment variable 13537@item $CVS_PID 13538This is the process identification (aka pid) number of 13539the @sc{cvs} process. It is often useful in the 13540programs and/or scripts specified by the 13541@file{commitinfo}, @file{verifymsg}, @file{loginfo} 13542files. 13543@end table 13544 13545@node Compatibility 13546@appendix Compatibility between CVS Versions 13547 13548@cindex CVS, versions of 13549@cindex Versions, of CVS 13550@cindex Compatibility, between CVS versions 13551@c We don't mention versions older than CVS 1.3 13552@c on the theory that it would clutter it up for the vast 13553@c majority of people, who don't have anything that old. 13554@c 13555The repository format is compatible going back to 13556@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 13557you have copies of @sc{cvs} 1.6 or older and you want 13558to use the optional developer communication features. 13559@c If you "cvs rm" and commit using 1.3, then you'll 13560@c want to run "rcs -sdead <file,v>" on each of the 13561@c files in the Attic if you then want 1.5 and 13562@c later to recognize those files as dead (I think the 13563@c symptom if this is not done is that files reappear 13564@c in joins). (Wait: the above will work but really to 13565@c be strictly correct we should suggest checking 13566@c in a new revision rather than just changing the 13567@c state of the head revision, shouldn't we?). 13568@c The old convert.sh script was for this, but it never 13569@c did get updated to reflect use of the RCS "dead" 13570@c state. 13571@c Note: this is tricky to document without confusing 13572@c people--need to carefully say what CVS version we 13573@c are talking about and keep in mind the distinction 13574@c between a 13575@c repository created with 1.3 and on which one now 13576@c uses 1.5+, and a repository on which one wants to 13577@c use both versions side by side (e.g. during a 13578@c transition period). 13579@c Wait, can't CVS just detect the case in which a file 13580@c is in the Attic but the head revision is not dead? 13581@c Not sure whether this should produce a warning or 13582@c something, and probably needs further thought, but 13583@c it would appear that the situation can be detected. 13584@c 13585@c We might want to separate out the 1.3 compatibility 13586@c section (for repository & working directory) from the 13587@c rest--that might help avoid confusing people who 13588@c are upgrading (for example) from 1.6 to 1.8. 13589@c 13590@c A minor incompatibility is if a current version of CVS 13591@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 13592@c see this as if there is no tag. Seems to me this is 13593@c too obscure to mention. 13594 13595The working directory format is compatible going back 13596to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 13597and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 13598a working directory checked out with @sc{cvs} 1.3, 13599@sc{cvs} will convert it, but to go back to @sc{cvs} 136001.3 you need to check out a new working directory with 13601@sc{cvs} 1.3. 13602 13603The remote protocol is interoperable going back to @sc{cvs} 1.5, but no 13604further (1.5 was the first official release with the remote protocol, 13605but some older versions might still be floating around). In many 13606cases you need to upgrade both the client and the server to take 13607advantage of new features and bugfixes, however. 13608 13609@c Perhaps should be saying something here about the 13610@c "D" lines in Entries (written by CVS 1.9; 1.8 and 13611@c older don't use them). These are supposed to be 13612@c compatible in both directions, but I'm not sure 13613@c they quite are 100%. One common gripe is if you 13614@c "rm -r" a directory and 1.9 gets confused, as it 13615@c still sees it in Entries. That one is fixed in 13616@c (say) 1.9.6. Someone else reported problems with 13617@c starting with a directory which was checked out with 13618@c an old version, and then using a new version, and 13619@c some "D" lines appeared, but not for every 13620@c directory, causing some directories to be skipped. 13621@c They weren't sure how to reproduce this, though. 13622 13623@c --------------------------------------------------------------------- 13624@node Troubleshooting 13625@appendix Troubleshooting 13626 13627If you are having trouble with @sc{cvs}, this appendix 13628may help. If there is a particular error message which 13629you are seeing, then you can look up the message 13630alphabetically. If not, you can look through the 13631section on other problems to see if your problem is 13632mentioned there. 13633 13634@menu 13635* Error messages:: Partial list of CVS errors 13636* Connection:: Trouble making a connection to a CVS server 13637* Other problems:: Problems not readily listed by error message 13638@end menu 13639 13640 13641@node Error messages 13642@appendixsec Partial list of error messages 13643 13644Here is a partial list of error messages that you may 13645see from @sc{cvs}. It is not a complete list---@sc{cvs} 13646is capable of printing many, many error messages, often 13647with parts of them supplied by the operating system, 13648but the intention is to list the common and/or 13649potentially confusing error messages. 13650 13651The messages are alphabetical, but introductory text 13652such as @samp{cvs update: } is not considered in 13653ordering them. 13654 13655In some cases the list includes messages printed by old 13656versions of @sc{cvs} (partly because users may not be 13657sure which version of @sc{cvs} they are using at any 13658particular moment). 13659@c If we want to start retiring messages, perhaps we 13660@c should pick a cutoff version (for example, no more 13661@c messages which are specific to versions before 1.9) 13662@c and then move the old messages to an "old messages" 13663@c node rather than deleting them completely. 13664 13665@table @code 13666@c FIXME: What is the correct way to format a multiline 13667@c error message here? Maybe @table is the wrong 13668@c choice? Texinfo gurus? 13669@item @var{file}:@var{line}: Assertion '@var{text}' failed 13670The exact format of this message may vary depending on 13671your system. It indicates a bug in @sc{cvs}, which can 13672be handled as described in @ref{BUGS}. 13673 13674@item cvs @var{command}: authorization failed: server @var{host} rejected access 13675This is a generic response when trying to connect to a 13676pserver server which chooses not to provide a 13677specific reason for denying authorization. Check that 13678the username and password specified are correct and 13679that the @code{CVSROOT} specified is allowed by @samp{--allow-root} 13680in @file{inetd.conf}. See @ref{Password authenticated}. 13681 13682@item cvs @var{command}: conflict: removed @var{file} was modified by second party 13683This message indicates that you removed a file, and 13684someone else modified it. To resolve the conflict, 13685first run @samp{cvs add @var{file}}. If desired, look 13686at the other party's modification to decide whether you 13687still want to remove it. If you don't want to remove 13688it, stop here. If you do want to remove it, proceed 13689with @samp{cvs remove @var{file}} and commit your 13690removal. 13691@c Tests conflicts2-142b* in sanity.sh test for this. 13692 13693@item cannot change permissions on temporary directory 13694@example 13695Operation not permitted 13696@end example 13697This message has been happening in a non-reproducible, 13698occasional way when we run the client/server testsuite, 13699both on Red Hat Linux 3.0.3 and 4.1. We haven't been 13700able to figure out what causes it, nor is it known 13701whether it is specific to linux (or even to this 13702particular machine!). If the problem does occur on 13703other unices, @samp{Operation not permitted} would be 13704likely to read @samp{Not owner} or whatever the system 13705in question uses for the unix @code{EPERM} error. If 13706you have any information to add, please let us know as 13707described in @ref{BUGS}. If you experience this error 13708while using @sc{cvs}, retrying the operation which 13709produced it should work fine. 13710@c This has been seen in a variety of tests, including 13711@c multibranch-2, multibranch-5, and basic1-24-rm-rm, 13712@c so it doesn't seem particularly specific to any one 13713@c test. 13714 13715@item cvs [server aborted]: Cannot check out files into the repository itself 13716The obvious cause for this message (especially for 13717non-client/server @sc{cvs}) is that the @sc{cvs} root 13718is, for example, @file{/usr/local/cvsroot} and you try 13719to check out files when you are in a subdirectory, such 13720as @file{/usr/local/cvsroot/test}. However, there is a 13721more subtle cause, which is that the temporary 13722directory on the server is set to a subdirectory of the 13723root (which is also not allowed). If this is the 13724problem, set the temporary directory to somewhere else, 13725for example @file{/var/tmp}; see @code{TMPDIR} in 13726@ref{Environment variables}, for how to set the 13727temporary directory. 13728 13729@item cannot commit files as 'root' 13730See @samp{'root' is not allowed to commit files}. 13731 13732@c For one example see basica-1a10 in the testsuite 13733@c For another example, "cvs co ." on NT; see comment 13734@c at windows-NT/filesubr.c (expand_wild). 13735@c For another example, "cvs co foo/bar" where foo exists. 13736@item cannot open CVS/Entries for reading: No such file or directory 13737This generally indicates a @sc{cvs} internal error, and 13738can be handled as with other @sc{cvs} bugs 13739(@pxref{BUGS}). Usually there is a workaround---the 13740exact nature of which would depend on the situation but 13741which hopefully could be figured out. 13742 13743@c This is more obscure than it might sound; it only 13744@c happens if you run "cvs init" from a directory which 13745@c contains a CVS/Root file at the start. 13746@item cvs [init aborted]: cannot open CVS/Root: No such file or directory 13747This message is harmless. Provided it is not 13748accompanied by other errors, the operation has 13749completed successfully. This message should not occur 13750with current versions of @sc{cvs}, but it is documented 13751here for the benefit of @sc{cvs} 1.9 and older. 13752 13753@item cvs server: cannot open /root/.cvsignore: Permission denied 13754@itemx cvs [server aborted]: can't chdir(/root): Permission denied 13755See @ref{Connection}. 13756 13757@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 13758This message has been reported as intermittently 13759happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 13760unknown; if you know more about what causes it, let us 13761know as described in @ref{BUGS}. 13762 13763@item cvs [@var{command} aborted]: cannot start server via rcmd 13764This, unfortunately, is a rather nonspecific error 13765message which @sc{cvs} 1.9 will print if you are 13766running the @sc{cvs} client and it is having trouble 13767connecting to the server. Current versions of @sc{cvs} 13768should print a much more specific error message. If 13769you get this message when you didn't mean to run the 13770client at all, you probably forgot to specify 13771@code{:local:}, as described in @ref{Repository}. 13772 13773@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 13774@sc{cvs} 1.9 and older will print this message 13775when trying to check in a binary file if 13776@sc{rcs} is not correctly installed. Re-read the 13777instructions that came with your @sc{rcs} distribution 13778and the @sc{install} file in the @sc{cvs} 13779distribution. Alternately, upgrade to a current 13780version of @sc{cvs}, which checks in files itself 13781rather than via @sc{rcs}. 13782 13783@item cvs checkout: could not check out @var{file} 13784With @sc{cvs} 1.9, this can mean that the @code{co} program 13785(part of @sc{rcs}) returned a failure. It should be 13786preceded by another error message, however it has been 13787observed without another error message and the cause is 13788not well-understood. With the current version of @sc{cvs}, 13789which does not run @code{co}, if this message occurs 13790without another error message, it is definitely a @sc{cvs} 13791bug (@pxref{BUGS}). 13792@c My current suspicion is that the RCS in the rcs (not 13793@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 13794@c CD is bad (remains to be confirmed). 13795@c There is also a report of something which looks 13796@c very similar on SGI, Irix 5.2, so I dunno. 13797 13798@item cvs [login aborted]: could not find out home directory 13799This means that you need to set the environment 13800variables that @sc{cvs} uses to locate your home directory. 13801See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 13802@ref{Environment variables}. 13803 13804@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 13805@sc{cvs} 1.9 and older will print this message if there was 13806a problem finding the @code{rcsmerge} program. Make 13807sure that it is in your @code{PATH}, or upgrade to a 13808current version of @sc{cvs}, which does not require 13809an external @code{rcsmerge} program. 13810 13811@item cvs [update aborted]: could not patch @var{file}: No such file or directory 13812This means that there was a problem finding the 13813@code{patch} program. Make sure that it is in your 13814@code{PATH}. Note that despite appearances the message 13815is @emph{not} referring to whether it can find @var{file}. 13816If both the client and the server are running a current 13817version of @sc{cvs}, then there is no need for an 13818external patch program and you should not see this 13819message. But if either client or server is running 13820@sc{cvs} 1.9, then you need @code{patch}. 13821 13822@item cvs update: could not patch @var{file}; will refetch 13823This means that for whatever reason the client was 13824unable to apply a patch that the server sent. The 13825message is nothing to be concerned about, because 13826inability to apply the patch only slows things down and 13827has no effect on what @sc{cvs} does. 13828@c xref to update output. Or File status? 13829@c Or some place else that 13830@c explains this whole "patch"/P/Needs Patch thing? 13831 13832@item dying gasps from @var{server} unexpected 13833There is a known bug in the server for @sc{cvs} 1.9.18 13834and older which can cause this. For me, this was 13835reproducible if I used the @samp{-t} global option. It 13836was fixed by Andy Piper's 14 Nov 1997 change to 13837src/filesubr.c, if anyone is curious. 13838If you see the message, 13839you probably can just retry the operation which failed, 13840or if you have discovered information concerning its 13841cause, please let us know as described in @ref{BUGS}. 13842 13843@item end of file from server (consult above messages if any) 13844The most common cause for this message is if you are 13845using an external @code{rsh} program and it exited with 13846an error. In this case the @code{rsh} program should 13847have printed a message, which will appear before the 13848above message. For more information on setting up a 13849@sc{cvs} client and server, see @ref{Remote repositories}. 13850 13851@item cvs [update aborted]: EOF in key in RCS file @var{file},v 13852@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 13853This means that there is a syntax error in the given 13854@sc{rcs} file. Note that this might be true even if @sc{rcs} can 13855read the file OK; @sc{cvs} does more error checking of 13856errors in the RCS file. That is why you may see this 13857message when upgrading from @sc{cvs} 1.9 to @sc{cvs} 138581.10. The likely cause for the original corruption is 13859hardware, the operating system, or the like. Of 13860course, if you find a case in which @sc{cvs} seems to 13861corrupting the file, by all means report it, 13862(@pxref{BUGS}). 13863There are quite a few variations of this error message, 13864depending on exactly where in the @sc{rcs} file @sc{cvs} 13865finds the syntax error. 13866 13867@cindex mkmodules 13868@item cvs commit: Executing 'mkmodules' 13869This means that your repository is set up for a version 13870of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 138711.8 or later, the above message will be preceded by 13872 13873@example 13874cvs commit: Rebuilding administrative file database 13875@end example 13876 13877If you see both messages, the database is being rebuilt 13878twice, which is unnecessary but harmless. If you wish 13879to avoid the duplication, and you have no versions of 13880@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 13881every place it appears in your @code{modules} 13882file. For more information on the @code{modules} file, 13883see @ref{modules}. 13884 13885@c This message comes from "co", and I believe is 13886@c possible only with older versions of CVS which call 13887@c co. The problem with being able to create the bogus 13888@c RCS file still exists, though (and I think maybe 13889@c there is a different symptom(s) now). 13890@c FIXME: Would be nice to have a more exact wording 13891@c for this message. 13892@item missing author 13893Typically this can happen if you created an RCS file 13894with your username set to empty. @sc{cvs} will, bogusly, 13895create an illegal RCS file with no value for the author 13896field. The solution is to make sure your username is 13897set to a non-empty value and re-create the RCS file. 13898@c "make sure your username is set" is complicated in 13899@c and of itself, as there are the environment 13900@c variables the system login name, &c, and it depends 13901@c on the version of CVS. 13902 13903@item cvs [checkout aborted]: no such tag @var{tag} 13904This message means that @sc{cvs} isn't familiar with 13905the tag @var{tag}. Usually this means that you have 13906mistyped a tag name; however there are (relatively 13907obscure) cases in which @sc{cvs} will require you to 13908@c Search sanity.sh for "no such tag" to see some of 13909@c the relatively obscure cases. 13910try a few other @sc{cvs} commands involving that tag, 13911before you find one which will cause @sc{cvs} to update 13912the @file{val-tags} file; see discussion of val-tags in 13913@ref{File permissions}. You only need to worry about 13914this once for a given tag; when a tag is listed in 13915@file{val-tags}, it stays there. Note that using 13916@samp{-f} to not require tag matches does not override 13917this check; see @ref{Common options}. 13918 13919@item *PANIC* administration files missing 13920This typically means that there is a directory named 13921@sc{cvs} but it does not contain the administrative files 13922which @sc{cvs} puts in a CVS directory. If the problem is 13923that you created a CVS directory via some mechanism 13924other than @sc{cvs}, then the answer is simple, use a name 13925other than @sc{cvs}. If not, it indicates a @sc{cvs} bug 13926(@pxref{BUGS}). 13927 13928@item rcs error: Unknown option: -x,v/ 13929This message will be followed by a usage message for 13930@sc{rcs}. It means that you have an old version of 13931@sc{rcs} (probably supplied with your operating 13932system), as well as an old version of @sc{cvs}. 13933@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 13934later; current versions of @sc{cvs} do not run @sc{rcs} programs. 13935@c For more information on installing @sc{cvs}, see 13936@c (FIXME: where? it depends on whether you are 13937@c getting binaries or sources or what). 13938@c The message can also say "ci error" or something 13939@c instead of "rcs error", I suspect. 13940 13941@item cvs [server aborted]: received broken pipe signal 13942This message seems to be caused by a hard-to-track-down 13943bug in @sc{cvs} or the systems it runs on (we don't 13944know---we haven't tracked it down yet!). It seems to 13945happen only after a @sc{cvs} command has completed, and 13946you should be able to just ignore the message. 13947However, if you have discovered information concerning its 13948cause, please let us know as described in @ref{BUGS}. 13949 13950@item 'root' is not allowed to commit files 13951When committing a permanent change, @sc{cvs} makes a log entry of 13952who committed the change. If you are committing the change logged 13953in as "root" (not under "su" or other root-priv giving program), 13954@sc{cvs} cannot determine who is actually making the change. 13955As such, by default, @sc{cvs} disallows changes to be committed by users 13956logged in as "root". (You can disable this option by passing the 13957@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 13958On some systems this means editing the appropriate @file{config.h} file 13959before building @sc{cvs}.) 13960 13961@item Too many arguments! 13962This message is typically printed by the @file{log.pl} 13963script which is in the @file{contrib} directory in the 13964@sc{cvs} source distribution. In some versions of 13965@sc{cvs}, @file{log.pl} has been part of the default 13966@sc{cvs} installation. The @file{log.pl} script gets 13967called from the @file{loginfo} administrative file. 13968Check that the arguments passed in @file{loginfo} match 13969what your version of @file{log.pl} expects. In 13970particular, the @file{log.pl} from @sc{cvs} 1.3 and 13971older expects the logfile as an argument whereas the 13972@file{log.pl} from @sc{cvs} 1.5 and newer expects the 13973logfile to be specified with a @samp{-f} option. Of 13974course, if you don't need @file{log.pl} you can just 13975comment it out of @file{loginfo}. 13976 13977@item cvs [update aborted]: unexpected EOF reading @var{file},v 13978See @samp{EOF in key in RCS file}. 13979 13980@item cvs [login aborted]: unrecognized auth response from @var{server} 13981This message typically means that the server is not set 13982up properly. For example, if @file{inetd.conf} points 13983to a nonexistent cvs executable. To debug it further, 13984find the log file which inetd writes 13985(@file{/var/log/messages} or whatever inetd uses on 13986your system). For details, see @ref{Connection}, and 13987@ref{Password authentication server}. 13988 13989@item cvs commit: Up-to-date check failed for `@var{file}' 13990This means that someone else has committed a change to 13991that file since the last time that you did a @code{cvs 13992update}. So before proceeding with your @code{cvs 13993commit} you need to @code{cvs update}. @sc{cvs} will merge 13994the changes that you made and the changes that the 13995other person made. If it does not detect any conflicts 13996it will report @samp{M @var{file}} and you are ready 13997to @code{cvs commit}. If it detects conflicts it will 13998print a message saying so, will report @samp{C @var{file}}, 13999and you need to manually resolve the 14000conflict. For more details on this process see 14001@ref{Conflicts example}. 14002 14003@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 14004@example 14005Only one of [exEX3] allowed 14006@end example 14007This indicates a problem with the installation of 14008@code{diff3} and @code{rcsmerge}. Specifically 14009@code{rcsmerge} was compiled to look for GNU diff3, but 14010it is finding unix diff3 instead. The exact text of 14011the message will vary depending on the system. The 14012simplest solution is to upgrade to a current version of 14013@sc{cvs}, which does not rely on external 14014@code{rcsmerge} or @code{diff3} programs. 14015 14016@item warning: unrecognized response `@var{text}' from cvs server 14017If @var{text} contains a valid response (such as 14018@samp{ok}) followed by an extra carriage return 14019character (on many systems this will cause the second 14020part of the message to overwrite the first part), then 14021it probably means that you are using the @samp{:ext:} 14022access method with a version of rsh, such as most 14023non-unix rsh versions, which does not by default 14024provide a transparent data stream. In such cases you 14025probably want to try @samp{:server:} instead of 14026@samp{:ext:}. If @var{text} is something else, this 14027may signify a problem with your @sc{cvs} server. 14028Double-check your installation against the instructions 14029for setting up the @sc{cvs} server. 14030@c FIXCVS: should be printing CR as \r or \015 or some 14031@c such, probably. 14032 14033@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 14034This is a normal message, not an error. See 14035@ref{Concurrency}, for more details. 14036 14037@item cvs commit: warning: editor session failed 14038@cindex Exit status, of editor 14039This means that the editor which @sc{cvs} is using exits with a nonzero 14040exit status. Some versions of vi will do this even when there was not 14041a problem editing the file. If so, point the 14042@code{CVSEDITOR} environment variable to a small script 14043such as: 14044 14045@example 14046#!/bin/sh 14047vi $* 14048exit 0 14049@end example 14050 14051@c "warning: foo was lost" and "no longer pertinent" (both normal). 14052@c Would be nice to write these up--they are 14053@c potentially confusing for the new user. 14054@end table 14055 14056@node Connection 14057@appendixsec Trouble making a connection to a CVS server 14058 14059This section concerns what to do if you are having 14060trouble making a connection to a @sc{cvs} server. If 14061you are running the @sc{cvs} command line client 14062running on Windows, first upgrade the client to 14063@sc{cvs} 1.9.12 or later. The error reporting in 14064earlier versions provided much less information about 14065what the problem was. If the client is non-Windows, 14066@sc{cvs} 1.9 should be fine. 14067 14068If the error messages are not sufficient to track down 14069the problem, the next steps depend largely on which 14070access method you are using. 14071 14072@table @code 14073@cindex :ext:, troubleshooting 14074@item :ext: 14075Try running the rsh program from the command line. For 14076example: "rsh servername cvs -v" should print @sc{cvs} 14077version information. If this doesn't work, you need to 14078fix it before you can worry about @sc{cvs} problems. 14079 14080@cindex :server:, troubleshooting 14081@item :server: 14082You don't need a command line rsh program to use this 14083access method, but if you have an rsh program around, 14084it may be useful as a debugging tool. Follow the 14085directions given for :ext:. 14086 14087@cindex :pserver:, troubleshooting 14088@item :pserver: 14089Errors along the lines of "connection refused" typically indicate 14090that inetd isn't even listening for connections on port 2401 14091whereas errors like "connection reset by peer", 14092"received broken pipe signal", "recv() from server: EOF", 14093or "end of file from server" 14094typically indicate that inetd is listening for 14095connections but is unable to start @sc{cvs} (this is frequently 14096caused by having an incorrect path in @file{inetd.conf} 14097or by firewall software rejecting the connection). 14098"unrecognized auth response" errors are caused by a bad command 14099line in @file{inetd.conf}, typically an invalid option or forgetting 14100to put the @samp{pserver} command at the end of the line. 14101Another less common problem is invisible control characters that 14102your editor "helpfully" added without you noticing. 14103 14104One good debugging tool is to "telnet servername 141052401". After connecting, send any text (for example 14106"foo" followed by return). If @sc{cvs} is working 14107correctly, it will respond with 14108 14109@example 14110cvs [pserver aborted]: bad auth protocol start: foo 14111@end example 14112 14113If instead you get: 14114 14115@example 14116Usage: cvs [cvs-options] command [command-options-and-arguments] 14117... 14118@end example 14119 14120@noindent 14121then you're missing the @samp{pserver} command at the end of the 14122line in @file{inetd.conf}; check to make sure that the entire command 14123is on one line and that it's complete. 14124 14125Likewise, if you get something like: 14126 14127@example 14128Unknown command: `pserved' 14129 14130CVS commands are: 14131 add Add a new file/directory to the repository 14132... 14133@end example 14134 14135@noindent 14136then you've misspelled @samp{pserver} in some way. If it isn't 14137obvious, check for invisible control characters (particularly 14138carriage returns) in @file{inetd.conf}. 14139 14140If it fails to work at all, then make sure inetd is working 14141right. Change the invocation in @file{inetd.conf} to run the 14142echo program instead of cvs. For example: 14143 14144@example 141452401 stream tcp nowait root /bin/echo echo hello 14146@end example 14147 14148After making that change and instructing inetd to 14149re-read its configuration file, "telnet servername 141502401" should show you the text hello and then the 14151server should close the connection. If this doesn't 14152work, you need to fix it before you can worry about 14153@sc{cvs} problems. 14154 14155On AIX systems, the system will often have its own 14156program trying to use port 2401. This is AIX's problem 14157in the sense that port 2401 is registered for use with 14158@sc{cvs}. I hear that there is an AIX patch available 14159to address this problem. 14160 14161Another good debugging tool is the @samp{-d} 14162(debugging) option to inetd. Consult your system 14163documentation for more information. 14164 14165If you seem to be connecting but get errors like: 14166 14167@example 14168cvs server: cannot open /root/.cvsignore: Permission denied 14169cvs [server aborted]: can't chdir(/root): Permission denied 14170@end example 14171 14172@noindent 14173then you probably haven't specified @samp{-f} in @file{inetd.conf}. 14174(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 14175your system setting the @code{$HOME} environment variable 14176for programs being run by inetd. In this case, you can either 14177have inetd run a shell script that unsets @code{$HOME} and then runs 14178@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 14179environment.) 14180 14181If you can connect successfully for a while but then can't, 14182you've probably hit inetd's rate limit. 14183(If inetd receives too many requests for the same service 14184in a short period of time, it assumes that something is wrong 14185and temporarily disables the service.) 14186Check your inetd documentation to find out how to adjust the 14187rate limit (some versions of inetd have a single rate limit, 14188others allow you to set the limit for each service separately.) 14189@end table 14190 14191@node Other problems 14192@appendixsec Other common problems 14193 14194Here is a list of problems which do not fit into the 14195above categories. They are in no particular order. 14196 14197@itemize @bullet 14198@item 14199On Windows, if there is a 30 second or so delay when 14200you run a @sc{cvs} command, it may mean that you have 14201your home directory set to @file{C:/}, for example (see 14202@code{HOMEDRIVE} and @code{HOMEPATH} in 14203@ref{Environment variables}). @sc{cvs} expects the home 14204directory to not end in a slash, for example @file{C:} 14205or @file{C:\cvs}. 14206@c FIXCVS: CVS should at least detect this and print an 14207@c error, presumably. 14208 14209@item 14210If you are running @sc{cvs} 1.9.18 or older, and 14211@code{cvs update} finds a conflict and tries to 14212merge, as described in @ref{Conflicts example}, but 14213doesn't tell you there were conflicts, then you may 14214have an old version of @sc{rcs}. The easiest solution 14215probably is to upgrade to a current version of 14216@sc{cvs}, which does not rely on external @sc{rcs} 14217programs. 14218@end itemize 14219 14220@c --------------------------------------------------------------------- 14221@node Credits 14222@appendix Credits 14223 14224@cindex Contributors (manual) 14225@cindex Credits (manual) 14226Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 14227wrote the manual pages which were distributed with 14228@sc{cvs} 1.3. Much of their text was copied into this 14229manual. He also read an early draft 14230of this manual and contributed many ideas and 14231corrections. 14232 14233The mailing-list @code{info-cvs} is sometimes 14234informative. I have included information from postings 14235made by the following persons: 14236David G. Grubbs <@t{dgg@@think.com}>. 14237 14238Some text has been extracted from the man pages for 14239@sc{rcs}. 14240 14241The @sc{cvs} @sc{faq} by David G. Grubbs has provided 14242useful material. The @sc{faq} is no longer maintained, 14243however, and this manual is about the closest thing there 14244is to a successor (with respect to documenting how to 14245use @sc{cvs}, at least). 14246 14247In addition, the following persons have helped by 14248telling me about mistakes I've made: 14249 14250@display 14251Roxanne Brunskill <@t{rbrunski@@datap.ca}>, 14252Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 14253Karl Pingle <@t{pingle@@acuson.com}>, 14254Thomas A Peterson <@t{tap@@src.honeywell.com}>, 14255Inge Wallin <@t{ingwa@@signum.se}>, 14256Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 14257and Michael Brown <@t{brown@@wi.extrel.com}>. 14258@end display 14259 14260The list of contributors here is not comprehensive; for a more 14261complete list of who has contributed to this manual see 14262the file @file{doc/ChangeLog} in the @sc{cvs} source 14263distribution. 14264 14265@c --------------------------------------------------------------------- 14266@node BUGS 14267@appendix Dealing with bugs in CVS or this manual 14268 14269@cindex Bugs in this manual or CVS 14270Neither @sc{cvs} nor this manual is perfect, and they 14271probably never will be. If you are having trouble 14272using @sc{cvs}, or think you have found a bug, there 14273are a number of things you can do about it. Note that 14274if the manual is unclear, that can be considered a bug 14275in the manual, so these problems are often worth doing 14276something about as well as problems with @sc{cvs} itself. 14277 14278@cindex Reporting bugs 14279@cindex Bugs, reporting 14280@cindex Errors, reporting 14281@itemize @bullet 14282@item 14283If you want someone to help you and fix bugs that you 14284report, there are companies which will do that for a 14285fee. One such company is: 14286 14287@cindex Ximbiot 14288@cindex Support, getting CVS support 14289@example 14290Ximbiot 14291319 S. River St. 14292Harrisburg, PA 17104-1657 14293USA 14294Email: info@@ximbiot.com 14295Phone: (717) 579-6168 14296Fax: (717) 234-3125 14297http://ximbiot.com/ 14298 14299@end example 14300 14301@item 14302If you got @sc{cvs} through a distributor, such as an 14303operating system vendor or a vendor of freeware 14304@sc{cd-rom}s, you may wish to see whether the 14305distributor provides support. Often, they will provide 14306no support or minimal support, but this may vary from 14307distributor to distributor. 14308 14309@item 14310If you have the skills and time to do so, you may wish 14311to fix the bug yourself. If you wish to submit your 14312fix for inclusion in future releases of @sc{cvs}, see 14313the file @sc{hacking} in the @sc{cvs} source 14314distribution. It contains much more information on the 14315process of submitting fixes. 14316 14317@item 14318There may be resources on the net which can help. Two 14319good places to start are: 14320 14321@example 14322http://www.cvshome.org 14323http://www.loria.fr/~molli/cvs-index.html 14324@end example 14325 14326If you are so inspired, increasing the information 14327available on the net is likely to be appreciated. For 14328example, before the standard @sc{cvs} distribution 14329worked on Windows 95, there was a web page with some 14330explanation and patches for running @sc{cvs} on Windows 1433195, and various people helped out by mentioning this 14332page on mailing lists or newsgroups when the subject 14333came up. 14334 14335@item 14336It is also possible to report bugs to @code{bug-cvs}. 14337Note that someone may or may not want to do anything 14338with your bug report---if you need a solution consider 14339one of the options mentioned above. People probably do 14340want to hear about bugs which are particularly severe 14341in consequences and/or easy to fix, however. You can 14342also increase your odds by being as clear as possible 14343about the exact nature of the bug and any other 14344relevant information. The way to report bugs is to 14345send email to @code{bug-cvs@@gnu.org}. Note 14346that submissions to @code{bug-cvs} may be distributed 14347under the terms of the @sc{gnu} Public License, so if 14348you don't like this, don't submit them. There is 14349usually no justification for sending mail directly to 14350one of the @sc{cvs} maintainers rather than to 14351@code{bug-cvs}; those maintainers who want to hear 14352about such bug reports read @code{bug-cvs}. Also note 14353that sending a bug report to other mailing lists or 14354newsgroups is @emph{not} a substitute for sending it to 14355@code{bug-cvs}. It is fine to discuss @sc{cvs} bugs on 14356whatever forum you prefer, but there are not 14357necessarily any maintainers reading bug reports sent 14358anywhere except @code{bug-cvs}. 14359@end itemize 14360 14361@cindex Known bugs in this manual or CVS 14362People often ask if there is a list of known bugs or 14363whether a particular bug is a known one. The file 14364@sc{bugs} in the @sc{cvs} source distribution is one 14365list of known bugs, but it doesn't necessarily try to 14366be comprehensive. Perhaps there will never be a 14367comprehensive, detailed list of known bugs. 14368 14369@c --------------------------------------------------------------------- 14370@node Index 14371@unnumbered Index 14372@cindex Index 14373 14374@printindex cp 14375 14376@summarycontents 14377 14378@contents 14379 14380@bye 14381