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 95@macro splitrcskeyword {arg} 96 \arg\ 97@end macro 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@titlepage 110@sp 4 111@comment The title is printed in a large font. 112@center @titlefont{Version Management} 113@sp 114@center @titlefont{with} 115@sp 116@center @titlefont{CVS} 117@sp 2 118@center for @sc{cvs} 4.2 119@comment -release- 120@sp 3 121@center Per Cederqvist et al 122 123@comment The following two commands start the copyright page 124@comment for the printed manual. This will not appear in the Info file. 125@page 126@vskip 0pt plus 1filll 127@noindent 128Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 129 2001, 2002, 2003 Free Software Foundation, Inc. 130 131@multitable @columnfractions .12 .88 132@item Portions 133@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek R. Price, 134@item @tab Copyright @copyright{} 2002, 2003 Ximbiot <http://ximbiot.com>, 135@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 136@item @tab and Copyright @copyright{} others. 137@end multitable 138 139Permission is granted to make and distribute verbatim copies of 140this manual provided the copyright notice and this permission notice 141are preserved on all copies. 142 143Permission is granted to copy and distribute modified versions of this 144manual under the conditions for verbatim copying, provided also that the 145entire resulting derived work is distributed under the terms of a 146permission notice identical to this one. 147 148Permission is granted to copy and distribute translations of this manual 149into another language, under the above conditions for modified versions, 150except that this permission notice may be stated in a translation 151approved by the Free Software Foundation. 152@end titlepage 153 154@comment ================================================================ 155@comment The real text starts here 156@comment ================================================================ 157 158@c --------------------------------------------------------------------- 159@node Top 160@top 161 162This info manual describes how to use and administer 163@sc{cvs} version 4.2. 164 165@noindent 166Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 167 2001, 2002, 2003 Free Software Foundation, Inc. 168 169@multitable @columnfractions .12 .88 170@item Portions 171@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Derek R. Price, 172@item @tab Copyright @copyright{} 2002, 2003 Ximbiot <http://ximbiot.com>, 173@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 174@item @tab and Copyright @copyright{} others. 175@end multitable 176 177Permission is granted to make and distribute verbatim copies of 178this manual provided the copyright notice and this permission notice 179are preserved on all copies. 180 181Permission is granted to copy and distribute modified versions of this 182manual under the conditions for verbatim copying, provided also that the 183entire resulting derived work is distributed under the terms of a 184permission notice identical to this one. 185 186Permission is granted to copy and distribute translations of this manual 187into another language, under the above conditions for modified versions, 188except that this permission notice may be stated in a translation 189approved by the Free Software Foundation. 190 191@c This menu is pretty long. Not sure how easily that 192@c can be fixed (no brilliant ideas right away)... 193@menu 194* Overview:: An introduction to CVS 195* Repository:: Where all your sources are stored 196* Starting a new project:: Starting a project with CVS 197* Revisions:: Numeric and symbolic names for revisions 198* Branching and merging:: Diverging/rejoining branches of development 199* Recursive behavior:: CVS descends directories 200* Adding and removing:: Adding/removing/renaming files/directories 201* History browsing:: Viewing the history of files in various ways 202 203CVS and the Real World. 204----------------------- 205* Binary files:: CVS can handle binary files 206* Multiple developers:: How CVS helps a group of developers 207* Revision management:: Policy questions for revision management 208* Keyword substitution:: CVS can include the revision inside the file 209* Tracking sources:: Tracking third-party sources 210* Builds:: Issues related to CVS and builds 211* Special Files:: Devices, links and other non-regular files 212 213References. 214----------- 215* CVS commands:: CVS commands share some things 216* Invoking CVS:: Quick reference to CVS commands 217* Administrative files:: Reference manual for the Administrative files 218* Environment variables:: All environment variables which affect CVS 219* Compatibility:: Upgrading CVS versions 220* Troubleshooting:: Some tips when nothing works 221* Credits:: Some of the contributors to this manual 222* BUGS:: Dealing with bugs in CVS or this manual 223* Index:: Index 224@end menu 225 226@c --------------------------------------------------------------------- 227@node Overview 228@chapter Overview 229@cindex Overview 230 231This chapter is for people who have never used 232@sc{cvs}, and perhaps have never used version control 233software before. 234 235If you are already familiar with @sc{cvs} and are just 236trying to learn a particular feature or remember a 237certain command, you can probably skip everything here. 238 239@menu 240* What is CVS?:: What you can do with @sc{cvs} 241* What is CVS not?:: Problems @sc{cvs} doesn't try to solve 242* A sample session:: A tour of basic @sc{cvs} usage 243@end menu 244 245@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 246@node What is CVS? 247@section What is CVS? 248@cindex What is CVS? 249@cindex Introduction to CVS 250@cindex CVS, introduction to 251 252@sc{cvs} is a version control system. Using it, you can 253record the history of your source files. 254 255@c -- /// 256@c -- ///Those who cannot remember the past are condemned to repeat it. 257@c -- /// -- George Santayana 258@c -- ////// 259 260@c -- Insert history quote here! 261For example, bugs sometimes creep in when 262software is modified, and you might not detect the bug 263until a long time after you make the modification. 264With @sc{cvs}, you can easily retrieve old versions to see 265exactly which change caused the bug. This can 266sometimes be a big help. 267 268You could of course save every version of every file 269you have ever created. This would 270however waste an enormous amount of disk space. @sc{cvs} 271stores all the versions of a file in a single file in a 272clever way that only stores the differences between 273versions. 274 275@sc{cvs} also helps you if you are part of a group of people working 276on the same project. It is all too easy to overwrite 277each others' changes unless you are extremely careful. 278Some editors, like @sc{gnu} Emacs, try to make sure that 279the same file is never modified by two people at the 280same time. Unfortunately, if someone is using another 281editor, that safeguard will not work. @sc{cvs} solves this problem 282by insulating the different developers from each other. Every 283developer works in his own directory, and @sc{cvs} merges 284the work when each developer is done. 285 286@cindex History of CVS 287@cindex CVS, history of 288@cindex Credits (CVS program) 289@cindex Contributors (CVS program) 290@sc{cvs} started out as a bunch of shell scripts written by 291Dick Grune, posted to the newsgroup 292@code{comp.sources.unix} in the volume 6 293release of July, 1986. While no actual code from 294these shell scripts is present in the current version 295of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms 296come from them. 297 298In April, 1989, Brian Berliner designed and coded @sc{cvs}. 299Jeff Polk later helped Brian with the design of the @sc{cvs} 300module and vendor branch support. 301 302@cindex Source, getting CVS source 303You can get @sc{cvs} in a variety of ways, including 304free download from the internet. For more information 305on downloading @sc{cvs} and other @sc{cvs} topics, see: 306 307@example 308http://www.cvshome.org/ 309http://www.loria.fr/~molli/cvs-index.html 310@end example 311 312@cindex Mailing list 313@cindex List, mailing list 314@cindex Newsgroups 315There is a mailing list, known as @w{@code{info-cvs}}, 316devoted to @sc{cvs}. To subscribe or 317unsubscribe 318write to 319@w{@code{info-cvs-request@@gnu.org}}. 320If you prefer a usenet group, the right 321group is @code{comp.software.config-mgmt} which is for 322@sc{cvs} discussions (along with other configuration 323management systems). In the future, it might be 324possible to create a 325@code{comp.software.config-mgmt.cvs}, but probably only 326if there is sufficient @sc{cvs} traffic on 327@code{comp.software.config-mgmt}. 328@c Other random data is that past attempts to create a 329@c gnu.* group have failed (the relevant authorities 330@c say they'll do it, but don't), and that tale was very 331@c skeptical of comp.software.config-mgmt.cvs when the 332@c subject came up around 1995 or so (for one 333@c thing, because creating it would be a "reorg" which 334@c would need to take a more comprehensive look at the 335@c whole comp.software.config-mgmt.* hierarchy). 336 337You can also subscribe to the @code{bug-cvs} mailing list, 338described in more detail in @ref{BUGS}. To subscribe 339send mail to @code{bug-cvs-request@@gnu.org}. 340 341@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 342@node What is CVS not? 343@section What is CVS not? 344@cindex What is CVS not? 345 346@sc{cvs} can do a lot of things for you, but it does 347not try to be everything for everyone. 348 349@table @asis 350@item @sc{cvs} is not a build system. 351 352Though the structure of your repository and modules 353file interact with your build system 354(e.g. @file{Makefile}s), they are essentially 355independent. 356 357@sc{cvs} does not dictate how you build anything. It 358merely stores files for retrieval in a tree structure 359you devise. 360 361@sc{cvs} does not dictate how to use disk space in the 362checked out working directories. If you write your 363@file{Makefile}s or scripts in every directory so they 364have to know the relative positions of everything else, 365you wind up requiring the entire repository to be 366checked out. 367 368If you modularize your work, and construct a build 369system that will share files (via links, mounts, 370@code{VPATH} in @file{Makefile}s, etc.), you can 371arrange your disk usage however you like. 372 373But you have to remember that @emph{any} such system is 374a lot of work to construct and maintain. @sc{cvs} does 375not address the issues involved. 376 377Of course, you should place the tools created to 378support such a build system (scripts, @file{Makefile}s, 379etc) under @sc{cvs}. 380 381Figuring out what files need to be rebuilt when 382something changes is, again, something to be handled 383outside the scope of @sc{cvs}. One traditional 384approach is to use @code{make} for building, and use 385some automated tool for generating the dependencies which 386@code{make} uses. 387 388See @ref{Builds}, for more information on doing builds 389in conjunction with @sc{cvs}. 390 391@item @sc{cvs} is not a substitute for management. 392 393Your managers and project leaders are expected to talk 394to you frequently enough to make certain you are aware 395of schedules, merge points, branch names and release 396dates. If they don't, @sc{cvs} can't help. 397 398@sc{cvs} is an instrument for making sources dance to 399your tune. But you are the piper and the composer. No 400instrument plays itself or writes its own music. 401 402@item @sc{cvs} is not a substitute for developer communication. 403 404When faced with conflicts within a single file, most 405developers manage to resolve them without too much 406effort. But a more general definition of ``conflict'' 407includes problems too difficult to solve without 408communication between developers. 409 410@sc{cvs} cannot determine when simultaneous changes 411within a single file, or across a whole collection of 412files, will logically conflict with one another. Its 413concept of a @dfn{conflict} is purely textual, arising 414when two changes to the same base file are near enough 415to spook the merge (i.e. @code{diff3}) command. 416 417@sc{cvs} does not claim to help at all in figuring out 418non-textual or distributed conflicts in program logic. 419 420For example: Say you change the arguments to function 421@code{X} defined in file @file{A}. At the same time, 422someone edits file @file{B}, adding new calls to 423function @code{X} using the old arguments. You are 424outside the realm of @sc{cvs}'s competence. 425 426Acquire the habit of reading specs and talking to your 427peers. 428 429 430@item @sc{cvs} does not have change control 431 432Change control refers to a number of things. First of 433all it can mean @dfn{bug-tracking}, that is being able 434to keep a database of reported bugs and the status of 435each one (is it fixed? in what release? has the bug 436submitter agreed that it is fixed?). For interfacing 437@sc{cvs} to an external bug-tracking system, see the 438@file{rcsinfo} and @file{verifymsg} files 439(@pxref{Administrative files}). 440 441Another aspect of change control is keeping track of 442the fact that changes to several files were in fact 443changed together as one logical change. If you check 444in several files in a single @code{cvs commit} 445operation, @sc{cvs} then forgets that those files were 446checked in together, and the fact that they have the 447same log message is the only thing tying them 448together. Keeping a @sc{gnu} style @file{ChangeLog} 449can help somewhat. 450@c FIXME: should have an xref to a section which talks 451@c more about keeping ChangeLog's with CVS, but that 452@c section hasn't been written yet. 453 454Another aspect of change control, in some systems, is 455the ability to keep track of the status of each 456change. Some changes have been written by a developer, 457others have been reviewed by a second developer, and so 458on. Generally, the way to do this with @sc{cvs} is to 459generate a diff (using @code{cvs diff} or @code{diff}) 460and email it to someone who can then apply it using the 461@code{patch} utility. This is very flexible, but 462depends on mechanisms outside @sc{cvs} to make sure 463nothing falls through the cracks. 464 465@item @sc{cvs} is not an automated testing program 466 467It should be possible to enforce mandatory use of a 468testsuite using the @code{commitinfo} file. I haven't 469heard a lot about projects trying to do that or whether 470there are subtle gotchas, however. 471 472@item @sc{cvs} does not have a builtin process model 473 474Some systems provide ways to ensure that changes or 475releases go through various steps, with various 476approvals as needed. Generally, one can accomplish 477this with @sc{cvs} but it might be a little more work. 478In some cases you'll want to use the @file{commitinfo}, 479@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} 480files, to require that certain steps be performed 481before cvs will allow a checkin. Also consider whether 482features such as branches and tags can be used to 483perform tasks such as doing work in a development tree 484and then merging certain changes over to a stable tree 485only once they have been proven. 486@end table 487 488@c --------------------------------------------------------------------- 489@node A sample session 490@section A sample session 491@cindex Example of a work-session 492@cindex Getting started 493@cindex Work-session, example of 494@cindex tc, Trivial Compiler (example) 495@cindex Trivial Compiler (example) 496 497@c I think an example is a pretty good way to start. But 498@c somewhere in here, maybe after the sample session, 499@c we need something which is kind of 500@c a "roadmap" which is more directed at sketching out 501@c the functionality of CVS and pointing people to 502@c various other parts of the manual. As it stands now 503@c people who read in order get dumped right into all 504@c manner of hair regarding remote repositories, 505@c creating a repository, etc. 506@c 507@c The following was in the old Basic concepts node. I don't 508@c know how good a job it does at introducing modules, 509@c or whether they need to be introduced so soon, but 510@c something of this sort might go into some 511@c introductory material somewhere. 512 513As a way of introducing @sc{cvs}, we'll go through a 514typical work-session using @sc{cvs}. The first thing 515to understand is that @sc{cvs} stores all files in a 516centralized @dfn{repository} (@pxref{Repository}); this 517section assumes that a repository is set up. 518@c I'm not sure that the sentence concerning the 519@c repository quite tells the user what they need to 520@c know at this point. Might need to expand on "centralized" 521@c slightly (maybe not here, maybe further down in the example?) 522 523Suppose you are working on a simple compiler. The source 524consists of a handful of C files and a @file{Makefile}. 525The compiler is called @samp{tc} (Trivial Compiler), 526and the repository is set up so that there is a module 527called @samp{tc}. 528 529@menu 530* Getting the source:: Creating a workspace 531* Committing your changes:: Making your work available to others 532* Cleaning up:: Cleaning up 533* Viewing differences:: Viewing differences 534@end menu 535 536@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 537@node Getting the source 538@subsection Getting the source 539@cindex Getting the source 540@cindex Checking out source 541@cindex Fetching source 542@cindex Source, getting from CVS 543@cindex Checkout, example 544 545The first thing you must do is to get your own working copy of the 546source for @samp{tc}. For this, you use the @code{checkout} command: 547 548@example 549$ cvs checkout tc 550@end example 551 552@noindent 553This will create a new directory called @file{tc} and populate it with 554the source files. 555 556@example 557$ cd tc 558$ ls 559CVS Makefile backend.c driver.c frontend.c parser.c 560@end example 561 562The @file{CVS} directory is used internally by 563@sc{cvs}. Normally, you should not modify or remove 564any of the files in it. 565 566You start your favorite editor, hack away at @file{backend.c}, and a couple 567of hours later you have added an optimization pass to the compiler. 568A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that 569you want to edit. @xref{Multiple developers}, for an explanation. 570 571@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 572@node Committing your changes 573@subsection Committing your changes 574@cindex Committing changes to files 575@cindex Log message entry 576 577When you have checked that the compiler is still compilable you decide 578to make a new version of @file{backend.c}. This will 579store your new @file{backend.c} in the repository and 580make it available to anyone else who is using that same 581repository. 582 583@example 584$ cvs commit backend.c 585@end example 586 587@noindent 588@sc{cvs} starts an editor, to allow you to enter a log 589message. You type in ``Added an optimization pass.'', 590save the temporary file, and exit the editor. 591 592@cindex CVSEDITOR, environment variable 593@cindex EDITOR, environment variable 594The environment variable @code{$CVSEDITOR} determines 595which editor is started. If @code{$CVSEDITOR} is not 596set, then if the environment variable @code{$EDITOR} is 597set, it will be used. If both @code{$CVSEDITOR} and 598@code{$EDITOR} are not set then there is a default 599which will vary with your operating system, for example 600@code{vi} for unix or @code{notepad} for Windows 601NT/95. 602 603@cindex VISUAL, environment variable 604In addition, @sc{cvs} checks the @code{$VISUAL} environment 605variable. Opinions vary on whether this behavior is desirable and 606whether future releases of @sc{cvs} should check @code{$VISUAL} or 607ignore it. You will be OK either way if you make sure that 608@code{$VISUAL} is either unset or set to the same thing as 609@code{$EDITOR}. 610 611@c This probably should go into some new node 612@c containing detailed info on the editor, rather than 613@c the intro. In fact, perhaps some of the stuff with 614@c CVSEDITOR and -m and so on should too. 615When @sc{cvs} starts the editor, it includes a list of 616files which are modified. For the @sc{cvs} client, 617this list is based on comparing the modification time 618of the file against the modification time that the file 619had when it was last gotten or updated. Therefore, if 620a file's modification time has changed but its contents 621have not, it will show up as modified. The simplest 622way to handle this is simply not to worry about it---if 623you proceed with the commit @sc{cvs} will detect that 624the contents are not modified and treat it as an 625unmodified file. The next @code{update} will clue 626@sc{cvs} in to the fact that the file is unmodified, 627and it will reset its stored timestamp so that the file 628will not show up in future editor sessions. 629@c FIXCVS: Might be nice if "commit" and other commands 630@c would reset that timestamp too, but currently commit 631@c doesn't. 632@c FIXME: Need to talk more about the process of 633@c prompting for the log message. Like show an example 634@c of what it pops up in the editor, for example. Also 635@c a discussion of how to get the "a)bort, c)ontinue, 636@c e)dit" prompt and what to do with it. Might also 637@c work in the suggestion that if you want a diff, you 638@c should make it before running commit (someone 639@c suggested that the diff pop up in the editor. I'm 640@c not sure that is better than telling people to run 641@c "cvs diff" first if that is what they want, but if 642@c we want to tell people that, the manual possibly 643@c should say it). 644 645If you want to avoid 646starting an editor you can specify the log message on 647the command line using the @samp{-m} flag instead, like 648this: 649 650@example 651$ cvs commit -m "Added an optimization pass" backend.c 652@end example 653 654@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 655@node Cleaning up 656@subsection Cleaning up 657@cindex Cleaning up 658@cindex Working copy, removing 659@cindex Removing your working copy 660@cindex Releasing your working copy 661 662Before you turn to other tasks you decide to remove your working copy of 663tc. One acceptable way to do that is of course 664 665@example 666$ cd .. 667$ rm -r tc 668@end example 669 670@noindent 671but a better way is to use the @code{release} command (@pxref{release}): 672 673@example 674$ cd .. 675$ cvs release -d tc 676M driver.c 677? tc 678You have [1] altered files in this repository. 679Are you sure you want to release (and delete) directory `tc': n 680** `release' aborted by user choice. 681@end example 682 683The @code{release} command checks that all your modifications have been 684committed. If history logging is enabled it also makes a note in the 685history file. @xref{history file}. 686 687When you use the @samp{-d} flag with @code{release}, it 688also removes your working copy. 689 690In the example above, the @code{release} command wrote a couple of lines 691of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. 692That is nothing to worry about: @file{tc} is the executable compiler, 693and it should not be stored in the repository. @xref{cvsignore}, 694for information about how to make that warning go away. 695@xref{release output}, for a complete explanation of 696all possible output from @code{release}. 697 698@samp{M driver.c} is more serious. It means that the 699file @file{driver.c} has been modified since it was 700checked out. 701 702The @code{release} command always finishes by telling 703you how many modified files you have in your working 704copy of the sources, and then asks you for confirmation 705before deleting any files or making any note in the 706history file. 707 708You decide to play it safe and answer @kbd{n @key{RET}} 709when @code{release} asks for confirmation. 710 711@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 712@node Viewing differences 713@subsection Viewing differences 714@cindex Viewing differences 715@cindex Diff 716 717You do not remember modifying @file{driver.c}, so you want to see what 718has happened to that file. 719 720@example 721$ cd tc 722$ cvs diff driver.c 723@end example 724 725This command runs @code{diff} to compare the version of @file{driver.c} 726that you checked out with your working copy. When you see the output 727you remember that you added a command line option that enabled the 728optimization pass. You check it in, and release the module. 729@c FIXME: we haven't yet defined the term "check in". 730 731@example 732$ cvs commit -m "Added an optimization pass" driver.c 733Checking in driver.c; 734/usr/local/cvsroot/tc/driver.c,v <-- driver.c 735new revision: 1.2; previous revision: 1.1 736done 737$ cd .. 738$ cvs release -d tc 739? tc 740You have [0] altered files in this repository. 741Are you sure you want to release (and delete) directory `tc': y 742@end example 743 744@c --------------------------------------------------------------------- 745@node Repository 746@chapter The Repository 747@cindex Repository (intro) 748@cindex Repository, example 749@cindex Layout of repository 750@cindex Typical repository 751@cindex /usr/local/cvsroot, as example repository 752@cindex cvsroot 753 754The @sc{cvs} @dfn{repository} stores a complete copy of 755all the files and directories which are under version 756control. 757 758Normally, you never access any of the files in the 759repository directly. Instead, you use @sc{cvs} 760commands to get your own copy of the files into a 761@dfn{working directory}, and then 762work on that copy. When you've finished a set of 763changes, you check (or @dfn{commit}) them back into the 764repository. The repository then contains the changes 765which you have made, as well as recording exactly what 766you changed, when you changed it, and other such 767information. Note that the repository is not a 768subdirectory of the working directory, or vice versa; 769they should be in separate locations. 770@c Need some example, e.g. repository 771@c /usr/local/cvsroot; working directory 772@c /home/joe/sources. But this node is too long 773@c as it is; need a little reorganization... 774 775@cindex :local:, setting up 776@sc{cvs} can access a repository by a variety of 777means. It might be on the local computer, or it might 778be on a computer across the room or across the world. 779To distinguish various ways to access a repository, the 780repository name can start with an @dfn{access method}. 781For example, the access method @code{:local:} means to 782access a repository directory, so the repository 783@code{:local:/usr/local/cvsroot} means that the 784repository is in @file{/usr/local/cvsroot} on the 785computer running @sc{cvs}. For information on other 786access methods, see @ref{Remote repositories}. 787 788@c Can se say this more concisely? Like by passing 789@c more of the buck to the Remote repositories node? 790If the access method is omitted, then if the repository 791starts with @samp{/}, then @code{:local:} is 792assumed. If it does not start with @samp{/} then either 793@code{:ext:} or @code{:server:} is assumed. For 794example, if you have a local repository in 795@file{/usr/local/cvsroot}, you can use 796@code{/usr/local/cvsroot} instead of 797@code{:local:/usr/local/cvsroot}. But if (under 798Windows NT, for example) your local repository is 799@file{c:\src\cvsroot}, then you must specify the access 800method, as in @code{:local:c:/src/cvsroot}. 801 802@c This might appear to go in Repository storage, but 803@c actually it is describing something which is quite 804@c user-visible, when you do a "cvs co CVSROOT". This 805@c isn't necessary the perfect place for that, though. 806The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains 807administrative files for @sc{cvs}. The other directories contain the actual 808user-defined modules. 809 810@menu 811* Specifying a repository:: Telling CVS where your repository is 812* Repository storage:: The structure of the repository 813* Working directory storage:: The structure of working directories 814* Intro administrative files:: Defining modules 815* Multiple repositories:: Multiple repositories 816* Creating a repository:: Creating a repository 817* Backing up:: Backing up a repository 818* Moving a repository:: Moving a repository 819* Remote repositories:: Accessing repositories on remote machines 820* Read-only access:: Granting read-only access to the repository 821* Server temporary directory:: The server creates temporary directories 822@end menu 823 824@node Specifying a repository 825@section Telling CVS where your repository is 826 827There are several ways to tell @sc{cvs} 828where to find the repository. You can name the 829repository on the command line explicitly, with the 830@code{-d} (for "directory") option: 831 832@example 833cvs -d /usr/local/cvsroot checkout yoyodyne/tc 834@end example 835 836@cindex .profile, setting CVSROOT in 837@cindex .cshrc, setting CVSROOT in 838@cindex .tcshrc, setting CVSROOT in 839@cindex .bashrc, setting CVSROOT in 840@cindex CVSROOT, environment variable 841 Or you can set the @code{$CVSROOT} environment 842variable to an absolute path to the root of the 843repository, @file{/usr/local/cvsroot} in this example. 844To set @code{$CVSROOT}, @code{csh} and @code{tcsh} 845users should have this line in their @file{.cshrc} or 846@file{.tcshrc} files: 847 848@example 849setenv CVSROOT /usr/local/cvsroot 850@end example 851 852@noindent 853@code{sh} and @code{bash} users should instead have these lines in their 854@file{.profile} or @file{.bashrc}: 855 856@example 857CVSROOT=/usr/local/cvsroot 858export CVSROOT 859@end example 860 861@cindex Root file, in CVS directory 862@cindex CVS/Root file 863 A repository specified with @code{-d} will 864override the @code{$CVSROOT} environment variable. 865Once you've checked a working copy out from the 866repository, it will remember where its repository is 867(the information is recorded in the 868@file{CVS/Root} file in the working copy). 869 870The @code{-d} option and the @file{CVS/Root} file both 871override the @code{$CVSROOT} environment variable. If 872@code{-d} option differs from @file{CVS/Root}, the 873former is used. Of course, for proper operation they 874should be two ways of referring to the same repository. 875 876@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 877@node Repository storage 878@section How data is stored in the repository 879@cindex Repository, how data is stored 880 881For most purposes it isn't important @emph{how} 882@sc{cvs} stores information in the repository. In 883fact, the format has changed in the past, and is likely 884to change in the future. Since in almost all cases one 885accesses the repository via @sc{cvs} commands, such 886changes need not be disruptive. 887 888However, in some cases it may be necessary to 889understand how @sc{cvs} stores data in the repository, 890for example you might need to track down @sc{cvs} locks 891(@pxref{Concurrency}) or you might need to deal with 892the file permissions appropriate for the repository. 893 894@menu 895* Repository files:: What files are stored in the repository 896* File permissions:: File permissions 897* Windows permissions:: Issues specific to Windows 898* Attic:: Some files are stored in the Attic 899* CVS in repository:: Additional information in CVS directory 900* Locks:: CVS locks control concurrent accesses 901* CVSROOT storage:: A few things about CVSROOT are different 902@end menu 903 904@node Repository files 905@subsection Where files are stored within the repository 906 907@c @cindex Filenames, legal 908@c @cindex Legal filenames 909@c Somewhere we need to say something about legitimate 910@c characters in filenames in working directory and 911@c repository. Not "/" (not even on non-unix). And 912@c here is a specific set of issues: 913@c Files starting with a - are handled inconsistently. They can not 914@c be added to a repository with an add command, because it they are 915@c interpreted as a switch. They can appear in a repository if they are 916@c part of a tree that is imported. They can not be removed from the tree 917@c once they are there. 918@c Note that "--" *is* supported (as a 919@c consequence of using GNU getopt). Should document 920@c this somewhere ("Common options"?). The other usual technique, 921@c "./-foo", isn't as effective, at least for "cvs add" 922@c which doesn't support pathnames containing "/". 923 924The overall structure of the repository is a directory 925tree corresponding to the directories in the working 926directory. For example, supposing the repository is in 927 928@example 929/usr/local/cvsroot 930@end example 931 932@noindent 933here is a possible directory tree (showing only the 934directories): 935 936@example 937@t{/usr} 938 | 939 +--@t{local} 940 | | 941 | +--@t{cvsroot} 942 | | | 943 | | +--@t{CVSROOT} 944 | (administrative files) 945 | 946 +--@t{gnu} 947 | | 948 | +--@t{diff} 949 | | (source code to @sc{gnu} diff) 950 | | 951 | +--@t{rcs} 952 | | (source code to @sc{rcs}) 953 | | 954 | +--@t{cvs} 955 | (source code to @sc{cvs}) 956 | 957 +--@t{yoyodyne} 958 | 959 +--@t{tc} 960 | | 961 | +--@t{man} 962 | | 963 | +--@t{testing} 964 | 965 +--(other Yoyodyne software) 966@end example 967 968With the directories are @dfn{history files} for each file 969under version control. The name of the history file is 970the name of the corresponding file with @samp{,v} 971appended to the end. Here is what the repository for 972the @file{yoyodyne/tc} directory might look like: 973@c FIXME: Should also mention CVS (CVSREP) 974@c FIXME? Should we introduce Attic with an xref to 975@c Attic? Not sure whether that is a good idea or not. 976@example 977 @code{$CVSROOT} 978 | 979 +--@t{yoyodyne} 980 | | 981 | +--@t{tc} 982 | | | 983 +--@t{Makefile,v} 984 +--@t{backend.c,v} 985 +--@t{driver.c,v} 986 +--@t{frontend.c,v} 987 +--@t{parser.c,v} 988 +--@t{man} 989 | | 990 | +--@t{tc.1,v} 991 | 992 +--@t{testing} 993 | 994 +--@t{testpgm.t,v} 995 +--@t{test2.t,v} 996@end example 997 998@cindex History files 999@cindex RCS history files 1000@c The first sentence, about what history files 1001@c contain, is kind of redundant with our intro to what the 1002@c repository does in node Repository.... 1003The history files contain, among other things, enough 1004information to recreate any revision of the file, a log 1005of all commit messages and the user-name of the person 1006who committed the revision. The history files are 1007known as @dfn{RCS files}, because the first program to 1008store files in that format was a version control system 1009known as @sc{rcs}. For a full 1010description of the file format, see the @code{man} page 1011@cite{rcsfile(5)}, distributed with @sc{rcs}, or the 1012file @file{doc/RCSFILES} in the @sc{cvs} source 1013distribution. This 1014file format has become very common---many systems other 1015than @sc{cvs} or @sc{rcs} can at least import history 1016files in this format. 1017@c FIXME: Think about including documentation for this 1018@c rather than citing it? In the long run, getting 1019@c this to be a standard (not sure if we can cope with 1020@c a standards process as formal as IEEE/ANSI/ISO/etc, 1021@c though...) is the way to go, so maybe citing is 1022@c better. 1023 1024The @sc{rcs} files used in @sc{cvs} differ in a few 1025ways from the standard format. The biggest difference 1026is magic branches; for more information see @ref{Magic 1027branch numbers}. Also in @sc{cvs} the valid tag names 1028are a subset of what @sc{rcs} accepts; for @sc{cvs}'s 1029rules see @ref{Tags}. 1030 1031@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032@node File permissions 1033@subsection File permissions 1034@c -- Move this to @node Creating a repository or similar 1035@cindex Security, file permissions in repository 1036@cindex File permissions, general 1037@cindex Permissions, general 1038@c FIXME: we need to somehow reflect "permissions in 1039@c repository" versus "permissions in working 1040@c directory" in the index entries. 1041@cindex Group 1042@cindex Read-only files, in repository 1043All @samp{,v} files are created read-only, and you 1044should not change the permission of those files. The 1045directories inside the repository should be writable by 1046the persons that have permission to modify the files in 1047each directory. This normally means that you must 1048create a UNIX group (see group(5)) consisting of the 1049persons that are to edit the files in a project, and 1050set up the repository so that it is that group that 1051owns the directory. 1052(On some systems, you also need to set the set-group-ID-on-execution bit 1053on the repository directories (see chmod(1)) so that newly-created files 1054and directories get the group-ID of the parent directory rather than 1055that of the current process.) 1056 1057@c See also comment in commitinfo node regarding cases 1058@c which are really awkward with unix groups. 1059 1060This means that you can only control access to files on 1061a per-directory basis. 1062 1063Note that users must also have write access to check 1064out files, because @sc{cvs} needs to create lock files 1065(@pxref{Concurrency}). You can use LockDir in CVSROOT/config 1066to put the lock files somewhere other than in the repository 1067if you want to allow read-only access to some directories 1068(@pxref{config}). 1069 1070@c CVS seems to use CVSUMASK in picking permissions for 1071@c val-tags, but maybe we should say more about this. 1072@c Like val-tags gets created by someone who doesn't 1073@c have CVSUMASK set right? 1074Also note that users must have write access to the 1075@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep 1076track of what tags are valid tag names (it is sometimes 1077updated when tags are used, as well as when they are 1078created). 1079 1080Each @sc{rcs} file will be owned by the user who last 1081checked it in. This has little significance; what 1082really matters is who owns the directories. 1083 1084@cindex CVSUMASK, environment variable 1085@cindex Umask, for repository files 1086@sc{cvs} tries to set up reasonable file permissions 1087for new directories that are added inside the tree, but 1088you must fix the permissions manually when a new 1089directory should have different permissions than its 1090parent directory. If you set the @code{CVSUMASK} 1091environment variable that will control the file 1092permissions which @sc{cvs} uses in creating directories 1093and/or files in the repository. @code{CVSUMASK} does 1094not affect the file permissions in the working 1095directory; such files have the permissions which are 1096typical for newly created files, except that sometimes 1097@sc{cvs} creates them read-only (see the sections on 1098watches, @ref{Setting a watch}; -r, @ref{Global 1099options}; or @code{CVSREAD}, @ref{Environment variables}). 1100@c FIXME: Need more discussion of which 1101@c group should own the file in the repository. 1102@c Include a somewhat detailed example of the usual 1103@c case where CVSUMASK is 007, the developers are all 1104@c in a group, and that group owns stuff in the 1105@c repository. Need to talk about group ownership of 1106@c newly-created directories/files (on some unices, 1107@c such as SunOS4, setting the setgid bit on the 1108@c directories will make files inherit the directory's 1109@c group. On other unices, your mileage may vary. I 1110@c can't remember what POSIX says about this, if 1111@c anything). 1112 1113Note that using the client/server @sc{cvs} 1114(@pxref{Remote repositories}), there is no good way to 1115set @code{CVSUMASK}; the setting on the client machine 1116has no effect. If you are connecting with @code{rsh}, you 1117can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as 1118described in the documentation for your operating 1119system. This behavior might change in future versions 1120of @sc{cvs}; do not rely on the setting of 1121@code{CVSUMASK} on the client having no effect. 1122@c FIXME: need to explain what a umask is or cite 1123@c someplace which does. 1124@c 1125@c There is also a larger (largely separate) issue 1126@c about the meaning of CVSUMASK in a non-unix context. 1127@c For example, whether there is 1128@c an equivalent which fits better into other 1129@c protection schemes like POSIX.6, VMS, &c. 1130@c 1131@c FIXME: Need one place which discusses this 1132@c read-only files thing. Why would one use -r or 1133@c CVSREAD? Why would one use watches? How do they 1134@c interact? 1135@c 1136@c FIXME: We need to state 1137@c whether using CVSUMASK removes the need for manually 1138@c fixing permissions (in fact, if we are going to mention 1139@c manually fixing permission, we better document a lot 1140@c better just what we mean by "fix"). 1141 1142Using pserver, you will generally need stricter 1143permissions on the @sc{cvsroot} directory and 1144directories above it in the tree; see @ref{Password 1145authentication security}. 1146 1147@cindex Setuid 1148@cindex Setgid 1149@cindex Security, setuid 1150@cindex Installed images (VMS) 1151Some operating systems have features which allow a 1152particular program to run with the ability to perform 1153operations which the caller of the program could not. 1154For example, the set user ID (setuid) or set group ID 1155(setgid) features of unix or the installed image 1156feature of VMS. @sc{cvs} was not written to use such 1157features and therefore attempting to install @sc{cvs} in 1158this fashion will provide protection against only 1159accidental lapses; anyone who is trying to circumvent 1160the measure will be able to do so, and depending on how 1161you have set it up may gain access to more than just 1162@sc{cvs}. You may wish to instead consider pserver. It 1163shares some of the same attributes, in terms of 1164possibly providing a false sense of security or opening 1165security holes wider than the ones you are trying to 1166fix, so read the documentation on pserver security 1167carefully if you are considering this option 1168(@ref{Password authentication security}). 1169 1170@node Windows permissions 1171@subsection File Permission issues specific to Windows 1172@cindex Windows, and permissions 1173@cindex File permissions, Windows-specific 1174@cindex Permissions, Windows-specific 1175 1176Some file permission issues are specific to Windows 1177operating systems (Windows 95, Windows NT, and 1178presumably future operating systems in this family. 1179Some of the following might apply to OS/2 but I'm not 1180sure). 1181 1182If you are using local @sc{cvs} and the repository is on a 1183networked file system which is served by the Samba SMB 1184server, some people have reported problems with 1185permissions. Enabling WRITE=YES in the samba 1186configuration is said to fix/workaround it. 1187Disclaimer: I haven't investigated enough to know the 1188implications of enabling that option, nor do I know 1189whether there is something which @sc{cvs} could be doing 1190differently in order to avoid the problem. If you find 1191something out, please let us know as described in 1192@ref{BUGS}. 1193 1194@node Attic 1195@subsection The attic 1196@cindex Attic 1197 1198You will notice that sometimes @sc{cvs} stores an 1199@sc{rcs} file in the @code{Attic}. For example, if the 1200@sc{cvsroot} is @file{/usr/local/cvsroot} and we are 1201talking about the file @file{backend.c} in the 1202directory @file{yoyodyne/tc}, then the file normally 1203would be in 1204 1205@example 1206/usr/local/cvsroot/yoyodyne/tc/backend.c,v 1207@end example 1208 1209@noindent 1210but if it goes in the attic, it would be in 1211 1212@example 1213/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v 1214@end example 1215 1216@noindent 1217@cindex Dead state 1218instead. It should not matter from a user point of 1219view whether a file is in the attic; @sc{cvs} keeps 1220track of this and looks in the attic when it needs to. 1221But in case you want to know, the rule is that the RCS 1222file is stored in the attic if and only if the head 1223revision on the trunk has state @code{dead}. A 1224@code{dead} state means that file has been removed, or 1225never added, for that revision. For example, if you 1226add a file on a branch, it will have a trunk revision 1227in @code{dead} state, and a branch revision in a 1228non-@code{dead} state. 1229@c Probably should have some more concrete examples 1230@c here, or somewhere (not sure exactly how we should 1231@c arrange the discussion of the dead state, versus 1232@c discussion of the attic). 1233 1234@node CVS in repository 1235@subsection The CVS directory in the repository 1236@cindex CVS directory, in repository 1237 1238The @file{CVS} directory in each repository directory 1239contains information such as file attributes (in a file 1240called @file{CVS/fileattr}. In the 1241future additional files may be added to this directory, 1242so implementations should silently ignore additional 1243files. 1244 1245This behavior is implemented only by @sc{cvs} 1.7 and 1246later; for details see @ref{Watches Compatibility}. 1247 1248The format of the fileattr file is a series of entries 1249of the following form (where @samp{@{} and @samp{@}} 1250means the text between the braces can be repeated zero 1251or more times): 1252 1253@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} 1254 @{; @var{attrname} = @var{attrval}@} <linefeed> 1255 1256@var{ent-type} is @samp{F} for a file, in which case the entry specifies the 1257attributes for that file. 1258 1259@var{ent-type} is @samp{D}, 1260and @var{filename} empty, to specify default attributes 1261to be used for newly added files. 1262 1263Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older 1264will delete them any time it writes file attributes. 1265@sc{cvs} 1.10 and later will preserve them. 1266 1267Note that the order of the lines is not significant; 1268a program writing the fileattr file may 1269rearrange them at its convenience. 1270 1271There is currently no way of quoting tabs or linefeeds in the 1272filename, @samp{=} in @var{attrname}, 1273@samp{;} in @var{attrval}, etc. Note: some implementations also 1274don't handle a NUL character in any of the fields, but 1275implementations are encouraged to allow it. 1276 1277By convention, @var{attrname} starting with @samp{_} is for an attribute given 1278special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes 1279(or will be, once implementations start supporting user-defined attributes). 1280 1281Builtin attributes: 1282 1283@table @code 1284@item _watched 1285Present means the file is watched and should be checked out 1286read-only. 1287 1288@item _watchers 1289Users with watches for this file. Value is 1290@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} 1291where @var{watcher} is a username, and @var{type} 1292is zero or more of edit,unedit,commit separated by 1293@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). 1294 1295@item _editors 1296Users editing this file. Value is 1297@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} 1298where @var{editor} is a username, and @var{val} is 1299@var{time}+@var{hostname}+@var{pathname}, where 1300@var{time} is when the @code{cvs edit} command (or 1301equivalent) happened, 1302and @var{hostname} and @var{pathname} are for the working directory. 1303@end table 1304 1305Example: 1306 1307@c FIXME: sanity.sh should contain a similar test case 1308@c so we can compare this example from something from 1309@c Real Life(TM). See cvsclient.texi (under Notify) for more 1310@c discussion of the date format of _editors. 1311@example 1312Ffile1 _watched=;_watchers=joe>edit,mary>commit 1313Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs 1314D _watched= 1315@end example 1316 1317@noindent 1318means that the file @file{file1} should be checked out 1319read-only. Furthermore, joe is watching for edits and 1320mary is watching for commits. The file @file{file2} 1321should be checked out read-only; sue started editing it 1322on 8 Jan 1975 in the directory @file{/home/sue/cvs} on 1323the machine @code{workstn1}. Future files which are 1324added should be checked out read-only. To represent 1325this example here, we have shown a space after 1326@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact 1327there must be a single tab character there and no spaces. 1328 1329@node Locks 1330@subsection CVS locks in the repository 1331 1332@cindex #cvs.rfl, technical details 1333@cindex #cvs.wfl, technical details 1334@cindex #cvs.lock, technical details 1335@cindex Locks, cvs, technical details 1336For an introduction to @sc{cvs} locks focusing on 1337user-visible behavior, see @ref{Concurrency}. The 1338following section is aimed at people who are writing 1339tools which want to access a @sc{cvs} repository without 1340interfering with other tools accessing the same 1341repository. If you find yourself confused by concepts 1342described here, like @dfn{read lock}, @dfn{write lock}, 1343and @dfn{deadlock}, you might consult the literature on 1344operating systems or databases. 1345 1346@cindex #cvs.tfl 1347Any file in the repository with a name starting 1348with @file{#cvs.rfl.} is a read lock. Any file in 1349the repository with a name starting with 1350@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} 1351(before @sc{cvs} 1.5) also created files with names starting 1352with @file{#cvs.tfl}, but they are not discussed here. 1353The directory @file{#cvs.lock} serves as a master 1354lock. That is, one must obtain this lock first before 1355creating any of the other locks. 1356 1357To obtain a readlock, first create the @file{#cvs.lock} 1358directory. This operation must be atomic (which should 1359be true for creating a directory under most operating 1360systems). If it fails because the directory already 1361existed, wait for a while and try again. After 1362obtaining the @file{#cvs.lock} lock, create a file 1363whose name is @file{#cvs.rfl.} followed by information 1364of your choice (for example, hostname and process 1365identification number). Then remove the 1366@file{#cvs.lock} directory to release the master lock. 1367Then proceed with reading the repository. When you are 1368done, remove the @file{#cvs.rfl} file to release the 1369read lock. 1370 1371To obtain a writelock, first create the 1372@file{#cvs.lock} directory, as with a readlock. Then 1373check that there are no files whose names start with 1374@file{#cvs.rfl.}. If there are, remove 1375@file{#cvs.lock}, wait for a while, and try again. If 1376there are no readers, then create a file whose name is 1377@file{#cvs.wfl} followed by information of your choice 1378(for example, hostname and process identification 1379number). Hang on to the @file{#cvs.lock} lock. Proceed 1380with writing the repository. When you are done, first 1381remove the @file{#cvs.wfl} file and then the 1382@file{#cvs.lock} directory. Note that unlike the 1383@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just 1384informational; it has no effect on the locking operation 1385beyond what is provided by holding on to the 1386@file{#cvs.lock} lock itself. 1387 1388Note that each lock (writelock or readlock) only locks 1389a single directory in the repository, including 1390@file{Attic} and @file{CVS} but not including 1391subdirectories which represent other directories under 1392version control. To lock an entire tree, you need to 1393lock each directory (note that if you fail to obtain 1394any lock you need, you must release the whole tree 1395before waiting and trying again, to avoid deadlocks). 1396 1397Note also that @sc{cvs} expects writelocks to control 1398access to individual @file{foo,v} files. @sc{rcs} has 1399a scheme where the @file{,foo,} file serves as a lock, 1400but @sc{cvs} does not implement it and so taking out a 1401@sc{cvs} writelock is recommended. See the comments at 1402rcs_internal_lockfile in the @sc{cvs} source code for 1403further discussion/rationale. 1404 1405@node CVSROOT storage 1406@subsection How files are stored in the CVSROOT directory 1407@cindex CVSROOT, storage of files 1408 1409The @file{$CVSROOT/CVSROOT} directory contains the 1410various administrative files. In some ways this 1411directory is just like any other directory in the 1412repository; it contains @sc{rcs} files whose names end 1413in @samp{,v}, and many of the @sc{cvs} commands operate 1414on it the same way. However, there are a few 1415differences. 1416 1417For each administrative file, in addition to the 1418@sc{rcs} file, there is also a checked out copy of the 1419file. For example, there is an @sc{rcs} file 1420@file{loginfo,v} and a file @file{loginfo} which 1421contains the latest revision contained in 1422@file{loginfo,v}. When you check in an administrative 1423file, @sc{cvs} should print 1424 1425@example 1426cvs commit: Rebuilding administrative file database 1427@end example 1428 1429@noindent 1430and update the checked out copy in 1431@file{$CVSROOT/CVSROOT}. If it does not, there is 1432something wrong (@pxref{BUGS}). To add your own files 1433to the files to be updated in this fashion, you can add 1434them to the @file{checkoutlist} administrative file 1435(@pxref{checkoutlist}). 1436 1437@cindex modules.db 1438@cindex modules.pag 1439@cindex modules.dir 1440By default, the @file{modules} file behaves as 1441described above. If the modules file is very large, 1442storing it as a flat text file may make looking up 1443modules slow (I'm not sure whether this is as much of a 1444concern now as when @sc{cvs} first evolved this 1445feature; I haven't seen benchmarks). Therefore, by 1446making appropriate edits to the @sc{cvs} source code 1447one can store the modules file in a database which 1448implements the @code{ndbm} interface, such as Berkeley 1449db or GDBM. If this option is in use, then the modules 1450database will be stored in the files @file{modules.db}, 1451@file{modules.pag}, and/or @file{modules.dir}. 1452@c I think fileattr also will use the database stuff. 1453@c Anything else? 1454 1455For information on the meaning of the various 1456administrative files, see @ref{Administrative files}. 1457 1458@node Working directory storage 1459@section How data is stored in the working directory 1460 1461@c FIXME: Somewhere we should discuss timestamps (test 1462@c case "stamps" in sanity.sh). But not here. Maybe 1463@c in some kind of "working directory" chapter which 1464@c would encompass the "Builds" one? But I'm not sure 1465@c whether that is a good organization (is it based on 1466@c what the user wants to do?). 1467 1468@cindex CVS directory, in working directory 1469While we are discussing @sc{cvs} internals which may 1470become visible from time to time, we might as well talk 1471about what @sc{cvs} puts in the @file{CVS} directories 1472in the working directories. As with the repository, 1473@sc{cvs} handles this information and one can usually 1474access it via @sc{cvs} commands. But in some cases it 1475may be useful to look at it, and other programs, such 1476as the @code{jCVS} graphical user interface or the 1477@code{VC} package for emacs, may need to look at it. 1478Such programs should follow the recommendations in this 1479section if they hope to be able to work with other 1480programs which use those files, including future 1481versions of the programs just mentioned and the 1482command-line @sc{cvs} client. 1483 1484The @file{CVS} directory contains several files. 1485Programs which are reading this directory should 1486silently ignore files which are in the directory but 1487which are not documented here, to allow for future 1488expansion. 1489 1490The files are stored according to the text file 1491convention for the system in question. This means that 1492working directories are not portable between systems 1493with differing conventions for storing text files. 1494This is intentional, on the theory that the files being 1495managed by @sc{cvs} probably will not be portable between 1496such systems either. 1497 1498@table @file 1499@item Root 1500This file contains the current @sc{cvs} root, as 1501described in @ref{Specifying a repository}. 1502 1503@cindex Repository file, in CVS directory 1504@cindex CVS/Repository file 1505@item Repository 1506This file contains the directory within the repository 1507which the current directory corresponds with. It can 1508be either an absolute pathname or a relative pathname; 1509@sc{cvs} has had the ability to read either format 1510since at least version 1.3 or so. The relative 1511pathname is relative to the root, and is the more 1512sensible approach, but the absolute pathname is quite 1513common and implementations should accept either. For 1514example, after the command 1515 1516@example 1517cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc 1518@end example 1519 1520@noindent 1521@file{Root} will contain 1522 1523@example 1524:local:/usr/local/cvsroot 1525@end example 1526 1527@noindent 1528and @file{Repository} will contain either 1529 1530@example 1531/usr/local/cvsroot/yoyodyne/tc 1532@end example 1533 1534@noindent 1535or 1536 1537@example 1538yoyodyne/tc 1539@end example 1540 1541If the particular working directory does not correspond 1542to a directory in the repository, then @file{Repository} 1543should contain @file{CVSROOT/Emptydir}. 1544@cindex Emptydir, in CVSROOT directory 1545@cindex CVSROOT/Emptydir directory 1546 1547@cindex Entries file, in CVS directory 1548@cindex CVS/Entries file 1549@item Entries 1550This file lists the files and directories in the 1551working directory. 1552The first character of each line indicates what sort of 1553line it is. If the character is unrecognized, programs 1554reading the file should silently skip that line, to 1555allow for future expansion. 1556 1557If the first character is @samp{/}, then the format is: 1558 1559@example 1560/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate} 1561@end example 1562 1563@noindent 1564where @samp{[} and @samp{]} are not part of the entry, 1565but instead indicate that the @samp{+} and conflict 1566marker are optional. @var{name} is the name of the 1567file within the directory. @var{revision} is the 1568revision that the file in the working derives from, or 1569@samp{0} for an added file, or @samp{-} followed by a 1570revision for a removed file. @var{timestamp} is the 1571timestamp of the file at the time that @sc{cvs} created 1572it; if the timestamp differs with the actual 1573modification time of the file it means the file has 1574been modified. It is stored in 1575the format used by the ISO C asctime() function (for 1576example, @samp{Sun Apr 7 01:29:26 1996}). One may 1577write a string which is not in that format, for 1578example, @samp{Result of merge}, to indicate that the 1579file should always be considered to be modified. This 1580is not a special case; to see whether a file is 1581modified a program should take the timestamp of the file 1582and simply do a string compare with @var{timestamp}. 1583If there was a conflict, @var{conflict} can be set to 1584the modification time of the file after the file has been 1585written with conflict markers (@pxref{Conflicts example}). 1586Thus if @var{conflict} is subsequently the same as the actual 1587modification time of the file it means that the user 1588has obviously not resolved the conflict. @var{options} 1589contains sticky options (for example @samp{-kb} for a 1590binary file). @var{tagdate} contains @samp{T} followed 1591by a tag name, or @samp{D} for a date, followed by a 1592sticky tag or date. Note that if @var{timestamp} 1593contains a pair of timestamps separated by a space, 1594rather than a single timestamp, you are dealing with a 1595version of @sc{cvs} earlier than @sc{cvs} 1.5 (not 1596documented here). 1597 1598The timezone on the timestamp in CVS/Entries (local or 1599universal) should be the same as the operating system 1600stores for the timestamp of the file itself. For 1601example, on Unix the file's timestamp is in universal 1602time (UT), so the timestamp in CVS/Entries should be 1603too. On @sc{vms}, the file's timestamp is in local 1604time, so @sc{cvs} on @sc{vms} should use local time. 1605This rule is so that files do not appear to be modified 1606merely because the timezone changed (for example, to or 1607from summer time). 1608@c See comments and calls to gmtime() and friends in 1609@c src/vers_ts.c (function time_stamp). 1610 1611If the first character of a line in @file{Entries} is 1612@samp{D}, then it indicates a subdirectory. @samp{D} 1613on a line all by itself indicates that the program 1614which wrote the @file{Entries} file does record 1615subdirectories (therefore, if there is such a line and 1616no other lines beginning with @samp{D}, one knows there 1617are no subdirectories). Otherwise, the line looks 1618like: 1619 1620@example 1621D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4} 1622@end example 1623 1624@noindent 1625where @var{name} is the name of the subdirectory, and 1626all the @var{filler} fields should be silently ignored, 1627for future expansion. Programs which modify 1628@code{Entries} files should preserve these fields. 1629 1630The lines in the @file{Entries} file can be in any order. 1631 1632@cindex Entries.Log file, in CVS directory 1633@cindex CVS/Entries.Log file 1634@item Entries.Log 1635This file does not record any information beyond that 1636in @file{Entries}, but it does provide a way to update 1637the information without having to rewrite the entire 1638@file{Entries} file, including the ability to preserve 1639the information even if the program writing 1640@file{Entries} and @file{Entries.Log} abruptly aborts. 1641Programs which are reading the @file{Entries} file 1642should also check for @file{Entries.Log}. If the latter 1643exists, they should read @file{Entries} and then apply 1644the changes mentioned in @file{Entries.Log}. After 1645applying the changes, the recommended practice is to 1646rewrite @file{Entries} and then delete @file{Entries.Log}. 1647The format of a line in @file{Entries.Log} is a single 1648character command followed by a space followed by a 1649line in the format specified for a line in 1650@file{Entries}. The single character command is 1651@samp{A} to indicate that the entry is being added, 1652@samp{R} to indicate that the entry is being removed, 1653or any other character to indicate that the entire line 1654in @file{Entries.Log} should be silently ignored (for 1655future expansion). If the second character of the line 1656in @file{Entries.Log} is not a space, then it was 1657written by an older version of @sc{cvs} (not documented 1658here). 1659 1660Programs which are writing rather than reading can 1661safely ignore @file{Entries.Log} if they so choose. 1662 1663@cindex Entries.Backup file, in CVS directory 1664@cindex CVS/Entries.Backup file 1665@item Entries.Backup 1666This is a temporary file. Recommended usage is to 1667write a new entries file to @file{Entries.Backup}, and 1668then to rename it (atomically, where possible) to @file{Entries}. 1669 1670@cindex Entries.Static file, in CVS directory 1671@cindex CVS/Entries.Static file 1672@item Entries.Static 1673The only relevant thing about this file is whether it 1674exists or not. If it exists, then it means that only 1675part of a directory was gotten and @sc{cvs} will 1676not create additional files in that directory. To 1677clear it, use the @code{update} command with the 1678@samp{-d} option, which will get the additional files 1679and remove @file{Entries.Static}. 1680@c FIXME: This needs to be better documented, in places 1681@c other than Working Directory Storage. 1682@c FIXCVS: The fact that this setting exists needs to 1683@c be more visible to the user. For example "cvs 1684@c status foo", in the case where the file would be 1685@c gotten except for Entries.Static, might say 1686@c something to distinguish this from other cases. 1687@c One thing that periodically gets suggested is to 1688@c have "cvs update" print something when it skips 1689@c files due to Entries.Static, but IMHO that kind of 1690@c noise pretty much makes the Entries.Static feature 1691@c useless. 1692 1693@cindex Tag file, in CVS directory 1694@cindex CVS/Tag file 1695@cindex Sticky tags/dates, per-directory 1696@cindex Per-directory sticky tags/dates 1697@item Tag 1698This file contains per-directory sticky tags or dates. 1699The first character is @samp{T} for a branch tag, 1700@samp{N} for a non-branch tag, or @samp{D} for a date, 1701or another character to mean the file should be 1702silently ignored, for future expansion. This character 1703is followed by the tag or date. Note that 1704per-directory sticky tags or dates are used for things 1705like applying to files which are newly added; they 1706might not be the same as the sticky tags or dates on 1707individual files. For general information on sticky 1708tags and dates, see @ref{Sticky tags}. 1709@c FIXME: This needs to be much better documented, 1710@c preferably not in the context of "working directory 1711@c storage". 1712@c FIXME: The Sticky tags node needs to discuss, or xref to 1713@c someplace which discusses, per-directory sticky 1714@c tags and the distinction with per-file sticky tags. 1715 1716@cindex Notify file, in CVS directory 1717@cindex CVS/Notify file 1718@item Notify 1719This file stores notifications (for example, for 1720@code{edit} or @code{unedit}) which have not yet been 1721sent to the server. Its format is not yet documented 1722here. 1723 1724@cindex Notify.tmp file, in CVS directory 1725@cindex CVS/Notify.tmp file 1726@item Notify.tmp 1727This file is to @file{Notify} as @file{Entries.Backup} 1728is to @file{Entries}. That is, to write @file{Notify}, 1729first write the new contents to @file{Notify.tmp} and 1730then (atomically where possible), rename it to 1731@file{Notify}. 1732 1733@cindex Base directory, in CVS directory 1734@cindex CVS/Base directory 1735@item Base 1736If watches are in use, then an @code{edit} command 1737stores the original copy of the file in the @file{Base} 1738directory. This allows the @code{unedit} command to 1739operate even if it is unable to communicate with the 1740server. 1741 1742@cindex Baserev file, in CVS directory 1743@cindex CVS/Baserev file 1744@item Baserev 1745The file lists the revision for each of the files in 1746the @file{Base} directory. The format is: 1747 1748@example 1749B@var{name}/@var{rev}/@var{expansion} 1750@end example 1751 1752@noindent 1753where @var{expansion} should be ignored, to allow for 1754future expansion. 1755 1756@cindex Baserev.tmp file, in CVS directory 1757@cindex CVS/Baserev.tmp file 1758@item Baserev.tmp 1759This file is to @file{Baserev} as @file{Entries.Backup} 1760is to @file{Entries}. That is, to write @file{Baserev}, 1761first write the new contents to @file{Baserev.tmp} and 1762then (atomically where possible), rename it to 1763@file{Baserev}. 1764 1765@cindex Template file, in CVS directory 1766@cindex CVS/Template file 1767@item Template 1768This file contains the template specified by the 1769@file{rcsinfo} file (@pxref{rcsinfo}). It is only used 1770by the client; the non-client/server @sc{cvs} consults 1771@file{rcsinfo} directly. 1772@end table 1773 1774@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1775@node Intro administrative files 1776@section The administrative files 1777@cindex Administrative files (intro) 1778@cindex Modules file 1779@cindex CVSROOT, module name 1780@cindex Defining modules (intro) 1781 1782@c FIXME: this node should be reorganized into "general 1783@c information about admin files" and put the "editing 1784@c admin files" stuff up front rather than jumping into 1785@c the details of modules right away. Then the 1786@c Administrative files node can go away, the information 1787@c on each admin file distributed to a place appropriate 1788@c to its function, and this node can contain a table 1789@c listing each file and a @ref to its detailed description. 1790 1791The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative 1792files}. @xref{Administrative files}, for a complete description. 1793You can use @sc{cvs} without any of these files, but 1794some commands work better when at least the 1795@file{modules} file is properly set up. 1796 1797The most important of these files is the @file{modules} 1798file. It defines all modules in the repository. This 1799is a sample @file{modules} file. 1800 1801@c FIXME: The CVSROOT line is a goofy example now that 1802@c mkmodules doesn't exist. 1803@example 1804CVSROOT CVSROOT 1805modules CVSROOT modules 1806cvs gnu/cvs 1807rcs gnu/rcs 1808diff gnu/diff 1809tc yoyodyne/tc 1810@end example 1811 1812The @file{modules} file is line oriented. In its 1813simplest form each line contains the name of the 1814module, whitespace, and the directory where the module 1815resides. The directory is a path relative to 1816@code{$CVSROOT}. The last four lines in the example 1817above are examples of such lines. 1818 1819@c FIXME: might want to introduce the concept of options in modules file 1820@c (the old example which was here, -i mkmodules, is obsolete). 1821 1822The line that defines the module called @samp{modules} 1823uses features that are not explained here. 1824@xref{modules}, for a full explanation of all the 1825available features. 1826 1827@c FIXME: subsection without node is bogus 1828@subsection Editing administrative files 1829@cindex Editing administrative files 1830@cindex Administrative files, editing them 1831 1832You edit the administrative files in the same way that you would edit 1833any other module. Use @samp{cvs checkout CVSROOT} to get a working 1834copy, edit it, and commit your changes in the normal way. 1835 1836It is possible to commit an erroneous administrative 1837file. You can often fix the error and check in a new 1838revision, but sometimes a particularly bad error in the 1839administrative file makes it impossible to commit new 1840revisions. 1841@c @xref{Bad administrative files} for a hint 1842@c about how to solve such situations. 1843@c -- administrative file checking-- 1844 1845@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1846@node Multiple repositories 1847@section Multiple repositories 1848@cindex Multiple repositories 1849@cindex Repositories, multiple 1850@cindex Many repositories 1851@cindex Parallel repositories 1852@cindex Disjoint repositories 1853@cindex CVSROOT, multiple repositories 1854 1855In some situations it is a good idea to have more than 1856one repository, for instance if you have two 1857development groups that work on separate projects 1858without sharing any code. All you have to do to have 1859several repositories is to specify the appropriate 1860repository, using the @code{CVSROOT} environment 1861variable, the @samp{-d} option to @sc{cvs}, or (once 1862you have checked out a working directory) by simply 1863allowing @sc{cvs} to use the repository that was used 1864to check out the working directory 1865(@pxref{Specifying a repository}). 1866 1867The big advantage of having multiple repositories is 1868that they can reside on different servers. With @sc{cvs} 1869version 1.10, a single command cannot recurse into 1870directories from different repositories. With development 1871versions of @sc{cvs}, you can check out code from multiple 1872servers into your working directory. @sc{cvs} will 1873recurse and handle all the details of making 1874connections to as many server machines as necessary to 1875perform the requested command. Here is an example of 1876how to set up a working directory: 1877 1878@example 1879cvs -d server1:/cvs co dir1 1880cd dir1 1881cvs -d server2:/root co sdir 1882cvs update 1883@end example 1884 1885The @code{cvs co} commands set up the working 1886directory, and then the @code{cvs update} command will 1887contact server2, to update the dir1/sdir subdirectory, 1888and server1, to update everything else. 1889 1890@c FIXME: Does the FAQ have more about this? I have a 1891@c dim recollection, but I'm too lazy to check right now. 1892 1893@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1894@node Creating a repository 1895@section Creating a repository 1896 1897@cindex Repository, setting up 1898@cindex Creating a repository 1899@cindex Setting up a repository 1900 1901To set up a @sc{cvs} repository, first choose the 1902machine and disk on which you want to store the 1903revision history of the source files. CPU and memory 1904requirements are modest, so most machines should be 1905adequate. For details see @ref{Server requirements}. 1906@c Possible that we should be providing a quick rule of 1907@c thumb, like the 32M memory for the server. That 1908@c might increase the number of people who are happy 1909@c with the answer, without following the xref. 1910 1911To estimate disk space 1912requirements, if you are importing RCS files from 1913another system, the size of those files is the 1914approximate initial size of your repository, or if you 1915are starting without any version history, a rule of 1916thumb is to allow for the server approximately three 1917times the size of the code to be under @sc{cvs} for the 1918repository (you will eventually outgrow this, but not 1919for a while). On the machines on which the developers 1920will be working, you'll want disk space for 1921approximately one working directory for each developer 1922(either the entire tree or a portion of it, depending 1923on what each developer uses). 1924 1925The repository should be accessible 1926(directly or via a networked file system) from all 1927machines which want to use @sc{cvs} in server or local 1928mode; the client machines need not have any access to 1929it other than via the @sc{cvs} protocol. It is not 1930possible to use @sc{cvs} to read from a repository 1931which one only has read access to; @sc{cvs} needs to be 1932able to create lock files (@pxref{Concurrency}). 1933 1934@cindex init (subcommand) 1935To create a repository, run the @code{cvs init} 1936command. It will set up an empty repository in the 1937@sc{cvs} root specified in the usual way 1938(@pxref{Repository}). For example, 1939 1940@example 1941cvs -d /usr/local/cvsroot init 1942@end example 1943 1944@code{cvs init} is careful to never overwrite any 1945existing files in the repository, so no harm is done if 1946you run @code{cvs init} on an already set-up 1947repository. 1948 1949@code{cvs init} will enable history logging; if you 1950don't want that, remove the history file after running 1951@code{cvs init}. @xref{history file}. 1952 1953@node Backing up 1954@section Backing up a repository 1955@cindex Repository, backing up 1956@cindex Backing up, repository 1957 1958There is nothing particularly magical about the files 1959in the repository; for the most part it is possible to 1960back them up just like any other files. However, there 1961are a few issues to consider. 1962 1963@cindex Locks, cvs, and backups 1964@cindex #cvs.rfl, and backups 1965The first is that to be paranoid, one should either not 1966use @sc{cvs} during the backup, or have the backup 1967program lock @sc{cvs} while doing the backup. To not 1968use @sc{cvs}, you might forbid logins to machines which 1969can access the repository, turn off your @sc{cvs} 1970server, or similar mechanisms. The details would 1971depend on your operating system and how you have 1972@sc{cvs} set up. To lock @sc{cvs}, you would create 1973@file{#cvs.rfl} locks in each repository directory. 1974See @ref{Concurrency}, for more on @sc{cvs} locks. 1975Having said all this, if you just back up without any 1976of these precautions, the results are unlikely to be 1977particularly dire. Restoring from backup, the 1978repository might be in an inconsistent state, but this 1979would not be particularly hard to fix manually. 1980 1981When you restore a repository from backup, assuming 1982that changes in the repository were made after the time 1983of the backup, working directories which were not 1984affected by the failure may refer to revisions which no 1985longer exist in the repository. Trying to run @sc{cvs} 1986in such directories will typically produce an error 1987message. One way to get those changes back into the 1988repository is as follows: 1989 1990@itemize @bullet 1991@item 1992Get a new working directory. 1993 1994@item 1995Copy the files from the working directory from before 1996the failure over to the new working directory (do not 1997copy the contents of the @file{CVS} directories, of 1998course). 1999 2000@item 2001Working in the new working directory, use commands such 2002as @code{cvs update} and @code{cvs diff} to figure out 2003what has changed, and then when you are ready, commit 2004the changes into the repository. 2005@end itemize 2006 2007@node Moving a repository 2008@section Moving a repository 2009@cindex Repository, moving 2010@cindex Moving a repository 2011@cindex Copying a repository 2012 2013Just as backing up the files in the repository is 2014pretty much like backing up any other files, if you 2015need to move a repository from one place to another it 2016is also pretty much like just moving any other 2017collection of files. 2018 2019The main thing to consider is that working directories 2020point to the repository. The simplest way to deal with 2021a moved repository is to just get a fresh working 2022directory after the move. Of course, you'll want to 2023make sure that the old working directory had been 2024checked in before the move, or you figured out some 2025other way to make sure that you don't lose any 2026changes. If you really do want to reuse the existing 2027working directory, it should be possible with manual 2028surgery on the @file{CVS/Repository} files. You can 2029see @ref{Working directory storage}, for information on 2030the @file{CVS/Repository} and @file{CVS/Root} files, but 2031unless you are sure you want to bother, it probably 2032isn't worth it. 2033@c FIXME: Surgery on CVS/Repository should be avoided 2034@c by making RELATIVE_REPOS the default. 2035@c FIXME-maybe: might want some documented way to 2036@c change the CVS/Root files in some particular tree. 2037@c But then again, I don't know, maybe just having 2038@c people do this in perl/shell/&c isn't so bad... 2039 2040@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2041@node Remote repositories 2042@section Remote repositories 2043@cindex Repositories, remote 2044@cindex Remote repositories 2045@cindex Client/Server Operation 2046@cindex Server, CVS 2047@cindex Remote repositories, port specification 2048@cindex Repositories, remote, port specification 2049@cindex Client/Server Operation, port specification 2050@cindex pserver (client/server connection method), port specification 2051@cindex kserver (client/server connection method), port specification 2052@cindex gserver (client/server connection method), port specification 2053@cindex port, specifying for remote repositories 2054 2055 Your working copy of the sources can be on a 2056different machine than the repository. Using @sc{cvs} 2057in this manner is known as @dfn{client/server} 2058operation. You run @sc{cvs} on a machine which can 2059mount your working directory, known as the 2060@dfn{client}, and tell it to communicate to a machine 2061which can mount the repository, known as the 2062@dfn{server}. Generally, using a remote 2063repository is just like using a local one, except that 2064the format of the repository name is: 2065 2066@example 2067[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository 2068@end example 2069 2070Specifying a password in the repository name is not recommended during 2071checkout, since this will cause @sc{cvs} to store a cleartext copy of the 2072password in each created directory. @code{cvs login} first instead 2073(@pxref{Password authentication client}). 2074 2075The details of exactly what needs to be set up depend 2076on how you are connecting to the server. 2077 2078If @var{method} is not specified, and the repository 2079name contains @samp{:}, then the default is @code{ext} 2080or @code{server}, depending on your platform; both are 2081described in @ref{Connecting via rsh}. 2082@c Should we try to explain which platforms are which? 2083@c Platforms like unix and VMS, which only allow 2084@c privileged programs to bind to sockets <1024 lose on 2085@c :server: 2086@c Platforms like Mac and VMS, whose rsh program is 2087@c unusable or nonexistent, lose on :ext: 2088@c Platforms like OS/2 and NT probably could plausibly 2089@c default either way (modulo -b troubles). 2090 2091@c FIXME: We need to have a better way of explaining 2092@c what method to use. This presentation totally 2093@c obscures the fact that :ext: and CVS_RSH is the way to 2094@c use SSH, for example. Plus it incorrectly implies 2095@c that you need an @code{rsh} binary on the client to use 2096@c :server:. 2097@c Also note that rsh not pserver is the right choice if you want 2098@c users to be able to create their own repositories 2099@c (because of the --allow-root related issues). 2100@menu 2101* Server requirements:: Memory and other resources for servers 2102* Connecting via rsh:: Using the @code{rsh} program to connect 2103* Password authenticated:: Direct connections using passwords 2104* GSSAPI authenticated:: Direct connections using GSSAPI 2105* Kerberos authenticated:: Direct connections with kerberos 2106* Connecting via fork:: Using a forked @code{cvs server} to connect 2107@end menu 2108 2109@node Server requirements 2110@subsection Server requirements 2111 2112The quick answer to what sort of machine is suitable as 2113a server is that requirements are modest---a server 2114with 32M of memory or even less can handle a fairly 2115large source tree with a fair amount of activity. 2116@c Say something about CPU speed too? I'm even less sure 2117@c what to say on that subject... 2118 2119The real answer, of course, is more complicated. 2120Estimating the known areas of large memory consumption 2121should be sufficient to estimate memory requirements. 2122There are two such areas documented here; other memory 2123consumption should be small by comparison (if you find 2124that is not the case, let us know, as described in 2125@ref{BUGS}, so we can update this documentation). 2126 2127The first area of big memory consumption is large 2128checkouts, when using the @sc{cvs} server. The server 2129consists of two processes for each client that it is 2130serving. Memory consumption on the child process 2131should remain fairly small. Memory consumption on the 2132parent process, particularly if the network connection 2133to the client is slow, can be expected to grow to 2134slightly more than the size of the sources in a single 2135directory, or two megabytes, whichever is larger. 2136@c "two megabytes" of course is SERVER_HI_WATER. But 2137@c we don't mention that here because we are 2138@c documenting the default configuration of CVS. If it 2139@c is a "standard" thing to change that value, it 2140@c should be some kind of run-time configuration. 2141@c 2142@c See cvsclient.texi for more on the design decision 2143@c to not have locks in place while waiting for the 2144@c client, which is what results in memory consumption 2145@c as high as this. 2146 2147Multiplying the size of each @sc{cvs} server by the 2148number of servers which you expect to have active at 2149one time should give an idea of memory requirements for 2150the server. For the most part, the memory consumed by 2151the parent process probably can be swap space rather 2152than physical memory. 2153@c Has anyone verified that notion about swap space? 2154@c I say it based pretty much on guessing that the 2155@c ->text of the struct buffer_data only gets accessed 2156@c in a first in, first out fashion, but I haven't 2157@c looked very closely. 2158 2159@c What about disk usage in /tmp on the server? I think that 2160@c it can be substantial, but I haven't looked at this 2161@c again and tried to figure it out ("cvs import" is 2162@c probably the worst case...). 2163 2164The second area of large memory consumption is 2165@code{diff}, when checking in large files. This is 2166required even for binary files. The rule of thumb is 2167to allow about ten times the size of the largest file 2168you will want to check in, although five times may be 2169adequate. For example, if you want to check in a file 2170which is 10 megabytes, you should have 100 megabytes of 2171memory on the machine doing the checkin (the server 2172machine for client/server, or the machine running 2173@sc{cvs} for non-client/server). This can be swap 2174space rather than physical memory. Because the memory 2175is only required briefly, there is no particular need 2176to allow memory for more than one such checkin at a 2177time. 2178@c The 5-10 times rule of thumb is from Paul Eggert for 2179@c GNU diff. I don't think it is in the GNU diff 2180@c manual or anyplace like that. 2181@c 2182@c Probably we could be saying more about 2183@c non-client/server CVS. 2184@c I would guess for non-client/server CVS in an NFS 2185@c environment the biggest issues are the network and 2186@c the NFS server. 2187 2188Resource consumption for the client is even more 2189modest---any machine with enough capacity to run the 2190operating system in question should have little 2191trouble. 2192@c Is that true? I think the client still wants to 2193@c (bogusly) store entire files in memory at times. 2194 2195For information on disk space requirements, see 2196@ref{Creating a repository}. 2197 2198@node Connecting via rsh 2199@subsection Connecting with rsh 2200 2201@cindex rsh 2202@sc{cvs} uses the @samp{rsh} protocol to perform these 2203operations, so the remote user host needs to have a 2204@file{.rhosts} file which grants access to the local 2205user. Note that the program that @sc{cvs} uses for this 2206purpose may be specified using the @file{--with-rsh} 2207flag to configure. 2208 2209For example, suppose you are the user @samp{mozart} on 2210the local machine @samp{toe.example.com}, and the 2211server machine is @samp{faun.example.org}. On 2212faun, put the following line into the file 2213@file{.rhosts} in @samp{bach}'s home directory: 2214 2215@example 2216toe.example.com mozart 2217@end example 2218 2219@noindent 2220Then test that @samp{rsh} is working with 2221 2222@example 2223rsh -l bach faun.example.org 'echo $PATH' 2224@end example 2225 2226@cindex CVS_SERVER, environment variable 2227Next you have to make sure that @code{rsh} will be able 2228to find the server. Make sure that the path which 2229@code{rsh} printed in the above example includes the 2230directory containing a program named @code{cvs} which 2231is the server. You need to set the path in 2232@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} 2233or @file{.profile}. Alternately, you can set the 2234environment variable @code{CVS_SERVER} on the client 2235machine to the filename of the server you want to use, 2236for example @file{/usr/local/bin/cvs-1.6}. 2237@c FIXME: there should be a way to specify the 2238@c program in CVSROOT, not CVS_SERVER, so that one can use 2239@c different ones for different roots. e.g. ":server;cvs=cvs-1.6:" 2240@c instead of ":server:". 2241 2242There is no need to edit @file{inetd.conf} or start a 2243@sc{cvs} server daemon. 2244 2245@cindex :server:, setting up 2246@cindex :ext:, setting up 2247@cindex Kerberos, using kerberized rsh 2248@cindex SSH (rsh replacement) 2249@cindex rsh replacements (Kerberized, SSH, &c) 2250There are two access methods that you use in @code{CVSROOT} 2251for rsh. @code{:server:} specifies an internal rsh 2252client, which is supported only by some @sc{cvs} ports. 2253@code{:ext:} specifies an external rsh program. By 2254default this is @code{rsh} (unless otherwise specified 2255by the @file{--with-rsh} flag to configure) but you may set the 2256@code{CVS_RSH} environment variable to invoke another 2257program which can access the remote server (for 2258example, @code{remsh} on HP-UX 9 because @code{rsh} is 2259something different). It must be a program which can 2260transmit data to and from the server without modifying 2261it; for example the Windows NT @code{rsh} is not 2262suitable since it by default translates between CRLF 2263and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b} 2264to @code{rsh} to get around this, but since this could 2265potentially cause problems for programs other than the 2266standard @code{rsh}, it may change in the future. If 2267you set @code{CVS_RSH} to @code{SSH} or some other rsh 2268replacement, the instructions in the rest of this 2269section concerning @file{.rhosts} and so on are likely 2270to be inapplicable; consult the documentation for your rsh 2271replacement. 2272@c FIXME: there should be a way to specify the 2273@c program in CVSROOT, not CVS_RSH, so that one can use 2274@c different ones for different roots. e.g. ":ext;rsh=remsh:" 2275@c instead of ":ext:". 2276@c See also the comment in src/client.c for rationale 2277@c concerning "rsh" being the default and never 2278@c "remsh". 2279 2280Continuing our example, supposing you want to access 2281the module @file{foo} in the repository 2282@file{/usr/local/cvsroot/}, on machine 2283@file{faun.example.org}, you are ready to go: 2284 2285@example 2286cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2287@end example 2288 2289@noindent 2290(The @file{bach@@} can be omitted if the username is 2291the same on both the local and remote hosts.) 2292 2293@c Should we mention "rsh host echo hi" and "rsh host 2294@c cat" (the latter followed by typing text and ^D) 2295@c as troubleshooting techniques? Probably yes 2296@c (people tend to have trouble setting this up), 2297@c but this kind of thing can be hard to spell out. 2298 2299@node Password authenticated 2300@subsection Direct connection with password authentication 2301 2302The @sc{cvs} client can also connect to the server 2303using a password protocol. This is particularly useful 2304if using @code{rsh} is not feasible (for example, 2305the server is behind a firewall), and Kerberos also is 2306not available. 2307 2308 To use this method, it is necessary to make 2309some adjustments on both the server and client sides. 2310 2311@menu 2312* Password authentication server:: Setting up the server 2313* Password authentication client:: Using the client 2314* Password authentication security:: What this method does and does not do 2315@end menu 2316 2317@node Password authentication server 2318@subsubsection Setting up the server for password authentication 2319 2320First of all, you probably want to tighten the 2321permissions on the @file{$CVSROOT} and 2322@file{$CVSROOT/CVSROOT} directories. See @ref{Password 2323authentication security}, for more details. 2324 2325@cindex pserver (subcommand) 2326@cindex Remote repositories, port specification 2327@cindex Repositories, remote, port specification 2328@cindex Client/Server Operation, port specification 2329@cindex pserver (client/server connection method), port specification 2330@cindex kserver (client/server connection method), port specification 2331@cindex gserver (client/server connection method), port specification 2332@cindex port, specifying for remote repositories 2333@cindex Password server, setting up 2334@cindex Authenticating server, setting up 2335@cindex inetd, configuring for pserver 2336@cindex xinetd, configuring for pserver 2337@c FIXME: this isn't quite right regarding port 2338@c numbers; CVS looks up "cvspserver" in 2339@c /etc/services (on unix, but what about non-unix?). 2340On the server side, the file @file{/etc/inetd.conf} 2341needs to be edited so @code{inetd} knows to run the 2342command @code{cvs pserver} when it receives a 2343connection on the right port. By default, the port 2344number is 2401; it would be different if your client 2345were compiled with @code{CVS_AUTH_PORT} defined to 2346something else, though. This can also be specified in the CVSROOT variable 2347(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT 2348environment variable (@pxref{Environment variables}). 2349 2350 If your @code{inetd} allows raw port numbers in 2351@file{/etc/inetd.conf}, then the following (all on a 2352single line in @file{inetd.conf}) should be sufficient: 2353 2354@example 23552401 stream tcp nowait root /usr/local/bin/cvs 2356cvs -f --allow-root=/usr/cvsroot pserver 2357@end example 2358 2359@noindent 2360(You could also use the 2361@samp{-T} option to specify a temporary directory.) 2362 2363The @samp{--allow-root} option specifies the allowable 2364@sc{cvsroot} directory. Clients which attempt to use a 2365different @sc{cvsroot} directory will not be allowed to 2366connect. If there is more than one @sc{cvsroot} 2367directory which you want to allow, repeat the option. 2368(Unfortunately, many versions of @code{inetd} have very small 2369limits on the number of arguments and/or the total length 2370of the command. The usual solution to this problem is 2371to have @code{inetd} run a shell script which then invokes 2372@sc{cvs} with the necessary arguments.) 2373 2374 If your @code{inetd} wants a symbolic service 2375name instead of a raw port number, then put this in 2376@file{/etc/services}: 2377 2378@example 2379cvspserver 2401/tcp 2380@end example 2381 2382@noindent 2383and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}. 2384 2385If your system uses @code{xinetd} instead of @code{inetd}, 2386the procedure is slightly different. 2387Create a file called @file{/etc/xinetd.d/cvspserver} containing the following: 2388 2389@example 2390service cvspserver 2391@{ 2392 port = 2401 2393 socket_type = stream 2394 protocol = tcp 2395 wait = no 2396 user = root 2397 passenv = PATH 2398 server = /usr/local/bin/cvs 2399 server_args = -f --allow-root=/usr/cvsroot pserver 2400@} 2401@end example 2402 2403@noindent 2404(If @code{cvspserver} is defined in @file{/etc/services}, you can omit 2405the @code{port} line.) 2406 2407 Once the above is taken care of, restart your 2408@code{inetd}, or do whatever is necessary to force it 2409to reread its initialization files. 2410 2411If you are having trouble setting this up, see 2412@ref{Connection}. 2413 2414@cindex CVS passwd file 2415@cindex passwd (admin file) 2416Because the client stores and transmits passwords in 2417cleartext (almost---see @ref{Password authentication 2418security}, for details), a separate @sc{cvs} password 2419file is generally used, so people don't compromise 2420their regular passwords when they access the 2421repository. This file is 2422@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro 2423administrative files}). It uses a colon-separated 2424format, similar to @file{/etc/passwd} on Unix systems, 2425except that it has fewer fields: @sc{cvs} username, 2426optional password, and an optional system username for 2427@sc{cvs} to run as if authentication succeeds. Here is 2428an example @file{passwd} file with five entries: 2429 2430@example 2431anonymous: 2432bach:ULtgRLXo7NRxs 2433spwang:1sOp854gDF3DY 2434melissa:tGX1fS8sun6rY:pubcvs 2435qproj:XR4EZcEs0szik:pubcvs 2436@end example 2437 2438@noindent 2439(The passwords are encrypted according to the standard 2440Unix @code{crypt()} function, so it is possible to 2441paste in passwords directly from regular Unix 2442@file{/etc/passwd} files.) 2443 2444The first line in the example will grant access to any 2445@sc{cvs} client attempting to authenticate as user 2446@code{anonymous}, no matter what password they use, 2447including an empty password. (This is typical for 2448sites granting anonymous read-only access; for 2449information on how to do the "read-only" part, see 2450@ref{Read-only access}.) 2451 2452The second and third lines will grant access to 2453@code{bach} and @code{spwang} if they supply their 2454respective plaintext passwords. 2455 2456@cindex User aliases 2457The fourth line will grant access to @code{melissa}, if 2458she supplies the correct password, but her @sc{cvs} 2459operations will actually run on the server side under 2460the system user @code{pubcvs}. Thus, there need not be 2461any system user named @code{melissa}, but there 2462@emph{must} be one named @code{pubcvs}. 2463 2464The fifth line shows that system user identities can be 2465shared: any client who successfully authenticates as 2466@code{qproj} will actually run as @code{pubcvs}, just 2467as @code{melissa} does. That way you could create a 2468single, shared system user for each project in your 2469repository, and give each developer their own line in 2470the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs} 2471username on each line would be different, but the 2472system username would be the same. The reason to have 2473different @sc{cvs} usernames is that @sc{cvs} will log their 2474actions under those names: when @code{melissa} commits 2475a change to a project, the checkin is recorded in the 2476project's history under the name @code{melissa}, not 2477@code{pubcvs}. And the reason to have them share a 2478system username is so that you can arrange permissions 2479in the relevant area of the repository such that only 2480that account has write-permission there. 2481 2482If the system-user field is present, all 2483password-authenticated @sc{cvs} commands run as that 2484user; if no system user is specified, @sc{cvs} simply 2485takes the @sc{cvs} username as the system username and 2486runs commands as that user. In either case, if there 2487is no such user on the system, then the @sc{cvs} 2488operation will fail (regardless of whether the client 2489supplied a valid password). 2490 2491The password and system-user fields can both be omitted 2492(and if the system-user field is omitted, then also 2493omit the colon that would have separated it from the 2494encrypted password). For example, this would be a 2495valid @file{$CVSROOT/CVSROOT/passwd} file: 2496 2497@example 2498anonymous::pubcvs 2499fish:rKa5jzULzmhOo:kfogel 2500sussman:1sOp854gDF3DY 2501@end example 2502 2503@noindent 2504When the password field is omitted or empty, then the 2505client's authentication attempt will succeed with any 2506password, including the empty string. However, the 2507colon after the @sc{cvs} username is always necessary, 2508even if the password is empty. 2509 2510@sc{cvs} can also fall back to use system authentication. 2511When authenticating a password, the server first checks 2512for the user in the @file{$CVSROOT/CVSROOT/passwd} 2513file. If it finds the user, it will use that entry for 2514authentication as described above. But if it does not 2515find the user, or if the @sc{cvs} @file{passwd} file 2516does not exist, then the server can try to authenticate 2517the username and password using the operating system's 2518user-lookup routines (this "fallback" behavior can be 2519disabled by setting @code{SystemAuth=no} in the 2520@sc{cvs} @file{config} file, @pxref{config}). 2521 2522The default fallback behaviour is to look in 2523@file{/etc/passwd} for this system password unless your 2524system has PAM (Pluggable Authentication Modules) 2525and your @sc{cvs} server executable was configured to 2526use it at compile time (using @code{./configure --enable-pam} - see the 2527INSTALL file for more). In this case, PAM will be consulted instead. 2528This means that @sc{cvs} can be configured to use any password 2529authentication source PAM can be configured to use (possibilities 2530include a simple UNIX password, NIS, LDAP, and others) in its 2531global configuration file (usually @file{/etc/pam.conf} 2532or possibly @file{/etc/pam.d/cvs}). See your PAM documentation 2533for more details on PAM configuration. 2534 2535Note that PAM is an experimental feature in @sc{cvs} and feedback is 2536encouraged. Please send a mail to one of the @sc{cvs} mailing lists 2537(@code{info-cvs@@gnu.org} or @code{bug-cvs@@gnu.org}) if you use the 2538@sc{cvs} PAM support. 2539 2540@strong{WARNING: Using PAM gives the system administrator much more 2541flexibility about how @sc{cvs} users are authenticated but 2542no more security than other methods. See below for more.} 2543 2544CVS needs an "auth" and "account" module in the 2545PAM configuration file. A typical PAM configuration 2546would therefore have the following lines 2547in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 2548system @file{/etc/passwd} authentication: 2549 2550@example 2551cvs auth required pam_unix.so 2552cvs account required pam_unix.so 2553@end example 2554 2555The the equivalent @file{/etc/pam.d/cvs} would contain 2556 2557@example 2558auth required pam_unix.so 2559account required pam_unix.so 2560@end example 2561 2562Some systems require a full path to the module so that 2563@file{pam_unix.so} (Linux) would become something like 2564@file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris). 2565See the @file{contrib/pam} subdirectory of the @sc{cvs} 2566source distribution for further example configurations. 2567 2568The PAM service name given above as "cvs" is just 2569the service name in the default configuration amd can be 2570set using 2571@code{./configure --with-hardcoded-pam-service-name=<pam-service-name>} 2572before compiling. @sc{cvs} can also be configured to use whatever 2573name it is invoked as as its PAM service name using 2574@code{./configure --without-hardcoded-pam-service-name}, but this 2575feature should not be used if you may not have control of the name 2576@sc{cvs} will be invoked as. 2577 2578Be aware, also, that falling back to system 2579authentication might be a security risk: @sc{cvs} 2580operations would then be authenticated with that user's 2581regular login password, and the password flies across 2582the network in plaintext. See @ref{Password 2583authentication security} for more on this. 2584This may be more of a problem with PAM authentication 2585because it is likely that the source of the system 2586password is some central authentication service like 2587LDAP which is also used to authenticate other services. 2588 2589On the other hand, PAM makes it very easy to change your password 2590regularly. If they are given the option of a one-password system for 2591all of their activities, users are often more willing to change their 2592password on a regular basis. 2593 2594In the non-PAM configuration where the password is stored in the 2595@file{CVSROOT/passwd} file, it is difficult to change passwords on a 2596regular basis since only administrative users (or in some cases 2597processes that act as an administrative user) are typicaly given 2598access to modify this file. Either there needs to be some 2599hand-crafted web page or set-uid program to update the file, or the 2600update needs to be done by submitting a request to an administrator to 2601perform the duty by hand. In the first case, having to remember to 2602update a separate password on a periodic basis can be difficult. In 2603the second case, the manual nature of the change will typically mean 2604that the password will not be changed unless it is absolutely 2605necessary. 2606 2607Note that PAM administrators should probably avoid configuring 2608one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If 2609OTPs are desired, the administrator may wish to encourage the use of 2610one of the other Client/Server access methods. See the section on 2611@pxref{Remote repositories} for a list of other methods. 2612 2613Right now, the only way to put a password in the 2614@sc{cvs} @file{passwd} file is to paste it there from 2615somewhere else. Someday, there may be a @code{cvs 2616passwd} command. 2617 2618Unlike many of the files in @file{$CVSROOT/CVSROOT}, it 2619is normal to edit the @file{passwd} file in-place, 2620rather than via @sc{cvs}. This is because of the 2621possible security risks of having the @file{passwd} 2622file checked out to people's working copies. If you do 2623want to include the @file{passwd} file in checkouts of 2624@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}. 2625 2626@c We might also suggest using the @code{htpasswd} command 2627@c from freely available web servers as well, but that 2628@c would open up a can of worms in that the users next 2629@c questions are likely to be "where do I get it?" and 2630@c "how do I use it?" 2631@c Also note that htpasswd, at least the version I had, 2632@c likes to clobber the third field. 2633 2634@node Password authentication client 2635@subsubsection Using the client with password authentication 2636@cindex Login (subcommand) 2637@cindex Password client, using 2638@cindex Authenticated client, using 2639@cindex :pserver:, setting up 2640To run a @sc{cvs} command on a remote repository via 2641the password-authenticating server, one specifies the 2642@code{pserver} protocol, optional username, repository host, an 2643optional port number, and path to the repository. For example: 2644 2645@example 2646cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj 2647@end example 2648 2649@noindent 2650or 2651 2652@example 2653CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot 2654cvs checkout someproj 2655@end example 2656 2657However, unless you're connecting to a public-access 2658repository (i.e., one where that username doesn't 2659require a password), you'll need to supply a password or @dfn{log in} first. 2660Logging in verifies your password with the repository and stores it in a file. 2661It's done with the @code{login} command, which will 2662prompt you interactively for the password if you didn't supply one as part of 2663@var{$CVSROOT}: 2664 2665@example 2666cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login 2667CVS password: 2668@end example 2669 2670@noindent 2671or 2672 2673@example 2674cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login 2675@end example 2676 2677After you enter the password, @sc{cvs} verifies it with 2678the server. If the verification succeeds, then that 2679combination of username, host, repository, and password 2680is permanently recorded, so future transactions with 2681that repository won't require you to run @code{cvs 2682login}. (If verification fails, @sc{cvs} will exit 2683complaining that the password was incorrect, and 2684nothing will be recorded.) 2685 2686The records are stored, by default, in the file 2687@file{$HOME/.cvspass}. That file's format is 2688human-readable, and to a degree human-editable, but 2689note that the passwords are not stored in 2690cleartext---they are trivially encoded to protect them 2691from "innocent" compromise (i.e., inadvertent viewing 2692by a system administrator or other non-malicious 2693person). 2694 2695@cindex CVS_PASSFILE, environment variable 2696You can change the default location of this file by 2697setting the @code{CVS_PASSFILE} environment variable. 2698If you use this variable, make sure you set it 2699@emph{before} @code{cvs login} is run. If you were to 2700set it after running @code{cvs login}, then later 2701@sc{cvs} commands would be unable to look up the 2702password for transmission to the server. 2703 2704Once you have logged in, all @sc{cvs} commands using 2705that remote repository and username will authenticate 2706with the stored password. So, for example 2707 2708@example 2709cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo 2710@end example 2711 2712@noindent 2713should just work (unless the password changes on the 2714server side, in which case you'll have to re-run 2715@code{cvs login}). 2716 2717Note that if the @samp{:pserver:} were not present in 2718the repository specification, @sc{cvs} would assume it 2719should use @code{rsh} to connect with the server 2720instead (@pxref{Connecting via rsh}). 2721 2722Of course, once you have a working copy checked out and 2723are running @sc{cvs} commands from within it, there is 2724no longer any need to specify the repository 2725explicitly, because @sc{cvs} can deduce the repository 2726from the working copy's @file{CVS} subdirectory. 2727 2728@c FIXME: seems to me this needs somewhat more 2729@c explanation. 2730@cindex Logout (subcommand) 2731The password for a given remote repository can be 2732removed from the @code{CVS_PASSFILE} by using the 2733@code{cvs logout} command. 2734 2735@node Password authentication security 2736@subsubsection Security considerations with password authentication 2737 2738@cindex Security, of pserver 2739The passwords are stored on the client side in a 2740trivial encoding of the cleartext, and transmitted in 2741the same encoding. The encoding is done only to 2742prevent inadvertent password compromises (i.e., a 2743system administrator accidentally looking at the file), 2744and will not prevent even a naive attacker from gaining 2745the password. 2746 2747@c FIXME: The bit about "access to the repository 2748@c implies general access to the system is *not* specific 2749@c to pserver; it applies to kerberos and SSH and 2750@c everything else too. Should reorganize the 2751@c documentation to make this clear. 2752The separate @sc{cvs} password file (@pxref{Password 2753authentication server}) allows people 2754to use a different password for repository access than 2755for login access. On the other hand, once a user has 2756non-read-only 2757access to the repository, she can execute programs on 2758the server system through a variety of means. Thus, repository 2759access implies fairly broad system access as well. It 2760might be possible to modify @sc{cvs} to prevent that, 2761but no one has done so as of this writing. 2762@c OpenBSD uses chroot() and copies the repository to 2763@c provide anonymous read-only access (for details see 2764@c http://www.openbsd.org/anoncvs.shar). While this 2765@c closes the most obvious holes, I'm not sure it 2766@c closes enough holes to recommend it (plus it is 2767@c *very* easy to accidentally screw up a setup of this 2768@c type). 2769 2770Note that because the @file{$CVSROOT/CVSROOT} directory 2771contains @file{passwd} and other files which are used 2772to check security, you must control the permissions on 2773this directory as tightly as the permissions on 2774@file{/etc}. The same applies to the @file{$CVSROOT} 2775directory itself and any directory 2776above it in the tree. Anyone who has write access to 2777such a directory will have the ability to become any 2778user on the system. Note that these permissions are 2779typically tighter than you would use if you are not 2780using pserver. 2781@c TODO: Would be really nice to document/implement a 2782@c scheme where the CVS server can run as some non-root 2783@c user, e.g. "cvs". CVSROOT/passwd would contain a 2784@c bunch of entries of the form foo:xxx:cvs (or the "cvs" 2785@c would be implicit). This would greatly reduce 2786@c security risks such as those hinted at in the 2787@c previous paragraph. I think minor changes to CVS 2788@c might be required but mostly this would just need 2789@c someone who wants to play with it, document it, &c. 2790 2791In summary, anyone who gets the password gets 2792repository access (which may imply some measure of general system 2793access as well). The password is available to anyone 2794who can sniff network packets or read a protected 2795(i.e., user read-only) file. If you want real 2796security, get Kerberos. 2797 2798@node GSSAPI authenticated 2799@subsection Direct connection with GSSAPI 2800 2801@cindex GSSAPI 2802@cindex Security, GSSAPI 2803@cindex :gserver:, setting up 2804@cindex Kerberos, using :gserver: 2805GSSAPI is a generic interface to network security 2806systems such as Kerberos 5. 2807If you have a working GSSAPI library, you can have 2808@sc{cvs} connect via a direct @sc{tcp} connection, 2809authenticating with GSSAPI. 2810 2811To do this, @sc{cvs} needs to be compiled with GSSAPI 2812support; when configuring @sc{cvs} it tries to detect 2813whether GSSAPI libraries using kerberos version 5 are 2814present. You can also use the @file{--with-gssapi} 2815flag to configure. 2816 2817The connection is authenticated using GSSAPI, but the 2818message stream is @emph{not} authenticated by default. 2819You must use the @code{-a} global option to request 2820stream authentication. 2821 2822The data transmitted is @emph{not} encrypted by 2823default. Encryption support must be compiled into both 2824the client and the server; use the 2825@file{--enable-encrypt} configure option to turn it on. 2826You must then use the @code{-x} global option to 2827request encryption. 2828 2829GSSAPI connections are handled on the server side by 2830the same server which handles the password 2831authentication server; see @ref{Password authentication 2832server}. If you are using a GSSAPI mechanism such as 2833Kerberos which provides for strong authentication, you 2834will probably want to disable the ability to 2835authenticate via cleartext passwords. To do so, create 2836an empty @file{CVSROOT/passwd} password file, and set 2837@code{SystemAuth=no} in the config file 2838(@pxref{config}). 2839 2840The GSSAPI server uses a principal name of 2841cvs/@var{hostname}, where @var{hostname} is the 2842canonical name of the server host. You will have to 2843set this up as required by your GSSAPI mechanism. 2844 2845To connect using GSSAPI, use @samp{:gserver:}. For 2846example, 2847 2848@example 2849cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo 2850@end example 2851 2852@node Kerberos authenticated 2853@subsection Direct connection with kerberos 2854 2855@cindex Kerberos, using :kserver: 2856@cindex Security, kerberos 2857@cindex :kserver:, setting up 2858The easiest way to use kerberos is to use the kerberos 2859@code{rsh}, as described in @ref{Connecting via rsh}. 2860The main disadvantage of using rsh is that all the data 2861needs to pass through additional programs, so it may be 2862slower. So if you have kerberos installed you can 2863connect via a direct @sc{tcp} connection, 2864authenticating with kerberos. 2865 2866This section concerns the kerberos network security 2867system, version 4. Kerberos version 5 is supported via 2868the GSSAPI generic network security interface, as 2869described in the previous section. 2870 2871To do this, @sc{cvs} needs to be compiled with kerberos 2872support; when configuring @sc{cvs} it tries to detect 2873whether kerberos is present or you can use the 2874@file{--with-krb4} flag to configure. 2875 2876The data transmitted is @emph{not} encrypted by 2877default. Encryption support must be compiled into both 2878the client and server; use the 2879@file{--enable-encryption} configure option to turn it 2880on. You must then use the @code{-x} global option to 2881request encryption. 2882 2883@cindex CVS_CLIENT_PORT 2884You need to edit @file{inetd.conf} on the server 2885machine to run @code{cvs kserver}. The client uses 2886port 1999 by default; if you want to use another port 2887specify it in the @code{CVSROOT} (@pxref{Remote repositories}) 2888or the @code{CVS_CLIENT_PORT} environment variable 2889(@pxref{Environment variables}) on the client. 2890 2891@cindex kinit 2892When you want to use @sc{cvs}, get a ticket in the 2893usual way (generally @code{kinit}); it must be a ticket 2894which allows you to log into the server machine. Then 2895you are ready to go: 2896 2897@example 2898cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo 2899@end example 2900 2901Previous versions of @sc{cvs} would fall back to a 2902connection via rsh; this version will not do so. 2903 2904@node Connecting via fork 2905@subsection Connecting with fork 2906 2907@cindex fork, access method 2908@cindex :fork:, setting up 2909This access method allows you to connect to a 2910repository on your local disk via the remote protocol. 2911In other words it does pretty much the same thing as 2912@code{:local:}, but various quirks, bugs and the like are 2913those of the remote @sc{cvs} rather than the local 2914@sc{cvs}. 2915 2916For day-to-day operations you might prefer either 2917@code{:local:} or @code{:fork:}, depending on your 2918preferences. Of course @code{:fork:} comes in 2919particularly handy in testing or 2920debugging @code{cvs} and the remote protocol. 2921Specifically, we avoid all of the network-related 2922setup/configuration, timeouts, and authentication 2923inherent in the other remote access methods but still 2924create a connection which uses the remote protocol. 2925 2926To connect using the @code{fork} method, use 2927@samp{:fork:} and the pathname to your local 2928repository. For example: 2929 2930@example 2931cvs -d :fork:/usr/local/cvsroot checkout foo 2932@end example 2933 2934@cindex CVS_SERVER, and :fork: 2935As with @code{:ext:}, the server is called @samp{cvs} 2936by default, or the value of the @code{CVS_SERVER} 2937environment variable. 2938 2939@c --------------------------------------------------------------------- 2940@node Read-only access 2941@section Read-only repository access 2942@cindex Read-only repository access 2943@cindex readers (admin file) 2944@cindex writers (admin file) 2945 2946 It is possible to grant read-only repository 2947access to people using the password-authenticated 2948server (@pxref{Password authenticated}). (The 2949other access methods do not have explicit support for 2950read-only users because those methods all assume login 2951access to the repository machine anyway, and therefore 2952the user can do whatever local file permissions allow 2953her to do.) 2954 2955 A user who has read-only access can do only 2956those @sc{cvs} operations which do not modify the 2957repository, except for certain ``administrative'' files 2958(such as lock files and the history file). It may be 2959desirable to use this feature in conjunction with 2960user-aliasing (@pxref{Password authentication server}). 2961 2962Unlike with previous versions of @sc{cvs}, read-only 2963users should be able merely to read the repository, and 2964not to execute programs on the server or otherwise gain 2965unexpected levels of access. Or to be more accurate, 2966the @emph{known} holes have been plugged. Because this 2967feature is new and has not received a comprehensive 2968security audit, you should use whatever level of 2969caution seems warranted given your attitude concerning 2970security. 2971 2972 There are two ways to specify read-only access 2973for a user: by inclusion, and by exclusion. 2974 2975 "Inclusion" means listing that user 2976specifically in the @file{$CVSROOT/CVSROOT/readers} 2977file, which is simply a newline-separated list of 2978users. Here is a sample @file{readers} file: 2979 2980@example 2981melissa 2982splotnik 2983jrandom 2984@end example 2985 2986@noindent 2987 (Don't forget the newline after the last user.) 2988 2989 "Exclusion" means explicitly listing everyone 2990who has @emph{write} access---if the file 2991 2992@example 2993$CVSROOT/CVSROOT/writers 2994@end example 2995 2996@noindent 2997exists, then only 2998those users listed in it have write access, and 2999everyone else has read-only access (of course, even the 3000read-only users still need to be listed in the 3001@sc{cvs} @file{passwd} file). The 3002@file{writers} file has the same format as the 3003@file{readers} file. 3004 3005 Note: if your @sc{cvs} @file{passwd} 3006file maps cvs users onto system users (@pxref{Password 3007authentication server}), make sure you deny or grant 3008read-only access using the @emph{cvs} usernames, not 3009the system usernames. That is, the @file{readers} and 3010@file{writers} files contain cvs usernames, which may 3011or may not be the same as system usernames. 3012 3013 Here is a complete description of the server's 3014behavior in deciding whether to grant read-only or 3015read-write access: 3016 3017 If @file{readers} exists, and this user is 3018listed in it, then she gets read-only access. Or if 3019@file{writers} exists, and this user is NOT listed in 3020it, then she also gets read-only access (this is true 3021even if @file{readers} exists but she is not listed 3022there). Otherwise, she gets full read-write access. 3023 3024 Of course there is a conflict if the user is 3025listed in both files. This is resolved in the more 3026conservative way, it being better to protect the 3027repository too much than too little: such a user gets 3028read-only access. 3029 3030@node Server temporary directory 3031@section Temporary directories for the server 3032@cindex Temporary directories, and server 3033@cindex Server, temporary directories 3034 3035While running, the @sc{cvs} server creates temporary 3036directories. They are named 3037 3038@example 3039cvs-serv@var{pid} 3040@end example 3041 3042@noindent 3043where @var{pid} is the process identification number of 3044the server. 3045They are located in the directory specified by 3046the @samp{-T} global option (@pxref{Global options}), 3047the @code{TMPDIR} environment variable (@pxref{Environment variables}), 3048or, failing that, @file{/tmp}. 3049 3050In most cases the server will remove the temporary 3051directory when it is done, whether it finishes normally 3052or abnormally. However, there are a few cases in which 3053the server does not or cannot remove the temporary 3054directory, for example: 3055 3056@itemize @bullet 3057@item 3058If the server aborts due to an internal server error, 3059it may preserve the directory to aid in debugging 3060 3061@item 3062If the server is killed in a way that it has no way of 3063cleaning up (most notably, @samp{kill -KILL} on unix). 3064 3065@item 3066If the system shuts down without an orderly shutdown, 3067which tells the server to clean up. 3068@end itemize 3069 3070In cases such as this, you will need to manually remove 3071the @file{cvs-serv@var{pid}} directories. As long as 3072there is no server running with process identification 3073number @var{pid}, it is safe to do so. 3074 3075@c --------------------------------------------------------------------- 3076@node Starting a new project 3077@chapter Starting a project with CVS 3078@cindex Starting a project with CVS 3079@cindex Creating a project 3080 3081@comment --moduledb-- 3082Because renaming files and moving them between 3083directories is somewhat inconvenient, the first thing 3084you do when you start a new project should be to think 3085through your file organization. It is not impossible 3086to rename or move files, but it does increase the 3087potential for confusion and @sc{cvs} does have some 3088quirks particularly in the area of renaming 3089directories. @xref{Moving files}. 3090 3091What to do next depends on the situation at hand. 3092 3093@menu 3094* Setting up the files:: Getting the files into the repository 3095* Defining the module:: How to make a module of the files 3096@end menu 3097@c -- File permissions! 3098 3099@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3100@node Setting up the files 3101@section Setting up the files 3102 3103The first step is to create the files inside the repository. This can 3104be done in a couple of different ways. 3105 3106@c -- The contributed scripts 3107@menu 3108* From files:: This method is useful with old projects 3109 where files already exists. 3110* From other version control systems:: Old projects where you want to 3111 preserve history from another system. 3112* From scratch:: Creating a directory tree from scratch. 3113@end menu 3114 3115@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3116@node From files 3117@subsection Creating a directory tree from a number of files 3118@cindex Importing files 3119 3120When you begin using @sc{cvs}, you will probably already have several 3121projects that can be 3122put under @sc{cvs} control. In these cases the easiest way is to use the 3123@code{import} command. An example is probably the easiest way to 3124explain how to use it. If the files you want to install in 3125@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the 3126repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this: 3127 3128@example 3129$ cd @var{wdir} 3130$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start 3131@end example 3132 3133Unless you supply a log message with the @samp{-m} 3134flag, @sc{cvs} starts an editor and prompts for a 3135message. The string @samp{yoyo} is a @dfn{vendor tag}, 3136and @samp{start} is a @dfn{release tag}. They may fill 3137no purpose in this context, but since @sc{cvs} requires 3138them they must be present. @xref{Tracking sources}, for 3139more information about them. 3140 3141You can now verify that it worked, and remove your 3142original source directory. 3143@c FIXME: Need to say more about "verify that it 3144@c worked". What should the user look for in the output 3145@c from "diff -r"? 3146 3147@example 3148$ cd .. 3149$ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below} 3150$ diff -r @var{wdir} yoyodyne/@var{rdir} 3151$ rm -r @var{wdir} 3152@end example 3153 3154@noindent 3155Erasing the original sources is a good idea, to make sure that you do 3156not accidentally edit them in @var{wdir}, bypassing @sc{cvs}. 3157Of course, it would be wise to make sure that you have 3158a backup of the sources before you remove them. 3159 3160The @code{checkout} command can either take a module 3161name as argument (as it has done in all previous 3162examples) or a path name relative to @code{$CVSROOT}, 3163as it did in the example above. 3164 3165It is a good idea to check that the permissions 3166@sc{cvs} sets on the directories inside @code{$CVSROOT} 3167are reasonable, and that they belong to the proper 3168groups. @xref{File permissions}. 3169 3170If some of the files you want to import are binary, you 3171may want to use the wrappers features to specify which 3172files are binary and which are not. @xref{Wrappers}. 3173 3174@c The node name is too long, but I am having trouble 3175@c thinking of something more concise. 3176@node From other version control systems 3177@subsection Creating Files From Other Version Control Systems 3178@cindex Importing files, from other version control systems 3179 3180If you have a project which you are maintaining with 3181another version control system, such as @sc{rcs}, you 3182may wish to put the files from that project into 3183@sc{cvs}, and preserve the revision history of the 3184files. 3185 3186@table @asis 3187@cindex RCS, importing files from 3188@item From RCS 3189If you have been using @sc{rcs}, find the @sc{rcs} 3190files---usually a file named @file{foo.c} will have its 3191@sc{rcs} file in @file{RCS/foo.c,v} (but it could be 3192other places; consult the @sc{rcs} documentation for 3193details). Then create the appropriate directories in 3194@sc{cvs} if they do not already exist. Then copy the 3195files into the appropriate directories in the @sc{cvs} 3196repository (the name in the repository must be the name 3197of the source file with @samp{,v} added; the files go 3198directly in the appropriate directory of the repository, 3199not in an @file{RCS} subdirectory). This is one of the 3200few times when it is a good idea to access the @sc{cvs} 3201repository directly, rather than using @sc{cvs} 3202commands. Then you are ready to check out a new 3203working directory. 3204@c Someday there probably should be a "cvs import -t 3205@c rcs" or some such. It could even create magic 3206@c branches. It could also do something about the case 3207@c where the RCS file had a (non-magic) "0" branch. 3208 3209The @sc{rcs} file should not be locked when you move it 3210into @sc{cvs}; if it is, @sc{cvs} will have trouble 3211letting you operate on it. 3212@c What is the easiest way to unlock your files if you 3213@c have them locked? Especially if you have a lot of them? 3214@c This is a CVS bug/misfeature; importing RCS files 3215@c should ignore whether they are locked and leave them in 3216@c an unlocked state. Yet another reason for a separate 3217@c "import RCS file" command. 3218 3219@c How many is "many"? Or do they just import RCS files? 3220@item From another version control system 3221Many version control systems have the ability to export 3222@sc{rcs} files in the standard format. If yours does, 3223export the @sc{rcs} files and then follow the above 3224instructions. 3225 3226Failing that, probably your best bet is to write a 3227script that will check out the files one revision at a 3228time using the command line interface to the other 3229system, and then check the revisions into @sc{cvs}. 3230The @file{sccs2rcs} script mentioned below may be a 3231useful example to follow. 3232 3233@cindex SCCS, importing files from 3234@item From SCCS 3235There is a script in the @file{contrib} directory of 3236the @sc{cvs} source distribution called @file{sccs2rcs} 3237which converts @sc{sccs} files to @sc{rcs} files. 3238Note: you must run it on a machine which has both 3239@sc{sccs} and @sc{rcs} installed, and like everything 3240else in contrib it is unsupported (your mileage may 3241vary). 3242 3243@cindex PVCS, importing files from 3244@item From PVCS 3245There is a script in the @file{contrib} directory of 3246the @sc{cvs} source distribution called @file{pvcs_to_rcs} 3247which converts @sc{pvcs} archives to @sc{rcs} files. 3248You must run it on a machine which has both 3249@sc{pvcs} and @sc{rcs} installed, and like everything 3250else in contrib it is unsupported (your mileage may 3251vary). See the comments in the script for details. 3252@end table 3253@c CMZ and/or PATCHY were systems that were used in the 3254@c high energy physics community (especially for 3255@c CERNLIB). CERN has replaced them with CVS, but the 3256@c CAR format seems to live on as a way to submit 3257@c changes. There is a program car2cvs which converts 3258@c but I'm not sure where one gets a copy. 3259@c Not sure it is worth mentioning here, since it would 3260@c appear to affect only one particular community. 3261@c Best page for more information is: 3262@c http://wwwcn1.cern.ch/asd/cvs/index.html 3263@c See also: 3264@c http://ecponion.cern.ch/ecpsa/cernlib.html 3265 3266@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267@node From scratch 3268@subsection Creating a directory tree from scratch 3269 3270@c Also/instead should be documenting 3271@c $ cvs co -l . 3272@c $ mkdir tc 3273@c $ cvs add tc 3274@c $ cd tc 3275@c $ mkdir man 3276@c $ cvs add man 3277@c etc. 3278@c Using import to create the directories only is 3279@c probably a somewhat confusing concept. 3280For a new project, the easiest thing to do is probably 3281to create an empty directory structure, like this: 3282 3283@example 3284$ mkdir tc 3285$ mkdir tc/man 3286$ mkdir tc/testing 3287@end example 3288 3289After that, you use the @code{import} command to create 3290the corresponding (empty) directory structure inside 3291the repository: 3292 3293@example 3294$ cd tc 3295$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start 3296@end example 3297 3298Then, use @code{add} to add files (and new directories) 3299as they appear. 3300 3301Check that the permissions @sc{cvs} sets on the 3302directories inside @code{$CVSROOT} are reasonable. 3303 3304@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3305@node Defining the module 3306@section Defining the module 3307@cindex Defining a module 3308@cindex Editing the modules file 3309@cindex Module, defining 3310@cindex Modules file, changing 3311 3312The next step is to define the module in the 3313@file{modules} file. This is not strictly necessary, 3314but modules can be convenient in grouping together 3315related files and directories. 3316 3317In simple cases these steps are sufficient to define a module. 3318 3319@enumerate 3320@item 3321Get a working copy of the modules file. 3322 3323@example 3324$ cvs checkout CVSROOT/modules 3325$ cd CVSROOT 3326@end example 3327 3328@item 3329Edit the file and insert a line that defines the module. @xref{Intro 3330administrative files}, for an introduction. @xref{modules}, for a full 3331description of the modules file. You can use the 3332following line to define the module @samp{tc}: 3333 3334@example 3335tc yoyodyne/tc 3336@end example 3337 3338@item 3339Commit your changes to the modules file. 3340 3341@example 3342$ cvs commit -m "Added the tc module." modules 3343@end example 3344 3345@item 3346Release the modules module. 3347 3348@example 3349$ cd .. 3350$ cvs release -d CVSROOT 3351@end example 3352@end enumerate 3353 3354@c --------------------------------------------------------------------- 3355@node Revisions 3356@chapter Revisions 3357 3358For many uses of @sc{cvs}, one doesn't need to worry 3359too much about revision numbers; @sc{cvs} assigns 3360numbers such as @code{1.1}, @code{1.2}, and so on, and 3361that is all one needs to know. However, some people 3362prefer to have more knowledge and control concerning 3363how @sc{cvs} assigns revision numbers. 3364 3365If one wants to keep track of a set of revisions 3366involving more than one file, such as which revisions 3367went into a particular release, one uses a @dfn{tag}, 3368which is a symbolic revision which can be assigned to a 3369numeric revision in each file. 3370 3371@menu 3372* Revision numbers:: The meaning of a revision number 3373* Versions revisions releases:: Terminology used in this manual 3374* Assigning revisions:: Assigning revisions 3375* Tags:: Tags--Symbolic revisions 3376* Tagging the working directory:: The cvs tag command 3377* Tagging by date/tag:: The cvs rtag command 3378* Modifying tags:: Adding, renaming, and deleting tags 3379* Tagging add/remove:: Tags with adding and removing files 3380* Sticky tags:: Certain tags are persistent 3381@end menu 3382 3383@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3384@node Revision numbers 3385@section Revision numbers 3386@cindex Revision numbers 3387@cindex Revision tree 3388@cindex Linear development 3389@cindex Number, revision- 3390@cindex Decimal revision number 3391@cindex Branch number 3392@cindex Number, branch 3393 3394Each version of a file has a unique @dfn{revision 3395number}. Revision numbers look like @samp{1.1}, 3396@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. 3397A revision number always has an even number of 3398period-separated decimal integers. By default revision 33991.1 is the first revision of a file. Each successive 3400revision is given a new number by increasing the 3401rightmost number by one. The following figure displays 3402a few revisions, with newer revisions to the right. 3403 3404@example 3405 +-----+ +-----+ +-----+ +-----+ +-----+ 3406 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 3407 +-----+ +-----+ +-----+ +-----+ +-----+ 3408@end example 3409 3410It is also possible to end up with numbers containing 3411more than one period, for example @samp{1.3.2.2}. Such 3412revisions represent revisions on branches 3413(@pxref{Branching and merging}); such revision numbers 3414are explained in detail in @ref{Branches and 3415revisions}. 3416 3417@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3418@node Versions revisions releases 3419@section Versions, revisions and releases 3420@cindex Revisions, versions and releases 3421@cindex Versions, revisions and releases 3422@cindex Releases, revisions and versions 3423 3424A file can have several versions, as described above. 3425Likewise, a software product can have several versions. 3426A software product is often given a version number such 3427as @samp{4.1.1}. 3428 3429Versions in the first sense are called @dfn{revisions} 3430in this document, and versions in the second sense are 3431called @dfn{releases}. To avoid confusion, the word 3432@dfn{version} is almost never used in this document. 3433 3434@node Assigning revisions 3435@section Assigning revisions 3436 3437@c We avoid the "major revision" terminology. It seems 3438@c like jargon. Hopefully "first number" is clear enough. 3439@c 3440@c Well, in the context of software release numbers, 3441@c "major" and "minor" release or version numbers are 3442@c documented in at least the GNU Coding Standards, but I'm 3443@c still not sure I find that a valid reason to apply the 3444@c terminology to RCS revision numbers. "First", "Second", 3445@c "subsequent", and so on is almost surely clearer, 3446@c especially to a novice reader. -DRP 3447By default, @sc{cvs} will assign numeric revisions by 3448leaving the first number the same and incrementing the 3449second number. For example, @code{1.1}, @code{1.2}, 3450@code{1.3}, etc. 3451 3452When adding a new file, the second number will always 3453be one and the first number will equal the highest 3454first number of any file in that directory. For 3455example, the current directory contains files whose 3456highest numbered revisions are @code{1.7}, @code{3.1}, 3457and @code{4.12}, then an added file will be given the 3458numeric revision @code{4.1}. 3459 3460@c This is sort of redundant with something we said a 3461@c while ago. Somewhere we need a better way of 3462@c introducing how the first number can be anything 3463@c except "1", perhaps. Also I don't think this 3464@c presentation is clear on why we are discussing releases 3465@c and first numbers of numeric revisions in the same 3466@c breath. 3467Normally there is no reason to care 3468about the revision numbers---it is easier to treat them 3469as internal numbers that @sc{cvs} maintains, and tags 3470provide a better way to distinguish between things like 3471release 1 versus release 2 of your product 3472(@pxref{Tags}). However, if you want to set the 3473numeric revisions, the @samp{-r} option to @code{cvs 3474commit} can do that. The @samp{-r} option implies the 3475@samp{-f} option, in the sense that it causes the 3476files to be committed even if they are not modified. 3477 3478For example, to bring all your files up to 3479revision 3.0 (including those that haven't changed), 3480you might invoke: 3481 3482@example 3483$ cvs commit -r 3.0 3484@end example 3485 3486Note that the number you specify with @samp{-r} must be 3487larger than any existing revision number. That is, if 3488revision 3.0 exists, you cannot @samp{cvs commit 3489-r 1.3}. If you want to maintain several releases in 3490parallel, you need to use a branch (@pxref{Branching and merging}). 3491 3492@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3493@node Tags 3494@section Tags--Symbolic revisions 3495@cindex Tags 3496 3497The revision numbers live a life of their own. They 3498need not have anything at all to do with the release 3499numbers of your software product. Depending 3500on how you use @sc{cvs} the revision numbers might change several times 3501between two releases. As an example, some of the 3502source files that make up @sc{rcs} 5.6 have the following 3503revision numbers: 3504@cindex RCS revision numbers 3505 3506@example 3507ci.c 5.21 3508co.c 5.9 3509ident.c 5.3 3510rcs.c 5.12 3511rcsbase.h 5.11 3512rcsdiff.c 5.10 3513rcsedit.c 5.11 3514rcsfcmp.c 5.9 3515rcsgen.c 5.10 3516rcslex.c 5.11 3517rcsmap.c 5.2 3518rcsutil.c 5.10 3519@end example 3520 3521@cindex tag (subcommand), introduction 3522@cindex Tags, symbolic name 3523@cindex Symbolic name (tag) 3524@cindex Name, symbolic (tag) 3525@cindex HEAD, as reserved tag name 3526@cindex BASE, as reserved tag name 3527You can use the @code{tag} command to give a symbolic name to a 3528certain revision of a file. You can use the @samp{-v} flag to the 3529@code{status} command to see all tags that a file has, and 3530which revision numbers they represent. Tag names must 3531start with an uppercase or lowercase letter and can 3532contain uppercase and lowercase letters, digits, 3533@samp{-}, and @samp{_}. The two tag names @code{BASE} 3534and @code{HEAD} are reserved for use by @sc{cvs}. It 3535is expected that future names which are special to 3536@sc{cvs} will be specially named, for example by 3537starting with @samp{.}, rather than being named analogously to 3538@code{BASE} and @code{HEAD}, to avoid conflicts with 3539actual tag names. 3540@c Including a character such as % or = has also been 3541@c suggested as the naming convention for future 3542@c special tag names. Starting with . is nice because 3543@c that is not a legal tag name as far as RCS is concerned. 3544@c FIXME: CVS actually accepts quite a few characters 3545@c in tag names, not just the ones documented above 3546@c (see RCS_check_tag). RCS 3547@c defines legitimate tag names by listing illegal 3548@c characters rather than legal ones. CVS is said to lose its 3549@c mind if you try to use "/" (try making such a tag sticky 3550@c and using "cvs status" client/server--see remote 3551@c protocol format for entries line for probable cause). 3552@c TODO: The testsuite 3553@c should test for whatever are documented above as 3554@c officially-OK tag names, and CVS should at least reject 3555@c characters that won't work, like "/". 3556 3557You'll want to choose some convention for naming tags, 3558based on information such as the name of the program 3559and the version number of the release. For example, 3560one might take the name of the program, immediately 3561followed by the version number with @samp{.} changed to 3562@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name 3563@code{cvs1-9}. If you choose a consistent convention, 3564then you won't constantly be guessing whether a tag is 3565@code{cvs-1-9} or @code{cvs1_9} or what. You might 3566even want to consider enforcing your convention in the 3567taginfo file (@pxref{user-defined logging}). 3568@c Might be nice to say more about using taginfo this 3569@c way, like giving an example, or pointing out any particular 3570@c issues which arise. 3571 3572@cindex Adding a tag 3573@cindex Tags, example 3574The following example shows how you can add a tag to a 3575file. The commands must be issued inside your working 3576directory. That is, you should issue the 3577command in the directory where @file{backend.c} 3578resides. 3579 3580@example 3581$ cvs tag rel-0-4 backend.c 3582T backend.c 3583$ cvs status -v backend.c 3584=================================================================== 3585File: backend.c Status: Up-to-date 3586 3587 Version: 1.4 Tue Dec 1 14:39:01 1992 3588 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 3589 Sticky Tag: (none) 3590 Sticky Date: (none) 3591 Sticky Options: (none) 3592 3593 Existing Tags: 3594 rel-0-4 (revision: 1.4) 3595 3596@end example 3597 3598For a complete summary of the syntax of @code{cvs tag}, 3599including the various options, see @ref{Invoking CVS}. 3600 3601There is seldom reason to tag a file in isolation. A more common use is 3602to tag all the files that constitute a module with the same tag at 3603strategic points in the development life-cycle, such as when a release 3604is made. 3605 3606@example 3607$ cvs tag rel-1-0 . 3608cvs tag: Tagging . 3609T Makefile 3610T backend.c 3611T driver.c 3612T frontend.c 3613T parser.c 3614@end example 3615 3616@noindent 3617(When you give @sc{cvs} a directory as argument, it generally applies the 3618operation to all the files in that directory, and (recursively), to any 3619subdirectories that it may contain. @xref{Recursive behavior}.) 3620 3621@cindex Retrieving an old revision using tags 3622@cindex Tags, retrieving old revisions 3623The @code{checkout} command has a flag, @samp{-r}, that lets you check out 3624a certain revision of a module. This flag makes it easy to 3625retrieve the sources that make up release 1.0 of the module @samp{tc} at 3626any time in the future: 3627 3628@example 3629$ cvs checkout -r rel-1-0 tc 3630@end example 3631 3632@noindent 3633This is useful, for instance, if someone claims that there is a bug in 3634that release, but you cannot find the bug in the current working copy. 3635 3636You can also check out a module as it was at any given date. 3637@xref{checkout options}. When specifying @samp{-r} to 3638any of these commands, you will need beware of sticky 3639tags; see @ref{Sticky tags}. 3640 3641When you tag more than one file with the same tag you 3642can think about the tag as "a curve drawn through a 3643matrix of filename vs. revision number." Say we have 5 3644files with the following revisions: 3645 3646@example 3647@group 3648 file1 file2 file3 file4 file5 3649 3650 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG 3651 1.2*- 1.2 1.2 -1.2*- 3652 1.3 \- 1.3*- 1.3 / 1.3 3653 1.4 \ 1.4 / 1.4 3654 \-1.5*- 1.5 3655 1.6 3656@end group 3657@end example 3658 3659At some time in the past, the @code{*} versions were tagged. 3660You can think of the tag as a handle attached to the curve 3661drawn through the tagged revisions. When you pull on 3662the handle, you get all the tagged revisions. Another 3663way to look at it is that you "sight" through a set of 3664revisions that is "flat" along the tagged revisions, 3665like this: 3666 3667@example 3668@group 3669 file1 file2 file3 file4 file5 3670 3671 1.1 3672 1.2 3673 1.1 1.3 _ 3674 1.1 1.2 1.4 1.1 / 3675 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here 3676 1.3 1.6 1.3 \_ 3677 1.4 1.4 3678 1.5 3679@end group 3680@end example 3681 3682@node Tagging the working directory 3683@section Specifying what to tag from the working directory 3684 3685@cindex tag (subcommand) 3686The example in the previous section demonstrates one of 3687the most common ways to choose which revisions to tag. 3688Namely, running the @code{cvs tag} command without 3689arguments causes @sc{cvs} to select the revisions which 3690are checked out in the current working directory. For 3691example, if the copy of @file{backend.c} in working 3692directory was checked out from revision 1.4, then 3693@sc{cvs} will tag revision 1.4. Note that the tag is 3694applied immediately to revision 1.4 in the repository; 3695tagging is not like modifying a file, or other 3696operations in which one first modifies the working 3697directory and then runs @code{cvs commit} to transfer 3698that modification to the repository. 3699 3700One potentially surprising aspect of the fact that 3701@code{cvs tag} operates on the repository is that you 3702are tagging the checked-in revisions, which may differ 3703from locally modified files in your working directory. 3704If you want to avoid doing this by mistake, specify the 3705@samp{-c} option to @code{cvs tag}. If there are any 3706locally modified files, @sc{cvs} will abort with an 3707error before it tags any files: 3708 3709@example 3710$ cvs tag -c rel-0-4 3711cvs tag: backend.c is locally modified 3712cvs [tag aborted]: correct the above errors first! 3713@end example 3714 3715@node Tagging by date/tag 3716@section Specifying what to tag by date or revision 3717@cindex rtag (subcommand) 3718 3719The @code{cvs rtag} command tags the repository as of a 3720certain date or time (or can be used to tag the latest 3721revision). @code{rtag} works directly on the 3722repository contents (it requires no prior checkout and 3723does not look for a working directory). 3724 3725The following options specify which date or revision to 3726tag. See @ref{Common options}, for a complete 3727description of them. 3728 3729@table @code 3730@item -D @var{date} 3731Tag the most recent revision no later than @var{date}. 3732 3733@item -f 3734Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}} 3735flags. If no matching revision is found, use the most 3736recent revision (instead of ignoring the file). 3737 3738@item -r @var{tag} 3739Only tag those files that contain existing tag @var{tag}. 3740@end table 3741 3742The @code{cvs tag} command also allows one to specify 3743files by revision or date, using the same @samp{-r}, 3744@samp{-D}, and @samp{-f} options. However, this 3745feature is probably not what you want. The reason is 3746that @code{cvs tag} chooses which files to tag based on 3747the files that exist in the working directory, rather 3748than the files which existed as of the given tag/date. 3749Therefore, you are generally better off using @code{cvs 3750rtag}. The exceptions might be cases like: 3751 3752@example 3753cvs tag -r 1.4 stable backend.c 3754@end example 3755 3756@node Modifying tags 3757@section Deleting, moving, and renaming tags 3758 3759@c Also see: 3760@c "How do I move or rename a magic branch tag?" 3761@c in the FAQ (I think the issues it talks about still 3762@c apply, but this could use some sanity.sh work). 3763 3764Normally one does not modify tags. They exist in order 3765to record the history of the repository and so deleting 3766them or changing their meaning would, generally, not be 3767what you want. 3768 3769However, there might be cases in which one uses a tag 3770temporarily or accidentally puts one in the wrong 3771place. Therefore, one might delete, move, or rename a 3772tag. 3773 3774@noindent 3775@strong{WARNING: the commands in this section are 3776dangerous; they permanently discard historical 3777information and it can be difficult or impossible to 3778recover from errors. If you are a @sc{cvs} 3779administrator, you may consider restricting these 3780commands with taginfo (@pxref{user-defined logging}).} 3781 3782@cindex Deleting tags 3783@cindex Deleting branch tags 3784@cindex Removing tags 3785@cindex Removing branch tags 3786@cindex Tags, deleting 3787@cindex Branch tags, deleting 3788To delete a tag, specify the @samp{-d} option to either 3789@code{cvs tag} or @code{cvs rtag}. For example: 3790 3791@example 3792cvs rtag -d rel-0-4 tc 3793@end example 3794 3795@noindent 3796deletes the non-branch tag @code{rel-0-4} from the module @code{tc}. 3797In the event that branch tags are encountered within the repository 3798with the given name, a warning message will be issued and the branch 3799tag will not be deleted. If you are absolutely certain you know what 3800you are doing, the @code{-B} option may be specified to allow deletion 3801of branch tags. In that case, any non-branch tags encountered will 3802trigger warnings and will not be deleted. 3803 3804@noindent 3805@strong{WARNING: Moving branch tags is very dangerous! If you think 3806you need the @code{-B} option, think again and ask your @sc{cvs} 3807administrator about it (if that isn't you). There is almost certainly 3808another way to accomplish what you want to accomplish.} 3809 3810@cindex Moving tags 3811@cindex Moving branch tags 3812@cindex Tags, moving 3813@cindex Branch tags, moving 3814When we say @dfn{move} a tag, we mean to make the same 3815name point to different revisions. For example, the 3816@code{stable} tag may currently point to revision 1.4 3817of @file{backend.c} and perhaps we want to make it 3818point to revision 1.6. To move a non-branch tag, specify the 3819@samp{-F} option to either @code{cvs tag} or @code{cvs 3820rtag}. For example, the task just mentioned might be 3821accomplished as: 3822 3823@example 3824cvs tag -r 1.6 -F stable backend.c 3825@end example 3826 3827@noindent 3828If any branch tags are encountered in the repository 3829with the given name, a warning is issued and the branch 3830tag is not disturbed. If you are absolutely certain you 3831wish to move the branch tag, the @code{-B} option may be specified. 3832In that case, non-branch tags encountered with the given 3833name are ignored with a warning message. 3834 3835@noindent 3836@strong{WARNING: Moving branch tags is very dangerous! If you think you 3837need the @code{-B} option, think again and ask your @sc{cvs} 3838administrator about it (if that isn't you). There is almost certainly 3839another way to accomplish what you want to accomplish.} 3840 3841@cindex Renaming tags 3842@cindex Tags, renaming 3843When we say @dfn{rename} a tag, we mean to make a 3844different name point to the same revisions as the old 3845tag. For example, one may have misspelled the tag name 3846and want to correct it (hopefully before others are 3847relying on the old spelling). To rename a tag, first 3848create a new tag using the @samp{-r} option to 3849@code{cvs rtag}, and then delete the old name. (Caution: 3850this method will not work with branch tags.) 3851This leaves the new tag on exactly the 3852same files as the old tag. For example: 3853 3854@example 3855cvs rtag -r old-name-0-4 rel-0-4 tc 3856cvs rtag -d old-name-0-4 tc 3857@end example 3858 3859@node Tagging add/remove 3860@section Tagging and adding and removing files 3861 3862The subject of exactly how tagging interacts with 3863adding and removing files is somewhat obscure; for the 3864most part @sc{cvs} will keep track of whether files 3865exist or not without too much fussing. By default, 3866tags are applied to only files which have a revision 3867corresponding to what is being tagged. Files which did 3868not exist yet, or which were already removed, simply 3869omit the tag, and @sc{cvs} knows to treat the absence 3870of a tag as meaning that the file didn't exist as of 3871that tag. 3872 3873However, this can lose a small amount of information. 3874For example, suppose a file was added and then removed. 3875Then, if the tag is missing for that file, there is no 3876way to know whether the tag refers to the time before 3877the file was added, or the time after it was removed. 3878If you specify the @samp{-r} option to @code{cvs rtag}, 3879then @sc{cvs} tags the files which have been removed, 3880and thereby avoids this problem. For example, one 3881might specify @code{-r HEAD} to tag the head. 3882 3883On the subject of adding and removing files, the 3884@code{cvs rtag} command has a @samp{-a} option which 3885means to clear the tag from removed files that would 3886not otherwise be tagged. For example, one might 3887specify this option in conjunction with @samp{-F} when 3888moving a tag. If one moved a tag without @samp{-a}, 3889then the tag in the removed files might still refer to 3890the old revision, rather than reflecting the fact that 3891the file had been removed. I don't think this is 3892necessary if @samp{-r} is specified, as noted above. 3893 3894@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 3895@node Sticky tags 3896@section Sticky tags 3897@cindex Sticky tags 3898@cindex Tags, sticky 3899 3900@c A somewhat related issue is per-directory sticky 3901@c tags (see comment at CVS/Tag in node Working 3902@c directory storage); we probably want to say 3903@c something like "you can set a sticky tag for only 3904@c some files, but you don't want to" or some such. 3905 3906Sometimes a working copy's revision has extra data 3907associated with it, for example it might be on a branch 3908(@pxref{Branching and merging}), or restricted to 3909versions prior to a certain date by @samp{checkout -D} 3910or @samp{update -D}. Because this data persists -- 3911that is, it applies to subsequent commands in the 3912working copy -- we refer to it as @dfn{sticky}. 3913 3914Most of the time, stickiness is an obscure aspect of 3915@sc{cvs} that you don't need to think about. However, 3916even if you don't want to use the feature, you may need 3917to know @emph{something} about sticky tags (for 3918example, how to avoid them!). 3919 3920You can use the @code{status} command to see if any 3921sticky tags or dates are set: 3922 3923@example 3924$ cvs status driver.c 3925=================================================================== 3926File: driver.c Status: Up-to-date 3927 3928 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 3929 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v 3930 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 3931 Sticky Date: (none) 3932 Sticky Options: (none) 3933 3934@end example 3935 3936@cindex Resetting sticky tags 3937@cindex Sticky tags, resetting 3938@cindex Deleting sticky tags 3939The sticky tags will remain on your working files until 3940you delete them with @samp{cvs update -A}. The 3941@samp{-A} option merges local changes into the version of the 3942file from the head of the trunk, removing any sticky tags, 3943dates, or options. See @ref{update} for more on the operation 3944of @code{cvs update}. 3945 3946@cindex Sticky date 3947The most common use of sticky tags is to identify which 3948branch one is working on, as described in 3949@ref{Accessing branches}. However, non-branch 3950sticky tags have uses as well. For example, 3951suppose that you want to avoid updating your working 3952directory, to isolate yourself from possibly 3953destabilizing changes other people are making. You 3954can, of course, just refrain from running @code{cvs 3955update}. But if you want to avoid updating only a 3956portion of a larger tree, then sticky tags can help. 3957If you check out a certain revision (such as 1.4) it 3958will become sticky. Subsequent @code{cvs update} 3959commands will 3960not retrieve the latest revision until you reset the 3961tag with @code{cvs update -A}. Likewise, use of the 3962@samp{-D} option to @code{update} or @code{checkout} 3963sets a @dfn{sticky date}, which, similarly, causes that 3964date to be used for future retrievals. 3965 3966People often want to retrieve an old version of 3967a file without setting a sticky tag. This can 3968be done with the @samp{-p} option to @code{checkout} or 3969@code{update}, which sends the contents of the file to 3970standard output. For example: 3971@example 3972$ cvs update -p -r 1.1 file1 >file1 3973=================================================================== 3974Checking out file1 3975RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v 3976VERS: 1.1 3977*************** 3978$ 3979@end example 3980 3981However, this isn't the easiest way, if you are asking 3982how to undo a previous checkin (in this example, put 3983@file{file1} back to the way it was as of revision 39841.1). In that case you are better off using the 3985@samp{-j} option to @code{update}; for further 3986discussion see @ref{Merging two revisions}. 3987 3988@c --------------------------------------------------------------------- 3989@node Branching and merging 3990@chapter Branching and merging 3991@cindex Branching 3992@cindex Merging 3993@cindex Copying changes 3994@cindex Main trunk and branches 3995@cindex Revision tree, making branches 3996@cindex Branches, copying changes between 3997@cindex Changes, copying between branches 3998@cindex Modifications, copying between branches 3999 4000@sc{cvs} allows you to isolate changes onto a separate 4001line of development, known as a @dfn{branch}. When you 4002change files on a branch, those changes do not appear 4003on the main trunk or other branches. 4004 4005Later you can move changes from one branch to another 4006branch (or the main trunk) by @dfn{merging}. Merging 4007involves first running @code{cvs update -j}, to merge 4008the changes into the working directory. 4009You can then commit that revision, and thus effectively 4010copy the changes onto another branch. 4011 4012@menu 4013* Branches motivation:: What branches are good for 4014* Creating a branch:: Creating a branch 4015* Accessing branches:: Checking out and updating branches 4016* Branches and revisions:: Branches are reflected in revision numbers 4017* Magic branch numbers:: Magic branch numbers 4018* Merging a branch:: Merging an entire branch 4019* Merging more than once:: Merging from a branch several times 4020* Merging two revisions:: Merging differences between two revisions 4021* Merging adds and removals:: What if files are added or removed? 4022* Merging and keywords:: Avoiding conflicts due to keyword substitution 4023@end menu 4024 4025@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4026@node Branches motivation 4027@section What branches are good for 4028@cindex Branches motivation 4029@cindex What branches are good for 4030@cindex Motivation for branches 4031 4032@c FIXME: this node mentions one way to use branches, 4033@c but it is by no means the only way. For example, 4034@c the technique of committing a new feature on a branch, 4035@c until it is ready for the main trunk. The whole 4036@c thing is generally speaking more akin to the 4037@c "Revision management" node although it isn't clear to 4038@c me whether policy matters should be centralized or 4039@c distributed throughout the relevant sections. 4040Suppose that release 1.0 of tc has been made. You are continuing to 4041develop tc, planning to create release 1.1 in a couple of months. After a 4042while your customers start to complain about a fatal bug. You check 4043out release 1.0 (@pxref{Tags}) and find the bug 4044(which turns out to have a trivial fix). However, the current revision 4045of the sources are in a state of flux and are not expected to be stable 4046for at least another month. There is no way to make a 4047bugfix release based on the newest sources. 4048 4049The thing to do in a situation like this is to create a @dfn{branch} on 4050the revision trees for all the files that make up 4051release 1.0 of tc. You can then make 4052modifications to the branch without disturbing the main trunk. When the 4053modifications are finished you can elect to either incorporate them on 4054the main trunk, or leave them on the branch. 4055 4056@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4057@node Creating a branch 4058@section Creating a branch 4059@cindex Creating a branch 4060@cindex Branch, creating a 4061@cindex tag (subcommand), creating a branch using 4062@cindex rtag (subcommand), creating a branch using 4063 4064You can create a branch with @code{tag -b}; for 4065example, assuming you're in a working copy: 4066 4067@example 4068$ cvs tag -b rel-1-0-patches 4069@end example 4070 4071@c FIXME: we should be more explicit about the value of 4072@c having a tag on the branchpoint. For example 4073@c "cvs tag rel-1-0-patches-branchpoint" before 4074@c the "cvs tag -b". This points out that 4075@c rel-1-0-patches is a pretty awkward name for 4076@c this example (more so than for the rtag example 4077@c below). 4078 4079This splits off a branch based on the current revisions 4080in the working copy, assigning that branch the name 4081@samp{rel-1-0-patches}. 4082 4083It is important to understand that branches get created 4084in the repository, not in the working copy. Creating a 4085branch based on current revisions, as the above example 4086does, will @emph{not} automatically switch the working 4087copy to be on the new branch. For information on how 4088to do that, see @ref{Accessing branches}. 4089 4090You can also create a branch without reference to any 4091working copy, by using @code{rtag}: 4092 4093@example 4094$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc 4095@end example 4096 4097@samp{-r rel-1-0} says that this branch should be 4098rooted at the revision that 4099corresponds to the tag @samp{rel-1-0}. It need not 4100be the most recent revision -- it's often useful to 4101split a branch off an old revision (for example, when 4102fixing a bug in a past release otherwise known to be 4103stable). 4104 4105As with @samp{tag}, the @samp{-b} flag tells 4106@code{rtag} to create a branch (rather than just a 4107symbolic revision name). Note that the numeric 4108revision number that matches @samp{rel-1-0} will 4109probably be different from file to file. 4110 4111So, the full effect of the command is to create a new 4112branch -- named @samp{rel-1-0-patches} -- in module 4113@samp{tc}, rooted in the revision tree at the point tagged 4114by @samp{rel-1-0}. 4115 4116@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4117@node Accessing branches 4118@section Accessing branches 4119@cindex Check out a branch 4120@cindex Retrieve a branch 4121@cindex Access a branch 4122@cindex Identifying a branch 4123@cindex Branch, check out 4124@cindex Branch, retrieving 4125@cindex Branch, accessing 4126@cindex Branch, identifying 4127 4128You can retrieve a branch in one of two ways: by 4129checking it out fresh from the repository, or by 4130switching an existing working copy over to the branch. 4131 4132To check out a branch from the repository, invoke 4133@samp{checkout} with the @samp{-r} flag, followed by 4134the tag name of the branch (@pxref{Creating a branch}): 4135 4136@example 4137$ cvs checkout -r rel-1-0-patches tc 4138@end example 4139 4140Or, if you already have a working copy, you can switch 4141it to a given branch with @samp{update -r}: 4142 4143@example 4144$ cvs update -r rel-1-0-patches tc 4145@end example 4146 4147@noindent 4148or equivalently: 4149 4150@example 4151$ cd tc 4152$ cvs update -r rel-1-0-patches 4153@end example 4154 4155It does not matter if the working copy was originally 4156on the main trunk or on some other branch -- the above 4157command will switch it to the named branch. And 4158similarly to a regular @samp{update} command, 4159@samp{update -r} merges any changes you have made, 4160notifying you of conflicts where they occur. 4161 4162Once you have a working copy tied to a particular 4163branch, it remains there until you tell it otherwise. 4164This means that changes checked in from the working 4165copy will add new revisions on that branch, while 4166leaving the main trunk and other branches unaffected. 4167 4168@cindex Branches, sticky 4169To find out what branch a working copy is on, you can 4170use the @samp{status} command. In its output, look for 4171the field named @samp{Sticky tag} (@pxref{Sticky tags}) 4172-- that's @sc{cvs}'s way of telling you the branch, if 4173any, of the current working files: 4174 4175@example 4176$ cvs status -v driver.c backend.c 4177=================================================================== 4178File: driver.c Status: Up-to-date 4179 4180 Version: 1.7 Sat Dec 5 18:25:54 1992 4181 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v 4182 Sticky Tag: rel-1-0-patches (branch: 1.7.2) 4183 Sticky Date: (none) 4184 Sticky Options: (none) 4185 4186 Existing Tags: 4187 rel-1-0-patches (branch: 1.7.2) 4188 rel-1-0 (revision: 1.7) 4189 4190=================================================================== 4191File: backend.c Status: Up-to-date 4192 4193 Version: 1.4 Tue Dec 1 14:39:01 1992 4194 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v 4195 Sticky Tag: rel-1-0-patches (branch: 1.4.2) 4196 Sticky Date: (none) 4197 Sticky Options: (none) 4198 4199 Existing Tags: 4200 rel-1-0-patches (branch: 1.4.2) 4201 rel-1-0 (revision: 1.4) 4202 rel-0-4 (revision: 1.4) 4203 4204@end example 4205 4206Don't be confused by the fact that the branch numbers 4207for each file are different (@samp{1.7.2} and 4208@samp{1.4.2} respectively). The branch tag is the 4209same, @samp{rel-1-0-patches}, and the files are 4210indeed on the same branch. The numbers simply reflect 4211the point in each file's revision history at which the 4212branch was made. In the above example, one can deduce 4213that @samp{driver.c} had been through more changes than 4214@samp{backend.c} before this branch was created. 4215 4216See @ref{Branches and revisions} for details about how 4217branch numbers are constructed. 4218 4219@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4220@node Branches and revisions 4221@section Branches and revisions 4222@cindex Branch number 4223@cindex Number, branch 4224@cindex Revision numbers (branches) 4225 4226Ordinarily, a file's revision history is a linear 4227series of increments (@pxref{Revision numbers}): 4228 4229@example 4230 +-----+ +-----+ +-----+ +-----+ +-----+ 4231 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! 4232 +-----+ +-----+ +-----+ +-----+ +-----+ 4233@end example 4234 4235However, @sc{cvs} is not limited to linear development. The 4236@dfn{revision tree} can be split into @dfn{branches}, 4237where each branch is a self-maintained line of 4238development. Changes made on one branch can easily be 4239moved back to the main trunk. 4240 4241Each branch has a @dfn{branch number}, consisting of an 4242odd number of period-separated decimal integers. The 4243branch number is created by appending an integer to the 4244revision number where the corresponding branch forked 4245off. Having branch numbers allows more than one branch 4246to be forked off from a certain revision. 4247 4248@need 3500 4249All revisions on a branch have revision numbers formed 4250by appending an ordinal number to the branch number. 4251The following figure illustrates branching with an 4252example. 4253 4254@example 4255@c This example used to have a 1.2.2.4 revision, which 4256@c might help clarify that development can continue on 4257@c 1.2.2. Might be worth reinstating if it can be done 4258@c without overfull hboxes. 4259@group 4260 +-------------+ 4261 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! 4262 / +-------------+ 4263 / 4264 / 4265 +---------+ +---------+ +---------+ 4266Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4267 / +---------+ +---------+ +---------+ 4268 / 4269 / 4270+-----+ +-----+ +-----+ +-----+ +-----+ 4271! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4272+-----+ +-----+ +-----+ +-----+ +-----+ 4273 ! 4274 ! 4275 ! +---------+ +---------+ +---------+ 4276Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! 4277 +---------+ +---------+ +---------+ 4278 4279@end group 4280@end example 4281 4282@c -- However, at least for me the figure is not enough. I suggest more 4283@c -- text to accompany it. "A picture is worth a thousand words", so you 4284@c -- have to make sure the reader notices the couple of hundred words 4285@c -- *you* had in mind more than the others! 4286 4287@c -- Why an even number of segments? This section implies that this is 4288@c -- how the main trunk is distinguished from branch roots, but you never 4289@c -- explicitly say that this is the purpose of the [by itself rather 4290@c -- surprising] restriction to an even number of segments. 4291 4292The exact details of how the branch number is 4293constructed is not something you normally need to be 4294concerned about, but here is how it works: When 4295@sc{cvs} creates a branch number it picks the first 4296unused even integer, starting with 2. So when you want 4297to create a branch from revision 6.4 it will be 4298numbered 6.4.2. All branch numbers ending in a zero 4299(such as 6.4.0) are used internally by @sc{cvs} 4300(@pxref{Magic branch numbers}). The branch 1.1.1 has a 4301special meaning. @xref{Tracking sources}. 4302 4303@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4304@node Magic branch numbers 4305@section Magic branch numbers 4306 4307@c Want xref to here from "log"? 4308 4309This section describes a @sc{cvs} feature called 4310@dfn{magic branches}. For most purposes, you need not 4311worry about magic branches; @sc{cvs} handles them for 4312you. However, they are visible to you in certain 4313circumstances, so it may be useful to have some idea of 4314how it works. 4315 4316Externally, branch numbers consist of an odd number of 4317dot-separated decimal integers. @xref{Revision 4318numbers}. That is not the whole truth, however. For 4319efficiency reasons @sc{cvs} sometimes inserts an extra 0 4320in the second rightmost position (1.2.4 becomes 43211.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so 4322on). 4323 4324@sc{cvs} does a pretty good job at hiding these so 4325called magic branches, but in a few places the hiding 4326is incomplete: 4327 4328@itemize @bullet 4329@item 4330The magic branch number appears in the output from 4331@code{cvs log}. 4332@c What output should appear instead? 4333 4334@item 4335You cannot specify a symbolic branch name to @code{cvs 4336admin}. 4337 4338@end itemize 4339 4340@c Can CVS do this automatically the first time 4341@c you check something in to that branch? Should 4342@c it? 4343You can use the @code{admin} command to reassign a 4344symbolic name to a branch the way @sc{rcs} expects it 4345to be. If @code{R4patches} is assigned to the branch 43461.4.2 (magic branch number 1.4.0.2) in file 4347@file{numbers.c} you can do this: 4348 4349@example 4350$ cvs admin -NR4patches:1.4.2 numbers.c 4351@end example 4352 4353It only works if at least one revision is already 4354committed on the branch. Be very careful so that you 4355do not assign the tag to the wrong number. (There is 4356no way to see how the tag was assigned yesterday). 4357 4358@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4359@node Merging a branch 4360@section Merging an entire branch 4361@cindex Merging a branch 4362@cindex -j (merging branches) 4363 4364You can merge changes made on a branch into your working copy by giving 4365the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one 4366@samp{-j @var{branchname}} option it merges the changes made between the 4367greatest common ancestor (GCA) of the branch and the destination revision (in 4368the simple case below the GCA is the point where the branch forked) and the 4369newest revision on that branch into your working copy. 4370 4371@cindex Join 4372The @samp{-j} stands for ``join''. 4373 4374@cindex Branch merge example 4375@cindex Example, branch merge 4376@cindex Merge, branch example 4377Consider this revision tree: 4378 4379@example 4380+-----+ +-----+ +-----+ +-----+ 4381! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk 4382+-----+ +-----+ +-----+ +-----+ 4383 ! 4384 ! 4385 ! +---------+ +---------+ 4386Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4387 +---------+ +---------+ 4388@end example 4389 4390@noindent 4391The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The 4392following example assumes that the module @samp{mod} contains only one 4393file, @file{m.c}. 4394 4395@example 4396$ cvs checkout mod # @r{Retrieve the latest revision, 1.4} 4397 4398$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} 4399 # @r{i.e. the changes between revision 1.2} 4400 # @r{and 1.2.2.2, into your working copy} 4401 # @r{of the file.} 4402 4403$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} 4404@end example 4405 4406A conflict can result from a merge operation. If that 4407happens, you should resolve it before committing the 4408new revision. @xref{Conflicts example}. 4409 4410If your source files contain keywords (@pxref{Keyword substitution}), 4411you might be getting more conflicts than strictly necessary. See 4412@ref{Merging and keywords}, for information on how to avoid this. 4413 4414The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The 4415same effect as above could be achieved with this: 4416 4417@example 4418$ cvs checkout -j R1fix mod 4419$ cvs commit -m "Included R1fix" 4420@end example 4421 4422It should be noted that @code{update -j @var{tagname}} will also work but may 4423not produce the desired result. @xref{Merging adds and removals}, for more. 4424 4425@node Merging more than once 4426@section Merging from a branch several times 4427 4428Continuing our example, the revision tree now looks 4429like this: 4430 4431@example 4432+-----+ +-----+ +-----+ +-----+ +-----+ 4433! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4434+-----+ +-----+ +-----+ +-----+ +-----+ 4435 ! * 4436 ! * 4437 ! +---------+ +---------+ 4438Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! 4439 +---------+ +---------+ 4440@end example 4441 4442@noindent 4443where the starred line represents the merge from the 4444@samp{R1fix} branch to the main trunk, as just 4445discussed. 4446 4447Now suppose that development continues on the 4448@samp{R1fix} branch: 4449 4450@example 4451+-----+ +-----+ +-----+ +-----+ +-----+ 4452! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk 4453+-----+ +-----+ +-----+ +-----+ +-----+ 4454 ! * 4455 ! * 4456 ! +---------+ +---------+ +---------+ 4457Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! 4458 +---------+ +---------+ +---------+ 4459@end example 4460 4461@noindent 4462and then you want to merge those new changes onto the 4463main trunk. If you just use the @code{cvs update -j 4464R1fix m.c} command again, @sc{cvs} will attempt to 4465merge again the changes which you have already merged, 4466which can have undesirable side effects. 4467 4468So instead you need to specify that you only want to 4469merge the changes on the branch which have not yet been 4470merged into the trunk. To do that you specify two 4471@samp{-j} options, and @sc{cvs} merges the changes from 4472the first revision to the second revision. For 4473example, in this case the simplest way would be 4474 4475@example 4476cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} 4477 # @r{head of the R1fix branch} 4478@end example 4479 4480The problem with this is that you need to specify the 44811.2.2.2 revision manually. A slightly better approach 4482might be to use the date the last merge was done: 4483 4484@example 4485cvs update -j R1fix:yesterday -j R1fix m.c 4486@end example 4487 4488Better yet, tag the R1fix branch after every merge into 4489the trunk, and then use that tag for subsequent merges: 4490 4491@example 4492cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c 4493@end example 4494 4495@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4496@node Merging two revisions 4497@section Merging differences between any two revisions 4498@cindex Merging two revisions 4499@cindex Revisions, merging differences between 4500@cindex Differences, merging 4501 4502With two @samp{-j @var{revision}} flags, the @code{update} 4503(and @code{checkout}) command can merge the differences 4504between any two revisions into your working file. 4505 4506@cindex Undoing a change 4507@cindex Removing a change 4508@example 4509$ cvs update -j 1.5 -j 1.3 backend.c 4510@end example 4511 4512@noindent 4513will undo all changes made between revision 45141.3 and 1.5. Note the order of the revisions! 4515 4516If you try to use this option when operating on 4517multiple files, remember that the numeric revisions will 4518probably be very different between the various files. 4519You almost always use symbolic 4520tags rather than revision numbers when operating on 4521multiple files. 4522 4523@cindex Restoring old version of removed file 4524@cindex Resurrecting old version of dead file 4525Specifying two @samp{-j} options can also undo file 4526removals or additions. For example, suppose you have 4527a file 4528named @file{file1} which existed as revision 1.1, and 4529you then removed it (thus adding a dead revision 1.2). 4530Now suppose you want to add it again, with the same 4531contents it had previously. Here is how to do it: 4532 4533@example 4534$ cvs update -j 1.2 -j 1.1 file1 4535U file1 4536$ cvs commit -m test 4537Checking in file1; 4538/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 4539new revision: 1.3; previous revision: 1.2 4540done 4541$ 4542@end example 4543 4544@node Merging adds and removals 4545@section Merging can add or remove files 4546 4547If the changes which you are merging involve removing 4548or adding some files, @code{update -j} will reflect 4549such additions or removals. 4550 4551@c FIXME: This example needs a lot more explanation. 4552@c We also need other examples for some of the other 4553@c cases (not all--there are too many--as long as we present a 4554@c coherent general principle). 4555For example: 4556@example 4557cvs update -A 4558touch a b c 4559cvs add a b c ; cvs ci -m "added" a b c 4560cvs tag -b branchtag 4561cvs update -r branchtag 4562touch d ; cvs add d 4563rm a ; cvs rm a 4564cvs ci -m "added d, removed a" 4565cvs update -A 4566cvs update -jbranchtag 4567@end example 4568 4569After these commands are executed and a @samp{cvs commit} is done, 4570file @file{a} will be removed and file @file{d} added in the main branch. 4571@c (which was determined by trying it) 4572 4573Note that using a single static tag (@samp{-j @var{tagname}}) 4574rather than a dynamic tag (@samp{-j @var{branchname}}) to merge 4575changes from a branch will usually not remove files which were removed on the 4576branch since @sc{cvs} does not automatically add static tags to dead revisions. 4577The exception to this rule occurs when 4578a static tag has been attached to a dead revision manually. Use the branch tag 4579to merge all changes from the branch or use two static tags as merge endpoints 4580to be sure that all intended changes are propagated in the merge. 4581 4582@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 4583@node Merging and keywords 4584@section Merging and keywords 4585@cindex Merging, and keyword substitution 4586@cindex Keyword substitution, and merging 4587@cindex -j (merging branches), and keyword substitution 4588@cindex -kk, to avoid conflicts during a merge 4589 4590If you merge files containing keywords (@pxref{Keyword 4591substitution}), you will normally get numerous 4592conflicts during the merge, because the keywords are 4593expanded differently in the revisions which you are 4594merging. 4595 4596Therefore, you will often want to specify the 4597@samp{-kk} (@pxref{Substitution modes}) switch to the 4598merge command line. By substituting just the name of 4599the keyword, not the expanded value of that keyword, 4600this option ensures that the revisions which you are 4601merging will be the same as each other, and avoid 4602spurious conflicts. 4603 4604For example, suppose you have a file like this: 4605 4606@example 4607 +---------+ 4608 _! 1.1.2.1 ! <- br1 4609 / +---------+ 4610 / 4611 / 4612+-----+ +-----+ 4613! 1.1 !----! 1.2 ! 4614+-----+ +-----+ 4615@end example 4616 4617@noindent 4618and your working directory is currently on the trunk 4619(revision 1.2). Then you might get the following 4620results from a merge: 4621 4622@example 4623$ cat file1 4624key $ Revision: 1.2 $ 4625. . . 4626$ cvs update -j br1 4627U file1 4628RCS file: /cvsroot/first-dir/file1,v 4629retrieving revision 1.1 4630retrieving revision 1.1.2.1 4631Merging differences between 1.1 and 1.1.2.1 into file1 4632rcsmerge: warning: conflicts during merge 4633$ cat file1 4634@asis{}<<<<<<< file1 4635key $ Revision: 1.2 $ 4636@asis{}======= 4637key $ Revision: 1.1.2.1 $ 4638@asis{}>>>>>>> 1.1.2.1 4639. . . 4640@end example 4641 4642What happened was that the merge tried to merge the 4643differences between 1.1 and 1.1.2.1 into your working 4644directory. So, since the keyword changed from 4645@code{Revision: 1.1} to @code{Revision: 1.1.2.1}, 4646@sc{cvs} tried to merge that change into your working 4647directory, which conflicted with the fact that your 4648working directory had contained @code{Revision: 1.2}. 4649 4650Here is what happens if you had used @samp{-kk}: 4651 4652@example 4653$ cat file1 4654key $ Revision: 1.2 $ 4655. . . 4656$ cvs update -kk -j br1 4657U file1 4658RCS file: /cvsroot/first-dir/file1,v 4659retrieving revision 1.1 4660retrieving revision 1.1.2.1 4661Merging differences between 1.1 and 1.1.2.1 into file1 4662$ cat file1 4663key $ Revision$ 4664. . . 4665@end example 4666 4667What is going on here is that revision 1.1 and 1.1.2.1 4668both expand as plain @code{Revision}, and therefore 4669merging the changes between them into the working 4670directory need not change anything. Therefore, there 4671is no conflict. 4672 4673@strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a 4674major problem with using @samp{-kk} on merges. Namely, @samp{-kk} 4675overrode any default keyword expansion mode set in the archive file in 4676the repository. This could, unfortunately for some users, cause data 4677corruption in binary files (with a default keyword expansion mode set 4678to @samp{-kb}). Therefore, when a repository contained binary files, 4679conflicts had to be dealt with manually rather than using @samp{-kk} in 4680a merge command.} 4681 4682In @sc{cvs} version 1.12.2 and later, the keyword expansion mode 4683provided on the command line to any @sc{cvs} command no longer 4684overrides the @samp{-kb} keyword expansion mode setting for binary 4685files, though it will still override other default keyword expansion 4686modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts 4687on lines containing RCS keywords, even when your repository contains 4688binary files. 4689 4690@c --------------------------------------------------------------------- 4691@node Recursive behavior 4692@chapter Recursive behavior 4693@cindex Recursive (directory descending) 4694@cindex Directory, descending 4695@cindex Descending directories 4696@cindex Subdirectories 4697 4698Almost all of the subcommands of @sc{cvs} work 4699recursively when you specify a directory as an 4700argument. For instance, consider this directory 4701structure: 4702 4703@example 4704 @code{$HOME} 4705 | 4706 +--@t{tc} 4707 | | 4708 +--@t{CVS} 4709 | (internal @sc{cvs} files) 4710 +--@t{Makefile} 4711 +--@t{backend.c} 4712 +--@t{driver.c} 4713 +--@t{frontend.c} 4714 +--@t{parser.c} 4715 +--@t{man} 4716 | | 4717 | +--@t{CVS} 4718 | | (internal @sc{cvs} files) 4719 | +--@t{tc.1} 4720 | 4721 +--@t{testing} 4722 | 4723 +--@t{CVS} 4724 | (internal @sc{cvs} files) 4725 +--@t{testpgm.t} 4726 +--@t{test2.t} 4727@end example 4728 4729@noindent 4730If @file{tc} is the current working directory, the 4731following is true: 4732 4733@itemize @bullet 4734@item 4735@samp{cvs update testing} is equivalent to 4736 4737@example 4738cvs update testing/testpgm.t testing/test2.t 4739@end example 4740 4741@item 4742@samp{cvs update testing man} updates all files in the 4743subdirectories 4744 4745@item 4746@samp{cvs update .} or just @samp{cvs update} updates 4747all files in the @code{tc} directory 4748@end itemize 4749 4750If no arguments are given to @code{update} it will 4751update all files in the current working directory and 4752all its subdirectories. In other words, @file{.} is a 4753default argument to @code{update}. This is also true 4754for most of the @sc{cvs} subcommands, not only the 4755@code{update} command. 4756 4757The recursive behavior of the @sc{cvs} subcommands can be 4758turned off with the @samp{-l} option. 4759Conversely, the @samp{-R} option can be used to force recursion if 4760@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 4761 4762@example 4763$ cvs update -l # @r{Don't update files in subdirectories} 4764@end example 4765 4766@c --------------------------------------------------------------------- 4767@node Adding and removing 4768@chapter Adding, removing, and renaming files and directories 4769 4770In the course of a project, one will often add new 4771files. Likewise with removing or renaming, or with 4772directories. The general concept to keep in mind in 4773all these cases is that instead of making an 4774irreversible change you want @sc{cvs} to record the 4775fact that a change has taken place, just as with 4776modifying an existing file. The exact mechanisms to do 4777this in @sc{cvs} vary depending on the situation. 4778 4779@menu 4780* Adding files:: Adding files 4781* Removing files:: Removing files 4782* Removing directories:: Removing directories 4783* Moving files:: Moving and renaming files 4784* Moving directories:: Moving and renaming directories 4785@end menu 4786 4787@node Adding files 4788@section Adding files to a directory 4789@cindex Adding files 4790 4791To add a new file to a directory, follow these steps. 4792 4793@itemize @bullet 4794@item 4795You must have a working copy of the directory. 4796@xref{Getting the source}. 4797 4798@item 4799Create the new file inside your working copy of the directory. 4800 4801@item 4802Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you 4803want to version control the file. If the file contains 4804binary data, specify @samp{-kb} (@pxref{Binary files}). 4805 4806@item 4807Use @samp{cvs commit @var{filename}} to actually check 4808in the file into the repository. Other developers 4809cannot see the file until you perform this step. 4810@end itemize 4811 4812You can also use the @code{add} command to add a new 4813directory. 4814@c FIXCVS and/or FIXME: Adding a directory doesn't 4815@c require the commit step. This probably can be 4816@c considered a CVS bug, but it is possible we should 4817@c warn people since this behavior probably won't be 4818@c changing right away. 4819 4820Unlike most other commands, the @code{add} command is 4821not recursive. You cannot even type @samp{cvs add 4822foo/bar}! Instead, you have to 4823@c FIXCVS: This is, of course, not a feature. It is 4824@c just that no one has gotten around to fixing "cvs add 4825@c foo/bar". 4826 4827@example 4828$ cd foo 4829$ cvs add bar 4830@end example 4831 4832@cindex add (subcommand) 4833@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{} 4834 4835Schedule @var{files} to be added to the repository. 4836The files or directories specified with @code{add} must 4837already exist in the current directory. To add a whole 4838new directory hierarchy to the source repository (for 4839example, files received from a third-party vendor), use 4840the @code{import} command instead. @xref{import}. 4841 4842The added files are not placed in the source repository 4843until you use @code{commit} to make the change 4844permanent. Doing an @code{add} on a file that was 4845removed with the @code{remove} command will undo the 4846effect of the @code{remove}, unless a @code{commit} 4847command intervened. @xref{Removing files}, for an 4848example. 4849 4850The @samp{-k} option specifies the default way that 4851this file will be checked out; for more information see 4852@ref{Substitution modes}. 4853 4854@c As noted in BUGS, -m is broken client/server (Nov 4855@c 96). Also see testsuite log2-* tests. 4856The @samp{-m} option specifies a description for the 4857file. This description appears in the history log (if 4858it is enabled, @pxref{history file}). It will also be 4859saved in the version history inside the repository when 4860the file is committed. The @code{log} command displays 4861this description. The description can be changed using 4862@samp{admin -t}. @xref{admin}. If you omit the 4863@samp{-m @var{description}} flag, an empty string will 4864be used. You will not be prompted for a description. 4865@end deffn 4866 4867For example, the following commands add the file 4868@file{backend.c} to the repository: 4869 4870@c This example used to specify 4871@c -m "Optimizer and code generation passes." 4872@c to the cvs add command, but that doesn't work 4873@c client/server (see log2 in sanity.sh). Should fix CVS, 4874@c but also seems strange to document things which 4875@c don't work... 4876@example 4877$ cvs add backend.c 4878$ cvs commit -m "Early version. Not yet compilable." backend.c 4879@end example 4880 4881When you add a file it is added only on the branch 4882which you are working on (@pxref{Branching and merging}). You can 4883later merge the additions to another branch if you want 4884(@pxref{Merging adds and removals}). 4885@c Should we mention that earlier versions of CVS 4886@c lacked this feature (1.3) or implemented it in a buggy 4887@c way (well, 1.8 had many bugs in cvs update -j)? 4888@c Should we mention the bug/limitation regarding a 4889@c file being a regular file on one branch and a directory 4890@c on another? 4891@c FIXME: This needs an example, or several, here or 4892@c elsewhere, for it to make much sense. 4893@c Somewhere we need to discuss the aspects of death 4894@c support which don't involve branching, I guess. 4895@c Like the ability to re-create a release from a tag. 4896 4897@c --------------------------------------------------------------------- 4898@node Removing files 4899@section Removing files 4900@cindex Removing files 4901@cindex Deleting files 4902 4903@c FIXME: this node wants to be split into several 4904@c smaller nodes. Could make these children of 4905@c "Adding and removing", probably (death support could 4906@c be its own section, for example, as could the 4907@c various bits about undoing mistakes in adding and 4908@c removing). 4909Directories change. New files are added, and old files 4910disappear. Still, you want to be able to retrieve an 4911exact copy of old releases. 4912 4913Here is what you can do to remove a file, 4914but remain able to retrieve old revisions: 4915 4916@itemize @bullet 4917@c FIXME: should probably be saying something about 4918@c having a working directory in the first place. 4919@item 4920Make sure that you have not made any uncommitted 4921modifications to the file. @xref{Viewing differences}, 4922for one way to do that. You can also use the 4923@code{status} or @code{update} command. If you remove 4924the file without committing your changes, you will of 4925course not be able to retrieve the file as it was 4926immediately before you deleted it. 4927 4928@item 4929Remove the file from your working copy of the directory. 4930You can for instance use @code{rm}. 4931 4932@item 4933Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that 4934you really want to delete the file. 4935 4936@item 4937Use @samp{cvs commit @var{filename}} to actually 4938perform the removal of the file from the repository. 4939@end itemize 4940 4941@c FIXME: Somehow this should be linked in with a more 4942@c general discussion of death support. I don't know 4943@c whether we want to use the term "death support" or 4944@c not (we can perhaps get by without it), but we do 4945@c need to discuss the "dead" state in "cvs log" and 4946@c related subjects. The current discussion is 4947@c scattered around, and not xref'd to each other. 4948@c FIXME: I think this paragraph wants to be moved 4949@c later down, at least after the first example. 4950When you commit the removal of the file, @sc{cvs} 4951records the fact that the file no longer exists. It is 4952possible for a file to exist on only some branches and 4953not on others, or to re-add another file with the same 4954name later. @sc{cvs} will correctly create or not create 4955the file, based on the @samp{-r} and @samp{-D} options 4956specified to @code{checkout} or @code{update}. 4957 4958@c FIXME: This style seems to clash with how we 4959@c document things in general. 4960@cindex Remove (subcommand) 4961@deffn Command {cvs remove} [options] files @dots{} 4962 4963Schedule file(s) to be removed from the repository 4964(files which have not already been removed from the 4965working directory are not processed). This command 4966does not actually remove the file from the repository 4967until you commit the removal. For a full list of 4968options, see @ref{Invoking CVS}. 4969@end deffn 4970 4971Here is an example of removing several files: 4972 4973@example 4974$ cd test 4975$ rm *.c 4976$ cvs remove 4977cvs remove: Removing . 4978cvs remove: scheduling a.c for removal 4979cvs remove: scheduling b.c for removal 4980cvs remove: use 'cvs commit' to remove these files permanently 4981$ cvs ci -m "Removed unneeded files" 4982cvs commit: Examining . 4983cvs commit: Committing . 4984@end example 4985 4986As a convenience you can remove the file and @code{cvs 4987remove} it in one step, by specifying the @samp{-f} 4988option. For example, the above example could also be 4989done like this: 4990 4991@example 4992$ cd test 4993$ cvs remove -f *.c 4994cvs remove: scheduling a.c for removal 4995cvs remove: scheduling b.c for removal 4996cvs remove: use 'cvs commit' to remove these files permanently 4997$ cvs ci -m "Removed unneeded files" 4998cvs commit: Examining . 4999cvs commit: Committing . 5000@end example 5001 5002If you execute @code{remove} for a file, and then 5003change your mind before you commit, you can undo the 5004@code{remove} with an @code{add} command. 5005 5006@c FIXME: what if you change your mind after you commit 5007@c it? (answer is also "cvs add" but we don't say that...). 5008@c We need some index entries for thinks like "undoing 5009@c removal" too. 5010 5011@example 5012$ ls 5013CVS ja.h oj.c 5014$ rm oj.c 5015$ cvs remove oj.c 5016cvs remove: scheduling oj.c for removal 5017cvs remove: use 'cvs commit' to remove this file permanently 5018$ cvs add oj.c 5019U oj.c 5020cvs add: oj.c, version 1.1.1.1, resurrected 5021@end example 5022 5023If you realize your mistake before you run the 5024@code{remove} command you can use @code{update} to 5025resurrect the file: 5026 5027@example 5028$ rm oj.c 5029$ cvs update oj.c 5030cvs update: warning: oj.c was lost 5031U oj.c 5032@end example 5033 5034When you remove a file it is removed only on the branch 5035which you are working on (@pxref{Branching and merging}). You can 5036later merge the removals to another branch if you want 5037(@pxref{Merging adds and removals}). 5038 5039@node Removing directories 5040@section Removing directories 5041@cindex Removing directories 5042@cindex Directories, removing 5043 5044In concept removing directories is somewhat similar to 5045removing files---you want the directory to not exist in 5046your current working directories, but you also want to 5047be able to retrieve old releases in which the directory 5048existed. 5049 5050The way that you remove a directory is to remove all 5051the files in it. You don't remove the directory 5052itself; there is no way to do that. 5053Instead you specify the @samp{-P} option to 5054@code{cvs update} or @code{cvs checkout}, 5055which will cause @sc{cvs} to remove empty 5056directories from working directories. 5057(Note that @code{cvs export} always removes empty directories.) 5058Probably the 5059best way to do this is to always specify @samp{-P}; if 5060you want an empty directory then put a dummy file (for 5061example @file{.keepme}) in it to prevent @samp{-P} from 5062removing it. 5063 5064@c I'd try to give a rationale for this, but I'm not 5065@c sure there is a particularly convincing one. What 5066@c we would _like_ is for CVS to do a better job of version 5067@c controlling whether directories exist, to eliminate the 5068@c need for -P and so that a file can be a directory in 5069@c one revision and a regular file in another. 5070Note that @samp{-P} is implied by the @samp{-r} or @samp{-D} 5071options of @code{checkout}. This way 5072@sc{cvs} will be able to correctly create the directory 5073or not depending on whether the particular version you 5074are checking out contains any files in that directory. 5075 5076@c --------------------------------------------------------------------- 5077@node Moving files 5078@section Moving and renaming files 5079@cindex Moving files 5080@cindex Renaming files 5081@cindex Files, moving 5082 5083Moving files to a different directory or renaming them 5084is not difficult, but some of the ways in which this 5085works may be non-obvious. (Moving or renaming a 5086directory is even harder. @xref{Moving directories}.). 5087 5088The examples below assume that the file @var{old} is renamed to 5089@var{new}. 5090 5091@menu 5092* Outside:: The normal way to Rename 5093* Inside:: A tricky, alternative way 5094* Rename by copying:: Another tricky, alternative way 5095@end menu 5096 5097@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5098@node Outside 5099@subsection The Normal way to Rename 5100 5101@c More rename issues. Not sure whether these are 5102@c worth documenting; I'm putting them here because 5103@c it seems to be as good a place as any to try to 5104@c set down the issues. 5105@c * "cvs annotate" will annotate either the new 5106@c file or the old file; it cannot annotate _each 5107@c line_ based on whether it was last changed in the 5108@c new or old file. Unlike "cvs log", where the 5109@c consequences of having to select either the new 5110@c or old name seem fairly benign, this may be a 5111@c real advantage to having CVS know about renames 5112@c other than as a deletion and an addition. 5113 5114The normal way to move a file is to copy @var{old} to 5115@var{new}, and then issue the normal @sc{cvs} commands 5116to remove @var{old} from the repository, and add 5117@var{new} to it. 5118@c The following sentence is not true: one must cd into 5119@c the directory to run "cvs add". 5120@c (Both @var{old} and @var{new} could 5121@c contain relative paths, for example @file{foo/bar.c}). 5122 5123@example 5124$ mv @var{old} @var{new} 5125$ cvs remove @var{old} 5126$ cvs add @var{new} 5127$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} 5128@end example 5129 5130This is the simplest way to move a file, it is not 5131error-prone, and it preserves the history of what was 5132done. Note that to access the history of the file you 5133must specify the old or the new name, depending on what 5134portion of the history you are accessing. For example, 5135@code{cvs log @var{old}} will give the log up until the 5136time of the rename. 5137 5138When @var{new} is committed its revision numbers will 5139start again, usually at 1.1, so if that bothers you, 5140use the @samp{-r rev} option to commit. For more 5141information see @ref{Assigning revisions}. 5142 5143@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5144@node Inside 5145@subsection Moving the history file 5146 5147This method is more dangerous, since it involves moving 5148files inside the repository. Read this entire section 5149before trying it out! 5150 5151@example 5152$ cd $CVSROOT/@var{dir} 5153$ mv @var{old},v @var{new},v 5154@end example 5155 5156@noindent 5157Advantages: 5158 5159@itemize @bullet 5160@item 5161The log of changes is maintained intact. 5162 5163@item 5164The revision numbers are not affected. 5165@end itemize 5166 5167@noindent 5168Disadvantages: 5169 5170@itemize @bullet 5171@item 5172Old releases cannot easily be fetched from the 5173repository. (The file will show up as @var{new} even 5174in revisions from the time before it was renamed). 5175 5176@item 5177There is no log information of when the file was renamed. 5178 5179@item 5180Nasty things might happen if someone accesses the history file 5181while you are moving it. Make sure no one else runs any of the @sc{cvs} 5182commands while you move it. 5183@end itemize 5184 5185@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5186@node Rename by copying 5187@subsection Copying the history file 5188 5189This way also involves direct modifications to the 5190repository. It is safe, but not without drawbacks. 5191 5192@example 5193# @r{Copy the @sc{rcs} file inside the repository} 5194$ cd $CVSROOT/@var{dir} 5195$ cp @var{old},v @var{new},v 5196# @r{Remove the old file} 5197$ cd ~/@var{dir} 5198$ rm @var{old} 5199$ cvs remove @var{old} 5200$ cvs commit @var{old} 5201# @r{Remove all tags from @var{new}} 5202$ cvs update @var{new} 5203$ cvs log @var{new} # @r{Remember the non-branch tag names} 5204$ cvs tag -d @var{tag1} @var{new} 5205$ cvs tag -d @var{tag2} @var{new} 5206@dots{} 5207@end example 5208 5209By removing the tags you will be able to check out old 5210revisions. 5211 5212@noindent 5213Advantages: 5214 5215@itemize @bullet 5216@item 5217@c FIXME: Is this true about -D now that we have death 5218@c support? See 5B.3 in the FAQ. 5219Checking out old revisions works correctly, as long as 5220you use @samp{-r@var{tag}} and not @samp{-D@var{date}} 5221to retrieve the revisions. 5222 5223@item 5224The log of changes is maintained intact. 5225 5226@item 5227The revision numbers are not affected. 5228@end itemize 5229 5230@noindent 5231Disadvantages: 5232 5233@itemize @bullet 5234@item 5235You cannot easily see the history of the file across the rename. 5236 5237@end itemize 5238 5239@c --------------------------------------------------------------------- 5240@node Moving directories 5241@section Moving and renaming directories 5242@cindex Moving directories 5243@cindex Renaming directories 5244@cindex Directories, moving 5245 5246The normal way to rename or move a directory is to 5247rename or move each file within it as described in 5248@ref{Outside}. Then check out with the @samp{-P} 5249option, as described in @ref{Removing directories}. 5250 5251If you really want to hack the repository to rename or 5252delete a directory in the repository, you can do it 5253like this: 5254 5255@enumerate 5256@item 5257Inform everyone who has a checked out copy of the directory that the 5258directory will be renamed. They should commit all 5259their changes, and remove their working copies, 5260before you take the steps below. 5261 5262@item 5263Rename the directory inside the repository. 5264 5265@example 5266$ cd $CVSROOT/@var{parent-dir} 5267$ mv @var{old-dir} @var{new-dir} 5268@end example 5269 5270@item 5271Fix the @sc{cvs} administrative files, if necessary (for 5272instance if you renamed an entire module). 5273 5274@item 5275Tell everyone that they can check out again and continue 5276working. 5277 5278@end enumerate 5279 5280If someone had a working copy the @sc{cvs} commands will 5281cease to work for him, until he removes the directory 5282that disappeared inside the repository. 5283 5284It is almost always better to move the files in the 5285directory instead of moving the directory. If you move the 5286directory you are unlikely to be able to retrieve old 5287releases correctly, since they probably depend on the 5288name of the directories. 5289 5290@c --------------------------------------------------------------------- 5291@node History browsing 5292@chapter History browsing 5293@cindex History browsing 5294@cindex Traceability 5295@cindex Isolation 5296 5297 5298@c kind of lame, in a lot of ways the above text inside 5299@c the @ignore motivates this chapter better 5300Once you have used @sc{cvs} to store a version control 5301history---what files have changed when, how, and by 5302whom, there are a variety of mechanisms for looking 5303through the history. 5304 5305@c FIXME: should also be talking about how you look at 5306@c old revisions (e.g. "cvs update -p -r 1.2 foo.c"). 5307@menu 5308* log messages:: Log messages 5309* history database:: The history database 5310* user-defined logging:: User-defined logging 5311* annotate:: What revision modified each line of a file? 5312@end menu 5313 5314@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5315@node log messages 5316@section Log messages 5317 5318@c FIXME: @xref to place where we talk about how to 5319@c specify message to commit. 5320Whenever you commit a file you specify a log message. 5321 5322@c FIXME: bring the information here, and get rid of or 5323@c greatly shrink the "log" node. 5324To look through the log messages which have been 5325specified for every revision which has been committed, 5326use the @code{cvs log} command (@pxref{log}). 5327 5328@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5329@node history database 5330@section The history database 5331 5332@c FIXME: bring the information from the history file 5333@c and history nodes here. Rewrite it to be motivated 5334@c better (start out by clearly explaining what gets 5335@c logged in history, for example). 5336You can use the history file (@pxref{history file}) to 5337log various @sc{cvs} actions. To retrieve the 5338information from the history file, use the @code{cvs 5339history} command (@pxref{history}). 5340 5341Note: you can control what is logged to this file by using the 5342@samp{LogHistory} keyword in the @file{CVSROOT/config} file 5343(@pxref{config}). 5344 5345@c 5346@c The history database has many problems: 5347@c * It is very unclear what field means what. This 5348@c could be improved greatly by better documentation, 5349@c but there are still non-orthogonalities (for 5350@c example, tag does not record the "repository" 5351@c field but most records do). 5352@c * Confusion about files, directories, and modules. 5353@c Some commands record one, some record others. 5354@c * File removal is not logged. There is an 'R' 5355@c record type documented, but CVS never uses it. 5356@c * Tags are only logged for the "cvs rtag" command, 5357@c not "cvs tag". The fix for this is not completely 5358@c clear (see above about modules vs. files). 5359@c * Are there other cases of operations that are not 5360@c logged? One would hope for all changes to the 5361@c repository to be logged somehow (particularly 5362@c operations like tagging, "cvs admin -k", and other 5363@c operations which do not record a history that one 5364@c can get with "cvs log"). Operations on the working 5365@c directory, like export, get, and release, are a 5366@c second category also covered by the current "cvs 5367@c history". 5368@c * The history file does not record the options given 5369@c to a command. The most serious manifestation of 5370@c this is perhaps that it doesn't record whether a command 5371@c was recursive. It is not clear to me whether one 5372@c wants to log at a level very close to the command 5373@c line, as a sort of way of logging each command 5374@c (more or less), or whether one wants 5375@c to log more at the level of what was changed (or 5376@c something in between), but either way the current 5377@c information has pretty big gaps. 5378@c * Further details about a tag--like whether it is a 5379@c branch tag or, if a non-branch tag, which branch it 5380@c is on. One can find out this information about the 5381@c tag as it exists _now_, but if the tag has been 5382@c moved, one doesn't know what it was like at the time 5383@c the history record was written. 5384@c * Whether operating on a particular tag, date, or 5385@c options was implicit (sticky) or explicit. 5386@c 5387@c Another item, only somewhat related to the above, is a 5388@c way to control what is logged in the history file. 5389@c This is probably the only good way to handle 5390@c different people having different ideas about 5391@c information/space tradeoffs. 5392@c 5393@c It isn't really clear that it makes sense to try to 5394@c patch up the history file format as it exists now to 5395@c include all that stuff. It might be better to 5396@c design a whole new CVSROOT/nhistory file and "cvs 5397@c nhistory" command, or some such, or in some other 5398@c way trying to come up with a clean break from the 5399@c past, which can address the above concerns. Another 5400@c open question is how/whether this relates to 5401@c taginfo/loginfo/etc. 5402 5403@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5404@node user-defined logging 5405@section User-defined logging 5406 5407@c FIXME: should probably also mention the fact the -l 5408@c global option can disable most of the mechanisms 5409@c discussed here (why? What is the -l global option for?). 5410@c 5411@c FIXME: probably should centralize this information 5412@c here, at least to some extent. Maybe by moving the 5413@c loginfo, etc., nodes here and replacing 5414@c the "user-defined logging" node with one node for 5415@c each method. 5416You can customize @sc{cvs} to log various kinds of 5417actions, in whatever manner you choose. These 5418mechanisms operate by executing a script at various 5419times. The script might append a message to a file 5420listing the information and the programmer who created 5421it, or send mail to a group of developers, or, perhaps, 5422post a message to a particular newsgroup. To log 5423commits, use the @file{loginfo} file (@pxref{loginfo}). 5424@c FIXME: What is difference between doing it in the 5425@c modules file and using loginfo/taginfo? Why should 5426@c user use one or the other? 5427To log commits, checkouts, exports, and tags, 5428respectively, you can also use the @samp{-i}, 5429@samp{-o}, @samp{-e}, and @samp{-t} options in the 5430modules file. For a more flexible way of giving 5431notifications to various users, which requires less in 5432the way of keeping centralized scripts up to date, use 5433the @code{cvs watch add} command (@pxref{Getting 5434Notified}); this command is useful even if you are not 5435using @code{cvs watch on}. 5436 5437@cindex taginfo 5438@cindex Exit status, of taginfo 5439The @file{taginfo} file defines programs to execute 5440when someone executes a @code{tag} or @code{rtag} 5441command. The @file{taginfo} file has the standard form 5442for administrative files (@pxref{Administrative 5443files}), where each line is a regular expression 5444followed by a command to execute. The arguments passed 5445to the command are, in order, the @var{tagname}, 5446@var{operation} (@code{add} for @code{tag}, 5447@code{mov} for @code{tag -F}, and @code{del} for 5448@code{tag -d}), @var{repository}, and any remaining are 5449pairs of @var{filename} @var{revision}. A non-zero 5450exit of the filter program will cause the tag to be 5451aborted. 5452 5453Here is an example of using taginfo to log tag and rtag 5454commands. In the taginfo file put: 5455 5456@example 5457ALL /usr/local/cvsroot/CVSROOT/loggit 5458@end example 5459 5460@noindent 5461Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the 5462following script: 5463 5464@example 5465#!/bin/sh 5466echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog 5467@end example 5468 5469@node annotate 5470@section Annotate command 5471@cindex annotate (subcommand) 5472 5473@deffn Command {cvs annotate} [@code{-FflR}] [@code{-r rev}|@code{-D date}] files @dots{} 5474 5475For each file in @var{files}, print the head revision 5476of the trunk, together with information on the last 5477modification for each line. For example: 5478 5479@example 5480$ cvs annotate ssfile 5481Annotations for ssfile 5482*************** 54831.1 (mary 27-Mar-96): ssfile line 1 54841.2 (joe 28-Mar-96): ssfile line 2 5485@end example 5486 5487The file @file{ssfile} currently contains two lines. 5488The @code{ssfile line 1} line was checked in by 5489@code{mary} on March 27. Then, on March 28, @code{joe} 5490added a line @code{ssfile line 2}, without modifying 5491the @code{ssfile line 1} line. This report doesn't 5492tell you anything about lines which have been deleted 5493or replaced; you need to use @code{cvs diff} for that 5494(@pxref{diff}). 5495 5496@end deffn 5497 5498The options to @code{cvs annotate} are listed in 5499@ref{Invoking CVS}, and can be used to select the files 5500and revisions to annotate. The options are described 5501in more detail there and in @ref{Common options}. 5502 5503@c FIXME: maybe an example using the options? Just 5504@c what it means to select a revision might be worth a 5505@c few words of explanation ("you want to see who 5506@c changed this line *before* 1.4"...). 5507 5508@c --------------------------------------------------------------------- 5509@node Binary files 5510@chapter Handling binary files 5511@cindex Binary files 5512 5513The most common use for @sc{cvs} is to store text 5514files. With text files, @sc{cvs} can merge revisions, 5515display the differences between revisions in a 5516human-visible fashion, and other such operations. 5517However, if you are willing to give up a few of these 5518abilities, @sc{cvs} can store binary files. For 5519example, one might store a web site in @sc{cvs} 5520including both text files and binary images. 5521 5522@menu 5523* Binary why:: More details on issues with binary files 5524* Binary howto:: How to store them 5525@end menu 5526 5527@node Binary why 5528@section The issues with binary files 5529 5530While the need to manage binary files may seem obvious 5531if the files that you customarily work with are binary, 5532putting them into version control does present some 5533additional issues. 5534 5535One basic function of version control is to show the 5536differences between two revisions. For example, if 5537someone else checked in a new version of a file, you 5538may wish to look at what they changed and determine 5539whether their changes are good. For text files, 5540@sc{cvs} provides this functionality via the @code{cvs 5541diff} command. For binary files, it may be possible to 5542extract the two revisions and then compare them with a 5543tool external to @sc{cvs} (for example, word processing 5544software often has such a feature). If there is no 5545such tool, one must track changes via other mechanisms, 5546such as urging people to write good log messages, and 5547hoping that the changes they actually made were the 5548changes that they intended to make. 5549 5550Another ability of a version control system is the 5551ability to merge two revisions. For @sc{cvs} this 5552happens in two contexts. The first is when users make 5553changes in separate working directories 5554(@pxref{Multiple developers}). The second is when one 5555merges explicitly with the @samp{update -j} command 5556(@pxref{Branching and merging}). 5557 5558In the case of text 5559files, @sc{cvs} can merge changes made independently, 5560and signal a conflict if the changes conflict. With 5561binary files, the best that @sc{cvs} can do is present 5562the two different copies of the file, and leave it to 5563the user to resolve the conflict. The user may choose 5564one copy or the other, or may run an external merge 5565tool which knows about that particular file format, if 5566one exists. 5567Note that having the user merge relies primarily on the 5568user to not accidentally omit some changes, and thus is 5569potentially error prone. 5570 5571If this process is thought to be undesirable, the best 5572choice may be to avoid merging. To avoid the merges 5573that result from separate working directories, see the 5574discussion of reserved checkouts (file locking) in 5575@ref{Multiple developers}. To avoid the merges 5576resulting from branches, restrict use of branches. 5577 5578@node Binary howto 5579@section How to store binary files 5580 5581There are two issues with using @sc{cvs} to store 5582binary files. The first is that @sc{cvs} by default 5583converts line endings between the canonical form in 5584which they are stored in the repository (linefeed 5585only), and the form appropriate to the operating system 5586in use on the client (for example, carriage return 5587followed by line feed for Windows NT). 5588 5589The second is that a binary file might happen to 5590contain data which looks like a keyword (@pxref{Keyword 5591substitution}), so keyword expansion must be turned 5592off. 5593 5594@c FIXME: the third is that one can't do merges with 5595@c binary files. xref to Multiple Developers and the 5596@c reserved checkout issues. 5597 5598The @samp{-kb} option available with some @sc{cvs} 5599commands insures that neither line ending conversion 5600nor keyword expansion will be done. 5601 5602Here is an example of how you can create a new file 5603using the @samp{-kb} flag: 5604 5605@example 5606$ echo '$ Id$' > kotest 5607$ cvs add -kb -m"A test file" kotest 5608$ cvs ci -m"First checkin; contains a keyword" kotest 5609@end example 5610 5611If a file accidentally gets added without @samp{-kb}, 5612one can use the @code{cvs admin} command to recover. 5613For example: 5614 5615@example 5616$ echo '$ Id$' > kotest 5617$ cvs add -m"A test file" kotest 5618$ cvs ci -m"First checkin; contains a keyword" kotest 5619$ cvs admin -kb kotest 5620$ cvs update -A kotest 5621# @r{For non-unix systems:} 5622# @r{Copy in a good copy of the file from outside CVS} 5623$ cvs commit -m "make it binary" kotest 5624@end example 5625 5626@c Trying to describe this for both unix and non-unix 5627@c in the same description is very confusing. Might 5628@c want to split the two, or just ditch the unix "shortcut" 5629@c (unixheads don't do much with binary files, anyway). 5630@c This used to say "(Try the above example, and do a 5631@c @code{cat kotest} after every command)". But that 5632@c only really makes sense for the unix case. 5633When you check in the file @file{kotest} the file is 5634not preserved as a binary file, because you did not 5635check it in as a binary file. The @code{cvs 5636admin -kb} command sets the default keyword 5637substitution method for this file, but it does not 5638alter the working copy of the file that you have. If you need to 5639cope with line endings (that is, you are using 5640@sc{cvs} on a non-unix system), then you need to 5641check in a new copy of the file, as shown by the 5642@code{cvs commit} command above. 5643On unix, the @code{cvs update -A} command suffices. 5644@c FIXME: should also describe what the *other users* 5645@c need to do, if they have checked out copies which 5646@c have been corrupted by lack of -kb. I think maybe 5647@c "cvs update -kb" or "cvs 5648@c update -A" would suffice, although the user who 5649@c reported this suggested removing the file, manually 5650@c removing it from CVS/Entries, and then "cvs update" 5651(Note that you can use @code{cvs log} to determine the default keyword 5652substitution method for a file and @code{cvs status} to determine 5653the keyword substitution method for a working copy.) 5654 5655However, in using @code{cvs admin -k} to change the 5656keyword expansion, be aware that the keyword expansion 5657mode is not version controlled. This means that, for 5658example, that if you have a text file in old releases, 5659and a binary file with the same name in new releases, 5660@sc{cvs} provides no way to check out the file in text 5661or binary mode depending on what version you are 5662checking out. There is no good workaround for this 5663problem. 5664 5665You can also set a default for whether @code{cvs add} 5666and @code{cvs import} treat a file as binary based on 5667its name; for example you could say that files who 5668names end in @samp{.exe} are binary. @xref{Wrappers}. 5669There is currently no way to have @sc{cvs} detect 5670whether a file is binary based on its contents. The 5671main difficulty with designing such a feature is that 5672it is not clear how to distinguish between binary and 5673non-binary files, and the rules to apply would vary 5674considerably with the operating system. 5675@c For example, it would be good on MS-DOS-family OSes 5676@c for anything containing ^Z to be binary. Having 5677@c characters with the 8th bit set imply binary is almost 5678@c surely a bad idea in the context of ISO-8859-* and 5679@c other such character sets. On VMS or the Mac, we 5680@c could use the OS's file typing. This is a 5681@c commonly-desired feature, and something of this sort 5682@c may make sense. But there are a lot of pitfalls here. 5683@c 5684@c Another, probably better, way to tell is to read the 5685@c file in text mode, write it to a temp file in text 5686@c mode, and then do a binary mode compare of the two 5687@c files. If they differ, it is a binary file. This 5688@c might have problems on VMS (or some other system 5689@c with several different text modes), but in general 5690@c should be relatively portable. The only other 5691@c downside I can think of is that it would be fairly 5692@c slow, but that is perhaps a small price to pay for 5693@c not having your files corrupted. Another issue is 5694@c what happens if you import a text file with bare 5695@c linefeeds on Windows. Such files will show up on 5696@c Windows sometimes (I think some native windows 5697@c programs even write them, on occasion). Perhaps it 5698@c is reasonable to treat such files as binary; after 5699@c all it is something of a presumption to assume that 5700@c the user would want the linefeeds converted to CRLF. 5701 5702@c --------------------------------------------------------------------- 5703@node Multiple developers 5704@chapter Multiple developers 5705@cindex Multiple developers 5706@cindex Team of developers 5707@cindex File locking 5708@cindex Locking files 5709@cindex Working copy 5710@cindex Reserved checkouts 5711@cindex Unreserved checkouts 5712@cindex RCS-style locking 5713 5714When more than one person works on a software project 5715things often get complicated. Often, two people try to 5716edit the same file simultaneously. One solution, known 5717as @dfn{file locking} or @dfn{reserved checkouts}, is 5718to allow only one person to edit each file at a time. 5719This is the only solution with some version control 5720systems, including @sc{rcs} and @sc{sccs}. Currently 5721the usual way to get reserved checkouts with @sc{cvs} 5722is the @code{cvs admin -l} command (@pxref{admin 5723options}). This is not as nicely integrated into 5724@sc{cvs} as the watch features, described below, but it 5725seems that most people with a need for reserved 5726checkouts find it adequate. 5727@c Or "find it better than worrying about implementing 5728@c nicely integrated reserved checkouts" or ...? 5729It also may be possible to use the watches 5730features described below, together with suitable 5731procedures (not enforced by software), to avoid having 5732two people edit at the same time. 5733 5734@c Our unreserved checkout model might not 5735@c be quite the same as others. For example, I 5736@c think that some systems will tend to create a branch 5737@c in the case where CVS prints "up-to-date check failed". 5738@c It isn't clear to me whether we should try to 5739@c explore these subtleties; it could easily just 5740@c confuse people. 5741The default model with @sc{cvs} is known as 5742@dfn{unreserved checkouts}. In this model, developers 5743can edit their own @dfn{working copy} of a file 5744simultaneously. The first person that commits his 5745changes has no automatic way of knowing that another 5746has started to edit it. Others will get an error 5747message when they try to commit the file. They must 5748then use @sc{cvs} commands to bring their working copy 5749up to date with the repository revision. This process 5750is almost automatic. 5751 5752@c FIXME? should probably use the word "watch" here, to 5753@c tie this into the text below and above. 5754@sc{cvs} also supports mechanisms which facilitate 5755various kinds of communication, without actually 5756enforcing rules like reserved checkouts do. 5757 5758The rest of this chapter describes how these various 5759models work, and some of the issues involved in 5760choosing between them. 5761 5762 5763@menu 5764* File status:: A file can be in several states 5765* Updating a file:: Bringing a file up-to-date 5766* Conflicts example:: An informative example 5767* Informing others:: To cooperate you must inform 5768* Concurrency:: Simultaneous repository access 5769* Watches:: Mechanisms to track who is editing files 5770* Choosing a model:: Reserved or unreserved checkouts? 5771@end menu 5772 5773@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5774@node File status 5775@section File status 5776@cindex File status 5777@cindex Status of a file 5778 5779@c Shouldn't this start with an example or something, 5780@c introducing the unreserved checkout model? Before we 5781@c dive into listing states? 5782Based on what operations you have performed on a 5783checked out file, and what operations others have 5784performed to that file in the repository, one can 5785classify a file in a number of states. The states, as 5786reported by the @code{status} command, are: 5787 5788@c The order of items is chosen to group logically 5789@c similar outputs together. 5790@c People who want alphabetical can use the index... 5791@table @asis 5792@cindex Up-to-date 5793@item Up-to-date 5794The file is identical with the latest revision in the 5795repository for the branch in use. 5796@c FIXME: should we clarify "in use"? The answer is 5797@c sticky tags, and trying to distinguish branch sticky 5798@c tags from non-branch sticky tags seems rather awkward 5799@c here. 5800@c FIXME: What happens with non-branch sticky tags? Is 5801@c a stuck file "Up-to-date" or "Needs checkout" or what? 5802 5803@item Locally Modified 5804@cindex Locally Modified 5805You have edited the file, and not yet committed your changes. 5806 5807@item Locally Added 5808@cindex Locally Added 5809You have added the file with @code{add}, and not yet 5810committed your changes. 5811@c There are many cases involving the file being 5812@c added/removed/modified in the working directory, and 5813@c added/removed/modified in the repository, which we 5814@c don't try to describe here. I'm not sure that "cvs 5815@c status" produces a non-confusing output in most of 5816@c those cases. 5817 5818@item Locally Removed 5819@cindex Locally Removed 5820You have removed the file with @code{remove}, and not yet 5821committed your changes. 5822 5823@item Needs Checkout 5824@cindex Needs Checkout 5825Someone else has committed a newer revision to the 5826repository. The name is slightly misleading; you will 5827ordinarily use @code{update} rather than 5828@code{checkout} to get that newer revision. 5829 5830@item Needs Patch 5831@cindex Needs Patch 5832@c See also newb-123j0 in sanity.sh (although that case 5833@c should probably be changed rather than documented). 5834Like Needs Checkout, but the @sc{cvs} server will send 5835a patch rather than the entire file. Sending a patch or 5836sending an entire file accomplishes the same thing. 5837 5838@item Needs Merge 5839@cindex Needs Merge 5840Someone else has committed a newer revision to the repository, and you 5841have also made modifications to the file. 5842 5843@item Unresolved Conflict 5844@cindex Unresolved Conflict 5845@c FIXCVS - This file status needs to be changed to some more informative 5846@c text that distinguishes it more clearly from each of the Locally Added, 5847@c File had conflicts on merge, and Unknown status types, but an exact and 5848@c succinct wording escapes me at the moment. 5849A file with the same name as this new file has been added to the repository 5850from a second workspace. This file will need to be moved out of the way 5851to allow an @code{update} to complete. 5852 5853@item File had conflicts on merge 5854@cindex File had conflicts on merge 5855@c is it worth saying that this message was "Unresolved 5856@c Conflict" in CVS 1.9 and earlier? I'm inclined to 5857@c think that is unnecessarily confusing to new users. 5858This is like Locally Modified, except that a previous 5859@code{update} command gave a conflict. If you have not 5860already done so, you need to 5861resolve the conflict as described in @ref{Conflicts example}. 5862 5863@item Unknown 5864@cindex Unknown 5865@sc{cvs} doesn't know anything about this file. For 5866example, you have created a new file and have not run 5867@code{add}. 5868@c 5869@c "Entry Invalid" and "Classify Error" are also in the 5870@c status.c. The latter definitely indicates a CVS bug 5871@c (should it be worded more like "internal error" so 5872@c people submit bug reports if they see it?). The former 5873@c I'm not as sure; I haven't tracked down whether/when it 5874@c appears in "cvs status" output. 5875 5876@end table 5877 5878To help clarify the file status, @code{status} also 5879reports the @code{Working revision} which is the 5880revision that the file in the working directory derives 5881from, and the @code{Repository revision} which is the 5882latest revision in the repository for the branch in 5883use. 5884@c FIXME: should we clarify "in use"? The answer is 5885@c sticky tags, and trying to distinguish branch sticky 5886@c tags from non-branch sticky tags seems rather awkward 5887@c here. 5888@c FIXME: What happens with non-branch sticky tags? 5889@c What is the Repository Revision there? See the 5890@c comment at vn_rcs in cvs.h, which is kind of 5891@c confused--we really need to document better what this 5892@c field contains. 5893@c Q: Should we document "New file!" and other such 5894@c outputs or are they self-explanatory? 5895@c FIXME: what about the date to the right of "Working 5896@c revision"? It doesn't appear with client/server and 5897@c seems unnecessary (redundant with "ls -l") so 5898@c perhaps it should be removed for non-client/server too? 5899@c FIXME: Need some examples. 5900@c FIXME: Working revision can also be something like 5901@c "-1.3" for a locally removed file. Not at all 5902@c self-explanatory (and it is possible that CVS should 5903@c be changed rather than documenting this). 5904 5905@c Would be nice to have an @example showing output 5906@c from cvs status, with comments showing the xref 5907@c where each part of the output is described. This 5908@c might fit in nicely if it is desirable to split this 5909@c node in two; one to introduce "cvs status" and one 5910@c to list each of the states. 5911The options to @code{status} are listed in 5912@ref{Invoking CVS}. For information on its @code{Sticky tag} 5913and @code{Sticky date} output, see @ref{Sticky tags}. 5914For information on its @code{Sticky options} output, 5915see the @samp{-k} option in @ref{update options}. 5916 5917You can think of the @code{status} and @code{update} 5918commands as somewhat complementary. You use 5919@code{update} to bring your files up to date, and you 5920can use @code{status} to give you some idea of what an 5921@code{update} would do (of course, the state of the 5922repository might change before you actually run 5923@code{update}). In fact, if you want a command to 5924display file status in a more brief format than is 5925displayed by the @code{status} command, you can invoke 5926 5927@cindex update, to display file status 5928@example 5929$ cvs -n -q update 5930@end example 5931 5932The @samp{-n} option means to not actually do the 5933update, but merely to display statuses; the @samp{-q} 5934option avoids printing the name of each directory. For 5935more information on the @code{update} command, and 5936these options, see @ref{Invoking CVS}. 5937 5938@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5939@node Updating a file 5940@section Bringing a file up to date 5941@cindex Bringing a file up to date 5942@cindex Updating a file 5943@cindex Merging a file 5944@cindex Update, introduction 5945 5946When you want to update or merge a file, use the @code{update} 5947command. For files that are not up to date this is roughly equivalent 5948to a @code{checkout} command: the newest revision of the file is 5949extracted from the repository and put in your working directory. 5950 5951Your modifications to a file are never lost when you 5952use @code{update}. If no newer revision exists, 5953running @code{update} has no effect. If you have 5954edited the file, and a newer revision is available, 5955@sc{cvs} will merge all changes into your working copy. 5956 5957For instance, imagine that you checked out revision 1.4 and started 5958editing it. In the meantime someone else committed revision 1.5, and 5959shortly after that revision 1.6. If you run @code{update} on the file 5960now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into 5961your file. 5962 5963@cindex Overlap 5964If any of the changes between 1.4 and 1.6 were made too 5965close to any of the changes you have made, an 5966@dfn{overlap} occurs. In such cases a warning is 5967printed, and the resulting file includes both 5968versions of the lines that overlap, delimited by 5969special markers. 5970@xref{update}, for a complete description of the 5971@code{update} command. 5972 5973@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5974@node Conflicts example 5975@section Conflicts example 5976@cindex Merge, an example 5977@cindex Example of merge 5978@cindex driver.c (merge example) 5979 5980Suppose revision 1.4 of @file{driver.c} contains this: 5981 5982@example 5983#include <stdio.h> 5984 5985void main() 5986@{ 5987 parse(); 5988 if (nerr == 0) 5989 gencode(); 5990 else 5991 fprintf(stderr, "No code generated.\n"); 5992 exit(nerr == 0 ? 0 : 1); 5993@} 5994@end example 5995 5996@noindent 5997Revision 1.6 of @file{driver.c} contains this: 5998 5999@example 6000#include <stdio.h> 6001 6002int main(int argc, 6003 char **argv) 6004@{ 6005 parse(); 6006 if (argc != 1) 6007 @{ 6008 fprintf(stderr, "tc: No args expected.\n"); 6009 exit(1); 6010 @} 6011 if (nerr == 0) 6012 gencode(); 6013 else 6014 fprintf(stderr, "No code generated.\n"); 6015 exit(!!nerr); 6016@} 6017@end example 6018 6019@noindent 6020Your working copy of @file{driver.c}, based on revision 60211.4, contains this before you run @samp{cvs update}: 6022@c -- Really include "cvs"? 6023 6024@example 6025#include <stdlib.h> 6026#include <stdio.h> 6027 6028void main() 6029@{ 6030 init_scanner(); 6031 parse(); 6032 if (nerr == 0) 6033 gencode(); 6034 else 6035 fprintf(stderr, "No code generated.\n"); 6036 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6037@} 6038@end example 6039 6040@noindent 6041You run @samp{cvs update}: 6042@c -- Really include "cvs"? 6043 6044@example 6045$ cvs update driver.c 6046RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v 6047retrieving revision 1.4 6048retrieving revision 1.6 6049Merging differences between 1.4 and 1.6 into driver.c 6050rcsmerge warning: overlaps during merge 6051cvs update: conflicts found in driver.c 6052C driver.c 6053@end example 6054 6055@noindent 6056@cindex Conflicts (merge example) 6057@sc{cvs} tells you that there were some conflicts. 6058Your original working file is saved unmodified in 6059@file{.#driver.c.1.4}. The new version of 6060@file{driver.c} contains this: 6061 6062@example 6063#include <stdlib.h> 6064#include <stdio.h> 6065 6066int main(int argc, 6067 char **argv) 6068@{ 6069 init_scanner(); 6070 parse(); 6071 if (argc != 1) 6072 @{ 6073 fprintf(stderr, "tc: No args expected.\n"); 6074 exit(1); 6075 @} 6076 if (nerr == 0) 6077 gencode(); 6078 else 6079 fprintf(stderr, "No code generated.\n"); 6080@asis{}<<<<<<< driver.c 6081 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6082@asis{}======= 6083 exit(!!nerr); 6084@asis{}>>>>>>> 1.6 6085@} 6086@end example 6087 6088@noindent 6089@cindex Markers, conflict 6090@cindex Conflict markers 6091@cindex <<<<<<< 6092@cindex >>>>>>> 6093@cindex ======= 6094 6095Note how all non-overlapping modifications are incorporated in your working 6096copy, and that the overlapping section is clearly marked with 6097@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. 6098 6099@cindex Resolving a conflict 6100@cindex Conflict resolution 6101You resolve the conflict by editing the file, removing the markers and 6102the erroneous line. Suppose you end up with this file: 6103@c -- Add xref to the pcl-cvs manual when it talks 6104@c -- about this. 6105@example 6106#include <stdlib.h> 6107#include <stdio.h> 6108 6109int main(int argc, 6110 char **argv) 6111@{ 6112 init_scanner(); 6113 parse(); 6114 if (argc != 1) 6115 @{ 6116 fprintf(stderr, "tc: No args expected.\n"); 6117 exit(1); 6118 @} 6119 if (nerr == 0) 6120 gencode(); 6121 else 6122 fprintf(stderr, "No code generated.\n"); 6123 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); 6124@} 6125@end example 6126 6127@noindent 6128You can now go ahead and commit this as revision 1.7. 6129 6130@example 6131$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c 6132Checking in driver.c; 6133/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c 6134new revision: 1.7; previous revision: 1.6 6135done 6136@end example 6137 6138For your protection, @sc{cvs} will refuse to check in a 6139file if a conflict occurred and you have not resolved 6140the conflict. Currently to resolve a conflict, you 6141must change the timestamp on the file. In previous 6142versions of @sc{cvs}, you also needed to 6143insure that the file contains no conflict markers. 6144Because 6145your file may legitimately contain conflict markers (that 6146is, occurrences of @samp{>>>>>>> } at the start of a 6147line that don't mark a conflict), the current 6148version of @sc{cvs} will print a warning and proceed to 6149check in the file. 6150@c The old behavior was really icky; the only way out 6151@c was to start hacking on 6152@c the @code{CVS/Entries} file or other such workarounds. 6153@c 6154@c If the timestamp thing isn't considered nice enough, 6155@c maybe there should be a "cvs resolved" command 6156@c which clears the conflict indication. For a nice user 6157@c interface, this should be invoked by an interactive 6158@c merge tool like emerge rather than by the user 6159@c directly--such a tool can verify that the user has 6160@c really dealt with each conflict. 6161 6162@cindex emerge 6163If you use release 1.04 or later of pcl-cvs (a @sc{gnu} 6164Emacs front-end for @sc{cvs}) you can use an Emacs 6165package called emerge to help you resolve conflicts. 6166See the documentation for pcl-cvs. 6167 6168@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6169@node Informing others 6170@section Informing others about commits 6171@cindex Informing others 6172@cindex Spreading information 6173@cindex Mail, automatic mail on commit 6174 6175It is often useful to inform others when you commit a 6176new revision of a file. The @samp{-i} option of the 6177@file{modules} file, or the @file{loginfo} file, can be 6178used to automate this process. @xref{modules}. 6179@xref{loginfo}. You can use these features of @sc{cvs} 6180to, for instance, instruct @sc{cvs} to mail a 6181message to all developers, or post a message to a local 6182newsgroup. 6183@c -- More text would be nice here. 6184 6185@node Concurrency 6186@section Several developers simultaneously attempting to run CVS 6187 6188@cindex Locks, cvs, introduction 6189@c For a discussion of *why* CVS creates locks, see 6190@c the comment at the start of src/lock.c 6191If several developers try to run @sc{cvs} at the same 6192time, one may get the following message: 6193 6194@example 6195[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo 6196@end example 6197 6198@cindex #cvs.rfl, removing 6199@cindex #cvs.wfl, removing 6200@cindex #cvs.lock, removing 6201@sc{cvs} will try again every 30 seconds, and either 6202continue with the operation or print the message again, 6203if it still needs to wait. If a lock seems to stick 6204around for an undue amount of time, find the person 6205holding the lock and ask them about the cvs command 6206they are running. If they aren't running a cvs 6207command, look in the repository directory mentioned in 6208the message and remove files which they own whose names 6209start with @file{#cvs.rfl}, 6210@file{#cvs.wfl}, or @file{#cvs.lock}. 6211 6212Note that these locks are to protect @sc{cvs}'s 6213internal data structures and have no relationship to 6214the word @dfn{lock} in the sense used by 6215@sc{rcs}---which refers to reserved checkouts 6216(@pxref{Multiple developers}). 6217 6218Any number of people can be reading from a given 6219repository at a time; only when someone is writing do 6220the locks prevent other people from reading or writing. 6221 6222@cindex Atomic transactions, lack of 6223@cindex Transactions, atomic, lack of 6224@c the following talks about what one might call commit/update 6225@c atomicity. 6226@c Probably also should say something about 6227@c commit/commit atomicity, that is, "An update will 6228@c not get partial versions of more than one commit". 6229@c CVS currently has this property and I guess we can 6230@c make it a documented feature. 6231@c For example one person commits 6232@c a/one.c and b/four.c and another commits a/two.c and 6233@c b/three.c. Then an update cannot get the new a/one.c 6234@c and a/two.c and the old b/four.c and b/three.c. 6235One might hope for the following property: 6236 6237@quotation 6238If someone commits some changes in one cvs command, 6239then an update by someone else will either get all the 6240changes, or none of them. 6241@end quotation 6242 6243@noindent 6244but @sc{cvs} does @emph{not} have this property. For 6245example, given the files 6246 6247@example 6248a/one.c 6249a/two.c 6250b/three.c 6251b/four.c 6252@end example 6253 6254@noindent 6255if someone runs 6256 6257@example 6258cvs ci a/two.c b/three.c 6259@end example 6260 6261@noindent 6262and someone else runs @code{cvs update} at the same 6263time, the person running @code{update} might get only 6264the change to @file{b/three.c} and not the change to 6265@file{a/two.c}. 6266 6267@node Watches 6268@section Mechanisms to track who is editing files 6269@cindex Watches 6270 6271For many groups, use of @sc{cvs} in its default mode is 6272perfectly satisfactory. Users may sometimes go to 6273check in a modification only to find that another 6274modification has intervened, but they deal with it and 6275proceed with their check in. Other groups prefer to be 6276able to know who is editing what files, so that if two 6277people try to edit the same file they can choose to 6278talk about who is doing what when rather than be 6279surprised at check in time. The features in this 6280section allow such coordination, while retaining the 6281ability of two developers to edit the same file at the 6282same time. 6283 6284@c Some people might ask why CVS does not enforce the 6285@c rule on chmod, by requiring a cvs edit before a cvs 6286@c commit. The main reason is that it could always be 6287@c circumvented--one could edit the file, and 6288@c then when ready to check it in, do the cvs edit and put 6289@c in the new contents and do the cvs commit. One 6290@c implementation note: if we _do_ want to have cvs commit 6291@c require a cvs edit, we should store the state on 6292@c whether the cvs edit has occurred in the working 6293@c directory, rather than having the server try to keep 6294@c track of what working directories exist. 6295@c FIXME: should the above discussion be part of the 6296@c manual proper, somewhere, not just in a comment? 6297For maximum benefit developers should use @code{cvs 6298edit} (not @code{chmod}) to make files read-write to 6299edit them, and @code{cvs release} (not @code{rm}) to 6300discard a working directory which is no longer in use, 6301but @sc{cvs} is not able to enforce this behavior. 6302 6303@c I'm a little dissatisfied with this presentation, 6304@c because "watch on"/"edit"/"editors" are one set of 6305@c functionality, and "watch add"/"watchers" is another 6306@c which is somewhat orthogonal even though they interact in 6307@c various ways. But I think it might be 6308@c confusing to describe them separately (e.g. "watch 6309@c add" with loginfo). I don't know. 6310 6311@menu 6312* Setting a watch:: Telling CVS to watch certain files 6313* Getting Notified:: Telling CVS to notify you 6314* Editing files:: How to edit a file which is being watched 6315* Watch information:: Information about who is watching and editing 6316* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier 6317@end menu 6318 6319@node Setting a watch 6320@subsection Telling CVS to watch certain files 6321 6322To enable the watch features, you first specify that 6323certain files are to be watched. 6324 6325@cindex watch on (subcommand) 6326@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{} 6327 6328@cindex Read-only files, and watches 6329Specify that developers should run @code{cvs edit} 6330before editing @var{files}. @sc{cvs} will create working 6331copies of @var{files} read-only, to remind developers 6332to run the @code{cvs edit} command before working on 6333them. 6334 6335If @var{files} includes the name of a directory, @sc{cvs} 6336arranges to watch all files added to the corresponding 6337repository directory, and sets a default for files 6338added in the future; this allows the user to set 6339notification policies on a per-directory basis. The 6340contents of the directory are processed recursively, 6341unless the @code{-l} option is given. 6342The @code{-R} option can be used to force recursion if the @code{-l} 6343option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}). 6344 6345If @var{files} is omitted, it defaults to the current directory. 6346 6347@cindex watch off (subcommand) 6348@end deffn 6349 6350@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{} 6351 6352Do not create @var{files} read-only on checkout; thus, 6353developers will not be reminded to use @code{cvs edit} 6354and @code{cvs unedit}. 6355 6356The @var{files} and options are processed as for @code{cvs 6357watch on}. 6358 6359@end deffn 6360 6361@node Getting Notified 6362@subsection Telling CVS to notify you 6363 6364You can tell @sc{cvs} that you want to receive 6365notifications about various actions taken on a file. 6366You can do this without using @code{cvs watch on} for 6367the file, but generally you will want to use @code{cvs 6368watch on}, to remind developers to use the @code{cvs edit} 6369command. 6370 6371@cindex watch add (subcommand) 6372@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6373 6374Add the current user to the list of people to receive notification of 6375work done on @var{files}. 6376 6377The @code{-a} option specifies what kinds of events @sc{cvs} should notify 6378the user about. @var{action} is one of the following: 6379 6380@table @code 6381 6382@item edit 6383Another user has applied the @code{cvs edit} command (described 6384below) to a watched file. 6385 6386@item commit 6387Another user has committed changes to one of the named @var{files}. 6388 6389@item unedit 6390Another user has abandoned editing a file (other than by committing changes). 6391They can do this in several ways, by: 6392 6393@itemize @bullet 6394 6395@item 6396applying the @code{cvs unedit} command (described below) to the file 6397 6398@item 6399applying the @code{cvs release} command (@pxref{release}) to the file's parent directory 6400(or recursively to a directory more than one level up) 6401 6402@item 6403deleting the file and allowing @code{cvs update} to recreate it 6404 6405@end itemize 6406 6407@item all 6408All of the above. 6409 6410@item none 6411None of the above. (This is useful with @code{cvs edit}, 6412described below.) 6413 6414@end table 6415 6416The @code{-a} option may appear more than once, or not at all. If 6417omitted, the action defaults to @code{all}. 6418 6419The @var{files} and options are processed as for 6420@code{cvs watch on}. 6421 6422@end deffn 6423 6424 6425@cindex watch remove (subcommand) 6426@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6427 6428Remove a notification request established using @code{cvs watch add}; 6429the arguments are the same. If the @code{-a} option is present, only 6430watches for the specified actions are removed. 6431 6432@end deffn 6433 6434@cindex notify (admin file) 6435When the conditions exist for notification, @sc{cvs} 6436calls the @file{notify} administrative file. Edit 6437@file{notify} as one edits the other administrative 6438files (@pxref{Intro administrative files}). This 6439file follows the usual conventions for administrative 6440files (@pxref{syntax}), where each line is a regular 6441expression followed by a command to execute. The 6442command should contain a single occurrence of @samp{%s} 6443which will be replaced by the user to notify; the rest 6444of the information regarding the notification will be 6445supplied to the command on standard input. The 6446standard thing to put in the @code{notify} file is the 6447single line: 6448 6449@example 6450ALL mail %s -s "CVS notification" 6451@end example 6452 6453@noindent 6454This causes users to be notified by electronic mail. 6455@c FIXME: should it be this hard to set up this 6456@c behavior (and the result when one fails to do so, 6457@c silent failure to notify, so non-obvious)? Should 6458@c CVS give a warning if no line in notify matches (and 6459@c document the use of "DEFAULT :" for the case where 6460@c skipping the notification is indeed desired)? 6461 6462@cindex users (admin file) 6463Note that if you set this up in the straightforward 6464way, users receive notifications on the server machine. 6465One could of course write a @file{notify} script which 6466directed notifications elsewhere, but to make this 6467easy, @sc{cvs} allows you to associate a notification 6468address for each user. To do so create a file 6469@file{users} in @file{CVSROOT} with a line for each 6470user in the format @var{user}:@var{value}. Then 6471instead of passing the name of the user to be notified 6472to @file{notify}, @sc{cvs} will pass the @var{value} 6473(normally an email address on some other machine). 6474 6475@sc{cvs} does not notify you for your own changes. 6476Currently this check is done based on whether the user 6477name of the person taking the action which triggers 6478notification matches the user name of the person 6479getting notification. In fact, in general, the watches 6480features only track one edit by each user. It probably 6481would be more useful if watches tracked each working 6482directory separately, so this behavior might be worth 6483changing. 6484@c "behavior might be worth changing" is an effort to 6485@c point to future directions while also not promising 6486@c that "they" (as in "why don't they fix CVS to....") 6487@c will do this. 6488@c one implementation issue is identifying whether a 6489@c working directory is same or different. Comparing 6490@c pathnames/hostnames is hopeless, but having the server 6491@c supply a serial number which the client stores in the 6492@c CVS directory as a magic cookie should work. 6493 6494@node Editing files 6495@subsection How to edit a file which is being watched 6496 6497@cindex Checkout, as term for getting ready to edit 6498Since a file which is being watched is checked out 6499read-only, you cannot simply edit it. To make it 6500read-write, and inform others that you are planning to 6501edit it, use the @code{cvs edit} command. Some systems 6502call this a @dfn{checkout}, but @sc{cvs} uses that term 6503for obtaining a copy of the sources (@pxref{Getting the 6504source}), an operation which those systems call a 6505@dfn{get} or a @dfn{fetch}. 6506@c Issue to think about: should we transition CVS 6507@c towards the "get" terminology? "cvs get" is already a 6508@c synonym for "cvs checkout" and that section of the 6509@c manual refers to "Getting the source". If this is 6510@c done, needs to be done gingerly (for example, we should 6511@c still accept "checkout" in .cvsrc files indefinitely 6512@c even if the CVS's messages are changed from "cvs checkout: " 6513@c to "cvs get: "). 6514@c There is a concern about whether "get" is not as 6515@c good for novices because it is a more general term 6516@c than "checkout" (and thus arguably harder to assign 6517@c a technical meaning for). 6518 6519@cindex edit (subcommand) 6520@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{} 6521 6522Prepare to edit the working files @var{files}. @sc{cvs} makes the 6523@var{files} read-write, and notifies users who have requested 6524@code{edit} notification for any of @var{files}. 6525 6526The @code{cvs edit} command accepts the same options as the 6527@code{cvs watch add} command, and establishes a temporary watch for the 6528user on @var{files}; @sc{cvs} will remove the watch when @var{files} are 6529@code{unedit}ed or @code{commit}ted. If the user does not wish to 6530receive notifications, she should specify @code{-a none}. 6531 6532The @var{files} and the options are processed as for the @code{cvs 6533watch} commands. 6534 6535 6536@end deffn 6537 6538Normally when you are done with a set of changes, you 6539use the @code{cvs commit} command, which checks in your 6540changes and returns the watched files to their usual 6541read-only state. But if you instead decide to abandon 6542your changes, or not to make any changes, you can use 6543the @code{cvs unedit} command. 6544 6545@cindex unedit (subcommand) 6546@cindex Abandoning work 6547@cindex Reverting to repository version 6548@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{} 6549 6550Abandon work on the working files @var{files}, and revert them to the 6551repository versions on which they are based. @sc{cvs} makes those 6552@var{files} read-only for which users have requested notification using 6553@code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit} 6554notification for any of @var{files}. 6555 6556The @var{files} and options are processed as for the 6557@code{cvs watch} commands. 6558 6559If watches are not in use, the @code{unedit} command 6560probably does not work, and the way to revert to the 6561repository version is with the command @code{cvs update -C file} 6562(@pxref{update}). 6563The meaning is 6564not precisely the same; the latter may also 6565bring in some changes which have been made in the 6566repository since the last time you updated. 6567@c It would be a useful enhancement to CVS to make 6568@c unedit work in the non-watch case as well. 6569@end deffn 6570 6571When using client/server @sc{cvs}, you can use the 6572@code{cvs edit} and @code{cvs unedit} commands even if 6573@sc{cvs} is unable to successfully communicate with the 6574server; the notifications will be sent upon the next 6575successful @sc{cvs} command. 6576 6577@node Watch information 6578@subsection Information about who is watching and editing 6579 6580@cindex watchers (subcommand) 6581@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{} 6582 6583List the users currently watching changes to @var{files}. The report 6584includes the files being watched, and the mail address of each watcher. 6585 6586The @var{files} and options are processed as for the 6587@code{cvs watch} commands. 6588 6589@end deffn 6590 6591 6592@cindex editors (subcommand) 6593@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{} 6594 6595List the users currently working on @var{files}. The report 6596includes the mail address of each user, the time when the user began 6597working with the file, and the host and path of the working directory 6598containing the file. 6599 6600The @var{files} and options are processed as for the 6601@code{cvs watch} commands. 6602 6603@end deffn 6604 6605@node Watches Compatibility 6606@subsection Using watches with old versions of CVS 6607 6608@cindex CVS 1.6, and watches 6609If you use the watch features on a repository, it 6610creates @file{CVS} directories in the repository and 6611stores the information about watches in that directory. 6612If you attempt to use @sc{cvs} 1.6 or earlier with the 6613repository, you get an error message such as the 6614following (all on one line): 6615 6616@example 6617cvs update: cannot open CVS/Entries for reading: 6618No such file or directory 6619@end example 6620 6621@noindent 6622and your operation will likely be aborted. To use the 6623watch features, you must upgrade all copies of @sc{cvs} 6624which use that repository in local or server mode. If 6625you cannot upgrade, use the @code{watch off} and 6626@code{watch remove} commands to remove all watches, and 6627that will restore the repository to a state which 6628@sc{cvs} 1.6 can cope with. 6629 6630@node Choosing a model 6631@section Choosing between reserved or unreserved checkouts 6632@cindex Choosing, reserved or unreserved checkouts 6633 6634Reserved and unreserved checkouts each have pros and 6635cons. Let it be said that a lot of this is a matter of 6636opinion or what works given different groups' working 6637styles, but here is a brief description of some of the 6638issues. There are many ways to organize a team of 6639developers. @sc{cvs} does not try to enforce a certain 6640organization. It is a tool that can be used in several 6641ways. 6642 6643Reserved checkouts can be very counter-productive. If 6644two persons want to edit different parts of a file, 6645there may be no reason to prevent either of them from 6646doing so. Also, it is common for someone to take out a 6647lock on a file, because they are planning to edit it, 6648but then forget to release the lock. 6649 6650@c "many groups"? specifics? cites to papers on this? 6651@c some way to weasel-word it a bit more so we don't 6652@c need facts :-)? 6653People, especially people who are familiar with 6654reserved checkouts, often wonder how often conflicts 6655occur if unreserved checkouts are used, and how 6656difficult they are to resolve. The experience with 6657many groups is that they occur rarely and usually are 6658relatively straightforward to resolve. 6659 6660The rarity of serious conflicts may be surprising, until one realizes 6661that they occur only when two developers disagree on the proper design 6662for a given section of code; such a disagreement suggests that the 6663team has not been communicating properly in the first place. In order 6664to collaborate under @emph{any} source management regimen, developers 6665must agree on the general design of the system; given this agreement, 6666overlapping changes are usually straightforward to merge. 6667 6668In some cases unreserved checkouts are clearly 6669inappropriate. If no merge tool exists for the kind of 6670file you are managing (for example word processor files 6671or files edited by Computer Aided Design programs), and 6672it is not desirable to change to a program which uses a 6673mergeable data format, then resolving conflicts is 6674going to be unpleasant enough that you generally will 6675be better off to simply avoid the conflicts instead, by 6676using reserved checkouts. 6677 6678The watches features described above in @ref{Watches} 6679can be considered to be an intermediate model between 6680reserved checkouts and unreserved checkouts. When you 6681go to edit a file, it is possible to find out who else 6682is editing it. And rather than having the system 6683simply forbid both people editing the file, it can tell 6684you what the situation is and let you figure out 6685whether it is a problem in that particular case or not. 6686Therefore, for some groups it can be considered the 6687best of both the reserved checkout and unreserved 6688checkout worlds. 6689 6690@c --------------------------------------------------------------------- 6691@node Revision management 6692@chapter Revision management 6693@cindex Revision management 6694 6695@c -- This chapter could be expanded a lot. 6696@c -- Experiences are very welcome! 6697 6698If you have read this far, you probably have a pretty 6699good grasp on what @sc{cvs} can do for you. This 6700chapter talks a little about things that you still have 6701to decide. 6702 6703If you are doing development on your own using @sc{cvs} 6704you could probably skip this chapter. The questions 6705this chapter takes up become more important when more 6706than one person is working in a repository. 6707 6708@menu 6709* When to commit:: Some discussion on the subject 6710@end menu 6711 6712@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6713@node When to commit 6714@section When to commit? 6715@cindex When to commit 6716@cindex Committing, when to 6717@cindex Policy 6718 6719Your group should decide which policy to use regarding 6720commits. Several policies are possible, and as your 6721experience with @sc{cvs} grows you will probably find 6722out what works for you. 6723 6724If you commit files too quickly you might commit files 6725that do not even compile. If your partner updates his 6726working sources to include your buggy file, he will be 6727unable to compile the code. On the other hand, other 6728persons will not be able to benefit from the 6729improvements you make to the code if you commit very 6730seldom, and conflicts will probably be more common. 6731 6732It is common to only commit files after making sure 6733that they can be compiled. Some sites require that the 6734files pass a test suite. Policies like this can be 6735enforced using the commitinfo file 6736(@pxref{commitinfo}), but you should think twice before 6737you enforce such a convention. By making the 6738development environment too controlled it might become 6739too regimented and thus counter-productive to the real 6740goal, which is to get software written. 6741 6742@c --------------------------------------------------------------------- 6743@node Keyword substitution 6744@chapter Keyword substitution 6745@cindex Keyword substitution 6746@cindex Keyword expansion 6747@cindex Identifying files 6748 6749@comment Be careful when editing this chapter. 6750@comment Remember that this file is kept under 6751@comment version control, so we must not accidentally 6752@comment include a valid keyword in the running text. 6753 6754As long as you edit source files inside a working 6755directory you can always find out the state of 6756your files via @samp{cvs status} and @samp{cvs log}. 6757But as soon as you export the files from your 6758development environment it becomes harder to identify 6759which revisions they are. 6760 6761@sc{cvs} can use a mechanism known as @dfn{keyword 6762substitution} (or @dfn{keyword expansion}) to help 6763identifying the files. Embedded strings of the form 6764@code{$@var{keyword}$} and 6765@code{$@var{keyword}:@dots{}$} in a file are replaced 6766with strings of the form 6767@code{$@var{keyword}:@var{value}$} whenever you obtain 6768a new revision of the file. 6769 6770@menu 6771* Keyword list:: Keywords 6772* Using keywords:: Using keywords 6773* Avoiding substitution:: Avoiding substitution 6774* Substitution modes:: Substitution modes 6775* Configuring keyword expansion:: Configuring keyword expansion 6776* Log keyword:: Problems with the $ Log$ keyword. 6777@end menu 6778 6779@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6780@node Keyword list 6781@section Keyword List 6782@cindex Keyword List 6783 6784@c FIXME: need some kind of example here I think, 6785@c perhaps in a 6786@c "Keyword intro" node. The intro in the "Keyword 6787@c substitution" node itself seems OK, but to launch 6788@c into a list of the keywords somehow seems too abrupt. 6789 6790This is a list of the keywords: 6791 6792@table @code 6793@cindex Author keyword 6794@item $ Author$ 6795The login name of the user who checked in the revision. 6796 6797@cindex CVSHeader keyword 6798@item $ CVSHeader 6799A standard header (similar to $ Header$, but with 6800the CVS root stripped off). It contains the relative 6801pathname of the @sc{rcs} file to the CVS root, the 6802revision number, the date (UTC), the author, the state, 6803and the locker (if locked). Files will normally never 6804be locked when you use @sc{cvs}. 6805 6806Note that this keyword has only been recently 6807introduced to @sc{cvs} and may cause problems with 6808existing installations if $ CVSHeader$ is already 6809in the files for a different purpose. This keyword may 6810be excluded using the @code{KeywordExpansion=eCVSHeader} 6811in the @file{CVSROOT/config} file. 6812See @ref{Configuring keyword expansion} for more details. 6813 6814@cindex Date keyword 6815@item $ Date$ 6816The date and time (UTC) the revision was checked in. 6817 6818@cindex Header keyword 6819@item $ Header$ 6820A standard header containing the full pathname of the 6821@sc{rcs} file, the revision number, the date (UTC), the 6822author, the state, and the locker (if locked). Files 6823will normally never be locked when you use @sc{cvs}. 6824 6825@cindex Id keyword 6826@item $ Id$ 6827Same as @code{$ Header$}, except that the @sc{rcs} 6828filename is without a path. 6829 6830@cindex Name keyword 6831@item $ Name$ 6832Tag name used to check out this file. The keyword is 6833expanded only if one checks out with an explicit tag 6834name. For example, when running the command @code{cvs 6835co -r first}, the keyword expands to @samp{Name: first}. 6836 6837@cindex Locker keyword 6838@item $ Locker$ 6839The login name of the user who locked the revision 6840(empty if not locked, which is the normal case unless 6841@code{cvs admin -l} is in use). 6842 6843@cindex Log keyword 6844@item $ Log$ 6845The log message supplied during commit, preceded by a 6846header containing the @sc{rcs} filename, the revision 6847number, the author, and the date (UTC). Existing log 6848messages are @emph{not} replaced. Instead, the new log 6849message is inserted after @code{$ Log:@dots{}$}. 6850Each new line is prefixed with the same string which 6851precedes the @code{$Log} keyword. For example, if the 6852file contains: 6853 6854@example 6855 /* Here is what people have been up to: 6856 * 6857 * $ Log: frob.c,v $ 6858 * Revision 1.1 1997/01/03 14:23:51 joe 6859 * Add the superfrobnicate option 6860 * 6861 */ 6862@end example 6863 6864@noindent 6865then additional lines which are added when expanding 6866the @code{$Log} keyword will be preceded by @samp{ * }. 6867Unlike previous versions of @sc{cvs} and @sc{rcs}, the 6868@dfn{comment leader} from the @sc{rcs} file is not used. 6869The @code{$Log} keyword is useful for 6870accumulating a complete change log in a source file, 6871but for several reasons it can be problematic. 6872@xref{Log keyword}. 6873 6874@cindex RCSfile keyword 6875@item $ RCSfile$ 6876The name of the RCS file without a path. 6877 6878@cindex Revision keyword 6879@item $ Revision$ 6880The revision number assigned to the revision. 6881 6882@cindex Source keyword 6883@item $ Source$ 6884The full pathname of the RCS file. 6885 6886@cindex State keyword 6887@item $ State$ 6888The state assigned to the revision. States can be 6889assigned with @code{cvs admin -s}---see @ref{admin options}. 6890 6891@cindex Local keyword 6892@item Local keyword 6893The @code{LocalKeyword} option in the @file{CVSROOT/config} file 6894may be used to specify a local keyword which is to be 6895used as an alias for one of the other keywords. For 6896example, if the @file{CVSROOT/config} file contains 6897a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a 6898file with the local keyword $ MYBSD$ will be 6899expanded as if it were a $ CVSHeader$ keyword. If 6900the src/frob.c file contained this keyword, it might 6901look something like this: 6902 6903@example 6904 /* 6905 * $ MYBSD: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 6906 */ 6907@end example 6908 6909Many repositories make use of a such a ``local 6910keyword'' feature. An old patch to @sc{cvs} provided 6911the @code{LocalKeyword} feature using a @code{tag=} 6912option and called this the ``custom tag'' or ``local 6913tag'' feature. It was used in conjunction with the 6914what they called the @code{tagexpand=} option. In 6915@sc{cvs} this other option is known as the 6916@code{KeywordExpand} option. 6917See @ref{Configuring keyword expansion} for more 6918details. 6919 6920Examples from popular projects include: 6921$ FreeBSD$, $ NetBSD$, 6922$ OpenBSD$, $ XFree86$, 6923$ Xorg$. 6924 6925The advantage of this is that you can include your 6926local version information in a file using this local 6927keyword without disrupting the upstream version 6928information (which may be a different local keyword or 6929a standard keyword). Allowing bug reports and the like 6930to more properly identify the source of the original 6931bug to the third-party and reducing the number of 6932conflicts that arise during an import of a new version. 6933 6934All keyword expansion except the local keyword may be 6935disabled using the @code{KeywordExpansion} option in 6936the @file{CVSROOT/config} file---see 6937@ref{Configuring keyword expansion} for more details. 6938 6939@end table 6940 6941@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6942@node Using keywords 6943@section Using keywords 6944 6945To include a keyword string you simply include the 6946relevant text string, such as @code{$ Id$}, inside the 6947file, and commit the file. @sc{cvs} will automatically 6948expand the string as part of the commit operation. 6949 6950It is common to embed the @code{$ Id$} string in 6951the source files so that it gets passed through to 6952generated files. For example, if you are managing 6953computer program source code, you might include a 6954variable which is initialized to contain that string. 6955Or some C compilers may provide a @code{#pragma ident} 6956directive. Or a document management system might 6957provide a way to pass a string through to generated 6958files. 6959 6960@c Would be nice to give an example, but doing this in 6961@c portable C is not possible and the problem with 6962@c picking any one language (VMS HELP files, Ada, 6963@c troff, whatever) is that people use CVS for all 6964@c kinds of files. 6965 6966@cindex Ident (shell command) 6967The @code{ident} command (which is part of the @sc{rcs} 6968package) can be used to extract keywords and their 6969values from a file. This can be handy for text files, 6970but it is even more useful for extracting keywords from 6971binary files. 6972 6973@example 6974$ ident samp.c 6975samp.c: 6976 $ Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 6977$ gcc samp.c 6978$ ident a.out 6979a.out: 6980 $ Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ 6981@end example 6982 6983@cindex What (shell command) 6984S@sc{ccs} is another popular revision control system. 6985It has a command, @code{what}, which is very similar to 6986@code{ident} and used for the same purpose. Many sites 6987without @sc{rcs} have @sc{sccs}. Since @code{what} 6988looks for the character sequence @code{@@(#)} it is 6989easy to include keywords that are detected by either 6990command. Simply prefix the keyword with the 6991magic @sc{sccs} phrase, like this: 6992 6993@example 6994static char *id="@@(#) $ Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; 6995@end example 6996 6997@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6998@node Avoiding substitution 6999@section Avoiding substitution 7000 7001Keyword substitution has its disadvantages. Sometimes 7002you might want the literal text string 7003@samp{$ Author$} to appear inside a file without 7004@sc{cvs} interpreting it as a keyword and expanding it 7005into something like @samp{$ Author: ceder $}. 7006 7007There is unfortunately no way to selectively turn off 7008keyword substitution. You can use @samp{-ko} 7009(@pxref{Substitution modes}) to turn off keyword 7010substitution entirely. 7011 7012In many cases you can avoid using keywords in 7013the source, even though they appear in the final 7014product. For example, the source for this manual 7015contains @samp{$@@asis@{@}Author$} whenever the text 7016@samp{$ Author$} should appear. In @code{nroff} 7017and @code{troff} you can embed the null-character 7018@code{\&} inside the keyword for a similar effect. 7019 7020It is also possible to specify an explicit list of 7021keywords to include or exclude using the 7022@code{KeywordExpand} option in the 7023@file{CVSROOT/config} file--see @ref{Configuring keyword expansion} 7024for more details. This feature is intended primarily 7025for use with the @code{LocalKeyword} option--see 7026@ref{Keyword list}. 7027 7028@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7029@node Substitution modes 7030@section Substitution modes 7031@cindex Keyword substitution, changing modes 7032@cindex -k (keyword substitution) 7033@cindex Kflag 7034 7035@c FIXME: This could be made more coherent, by expanding it 7036@c with more examples or something. 7037Each file has a stored default substitution mode, and 7038each working directory copy of a file also has a 7039substitution mode. The former is set by the @samp{-k} 7040option to @code{cvs add} and @code{cvs admin}; the 7041latter is set by the @samp{-k} or @samp{-A} options to @code{cvs 7042checkout} or @code{cvs update}. @code{cvs diff} also 7043has a @samp{-k} option. For some examples, 7044see @ref{Binary files}, and @ref{Merging and keywords}. 7045@c The fact that -A is overloaded to mean both reset 7046@c sticky options and reset sticky tags/dates is 7047@c somewhat questionable. Perhaps there should be 7048@c separate options to reset sticky options (e.g. -k 7049@c A") and tags/dates (someone suggested -r HEAD could 7050@c do this instead of setting a sticky tag of "HEAD" 7051@c as in the status quo but I haven't thought much 7052@c about that idea. Of course -r .reset or something 7053@c could be coined if this needs to be a new option). 7054@c On the other hand, having -A mean "get things back 7055@c into the state after a fresh checkout" has a certain 7056@c appeal, and maybe there is no sufficient reason for 7057@c creeping featurism in this area. 7058 7059The modes available are: 7060 7061@table @samp 7062@item -kkv 7063Generate keyword strings using the default form, e.g. 7064@code{$ Revision: 5.7 $} for the @code{Revision} 7065keyword. 7066 7067@item -kkvl 7068Like @samp{-kkv}, except that a locker's name is always 7069inserted if the given revision is currently locked. 7070The locker's name is only relevant if @code{cvs admin 7071-l} is in use. 7072 7073@item -kk 7074Generate only keyword names in keyword strings; omit 7075their values. For example, for the @code{Revision} 7076keyword, generate the string @code{$ Revision$} 7077instead of @code{$ Revision: 5.7 $}. This option 7078is useful to ignore differences due to keyword 7079substitution when comparing different revisions of a 7080file (@pxref{Merging and keywords}). 7081 7082@item -ko 7083Generate the old keyword string, present in the working 7084file just before it was checked in. For example, for 7085the @code{Revision} keyword, generate the string 7086@code{$ Revision: 1.1 $} instead of 7087@code{$ Revision: 5.7 $} if that is how the 7088string appeared when the file was checked in. 7089 7090@item -kb 7091Like @samp{-ko}, but also inhibit conversion of line 7092endings between the canonical form in which they are 7093stored in the repository (linefeed only), and the form 7094appropriate to the operating system in use on the 7095client. For systems, like unix, which use linefeed 7096only to terminate lines, this is very similar to 7097@samp{-ko}. For more information on binary files, see 7098@ref{Binary files}. In @sc{cvs} version 1.12.2 and later 7099@samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or 7100@code{cvs import} may not be overridden by a @samp{-k} option 7101specified on the command line. 7102 7103@item -kv 7104Generate only keyword values for keyword strings. For 7105example, for the @code{Revision} keyword, generate the string 7106@code{5.7} instead of @code{$ Revision: 5.7 $}. 7107This can help generate files in programming languages 7108where it is hard to strip keyword delimiters like 7109@code{$ Revision: $} from a string. However, 7110further keyword substitution cannot be performed once 7111the keyword names are removed, so this option should be 7112used with care. 7113 7114One often would like to use @samp{-kv} with @code{cvs 7115export}---@pxref{export}. But be aware that doesn't 7116handle an export containing binary files correctly. 7117 7118@end table 7119 7120@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7121@node Configuring keyword expansion 7122@section Configuring Keyord Expansion 7123@cindex Configuring keyword expansion 7124 7125In a repository that includes third-party software on 7126vendor branches, it is sometimes helpful to configure 7127CVS to use a local keyword instead of the standard 7128$ Id$ or $ Header$ keywords. Examples from 7129real projects includ, $ Xorg$, $ XFree86$, 7130$ FreeBSD$, $ NetBSD$, 7131$ OpenBSD$, and even $ dotat$. 7132The advantage of this is that 7133you can include your local version information in a 7134file using this local keyword (sometimes called a 7135``custom tag'' or a ``local tag'') without disrupting 7136the upstream version information (which may be a 7137different local keyword or a standard keyword). In 7138these cases, it is typically desirable to disable the 7139expansion of all keywords except the configured local 7140keyword. 7141 7142The @code{KeywordExpansion} option in the 7143@file{CVSROOT/config} file is intended to allow for the 7144either the explicit exclusion of a keyword or list of 7145keywords, or for the explicit inclusion of a keyword or 7146a list of keywords. This list may include the 7147@code{LocalKeyword} that has been configured. 7148 7149The @code{KeywordExpansion} option is followed by 7150@code{=} and the next character may either be @code{i} 7151to start an inclusion list or @code{e} to start an 7152exclusion list. If the following lines were added to 7153the @file{CVSROOT/config} file: 7154 7155@example 7156 # Add a "MyBSD" keyword and restrict keyword 7157 # expansion 7158 LocalKeyword=MyBSD=CVSHeader 7159 KeywordExpand=iMyBSD 7160@end example 7161 7162then only the $ MyBSD$ keyword would be expanded. 7163A list may be used. The this example: 7164 7165@example 7166 # Add a "MyBSD" keyword and restrict keyword 7167 # expansion to the MyBSD, Name and Date keywords. 7168 LocalKeyword=MyBSD=CVSHeader 7169 KeywordExpand=iMyBSD,Name,Date 7170@end example 7171 7172would allow $ MyBSD$, $ Name$, and 7173$ Date$ to be expanded. 7174 7175It is also possible to configure an exclusion list 7176using the following: 7177 7178@example 7179 # Do not expand the non-RCS keyword CVSHeader 7180 KeywordExpand=eCVSHeader 7181@end example 7182 7183This allows @sc{cvs} to ignore the recently introduced 7184$ CVSHeader$ keyword and retain all of the 7185others. The exclusion entry could also contain the 7186standard RCS keyword list, but this could be confusing 7187to users that expect RCS keywords to be expanded, so 7188ycare should be taken to properly set user expectations 7189for a repository that is configured in that manner. 7190 7191If there is a desire to not have any RCS keywords 7192expanded and not use the @code{-ko} flags everywhere, 7193an administrator may disable all keyword expansion 7194using the @file{CVSROOT/config} line: 7195 7196@example 7197 # Do not expand any RCS keywords 7198 KeywordExpand=i 7199@end example 7200 7201this could be confusing to users that expect RCS 7202keywords like $ Id$ to be expanded properly, 7203so care should be taken to properly set user 7204expectations for a repository so configured. 7205 7206It should be noted that a patch to provide both the 7207@code{KeywordExpand} and @code{LocalKeyword} features 7208has been around a long time. However, that patch 7209implemented these features using @code{tag=} and 7210@code{tagexpand=} keywords and those keywords are NOT 7211recognized. 7212 7213@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7214@node Log keyword 7215@section Problems with the $ Log$ keyword. 7216 7217The @code{$ Log$} keyword is somewhat 7218controversial. As long as you are working on your 7219development system the information is easily accessible 7220even if you do not use the @code{$ Log$} 7221keyword---just do a @code{cvs log}. Once you export 7222the file the history information might be useless 7223anyhow. 7224 7225A more serious concern is that @sc{cvs} is not good at 7226handling @code{$ Log$} entries when a branch is 7227merged onto the main trunk. Conflicts often result 7228from the merging operation. 7229@c Might want to check whether the CVS implementation 7230@c of RCS_merge has this problem the same way rcsmerge 7231@c does. I would assume so.... 7232 7233People also tend to "fix" the log entries in the file 7234(correcting spelling mistakes and maybe even factual 7235errors). If that is done the information from 7236@code{cvs log} will not be consistent with the 7237information inside the file. This may or may not be a 7238problem in real life. 7239 7240It has been suggested that the @code{$ Log$} 7241keyword should be inserted @emph{last} in the file, and 7242not in the files header, if it is to be used at all. 7243That way the long list of change messages will not 7244interfere with everyday source file browsing. 7245 7246@c --------------------------------------------------------------------- 7247@node Tracking sources 7248@chapter Tracking third-party sources 7249@cindex Third-party sources 7250@cindex Tracking sources 7251 7252@c FIXME: Need discussion of added and removed files. 7253@c FIXME: This doesn't really adequately introduce the 7254@c concepts of "vendor" and "you". They don't *have* 7255@c to be separate organizations or separate people. 7256@c We want a description which is somewhat more based on 7257@c the technical issues of which sources go where, but 7258@c also with enough examples of how this relates to 7259@c relationships like customer-supplier, developer-QA, 7260@c maintainer-contributor, or whatever, to make it 7261@c seem concrete. 7262If you modify a program to better fit your site, you 7263probably want to include your modifications when the next 7264release of the program arrives. @sc{cvs} can help you with 7265this task. 7266 7267@cindex Vendor 7268@cindex Vendor branch 7269@cindex Branch, vendor- 7270In the terminology used in @sc{cvs}, the supplier of the 7271program is called a @dfn{vendor}. The unmodified 7272distribution from the vendor is checked in on its own 7273branch, the @dfn{vendor branch}. @sc{cvs} reserves branch 72741.1.1 for this use. 7275 7276When you modify the source and commit it, your revision 7277will end up on the main trunk. When a new release is 7278made by the vendor, you commit it on the vendor branch 7279and copy the modifications onto the main trunk. 7280 7281Use the @code{import} command to create and update 7282the vendor branch. When you import a new file, 7283the vendor branch is made the `head' revision, so 7284anyone that checks out a copy of the file gets that 7285revision. When a local modification is committed it is 7286placed on the main trunk, and made the `head' 7287revision. 7288 7289@menu 7290* First import:: Importing for the first time 7291* Update imports:: Updating with the import command 7292* Reverting local changes:: Reverting to the latest vendor release 7293* Binary files in imports:: Binary files require special handling 7294* Keywords in imports:: Keyword substitution might be undesirable 7295* Multiple vendor branches:: What if you get sources from several places? 7296@end menu 7297 7298@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7299@node First import 7300@section Importing for the first time 7301@cindex Importing modules 7302 7303@c Should mention naming conventions for vendor tags, 7304@c release tags, and perhaps directory names. 7305Use the @code{import} command to check in the sources 7306for the first time. When you use the @code{import} 7307command to track third-party sources, the @dfn{vendor 7308tag} and @dfn{release tags} are useful. The 7309@dfn{vendor tag} is a symbolic name for the branch 7310(which is always 1.1.1, unless you use the @samp{-b 7311@var{branch}} flag---see @ref{Multiple vendor branches}.). The 7312@dfn{release tags} are symbolic names for a particular 7313release, such as @samp{FSF_0_04}. 7314 7315@c I'm not completely sure this belongs here. But 7316@c we need to say it _somewhere_ reasonably obvious; it 7317@c is a common misconception among people first learning CVS 7318Note that @code{import} does @emph{not} change the 7319directory in which you invoke it. In particular, it 7320does not set up that directory as a @sc{cvs} working 7321directory; if you want to work with the sources import 7322them first and then check them out into a different 7323directory (@pxref{Getting the source}). 7324 7325@cindex wdiff (import example) 7326Suppose you have the sources to a program called 7327@code{wdiff} in a directory @file{wdiff-0.04}, 7328and are going to make private modifications that you 7329want to be able to use even when new releases are made 7330in the future. You start by importing the source to 7331your repository: 7332 7333@example 7334$ cd wdiff-0.04 7335$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04 7336@end example 7337 7338The vendor tag is named @samp{FSF_DIST} in the above 7339example, and the only release tag assigned is 7340@samp{WDIFF_0_04}. 7341@c FIXME: Need to say where fsf/wdiff comes from. 7342 7343@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7344@node Update imports 7345@section Updating with the import command 7346 7347When a new release of the source arrives, you import it into the 7348repository with the same @code{import} command that you used to set up 7349the repository in the first place. The only difference is that you 7350specify a different release tag this time: 7351 7352@example 7353$ tar xfz wdiff-0.05.tar.gz 7354$ cd wdiff-0.05 7355$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05 7356@end example 7357 7358For files that have not been modified locally, the newly created 7359revision becomes the head revision. If you have made local 7360changes, @code{import} will warn you that you must merge the changes 7361into the main trunk, and tell you to use @samp{checkout -j} to do so: 7362 7363@c FIXME: why "wdiff" here and "fsf/wdiff" in the 7364@c "import"? I think the assumption is that one has 7365@c "wdiff fsf/wdiff" or some such in modules, but it 7366@c would be better to not use modules in this example. 7367@example 7368$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff 7369@end example 7370 7371@noindent 7372The above command will check out the latest revision of 7373@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST} 7374since yesterday into the working copy. If any conflicts arise during 7375the merge they should be resolved in the normal way (@pxref{Conflicts 7376example}). Then, the modified files may be committed. 7377 7378However, it is much better to use the two release tags rather than using 7379a date on the branch as suggested above: 7380 7381@example 7382$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff 7383@end example 7384 7385@noindent 7386The reason this is better is that 7387using a date, as suggested above, assumes that you do 7388not import more than one release of a product per day. 7389More importantly, using the release tags allows @sc{cvs} to detect files 7390that were removed between the two vendor releases and mark them for 7391removal. Since @code{import} has no way to detect removed files, you 7392should do a merge like this even if @code{import} doesn't tell you to. 7393 7394@node Reverting local changes 7395@section Reverting to the latest vendor release 7396 7397You can also revert local changes completely and return 7398to the latest vendor release by changing the `head' 7399revision back to the vendor branch on all files. For 7400example, if you have a checked-out copy of the sources 7401in @file{~/work.d/wdiff}, and you want to revert to the 7402vendor's version for all the files in that directory, 7403you would type: 7404 7405@example 7406$ cd ~/work.d/wdiff 7407$ cvs admin -bWDIFF . 7408@end example 7409 7410@noindent 7411You must specify the @samp{-bWDIFF} without any space 7412after the @samp{-b}. @xref{admin options}. 7413 7414@node Binary files in imports 7415@section How to handle binary files with cvs import 7416 7417Use the @samp{-k} wrapper option to tell import which 7418files are binary. @xref{Wrappers}. 7419 7420@node Keywords in imports 7421@section How to handle keyword substitution with cvs import 7422 7423The sources which you are importing may contain 7424keywords (@pxref{Keyword substitution}). For example, 7425the vendor may use @sc{cvs} or some other system 7426which uses similar keyword expansion syntax. If you 7427just import the files in the default fashion, then 7428the keyword expansions supplied by the vendor will 7429be replaced by keyword expansions supplied by your 7430own copy of @sc{cvs}. It may be more convenient to 7431maintain the expansions supplied by the vendor, so 7432that this information can supply information about 7433the sources that you imported from the vendor. 7434 7435To maintain the keyword expansions supplied by the 7436vendor, supply the @samp{-ko} option to @code{cvs 7437import} the first time you import the file. 7438This will turn off keyword expansion 7439for that file entirely, so if you want to be more 7440selective you'll have to think about what you want 7441and use the @samp{-k} option to @code{cvs update} or 7442@code{cvs admin} as appropriate. 7443@c Supplying -ko to import if the file already existed 7444@c has no effect. Not clear to me whether it should 7445@c or not. 7446 7447@node Multiple vendor branches 7448@section Multiple vendor branches 7449 7450All the examples so far assume that there is only one 7451vendor from which you are getting sources. In some 7452situations you might get sources from a variety of 7453places. For example, suppose that you are dealing with 7454a project where many different people and teams are 7455modifying the software. There are a variety of ways to 7456handle this, but in some cases you have a bunch of 7457source trees lying around and what you want to do more 7458than anything else is just to all put them in @sc{cvs} so 7459that you at least have them in one place. 7460 7461For handling situations in which there may be more than 7462one vendor, you may specify the @samp{-b} option to 7463@code{cvs import}. It takes as an argument the vendor 7464branch to import to. The default is @samp{-b 1.1.1}. 7465 7466For example, suppose that there are two teams, the red 7467team and the blue team, that are sending you sources. 7468You want to import the red team's efforts to branch 74691.1.1 and use the vendor tag RED. You want to import 7470the blue team's efforts to branch 1.1.3 and use the 7471vendor tag BLUE. So the commands you might use are: 7472 7473@example 7474$ cvs import dir RED RED_1-0 7475$ cvs import -b 1.1.3 dir BLUE BLUE_1-5 7476@end example 7477 7478Note that if your vendor tag does not match your 7479@samp{-b} option, @sc{cvs} will not detect this case! For 7480example, 7481 7482@example 7483$ cvs import -b 1.1.3 dir RED RED_1-0 7484@end example 7485 7486@noindent 7487Be careful; this kind of mismatch is sure to sow 7488confusion or worse. I can't think of a useful purpose 7489for the ability to specify a mismatch here, but if you 7490discover such a use, don't. @sc{cvs} is likely to make this 7491an error in some future release. 7492 7493@c Probably should say more about the semantics of 7494@c multiple branches. What about the default branch? 7495@c What about joining (perhaps not as useful with 7496@c multiple branches, or perhaps it is. Either way 7497@c should be mentioned). 7498 7499@c I'm not sure about the best location for this. In 7500@c one sense, it might belong right after we've introduced 7501@c CVS's basic version control model, because people need 7502@c to figure out builds right away. The current location 7503@c is based on the theory that it kind of akin to the 7504@c "Revision management" section. 7505@node Builds 7506@chapter How your build system interacts with CVS 7507@cindex Builds 7508@cindex make 7509 7510As mentioned in the introduction, @sc{cvs} does not 7511contain software for building your software from source 7512code. This section describes how various aspects of 7513your build system might interact with @sc{cvs}. 7514 7515@c Is there a way to discuss this without reference to 7516@c tools other than CVS? I'm not sure there is; I 7517@c wouldn't think that people who learn CVS first would 7518@c even have this concern. 7519One common question, especially from people who are 7520accustomed to @sc{rcs}, is how to make their build get 7521an up to date copy of the sources. The answer to this 7522with @sc{cvs} is two-fold. First of all, since 7523@sc{cvs} itself can recurse through directories, there 7524is no need to modify your @file{Makefile} (or whatever 7525configuration file your build tool uses) to make sure 7526each file is up to date. Instead, just use two 7527commands, first @code{cvs -q update} and then 7528@code{make} or whatever the command is to invoke your 7529build tool. Secondly, you do not necessarily 7530@emph{want} to get a copy of a change someone else made 7531until you have finished your own work. One suggested 7532approach is to first update your sources, then 7533implement, build and 7534test the change you were thinking of, and then commit 7535your sources (updating first if necessary). By 7536periodically (in between changes, using the approach 7537just described) updating your entire tree, you ensure 7538that your sources are sufficiently up to date. 7539 7540@cindex Bill of materials 7541One common need is to record which versions of which 7542source files went into a particular build. This kind 7543of functionality is sometimes called @dfn{bill of 7544materials} or something similar. The best way to do 7545this with @sc{cvs} is to use the @code{tag} command to 7546record which versions went into a given build 7547(@pxref{Tags}). 7548 7549Using @sc{cvs} in the most straightforward manner 7550possible, each developer will have a copy of the entire 7551source tree which is used in a particular build. If 7552the source tree is small, or if developers are 7553geographically dispersed, this is the preferred 7554solution. In fact one approach for larger projects is 7555to break a project down into smaller 7556@c I say subsystem instead of module because they may or 7557@c may not use the modules file. 7558separately-compiled subsystems, and arrange a way of 7559releasing them internally so that each developer need 7560check out only those subsystems which they are 7561actively working on. 7562 7563Another approach is to set up a structure which allows 7564developers to have their own copies of some files, and 7565for other files to access source files from a central 7566location. Many people have come up with some such a 7567@c two such people are paul@sander.cupertino.ca.us (for 7568@c a previous employer) 7569@c and gtornblo@senet.abb.se (spicm and related tools), 7570@c but as far as I know 7571@c no one has nicely packaged or released such a system (or 7572@c instructions for constructing one). 7573system using features such as the symbolic link feature 7574found in many operating systems, or the @code{VPATH} 7575feature found in many versions of @code{make}. One build 7576tool which is designed to help with this kind of thing 7577is Odin (see 7578@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}). 7579@c Should we be saying more about Odin? Or how you use 7580@c it with CVS? Also, the Prime Time Freeware for Unix 7581@c disk (see http://www.ptf.com/) has Odin (with a nice 7582@c paragraph summarizing it on the web), so that might be a 7583@c semi-"official" place to point people. 7584@c 7585@c Of course, many non-CVS systems have this kind of 7586@c functionality, for example OSF's ODE 7587@c (http://www.osf.org/ode/) or mk 7588@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html 7589@c He has changed providers in the past; a search engine search 7590@c for "Peter Ziobrzynski" probably won't get too many 7591@c spurious hits :-). A more stable URL might be 7592@c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure 7593@c there is any point in mentioning them here unless they 7594@c can work with CVS. 7595 7596@c --------------------------------------------------------------------- 7597@node Special Files 7598@chapter Special Files 7599 7600@cindex Special files 7601@cindex Device nodes 7602@cindex Ownership, saving in CVS 7603@cindex Permissions, saving in CVS 7604@cindex Hard links 7605@cindex Symbolic links 7606 7607In normal circumstances, @sc{cvs} works only with regular 7608files. Every file in a project is assumed to be 7609persistent; it must be possible to open, read and close 7610them; and so on. @sc{cvs} also ignores file permissions and 7611ownerships, leaving such issues to be resolved by the 7612developer at installation time. In other words, it is 7613not possible to "check in" a device into a repository; 7614if the device file cannot be opened, @sc{cvs} will refuse to 7615handle it. Files also lose their ownerships and 7616permissions during repository transactions. 7617 7618 7619@c --------------------------------------------------------------------- 7620@node CVS commands 7621@appendix Guide to CVS commands 7622 7623This appendix describes the overall structure of 7624@sc{cvs} commands, and describes some commands in 7625detail (others are described elsewhere; for a quick 7626reference to @sc{cvs} commands, @pxref{Invoking CVS}). 7627@c The idea is that we want to move the commands which 7628@c are described here into the main body of the manual, 7629@c in the process reorganizing the manual to be 7630@c organized around what the user wants to do, not 7631@c organized around CVS commands. 7632@c 7633@c Note that many users do expect a manual which is 7634@c organized by command. At least some users do. 7635@c One good addition to the "organized by command" 7636@c section (if any) would be "see also" links. 7637@c The awk manual might be a good example; it has a 7638@c reference manual which is more verbose than Invoking 7639@c CVS but probably somewhat less verbose than CVS 7640@c Commands. 7641 7642@menu 7643* Structure:: Overall structure of CVS commands 7644* Exit status:: Indicating CVS's success or failure 7645* ~/.cvsrc:: Default options with the ~/.csvrc file 7646* Global options:: Options you give to the left of cvs_command 7647* Common options:: Options you give to the right of cvs_command 7648* admin:: Administration 7649* checkout:: Checkout sources for editing 7650* commit:: Check files into the repository 7651* diff:: Show differences between revisions 7652* export:: Export sources from CVS, similar to checkout 7653* history:: Show status of files and users 7654* import:: Import sources into CVS, using vendor branches 7655* log:: Show log messages for files 7656* rdiff:: 'patch' format diffs between releases 7657* release:: Indicate that a directory is no longer in use 7658* update:: Bring work tree in sync with repository 7659@end menu 7660 7661@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7662@node Structure 7663@appendixsec Overall structure of CVS commands 7664@cindex Structure 7665@cindex CVS command structure 7666@cindex Command structure 7667@cindex Format of CVS commands 7668 7669The overall format of all @sc{cvs} commands is: 7670 7671@example 7672cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] 7673@end example 7674 7675@table @code 7676@item cvs 7677The name of the @sc{cvs} program. 7678 7679@item cvs_options 7680Some options that affect all sub-commands of @sc{cvs}. These are 7681described below. 7682 7683@item cvs_command 7684One of several different sub-commands. Some of the commands have 7685aliases that can be used instead; those aliases are noted in the 7686reference manual for that command. There are only two situations 7687where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a 7688list of available commands, and @samp{cvs -v} displays version 7689information on @sc{cvs} itself. 7690 7691@item command_options 7692Options that are specific for the command. 7693 7694@item command_args 7695Arguments to the commands. 7696@end table 7697 7698There is unfortunately some confusion between 7699@code{cvs_options} and @code{command_options}. 7700@samp{-l}, when given as a @code{cvs_option}, only 7701affects some of the commands. When it is given as a 7702@code{command_option} is has a different meaning, and 7703is accepted by more commands. In other words, do not 7704take the above categorization too seriously. Look at 7705the documentation instead. 7706 7707@node Exit status 7708@appendixsec CVS's exit status 7709@cindex Exit status, of CVS 7710 7711@sc{cvs} can indicate to the calling environment whether it 7712succeeded or failed by setting its @dfn{exit status}. 7713The exact way of testing the exit status will vary from 7714one operating system to another. For example in a unix 7715shell script the @samp{$?} variable will be 0 if the 7716last command returned a successful exit status, or 7717greater than 0 if the exit status indicated failure. 7718 7719If @sc{cvs} is successful, it returns a successful status; 7720if there is an error, it prints an error message and 7721returns a failure status. The one exception to this is 7722the @code{cvs diff} command. It will return a 7723successful status if it found no differences, or a 7724failure status if there were differences or if there 7725was an error. Because this behavior provides no good 7726way to detect errors, in the future it is possible that 7727@code{cvs diff} will be changed to behave like the 7728other @sc{cvs} commands. 7729@c It might seem like checking whether cvs -q diff 7730@c produces empty or non-empty output can tell whether 7731@c there were differences or not. But it seems like 7732@c there are cases with output but no differences 7733@c (testsuite basica-8b). It is not clear to me how 7734@c useful it is for a script to be able to check 7735@c whether there were differences. 7736@c FIXCVS? In previous versions of CVS, cvs diff 7737@c returned 0 for no differences, 1 for differences, or 7738@c 2 for errors. Is this behavior worth trying to 7739@c bring back (but what does it mean for VMS?)? 7740 7741@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7742@node ~/.cvsrc 7743@appendixsec Default options and the ~/.cvsrc file 7744@cindex .cvsrc file 7745@cindex Option defaults 7746 7747There are some @code{command_options} that are used so 7748often that you might have set up an alias or some other 7749means to make sure you always specify that option. One 7750example (the one that drove the implementation of the 7751@file{.cvsrc} support, actually) is that many people find the 7752default output of the @samp{diff} command to be very 7753hard to read, and that either context diffs or unidiffs 7754are much easier to understand. 7755 7756The @file{~/.cvsrc} file is a way that you can add 7757default options to @code{cvs_commands} within cvs, 7758instead of relying on aliases or other shell scripts. 7759 7760The format of the @file{~/.cvsrc} file is simple. The 7761file is searched for a line that begins with the same 7762name as the @code{cvs_command} being executed. If a 7763match is found, then the remainder of the line is split 7764up (at whitespace characters) into separate options and 7765added to the command arguments @emph{before} any 7766options from the command line. 7767 7768If a command has two names (e.g., @code{checkout} and 7769@code{co}), the official name, not necessarily the one 7770used on the command line, will be used to match against 7771the file. So if this is the contents of the user's 7772@file{~/.cvsrc} file: 7773 7774@example 7775log -N 7776diff -uN 7777rdiff -u 7778update -Pd 7779checkout -P 7780release -d 7781@end example 7782 7783@noindent 7784the command @samp{cvs checkout foo} would have the 7785@samp{-P} option added to the arguments, as well as 7786@samp{cvs co foo}. 7787 7788With the example file above, the output from @samp{cvs 7789diff foobar} will be in unidiff format. @samp{cvs diff 7790-c foobar} will provide context diffs, as usual. 7791Getting "old" format diffs would be slightly more 7792complicated, because @code{diff} doesn't have an option 7793to specify use of the "old" format, so you would need 7794@samp{cvs -f diff foobar}. 7795 7796In place of the command name you can use @code{cvs} to 7797specify global options (@pxref{Global options}). For 7798example the following line in @file{.cvsrc} 7799 7800@example 7801cvs -z6 7802@end example 7803 7804@noindent 7805causes @sc{cvs} to use compression level 6. 7806 7807@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7808@node Global options 7809@appendixsec Global options 7810@cindex Options, global 7811@cindex Global options 7812@cindex Left-hand options 7813 7814The available @samp{cvs_options} (that are given to the 7815left of @samp{cvs_command}) are: 7816 7817@table @code 7818@item --allow-root=@var{rootdir} 7819Specify legal @sc{cvsroot} directory. See 7820@ref{Password authentication server}. 7821 7822@cindex Authentication, stream 7823@cindex Stream authentication 7824@item -a 7825Authenticate all communication between the client and 7826the server. Only has an effect on the @sc{cvs} client. 7827As of this writing, this is only implemented when using 7828a GSSAPI connection (@pxref{GSSAPI authenticated}). 7829Authentication prevents certain sorts of attacks 7830involving hijacking the active @sc{tcp} connection. 7831Enabling authentication does not enable encryption. 7832 7833@cindex RCSBIN, overriding 7834@cindex Overriding RCSBIN 7835@item -b @var{bindir} 7836In @sc{cvs} 1.9.18 and older, this specified that 7837@sc{rcs} programs are in the @var{bindir} directory. 7838Current versions of @sc{cvs} do not run @sc{rcs} 7839programs; for compatibility this option is accepted, 7840but it does nothing. 7841 7842@cindex TMPDIR, overriding 7843@cindex Overriding TMPDIR 7844@item -T @var{tempdir} 7845Use @var{tempdir} as the directory where temporary files are 7846located. Overrides the setting of the @code{$TMPDIR} environment 7847variable and any precompiled directory. This parameter should be 7848specified as an absolute pathname. 7849(When running client/server, @samp{-T} affects only the local process; 7850specifying @samp{-T} for the client has no effect on the server and 7851vice versa.) 7852 7853@cindex CVSROOT, overriding 7854@cindex Overriding CVSROOT 7855@item -d @var{cvs_root_directory} 7856Use @var{cvs_root_directory} as the root directory 7857pathname of the repository. Overrides the setting of 7858the @code{$CVSROOT} environment variable. @xref{Repository}. 7859 7860@cindex EDITOR, overriding 7861@cindex Overriding EDITOR 7862@item -e @var{editor} 7863Use @var{editor} to enter revision log information. Overrides the 7864setting of the @code{$CVSEDITOR} and @code{$EDITOR} 7865environment variables. For more information, see 7866@ref{Committing your changes}. 7867 7868@item -f 7869Do not read the @file{~/.cvsrc} file. This 7870option is most often used because of the 7871non-orthogonality of the @sc{cvs} option set. For 7872example, the @samp{cvs log} option @samp{-N} (turn off 7873display of tag names) does not have a corresponding 7874option to turn the display on. So if you have 7875@samp{-N} in the @file{~/.cvsrc} entry for @samp{log}, 7876you may need to use @samp{-f} to show the tag names. 7877 7878@item -H 7879@itemx --help 7880Display usage information about the specified @samp{cvs_command} 7881(but do not actually execute the command). If you don't specify 7882a command name, @samp{cvs -H} displays overall help for 7883@sc{cvs}, including a list of other help options. 7884@c It seems to me it is better to document it this way 7885@c rather than trying to update this documentation 7886@c every time that we add a --help-foo option. But 7887@c perhaps that is confusing... 7888 7889@item -l 7890Do not log the @samp{cvs_command} in the command history (but execute it 7891anyway). @xref{history}, for information on command history. 7892 7893@cindex Read-only repository mode 7894@item -R 7895Turns on read-only repository mode. This allows one to check out from a 7896read-only repository, such as within an anoncvs server, or from a CDROM 7897repository. 7898 7899Same effect as if the @code{CVSREADONLYFS} environment 7900variable is set. Using @samp{-R} can also considerably 7901speed up checkout's over NFS. 7902 7903@cindex Read-only mode 7904@item -n 7905Do not change any files. Attempt to execute the 7906@samp{cvs_command}, but only to issue reports; do not remove, 7907update, or merge any existing files, or create any new files. 7908 7909Note that @sc{cvs} will not necessarily produce exactly 7910the same output as without @samp{-n}. In some cases 7911the output will be the same, but in other cases 7912@sc{cvs} will skip some of the processing that would 7913have been required to produce the exact same output. 7914 7915@item -Q 7916Cause the command to be really quiet; the command will only 7917generate output for serious problems. 7918 7919@item -q 7920Cause the command to be somewhat quiet; informational messages, 7921such as reports of recursion through subdirectories, are 7922suppressed. 7923 7924@cindex Read-only files, and -r 7925@item -r 7926Make new working files read-only. Same effect 7927as if the @code{$CVSREAD} environment variable is set 7928(@pxref{Environment variables}). The default is to 7929make working files writable, unless watches are on 7930(@pxref{Watches}). 7931 7932@item -s @var{variable}=@var{value} 7933Set a user variable (@pxref{Variables}). 7934 7935@cindex Trace 7936@item -t 7937Trace program execution; display messages showing the steps of 7938@sc{cvs} activity. Particularly useful with @samp{-n} to explore the 7939potential impact of an unfamiliar command. 7940 7941@item -v 7942@item --version 7943Display version and copyright information for @sc{cvs}. 7944 7945@cindex CVSREAD, overriding 7946@cindex Overriding CVSREAD 7947@item -w 7948Make new working files read-write. Overrides the 7949setting of the @code{$CVSREAD} environment variable. 7950Files are created read-write by default, unless @code{$CVSREAD} is 7951set or @samp{-r} is given. 7952@c Note that -w only overrides -r and CVSREAD; it has 7953@c no effect on files which are readonly because of 7954@c "cvs watch on". My guess is that is the way it 7955@c should be (or should "cvs -w get" on a watched file 7956@c be the same as a get and a cvs edit?), but I'm not 7957@c completely sure whether to document it this way. 7958 7959@item -x 7960@cindex Encryption 7961Encrypt all communication between the client and the 7962server. Only has an effect on the @sc{cvs} client. As 7963of this writing, this is only implemented when using a 7964GSSAPI connection (@pxref{GSSAPI authenticated}) or a 7965Kerberos connection (@pxref{Kerberos authenticated}). 7966Enabling encryption implies that message traffic is 7967also authenticated. Encryption support is not 7968available by default; it must be enabled using a 7969special configure option, @file{--enable-encryption}, 7970when you build @sc{cvs}. 7971 7972@item -z @var{gzip-level} 7973@cindex Compression 7974@cindex Gzip 7975Set the compression level. 7976Valid levels are 1 (high speed, low compression) to 79779 (low speed, high compression), or 0 to disable 7978compression (the default). 7979Only has an effect on the @sc{cvs} client. 7980 7981@end table 7982 7983@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7984@node Common options 7985@appendixsec Common command options 7986@cindex Common options 7987@cindex Right-hand options 7988 7989This section describes the @samp{command_options} that 7990are available across several @sc{cvs} commands. These 7991options are always given to the right of 7992@samp{cvs_command}. Not all 7993commands support all of these options; each option is 7994only supported for commands where it makes sense. 7995However, when a command has one of these options you 7996can almost always count on the same behavior of the 7997option as in other commands. (Other command options, 7998which are listed with the individual commands, may have 7999different behavior from one @sc{cvs} command to the other). 8000 8001@strong{Note: the @samp{history} command is an exception; it supports 8002many options that conflict even with these standard options.} 8003 8004@table @code 8005@cindex Dates 8006@cindex Time 8007@cindex Specifying dates 8008@item -D @var{date_spec} 8009Use the most recent revision no later than @var{date_spec}. 8010@var{date_spec} is a single argument, a date description 8011specifying a date in the past. 8012 8013The specification is @dfn{sticky} when you use it to make a 8014private copy of a source file; that is, when you get a working 8015file using @samp{-D}, @sc{cvs} records the date you specified, so that 8016further updates in the same directory will use the same date 8017(for more information on sticky tags/dates, @pxref{Sticky tags}). 8018 8019@samp{-D} is available with the @code{annotate}, @code{checkout}, 8020@code{diff}, @code{export}, @code{history}, 8021@code{rdiff}, @code{rtag}, @code{tag}, and @code{update} commands. 8022(The @code{history} command uses this option in a 8023slightly different way; @pxref{history options}). 8024 8025@c What other formats should we accept? I don't want 8026@c to start accepting a whole mess of non-standard 8027@c new formats (there are a lot which are in wide use in 8028@c one context or another), but practicality does 8029@c dictate some level of flexibility. 8030@c * POSIX.2 (e.g. touch, ls output, date) and other 8031@c POSIX and/or de facto unix standards (e.g. at). The 8032@c practice here is too inconsistent to be of any use. 8033@c * VMS dates. This is not a formal standard, but 8034@c there is a published specification (see SYS$ASCTIM 8035@c and SYS$BINTIM in the _VMS System Services Reference 8036@c Manual_), it is implemented consistently in VMS 8037@c utilities, and VMS users will expect CVS running on 8038@c VMS to support this format (and if we're going to do 8039@c that, better to make CVS support it on all 8040@c platforms. Maybe). 8041@c 8042@c NOTE: The tar manual has some documentation for 8043@c getdate.y (just for our info; we don't want to 8044@c attempt to document all the formats accepted by 8045@c getdate.y). 8046@c 8047@c One more note: In output, CVS should consistently 8048@c use one date format, and that format should be one that 8049@c it accepts in input as well. The former isn't 8050@c really true (see survey below), and I'm not 8051@c sure that either of those formats is accepted in 8052@c input. 8053@c 8054@c cvs log 8055@c current 1996/01/02 13:45:31 8056@c Internet 02 Jan 1996 13:45:31 UT 8057@c ISO 1996-01-02 13:45:31 8058@c cvs ann 8059@c current 02-Jan-96 8060@c Internet-like 02 Jan 96 8061@c ISO 96-01-02 8062@c cvs status 8063@c current Tue Jun 11 02:54:53 1996 8064@c Internet [Tue,] 11 Jun 1996 02:54:53 8065@c ISO 1996-06-11 02:54:53 8066@c note: date possibly should be omitted entirely for 8067@c other reasons. 8068@c cvs editors 8069@c current Tue Jun 11 02:54:53 1996 GMT 8070@c cvs history 8071@c current 06/11 02:54 +0000 8072@c any others? 8073@c There is a good chance the proper solution has to 8074@c involve at least some level of letting the user 8075@c decide which format (with the default being the 8076@c formats CVS has always used; changing these might be 8077@c _very_ disruptive since scripts may very well be 8078@c parsing them). 8079@c 8080@c Another random bit of prior art concerning dates is 8081@c the strptime function which takes templates such as 8082@c "%m/%d/%y", and apparent a variant of getdate() 8083@c which also honors them. See 8084@c X/Open CAE Specification, System Interfaces and 8085@c Headers Issue 4, Version 2 (September 1994), in the 8086@c entry for getdate() on page 231 8087 8088@cindex Timezone, in input 8089@cindex Zone, time, in input 8090A wide variety of date formats are supported by 8091@sc{cvs}. The most standard ones are ISO8601 (from the 8092International Standards Organization) and the Internet 8093e-mail standard (specified in RFC822 as amended by 8094RFC1123). 8095 8096@c Probably should be doing more to spell out just what 8097@c the rules are, rather than just giving examples. 8098@c But I want to keep this simple too. 8099@c So I don't know.... 8100@c A few specific issues: (1) Maybe should reassure 8101@c people that years after 2000 8102@c work (they are in the testsuite, so they do indeed 8103@c work). (2) What do two digit years 8104@c mean? Where do we accept them? (3) Local times can 8105@c be ambiguous or nonexistent if they fall during the 8106@c hour when daylight savings time goes into or out of 8107@c effect. Pretty obscure, so I'm not at all sure we 8108@c should be documenting the behavior in that case. 8109ISO8601 dates have many variants but a few examples 8110are: 8111 8112@example 81131972-09-24 81141972-09-24 20:05 8115@end example 8116@c I doubt we really accept all ISO8601 format dates 8117@c (for example, decimal hours like 1972-09-24 20,2) 8118@c I'm not sure we should, many of them are pretty 8119@c bizarre and it has lots of gratuitous multiple ways 8120@c to specify the same thing. 8121 8122There are a lot more ISO8601 date formats, and @sc{cvs} 8123accepts many of them, but you probably don't want to 8124hear the @emph{whole} long story :-). 8125 8126@c Citing a URL here is kind of problematic given how 8127@c much they change and people who have old versions of 8128@c this manual, but in case we want to reinstate an 8129@c ISO8601 URL, a few are: 8130@c http://www.saqqara.demon.co.uk/datefmt.htm 8131@c http://www.cl.cam.ac.uk/~mgk25/iso-time.html 8132@c Citing some other ISO8601 source is probably even 8133@c worse :-). 8134 8135In addition to the dates allowed in Internet e-mail 8136itself, @sc{cvs} also allows some of the fields to be 8137omitted. For example: 8138@c FIXME: Need to figure out better, and document, 8139@c what we want to allow the user to omit. 8140@c NOTE: "omit" does not imply "reorder". 8141@c FIXME: Need to cite a web page describing how to get 8142@c RFC's. 8143 8144@example 814524 Sep 1972 20:05 814624 Sep 8147@end example 8148 8149The date is interpreted as being in the 8150local timezone, unless a specific timezone is 8151specified. 8152 8153These two date formats are preferred. However, 8154@sc{cvs} currently accepts a wide variety of other date 8155formats. They are intentionally not documented here in 8156any detail, and future versions of @sc{cvs} might not 8157accept all of them. 8158@c We should document and testsuite "now" and 8159@c "yesterday". "now" is mentioned in the FAQ and 8160@c "yesterday" is mentioned in this document (and the 8161@c message from "cvs import" suggesting a merge 8162@c command). What else? Probably some/all of the "3 8163@c weeks ago" family. 8164@c 8165@c Maybe at 8166@c some point have CVS start give warnings on "unofficial" 8167@c formats (many of which might be typos or user 8168@c misunderstandings, and/or formats people never/rarely 8169@c use to specify dates)? 8170 8171One such format is 8172@code{@var{month}/@var{day}/@var{year}}. This may 8173confuse people who are accustomed to having the month 8174and day in the other order; @samp{1/4/96} is January 4, 8175not April 1. 8176 8177Remember to quote the argument to the @samp{-D} 8178flag so that your shell doesn't interpret spaces as 8179argument separators. A command using the @samp{-D} 8180flag can look like this: 8181 8182@example 8183$ cvs diff -D "1 hour ago" cvs.texinfo 8184@end example 8185 8186@cindex Forcing a tag match 8187@item -f 8188When you specify a particular date or tag to @sc{cvs} commands, they 8189normally ignore files that do not contain the tag (or did not 8190exist prior to the date) that you specified. Use the @samp{-f} option 8191if you want files retrieved even when there is no match for the 8192tag or date. (The most recent revision of the file 8193will be used). 8194 8195Note that even with @samp{-f}, a tag that you specify 8196must exist (that is, in some file, not necessary in 8197every file). This is so that @sc{cvs} will continue to 8198give an error if you mistype a tag name. 8199 8200@need 800 8201@samp{-f} is available with these commands: 8202@code{annotate}, @code{checkout}, @code{export}, 8203@code{rdiff}, @code{rtag}, and @code{update}. 8204 8205@strong{WARNING: The @code{commit} and @code{remove} 8206commands also have a 8207@samp{-f} option, but it has a different behavior for 8208those commands. See @ref{commit options}, and 8209@ref{Removing files}.} 8210 8211@item -k @var{kflag} 8212Override the default processing of RCS keywords other than 8213@samp{-kb}. @xref{Keyword substitution}, for the meaning of 8214@var{kflag}. Used with the @code{checkout} and @code{update} 8215commands, your @var{kflag} specification is 8216@dfn{sticky}; that is, when you use this option 8217with a @code{checkout} or @code{update} command, 8218@sc{cvs} associates your selected @var{kflag} with any files 8219it operates on, and continues to use that @var{kflag} with future 8220commands on the same files until you specify otherwise. 8221 8222The @samp{-k} option is available with the @code{add}, 8223@code{checkout}, @code{diff}, @code{export}, @code{import} and 8224@code{update} commands. 8225 8226@strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag 8227overrode the @samp{-kb} indication for a binary file. This could 8228sometimes corrupt binary files. @xref{Merging and keywords}, for 8229more.} 8230 8231@item -l 8232Local; run only in current working directory, rather than 8233recursing through subdirectories. 8234 8235Available with the following commands: @code{annotate}, @code{checkout}, 8236@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8237@code{log}, @code{rdiff}, @code{remove}, @code{rtag}, 8238@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8239and @code{watchers}. 8240 8241@cindex Editor, avoiding invocation of 8242@cindex Avoiding editor invocation 8243@item -m @var{message} 8244Use @var{message} as log information, instead of 8245invoking an editor. 8246 8247Available with the following commands: @code{add}, 8248@code{commit} and @code{import}. 8249 8250@item -n 8251Do not run any tag program. (A program can be 8252specified to run in the modules 8253database (@pxref{modules}); this option bypasses it). 8254 8255@strong{Note: this is not the same as the @samp{cvs -n} 8256program option, which you can specify to the left of a cvs command!} 8257 8258Available with the @code{checkout}, @code{commit}, @code{export}, 8259and @code{rtag} commands. 8260 8261@item -P 8262Prune empty directories. See @ref{Removing directories}. 8263 8264@item -p 8265Pipe the files retrieved from the repository to standard output, 8266rather than writing them in the current directory. Available 8267with the @code{checkout} and @code{update} commands. 8268 8269@item -R 8270Process directories recursively. This is on by default. 8271 8272Available with the following commands: @code{annotate}, @code{checkout}, 8273@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export}, 8274@code{rdiff}, @code{remove}, @code{rtag}, 8275@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch}, 8276and @code{watchers}. 8277 8278@item -r @var{tag} 8279@cindex HEAD, special tag 8280@cindex BASE, special tag 8281Use the revision specified by the @var{tag} argument instead of the 8282default @dfn{head} revision. As well as arbitrary tags defined 8283with the @code{tag} or @code{rtag} command, two special tags are 8284always available: @samp{HEAD} refers to the most recent version 8285available in the repository, and @samp{BASE} refers to the 8286revision you last checked out into the current working directory. 8287 8288@c FIXME: What does HEAD really mean? I believe that 8289@c the current answer is the head of the default branch 8290@c for all cvs commands except diff. For diff, it 8291@c seems to be (a) the head of the trunk (or the default 8292@c branch?) if there is no sticky tag, (b) the head of the 8293@c branch for the sticky tag, if there is a sticky tag. 8294@c (b) is ugly as it differs 8295@c from what HEAD means for other commands, but people 8296@c and/or scripts are quite possibly used to it. 8297@c See "head" tests in sanity.sh. 8298@c Probably the best fix is to introduce two new 8299@c special tags, ".thead" for the head of the trunk, 8300@c and ".bhead" for the head of the current branch. 8301@c Then deprecate HEAD. This has the advantage of 8302@c not surprising people with a change to HEAD, and a 8303@c side benefit of also phasing out the poorly-named 8304@c HEAD (see discussion of reserved tag names in node 8305@c "Tags"). Of course, .thead and .bhead should be 8306@c carefully implemented (with the implementation the 8307@c same for "diff" as for everyone else), test cases 8308@c written (similar to the ones in "head"), new tests 8309@c cases written for things like default branches, &c. 8310 8311The tag specification is sticky when you use this 8312@c option 8313with @code{checkout} or @code{update} to make your own 8314copy of a file: @sc{cvs} remembers the tag and continues to use it on 8315future update commands, until you specify otherwise (for more information 8316on sticky tags/dates, @pxref{Sticky tags}). 8317 8318The tag can be either a symbolic or numeric tag, as 8319described in @ref{Tags}, or the name of a branch, as 8320described in @ref{Branching and merging}. 8321 8322Specifying the @samp{-q} global option along with the 8323@samp{-r} command option is often useful, to suppress 8324the warning messages when the @sc{rcs} file 8325does not contain the specified tag. 8326 8327@strong{Note: this is not the same as the overall @samp{cvs -r} option, 8328which you can specify to the left of a @sc{cvs} command!} 8329 8330@samp{-r} is available with the @code{checkout}, @code{commit}, 8331@code{diff}, @code{history}, @code{export}, @code{rdiff}, 8332@code{rtag}, and @code{update} commands. 8333 8334@item -W 8335Specify file names that should be filtered. You can 8336use this option repeatedly. The spec can be a file 8337name pattern of the same type that you can specify in 8338the @file{.cvswrappers} file. 8339Available with the following commands: @code{import}, 8340and @code{update}. 8341 8342@end table 8343 8344@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8345@node admin 8346@appendixsec admin---Administration 8347@cindex Admin (subcommand) 8348 8349@itemize @bullet 8350@item 8351Requires: repository, working directory. 8352@item 8353Changes: repository. 8354@item 8355Synonym: rcs 8356@end itemize 8357 8358This is the @sc{cvs} interface to assorted 8359administrative facilities. Some of them have 8360questionable usefulness for @sc{cvs} but exist for 8361historical purposes. Some of the questionable options 8362are likely to disappear in the future. This command 8363@emph{does} work recursively, so extreme care should be 8364used. 8365 8366@cindex cvsadmin 8367@cindex UserAdminOptions, in CVSROOT/config 8368On unix, if there is a group named @code{cvsadmin}, 8369only members of that group can run @code{cvs admin} 8370commands, except for those specified using the 8371@code{UserAdminOptions} configuration option in the 8372@file{CVSROOT/config} file. Options specified using 8373@code{UserAdminOptions} can be run by any user. See 8374@ref{config} for more on @code{UserAdminOptions}. 8375 8376The @code{cvsadmin} group should exist on the server, 8377or any system running the non-client/server @sc{cvs}. 8378To disallow @code{cvs admin} for all users, create a 8379group with no users in it. On NT, the @code{cvsadmin} 8380feature does not exist and all users 8381can run @code{cvs admin}. 8382 8383@menu 8384* admin options:: admin options 8385@end menu 8386 8387@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8388@node admin options 8389@appendixsubsec admin options 8390 8391Some of these options have questionable usefulness for 8392@sc{cvs} but exist for historical purposes. Some even 8393make it impossible to use @sc{cvs} until you undo the 8394effect! 8395 8396@table @code 8397@item -A@var{oldfile} 8398Might not work together with @sc{cvs}. Append the 8399access list of @var{oldfile} to the access list of the 8400@sc{rcs} file. 8401 8402@item -a@var{logins} 8403Might not work together with @sc{cvs}. Append the 8404login names appearing in the comma-separated list 8405@var{logins} to the access list of the @sc{rcs} file. 8406 8407@item -b[@var{rev}] 8408Set the default branch to @var{rev}. In @sc{cvs}, you 8409normally do not manipulate default branches; sticky 8410tags (@pxref{Sticky tags}) are a better way to decide 8411which branch you want to work on. There is one reason 8412to run @code{cvs admin -b}: to revert to the vendor's 8413version when using vendor branches (@pxref{Reverting 8414local changes}). 8415There can be no space between @samp{-b} and its argument. 8416@c Hmm, we don't document the usage where rev is 8417@c omitted. Maybe that usage can/should be deprecated 8418@c (and replaced with -bHEAD or something?) (so we can toss 8419@c the optional argument). Note that -bHEAD does not 8420@c work, as of 17 Sep 1997, but probably will once "cvs 8421@c admin" is internal to CVS. 8422 8423@cindex Comment leader 8424@item -c@var{string} 8425Sets the comment leader to @var{string}. The comment 8426leader is not used by current versions of @sc{cvs} or 8427@sc{rcs} 5.7. Therefore, you can almost surely not 8428worry about it. @xref{Keyword substitution}. 8429 8430@item -e[@var{logins}] 8431Might not work together with @sc{cvs}. Erase the login 8432names appearing in the comma-separated list 8433@var{logins} from the access list of the RCS file. If 8434@var{logins} is omitted, erase the entire access list. 8435There can be no space between @samp{-e} and its argument. 8436 8437@item -I 8438Run interactively, even if the standard input is not a 8439terminal. This option does not work with the 8440client/server @sc{cvs} and is likely to disappear in 8441a future release of @sc{cvs}. 8442 8443@item -i 8444Useless with @sc{cvs}. This creates and initializes a 8445new @sc{rcs} file, without depositing a revision. With 8446@sc{cvs}, add files with the @code{cvs add} command 8447(@pxref{Adding files}). 8448 8449@item -k@var{subst} 8450Set the default keyword 8451substitution to @var{subst}. @xref{Keyword 8452substitution}. Giving an explicit @samp{-k} option to 8453@code{cvs update}, @code{cvs export}, or @code{cvs 8454checkout} overrides this default. 8455 8456@item -l[@var{rev}] 8457Lock the revision with number @var{rev}. If a branch 8458is given, lock the latest revision on that branch. If 8459@var{rev} is omitted, lock the latest revision on the 8460default branch. There can be no space between 8461@samp{-l} and its argument. 8462 8463This can be used in conjunction with the 8464@file{rcslock.pl} script in the @file{contrib} 8465directory of the @sc{cvs} source distribution to 8466provide reserved checkouts (where only one user can be 8467editing a given file at a time). See the comments in 8468that file for details (and see the @file{README} file 8469in that directory for disclaimers about the unsupported 8470nature of contrib). According to comments in that 8471file, locking must set to strict (which is the default). 8472 8473@item -L 8474Set locking to strict. Strict locking means that the 8475owner of an RCS file is not exempt from locking for 8476checkin. For use with @sc{cvs}, strict locking must be 8477set; see the discussion under the @samp{-l} option above. 8478 8479@cindex Changing a log message 8480@cindex Replacing a log message 8481@cindex Correcting a log message 8482@cindex Fixing a log message 8483@cindex Log message, correcting 8484@item -m@var{rev}:@var{msg} 8485Replace the log message of revision @var{rev} with 8486@var{msg}. 8487 8488@c The rcs -M option, to suppress sending mail, has never been 8489@c documented as a cvs admin option. 8490 8491@item -N@var{name}[:[@var{rev}]] 8492Act like @samp{-n}, except override any previous 8493assignment of @var{name}. For use with magic branches, 8494see @ref{Magic branch numbers}. 8495 8496@item -n@var{name}[:[@var{rev}]] 8497Associate the symbolic name @var{name} with the branch 8498or revision @var{rev}. It is normally better to use 8499@samp{cvs tag} or @samp{cvs rtag} instead. Delete the 8500symbolic name if both @samp{:} and @var{rev} are 8501omitted; otherwise, print an error message if 8502@var{name} is already associated with another number. 8503If @var{rev} is symbolic, it is expanded before 8504association. A @var{rev} consisting of a branch number 8505followed by a @samp{.} stands for the current latest 8506revision in the branch. A @samp{:} with an empty 8507@var{rev} stands for the current latest revision on the 8508default branch, normally the trunk. For example, 8509@samp{cvs admin -n@var{name}:} associates @var{name} with the 8510current latest revision of all the RCS files; 8511this contrasts with @samp{cvs admin -n@var{name}:$} which 8512associates @var{name} with the revision numbers 8513extracted from keyword strings in the corresponding 8514working files. 8515 8516@cindex Deleting revisions 8517@cindex Outdating revisions 8518@cindex Saving space 8519@item -o@var{range} 8520Deletes (@dfn{outdates}) the revisions given by 8521@var{range}. 8522 8523Note that this command can be quite dangerous unless 8524you know @emph{exactly} what you are doing (for example 8525see the warnings below about how the 8526@var{rev1}:@var{rev2} syntax is confusing). 8527 8528If you are short on disc this option might help you. 8529But think twice before using it---there is no way short 8530of restoring the latest backup to undo this command! 8531If you delete different revisions than you planned, 8532either due to carelessness or (heaven forbid) a @sc{cvs} 8533bug, there is no opportunity to correct the error 8534before the revisions are deleted. It probably would be 8535a good idea to experiment on a copy of the repository 8536first. 8537 8538Specify @var{range} in one of the following ways: 8539 8540@table @code 8541@item @var{rev1}::@var{rev2} 8542Collapse all revisions between rev1 and rev2, so that 8543@sc{cvs} only stores the differences associated with going 8544from rev1 to rev2, not intermediate steps. For 8545example, after @samp{-o 1.3::1.5} one can retrieve 8546revision 1.3, revision 1.5, or the differences to get 8547from 1.3 to 1.5, but not the revision 1.4, or the 8548differences between 1.3 and 1.4. Other examples: 8549@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no 8550effect, because there are no intermediate revisions to 8551remove. 8552 8553@item ::@var{rev} 8554Collapse revisions between the beginning of the branch 8555containing @var{rev} and @var{rev} itself. The 8556branchpoint and @var{rev} are left intact. For 8557example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1, 8558revision 1.3.2.5, and everything in between, but leaves 85591.3 and 1.3.2.6 intact. 8560 8561@item @var{rev}:: 8562Collapse revisions between @var{rev} and the end of the 8563branch containing @var{rev}. Revision @var{rev} is 8564left intact but the head revision is deleted. 8565 8566@item @var{rev} 8567Delete the revision @var{rev}. For example, @samp{-o 85681.3} is equivalent to @samp{-o 1.2::1.4}. 8569 8570@item @var{rev1}:@var{rev2} 8571Delete the revisions from @var{rev1} to @var{rev2}, 8572inclusive, on the same branch. One will not be able to 8573retrieve @var{rev1} or @var{rev2} or any of the 8574revisions in between. For example, the command 8575@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful. 8576It means to delete revisions up to, and including, the 8577tag R_1_02. But beware! If there are files that have not 8578changed between R_1_02 and R_1_03 the file will have 8579@emph{the same} numerical revision number assigned to 8580the tags R_1_02 and R_1_03. So not only will it be 8581impossible to retrieve R_1_02; R_1_03 will also have to 8582be restored from the tapes! In most cases you want to 8583specify @var{rev1}::@var{rev2} instead. 8584 8585@item :@var{rev} 8586Delete revisions from the beginning of the 8587branch containing @var{rev} up to and including 8588@var{rev}. 8589 8590@item @var{rev}: 8591Delete revisions from revision @var{rev}, including 8592@var{rev} itself, to the end of the branch containing 8593@var{rev}. 8594@end table 8595 8596None of the revisions to be deleted may have 8597branches or locks. 8598 8599If any of the revisions to be deleted have symbolic 8600names, and one specifies one of the @samp{::} syntaxes, 8601then @sc{cvs} will give an error and not delete any 8602revisions. If you really want to delete both the 8603symbolic names and the revisions, first delete the 8604symbolic names with @code{cvs tag -d}, then run 8605@code{cvs admin -o}. If one specifies the 8606non-@samp{::} syntaxes, then @sc{cvs} will delete the 8607revisions but leave the symbolic names pointing to 8608nonexistent revisions. This behavior is preserved for 8609compatibility with previous versions of @sc{cvs}, but 8610because it isn't very useful, in the future it may 8611change to be like the @samp{::} case. 8612 8613Due to the way @sc{cvs} handles branches @var{rev} 8614cannot be specified symbolically if it is a branch. 8615@xref{Magic branch numbers}, for an explanation. 8616@c FIXME: is this still true? I suspect not. 8617 8618Make sure that no-one has checked out a copy of the 8619revision you outdate. Strange things will happen if he 8620starts to edit it and tries to check it back in. For 8621this reason, this option is not a good way to take back 8622a bogus commit; commit a new revision undoing the bogus 8623change instead (@pxref{Merging two revisions}). 8624 8625@item -q 8626Run quietly; do not print diagnostics. 8627 8628@item -s@var{state}[:@var{rev}] 8629Useful with @sc{cvs}. Set the state attribute of the 8630revision @var{rev} to @var{state}. If @var{rev} is a 8631branch number, assume the latest revision on that 8632branch. If @var{rev} is omitted, assume the latest 8633revision on the default branch. Any identifier is 8634acceptable for @var{state}. A useful set of states is 8635@samp{Exp} (for experimental), @samp{Stab} (for 8636stable), and @samp{Rel} (for released). By default, 8637the state of a new revision is set to @samp{Exp} when 8638it is created. The state is visible in the output from 8639@var{cvs log} (@pxref{log}), and in the 8640@samp{$ Log$} and @samp{$ State$} keywords 8641(@pxref{Keyword substitution}). Note that @sc{cvs} 8642uses the @code{dead} state for its own purposes; to 8643take a file to or from the @code{dead} state use 8644commands like @code{cvs remove} and @code{cvs add}, not 8645@code{cvs admin -s}. 8646 8647@item -t[@var{file}] 8648Useful with @sc{cvs}. Write descriptive text from the 8649contents of the named @var{file} into the RCS file, 8650deleting the existing text. The @var{file} pathname 8651may not begin with @samp{-}. The descriptive text can be seen in the 8652output from @samp{cvs log} (@pxref{log}). 8653There can be no space between @samp{-t} and its argument. 8654 8655If @var{file} is omitted, 8656obtain the text from standard input, terminated by 8657end-of-file or by a line containing @samp{.} by itself. 8658Prompt for the text if interaction is possible; see 8659@samp{-I}. 8660 8661@item -t-@var{string} 8662Similar to @samp{-t@var{file}}. Write descriptive text 8663from the @var{string} into the @sc{rcs} file, deleting 8664the existing text. 8665There can be no space between @samp{-t} and its argument. 8666 8667@c The rcs -T option, do not update last-mod time for 8668@c minor changes, has never been documented as a 8669@c cvs admin option. 8670 8671@item -U 8672Set locking to non-strict. Non-strict locking means 8673that the owner of a file need not lock a revision for 8674checkin. For use with @sc{cvs}, strict locking must be 8675set; see the discussion under the @samp{-l} option 8676above. 8677 8678@item -u[@var{rev}] 8679See the option @samp{-l} above, for a discussion of 8680using this option with @sc{cvs}. Unlock the revision 8681with number @var{rev}. If a branch is given, unlock 8682the latest revision on that branch. If @var{rev} is 8683omitted, remove the latest lock held by the caller. 8684Normally, only the locker of a revision may unlock it; 8685somebody else unlocking a revision breaks the lock. 8686This causes the original locker to be sent a @code{commit} 8687notification (@pxref{Getting Notified}). 8688There can be no space between @samp{-u} and its argument. 8689 8690@item -V@var{n} 8691In previous versions of @sc{cvs}, this option meant to 8692write an @sc{rcs} file which would be acceptable to 8693@sc{rcs} version @var{n}, but it is now obsolete and 8694specifying it will produce an error. 8695@c Note that -V without an argument has never been 8696@c documented as a cvs admin option. 8697 8698@item -x@var{suffixes} 8699In previous versions of @sc{cvs}, this was documented 8700as a way of specifying the names of the @sc{rcs} 8701files. However, @sc{cvs} has always required that the 8702@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so 8703this option has never done anything useful. 8704 8705@c The rcs -z option, to specify the timezone, has 8706@c never been documented as a cvs admin option. 8707@end table 8708 8709 8710@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8711@node checkout 8712@appendixsec checkout---Check out sources for editing 8713@cindex checkout (subcommand) 8714@cindex co (subcommand) 8715 8716@itemize @bullet 8717@item 8718Synopsis: checkout [options] modules@dots{} 8719@item 8720Requires: repository. 8721@item 8722Changes: working directory. 8723@item 8724Synonyms: co, get 8725@end itemize 8726 8727Create or update a working directory containing copies of the 8728source files specified by @var{modules}. You must execute 8729@code{checkout} before using most of the other @sc{cvs} 8730commands, since most of them operate on your working 8731directory. 8732 8733The @var{modules} are either 8734symbolic names for some 8735collection of source directories and files, or paths to 8736directories or files in the repository. The symbolic 8737names are defined in the @samp{modules} file. 8738@xref{modules}. 8739@c Needs an example, particularly of the non-"modules" 8740@c case but probably of both. 8741 8742@c FIXME: this seems like a very odd place to introduce 8743@c people to how CVS works. The bit about unreserved 8744@c checkouts is also misleading as it depends on how 8745@c things are set up. 8746Depending on the modules you specify, @code{checkout} may 8747recursively create directories and populate them with 8748the appropriate source files. You can then edit these 8749source files at any time (regardless of whether other 8750software developers are editing their own copies of the 8751sources); update them to include new changes applied by 8752others to the source repository; or commit your work as 8753a permanent change to the source repository. 8754 8755Note that @code{checkout} is used to create 8756directories. The top-level directory created is always 8757added to the directory where @code{checkout} is 8758invoked, and usually has the same name as the specified 8759module. In the case of a module alias, the created 8760sub-directory may have a different name, but you can be 8761sure that it will be a sub-directory, and that 8762@code{checkout} will show the relative path leading to 8763each file as it is extracted into your private work 8764area (unless you specify the @samp{-Q} global option). 8765 8766The files created by @code{checkout} are created 8767read-write, unless the @samp{-r} option to @sc{cvs} 8768(@pxref{Global options}) is specified, the 8769@code{CVSREAD} environment variable is specified 8770(@pxref{Environment variables}), or a watch is in 8771effect for that file (@pxref{Watches}). 8772 8773Note that running @code{checkout} on a directory that was already 8774built by a prior @code{checkout} is also permitted. 8775This is similar to specifying the @samp{-d} option 8776to the @code{update} command in the sense that new 8777directories that have been created in the repository 8778will appear in your work area. 8779However, @code{checkout} takes a module name whereas 8780@code{update} takes a directory name. Also 8781to use @code{checkout} this way it must be run from the 8782top level directory (where you originally ran 8783@code{checkout} from), so before you run 8784@code{checkout} to update an existing directory, don't 8785forget to change your directory to the top level 8786directory. 8787 8788For the output produced by the @code{checkout} command 8789see @ref{update output}. 8790 8791@menu 8792* checkout options:: checkout options 8793* checkout examples:: checkout examples 8794@end menu 8795 8796@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8797@node checkout options 8798@appendixsubsec checkout options 8799 8800These standard options are supported by @code{checkout} 8801(@pxref{Common options}, for a complete description of 8802them): 8803 8804@table @code 8805@item -D @var{date} 8806Use the most recent revision no later than @var{date}. 8807This option is sticky, and implies @samp{-P}. See 8808@ref{Sticky tags}, for more information on sticky tags/dates. 8809 8810@item -f 8811Only useful with the @samp{-D @var{date}} or @samp{-r 8812@var{tag}} flags. If no matching revision is found, 8813retrieve the most recent revision (instead of ignoring 8814the file). 8815 8816@item -k @var{kflag} 8817Process keywords according to @var{kflag}. See 8818@ref{Keyword substitution}. 8819This option is sticky; future updates of 8820this file in this working directory will use the same 8821@var{kflag}. The @code{status} command can be viewed 8822to see the sticky options. See @ref{Invoking CVS}, for 8823more information on the @code{status} command. 8824 8825@item -l 8826Local; run only in current working directory. 8827 8828@item -n 8829Do not run any checkout program (as specified 8830with the @samp{-o} option in the modules file; 8831@pxref{modules}). 8832 8833@item -P 8834Prune empty directories. See @ref{Moving directories}. 8835 8836@item -p 8837Pipe files to the standard output. 8838 8839@item -R 8840Checkout directories recursively. This option is on by default. 8841 8842@item -r @var{tag} 8843Use revision @var{tag}. This option is sticky, and implies @samp{-P}. 8844See @ref{Sticky tags}, for more information on sticky tags/dates. 8845@end table 8846 8847In addition to those, you can use these special command 8848options with @code{checkout}: 8849 8850@table @code 8851@item -A 8852Reset any sticky tags, dates, or @samp{-k} options. 8853See @ref{Sticky tags}, for more information on sticky tags/dates. 8854 8855@item -c 8856Copy the module file, sorted, to the standard output, 8857instead of creating or modifying any files or 8858directories in your working directory. 8859 8860@item -d @var{dir} 8861Create a directory called @var{dir} for the working 8862files, instead of using the module name. In general, 8863using this flag is equivalent to using @samp{mkdir 8864@var{dir}; cd @var{dir}} followed by the checkout 8865command without the @samp{-d} flag. 8866 8867There is an important exception, however. It is very 8868convenient when checking out a single item to have the 8869output appear in a directory that doesn't contain empty 8870intermediate directories. In this case @emph{only}, 8871@sc{cvs} tries to ``shorten'' pathnames to avoid those empty 8872directories. 8873 8874For example, given a module @samp{foo} that contains 8875the file @samp{bar.c}, the command @samp{cvs co -d dir 8876foo} will create directory @samp{dir} and place 8877@samp{bar.c} inside. Similarly, given a module 8878@samp{bar} which has subdirectory @samp{baz} wherein 8879there is a file @samp{quux.c}, the command @samp{cvs co 8880-d dir bar/baz} will create directory @samp{dir} and 8881place @samp{quux.c} inside. 8882 8883Using the @samp{-N} flag will defeat this behavior. 8884Given the same module definitions above, @samp{cvs co 8885-N -d dir foo} will create directories @samp{dir/foo} 8886and place @samp{bar.c} inside, while @samp{cvs co -N -d 8887dir bar/baz} will create directories @samp{dir/bar/baz} 8888and place @samp{quux.c} inside. 8889 8890@item -j @var{tag} 8891With two @samp{-j} options, merge changes from the 8892revision specified with the first @samp{-j} option to 8893the revision specified with the second @samp{j} option, 8894into the working directory. 8895 8896With one @samp{-j} option, merge changes from the 8897ancestor revision to the revision specified with the 8898@samp{-j} option, into the working directory. The 8899ancestor revision is the common ancestor of the 8900revision which the working directory is based on, and 8901the revision specified in the @samp{-j} option. 8902 8903In addition, each -j option can contain an optional 8904date specification which, when used with branches, can 8905limit the chosen revision to one within a specific 8906date. An optional date is specified by adding a colon 8907(:) to the tag: 8908@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 8909 8910@xref{Branching and merging}. 8911 8912@item -N 8913Only useful together with @samp{-d @var{dir}}. With 8914this option, @sc{cvs} will not ``shorten'' module paths 8915in your working directory when you check out a single 8916module. See the @samp{-d} flag for examples and a 8917discussion. 8918 8919@item -s 8920Like @samp{-c}, but include the status of all modules, 8921and sort it by the status string. @xref{modules}, for 8922info about the @samp{-s} option that is used inside the 8923modules file to set the module status. 8924@end table 8925 8926@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8927@node checkout examples 8928@appendixsubsec checkout examples 8929 8930Get a copy of the module @samp{tc}: 8931 8932@example 8933$ cvs checkout tc 8934@end example 8935 8936Get a copy of the module @samp{tc} as it looked one day 8937ago: 8938 8939@example 8940$ cvs checkout -D yesterday tc 8941@end example 8942 8943@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 8944@node commit 8945@appendixsec commit---Check files into the repository 8946@cindex commit (subcommand) 8947 8948@itemize @bullet 8949@item 8950Synopsis: commit [-lnRf] [-m 'log_message' | 8951-F file] [-r revision] [files@dots{}] 8952@item 8953Requires: working directory, repository. 8954@item 8955Changes: repository. 8956@item 8957Synonym: ci 8958@end itemize 8959 8960Use @code{commit} when you want to incorporate changes 8961from your working source files into the source 8962repository. 8963 8964If you don't specify particular files to commit, all of 8965the files in your working current directory are 8966examined. @code{commit} is careful to change in the 8967repository only those files that you have really 8968changed. By default (or if you explicitly specify the 8969@samp{-R} option), files in subdirectories are also 8970examined and committed if they have changed; you can 8971use the @samp{-l} option to limit @code{commit} to the 8972current directory only. 8973 8974@code{commit} verifies that the selected files are up 8975to date with the current revisions in the source 8976repository; it will notify you, and exit without 8977committing, if any of the specified files must be made 8978current first with @code{update} (@pxref{update}). 8979@code{commit} does not call the @code{update} command 8980for you, but rather leaves that for you to do when the 8981time is right. 8982 8983When all is well, an editor is invoked to allow you to 8984enter a log message that will be written to one or more 8985logging programs (@pxref{modules}, and @pxref{loginfo}) 8986and placed in the @sc{rcs} file inside the 8987repository. This log message can be retrieved with the 8988@code{log} command; see @ref{log}. You can specify the 8989log message on the command line with the @samp{-m 8990@var{message}} option, and thus avoid the editor invocation, 8991or use the @samp{-F @var{file}} option to specify 8992that the argument file contains the log message. 8993 8994@menu 8995* commit options:: commit options 8996* commit examples:: commit examples 8997@end menu 8998 8999@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9000@node commit options 9001@appendixsubsec commit options 9002 9003These standard options are supported by @code{commit} 9004(@pxref{Common options}, for a complete description of 9005them): 9006 9007@table @code 9008@item -l 9009Local; run only in current working directory. 9010 9011@item -R 9012Commit directories recursively. This is on by default. 9013 9014@item -r @var{revision} 9015Commit to @var{revision}. @var{revision} must be 9016either a branch, or a revision on the main trunk that 9017is higher than any existing revision number 9018(@pxref{Assigning revisions}). You 9019cannot commit to a specific revision on a branch. 9020@c FIXME: Need xref for branch case. 9021@end table 9022 9023@code{commit} also supports these options: 9024 9025@table @code 9026@item -F @var{file} 9027Read the log message from @var{file}, instead 9028of invoking an editor. 9029 9030@item -f 9031Note that this is not the standard behavior of 9032the @samp{-f} option as defined in @ref{Common options}. 9033 9034Force @sc{cvs} to commit a new revision even if you haven't 9035made any changes to the file. If the current revision 9036of @var{file} is 1.7, then the following two commands 9037are equivalent: 9038 9039@example 9040$ cvs commit -f @var{file} 9041$ cvs commit -r 1.8 @var{file} 9042@end example 9043 9044@c This is odd, but it's how CVS has worked for some 9045@c time. 9046The @samp{-f} option disables recursion (i.e., it 9047implies @samp{-l}). To force @sc{cvs} to commit a new 9048revision for all files in all subdirectories, you must 9049use @samp{-f -R}. 9050 9051@item -m @var{message} 9052Use @var{message} as the log message, instead of 9053invoking an editor. 9054@end table 9055 9056@need 2000 9057@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9058@node commit examples 9059@appendixsubsec commit examples 9060 9061@c FIXME: this material wants to be somewhere 9062@c in "Branching and merging". 9063 9064@appendixsubsubsec Committing to a branch 9065 9066You can commit to a branch revision (one that has an 9067even number of dots) with the @samp{-r} option. To 9068create a branch revision, use the @samp{-b} option 9069of the @code{rtag} or @code{tag} commands 9070(@pxref{Branching and merging}). Then, either @code{checkout} or 9071@code{update} can be used to base your sources on the 9072newly created branch. From that point on, all 9073@code{commit} changes made within these working sources 9074will be automatically added to a branch revision, 9075thereby not disturbing main-line development in any 9076way. For example, if you had to create a patch to the 90771.2 version of the product, even though the 2.0 version 9078is already under development, you might do: 9079 9080@example 9081$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module 9082$ cvs checkout -r FCS1_2_Patch product_module 9083$ cd product_module 9084[[ hack away ]] 9085$ cvs commit 9086@end example 9087 9088@noindent 9089This works automatically since the @samp{-r} option is 9090sticky. 9091 9092@appendixsubsubsec Creating the branch after editing 9093 9094Say you have been working on some extremely 9095experimental software, based on whatever revision you 9096happened to checkout last week. If others in your 9097group would like to work on this software with you, but 9098without disturbing main-line development, you could 9099commit your change to a new branch. Others can then 9100checkout your experimental stuff and utilize the full 9101benefit of @sc{cvs} conflict resolution. The scenario might 9102look like: 9103 9104@c FIXME: Should we be recommending tagging the branchpoint? 9105@example 9106[[ hacked sources are present ]] 9107$ cvs tag -b EXPR1 9108$ cvs update -r EXPR1 9109$ cvs commit 9110@end example 9111 9112The @code{update} command will make the @samp{-r 9113EXPR1} option sticky on all files. Note that your 9114changes to the files will never be removed by the 9115@code{update} command. The @code{commit} will 9116automatically commit to the correct branch, because the 9117@samp{-r} is sticky. You could also do like this: 9118 9119@c FIXME: Should we be recommending tagging the branchpoint? 9120@example 9121[[ hacked sources are present ]] 9122$ cvs tag -b EXPR1 9123$ cvs commit -r EXPR1 9124@end example 9125 9126@noindent 9127but then, only those files that were changed by you 9128will have the @samp{-r EXPR1} sticky flag. If you hack 9129away, and commit without specifying the @samp{-r EXPR1} 9130flag, some files may accidentally end up on the main 9131trunk. 9132 9133To work with you on the experimental change, others 9134would simply do 9135 9136@example 9137$ cvs checkout -r EXPR1 whatever_module 9138@end example 9139 9140@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9141@node diff 9142@appendixsec diff---Show differences between revisions 9143@cindex diff (subcommand) 9144 9145@itemize @bullet 9146@item 9147Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}] 9148@item 9149Requires: working directory, repository. 9150@item 9151Changes: nothing. 9152@end itemize 9153 9154The @code{diff} command is used to compare different 9155revisions of files. The default action is to compare 9156your working files with the revisions they were based 9157on, and report any differences that are found. 9158 9159If any file names are given, only those files are 9160compared. If any directories are given, all files 9161under them will be compared. 9162 9163The exit status for diff is different than for other 9164@sc{cvs} commands; for details @ref{Exit status}. 9165 9166@menu 9167* diff options:: diff options 9168* diff examples:: diff examples 9169@end menu 9170 9171@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9172@node diff options 9173@appendixsubsec diff options 9174 9175These standard options are supported by @code{diff} 9176(@pxref{Common options}, for a complete description of 9177them): 9178 9179@table @code 9180@item -D @var{date} 9181Use the most recent revision no later than @var{date}. 9182See @samp{-r} for how this affects the comparison. 9183 9184@item -k @var{kflag} 9185Process keywords according to @var{kflag}. See 9186@ref{Keyword substitution}. 9187 9188@item -l 9189Local; run only in current working directory. 9190 9191@item -R 9192Examine directories recursively. This option is on by 9193default. 9194 9195@item -r @var{tag} 9196Compare with revision @var{tag}. Zero, one or two 9197@samp{-r} options can be present. With no @samp{-r} 9198option, the working file will be compared with the 9199revision it was based on. With one @samp{-r}, that 9200revision will be compared to your current working file. 9201With two @samp{-r} options those two revisions will be 9202compared (and your working file will not affect the 9203outcome in any way). 9204@c We should be a lot more explicit, with examples, 9205@c about the difference between "cvs diff" and "cvs 9206@c diff -r HEAD". This often confuses new users. 9207 9208One or both @samp{-r} options can be replaced by a 9209@samp{-D @var{date}} option, described above. 9210@end table 9211 9212@c Conceptually, this is a disaster. There are 3 9213@c zillion diff formats that we support via the diff 9214@c library. It is not obvious to me that we should 9215@c document them all. Maybe just the most common ones 9216@c like -c and -u, and think about phasing out the 9217@c obscure ones. 9218@c FIXCVS: also should be a way to specify an external 9219@c diff program (which can be different for different 9220@c file types) and pass through 9221@c arbitrary options, so that the user can do 9222@c "--pass=-Z --pass=foo" or something even if CVS 9223@c doesn't know about the "-Z foo" option to diff. 9224@c This would fit nicely with deprecating/eliminating 9225@c the obscure options of the diff library, because it 9226@c would let people specify an external GNU diff if 9227@c they are into that sort of thing. 9228The following options specify the format of the 9229output. They have the same meaning as in GNU diff. 9230Most options have two equivalent names, one of which is a single letter 9231preceded by @samp{-}, and the other of which is a long name preceded by 9232@samp{--}. 9233 9234@table @samp 9235@item -@var{lines} 9236Show @var{lines} (an integer) lines of context. This option does not 9237specify an output format by itself; it has no effect unless it is 9238combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper 9239operation, @code{patch} typically needs at least two lines of context. 9240 9241@item -a 9242Treat all files as text and compare them line-by-line, even if they 9243do not seem to be text. 9244 9245@item -b 9246Ignore trailing white space and consider all other sequences of one or 9247more white space characters to be equivalent. 9248 9249@item -B 9250Ignore changes that just insert or delete blank lines. 9251 9252@item --binary 9253Read and write data in binary mode. 9254 9255@item --brief 9256Report only whether the files differ, not the details of the 9257differences. 9258 9259@item -c 9260Use the context output format. 9261 9262@item -C @var{lines} 9263@itemx --context@r{[}=@var{lines}@r{]} 9264Use the context output format, showing @var{lines} (an integer) lines of 9265context, or three if @var{lines} is not given. 9266For proper operation, @code{patch} typically needs at least two lines of 9267context. 9268 9269@item --changed-group-format=@var{format} 9270Use @var{format} to output a line group containing differing lines from 9271both files in if-then-else format. @xref{Line group formats}. 9272 9273@item -d 9274Change the algorithm to perhaps find a smaller set of changes. This makes 9275@code{diff} slower (sometimes much slower). 9276 9277@item -e 9278@itemx --ed 9279Make output that is a valid @code{ed} script. 9280 9281@item --expand-tabs 9282Expand tabs to spaces in the output, to preserve the alignment of tabs 9283in the input files. 9284 9285@item -f 9286Make output that looks vaguely like an @code{ed} script but has changes 9287in the order they appear in the file. 9288 9289@item -F @var{regexp} 9290In context and unified format, for each hunk of differences, show some 9291of the last preceding line that matches @var{regexp}. 9292 9293@item --forward-ed 9294Make output that looks vaguely like an @code{ed} script but has changes 9295in the order they appear in the file. 9296 9297@item -H 9298Use heuristics to speed handling of large files that have numerous 9299scattered small changes. 9300 9301@item --horizon-lines=@var{lines} 9302Do not discard the last @var{lines} lines of the common prefix 9303and the first @var{lines} lines of the common suffix. 9304 9305@item -i 9306Ignore changes in case; consider upper- and lower-case letters 9307equivalent. 9308 9309@item -I @var{regexp} 9310Ignore changes that just insert or delete lines that match @var{regexp}. 9311 9312@item --ifdef=@var{name} 9313Make merged if-then-else output using @var{name}. 9314 9315@item --ignore-all-space 9316Ignore white space when comparing lines. 9317 9318@item --ignore-blank-lines 9319Ignore changes that just insert or delete blank lines. 9320 9321@item --ignore-case 9322Ignore changes in case; consider upper- and lower-case to be the same. 9323 9324@item --ignore-matching-lines=@var{regexp} 9325Ignore changes that just insert or delete lines that match @var{regexp}. 9326 9327@item --ignore-space-change 9328Ignore trailing white space and consider all other sequences of one or 9329more white space characters to be equivalent. 9330 9331@item --initial-tab 9332Output a tab rather than a space before the text of a line in normal or 9333context format. This causes the alignment of tabs in the line to look 9334normal. 9335 9336@item -L @var{label} 9337Use @var{label} instead of the file name in the context format 9338and unified format headers. 9339 9340@item --label=@var{label} 9341Use @var{label} instead of the file name in the context format 9342and unified format headers. 9343 9344@item --left-column 9345Print only the left column of two common lines in side by side format. 9346 9347@item --line-format=@var{format} 9348Use @var{format} to output all input lines in if-then-else format. 9349@xref{Line formats}. 9350 9351@item --minimal 9352Change the algorithm to perhaps find a smaller set of changes. This 9353makes @code{diff} slower (sometimes much slower). 9354 9355@item -n 9356Output RCS-format diffs; like @samp{-f} except that each command 9357specifies the number of lines affected. 9358 9359@item -N 9360@itemx --new-file 9361In directory comparison, if a file is found in only one directory, 9362treat it as present but empty in the other directory. 9363 9364@item --new-group-format=@var{format} 9365Use @var{format} to output a group of lines taken from just the second 9366file in if-then-else format. @xref{Line group formats}. 9367 9368@item --new-line-format=@var{format} 9369Use @var{format} to output a line taken from just the second file in 9370if-then-else format. @xref{Line formats}. 9371 9372@item --old-group-format=@var{format} 9373Use @var{format} to output a group of lines taken from just the first 9374file in if-then-else format. @xref{Line group formats}. 9375 9376@item --old-line-format=@var{format} 9377Use @var{format} to output a line taken from just the first file in 9378if-then-else format. @xref{Line formats}. 9379 9380@item -p 9381Show which C function each change is in. 9382 9383@item --rcs 9384Output RCS-format diffs; like @samp{-f} except that each command 9385specifies the number of lines affected. 9386 9387@item --report-identical-files 9388@itemx -s 9389Report when two files are the same. 9390 9391@item --show-c-function 9392Show which C function each change is in. 9393 9394@item --show-function-line=@var{regexp} 9395In context and unified format, for each hunk of differences, show some 9396of the last preceding line that matches @var{regexp}. 9397 9398@item --side-by-side 9399Use the side by side output format. 9400 9401@item --speed-large-files 9402Use heuristics to speed handling of large files that have numerous 9403scattered small changes. 9404 9405@item --suppress-common-lines 9406Do not print common lines in side by side format. 9407 9408@item -t 9409Expand tabs to spaces in the output, to preserve the alignment of tabs 9410in the input files. 9411 9412@item -T 9413Output a tab rather than a space before the text of a line in normal or 9414context format. This causes the alignment of tabs in the line to look 9415normal. 9416 9417@item --text 9418Treat all files as text and compare them line-by-line, even if they 9419do not appear to be text. 9420 9421@item -u 9422Use the unified output format. 9423 9424@item --unchanged-group-format=@var{format} 9425Use @var{format} to output a group of common lines taken from both files 9426in if-then-else format. @xref{Line group formats}. 9427 9428@item --unchanged-line-format=@var{format} 9429Use @var{format} to output a line common to both files in if-then-else 9430format. @xref{Line formats}. 9431 9432@item -U @var{lines} 9433@itemx --unified@r{[}=@var{lines}@r{]} 9434Use the unified output format, showing @var{lines} (an integer) lines of 9435context, or three if @var{lines} is not given. 9436For proper operation, @code{patch} typically needs at least two lines of 9437context. 9438 9439@item -w 9440Ignore white space when comparing lines. 9441 9442@item -W @var{columns} 9443@itemx --width=@var{columns} 9444Use an output width of @var{columns} in side by side format. 9445 9446@item -y 9447Use the side by side output format. 9448@end table 9449 9450@menu 9451* Line group formats:: Line group formats 9452* Line formats:: Line formats 9453@end menu 9454 9455@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9456@node Line group formats 9457@appendixsubsubsec Line group formats 9458 9459Line group formats let you specify formats suitable for many 9460applications that allow if-then-else input, including programming 9461languages and text formatting languages. A line group format specifies 9462the output format for a contiguous group of similar lines. 9463 9464For example, the following command compares the TeX file @file{myfile} 9465with the original version from the repository, 9466and outputs a merged file in which old regions are 9467surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new 9468regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines. 9469 9470@example 9471cvs diff \ 9472 --old-group-format='\begin@{em@} 9473%<\end@{em@} 9474' \ 9475 --new-group-format='\begin@{bf@} 9476%>\end@{bf@} 9477' \ 9478 myfile 9479@end example 9480 9481The following command is equivalent to the above example, but it is a 9482little more verbose, because it spells out the default line group formats. 9483 9484@example 9485cvs diff \ 9486 --old-group-format='\begin@{em@} 9487%<\end@{em@} 9488' \ 9489 --new-group-format='\begin@{bf@} 9490%>\end@{bf@} 9491' \ 9492 --unchanged-group-format='%=' \ 9493 --changed-group-format='\begin@{em@} 9494%<\end@{em@} 9495\begin@{bf@} 9496%>\end@{bf@} 9497' \ 9498 myfile 9499@end example 9500 9501Here is a more advanced example, which outputs a diff listing with 9502headers containing line numbers in a ``plain English'' style. 9503 9504@example 9505cvs diff \ 9506 --unchanged-group-format='' \ 9507 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: 9508%<' \ 9509 --new-group-format='-------- %dN line%(N=1?:s) added after %de: 9510%>' \ 9511 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: 9512%<-------- to: 9513%>' \ 9514 myfile 9515@end example 9516 9517To specify a line group format, use one of the options 9518listed below. You can specify up to four line group formats, one for 9519each kind of line group. You should quote @var{format}, because it 9520typically contains shell metacharacters. 9521 9522@table @samp 9523@item --old-group-format=@var{format} 9524These line groups are hunks containing only lines from the first file. 9525The default old group format is the same as the changed group format if 9526it is specified; otherwise it is a format that outputs the line group as-is. 9527 9528@item --new-group-format=@var{format} 9529These line groups are hunks containing only lines from the second 9530file. The default new group format is same as the changed group 9531format if it is specified; otherwise it is a format that outputs the 9532line group as-is. 9533 9534@item --changed-group-format=@var{format} 9535These line groups are hunks containing lines from both files. The 9536default changed group format is the concatenation of the old and new 9537group formats. 9538 9539@item --unchanged-group-format=@var{format} 9540These line groups contain lines common to both files. The default 9541unchanged group format is a format that outputs the line group as-is. 9542@end table 9543 9544In a line group format, ordinary characters represent themselves; 9545conversion specifications start with @samp{%} and have one of the 9546following forms. 9547 9548@table @samp 9549@item %< 9550stands for the lines from the first file, including the trailing newline. 9551Each line is formatted according to the old line format (@pxref{Line formats}). 9552 9553@item %> 9554stands for the lines from the second file, including the trailing newline. 9555Each line is formatted according to the new line format. 9556 9557@item %= 9558stands for the lines common to both files, including the trailing newline. 9559Each line is formatted according to the unchanged line format. 9560 9561@item %% 9562stands for @samp{%}. 9563 9564@item %c'@var{C}' 9565where @var{C} is a single character, stands for @var{C}. 9566@var{C} may not be a backslash or an apostrophe. 9567For example, @samp{%c':'} stands for a colon, even inside 9568the then-part of an if-then-else format, which a colon would 9569normally terminate. 9570 9571@item %c'\@var{O}' 9572where @var{O} is a string of 1, 2, or 3 octal digits, 9573stands for the character with octal code @var{O}. 9574For example, @samp{%c'\0'} stands for a null character. 9575 9576@item @var{F}@var{n} 9577where @var{F} is a @code{printf} conversion specification and @var{n} is one 9578of the following letters, stands for @var{n}'s value formatted with @var{F}. 9579 9580@table @samp 9581@item e 9582The line number of the line just before the group in the old file. 9583 9584@item f 9585The line number of the first line in the group in the old file; 9586equals @var{e} + 1. 9587 9588@item l 9589The line number of the last line in the group in the old file. 9590 9591@item m 9592The line number of the line just after the group in the old file; 9593equals @var{l} + 1. 9594 9595@item n 9596The number of lines in the group in the old file; equals @var{l} - @var{f} + 1. 9597 9598@item E, F, L, M, N 9599Likewise, for lines in the new file. 9600 9601@end table 9602 9603The @code{printf} conversion specification can be @samp{%d}, 9604@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal, 9605lower case hexadecimal, or upper case hexadecimal output 9606respectively. After the @samp{%} the following options can appear in 9607sequence: a @samp{-} specifying left-justification; an integer 9608specifying the minimum field width; and a period followed by an 9609optional integer specifying the minimum number of digits. 9610For example, @samp{%5dN} prints the number of new lines in the group 9611in a field of width 5 characters, using the @code{printf} format @code{"%5d"}. 9612 9613@item (@var{A}=@var{B}?@var{T}:@var{E}) 9614If @var{A} equals @var{B} then @var{T} else @var{E}. 9615@var{A} and @var{B} are each either a decimal constant 9616or a single letter interpreted as above. 9617This format spec is equivalent to @var{T} if 9618@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}. 9619 9620For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to 9621@samp{no lines} if @var{N} (the number of lines in the group in the 9622new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines} 9623otherwise. 9624@end table 9625 9626@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9627@node Line formats 9628@appendixsubsubsec Line formats 9629 9630Line formats control how each line taken from an input file is 9631output as part of a line group in if-then-else format. 9632 9633For example, the following command outputs text with a one-column 9634change indicator to the left of the text. The first column of output 9635is @samp{-} for deleted lines, @samp{|} for added lines, and a space 9636for unchanged lines. The formats contain newline characters where 9637newlines are desired on output. 9638 9639@example 9640cvs diff \ 9641 --old-line-format='-%l 9642' \ 9643 --new-line-format='|%l 9644' \ 9645 --unchanged-line-format=' %l 9646' \ 9647 myfile 9648@end example 9649 9650To specify a line format, use one of the following options. You should 9651quote @var{format}, since it often contains shell metacharacters. 9652 9653@table @samp 9654@item --old-line-format=@var{format} 9655formats lines just from the first file. 9656 9657@item --new-line-format=@var{format} 9658formats lines just from the second file. 9659 9660@item --unchanged-line-format=@var{format} 9661formats lines common to both files. 9662 9663@item --line-format=@var{format} 9664formats all lines; in effect, it sets all three above options simultaneously. 9665@end table 9666 9667In a line format, ordinary characters represent themselves; 9668conversion specifications start with @samp{%} and have one of the 9669following forms. 9670 9671@table @samp 9672@item %l 9673stands for the contents of the line, not counting its trailing 9674newline (if any). This format ignores whether the line is incomplete. 9675 9676@item %L 9677stands for the contents of the line, including its trailing newline 9678(if any). If a line is incomplete, this format preserves its 9679incompleteness. 9680 9681@item %% 9682stands for @samp{%}. 9683 9684@item %c'@var{C}' 9685where @var{C} is a single character, stands for @var{C}. 9686@var{C} may not be a backslash or an apostrophe. 9687For example, @samp{%c':'} stands for a colon. 9688 9689@item %c'\@var{O}' 9690where @var{O} is a string of 1, 2, or 3 octal digits, 9691stands for the character with octal code @var{O}. 9692For example, @samp{%c'\0'} stands for a null character. 9693 9694@item @var{F}n 9695where @var{F} is a @code{printf} conversion specification, 9696stands for the line number formatted with @var{F}. 9697For example, @samp{%.5dn} prints the line number using the 9698@code{printf} format @code{"%.5d"}. @xref{Line group formats}, for 9699more about printf conversion specifications. 9700 9701@end table 9702 9703The default line format is @samp{%l} followed by a newline character. 9704 9705If the input contains tab characters and it is important that they line 9706up on output, you should ensure that @samp{%l} or @samp{%L} in a line 9707format is just after a tab stop (e.g.@: by preceding @samp{%l} or 9708@samp{%L} with a tab character), or you should use the @samp{-t} or 9709@samp{--expand-tabs} option. 9710 9711Taken together, the line and line group formats let you specify many 9712different formats. For example, the following command uses a format 9713similar to @code{diff}'s normal format. You can tailor this command 9714to get fine control over @code{diff}'s output. 9715 9716@example 9717cvs diff \ 9718 --old-line-format='< %l 9719' \ 9720 --new-line-format='> %l 9721' \ 9722 --old-group-format='%df%(f=l?:,%dl)d%dE 9723%<' \ 9724 --new-group-format='%dea%dF%(F=L?:,%dL) 9725%>' \ 9726 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) 9727%<--- 9728%>' \ 9729 --unchanged-group-format='' \ 9730 myfile 9731@end example 9732 9733@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9734@node diff examples 9735@appendixsubsec diff examples 9736 9737The following line produces a Unidiff (@samp{-u} flag) 9738between revision 1.14 and 1.19 of 9739@file{backend.c}. Due to the @samp{-kk} flag no 9740keywords are substituted, so differences that only depend 9741on keyword substitution are ignored. 9742 9743@example 9744$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c 9745@end example 9746 9747Suppose the experimental branch EXPR1 was based on a 9748set of files tagged RELEASE_1_0. To see what has 9749happened on that branch, the following can be used: 9750 9751@example 9752$ cvs diff -r RELEASE_1_0 -r EXPR1 9753@end example 9754 9755A command like this can be used to produce a context 9756diff between two releases: 9757 9758@example 9759$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs 9760@end example 9761 9762If you are maintaining ChangeLogs, a command like the following 9763just before you commit your changes may help you write 9764the ChangeLog entry. All local modifications that have 9765not yet been committed will be printed. 9766 9767@example 9768$ cvs diff -u | less 9769@end example 9770 9771@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9772@node export 9773@appendixsec export---Export sources from CVS, similar to checkout 9774@cindex export (subcommand) 9775 9776@itemize @bullet 9777@item 9778Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{} 9779@item 9780Requires: repository. 9781@item 9782Changes: current directory. 9783@end itemize 9784 9785This command is a variant of @code{checkout}; use it 9786when you want a copy of the source for module without 9787the @sc{cvs} administrative directories. For example, you 9788might use @code{export} to prepare source for shipment 9789off-site. This command requires that you specify a 9790date or tag (with @samp{-D} or @samp{-r}), so that you 9791can count on reproducing the source you ship to others 9792(and thus it always prunes empty directories). 9793 9794One often would like to use @samp{-kv} with @code{cvs 9795export}. This causes any keywords to be 9796expanded such that an import done at some other site 9797will not lose the keyword revision information. But be 9798aware that doesn't handle an export containing binary 9799files correctly. Also be aware that after having used 9800@samp{-kv}, one can no longer use the @code{ident} 9801command (which is part of the @sc{rcs} suite---see 9802ident(1)) which looks for keyword strings. If 9803you want to be able to use @code{ident} you must not 9804use @samp{-kv}. 9805 9806@menu 9807* export options:: export options 9808@end menu 9809 9810@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9811@node export options 9812@appendixsubsec export options 9813 9814These standard options are supported by @code{export} 9815(@pxref{Common options}, for a complete description of 9816them): 9817 9818@table @code 9819@item -D @var{date} 9820Use the most recent revision no later than @var{date}. 9821 9822@item -f 9823If no matching revision is found, retrieve the most 9824recent revision (instead of ignoring the file). 9825 9826@item -l 9827Local; run only in current working directory. 9828 9829@item -n 9830Do not run any checkout program. 9831 9832@item -R 9833Export directories recursively. This is on by default. 9834 9835@item -r @var{tag} 9836Use revision @var{tag}. 9837@end table 9838 9839In addition, these options (that are common to 9840@code{checkout} and @code{export}) are also supported: 9841 9842@table @code 9843@item -d @var{dir} 9844Create a directory called @var{dir} for the working 9845files, instead of using the module name. 9846@xref{checkout options}, for complete details on how 9847@sc{cvs} handles this flag. 9848 9849@item -k @var{subst} 9850Set keyword expansion mode (@pxref{Substitution modes}). 9851 9852@item -N 9853Only useful together with @samp{-d @var{dir}}. 9854@xref{checkout options}, for complete details on how 9855@sc{cvs} handles this flag. 9856@end table 9857 9858 9859@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 9860@node history 9861@appendixsec history---Show status of files and users 9862@cindex history (subcommand) 9863 9864@itemize @bullet 9865@item 9866Synopsis: history [-report] [-flags] [-options args] [files@dots{}] 9867@item 9868Requires: the file @file{$CVSROOT/CVSROOT/history} 9869@item 9870Changes: nothing. 9871@end itemize 9872 9873@sc{cvs} can keep a history file that tracks each use of the 9874@code{checkout}, @code{commit}, @code{rtag}, 9875@code{update}, and @code{release} commands. You can 9876use @code{history} to display this information in 9877various formats. 9878 9879Logging must be enabled by creating the file 9880@file{$CVSROOT/CVSROOT/history}. 9881 9882@strong{Note: @code{history} uses @samp{-f}, @samp{-l}, 9883@samp{-n}, and @samp{-p} in ways that conflict with the 9884normal use inside @sc{cvs} (@pxref{Common options}).} 9885 9886@menu 9887* history options:: history options 9888@end menu 9889 9890@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9891@node history options 9892@appendixsubsec history options 9893 9894Several options (shown above as @samp{-report}) control what 9895kind of report is generated: 9896 9897@table @code 9898@item -c 9899Report on each time commit was used (i.e., each time 9900the repository was modified). 9901 9902@item -e 9903Everything (all record types). Equivalent to 9904specifying @samp{-x} with all record types. Of course, 9905@samp{-e} will also include record types which are 9906added in a future version of @sc{cvs}; if you are 9907writing a script which can only handle certain record 9908types, you'll want to specify @samp{-x}. 9909 9910@item -m @var{module} 9911Report on a particular module. (You can meaningfully 9912use @samp{-m} more than once on the command line.) 9913 9914@item -o 9915Report on checked-out modules. This is the default report type. 9916 9917@item -T 9918Report on all tags. 9919 9920@item -x @var{type} 9921Extract a particular set of record types @var{type} from the @sc{cvs} 9922history. The types are indicated by single letters, 9923which you may specify in combination. 9924 9925Certain commands have a single record type: 9926 9927@table @code 9928@item F 9929release 9930@item O 9931checkout 9932@item E 9933export 9934@item T 9935rtag 9936@end table 9937 9938@noindent 9939One of four record types may result from an update: 9940 9941@table @code 9942@item C 9943A merge was necessary but collisions were 9944detected (requiring manual merging). 9945@item G 9946A merge was necessary and it succeeded. 9947@item U 9948A working file was copied from the repository. 9949@item W 9950The working copy of a file was deleted during 9951update (because it was gone from the repository). 9952@end table 9953 9954@noindent 9955One of three record types results from commit: 9956 9957@table @code 9958@item A 9959A file was added for the first time. 9960@item M 9961A file was modified. 9962@item R 9963A file was removed. 9964@end table 9965@end table 9966 9967The options shown as @samp{-flags} constrain or expand 9968the report without requiring option arguments: 9969 9970@table @code 9971@item -a 9972Show data for all users (the default is to show data 9973only for the user executing @code{history}). 9974 9975@item -l 9976Show last modification only. 9977 9978@item -w 9979Show only the records for modifications done from the 9980same working directory where @code{history} is 9981executing. 9982@end table 9983 9984The options shown as @samp{-options @var{args}} constrain the report 9985based on an argument: 9986 9987@table @code 9988@item -b @var{str} 9989Show data back to a record containing the string 9990@var{str} in either the module name, the file name, or 9991the repository path. 9992 9993@item -D @var{date} 9994Show data since @var{date}. This is slightly different 9995from the normal use of @samp{-D @var{date}}, which 9996selects the newest revision older than @var{date}. 9997 9998@item -f @var{file} 9999Show data for a particular file 10000(you can specify several @samp{-f} options on the same command line). 10001This is equivalent to specifying the file on the command line. 10002 10003@item -n @var{module} 10004Show data for a particular module 10005(you can specify several @samp{-n} options on the same command line). 10006 10007@item -p @var{repository} 10008Show data for a particular source repository (you 10009can specify several @samp{-p} options on the same command 10010line). 10011 10012@item -r @var{rev} 10013Show records referring to revisions since the revision 10014or tag named @var{rev} appears in individual @sc{rcs} 10015files. Each @sc{rcs} file is searched for the revision or 10016tag. 10017 10018@item -t @var{tag} 10019Show records since tag @var{tag} was last added to the 10020history file. This differs from the @samp{-r} flag 10021above in that it reads only the history file, not the 10022@sc{rcs} files, and is much faster. 10023 10024@item -u @var{name} 10025Show records for user @var{name}. 10026 10027@item -z @var{timezone} 10028Show times in the selected records using the specified 10029time zone instead of UTC. 10030@end table 10031 10032 10033@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10034@node import 10035@appendixsec import---Import sources into CVS, using vendor branches 10036@cindex import (subcommand) 10037 10038@c FIXME: This node is way too long for one which has subnodes. 10039 10040@itemize @bullet 10041@item 10042Synopsis: import [-options] repository vendortag releasetag@dots{} 10043@item 10044Requires: Repository, source distribution directory. 10045@item 10046Changes: repository. 10047@end itemize 10048 10049Use @code{import} to incorporate an entire source 10050distribution from an outside source (e.g., a source 10051vendor) into your source repository directory. You can 10052use this command both for initial creation of a 10053repository, and for wholesale updates to the module 10054from the outside source. @xref{Tracking sources}, for 10055a discussion on this subject. 10056 10057The @var{repository} argument gives a directory name 10058(or a path to a directory) under the @sc{cvs} root directory 10059for repositories; if the directory did not exist, 10060import creates it. 10061 10062When you use import for updates to source that has been 10063modified in your source repository (since a prior 10064import), it will notify you of any files that conflict 10065in the two branches of development; use @samp{checkout 10066-j} to reconcile the differences, as import instructs 10067you to do. 10068 10069If @sc{cvs} decides a file should be ignored 10070(@pxref{cvsignore}), it does not import it and prints 10071@samp{I } followed by the filename (@pxref{import output}, for a 10072complete description of the output). 10073 10074If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, 10075any file whose names match the specifications in that 10076file will be treated as packages and the appropriate 10077filtering will be performed on the file/directory 10078before being imported. @xref{Wrappers}. 10079 10080The outside source is saved in a first-level 10081branch, by default 1.1.1. Updates are leaves of this 10082branch; for example, files from the first imported 10083collection of source will be revision 1.1.1.1, then 10084files from the first imported update will be revision 100851.1.1.2, and so on. 10086 10087At least three arguments are required. 10088@var{repository} is needed to identify the collection 10089of source. @var{vendortag} is a tag for the entire 10090branch (e.g., for 1.1.1). You must also specify at 10091least one @var{releasetag} to identify the files at 10092the leaves created each time you execute @code{import}. 10093 10094@c I'm not completely sure this belongs here. But 10095@c we need to say it _somewhere_ reasonably obvious; it 10096@c is a common misconception among people first learning CVS 10097Note that @code{import} does @emph{not} change the 10098directory in which you invoke it. In particular, it 10099does not set up that directory as a @sc{cvs} working 10100directory; if you want to work with the sources import 10101them first and then check them out into a different 10102directory (@pxref{Getting the source}). 10103 10104@menu 10105* import options:: import options 10106* import output:: import output 10107* import examples:: import examples 10108@end menu 10109 10110@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10111@node import options 10112@appendixsubsec import options 10113 10114This standard option is supported by @code{import} 10115(@pxref{Common options}, for a complete description): 10116 10117@table @code 10118@item -m @var{message} 10119Use @var{message} as log information, instead of 10120invoking an editor. 10121@end table 10122 10123There are the following additional special options. 10124 10125@table @code 10126@item -b @var{branch} 10127See @ref{Multiple vendor branches}. 10128 10129@item -k @var{subst} 10130Indicate the keyword expansion mode desired. This 10131setting will apply to all files created during the 10132import, but not to any files that previously existed in 10133the repository. See @ref{Substitution modes}, for a 10134list of valid @samp{-k} settings. 10135 10136@item -I @var{name} 10137Specify file names that should be ignored during 10138import. You can use this option repeatedly. To avoid 10139ignoring any files at all (even those ignored by 10140default), specify `-I !'. 10141 10142@var{name} can be a file name pattern of the same type 10143that you can specify in the @file{.cvsignore} file. 10144@xref{cvsignore}. 10145@c -- Is this really true? 10146 10147@item -W @var{spec} 10148Specify file names that should be filtered during 10149import. You can use this option repeatedly. 10150 10151@var{spec} can be a file name pattern of the same type 10152that you can specify in the @file{.cvswrappers} 10153file. @xref{Wrappers}. 10154@end table 10155 10156@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10157@node import output 10158@appendixsubsec import output 10159 10160@code{import} keeps you informed of its progress by printing a line 10161for each file, preceded by one character indicating the status of the file: 10162 10163@table @code 10164@item U @var{file} 10165The file already exists in the repository and has not been locally 10166modified; a new revision has been created (if necessary). 10167 10168@item N @var{file} 10169The file is a new file which has been added to the repository. 10170 10171@item C @var{file} 10172The file already exists in the repository but has been locally modified; 10173you will have to merge the changes. 10174 10175@item I @var{file} 10176The file is being ignored (@pxref{cvsignore}). 10177 10178@cindex Symbolic link, importing 10179@cindex Link, symbolic, importing 10180@c FIXME: also (somewhere else) probably 10181@c should be documenting what happens if you "cvs add" 10182@c a symbolic link. Also maybe what happens if 10183@c you manually create symbolic links within the 10184@c repository (? - not sure why we'd want to suggest 10185@c doing that). 10186@item L @var{file} 10187The file is a symbolic link; @code{cvs import} ignores symbolic links. 10188People periodically suggest that this behavior should 10189be changed, but if there is a consensus on what it 10190should be changed to, it is not apparent. 10191(Various options in the @file{modules} file can be used 10192to recreate symbolic links on checkout, update, etc.; 10193@pxref{modules}.) 10194@end table 10195 10196@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10197@node import examples 10198@appendixsubsec import examples 10199 10200See @ref{Tracking sources}, and @ref{From files}. 10201 10202@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10203@node log 10204@appendixsec log---Print out log information for files 10205@cindex log (subcommand) 10206 10207@itemize @bullet 10208@item 10209Synopsis: log [options] [files@dots{}] 10210@item 10211Requires: repository, working directory. 10212@item 10213Changes: nothing. 10214@end itemize 10215 10216Display log information for files. @code{log} used to 10217call the @sc{rcs} utility @code{rlog}. Although this 10218is no longer true in the current sources, this history 10219determines the format of the output and the options, 10220which are not quite in the style of the other @sc{cvs} 10221commands. 10222 10223@cindex Timezone, in output 10224@cindex Zone, time, in output 10225@c Kind of a funny place to document the timezone used 10226@c in output from commands other than @code{log}. 10227@c There is also more we need to say about this, 10228@c including what happens in a client/server environment. 10229The output includes the location of the @sc{rcs} file, 10230the @dfn{head} revision (the latest revision on the 10231trunk), all symbolic names (tags) and some other 10232things. For each revision, the revision number, the 10233author, the number of lines added/deleted and the log 10234message are printed. All times are displayed in 10235Coordinated Universal Time (UTC). (Other parts of 10236@sc{cvs} print times in the local timezone). 10237@c FIXCVS: need a better way to control the timezone 10238@c used in output. Previous/current versions of CVS did/do 10239@c sometimes support -z in RCSINIT, and/or an 10240@c undocumented (except by reference to 'rlog') -z option 10241@c to cvs log, but this has not been a consistent, 10242@c documented feature. Perhaps a new global option, 10243@c where LT means the client's timezone, which the 10244@c client then communicates to the server, is the 10245@c right solution. 10246 10247@strong{Note: @code{log} uses @samp{-R} in a way that conflicts 10248with the normal use inside @sc{cvs} (@pxref{Common options}).} 10249 10250@menu 10251* log options:: log options 10252* log examples:: log examples 10253@end menu 10254 10255@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10256@node log options 10257@appendixsubsec log options 10258 10259By default, @code{log} prints all information that is 10260available. All other options restrict the output. 10261 10262@table @code 10263@item -b 10264Print information about the revisions on the default 10265branch, normally the highest branch on the trunk. 10266 10267@item -d @var{dates} 10268Print information about revisions with a checkin 10269date/time in the range given by the 10270semicolon-separated list of dates. The date formats 10271accepted are those accepted by the @samp{-D} option to 10272many other @sc{cvs} commands (@pxref{Common options}). 10273Dates can be combined into ranges as follows: 10274 10275@c Should we be thinking about accepting ISO8601 10276@c ranges? For example "1972-09-10/1972-09-12". 10277@table @code 10278@item @var{d1}<@var{d2} 10279@itemx @var{d2}>@var{d1} 10280Select the revisions that were deposited between 10281@var{d1} and @var{d2}. 10282 10283@item <@var{d} 10284@itemx @var{d}> 10285Select all revisions dated @var{d} or earlier. 10286 10287@item @var{d}< 10288@itemx >@var{d} 10289Select all revisions dated @var{d} or later. 10290 10291@item @var{d} 10292Select the single, latest revision dated @var{d} or 10293earlier. 10294@end table 10295 10296The @samp{>} or @samp{<} characters may be followed by 10297@samp{=} to indicate an inclusive range rather than an 10298exclusive one. 10299 10300Note that the separator is a semicolon (;). 10301 10302@item -h 10303Print only the name of the @sc{rcs} file, name 10304of the file in the working directory, head, 10305default branch, access list, locks, symbolic names, and 10306suffix. 10307 10308@item -l 10309Local; run only in current working directory. (Default 10310is to run recursively). 10311 10312@item -N 10313Do not print the list of tags for this file. This 10314option can be very useful when your site uses a lot of 10315tags, so rather than "more"'ing over 3 pages of tag 10316information, the log information is presented without 10317tags at all. 10318 10319@item -R 10320Print only the name of the @sc{rcs} file. 10321 10322@c Note that using a bare revision (in addition to not 10323@c being explicitly documented here) is potentially 10324@c confusing; it shows the log message to get from the 10325@c previous revision to that revision. "-r1.3 -r1.6" 10326@c (equivalent to "-r1.3,1.6") is even worse; it 10327@c prints the messages to get from 1.2 to 1.3 and 1.5 10328@c to 1.6. By analogy with "cvs diff", users might 10329@c expect that it is more like specifying a range. 10330@c It is not 100% clear to me how much of this should 10331@c be documented (for example, multiple -r options 10332@c perhaps could/should be deprecated given the false 10333@c analogy with "cvs diff"). 10334@c In general, this section should be rewritten to talk 10335@c about messages to get from revision rev1 to rev2, 10336@c rather than messages for revision rev2 (that is, the 10337@c messages are associated with a change not a static 10338@c revision and failing to make this distinction causes 10339@c much confusion). 10340@item -r@var{revisions} 10341Print information about revisions given in the 10342comma-separated list @var{revisions} of revisions and 10343ranges. The following table explains the available 10344range formats: 10345 10346@table @code 10347@item @var{rev1}:@var{rev2} 10348Revisions @var{rev1} to @var{rev2} (which must be on 10349the same branch). 10350 10351@item @var{rev1}::@var{rev2} 10352The same, but excluding @var{rev1}. 10353 10354@item :@var{rev} 10355@itemx ::@var{rev} 10356Revisions from the beginning of the branch up to 10357and including @var{rev}. 10358 10359@item @var{rev}: 10360Revisions starting with @var{rev} to the end of the 10361branch containing @var{rev}. 10362 10363@item @var{rev}:: 10364Revisions starting just after @var{rev} to the end of the 10365branch containing @var{rev}. 10366 10367@item @var{branch} 10368An argument that is a branch means all revisions on 10369that branch. 10370 10371@item @var{branch1}:@var{branch2} 10372@itemx @var{branch1}::@var{branch2} 10373A range of branches means all revisions 10374on the branches in that range. 10375 10376@item @var{branch}. 10377The latest revision in @var{branch}. 10378@end table 10379 10380A bare @samp{-r} with no revisions means the latest 10381revision on the default branch, normally the trunk. 10382There can be no space between the @samp{-r} option and 10383its argument. 10384 10385@item -S 10386Suppress the header if no revisions are selected. 10387 10388@item -s @var{states} 10389Print information about revisions whose state 10390attributes match one of the states given in the 10391comma-separated list @var{states}. 10392 10393@item -t 10394Print the same as @samp{-h}, plus the descriptive text. 10395 10396@item -w@var{logins} 10397Print information about revisions checked in by users 10398with login names appearing in the comma-separated list 10399@var{logins}. If @var{logins} is omitted, the user's 10400login is assumed. There can be no space between the 10401@samp{-w} option and its argument. 10402@end table 10403 10404@code{log} prints the intersection of the revisions 10405selected with the options @samp{-d}, @samp{-s}, and 10406@samp{-w}, intersected with the union of the revisions 10407selected by @samp{-b} and @samp{-r}. 10408 10409@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10410@node log examples 10411@appendixsubsec log examples 10412 10413Contributed examples are gratefully accepted. 10414 10415@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10416@node rdiff 10417@appendixsec rdiff---'patch' format diffs between releases 10418@cindex rdiff (subcommand) 10419 10420@itemize @bullet 10421@item 10422rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{} 10423@item 10424Requires: repository. 10425@item 10426Changes: nothing. 10427@item 10428Synonym: patch 10429@end itemize 10430 10431Builds a Larry Wall format patch(1) file between two 10432releases, that can be fed directly into the @code{patch} 10433program to bring an old release up-to-date with the new 10434release. (This is one of the few @sc{cvs} commands that 10435operates directly from the repository, and doesn't 10436require a prior checkout.) The diff output is sent to 10437the standard output device. 10438 10439You can specify (using the standard @samp{-r} and 10440@samp{-D} options) any combination of one or two 10441revisions or dates. If only one revision or date is 10442specified, the patch file reflects differences between 10443that revision or date and the current head revisions in 10444the @sc{rcs} file. 10445 10446Note that if the software release affected is contained 10447in more than one directory, then it may be necessary to 10448specify the @samp{-p} option to the @code{patch} command when 10449patching the old sources, so that @code{patch} is able to find 10450the files that are located in other directories. 10451 10452@menu 10453* rdiff options:: rdiff options 10454* rdiff examples:: rdiff examples 10455@end menu 10456 10457@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10458@node rdiff options 10459@appendixsubsec rdiff options 10460 10461These standard options are supported by @code{rdiff} 10462(@pxref{Common options}, for a complete description of 10463them): 10464 10465@table @code 10466@item -D @var{date} 10467Use the most recent revision no later than @var{date}. 10468 10469@item -f 10470If no matching revision is found, retrieve the most 10471recent revision (instead of ignoring the file). 10472 10473@item -l 10474Local; don't descend subdirectories. 10475 10476@item -R 10477Examine directories recursively. This option is on by default. 10478 10479@item -r @var{tag} 10480Use revision @var{tag}. 10481@end table 10482 10483In addition to the above, these options are available: 10484 10485@table @code 10486@item -c 10487Use the context diff format. This is the default format. 10488 10489@item -s 10490Create a summary change report instead of a patch. The 10491summary includes information about files that were 10492changed or added between the releases. It is sent to 10493the standard output device. This is useful for finding 10494out, for example, which files have changed between two 10495dates or revisions. 10496 10497@item -t 10498A diff of the top two revisions is sent to the standard 10499output device. This is most useful for seeing what the 10500last change to a file was. 10501 10502@item -u 10503Use the unidiff format for the context diffs. 10504Remember that old versions 10505of the @code{patch} program can't handle the unidiff 10506format, so if you plan to post this patch to the net 10507you should probably not use @samp{-u}. 10508 10509@item -V @var{vn} 10510Expand keywords according to the rules current in 10511@sc{rcs} version @var{vn} (the expansion format changed with 10512@sc{rcs} version 5). Note that this option is no 10513longer accepted. @sc{cvs} will always expand keywords the 10514way that @sc{rcs} version 5 does. 10515@end table 10516 10517@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10518@node rdiff examples 10519@appendixsubsec rdiff examples 10520 10521Suppose you receive mail from @t{foo@@example.net} asking for an 10522update from release 1.2 to 1.4 of the tc compiler. You 10523have no such patches on hand, but with @sc{cvs} that can 10524easily be fixed with a command such as this: 10525 10526@example 10527$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ 10528$$ Mail -s 'The patches you asked for' foo@@example.net 10529@end example 10530 10531Suppose you have made release 1.3, and forked a branch 10532called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1} 10533corresponds to release 1.3.1, which was made some time 10534ago. Now, you want to see how much development has been 10535done on the branch. This command can be used: 10536 10537@example 10538$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name 10539cvs rdiff: Diffing module-name 10540File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 10541File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 10542File bar.h,v changed from revision 1.29.2.1 to 1.2 10543@end example 10544 10545@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10546@node release 10547@appendixsec release---Indicate that a Module is no longer in use 10548@cindex release (subcommand) 10549 10550@itemize @bullet 10551@item 10552release [-d] directories@dots{} 10553@item 10554Requires: Working directory. 10555@item 10556Changes: Working directory, history log. 10557@end itemize 10558 10559This command is meant to safely cancel the effect of 10560@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it 10561isn't strictly necessary to use this command. You can 10562always simply delete your working directory, if you 10563like; but you risk losing changes you may have 10564forgotten, and you leave no trace in the @sc{cvs} history 10565file (@pxref{history file}) that you've abandoned your 10566checkout. 10567 10568Use @samp{cvs release} to avoid these problems. This 10569command checks that no uncommitted changes are 10570present; that you are executing it from immediately 10571above a @sc{cvs} working directory; and that the repository 10572recorded for your files is the same as the repository 10573defined in the module database. 10574 10575If all these conditions are true, @samp{cvs release} 10576leaves a record of its execution (attesting to your 10577intentionally abandoning your checkout) in the @sc{cvs} 10578history log. 10579 10580@menu 10581* release options:: release options 10582* release output:: release output 10583* release examples:: release examples 10584@end menu 10585 10586@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10587@node release options 10588@appendixsubsec release options 10589 10590The @code{release} command supports one command option: 10591 10592@table @code 10593@item -d 10594Delete your working copy of the file if the release 10595succeeds. If this flag is not given your files will 10596remain in your working directory. 10597 10598@strong{WARNING: The @code{release} command deletes 10599all directories and files recursively. This 10600has the very serious side-effect that any directory 10601that you have created inside your checked-out sources, 10602and not added to the repository (using the @code{add} 10603command; @pxref{Adding files}) will be silently deleted---even 10604if it is non-empty!} 10605@end table 10606 10607@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10608@node release output 10609@appendixsubsec release output 10610 10611Before @code{release} releases your sources it will 10612print a one-line message for any file that is not 10613up-to-date. 10614 10615@table @code 10616@item U @var{file} 10617@itemx P @var{file} 10618There exists a newer revision of this file in the 10619repository, and you have not modified your local copy 10620of the file (@samp{U} and @samp{P} mean the same thing). 10621 10622@item A @var{file} 10623The file has been added to your private copy of the 10624sources, but has not yet been committed to the 10625repository. If you delete your copy of the sources 10626this file will be lost. 10627 10628@item R @var{file} 10629The file has been removed from your private copy of the 10630sources, but has not yet been removed from the 10631repository, since you have not yet committed the 10632removal. @xref{commit}. 10633 10634@item M @var{file} 10635The file is modified in your working directory. There 10636might also be a newer revision inside the repository. 10637 10638@item ? @var{file} 10639@var{file} is in your working directory, but does not 10640correspond to anything in the source repository, and is 10641not in the list of files for @sc{cvs} to ignore (see the 10642description of the @samp{-I} option, and 10643@pxref{cvsignore}). If you remove your working 10644sources, this file will be lost. 10645@end table 10646 10647@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10648@node release examples 10649@appendixsubsec release examples 10650 10651Release the @file{tc} directory, and delete your local working copy 10652of the files. 10653 10654@example 10655$ cd .. # @r{You must stand immediately above the} 10656 # @r{sources when you issue @samp{cvs release}.} 10657$ cvs release -d tc 10658You have [0] altered files in this repository. 10659Are you sure you want to release (and delete) directory `tc': y 10660$ 10661@end example 10662 10663@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 10664@node update 10665@appendixsec update---Bring work tree in sync with repository 10666@cindex update (subcommand) 10667 10668@itemize @bullet 10669@item 10670update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files@dots{} 10671@item 10672Requires: repository, working directory. 10673@item 10674Changes: working directory. 10675@end itemize 10676 10677After you've run checkout to create your private copy 10678of source from the common repository, other developers 10679will continue changing the central source. From time 10680to time, when it is convenient in your development 10681process, you can use the @code{update} command from 10682within your working directory to reconcile your work 10683with any revisions applied to the source repository 10684since your last checkout or update. Without the @code{-C} 10685option, @code{update} will also merge any differences 10686between the local copy of files and their base revisions 10687into any destination revisions specified with @code{-r}, 10688@code{-D}, or @code{-A}. 10689 10690@menu 10691* update options:: update options 10692* update output:: update output 10693@end menu 10694 10695@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10696@node update options 10697@appendixsubsec update options 10698 10699These standard options are available with @code{update} 10700(@pxref{Common options}, for a complete description of 10701them): 10702 10703@table @code 10704@item -D date 10705Use the most recent revision no later than @var{date}. 10706This option is sticky, and implies @samp{-P}. 10707See @ref{Sticky tags}, for more information on sticky tags/dates. 10708 10709@item -f 10710Only useful with the @samp{-D @var{date}} or @samp{-r 10711@var{tag}} flags. If no matching revision is found, 10712retrieve the most recent revision (instead of ignoring 10713the file). 10714 10715@item -k @var{kflag} 10716Process keywords according to @var{kflag}. See 10717@ref{Keyword substitution}. 10718This option is sticky; future updates of 10719this file in this working directory will use the same 10720@var{kflag}. The @code{status} command can be viewed 10721to see the sticky options. See @ref{Invoking CVS}, for 10722more information on the @code{status} command. 10723 10724@item -l 10725Local; run only in current working directory. @xref{Recursive behavior}. 10726 10727@item -P 10728Prune empty directories. See @ref{Moving directories}. 10729 10730@item -p 10731Pipe files to the standard output. 10732 10733@item -R 10734Update directories recursively (default). @xref{Recursive 10735behavior}. 10736 10737@item -r rev 10738Retrieve revision/tag @var{rev}. This option is sticky, 10739and implies @samp{-P}. 10740See @ref{Sticky tags}, for more information on sticky tags/dates. 10741@end table 10742 10743@need 800 10744These special options are also available with 10745@code{update}. 10746 10747@table @code 10748@item -A 10749Reset any sticky tags, dates, or @samp{-k} options. 10750See @ref{Sticky tags}, for more information on sticky tags/dates. 10751 10752@item -C 10753Overwrite locally modified files with clean copies from 10754the repository (the modified file is saved in 10755@file{.#@var{file}.@var{revision}}, however). 10756 10757@item -d 10758Create any directories that exist in the repository if 10759they're missing from the working directory. Normally, 10760@code{update} acts only on directories and files that 10761were already enrolled in your working directory. 10762 10763This is useful for updating directories that were 10764created in the repository since the initial checkout; 10765but it has an unfortunate side effect. If you 10766deliberately avoided certain directories in the 10767repository when you created your working directory 10768(either through use of a module name or by listing 10769explicitly the files and directories you wanted on the 10770command line), then updating with @samp{-d} will create 10771those directories, which may not be what you want. 10772 10773@item -I @var{name} 10774Ignore files whose names match @var{name} (in your 10775working directory) during the update. You can specify 10776@samp{-I} more than once on the command line to specify 10777several files to ignore. Use @samp{-I !} to avoid 10778ignoring any files at all. @xref{cvsignore}, for other 10779ways to make @sc{cvs} ignore some files. 10780 10781@item -W@var{spec} 10782Specify file names that should be filtered during 10783update. You can use this option repeatedly. 10784 10785@var{spec} can be a file name pattern of the same type 10786that you can specify in the @file{.cvswrappers} 10787file. @xref{Wrappers}. 10788 10789@item -j@var{revision} 10790With two @samp{-j} options, merge changes from the 10791revision specified with the first @samp{-j} option to 10792the revision specified with the second @samp{j} option, 10793into the working directory. 10794 10795With one @samp{-j} option, merge changes from the 10796ancestor revision to the revision specified with the 10797@samp{-j} option, into the working directory. The 10798ancestor revision is the common ancestor of the 10799revision which the working directory is based on, and 10800the revision specified in the @samp{-j} option. 10801 10802Note that using a single @samp{-j @var{tagname}} option rather than 10803@samp{-j @var{branchname}} to merge changes from a branch will 10804often not remove files which were removed on the branch. 10805@xref{Merging adds and removals}, for more. 10806 10807In addition, each @samp{-j} option can contain an optional 10808date specification which, when used with branches, can 10809limit the chosen revision to one within a specific 10810date. An optional date is specified by adding a colon 10811(:) to the tag: 10812@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. 10813 10814@xref{Branching and merging}. 10815 10816@end table 10817 10818@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10819@node update output 10820@appendixsubsec update output 10821 10822@code{update} and @code{checkout} keep you informed of 10823their progress by printing a line for each file, preceded 10824by one character indicating the status of the file: 10825 10826@table @code 10827@item U @var{file} 10828The file was brought up to date with respect to the 10829repository. This is done for any file that exists in 10830the repository but not in your source, and for files 10831that you haven't changed but are not the most recent 10832versions available in the repository. 10833 10834@item P @var{file} 10835Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire 10836file. This accomplishes the same thing as @samp{U} using less bandwidth. 10837 10838@item A @var{file} 10839The file has been added to your private copy of the 10840sources, and will be added to the source repository 10841when you run @code{commit} on the file. This is a 10842reminder to you that the file needs to be committed. 10843 10844@item R @var{file} 10845The file has been removed from your private copy of the 10846sources, and will be removed from the source repository 10847when you run @code{commit} on the file. This is a 10848reminder to you that the file needs to be committed. 10849 10850@item M @var{file} 10851The file is modified in your working directory. 10852 10853@samp{M} can indicate one of two states for a file 10854you're working on: either there were no modifications 10855to the same file in the repository, so that your file 10856remains as you last saw it; or there were modifications 10857in the repository as well as in your copy, but they 10858were merged successfully, without conflict, in your 10859working directory. 10860 10861@sc{cvs} will print some messages if it merges your work, 10862and a backup copy of your working file (as it looked 10863before you ran @code{update}) will be made. The exact 10864name of that file is printed while @code{update} runs. 10865 10866@item C @var{file} 10867@cindex .# files 10868@cindex __ files (VMS) 10869A conflict was detected while trying to merge your 10870changes to @var{file} with changes from the source 10871repository. @var{file} (the copy in your working 10872directory) is now the result of attempting to merge 10873the two revisions; an unmodified copy of your file 10874is also in your working directory, with the name 10875@file{.#@var{file}.@var{revision}} where @var{revision} 10876is the revision that your modified file started 10877from. Resolve the conflict as described in 10878@ref{Conflicts example}. 10879@c "some systems" as in out-of-the-box OSes? Not as 10880@c far as I know. We need to advise sysadmins as well 10881@c as users how to set up this kind of purge, if that is 10882@c what they want. 10883@c We also might want to think about cleaner solutions, 10884@c like having CVS remove the .# file once the conflict 10885@c has been resolved or something like that. 10886(Note that some systems automatically purge 10887files that begin with @file{.#} if they have not been 10888accessed for a few days. If you intend to keep a copy 10889of your original file, it is a very good idea to rename 10890it.) Under @sc{vms}, the file name starts with 10891@file{__} rather than @file{.#}. 10892 10893@item ? @var{file} 10894@var{file} is in your working directory, but does not 10895correspond to anything in the source repository, and is 10896not in the list of files for @sc{cvs} to ignore (see the 10897description of the @samp{-I} option, and 10898@pxref{cvsignore}). 10899@end table 10900 10901@node Invoking CVS 10902@appendix Quick reference to CVS commands 10903@cindex Command reference 10904@cindex Reference, commands 10905@cindex Invoking CVS 10906 10907This appendix describes how to invoke @sc{cvs}, with 10908references to where each command or feature is 10909described in detail. For other references run the 10910@code{cvs --help} command, or see @ref{Index}. 10911 10912A @sc{cvs} command looks like: 10913 10914@example 10915cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ] 10916@end example 10917 10918Global options: 10919 10920@table @code 10921@item --allow-root=@var{rootdir} 10922Specify legal @sc{cvsroot} directory (server only) (not 10923in @sc{cvs} 1.9 and older). See @ref{Password 10924authentication server}. 10925 10926@item -a 10927Authenticate all communication (client only) (not in @sc{cvs} 109281.9 and older). See @ref{Global options}. 10929 10930@item -b 10931Specify RCS location (@sc{cvs} 1.9 and older). See 10932@ref{Global options}. 10933 10934@item -d @var{root} 10935Specify the @sc{cvsroot}. See @ref{Repository}. 10936 10937@item -e @var{editor} 10938Edit messages with @var{editor}. See @ref{Committing 10939your changes}. 10940 10941@item -f 10942Do not read the @file{~/.cvsrc} file. See @ref{Global 10943options}. 10944 10945@item -H 10946@itemx --help 10947Print a help message. See @ref{Global options}. 10948 10949@item -l 10950Do not log in @file{$CVSROOT/CVSROOT/history} file. See @ref{Global 10951options}. 10952 10953@item -n 10954Do not change any files. See @ref{Global options}. 10955 10956@item -Q 10957Be really quiet. See @ref{Global options}. 10958 10959@item -q 10960Be somewhat quiet. See @ref{Global options}. 10961 10962@item -r 10963Make new working files read-only. See @ref{Global options}. 10964 10965@item -s @var{variable}=@var{value} 10966Set a user variable. See @ref{Variables}. 10967 10968@item -T @var{tempdir} 10969Put temporary files in @var{tempdir}. See @ref{Global 10970options}. 10971 10972@item -t 10973Trace @sc{cvs} execution. See @ref{Global options}. 10974 10975@item -v 10976@item --version 10977Display version and copyright information for @sc{cvs}. 10978 10979@item -w 10980Make new working files read-write. See @ref{Global 10981options}. 10982 10983@item -x 10984Encrypt all communication (client only). 10985See @ref{Global options}. 10986 10987@item -z @var{gzip-level} 10988@cindex Compression 10989@cindex Gzip 10990Set the compression level (client only). 10991See @ref{Global options}. 10992@end table 10993 10994Keyword expansion modes (@pxref{Substitution modes}): 10995 10996@example 10997-kkv $ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ 10998-kkvl $ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 10999-kk $ Id$ 11000-kv file1,v 1.1 1993/12/09 03:21:13 joe Exp 11001-ko @i{no expansion} 11002-kb @i{no expansion, file is binary} 11003@end example 11004 11005Keywords (@pxref{Keyword list}): 11006 11007@example 11008$ Author: joe $ 11009$ Date: 1993/12/09 03:21:13 $ 11010$ CVSHeader: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11011$ Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11012$ Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $ 11013$ Locker: harry $ 11014$ Name: snapshot_1_14 $ 11015$ RCSfile: file1,v $ 11016$ Revision: 1.1 $ 11017$ Source: /home/files/file1,v $ 11018$ State: Exp $ 11019$ Log: file1,v $ 11020Revision 1.1 1993/12/09 03:30:17 joe 11021Initial revision 11022 11023@end example 11024 11025@c The idea behind this table is that we want each item 11026@c to be a sentence or two at most. Preferably a 11027@c single line. 11028@c 11029@c In some cases refs to "foo options" are just to get 11030@c this thing written quickly, not because the "foo 11031@c options" node is really the best place to point. 11032Commands, command options, and command arguments: 11033 11034@table @code 11035@c ------------------------------------------------------------ 11036@item add [@var{options}] [@var{files}@dots{}] 11037Add a new file/directory. See @ref{Adding files}. 11038 11039@table @code 11040@item -k @var{kflag} 11041Set keyword expansion. 11042 11043@item -m @var{msg} 11044Set file description. 11045@end table 11046 11047@c ------------------------------------------------------------ 11048@item admin [@var{options}] [@var{files}@dots{}] 11049Administration of history files in the repository. See 11050@ref{admin}. 11051@c This list omits those options which are not 11052@c documented as being useful with CVS. That might be 11053@c a mistake... 11054 11055@table @code 11056@item -b[@var{rev}] 11057Set default branch. See @ref{Reverting local changes}. 11058 11059@item -c@var{string} 11060Set comment leader. 11061 11062@item -k@var{subst} 11063Set keyword substitution. See @ref{Keyword 11064substitution}. 11065 11066@item -l[@var{rev}] 11067Lock revision @var{rev}, or latest revision. 11068 11069@item -m@var{rev}:@var{msg} 11070Replace the log message of revision @var{rev} with 11071@var{msg}. 11072 11073@item -o@var{range} 11074Delete revisions from the repository. See 11075@ref{admin options}. 11076 11077@item -q 11078Run quietly; do not print diagnostics. 11079 11080@item -s@var{state}[:@var{rev}] 11081Set the state. 11082 11083@c Does not work for client/server CVS 11084@item -t 11085Set file description from standard input. 11086 11087@item -t@var{file} 11088Set file description from @var{file}. 11089 11090@item -t-@var{string} 11091Set file description to @var{string}. 11092 11093@item -u[@var{rev}] 11094Unlock revision @var{rev}, or latest revision. 11095@end table 11096 11097@c ------------------------------------------------------------ 11098@item annotate [@var{options}] [@var{files}@dots{}] 11099Show last revision where each line was modified. See 11100@ref{annotate}. 11101 11102@table @code 11103@item -D @var{date} 11104Annotate the most recent revision no later than 11105@var{date}. See @ref{Common options}. 11106 11107@item -F 11108Force annotation of binary files. (Without this option, 11109binary files are skipped with a message.) 11110 11111@item -f 11112Use head revision if tag/date not found. See 11113@ref{Common options}. 11114 11115@item -l 11116Local; run only in current working directory. @xref{Recursive behavior}. 11117 11118@item -R 11119Operate recursively (default). @xref{Recursive 11120behavior}. 11121 11122@item -r @var{tag} 11123Annotate revision @var{tag}. See @ref{Common options}. 11124@end table 11125 11126@c ------------------------------------------------------------ 11127@item checkout [@var{options}] @var{modules}@dots{} 11128Get a copy of the sources. See @ref{checkout}. 11129 11130@table @code 11131@item -A 11132Reset any sticky tags/date/options. See @ref{Sticky 11133tags} and @ref{Keyword substitution}. 11134 11135@item -c 11136Output the module database. See @ref{checkout options}. 11137 11138@item -D @var{date} 11139Check out revisions as of @var{date} (is sticky). See 11140@ref{Common options}. 11141 11142@item -d @var{dir} 11143Check out into @var{dir}. See @ref{checkout options}. 11144 11145@item -f 11146Use head revision if tag/date not found. See 11147@ref{Common options}. 11148 11149@c Probably want to use rev1/rev2 style like for diff 11150@c -r. Here and in on-line help. 11151@item -j @var{rev} 11152Merge in changes. See @ref{checkout options}. 11153 11154@item -k @var{kflag} 11155Use @var{kflag} keyword expansion. See 11156@ref{Substitution modes}. 11157 11158@item -l 11159Local; run only in current working directory. @xref{Recursive behavior}. 11160 11161@item -N 11162Don't ``shorten'' module paths if -d specified. See 11163@ref{checkout options}. 11164 11165@item -n 11166Do not run module program (if any). See @ref{checkout options}. 11167 11168@item -P 11169Prune empty directories. See @ref{Moving directories}. 11170 11171@item -p 11172Check out files to standard output (avoids 11173stickiness). See @ref{checkout options}. 11174 11175@item -R 11176Operate recursively (default). @xref{Recursive 11177behavior}. 11178 11179@item -r @var{tag} 11180Checkout revision @var{tag} (is sticky). See @ref{Common options}. 11181 11182@item -s 11183Like -c, but include module status. See @ref{checkout options}. 11184@end table 11185 11186@c ------------------------------------------------------------ 11187@item commit [@var{options}] [@var{files}@dots{}] 11188Check changes into the repository. See @ref{commit}. 11189 11190@table @code 11191@item -F @var{file} 11192Read log message from @var{file}. See @ref{commit options}. 11193 11194@item -f 11195@c What is this "disables recursion"? It is from the 11196@c on-line help; is it documented in this manual? 11197Force the file to be committed; disables recursion. 11198See @ref{commit options}. 11199 11200@item -l 11201Local; run only in current working directory. See @ref{Recursive behavior}. 11202 11203@item -m @var{msg} 11204Use @var{msg} as log message. See @ref{commit options}. 11205 11206@item -n 11207Do not run module program (if any). See @ref{commit options}. 11208 11209@item -R 11210Operate recursively (default). @xref{Recursive 11211behavior}. 11212 11213@item -r @var{rev} 11214Commit to @var{rev}. See @ref{commit options}. 11215@c FIXME: should be dragging over text from 11216@c commit options, especially if it can be cleaned up 11217@c and made concise enough. 11218@end table 11219 11220@c ------------------------------------------------------------ 11221@item diff [@var{options}] [@var{files}@dots{}] 11222Show differences between revisions. See @ref{diff}. 11223In addition to the options shown below, accepts a wide 11224variety of options to control output style, for example 11225@samp{-c} for context diffs. 11226 11227@table @code 11228@item -D @var{date1} 11229Diff revision for date against working file. See 11230@ref{diff options}. 11231 11232@item -D @var{date2} 11233Diff @var{rev1}/@var{date1} against @var{date2}. See 11234@ref{diff options}. 11235 11236@item -l 11237Local; run only in current working directory. See @ref{Recursive behavior}. 11238 11239@item -N 11240Include diffs for added and removed files. See 11241@ref{diff options}. 11242 11243@item -R 11244Operate recursively (default). @xref{Recursive 11245behavior}. 11246 11247@item -r @var{rev1} 11248Diff revision for @var{rev1} against working file. See 11249@ref{diff options}. 11250 11251@item -r @var{rev2} 11252Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}. 11253@end table 11254 11255@c ------------------------------------------------------------ 11256@item edit [@var{options}] [@var{files}@dots{}] 11257Get ready to edit a watched file. See @ref{Editing files}. 11258 11259@table @code 11260@item -a @var{actions} 11261Specify actions for temporary watch, where 11262@var{actions} is @code{edit}, @code{unedit}, 11263@code{commit}, @code{all}, or @code{none}. See 11264@ref{Editing files}. 11265 11266@item -l 11267Local; run only in current working directory. See @ref{Recursive behavior}. 11268 11269@item -R 11270Operate recursively (default). @xref{Recursive 11271behavior}. 11272@end table 11273 11274@c ------------------------------------------------------------ 11275@item editors [@var{options}] [@var{files}@dots{}] 11276See who is editing a watched file. See @ref{Watch information}. 11277 11278@table @code 11279@item -l 11280Local; run only in current working directory. See @ref{Recursive behavior}. 11281 11282@item -R 11283Operate recursively (default). @xref{Recursive 11284behavior}. 11285@end table 11286 11287@c ------------------------------------------------------------ 11288@item export [@var{options}] @var{modules}@dots{} 11289Export files from @sc{cvs}. See @ref{export}. 11290 11291@table @code 11292@item -D @var{date} 11293Check out revisions as of @var{date}. See 11294@ref{Common options}. 11295 11296@item -d @var{dir} 11297Check out into @var{dir}. See @ref{export options}. 11298 11299@item -f 11300Use head revision if tag/date not found. See 11301@ref{Common options}. 11302 11303@item -k @var{kflag} 11304Use @var{kflag} keyword expansion. See 11305@ref{Substitution modes}. 11306 11307@item -l 11308Local; run only in current working directory. @xref{Recursive behavior}. 11309 11310@item -N 11311Don't ``shorten'' module paths if -d specified. See 11312@ref{export options}. 11313 11314@item -n 11315Do not run module program (if any). See @ref{export options}. 11316 11317@item -R 11318Operate recursively (default). @xref{Recursive 11319behavior}. 11320 11321@item -r @var{tag} 11322Checkout revision @var{tag}. See @ref{Common options}. 11323@end table 11324 11325@c ------------------------------------------------------------ 11326@item history [@var{options}] [@var{files}@dots{}] 11327Show repository access history. See @ref{history}. 11328 11329@table @code 11330@item -a 11331All users (default is self). See @ref{history options}. 11332 11333@item -b @var{str} 11334Back to record with @var{str} in module/file/repos 11335field. See @ref{history options}. 11336 11337@item -c 11338Report on committed (modified) files. See @ref{history options}. 11339 11340@item -D @var{date} 11341Since @var{date}. See @ref{history options}. 11342 11343@item -e 11344Report on all record types. See @ref{history options}. 11345 11346@item -l 11347Last modified (committed or modified report). See @ref{history options}. 11348 11349@item -m @var{module} 11350Report on @var{module} (repeatable). See @ref{history options}. 11351 11352@item -n @var{module} 11353In @var{module}. See @ref{history options}. 11354 11355@item -o 11356Report on checked out modules. See @ref{history options}. 11357 11358@item -p @var{repository} 11359In @var{repository}. See @ref{history options}. 11360 11361@item -r @var{rev} 11362Since revision @var{rev}. See @ref{history options}. 11363 11364@item -T 11365@c What the @#$@# is a TAG? Same as a tag? This 11366@c wording is also in the online-line help. 11367Produce report on all TAGs. See @ref{history options}. 11368 11369@item -t @var{tag} 11370Since tag record placed in history file (by anyone). 11371See @ref{history options}. 11372 11373@item -u @var{user} 11374For user @var{user} (repeatable). See @ref{history options}. 11375 11376@item -w 11377Working directory must match. See @ref{history options}. 11378 11379@item -x @var{types} 11380Report on @var{types}, one or more of 11381@code{TOEFWUCGMAR}. See @ref{history options}. 11382 11383@item -z @var{zone} 11384Output for time zone @var{zone}. See @ref{history options}. 11385@end table 11386 11387@c ------------------------------------------------------------ 11388@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{} 11389Import files into @sc{cvs}, using vendor branches. See 11390@ref{import}. 11391 11392@table @code 11393@item -b @var{bra} 11394Import to vendor branch @var{bra}. See 11395@ref{Multiple vendor branches}. 11396 11397@item -d 11398Use the file's modification time as the time of 11399import. See @ref{import options}. 11400 11401@item -k @var{kflag} 11402Set default keyword substitution mode. See 11403@ref{import options}. 11404 11405@item -m @var{msg} 11406Use @var{msg} for log message. See 11407@ref{import options}. 11408 11409@item -I @var{ign} 11410More files to ignore (! to reset). See 11411@ref{import options}. 11412 11413@item -W @var{spec} 11414More wrappers. See @ref{import options}. 11415@end table 11416 11417@c ------------------------------------------------------------ 11418@item init 11419Create a @sc{cvs} repository if it doesn't exist. See 11420@ref{Creating a repository}. 11421 11422@c ------------------------------------------------------------ 11423@item kserver 11424Kerberos authenticated server. 11425See @ref{Kerberos authenticated}. 11426 11427@c ------------------------------------------------------------ 11428@item log [@var{options}] [@var{files}@dots{}] 11429Print out history information for files. See @ref{log}. 11430 11431@table @code 11432@item -b 11433Only list revisions on the default branch. See @ref{log options}. 11434 11435@item -d @var{dates} 11436Specify dates (@var{d1}<@var{d2} for range, @var{d} for 11437latest before). See @ref{log options}. 11438 11439@item -h 11440Only print header. See @ref{log options}. 11441 11442@item -l 11443Local; run only in current working directory. See @ref{Recursive behavior}. 11444 11445@item -N 11446Do not list tags. See @ref{log options}. 11447 11448@item -R 11449Only print name of RCS file. See @ref{log options}. 11450 11451@item -r@var{revs} 11452Only list revisions @var{revs}. See @ref{log options}. 11453 11454@item -s @var{states} 11455Only list revisions with specified states. See @ref{log options}. 11456 11457@item -t 11458Only print header and descriptive text. See @ref{log 11459options}. 11460 11461@item -w@var{logins} 11462Only list revisions checked in by specified logins. See @ref{log options}. 11463@end table 11464 11465@c ------------------------------------------------------------ 11466@item login 11467Prompt for password for authenticating server. See 11468@ref{Password authentication client}. 11469 11470@c ------------------------------------------------------------ 11471@item logout 11472Remove stored password for authenticating server. See 11473@ref{Password authentication client}. 11474 11475@c ------------------------------------------------------------ 11476@item pserver 11477Password authenticated server. 11478See @ref{Password authentication server}. 11479 11480@c ------------------------------------------------------------ 11481@item rannotate [@var{options}] [@var{modules}@dots{}] 11482Show last revision where each line was modified. See 11483@ref{annotate}. 11484 11485@table @code 11486@item -D @var{date} 11487Annotate the most recent revision no later than 11488@var{date}. See @ref{Common options}. 11489 11490@item -F 11491Force annotation of binary files. (Without this option, 11492binary files are skipped with a message.) 11493 11494@item -f 11495Use head revision if tag/date not found. See 11496@ref{Common options}. 11497 11498@item -l 11499Local; run only in current working directory. @xref{Recursive behavior}. 11500 11501@item -R 11502Operate recursively (default). @xref{Recursive behavior}. 11503 11504@item -r @var{tag} 11505Annotate revision @var{tag}. See @ref{Common options}. 11506@end table 11507 11508@c ------------------------------------------------------------ 11509@item rdiff [@var{options}] @var{modules}@dots{} 11510Show differences between releases. See @ref{rdiff}. 11511 11512@table @code 11513@item -c 11514Context diff output format (default). See @ref{rdiff options}. 11515 11516@item -D @var{date} 11517Select revisions based on @var{date}. See @ref{Common options}. 11518 11519@item -f 11520Use head revision if tag/date not found. See 11521@ref{Common options}. 11522 11523@item -l 11524Local; run only in current working directory. See @ref{Recursive behavior}. 11525 11526@item -R 11527Operate recursively (default). @xref{Recursive 11528behavior}. 11529 11530@item -r @var{rev} 11531Select revisions based on @var{rev}. See @ref{Common options}. 11532 11533@item -s 11534Short patch - one liner per file. See @ref{rdiff options}. 11535 11536@item -t 11537Top two diffs - last change made to the file. See 11538@ref{diff options}. 11539 11540@item -u 11541Unidiff output format. See @ref{rdiff options}. 11542 11543@item -V @var{vers} 11544Use RCS Version @var{vers} for keyword expansion (obsolete). See 11545@ref{rdiff options}. 11546@end table 11547 11548@c ------------------------------------------------------------ 11549@item release [@var{options}] @var{directory} 11550Indicate that a directory is no longer in use. See 11551@ref{release}. 11552 11553@table @code 11554@item -d 11555Delete the given directory. See @ref{release options}. 11556@end table 11557 11558@c ------------------------------------------------------------ 11559@item remove [@var{options}] [@var{files}@dots{}] 11560Remove an entry from the repository. See @ref{Removing files}. 11561 11562@table @code 11563@item -f 11564Delete the file before removing it. See @ref{Removing files}. 11565 11566@item -l 11567Local; run only in current working directory. See @ref{Recursive behavior}. 11568 11569@item -R 11570Operate recursively (default). @xref{Recursive 11571behavior}. 11572@end table 11573 11574@c ------------------------------------------------------------ 11575@item rlog [@var{options}] [@var{files}@dots{}] 11576Print out history information for modules. See @ref{log}. 11577 11578@table @code 11579@item -b 11580Only list revisions on the default branch. See @ref{log options}. 11581 11582@item -d @var{dates} 11583Specify dates (@var{d1}<@var{d2} for range, @var{d} for 11584latest before). See @ref{log options}. 11585 11586@item -h 11587Only print header. See @ref{log options}. 11588 11589@item -l 11590Local; run only in current working directory. See @ref{Recursive behavior}. 11591 11592@item -N 11593Do not list tags. See @ref{log options}. 11594 11595@item -R 11596Only print name of RCS file. See @ref{log options}. 11597 11598@item -r@var{revs} 11599Only list revisions @var{revs}. See @ref{log options}. 11600 11601@item -s @var{states} 11602Only list revisions with specified states. See @ref{log options}. 11603 11604@item -t 11605Only print header and descriptive text. See @ref{log options}. 11606 11607@item -w@var{logins} 11608Only list revisions checked in by specified logins. See @ref{log options}. 11609@end table 11610 11611@c ------------------------------------------------------------ 11612@item rtag [@var{options}] @var{tag} @var{modules}@dots{} 11613Add a symbolic tag to a module. 11614See @ref{Revisions} and @ref{Branching and merging}. 11615 11616@table @code 11617@item -a 11618Clear tag from removed files that would not otherwise 11619be tagged. See @ref{Tagging add/remove}. 11620 11621@item -b 11622Create a branch named @var{tag}. See @ref{Branching and merging}. 11623 11624@item -B 11625Used in conjunction with -F or -d, enables movement and deletion of 11626branch tags. Use with extreme caution. 11627 11628@item -D @var{date} 11629Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 11630 11631@item -d 11632Delete @var{tag}. See @ref{Modifying tags}. 11633 11634@item -F 11635Move @var{tag} if it already exists. See @ref{Modifying tags}. 11636 11637@item -f 11638Force a head revision match if tag/date not found. 11639See @ref{Tagging by date/tag}. 11640 11641@item -l 11642Local; run only in current working directory. See @ref{Recursive behavior}. 11643 11644@item -n 11645No execution of tag program. See @ref{Common options}. 11646 11647@item -R 11648Operate recursively (default). @xref{Recursive 11649behavior}. 11650 11651@item -r @var{rev} 11652Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. 11653@end table 11654 11655@c ------------------------------------------------------------ 11656@item server 11657Rsh server. See @ref{Connecting via rsh}. 11658 11659@c ------------------------------------------------------------ 11660@item status [@var{options}] @var{files}@dots{} 11661Display status information in a working directory. See 11662@ref{File status}. 11663 11664@table @code 11665@item -l 11666Local; run only in current working directory. See @ref{Recursive behavior}. 11667 11668@item -R 11669Operate recursively (default). @xref{Recursive 11670behavior}. 11671 11672@item -v 11673Include tag information for file. See @ref{Tags}. 11674@end table 11675 11676@c ------------------------------------------------------------ 11677@item tag [@var{options}] @var{tag} [@var{files}@dots{}] 11678Add a symbolic tag to checked out version of files. 11679See @ref{Revisions} and @ref{Branching and merging}. 11680 11681@table @code 11682@item -b 11683Create a branch named @var{tag}. See @ref{Branching and merging}. 11684 11685@item -c 11686Check that working files are unmodified. See 11687@ref{Tagging the working directory}. 11688 11689@item -D @var{date} 11690Tag revisions as of @var{date}. See @ref{Tagging by date/tag}. 11691 11692@item -d 11693Delete @var{tag}. See @ref{Modifying tags}. 11694 11695@item -F 11696Move @var{tag} if it already exists. See @ref{Modifying tags}. 11697 11698@item -f 11699Force a head revision match if tag/date not found. 11700See @ref{Tagging by date/tag}. 11701 11702@item -l 11703Local; run only in current working directory. See @ref{Recursive behavior}. 11704 11705@item -R 11706Operate recursively (default). @xref{Recursive 11707behavior}. 11708 11709@item -r @var{rev} 11710Tag existing tag @var{rev}. See @ref{Tagging by date/tag}. 11711@end table 11712 11713@c ------------------------------------------------------------ 11714@item unedit [@var{options}] [@var{files}@dots{}] 11715Undo an edit command. See @ref{Editing files}. 11716 11717@table @code 11718@item -l 11719Local; run only in current working directory. See @ref{Recursive behavior}. 11720 11721@item -R 11722Operate recursively (default). @xref{Recursive behavior}. 11723@end table 11724 11725@c ------------------------------------------------------------ 11726@item update [@var{options}] [@var{files}@dots{}] 11727Bring work tree in sync with repository. See 11728@ref{update}. 11729 11730@table @code 11731@item -A 11732Reset any sticky tags/date/options. See @ref{Sticky 11733tags} and @ref{Keyword substitution}. 11734 11735@item -C 11736Overwrite locally modified files with clean copies from 11737the repository (the modified file is saved in 11738@file{.#@var{file}.@var{revision}}, however). 11739 11740@item -D @var{date} 11741Check out revisions as of @var{date} (is sticky). See 11742@ref{Common options}. 11743 11744@item -d 11745Create directories. See @ref{update options}. 11746 11747@item -f 11748Use head revision if tag/date not found. See 11749@ref{Common options}. 11750 11751@item -I @var{ign} 11752More files to ignore (! to reset). See 11753@ref{import options}. 11754 11755@c Probably want to use rev1/rev2 style like for diff 11756@c -r. Here and in on-line help. 11757@item -j @var{rev} 11758Merge in changes. See @ref{update options}. 11759 11760@item -k @var{kflag} 11761Use @var{kflag} keyword expansion. See 11762@ref{Substitution modes}. 11763 11764@item -l 11765Local; run only in current working directory. @xref{Recursive behavior}. 11766 11767@item -P 11768Prune empty directories. See @ref{Moving directories}. 11769 11770@item -p 11771Check out files to standard output (avoids 11772stickiness). See @ref{update options}. 11773 11774@item -R 11775Operate recursively (default). @xref{Recursive 11776behavior}. 11777 11778@item -r @var{tag} 11779Checkout revision @var{tag} (is sticky). See @ref{Common options}. 11780 11781@item -W @var{spec} 11782More wrappers. See @ref{import options}. 11783@end table 11784 11785@c ------------------------------------------------------------ 11786@item version 11787@cindex version (subcommand) 11788 11789Display the version of @sc{cvs} being used. If the repository 11790is remote, display both the client and server versions. 11791 11792@c ------------------------------------------------------------ 11793@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}] 11794 11795on/off: turn on/off read-only checkouts of files. See 11796@ref{Setting a watch}. 11797 11798add/remove: add or remove notification on actions. See 11799@ref{Getting Notified}. 11800 11801@table @code 11802@item -a @var{actions} 11803Specify actions for temporary watch, where 11804@var{actions} is @code{edit}, @code{unedit}, 11805@code{commit}, @code{all}, or @code{none}. See 11806@ref{Editing files}. 11807 11808@item -l 11809Local; run only in current working directory. See @ref{Recursive behavior}. 11810 11811@item -R 11812Operate recursively (default). @xref{Recursive 11813behavior}. 11814@end table 11815 11816@c ------------------------------------------------------------ 11817@item watchers [@var{options}] [@var{files}@dots{}] 11818See who is watching a file. See @ref{Watch information}. 11819 11820@table @code 11821@item -l 11822Local; run only in current working directory. See @ref{Recursive behavior}. 11823 11824@item -R 11825Operate recursively (default). @xref{Recursive 11826behavior}. 11827@end table 11828 11829@end table 11830 11831@c --------------------------------------------------------------------- 11832@node Administrative files 11833@appendix Reference manual for Administrative files 11834@cindex Administrative files (reference) 11835@cindex Files, reference manual 11836@cindex Reference manual (files) 11837@cindex CVSROOT (file) 11838 11839@c FIXME? Somewhere there needs to be a more "how-to" 11840@c guide to writing these. I think the triggers 11841@c (commitinfo, loginfo, taginfo, &c) are perhaps a 11842@c different case than files like modules. One 11843@c particular issue that people sometimes are 11844@c (unnecessarily?) worried about is performance, and 11845@c the impact of writing in perl or sh or ____. 11846Inside the repository, in the directory 11847@file{$CVSROOT/CVSROOT}, there are a number of 11848supportive files for @sc{cvs}. You can use @sc{cvs} in a limited 11849fashion without any of them, but if they are set up 11850properly they can help make life easier. For a 11851discussion of how to edit them, see @ref{Intro 11852administrative files}. 11853 11854The most important of these files is the @file{modules} 11855file, which defines the modules inside the repository. 11856 11857@menu 11858* modules:: Defining modules 11859* Wrappers:: Specify binary-ness based on file name 11860* commit files:: The commit support files (commitinfo, 11861 verifymsg, editinfo, loginfo) 11862* rcsinfo:: Templates for the log messages 11863* cvsignore:: Ignoring files via cvsignore 11864* checkoutlist:: Adding your own administrative files 11865* history file:: History information 11866* Variables:: Various variables are expanded 11867* config:: Miscellaneous CVS configuration 11868@end menu 11869 11870@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11871@node modules 11872@appendixsec The modules file 11873@cindex Modules (admin file) 11874@cindex Defining modules (reference manual) 11875 11876The @file{modules} file records your definitions of 11877names for collections of source code. @sc{cvs} will 11878use these definitions if you use @sc{cvs} to update the 11879modules file (use normal commands like @code{add}, 11880@code{commit}, etc). 11881 11882The @file{modules} file may contain blank lines and 11883comments (lines beginning with @samp{#}) as well as 11884module definitions. Long lines can be continued on the 11885next line by specifying a backslash (@samp{\}) as the 11886last character on the line. 11887 11888There are three basic types of modules: alias modules, 11889regular modules, and ampersand modules. The difference 11890between them is the way that they map files in the 11891repository to files in the working directory. In all 11892of the following examples, the top-level repository 11893contains a directory called @file{first-dir}, which 11894contains two files, @file{file1} and @file{file2}, and a 11895directory @file{sdir}. @file{first-dir/sdir} contains 11896a file @file{sfile}. 11897 11898@c FIXME: should test all the examples in this section. 11899 11900@menu 11901* Alias modules:: The simplest kind of module 11902* Regular modules:: 11903* Ampersand modules:: 11904* Excluding directories:: Excluding directories from a module 11905* Module options:: Regular and ampersand modules can take options 11906* Module program options:: How the modules ``program options'' programs 11907 are run. 11908@end menu 11909 11910@node Alias modules 11911@appendixsubsec Alias modules 11912@cindex Alias modules 11913@cindex -a, in modules file 11914 11915Alias modules are the simplest kind of module: 11916 11917@table @code 11918@item @var{mname} -a @var{aliases}@dots{} 11919This represents the simplest way of defining a module 11920@var{mname}. The @samp{-a} flags the definition as a 11921simple alias: @sc{cvs} will treat any use of @var{mname} (as 11922a command argument) as if the list of names 11923@var{aliases} had been specified instead. 11924@var{aliases} may contain either other module names or 11925paths. When you use paths in aliases, @code{checkout} 11926creates all intermediate directories in the working 11927directory, just as if the path had been specified 11928explicitly in the @sc{cvs} arguments. 11929@end table 11930 11931For example, if the modules file contains: 11932 11933@example 11934amodule -a first-dir 11935@end example 11936 11937@noindent 11938then the following two commands are equivalent: 11939 11940@example 11941$ cvs co amodule 11942$ cvs co first-dir 11943@end example 11944 11945@noindent 11946and they each would provide output such as: 11947 11948@example 11949cvs checkout: Updating first-dir 11950U first-dir/file1 11951U first-dir/file2 11952cvs checkout: Updating first-dir/sdir 11953U first-dir/sdir/sfile 11954@end example 11955 11956@node Regular modules 11957@appendixsubsec Regular modules 11958@cindex Regular modules 11959 11960@table @code 11961@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] 11962In the simplest case, this form of module definition 11963reduces to @samp{@var{mname} @var{dir}}. This defines 11964all the files in directory @var{dir} as module mname. 11965@var{dir} is a relative path (from @code{$CVSROOT}) to a 11966directory of source in the source repository. In this 11967case, on checkout, a single directory called 11968@var{mname} is created as a working directory; no 11969intermediate directory levels are used by default, even 11970if @var{dir} was a path involving several directory 11971levels. 11972@end table 11973 11974For example, if a module is defined by: 11975 11976@example 11977regmodule first-dir 11978@end example 11979 11980@noindent 11981then regmodule will contain the files from first-dir: 11982 11983@example 11984$ cvs co regmodule 11985cvs checkout: Updating regmodule 11986U regmodule/file1 11987U regmodule/file2 11988cvs checkout: Updating regmodule/sdir 11989U regmodule/sdir/sfile 11990$ 11991@end example 11992 11993By explicitly specifying files in the module definition 11994after @var{dir}, you can select particular files from 11995directory @var{dir}. Here is 11996an example: 11997 11998@example 11999regfiles first-dir/sdir sfile 12000@end example 12001 12002@noindent 12003With this definition, getting the regfiles module 12004will create a single working directory 12005@file{regfiles} containing the file listed, which 12006comes from a directory deeper 12007in the @sc{cvs} source repository: 12008 12009@example 12010$ cvs co regfiles 12011U regfiles/sfile 12012$ 12013@end example 12014 12015@node Ampersand modules 12016@appendixsubsec Ampersand modules 12017@cindex Ampersand modules 12018@cindex &, in modules file 12019 12020A module definition can refer to other modules by 12021including @samp{&@var{module}} in its definition. 12022@example 12023@var{mname} [ options ] @var{&module}@dots{} 12024@end example 12025 12026Then getting the module creates a subdirectory for each such 12027module, in the directory containing the module. For 12028example, if modules contains 12029 12030@example 12031ampermod &first-dir 12032@end example 12033 12034@noindent 12035then a checkout will create an @code{ampermod} directory 12036which contains a directory called @code{first-dir}, 12037which in turns contains all the directories and files 12038which live there. For example, the command 12039 12040@example 12041$ cvs co ampermod 12042@end example 12043 12044@noindent 12045will create the following files: 12046 12047@example 12048ampermod/first-dir/file1 12049ampermod/first-dir/file2 12050ampermod/first-dir/sdir/sfile 12051@end example 12052 12053There is one quirk/bug: the messages that @sc{cvs} 12054prints omit the @file{ampermod}, and thus do not 12055correctly display the location to which it is checking 12056out the files: 12057 12058@example 12059$ cvs co ampermod 12060cvs checkout: Updating first-dir 12061U first-dir/file1 12062U first-dir/file2 12063cvs checkout: Updating first-dir/sdir 12064U first-dir/sdir/sfile 12065$ 12066@end example 12067 12068Do not rely on this buggy behavior; it may get fixed in 12069a future release of @sc{cvs}. 12070 12071@c FIXCVS: What happens if regular and & modules are 12072@c combined, as in "ampermodule first-dir &second-dir"? 12073@c When I tried it, it seemed to just ignore the 12074@c "first-dir". I think perhaps it should be an error 12075@c (but this needs further investigation). 12076@c In addition to discussing what each one does, we 12077@c should put in a few words about why you would use one or 12078@c the other in various situations. 12079 12080@node Excluding directories 12081@appendixsubsec Excluding directories 12082@cindex Excluding directories, in modules file 12083@cindex !, in modules file 12084 12085An alias module may exclude particular directories from 12086other modules by using an exclamation mark (@samp{!}) 12087before the name of each directory to be excluded. 12088 12089For example, if the modules file contains: 12090 12091@example 12092exmodule -a !first-dir/sdir first-dir 12093@end example 12094 12095@noindent 12096then checking out the module @samp{exmodule} will check 12097out everything in @samp{first-dir} except any files in 12098the subdirectory @samp{first-dir/sdir}. 12099@c Note that the "!first-dir/sdir" sometimes must be listed 12100@c before "first-dir". That seems like a probable bug, in which 12101@c case perhaps it should be fixed (to allow either 12102@c order) rather than documented. See modules4 in testsuite. 12103 12104@node Module options 12105@appendixsubsec Module options 12106@cindex Options, in modules file 12107 12108Either regular modules or ampersand modules can contain 12109options, which supply additional information concerning 12110the module. 12111 12112@table @code 12113@cindex -d, in modules file 12114@item -d @var{name} 12115Name the working directory something other than the 12116module name. 12117@c FIXME: Needs a bunch of examples, analogous to the 12118@c examples for alias, regular, and ampersand modules 12119@c which show where the files go without -d. 12120 12121@cindex Export program 12122@cindex -e, in modules file 12123@item -e @var{prog} 12124Specify a program @var{prog} to run whenever files in a 12125module are exported. @var{prog} runs with a single 12126argument, the module name. 12127@c FIXME: Is it run on server? client? 12128 12129@cindex Checkout program 12130@cindex -o, in modules file 12131@item -o @var{prog} 12132Specify a program @var{prog} to run whenever files in a 12133module are checked out. @var{prog} runs with a single 12134argument, the module name. See @ref{Module program options} for 12135information on how @var{prog} is called. 12136@c FIXME: Is it run on server? client? 12137 12138@cindex Status of a module 12139@cindex Module status 12140@cindex -s, in modules file 12141@item -s @var{status} 12142Assign a status to the module. When the module file is 12143printed with @samp{cvs checkout -s} the modules are 12144sorted according to primarily module status, and 12145secondarily according to the module name. This option 12146has no other meaning. You can use this option for 12147several things besides status: for instance, list the 12148person that is responsible for this module. 12149 12150@cindex Tag program 12151@cindex -t, in modules file 12152@item -t @var{prog} 12153Specify a program @var{prog} to run whenever files in a 12154module are tagged with @code{rtag}. @var{prog} runs 12155with two arguments: the module name and the symbolic 12156tag specified to @code{rtag}. It is not run 12157when @code{tag} is executed. Generally you will find 12158that taginfo is a better solution (@pxref{user-defined logging}). 12159@c FIXME: Is it run on server? client? 12160@c Problems with -t include: 12161@c * It is run after the tag not before 12162@c * It doesn't get passed all the information that 12163@c taginfo does ("mov", &c). 12164@c * It only is run for rtag, not tag. 12165@end table 12166 12167You should also see @pxref{Module program options} about how the 12168``program options'' programs are run. 12169 12170@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12171 12172@node Module program options 12173@appendixsubsec How the modules file ``program options'' programs are run 12174@cindex Modules file program options 12175@cindex -t, in modules file 12176@cindex -o, in modules file 12177@cindex -e, in modules file 12178 12179@noindent 12180For checkout, rtag, and export, the program is server-based, and as such the 12181following applies:- 12182 12183If using remote access methods (pserver, ext, etc.), 12184@sc{cvs} will execute this program on the server from a temporary 12185directory. The path is searched for this program. 12186 12187If using ``local access'' (on a local or remote NFS file system, i.e. 12188repository set just to a path), 12189the program will be executed from the newly checked-out tree, if 12190found there, or alternatively searched for in the path if not. 12191 12192The programs are all run after the operation has effectively 12193completed. 12194 12195 12196@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12197@node Wrappers 12198@appendixsec The cvswrappers file 12199@cindex cvswrappers (admin file) 12200@cindex CVSWRAPPERS, environment variable 12201@cindex Wrappers 12202 12203@c FIXME: need some better way of separating this out 12204@c by functionality. -m is 12205@c one feature, and -k is a another. And this discussion 12206@c should be better motivated (e.g. start with the 12207@c problems, then explain how the feature solves it). 12208 12209Wrappers refers to a @sc{cvs} feature which lets you 12210control certain settings based on the name of the file 12211which is being operated on. The settings are @samp{-k} 12212for binary files, and @samp{-m} for nonmergeable text 12213files. 12214 12215The @samp{-m} option 12216specifies the merge methodology that should be used when 12217a non-binary file is updated. @code{MERGE} means the usual 12218@sc{cvs} behavior: try to merge the files. @code{COPY} 12219means that @code{cvs update} will refuse to merge 12220files, as it also does for files specified as binary 12221with @samp{-kb} (but if the file is specified as 12222binary, there is no need to specify @samp{-m 'COPY'}). 12223@sc{cvs} will provide the user with the 12224two versions of the files, and require the user using 12225mechanisms outside @sc{cvs}, to insert any necessary 12226changes. 12227 12228@strong{WARNING: do not use @code{COPY} with 12229@sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will 12230copy one version of your file over the other, wiping 12231out the previous contents.} 12232@c Ordinarily we don't document the behavior of old 12233@c versions. But this one is so dangerous, I think we 12234@c must. I almost renamed it to -m 'NOMERGE' so we 12235@c could say "never use -m 'COPY'". 12236The @samp{-m} wrapper option only affects behavior when 12237merging is done on update; it does not affect how files 12238are stored. See @ref{Binary files}, for more on 12239binary files. 12240 12241The basic format of the file @file{cvswrappers} is: 12242 12243@c FIXME: @example is all wrong for this. Use @deffn or 12244@c something more sensible. 12245@example 12246wildcard [option value][option value]... 12247 12248where option is one of 12249-m update methodology value: MERGE or COPY 12250-k keyword expansion value: expansion mode 12251 12252and value is a single-quote delimited value. 12253@end example 12254 12255 12256@c FIXME: We don't document -W or point to where it is 12257@c documented. Or .cvswrappers. 12258For example, the following command imports a 12259directory, treating files whose name ends in 12260@samp{.exe} as binary: 12261 12262@example 12263cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag 12264@end example 12265 12266@c Another good example, would be storing files 12267@c (e.g. binary files) compressed in the repository. 12268@c :::::::::::::::::: 12269@c cvswrappers 12270@c :::::::::::::::::: 12271@c *.t12 -m 'COPY' 12272@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY' 12273@c 12274@c :::::::::::::::::: 12275@c gunzipcp 12276@c :::::::::::::::::: 12277@c : 12278@c [ -f $1 ] || exit 1 12279@c zcat $1 > /tmp/.#$1.$$ 12280@c mv /tmp/.#$1.$$ $1 12281@c 12282@c :::::::::::::::::: 12283@c gzipcp 12284@c :::::::::::::::::: 12285@c : 12286@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"` 12287@c if [ ! -d $DIRNAME ] ; then 12288@c DIRNAME=`echo $1 | sed -e "s|.*/||g"` 12289@c fi 12290@c gzip -c $DIRNAME > $2 12291@c One catch--"cvs diff" will not invoke the wrappers 12292@c (probably a CVS bug, although I haven't thought it out). 12293 12294@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12295@node commit files 12296@appendixsec The commit support files 12297@cindex Committing, administrative support files 12298 12299The @samp{-i} flag in the @file{modules} file can be 12300used to run a certain program whenever files are 12301committed (@pxref{modules}). The files described in 12302this section provide other, more flexible, ways to run 12303programs whenever something is committed. 12304 12305There are three kind of programs that can be run on 12306commit. They are specified in files in the repository, 12307as described below. The following table summarizes the 12308file names and the purpose of the corresponding 12309programs. 12310 12311@table @file 12312@item commitinfo 12313The program is responsible for checking that the commit 12314is allowed. If it exits with a non-zero exit status 12315the commit will be aborted. 12316 12317@item verifymsg 12318The specified program is used to evaluate the log message, 12319and possibly verify that it contains all required 12320fields. This is most useful in combination with the 12321@file{rcsinfo} file, which can hold a log message 12322template (@pxref{rcsinfo}). 12323 12324@item editinfo 12325The specified program is used to edit the log message, 12326and possibly verify that it contains all required 12327fields. This is most useful in combination with the 12328@file{rcsinfo} file, which can hold a log message 12329template (@pxref{rcsinfo}). (obsolete) 12330 12331@item loginfo 12332The specified program is called when the commit is 12333complete. It receives the log message and some 12334additional information and can store the log message in 12335a file, or mail it to appropriate persons, or maybe 12336post it to a local newsgroup, or@dots{} Your 12337imagination is the limit! 12338@end table 12339 12340@menu 12341* syntax:: The common syntax 12342* commitinfo:: Pre-commit checking 12343* verifymsg:: How are log messages evaluated? 12344* editinfo:: Specifying how log messages are created 12345 (obsolete) 12346* loginfo:: Where should log messages be sent? 12347@end menu 12348 12349@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12350@node syntax 12351@appendixsubsec The common syntax 12352@cindex Info files (syntax) 12353@cindex Syntax of info files 12354@cindex Common syntax of info files 12355 12356@c FIXME: having this so totally separate from the 12357@c Variables node is rather bogus. 12358 12359The administrative files such as @file{commitinfo}, 12360@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc., 12361all have a common format. The purpose of the files are 12362described later on. The common syntax is described 12363here. 12364 12365@cindex Regular expression syntax 12366Each line contains the following: 12367@itemize @bullet 12368@item 12369@c Say anything about DEFAULT and ALL? Right now we 12370@c leave that to the description of each file (and in fact 12371@c the practice is inconsistent which is really annoying). 12372A regular expression. This is a basic regular 12373expression in the syntax used by GNU emacs. 12374@c FIXME: What we probably should be saying is "POSIX Basic 12375@c Regular Expression with the following extensions (`\(' 12376@c `\|' '+' etc)" 12377@c rather than define it with reference to emacs. 12378@c The reference to emacs is not strictly speaking 12379@c true, as we don't support \=, \s, or \S. Also it isn't 12380@c clear we should document and/or promise to continue to 12381@c support all the obscure emacs extensions like \<. 12382@c Also need to better cite (or include) full 12383@c documentation for the syntax. 12384@c Also see comment in configure.in about what happens to the 12385@c syntax if we pick up a system-supplied regexp matcher. 12386 12387@item 12388A whitespace separator---one or more spaces and/or tabs. 12389 12390@item 12391A file name or command-line template. 12392@end itemize 12393 12394@noindent 12395Blank lines are ignored. Lines that start with the 12396character @samp{#} are treated as comments. Long lines 12397unfortunately can @emph{not} be broken in two parts in 12398any way. 12399 12400The first regular expression that matches the current 12401directory name in the repository is used. The rest of the line 12402is used as a file name or command-line as appropriate. 12403 12404@c FIXME: need an example. In particular, show what 12405@c the regular expression is matched against (one 12406@c ordinarily clueful person got confused about whether it 12407@c includes the filename--"directory name" above should be 12408@c unambiguous but there is nothing like an example to 12409@c confirm people's understanding of this sort of thing). 12410 12411@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12412@node commitinfo 12413@appendixsubsec Commitinfo 12414@cindex @file{commitinfo} 12415@cindex Commits, precommit verification of 12416@cindex Precommit checking 12417 12418The @file{commitinfo} file defines programs to execute 12419whenever @samp{cvs commit} is about to execute. These 12420programs are used for pre-commit checking to verify 12421that the modified, added and removed files are really 12422ready to be committed. This could be used, for 12423instance, to verify that the changed files conform to 12424to your site's standards for coding practice. 12425 12426As mentioned earlier, each line in the 12427@file{commitinfo} file consists of a regular expression 12428and a command-line template. The template can include 12429a program name and any number of arguments you wish to 12430supply to it. The full path to the current source 12431repository is appended to the template, followed by the 12432file names of any files involved in the commit (added, 12433removed, and modified files). 12434 12435@cindex Exit status, of commitinfo 12436The first line with a regular expression matching the 12437directory within the repository will be used. If the 12438command returns a non-zero exit status the commit will 12439be aborted. 12440@c FIXME: need example(s) of what "directory within the 12441@c repository" means. 12442 12443@cindex DEFAULT in commitinfo 12444If the repository name does not match any of the 12445regular expressions in this file, the @samp{DEFAULT} 12446line is used, if it is specified. 12447 12448@cindex ALL in commitinfo 12449All occurrences of the name @samp{ALL} appearing as a 12450regular expression are used in addition to the first 12451matching regular expression or the name @samp{DEFAULT}. 12452 12453@cindex @file{commitinfo}, working directory 12454@cindex @file{commitinfo}, command environment 12455The command will be run in the root of the workspace 12456containing the new versions of any files the user would like 12457to modify (commit), @emph{or in a copy of the workspace on 12458the server (@pxref{Remote repositories})}. If a file is 12459being removed, there will be no copy of the file under the 12460current directory. If a file is being added, there will be 12461no corresponding archive file in the repository unless the 12462file is being resurrected. 12463 12464Note that both the repository directory and the corresponding 12465Attic (@pxref{Attic}) directory may need to be checked to 12466locate the archive file corresponding to any given file being 12467committed. Much of the information about the specific commit 12468request being made, including the destination branch, commit 12469message, and command line options specified, is not available 12470to the command. 12471 12472@c FIXME: should discuss using commitinfo to control 12473@c who has checkin access to what (e.g. Joe can check into 12474@c directories a, b, and c, and Mary can check into 12475@c directories b, c, and d--note this case cannot be 12476@c conveniently handled with unix groups). Of course, 12477@c adding a new set of features to CVS might be a more 12478@c natural way to fix this problem than telling people to 12479@c use commitinfo. 12480@c FIXME: Should make some reference, especially in 12481@c the context of controlling who has access, to the fact 12482@c that commitinfo can be circumvented. Perhaps 12483@c mention SETXID (but has it been carefully examined 12484@c for holes?). This fits in with the discussion of 12485@c general CVS security in "Password authentication 12486@c security" (the bit which is not pserver-specific). 12487 12488@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12489@node verifymsg 12490@appendixsubsec Verifying log messages 12491@cindex @file{verifymsg} (admin file) 12492@cindex Log message, verifying 12493 12494Once you have entered a log message, you can evaluate 12495that message to check for specific content, such as 12496a bug ID. Use the @file{verifymsg} file to 12497specify a program that is used to verify the log message. 12498This program could be a simple script that checks 12499that the entered message contains the required fields. 12500 12501The @file{verifymsg} file is often most useful together 12502with the @file{rcsinfo} file, which can be used to 12503specify a log message template. 12504 12505Each line in the @file{verifymsg} file consists of a 12506regular expression and a command-line template. The 12507template must include a program name, and can include 12508any number of arguments. The full path to the current 12509log message template file is appended to the template. 12510 12511One thing that should be noted is that the @samp{ALL} 12512keyword is not supported. If more than one matching 12513line is found, the first one is used. This can be 12514useful for specifying a default verification script in a 12515directory, and then overriding it in a subdirectory. 12516 12517@cindex DEFAULT in @file{verifymsg} 12518If the repository name does not match any of the 12519regular expressions in this file, the @samp{DEFAULT} 12520line is used, if it is specified. 12521 12522@cindex Exit status, of @file{verifymsg} 12523If the verification script exits with a non-zero exit status, 12524the commit is aborted. 12525 12526@cindex @file{verifymsg}, changing the log message 12527In the default configuration, CVS allows the 12528verification script to change the log message. This is 12529controlled via the RereadLogAfterVerify CVSROOT/config 12530option. 12531 12532When @samp{RereadLogAfterVerify=always} or 12533@samp{RereadLogAfterVerify=stat}, the log message will 12534either always be reread after the verification script 12535is run or reread only if the log message file status 12536has changed. 12537 12538@xref{config}, for more on CVSROOT/config options. 12539 12540It is NOT a good idea for a @file{verifymsg} script to 12541interact directly with the user in the various 12542client/server methods. For the @code{pserver} method, 12543there is no protocol support for communicating between 12544@file{verifymsg} and the client on the remote end. For the 12545@code{ext} and @code{server} methods, it is possible 12546for CVS to become confused by the characters going 12547along the same channel as the CVS protocol 12548messages. See @ref{Remote repositories}, for more 12549information on client/server setups. In addition, at the time 12550the @file{verifymsg} script runs, the CVS 12551server has locks in place in the repository. If control is 12552returned to the user here then other users may be stuck waiting 12553for access to the repository. 12554 12555This option can be useful if you find yourself using an 12556rcstemplate that needs to be modified to remove empty 12557elements or to fill in default values. It can also be 12558useful if the rcstemplate has changed in the repository 12559and the CVS/Template was not updated, but is able to be 12560adapted to the new format by the verification script 12561that is run by @file{verifymsg}. 12562 12563An example of an update might be to change all 12564occurrences of 'BugId:' to be 'DefectId:' (which can be 12565useful if the rcstemplate has recently been changed and 12566there are still checked-out user trees with cached 12567copies in the CVS/Template file of the older version). 12568 12569Another example of an update might be to delete a line 12570that contains 'BugID: none' from the log message after 12571validation of that value as being allowed is made. 12572 12573The following is a little silly example of a 12574@file{verifymsg} file, together with the corresponding 12575@file{rcsinfo} file, the log message template and an 12576verification script. We begin with the log message template. 12577We want to always record a bug-id number on the first 12578line of the log message. The rest of log message is 12579free text. The following template is found in the file 12580@file{/usr/cvssupport/tc.template}. 12581 12582@example 12583BugId: 12584@end example 12585 12586The script @file{/usr/cvssupport/bugid.verify} is used to 12587evaluate the log message. 12588 12589@example 12590#!/bin/sh 12591# 12592# bugid.verify filename 12593# 12594# Verify that the log message contains a valid bugid 12595# on the first line. 12596# 12597if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then 12598 exit 0 12599elif head -1 < $1 | grep '^BugId:[ ]*none$' > /dev/null; then 12600 # It is okay to allow commits with 'BugId: none', 12601 # but do not put that text into the real log message. 12602 grep -v '^BugId:[ ]*none$' > $1.rewrite 12603 mv $1.rewrite $1 12604 exit 0 12605else 12606 echo "No BugId found." 12607 exit 1 12608fi 12609@end example 12610 12611The @file{verifymsg} file contains this line: 12612 12613@example 12614^tc /usr/cvssupport/bugid.verify 12615@end example 12616 12617The @file{rcsinfo} file contains this line: 12618 12619@example 12620^tc /usr/cvssupport/tc.template 12621@end example 12622 12623The @file{config} file contains this line: 12624 12625@example 12626RereadLogAfterVerify=always 12627@end example 12628 12629 12630 12631@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12632@node editinfo 12633@appendixsubsec Editinfo 12634@cindex editinfo (admin file) 12635@cindex Editor, specifying per module 12636@cindex Per-module editor 12637@cindex Log messages, editing 12638 12639@strong{Note: The @file{editinfo} feature has been 12640rendered obsolete. To set a default editor for log 12641messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables 12642(@pxref{Environment variables}) or the @samp{-e} global 12643option (@pxref{Global options}). See @ref{verifymsg}, 12644for information on the use of the @file{verifymsg} 12645feature for evaluating log messages.} 12646 12647If you want to make sure that all log messages look the 12648same way, you can use the @file{editinfo} file to 12649specify a program that is used to edit the log message. 12650This program could be a custom-made editor that always 12651enforces a certain style of the log message, or maybe a 12652simple shell script that calls an editor, and checks 12653that the entered message contains the required fields. 12654 12655If no matching line is found in the @file{editinfo} 12656file, the editor specified in the environment variable 12657@code{$CVSEDITOR} is used instead. If that variable is 12658not set, then the environment variable @code{$EDITOR} 12659is used instead. If that variable is not 12660set a default will be used. See @ref{Committing your changes}. 12661 12662The @file{editinfo} file is often most useful together 12663with the @file{rcsinfo} file, which can be used to 12664specify a log message template. 12665 12666Each line in the @file{editinfo} file consists of a 12667regular expression and a command-line template. The 12668template must include a program name, and can include 12669any number of arguments. The full path to the current 12670log message template file is appended to the template. 12671 12672One thing that should be noted is that the @samp{ALL} 12673keyword is not supported. If more than one matching 12674line is found, the first one is used. This can be 12675useful for specifying a default edit script in a 12676module, and then overriding it in a subdirectory. 12677 12678@cindex DEFAULT in editinfo 12679If the repository name does not match any of the 12680regular expressions in this file, the @samp{DEFAULT} 12681line is used, if it is specified. 12682 12683If the edit script exits with a non-zero exit status, 12684the commit is aborted. 12685 12686Note: when @sc{cvs} is accessing a remote repository, 12687or when the @samp{-m} or @samp{-F} options to @code{cvs 12688commit} are used, @file{editinfo} will not be consulted. 12689There is no good workaround for this; use 12690@file{verifymsg} instead. 12691 12692@menu 12693* editinfo example:: Editinfo example 12694@end menu 12695 12696@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12697@node editinfo example 12698@appendixsubsubsec Editinfo example 12699 12700The following is a little silly example of a 12701@file{editinfo} file, together with the corresponding 12702@file{rcsinfo} file, the log message template and an 12703editor script. We begin with the log message template. 12704We want to always record a bug-id number on the first 12705line of the log message. The rest of log message is 12706free text. The following template is found in the file 12707@file{/usr/cvssupport/tc.template}. 12708 12709@example 12710BugId: 12711@end example 12712 12713The script @file{/usr/cvssupport/bugid.edit} is used to 12714edit the log message. 12715 12716@example 12717#!/bin/sh 12718# 12719# bugid.edit filename 12720# 12721# Call $EDITOR on FILENAME, and verify that the 12722# resulting file contains a valid bugid on the first 12723# line. 12724if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi 12725if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi 12726$CVSEDITOR $1 12727until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1 12728do echo -n "No BugId found. Edit again? ([y]/n)" 12729 read ans 12730 case $@{ans@} in 12731 n*) exit 1;; 12732 esac 12733 $CVSEDITOR $1 12734done 12735@end example 12736 12737The @file{editinfo} file contains this line: 12738 12739@example 12740^tc /usr/cvssupport/bugid.edit 12741@end example 12742 12743The @file{rcsinfo} file contains this line: 12744 12745@example 12746^tc /usr/cvssupport/tc.template 12747@end example 12748 12749@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12750@node loginfo 12751@appendixsubsec Loginfo 12752@cindex loginfo (admin file) 12753@cindex Storing log messages 12754@cindex Mailing log messages 12755@cindex Distributing log messages 12756@cindex Log messages 12757 12758@c "cvs commit" is not quite right. What we 12759@c mean is "when the repository gets changed" which 12760@c also includes "cvs import" and "cvs add" on a directory. 12761The @file{loginfo} file is used to control where 12762@samp{cvs commit} log information is sent. The first 12763entry on a line is a regular expression which is tested 12764against the directory that the change is being made to, 12765relative to the @code{$CVSROOT}. If a match is found, then 12766the remainder of the line is a filter program that 12767should expect log information on its standard input. 12768 12769If the repository name does not match any of the 12770regular expressions in this file, the @samp{DEFAULT} 12771line is used, if it is specified. 12772 12773All occurrences of the name @samp{ALL} appearing as a 12774regular expression are used in addition to the first 12775matching regular expression or @samp{DEFAULT}. 12776 12777The first matching regular expression is used. 12778 12779@xref{commit files}, for a description of the syntax of 12780the @file{loginfo} file. 12781 12782The user may specify a format string as 12783part of the filter. The string is composed of a 12784@samp{%} followed by a space, or followed by a single 12785format character, or followed by a set of format 12786characters surrounded by @samp{@{} and @samp{@}} as 12787separators. The format characters are: 12788 12789@table @t 12790@item s 12791file name 12792@item V 12793old version number (pre-checkin) 12794@item v 12795new version number (post-checkin) 12796@end table 12797 12798All other characters that appear in a format string 12799expand to an empty field (commas separating fields are 12800still provided). 12801 12802For example, some valid format strings are @samp{%}, 12803@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}. 12804 12805The output will be a space separated string of tokens enclosed in 12806quotation marks (@t{"}). 12807Any embedded dollar signs (@t{$}), backticks (@t{`}), 12808backslashes (@t{\}), or quotation marks will be preceded 12809by a backslash (this allows the shell to correctly parse it 12810as a single string, regardless of the characters it contains). 12811For backwards compatibility, the first 12812token will be the repository subdirectory. The rest of the 12813tokens will be comma-delimited lists of the information 12814requested in the format string. For example, if 12815@samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%@{sVv@}} 12816is the format string, and three files (@t{ChangeLog}, 12817@t{Makefile}, @t{foo.c}) were modified, the output 12818might be: 12819 12820@example 12821"yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13" 12822@end example 12823 12824As another example, @samp{%@{@}} means that only the 12825name of the repository will be generated. 12826 12827Note: when @sc{cvs} is accessing a remote repository, 12828@file{loginfo} will be run on the @emph{remote} 12829(i.e., server) side, not the client side (@pxref{Remote 12830repositories}). 12831 12832@menu 12833* loginfo example:: Loginfo example 12834* Keeping a checked out copy:: Updating a tree on every checkin 12835@end menu 12836 12837@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12838@node loginfo example 12839@appendixsubsubsec Loginfo example 12840 12841The following @file{loginfo} file, together with the 12842tiny shell-script below, appends all log messages 12843to the file @file{$CVSROOT/CVSROOT/commitlog}, 12844and any commits to the administrative files (inside 12845the @file{CVSROOT} directory) are also logged in 12846@file{/usr/adm/cvsroot-log}. 12847Commits to the @file{prog1} directory are mailed to @t{ceder}. 12848 12849@c FIXME: is it a CVS feature or bug that only the 12850@c first matching line is used? It is documented 12851@c above, but is it useful? For example, if we wanted 12852@c to run both "cvs-log" and "Mail" for the CVSROOT 12853@c directory, it is kind of awkward if 12854@c only the first matching line is used. 12855@example 12856ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER 12857^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log 12858^prog1 Mail -s %s ceder 12859@end example 12860 12861The shell-script @file{/usr/local/bin/cvs-log} looks 12862like this: 12863 12864@example 12865#!/bin/sh 12866(echo "------------------------------------------------------"; 12867 echo -n $2" "; 12868 date; 12869 echo; 12870 cat) >> $1 12871@end example 12872 12873@node Keeping a checked out copy 12874@appendixsubsubsec Keeping a checked out copy 12875 12876@c What other index entries? It seems like 12877@c people might want to use a lot of different 12878@c words for this functionality. 12879@cindex Keeping a checked out copy 12880@cindex Checked out copy, keeping 12881@cindex Web pages, maintaining with CVS 12882 12883It is often useful to maintain a directory tree which 12884contains files which correspond to the latest version 12885in the repository. For example, other developers might 12886want to refer to the latest sources without having to 12887check them out, or you might be maintaining a web site 12888with @sc{cvs} and want every checkin to cause the files 12889used by the web server to be updated. 12890@c Can we offer more details on the web example? Or 12891@c point the user at how to figure it out? This text 12892@c strikes me as sufficient for someone who already has 12893@c some idea of what we mean but not enough for the naive 12894@c user/sysadmin to understand it and set it up. 12895 12896The way to do this is by having loginfo invoke 12897@code{cvs update}. Doing so in the naive way will 12898cause a problem with locks, so the @code{cvs update} 12899must be run in the background. 12900@c Should we try to describe the problem with locks? 12901@c It seems like a digression for someone who just 12902@c wants to know how to make it work. 12903@c Another choice which might work for a single file 12904@c is to use "cvs -n update -p" which doesn't take 12905@c out locks (I think) but I don't see many advantages 12906@c of that and we might as well document something which 12907@c works for multiple files. 12908Here is an example for unix (this should all be on one line): 12909 12910@example 12911^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs; 12912 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1 12913@end example 12914 12915This will cause checkins to repository directories 12916starting with @code{cyclic-pages} to update the checked 12917out tree in @file{/u/www/local-docs}. 12918@c More info on some of the details? The "sleep 2" is 12919@c so if we are lucky the lock will be gone by the time 12920@c we start and we can wait 2 seconds instead of 30. 12921 12922@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12923@node rcsinfo 12924@appendixsec Rcsinfo 12925@cindex rcsinfo (admin file) 12926@cindex Form for log message 12927@cindex Log message template 12928@cindex Template for log message 12929 12930The @file{rcsinfo} file can be used to specify a form to 12931edit when filling out the commit log. The 12932@file{rcsinfo} file has a syntax similar to the 12933@file{verifymsg}, @file{commitinfo} and @file{loginfo} 12934files. @xref{syntax}. Unlike the other files the second 12935part is @emph{not} a command-line template. Instead, 12936the part after the regular expression should be a full pathname to 12937a file containing the log message template. 12938 12939If the repository name does not match any of the 12940regular expressions in this file, the @samp{DEFAULT} 12941line is used, if it is specified. 12942 12943All occurrences of the name @samp{ALL} appearing as a 12944regular expression are used in addition to the first 12945matching regular expression or @samp{DEFAULT}. 12946 12947@c FIXME: should be offering advice, somewhere around 12948@c here, about where to put the template file. The 12949@c verifymsg example uses /usr/cvssupport but doesn't 12950@c say anything about what that directory is for or 12951@c whether it is hardwired into CVS or who creates 12952@c it or anything. In particular we should say 12953@c how to version control the template file. A 12954@c probably better answer than the /usr/cvssupport 12955@c stuff is to use checkoutlist (with xref to the 12956@c checkoutlist doc). 12957@c Also I am starting to see a connection between 12958@c this and the Keeping a checked out copy node. 12959@c Probably want to say something about that. 12960The log message template will be used as a default log 12961message. If you specify a log message with @samp{cvs 12962commit -m @var{message}} or @samp{cvs commit -f 12963@var{file}} that log message will override the 12964template. 12965 12966@xref{verifymsg}, for an example @file{rcsinfo} 12967file. 12968 12969When @sc{cvs} is accessing a remote repository, 12970the contents of @file{rcsinfo} at the time a directory 12971is first checked out will specify a template. This 12972template will be updated on all @samp{cvs update} 12973commands. It will also be added to new directories 12974added with a @samp{cvs add new-directry} command. 12975In versions of @sc{cvs} prior to version 1.12, the 12976@file{CVS/Template} file was not updated. If the 12977@sc{cvs} server is at version 1.12 or higher an older 12978client may be used and the @file{CVS/Template} will 12979be updated from the server. 12980 12981@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 12982@node cvsignore 12983@appendixsec Ignoring files via cvsignore 12984@cindex cvsignore (admin file), global 12985@cindex Global cvsignore 12986@cindex Ignoring files 12987@c -- This chapter should maybe be moved to the 12988@c tutorial part of the manual? 12989 12990There are certain file names that frequently occur 12991inside your working copy, but that you don't want to 12992put under @sc{cvs} control. Examples are all the object 12993files that you get while you compile your sources. 12994Normally, when you run @samp{cvs update}, it prints a 12995line for each file it encounters that it doesn't know 12996about (@pxref{update output}). 12997 12998@sc{cvs} has a list of files (or sh(1) file name patterns) 12999that it should ignore while running @code{update}, 13000@code{import} and @code{release}. 13001@c -- Are those the only three commands affected? 13002This list is constructed in the following way. 13003 13004@itemize @bullet 13005@item 13006The list is initialized to include certain file name 13007patterns: names associated with @sc{cvs} 13008administration, or with other common source control 13009systems; common names for patch files, object files, 13010archive files, and editor backup files; and other names 13011that are usually artifacts of assorted utilities. 13012Currently, the default list of ignored file name 13013patterns is: 13014 13015@cindex Ignored files 13016@cindex Automatically ignored files 13017@example 13018 RCS SCCS CVS CVS.adm 13019 RCSLOG cvslog.* 13020 tags TAGS 13021 .make.state .nse_depinfo 13022 *~ #* .#* ,* _$* *$ 13023 *.old *.bak *.BAK *.orig *.rej .del-* 13024 *.a *.olb *.o *.obj *.so *.exe 13025 *.Z *.elc *.ln 13026 core 13027@end example 13028 13029@item 13030The per-repository list in 13031@file{$CVSROOT/CVSROOT/cvsignore} is appended to 13032the list, if that file exists. 13033 13034@item 13035The per-user list in @file{.cvsignore} in your home 13036directory is appended to the list, if it exists. 13037 13038@item 13039Any entries in the environment variable 13040@code{$CVSIGNORE} is appended to the list. 13041 13042@item 13043Any @samp{-I} options given to @sc{cvs} is appended. 13044 13045@item 13046As @sc{cvs} traverses through your directories, the contents 13047of any @file{.cvsignore} will be appended to the list. 13048The patterns found in @file{.cvsignore} are only valid 13049for the directory that contains them, not for 13050any sub-directories. 13051@end itemize 13052 13053In any of the 5 places listed above, a single 13054exclamation mark (@samp{!}) clears the ignore list. 13055This can be used if you want to store any file which 13056normally is ignored by @sc{cvs}. 13057 13058Specifying @samp{-I !} to @code{cvs import} will import 13059everything, which is generally what you want to do if 13060you are importing files from a pristine distribution or 13061any other source which is known to not contain any 13062extraneous files. However, looking at the rules above 13063you will see there is a fly in the ointment; if the 13064distribution contains any @file{.cvsignore} files, then 13065the patterns from those files will be processed even if 13066@samp{-I !} is specified. The only workaround is to 13067remove the @file{.cvsignore} files in order to do the 13068import. Because this is awkward, in the future 13069@samp{-I !} might be modified to override 13070@file{.cvsignore} files in each directory. 13071 13072Note that the syntax of the ignore files consists of a 13073series of lines, each of which contains a space 13074separated list of filenames. This offers no clean way 13075to specify filenames which contain spaces, but you can 13076use a workaround like @file{foo?bar} to match a file 13077named @file{foo bar} (it also matches @file{fooxbar} 13078and the like). Also note that there is currently no 13079way to specify comments. 13080@c FIXCVS? I don't _like_ this syntax at all, but 13081@c changing it raises all the usual compatibility 13082@c issues and I'm also not sure what to change it to. 13083 13084@node checkoutlist 13085@appendixsec The checkoutlist file 13086@cindex checkoutlist 13087 13088It may be helpful to use @sc{cvs} to maintain your own 13089files in the @file{CVSROOT} directory. For example, 13090suppose that you have a script @file{logcommit.pl} 13091which you run by including the following line in the 13092@file{commitinfo} administrative file: 13093 13094@example 13095ALL $CVSROOT/CVSROOT/logcommit.pl 13096@end example 13097 13098To maintain @file{logcommit.pl} with @sc{cvs} you would 13099add the following line to the @file{checkoutlist} 13100administrative file: 13101 13102@example 13103logcommit.pl 13104@end example 13105 13106The format of @file{checkoutlist} is one line for each 13107file that you want to maintain using @sc{cvs}, giving 13108the name of the file. 13109 13110After setting up @file{checkoutlist} in this fashion, 13111the files listed there will function just like 13112@sc{cvs}'s built-in administrative files. For example, 13113when checking in one of the files you should get a 13114message such as: 13115 13116@example 13117cvs commit: Rebuilding administrative file database 13118@end example 13119 13120@noindent 13121and the checked out copy in the @file{CVSROOT} 13122directory should be updated. 13123 13124Note that listing @file{passwd} (@pxref{Password 13125authentication server}) in @file{checkoutlist} is not 13126recommended for security reasons. 13127 13128For information about keeping a checkout out copy in a 13129more general context than the one provided by 13130@file{checkoutlist}, see @ref{Keeping a checked out 13131copy}. 13132 13133@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 13134@node history file 13135@appendixsec The history file 13136@cindex History file 13137@cindex Log information, saving 13138 13139The file @file{$CVSROOT/CVSROOT/history} is used 13140to log information for the @code{history} command 13141(@pxref{history}). This file must be created to turn 13142on logging. This is done automatically if the 13143@code{cvs init} command is used to set up the 13144repository (@pxref{Creating a repository}). 13145 13146The file format of the @file{history} file is 13147documented only in comments in the @sc{cvs} source 13148code, but generally programs should use the @code{cvs 13149history} command to access it anyway, in case the 13150format changes with future releases of @sc{cvs}. 13151 13152@node Variables 13153@appendixsec Expansions in administrative files 13154@cindex Internal variables 13155@cindex Variables 13156 13157Sometimes in writing an administrative file, you might 13158want the file to be able to know various things based 13159on environment @sc{cvs} is running in. There are 13160several mechanisms to do that. 13161 13162To find the home directory of the user running @sc{cvs} 13163(from the @code{HOME} environment variable), use 13164@samp{~} followed by @samp{/} or the end of the line. 13165Likewise for the home directory of @var{user}, use 13166@samp{~@var{user}}. These variables are expanded on 13167the server machine, and don't get any reasonable 13168expansion if pserver (@pxref{Password authenticated}) 13169is in use; therefore user variables (see below) may be 13170a better choice to customize behavior based on the user 13171running @sc{cvs}. 13172@c Based on these limitations, should we deprecate ~? 13173@c What is it good for? Are people using it? 13174 13175One may want to know about various pieces of 13176information internal to @sc{cvs}. A @sc{cvs} internal 13177variable has the syntax @code{$@{@var{variable}@}}, 13178where @var{variable} starts with a letter and consists 13179of alphanumeric characters and @samp{_}. If the 13180character following @var{variable} is a 13181non-alphanumeric character other than @samp{_}, the 13182@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} 13183internal variables are: 13184 13185@table @code 13186@item CVSROOT 13187@cindex CVSROOT, internal variable 13188This is the absolute path to the current @sc{cvs} root directory. 13189@xref{Repository}, for a description of the various 13190ways to specify this, but note that the internal 13191variable contains just the directory and not any 13192of the access method information. 13193 13194@item RCSBIN 13195@cindex RCSBIN, internal variable 13196In @sc{cvs} 1.9.18 and older, this specified the 13197directory where @sc{cvs} was looking for @sc{rcs} 13198programs. Because @sc{cvs} no longer runs @sc{rcs} 13199programs, specifying this internal variable is now an 13200error. 13201 13202@item CVSEDITOR 13203@cindex CVSEDITOR, internal variable 13204@itemx EDITOR 13205@cindex EDITOR, internal variable 13206@itemx VISUAL 13207@cindex VISUAL, internal variable 13208These all expand to the same value, which is the editor 13209that @sc{cvs} is using. @xref{Global options}, for how 13210to specify this. 13211 13212@item USER 13213@cindex USER, internal variable 13214Username of the user running @sc{cvs} (on the @sc{cvs} 13215server machine). 13216When using pserver, this is the user specified in the repository 13217specification which need not be the same as the username the 13218server is running as (@pxref{Password authentication server}). 13219Do not confuse this with the environment variable of the same name. 13220@end table 13221 13222If you want to pass a value to the administrative files 13223which the user who is running @sc{cvs} can specify, 13224use a user variable. 13225@cindex User variables 13226To expand a user variable, the 13227administrative file contains 13228@code{$@{=@var{variable}@}}. To set a user variable, 13229specify the global option @samp{-s} to @sc{cvs}, with 13230argument @code{@var{variable}=@var{value}}. It may be 13231particularly useful to specify this option via 13232@file{.cvsrc} (@pxref{~/.cvsrc}). 13233 13234For example, if you want the administrative file to 13235refer to a test directory you might create a user 13236variable @code{TESTDIR}. Then if @sc{cvs} is invoked 13237as 13238 13239@example 13240cvs -s TESTDIR=/work/local/tests 13241@end example 13242 13243@noindent 13244and the 13245administrative file contains @code{sh 13246$@{=TESTDIR@}/runtests}, then that string is expanded 13247to @code{sh /work/local/tests/runtests}. 13248 13249All other strings containing @samp{$} are reserved; 13250there is no way to quote a @samp{$} character so that 13251@samp{$} represents itself. 13252 13253Environment variables passed to administrative files are: 13254 13255@table @code 13256@cindex environment variables, passed to administrative files 13257 13258@item CVS_USER 13259@cindex CVS_USER, environment variable 13260The @sc{cvs}-specific username provided by the user, if it 13261can be provided (currently just for the pserver access 13262method), and to the empty string otherwise. (@code{CVS_USER} 13263and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd} 13264is used to map @sc{cvs} usernames to system usernames.) 13265 13266@item LOGNAME 13267@cindex LOGNAME, environment variable 13268The username of the system user. 13269 13270@item USER 13271@cindex USER, environment variable 13272Same as @code{LOGNAME}. 13273Do not confuse this with the internal variable of the same name. 13274@end table 13275 13276@node config 13277@appendixsec The CVSROOT/config configuration file 13278 13279@cindex config, in CVSROOT 13280@cindex CVSROOT/config 13281 13282The administrative file @file{config} contains various 13283miscellaneous settings which affect the behavior of 13284@sc{cvs}. The syntax is slightly different from the 13285other administrative files. Variables are not 13286expanded. Lines which start with @samp{#} are 13287considered comments. 13288@c FIXME: where do we define comments for the other 13289@c administrative files. 13290Other lines consist of a keyword, @samp{=}, and a 13291value. Note that this syntax is very strict. 13292Extraneous spaces or tabs are not permitted. 13293@c See comments in parseinfo.c:parse_config for more 13294@c discussion of this strictness. 13295 13296Currently defined keywords are: 13297 13298@table @code 13299@cindex RCSBIN, in CVSROOT/config 13300@item RCSBIN=@var{bindir} 13301For @sc{cvs} 1.9.12 through 1.9.18, this setting told 13302@sc{cvs} to look for @sc{rcs} programs in the 13303@var{bindir} directory. Current versions of @sc{cvs} 13304do not run @sc{rcs} programs; for compatibility this 13305setting is accepted, but it does nothing. 13306 13307@cindex SystemAuth, in CVSROOT/config 13308@item SystemAuth=@var{value} 13309If @var{value} is @samp{yes}, then pserver should check 13310for users in the system's user database if not found in 13311@file{CVSROOT/passwd}. If it is @samp{no}, then all 13312pserver users must exist in @file{CVSROOT/passwd}. 13313The default is @samp{yes}. For more on pserver, see 13314@ref{Password authenticated}. 13315 13316 13317@cindex TopLevelAdmin, in CVSROOT/config 13318@item TopLevelAdmin=@var{value} 13319Modify the @samp{checkout} command to create a 13320@samp{CVS} directory at the top level of the new 13321working directory, in addition to @samp{CVS} 13322directories created within checked-out directories. 13323The default value is @samp{no}. 13324 13325This option is useful if you find yourself performing 13326many commands at the top level of your working 13327directory, rather than in one of the checked out 13328subdirectories. The @file{CVS} directory created there 13329will mean you don't have to specify @code{CVSROOT} for 13330each command. It also provides a place for the 13331@file{CVS/Template} file (@pxref{Working directory 13332storage}). 13333 13334@cindex LockDir, in CVSROOT/config 13335@item LockDir=@var{directory} 13336Put @sc{cvs} lock files in @var{directory} rather than 13337directly in the repository. This is useful if you want 13338to let users read from the repository while giving them 13339write access only to @var{directory}, not to the 13340repository. 13341It can also be used to put the locks on a very fast 13342in-memory file system to speed up locking and unlocking 13343the repository. 13344You need to create @var{directory}, but 13345@sc{cvs} will create subdirectories of @var{directory} as it 13346needs them. For information on @sc{cvs} locks, see 13347@ref{Concurrency}. 13348 13349@c Mention this in Compatibility section? 13350Before enabling the LockDir option, make sure that you 13351have tracked down and removed any copies of @sc{cvs} 1.9 or 13352older. Such versions neither support LockDir, nor will 13353give an error indicating that they don't support it. 13354The result, if this is allowed to happen, is that some 13355@sc{cvs} users will put the locks one place, and others will 13356put them another place, and therefore the repository 13357could become corrupted. @sc{cvs} 1.10 does not support 13358LockDir but it will print a warning if run on a 13359repository with LockDir enabled. 13360 13361@cindex LogHistory, in CVSROOT/config 13362@item LogHistory=@var{value} 13363Control what is logged to the @file{CVSROOT/history} file (@pxref{history}). 13364Default of @samp{TOEFWUCGMAR} (or simply @samp{all}) will log 13365all transactions. Any subset of the default is 13366legal. (For example, to only log transactions that modify the 13367@file{*,v} files, use @samp{LogHistory=TMAR}.) 13368 13369@cindex RereadLogAfterVerify, in CVSROOT/config 13370@cindex @file{verifymsg}, changing the log message 13371@item RereadLogAfterVerify=@var{value} 13372Modify the @samp{commit} command such that CVS will reread the 13373log message after running the program specified by @file{verifymsg}. 13374@var{value} may be one of @samp{yes} or @samp{always}, indicating that 13375the log message should always be reread; @samp{no} 13376or @samp{never}, indicating that it should never be 13377reread; or @var{value} may be @samp{stat}, indicating 13378that the file should be checked with the filesystem 13379@samp{stat()} function to see if it has changed (see warning below) 13380before rereading. The default value is @samp{always}. 13381 13382@strong{Note: the `stat' mode can cause CVS to pause for up to 13383one extra second per directory committed. This can be less IO and 13384CPU intensive but is not recommended for use with large repositories} 13385 13386@xref{verifymsg}, for more information on how verifymsg 13387may be used. 13388 13389@cindex UserAdminOptions, in CVSROOT/config 13390@item UserAdminOptions=@var{value} 13391Control what options will be allowed with the @code{cvs admin} 13392command (@pxref{admin}) for users not in the @code{cvsadmin} group. 13393The @var{value} string is a list of single character options 13394which should be allowed. If a user who is not a member of the 13395@code{cvsadmin} group tries to execute any @code{cvs admin} 13396option which is not listed they will will receive an error message 13397reporting that the option is restricted. 13398 13399If no @code{cvsadmin} group exists on the server, @sc{cvs} will 13400ignore the @code{UserAdminOptions} keyword (@pxref{admin}). 13401 13402When not specified, @code{UserAdminOptions} defaults to 13403@samp{k}. In other words, it defaults to allowing 13404users outside of the @code{cvsadmin} group to use the 13405@code{cvs admin} command only to change the default keyword 13406expansion mode for files. 13407 13408As an example, to restrict users not in the @code{cvsadmin} 13409group to using @code{cvs admin} to change the default keyword 13410substitution mode, lock revisions, unlock revisions, and 13411replace the log message, use @samp{UserAdminOptions=klum}. 13412@end table 13413 13414@c --------------------------------------------------------------------- 13415@node Environment variables 13416@appendix All environment variables which affect CVS 13417@cindex Environment variables 13418@cindex Reference manual for variables 13419 13420This is a complete list of all environment variables 13421that affect @sc{cvs}. 13422 13423@table @code 13424@cindex CVSIGNORE, environment variable 13425@item $CVSIGNORE 13426A whitespace-separated list of file name patterns that 13427@sc{cvs} should ignore. @xref{cvsignore}. 13428 13429@cindex CVSWRAPPERS, environment variable 13430@item $CVSWRAPPERS 13431A whitespace-separated list of file name patterns that 13432@sc{cvs} should treat as wrappers. @xref{Wrappers}. 13433 13434@cindex CVSREAD, environment variable 13435@cindex Read-only files, and CVSREAD 13436@item $CVSREAD 13437If this is set, @code{checkout} and @code{update} will 13438try hard to make the files in your working directory 13439read-only. When this is not set, the default behavior 13440is to permit modification of your working files. 13441 13442@cindex CVSREADONLYFS, environment variable 13443@item $CVSREADONLYFS 13444Turns on read-only repository mode. This allows one to 13445check out from a read-only repository, such as within 13446an anoncvs server, or from a CDROM repository. 13447 13448It has the same effect as if the @samp{-R} command-line 13449option is used. This can also allow the use of 13450read-only NFS repositories. 13451 13452@item $CVSUMASK 13453Controls permissions of files in the repository. See 13454@ref{File permissions}. 13455 13456@item $CVSROOT 13457Should contain the full pathname to the root of the @sc{cvs} 13458source repository (where the @sc{rcs} files are 13459kept). This information must be available to @sc{cvs} for 13460most commands to execute; if @code{$CVSROOT} is not set, 13461or if you wish to override it for one invocation, you 13462can supply it on the command line: @samp{cvs -d cvsroot 13463cvs_command@dots{}} Once you have checked out a working 13464directory, @sc{cvs} stores the appropriate root (in 13465the file @file{CVS/Root}), so normally you only need to 13466worry about this when initially checking out a working 13467directory. 13468 13469@item $CVSEDITOR 13470@cindex CVSEDITOR, environment variable 13471@itemx $EDITOR 13472@cindex EDITOR, environment variable 13473@itemx $VISUAL 13474@cindex VISUAL, environment variable 13475Specifies the program to use for recording log messages 13476during commit. @code{$CVSEDITOR} overrides 13477@code{$EDITOR}, which overrides @code{$VISUAL}. 13478See @ref{Committing your changes} for more or 13479@ref{Global options} for alternative ways of specifying a 13480log editor. 13481 13482@cindex PATH, environment variable 13483@item $PATH 13484If @code{$RCSBIN} is not set, and no path is compiled 13485into @sc{cvs}, it will use @code{$PATH} to try to find all 13486programs it uses. 13487 13488@cindex HOME, environment variable 13489@item $HOME 13490@cindex HOMEPATH, environment variable 13491@item $HOMEPATH 13492@cindex HOMEDRIVE, environment variable 13493@item $HOMEDRIVE 13494Used to locate the directory where the @file{.cvsrc} 13495file, and other such files, are searched. On Unix, @sc{cvs} 13496just checks for @code{HOME}. On Windows NT, the system will 13497set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH}, 13498for example to @file{\joe}. On Windows 95, you'll 13499probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself. 13500@c We are being vague about whether HOME works on 13501@c Windows; see long comment in windows-NT/filesubr.c. 13502 13503@cindex CVS_RSH, environment variable 13504@item $CVS_RSH 13505Specifies the external program which @sc{cvs} connects with, 13506when @code{:ext:} access method is specified. 13507@pxref{Connecting via rsh}. 13508 13509@item $CVS_SERVER 13510Used in client-server mode when accessing a remote 13511repository using @sc{rsh}. It specifies the name of 13512the program to start on the server side (and any 13513necessary arguments) when accessing a remote repository 13514using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods. 13515The default value for @code{:ext:} and @code{:server:} is @code{cvs}; 13516the default value for @code{:fork:} is the name used to run the client. 13517@pxref{Connecting via rsh} 13518 13519@item $CVS_PASSFILE 13520Used in client-server mode when accessing the @code{cvs 13521login server}. Default value is @file{$HOME/.cvspass}. 13522@pxref{Password authentication client} 13523 13524@item $CVS_CLIENT_PORT 13525Used in client-server mode to set the port to use when accessing the server 13526via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol 13527if the port is not specified in the CVSROOT. 13528@pxref{Remote repositories} 13529 13530@cindex CVS_RCMD_PORT, environment variable 13531@item $CVS_RCMD_PORT 13532Used in client-server mode. If set, specifies the port 13533number to be used when accessing the @sc{rcmd} demon on 13534the server side. (Currently not used for Unix clients). 13535 13536@cindex CVS_CLIENT_LOG, environment variable 13537@item $CVS_CLIENT_LOG 13538Used for debugging only in client-server 13539mode. If set, everything sent to the server is logged 13540into @file{@code{$CVS_CLIENT_LOG}.in} and everything 13541sent from the server is logged into 13542@file{@code{$CVS_CLIENT_LOG}.out}. 13543 13544@cindex CVS_SERVER_SLEEP, environment variable 13545@item $CVS_SERVER_SLEEP 13546Used only for debugging the server side in 13547client-server mode. If set, delays the start of the 13548server child process the specified amount of 13549seconds so that you can attach to it with a debugger. 13550 13551@cindex CVS_IGNORE_REMOTE_ROOT, environment variable 13552@item $CVS_IGNORE_REMOTE_ROOT 13553For @sc{cvs} 1.10 and older, setting this variable 13554prevents @sc{cvs} from overwriting the @file{CVS/Root} 13555file when the @samp{-d} global option is specified. 13556Later versions of @sc{cvs} do not rewrite 13557@file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no 13558effect. 13559 13560@cindex CVS_LOCAL_BRANCH_NUM, environment variable 13561@item $CVS_LOCAL_BRANCH_NUM 13562Setting this variable allows some control over the 13563branch number that is assigned. This is specifically to 13564support the local commit feature of CVSup. If one sets 13565@code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches 13566the local repository, the revision numbers will look 13567like 1.66.1000.xx. There is almost a dead-set certainty 13568that there will be no conflicts with version numbers. 13569 13570@cindex COMSPEC, environment variable 13571@item $COMSPEC 13572Used under OS/2 only. It specifies the name of the 13573command interpreter and defaults to @sc{cmd.exe}. 13574 13575@cindex TMPDIR, environment variable 13576@item $TMPDIR 13577@cindex TMP, environment variable 13578@itemx $TMP 13579@cindex TEMP, environment variable 13580@itemx $TEMP 13581@cindex Temporary files, location of 13582@c This is quite nuts. We don't talk about tempnam 13583@c or mkstemp which we sometimes use. The discussion 13584@c of "Global options" is semi-incoherent. 13585@c I'm not even sure those are the only inaccuracies. 13586@c Furthermore, the conventions are 13587@c pretty crazy and they should be simplified. 13588Directory in which temporary files are located. 13589The @sc{cvs} server uses 13590@code{TMPDIR}. @xref{Global options}, for a 13591description of how to specify this. 13592Some parts of @sc{cvs} will always use @file{/tmp} (via 13593the @code{tmpnam} function provided by the system). 13594 13595On Windows NT, @code{TMP} is used (via the @code{_tempnam} 13596function provided by the system). 13597 13598The @code{patch} program which is used by the @sc{cvs} 13599client uses @code{TMPDIR}, and if it is not set, uses 13600@file{/tmp} (at least with GNU patch 2.1). Note that 13601if your server and client are both running @sc{cvs} 136021.9.10 or later, @sc{cvs} will not invoke an external 13603@code{patch} program. 13604 13605@cindex CVS_PID, environment variable 13606@item $CVS_PID 13607This is the process identification (aka pid) number of 13608the @sc{cvs} process. It is often useful in the 13609programs and/or scripts specified by the 13610@file{commitinfo}, @file{verifymsg}, @file{loginfo} 13611files. 13612@end table 13613 13614@node Compatibility 13615@appendix Compatibility between CVS Versions 13616 13617@cindex CVS, versions of 13618@cindex Versions, of CVS 13619@cindex Compatibility, between CVS versions 13620@c We don't mention versions older than CVS 1.3 13621@c on the theory that it would clutter it up for the vast 13622@c majority of people, who don't have anything that old. 13623@c 13624The repository format is compatible going back to 13625@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if 13626you have copies of @sc{cvs} 1.6 or older and you want 13627to use the optional developer communication features. 13628@c If you "cvs rm" and commit using 1.3, then you'll 13629@c want to run "rcs -sdead <file,v>" on each of the 13630@c files in the Attic if you then want 1.5 and 13631@c later to recognize those files as dead (I think the 13632@c symptom if this is not done is that files reappear 13633@c in joins). (Wait: the above will work but really to 13634@c be strictly correct we should suggest checking 13635@c in a new revision rather than just changing the 13636@c state of the head revision, shouldn't we?). 13637@c The old convert.sh script was for this, but it never 13638@c did get updated to reflect use of the RCS "dead" 13639@c state. 13640@c Note: this is tricky to document without confusing 13641@c people--need to carefully say what CVS version we 13642@c are talking about and keep in mind the distinction 13643@c between a 13644@c repository created with 1.3 and on which one now 13645@c uses 1.5+, and a repository on which one wants to 13646@c use both versions side by side (e.g. during a 13647@c transition period). 13648@c Wait, can't CVS just detect the case in which a file 13649@c is in the Attic but the head revision is not dead? 13650@c Not sure whether this should produce a warning or 13651@c something, and probably needs further thought, but 13652@c it would appear that the situation can be detected. 13653@c 13654@c We might want to separate out the 1.3 compatibility 13655@c section (for repository & working directory) from the 13656@c rest--that might help avoid confusing people who 13657@c are upgrading (for example) from 1.6 to 1.8. 13658@c 13659@c A minor incompatibility is if a current version of CVS 13660@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will 13661@c see this as if there is no tag. Seems to me this is 13662@c too obscure to mention. 13663 13664The working directory format is compatible going back 13665to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3 13666and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on 13667a working directory checked out with @sc{cvs} 1.3, 13668@sc{cvs} will convert it, but to go back to @sc{cvs} 136691.3 you need to check out a new working directory with 13670@sc{cvs} 1.3. 13671 13672The remote protocol is interoperable going back to @sc{cvs} 1.5, but no 13673further (1.5 was the first official release with the remote protocol, 13674but some older versions might still be floating around). In many 13675cases you need to upgrade both the client and the server to take 13676advantage of new features and bugfixes, however. 13677 13678@c Perhaps should be saying something here about the 13679@c "D" lines in Entries (written by CVS 1.9; 1.8 and 13680@c older don't use them). These are supposed to be 13681@c compatible in both directions, but I'm not sure 13682@c they quite are 100%. One common gripe is if you 13683@c "rm -r" a directory and 1.9 gets confused, as it 13684@c still sees it in Entries. That one is fixed in 13685@c (say) 1.9.6. Someone else reported problems with 13686@c starting with a directory which was checked out with 13687@c an old version, and then using a new version, and 13688@c some "D" lines appeared, but not for every 13689@c directory, causing some directories to be skipped. 13690@c They weren't sure how to reproduce this, though. 13691 13692@c --------------------------------------------------------------------- 13693@node Troubleshooting 13694@appendix Troubleshooting 13695 13696If you are having trouble with @sc{cvs}, this appendix 13697may help. If there is a particular error message which 13698you are seeing, then you can look up the message 13699alphabetically. If not, you can look through the 13700section on other problems to see if your problem is 13701mentioned there. 13702 13703@menu 13704* Error messages:: Partial list of CVS errors 13705* Connection:: Trouble making a connection to a CVS server 13706* Other problems:: Problems not readily listed by error message 13707@end menu 13708 13709 13710@node Error messages 13711@appendixsec Partial list of error messages 13712 13713Here is a partial list of error messages that you may 13714see from @sc{cvs}. It is not a complete list---@sc{cvs} 13715is capable of printing many, many error messages, often 13716with parts of them supplied by the operating system, 13717but the intention is to list the common and/or 13718potentially confusing error messages. 13719 13720The messages are alphabetical, but introductory text 13721such as @samp{cvs update: } is not considered in 13722ordering them. 13723 13724In some cases the list includes messages printed by old 13725versions of @sc{cvs} (partly because users may not be 13726sure which version of @sc{cvs} they are using at any 13727particular moment). 13728@c If we want to start retiring messages, perhaps we 13729@c should pick a cutoff version (for example, no more 13730@c messages which are specific to versions before 1.9) 13731@c and then move the old messages to an "old messages" 13732@c node rather than deleting them completely. 13733 13734@table @code 13735@c FIXME: What is the correct way to format a multiline 13736@c error message here? Maybe @table is the wrong 13737@c choice? Texinfo gurus? 13738@item @var{file}:@var{line}: Assertion '@var{text}' failed 13739The exact format of this message may vary depending on 13740your system. It indicates a bug in @sc{cvs}, which can 13741be handled as described in @ref{BUGS}. 13742 13743@item cvs @var{command}: authorization failed: server @var{host} rejected access 13744This is a generic response when trying to connect to a 13745pserver server which chooses not to provide a 13746specific reason for denying authorization. Check that 13747the username and password specified are correct and 13748that the @code{CVSROOT} specified is allowed by @samp{--allow-root} 13749in @file{inetd.conf}. See @ref{Password authenticated}. 13750 13751@item cvs @var{command}: conflict: removed @var{file} was modified by second party 13752This message indicates that you removed a file, and 13753someone else modified it. To resolve the conflict, 13754first run @samp{cvs add @var{file}}. If desired, look 13755at the other party's modification to decide whether you 13756still want to remove it. If you don't want to remove 13757it, stop here. If you do want to remove it, proceed 13758with @samp{cvs remove @var{file}} and commit your 13759removal. 13760@c Tests conflicts2-142b* in sanity.sh test for this. 13761 13762@item cannot change permissions on temporary directory 13763@example 13764Operation not permitted 13765@end example 13766This message has been happening in a non-reproducible, 13767occasional way when we run the client/server testsuite, 13768both on Red Hat Linux 3.0.3 and 4.1. We haven't been 13769able to figure out what causes it, nor is it known 13770whether it is specific to linux (or even to this 13771particular machine!). If the problem does occur on 13772other unices, @samp{Operation not permitted} would be 13773likely to read @samp{Not owner} or whatever the system 13774in question uses for the unix @code{EPERM} error. If 13775you have any information to add, please let us know as 13776described in @ref{BUGS}. If you experience this error 13777while using @sc{cvs}, retrying the operation which 13778produced it should work fine. 13779@c This has been seen in a variety of tests, including 13780@c multibranch-2, multibranch-5, and basic1-24-rm-rm, 13781@c so it doesn't seem particularly specific to any one 13782@c test. 13783 13784@item cvs [server aborted]: Cannot check out files into the repository itself 13785The obvious cause for this message (especially for 13786non-client/server @sc{cvs}) is that the @sc{cvs} root 13787is, for example, @file{/usr/local/cvsroot} and you try 13788to check out files when you are in a subdirectory, such 13789as @file{/usr/local/cvsroot/test}. However, there is a 13790more subtle cause, which is that the temporary 13791directory on the server is set to a subdirectory of the 13792root (which is also not allowed). If this is the 13793problem, set the temporary directory to somewhere else, 13794for example @file{/var/tmp}; see @code{TMPDIR} in 13795@ref{Environment variables}, for how to set the 13796temporary directory. 13797 13798@item cannot commit files as 'root' 13799See @samp{'root' is not allowed to commit files}. 13800 13801@c For one example see basica-1a10 in the testsuite 13802@c For another example, "cvs co ." on NT; see comment 13803@c at windows-NT/filesubr.c (expand_wild). 13804@c For another example, "cvs co foo/bar" where foo exists. 13805@item cannot open CVS/Entries for reading: No such file or directory 13806This generally indicates a @sc{cvs} internal error, and 13807can be handled as with other @sc{cvs} bugs 13808(@pxref{BUGS}). Usually there is a workaround---the 13809exact nature of which would depend on the situation but 13810which hopefully could be figured out. 13811 13812@c This is more obscure than it might sound; it only 13813@c happens if you run "cvs init" from a directory which 13814@c contains a CVS/Root file at the start. 13815@item cvs [init aborted]: cannot open CVS/Root: No such file or directory 13816This message is harmless. Provided it is not 13817accompanied by other errors, the operation has 13818completed successfully. This message should not occur 13819with current versions of @sc{cvs}, but it is documented 13820here for the benefit of @sc{cvs} 1.9 and older. 13821 13822@item cvs server: cannot open /root/.cvsignore: Permission denied 13823@itemx cvs [server aborted]: can't chdir(/root): Permission denied 13824See @ref{Connection}. 13825 13826@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument 13827This message has been reported as intermittently 13828happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is 13829unknown; if you know more about what causes it, let us 13830know as described in @ref{BUGS}. 13831 13832@item cvs [@var{command} aborted]: cannot start server via rcmd 13833This, unfortunately, is a rather nonspecific error 13834message which @sc{cvs} 1.9 will print if you are 13835running the @sc{cvs} client and it is having trouble 13836connecting to the server. Current versions of @sc{cvs} 13837should print a much more specific error message. If 13838you get this message when you didn't mean to run the 13839client at all, you probably forgot to specify 13840@code{:local:}, as described in @ref{Repository}. 13841 13842@item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ 13843@sc{cvs} 1.9 and older will print this message 13844when trying to check in a binary file if 13845@sc{rcs} is not correctly installed. Re-read the 13846instructions that came with your @sc{rcs} distribution 13847and the @sc{install} file in the @sc{cvs} 13848distribution. Alternately, upgrade to a current 13849version of @sc{cvs}, which checks in files itself 13850rather than via @sc{rcs}. 13851 13852@item cvs checkout: could not check out @var{file} 13853With @sc{cvs} 1.9, this can mean that the @code{co} program 13854(part of @sc{rcs}) returned a failure. It should be 13855preceded by another error message, however it has been 13856observed without another error message and the cause is 13857not well-understood. With the current version of @sc{cvs}, 13858which does not run @code{co}, if this message occurs 13859without another error message, it is definitely a @sc{cvs} 13860bug (@pxref{BUGS}). 13861@c My current suspicion is that the RCS in the rcs (not 13862@c cvs/winnt/rcs57nt.zip) directory on the _Practical_ 13863@c CD is bad (remains to be confirmed). 13864@c There is also a report of something which looks 13865@c very similar on SGI, Irix 5.2, so I dunno. 13866 13867@item cvs [login aborted]: could not find out home directory 13868This means that you need to set the environment 13869variables that @sc{cvs} uses to locate your home directory. 13870See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in 13871@ref{Environment variables}. 13872 13873@item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory 13874@sc{cvs} 1.9 and older will print this message if there was 13875a problem finding the @code{rcsmerge} program. Make 13876sure that it is in your @code{PATH}, or upgrade to a 13877current version of @sc{cvs}, which does not require 13878an external @code{rcsmerge} program. 13879 13880@item cvs [update aborted]: could not patch @var{file}: No such file or directory 13881This means that there was a problem finding the 13882@code{patch} program. Make sure that it is in your 13883@code{PATH}. Note that despite appearances the message 13884is @emph{not} referring to whether it can find @var{file}. 13885If both the client and the server are running a current 13886version of @sc{cvs}, then there is no need for an 13887external patch program and you should not see this 13888message. But if either client or server is running 13889@sc{cvs} 1.9, then you need @code{patch}. 13890 13891@item cvs update: could not patch @var{file}; will refetch 13892This means that for whatever reason the client was 13893unable to apply a patch that the server sent. The 13894message is nothing to be concerned about, because 13895inability to apply the patch only slows things down and 13896has no effect on what @sc{cvs} does. 13897@c xref to update output. Or File status? 13898@c Or some place else that 13899@c explains this whole "patch"/P/Needs Patch thing? 13900 13901@item dying gasps from @var{server} unexpected 13902There is a known bug in the server for @sc{cvs} 1.9.18 13903and older which can cause this. For me, this was 13904reproducible if I used the @samp{-t} global option. It 13905was fixed by Andy Piper's 14 Nov 1997 change to 13906src/filesubr.c, if anyone is curious. 13907If you see the message, 13908you probably can just retry the operation which failed, 13909or if you have discovered information concerning its 13910cause, please let us know as described in @ref{BUGS}. 13911 13912@item end of file from server (consult above messages if any) 13913The most common cause for this message is if you are 13914using an external @code{rsh} program and it exited with 13915an error. In this case the @code{rsh} program should 13916have printed a message, which will appear before the 13917above message. For more information on setting up a 13918@sc{cvs} client and server, see @ref{Remote repositories}. 13919 13920@item cvs [update aborted]: EOF in key in RCS file @var{file},v 13921@itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v 13922This means that there is a syntax error in the given 13923@sc{rcs} file. Note that this might be true even if @sc{rcs} can 13924read the file OK; @sc{cvs} does more error checking of 13925errors in the RCS file. That is why you may see this 13926message when upgrading from @sc{cvs} 1.9 to @sc{cvs} 139271.10. The likely cause for the original corruption is 13928hardware, the operating system, or the like. Of 13929course, if you find a case in which @sc{cvs} seems to 13930corrupting the file, by all means report it, 13931(@pxref{BUGS}). 13932There are quite a few variations of this error message, 13933depending on exactly where in the @sc{rcs} file @sc{cvs} 13934finds the syntax error. 13935 13936@cindex mkmodules 13937@item cvs commit: Executing 'mkmodules' 13938This means that your repository is set up for a version 13939of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs} 139401.8 or later, the above message will be preceded by 13941 13942@example 13943cvs commit: Rebuilding administrative file database 13944@end example 13945 13946If you see both messages, the database is being rebuilt 13947twice, which is unnecessary but harmless. If you wish 13948to avoid the duplication, and you have no versions of 13949@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules} 13950every place it appears in your @code{modules} 13951file. For more information on the @code{modules} file, 13952see @ref{modules}. 13953 13954@c This message comes from "co", and I believe is 13955@c possible only with older versions of CVS which call 13956@c co. The problem with being able to create the bogus 13957@c RCS file still exists, though (and I think maybe 13958@c there is a different symptom(s) now). 13959@c FIXME: Would be nice to have a more exact wording 13960@c for this message. 13961@item missing author 13962Typically this can happen if you created an RCS file 13963with your username set to empty. @sc{cvs} will, bogusly, 13964create an illegal RCS file with no value for the author 13965field. The solution is to make sure your username is 13966set to a non-empty value and re-create the RCS file. 13967@c "make sure your username is set" is complicated in 13968@c and of itself, as there are the environment 13969@c variables the system login name, &c, and it depends 13970@c on the version of CVS. 13971 13972@item cvs [checkout aborted]: no such tag @var{tag} 13973This message means that @sc{cvs} isn't familiar with 13974the tag @var{tag}. Usually this means that you have 13975mistyped a tag name; however there are (relatively 13976obscure) cases in which @sc{cvs} will require you to 13977@c Search sanity.sh for "no such tag" to see some of 13978@c the relatively obscure cases. 13979try a few other @sc{cvs} commands involving that tag, 13980before you find one which will cause @sc{cvs} to update 13981the @file{val-tags} file; see discussion of val-tags in 13982@ref{File permissions}. You only need to worry about 13983this once for a given tag; when a tag is listed in 13984@file{val-tags}, it stays there. Note that using 13985@samp{-f} to not require tag matches does not override 13986this check; see @ref{Common options}. 13987 13988@item *PANIC* administration files missing 13989This typically means that there is a directory named 13990@sc{cvs} but it does not contain the administrative files 13991which @sc{cvs} puts in a CVS directory. If the problem is 13992that you created a CVS directory via some mechanism 13993other than @sc{cvs}, then the answer is simple, use a name 13994other than @sc{cvs}. If not, it indicates a @sc{cvs} bug 13995(@pxref{BUGS}). 13996 13997@item rcs error: Unknown option: -x,v/ 13998This message will be followed by a usage message for 13999@sc{rcs}. It means that you have an old version of 14000@sc{rcs} (probably supplied with your operating 14001system), as well as an old version of @sc{cvs}. 14002@sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and 14003later; current versions of @sc{cvs} do not run @sc{rcs} programs. 14004@c For more information on installing @sc{cvs}, see 14005@c (FIXME: where? it depends on whether you are 14006@c getting binaries or sources or what). 14007@c The message can also say "ci error" or something 14008@c instead of "rcs error", I suspect. 14009 14010@item cvs [server aborted]: received broken pipe signal 14011This message seems to be caused by a hard-to-track-down 14012bug in @sc{cvs} or the systems it runs on (we don't 14013know---we haven't tracked it down yet!). It seems to 14014happen only after a @sc{cvs} command has completed, and 14015you should be able to just ignore the message. 14016However, if you have discovered information concerning its 14017cause, please let us know as described in @ref{BUGS}. 14018 14019@item 'root' is not allowed to commit files 14020When committing a permanent change, @sc{cvs} makes a log entry of 14021who committed the change. If you are committing the change logged 14022in as "root" (not under "su" or other root-priv giving program), 14023@sc{cvs} cannot determine who is actually making the change. 14024As such, by default, @sc{cvs} disallows changes to be committed by users 14025logged in as "root". (You can disable this option by passing the 14026@code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}. 14027On some systems this means editing the appropriate @file{config.h} file 14028before building @sc{cvs}.) 14029 14030@item Too many arguments! 14031This message is typically printed by the @file{log.pl} 14032script which is in the @file{contrib} directory in the 14033@sc{cvs} source distribution. In some versions of 14034@sc{cvs}, @file{log.pl} has been part of the default 14035@sc{cvs} installation. The @file{log.pl} script gets 14036called from the @file{loginfo} administrative file. 14037Check that the arguments passed in @file{loginfo} match 14038what your version of @file{log.pl} expects. In 14039particular, the @file{log.pl} from @sc{cvs} 1.3 and 14040older expects the logfile as an argument whereas the 14041@file{log.pl} from @sc{cvs} 1.5 and newer expects the 14042logfile to be specified with a @samp{-f} option. Of 14043course, if you don't need @file{log.pl} you can just 14044comment it out of @file{loginfo}. 14045 14046@item cvs [update aborted]: unexpected EOF reading @var{file},v 14047See @samp{EOF in key in RCS file}. 14048 14049@item cvs [login aborted]: unrecognized auth response from @var{server} 14050This message typically means that the server is not set 14051up properly. For example, if @file{inetd.conf} points 14052to a nonexistent cvs executable. To debug it further, 14053find the log file which inetd writes 14054(@file{/var/log/messages} or whatever inetd uses on 14055your system). For details, see @ref{Connection}, and 14056@ref{Password authentication server}. 14057 14058@item cvs commit: Up-to-date check failed for `@var{file}' 14059This means that someone else has committed a change to 14060that file since the last time that you did a @code{cvs 14061update}. So before proceeding with your @code{cvs 14062commit} you need to @code{cvs update}. @sc{cvs} will merge 14063the changes that you made and the changes that the 14064other person made. If it does not detect any conflicts 14065it will report @samp{M @var{file}} and you are ready 14066to @code{cvs commit}. If it detects conflicts it will 14067print a message saying so, will report @samp{C @var{file}}, 14068and you need to manually resolve the 14069conflict. For more details on this process see 14070@ref{Conflicts example}. 14071 14072@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3 14073@example 14074Only one of [exEX3] allowed 14075@end example 14076This indicates a problem with the installation of 14077@code{diff3} and @code{rcsmerge}. Specifically 14078@code{rcsmerge} was compiled to look for GNU diff3, but 14079it is finding unix diff3 instead. The exact text of 14080the message will vary depending on the system. The 14081simplest solution is to upgrade to a current version of 14082@sc{cvs}, which does not rely on external 14083@code{rcsmerge} or @code{diff3} programs. 14084 14085@item warning: unrecognized response `@var{text}' from cvs server 14086If @var{text} contains a valid response (such as 14087@samp{ok}) followed by an extra carriage return 14088character (on many systems this will cause the second 14089part of the message to overwrite the first part), then 14090it probably means that you are using the @samp{:ext:} 14091access method with a version of rsh, such as most 14092non-unix rsh versions, which does not by default 14093provide a transparent data stream. In such cases you 14094probably want to try @samp{:server:} instead of 14095@samp{:ext:}. If @var{text} is something else, this 14096may signify a problem with your @sc{cvs} server. 14097Double-check your installation against the instructions 14098for setting up the @sc{cvs} server. 14099@c FIXCVS: should be printing CR as \r or \015 or some 14100@c such, probably. 14101 14102@item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory} 14103This is a normal message, not an error. See 14104@ref{Concurrency}, for more details. 14105 14106@item cvs commit: warning: editor session failed 14107@cindex Exit status, of editor 14108This means that the editor which @sc{cvs} is using exits with a nonzero 14109exit status. Some versions of vi will do this even when there was not 14110a problem editing the file. If so, point the 14111@code{CVSEDITOR} environment variable to a small script 14112such as: 14113 14114@example 14115#!/bin/sh 14116vi $* 14117exit 0 14118@end example 14119 14120@c "warning: foo was lost" and "no longer pertinent" (both normal). 14121@c Would be nice to write these up--they are 14122@c potentially confusing for the new user. 14123@end table 14124 14125@node Connection 14126@appendixsec Trouble making a connection to a CVS server 14127 14128This section concerns what to do if you are having 14129trouble making a connection to a @sc{cvs} server. If 14130you are running the @sc{cvs} command line client 14131running on Windows, first upgrade the client to 14132@sc{cvs} 1.9.12 or later. The error reporting in 14133earlier versions provided much less information about 14134what the problem was. If the client is non-Windows, 14135@sc{cvs} 1.9 should be fine. 14136 14137If the error messages are not sufficient to track down 14138the problem, the next steps depend largely on which 14139access method you are using. 14140 14141@table @code 14142@cindex :ext:, troubleshooting 14143@item :ext: 14144Try running the rsh program from the command line. For 14145example: "rsh servername cvs -v" should print @sc{cvs} 14146version information. If this doesn't work, you need to 14147fix it before you can worry about @sc{cvs} problems. 14148 14149@cindex :server:, troubleshooting 14150@item :server: 14151You don't need a command line rsh program to use this 14152access method, but if you have an rsh program around, 14153it may be useful as a debugging tool. Follow the 14154directions given for :ext:. 14155 14156@cindex :pserver:, troubleshooting 14157@item :pserver: 14158Errors along the lines of "connection refused" typically indicate 14159that inetd isn't even listening for connections on port 2401 14160whereas errors like "connection reset by peer", 14161"received broken pipe signal", "recv() from server: EOF", 14162or "end of file from server" 14163typically indicate that inetd is listening for 14164connections but is unable to start @sc{cvs} (this is frequently 14165caused by having an incorrect path in @file{inetd.conf} 14166or by firewall software rejecting the connection). 14167"unrecognized auth response" errors are caused by a bad command 14168line in @file{inetd.conf}, typically an invalid option or forgetting 14169to put the @samp{pserver} command at the end of the line. 14170Another less common problem is invisible control characters that 14171your editor "helpfully" added without you noticing. 14172 14173One good debugging tool is to "telnet servername 141742401". After connecting, send any text (for example 14175"foo" followed by return). If @sc{cvs} is working 14176correctly, it will respond with 14177 14178@example 14179cvs [pserver aborted]: bad auth protocol start: foo 14180@end example 14181 14182If instead you get: 14183 14184@example 14185Usage: cvs [cvs-options] command [command-options-and-arguments] 14186... 14187@end example 14188 14189@noindent 14190then you're missing the @samp{pserver} command at the end of the 14191line in @file{inetd.conf}; check to make sure that the entire command 14192is on one line and that it's complete. 14193 14194Likewise, if you get something like: 14195 14196@example 14197Unknown command: `pserved' 14198 14199CVS commands are: 14200 add Add a new file/directory to the repository 14201... 14202@end example 14203 14204@noindent 14205then you've misspelled @samp{pserver} in some way. If it isn't 14206obvious, check for invisible control characters (particularly 14207carriage returns) in @file{inetd.conf}. 14208 14209If it fails to work at all, then make sure inetd is working 14210right. Change the invocation in @file{inetd.conf} to run the 14211echo program instead of cvs. For example: 14212 14213@example 142142401 stream tcp nowait root /bin/echo echo hello 14215@end example 14216 14217After making that change and instructing inetd to 14218re-read its configuration file, "telnet servername 142192401" should show you the text hello and then the 14220server should close the connection. If this doesn't 14221work, you need to fix it before you can worry about 14222@sc{cvs} problems. 14223 14224On AIX systems, the system will often have its own 14225program trying to use port 2401. This is AIX's problem 14226in the sense that port 2401 is registered for use with 14227@sc{cvs}. I hear that there is an AIX patch available 14228to address this problem. 14229 14230Another good debugging tool is the @samp{-d} 14231(debugging) option to inetd. Consult your system 14232documentation for more information. 14233 14234If you seem to be connecting but get errors like: 14235 14236@example 14237cvs server: cannot open /root/.cvsignore: Permission denied 14238cvs [server aborted]: can't chdir(/root): Permission denied 14239@end example 14240 14241@noindent 14242then you probably haven't specified @samp{-f} in @file{inetd.conf}. 14243(In releases prior to @sc{cvs} 1.11.1, this problem can be caused by 14244your system setting the @code{$HOME} environment variable 14245for programs being run by inetd. In this case, you can either 14246have inetd run a shell script that unsets @code{$HOME} and then runs 14247@sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine 14248environment.) 14249 14250If you can connect successfully for a while but then can't, 14251you've probably hit inetd's rate limit. 14252(If inetd receives too many requests for the same service 14253in a short period of time, it assumes that something is wrong 14254and temporarily disables the service.) 14255Check your inetd documentation to find out how to adjust the 14256rate limit (some versions of inetd have a single rate limit, 14257others allow you to set the limit for each service separately.) 14258@end table 14259 14260@node Other problems 14261@appendixsec Other common problems 14262 14263Here is a list of problems which do not fit into the 14264above categories. They are in no particular order. 14265 14266@itemize @bullet 14267@item 14268On Windows, if there is a 30 second or so delay when 14269you run a @sc{cvs} command, it may mean that you have 14270your home directory set to @file{C:/}, for example (see 14271@code{HOMEDRIVE} and @code{HOMEPATH} in 14272@ref{Environment variables}). @sc{cvs} expects the home 14273directory to not end in a slash, for example @file{C:} 14274or @file{C:\cvs}. 14275@c FIXCVS: CVS should at least detect this and print an 14276@c error, presumably. 14277 14278@item 14279If you are running @sc{cvs} 1.9.18 or older, and 14280@code{cvs update} finds a conflict and tries to 14281merge, as described in @ref{Conflicts example}, but 14282doesn't tell you there were conflicts, then you may 14283have an old version of @sc{rcs}. The easiest solution 14284probably is to upgrade to a current version of 14285@sc{cvs}, which does not rely on external @sc{rcs} 14286programs. 14287@end itemize 14288 14289@c --------------------------------------------------------------------- 14290@node Credits 14291@appendix Credits 14292 14293@cindex Contributors (manual) 14294@cindex Credits (manual) 14295Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}> 14296wrote the manual pages which were distributed with 14297@sc{cvs} 1.3. Much of their text was copied into this 14298manual. He also read an early draft 14299of this manual and contributed many ideas and 14300corrections. 14301 14302The mailing-list @code{info-cvs} is sometimes 14303informative. I have included information from postings 14304made by the following persons: 14305David G. Grubbs <@t{dgg@@think.com}>. 14306 14307Some text has been extracted from the man pages for 14308@sc{rcs}. 14309 14310The @sc{cvs} @sc{faq} by David G. Grubbs has provided 14311useful material. The @sc{faq} is no longer maintained, 14312however, and this manual is about the closest thing there 14313is to a successor (with respect to documenting how to 14314use @sc{cvs}, at least). 14315 14316In addition, the following persons have helped by 14317telling me about mistakes I've made: 14318 14319@display 14320Roxanne Brunskill <@t{rbrunski@@datap.ca}>, 14321Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, 14322Karl Pingle <@t{pingle@@acuson.com}>, 14323Thomas A Peterson <@t{tap@@src.honeywell.com}>, 14324Inge Wallin <@t{ingwa@@signum.se}>, 14325Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> 14326and Michael Brown <@t{brown@@wi.extrel.com}>. 14327@end display 14328 14329The list of contributors here is not comprehensive; for a more 14330complete list of who has contributed to this manual see 14331the file @file{doc/ChangeLog} in the @sc{cvs} source 14332distribution. 14333 14334@c --------------------------------------------------------------------- 14335@node BUGS 14336@appendix Dealing with bugs in CVS or this manual 14337 14338@cindex Bugs in this manual or CVS 14339Neither @sc{cvs} nor this manual is perfect, and they 14340probably never will be. If you are having trouble 14341using @sc{cvs}, or think you have found a bug, there 14342are a number of things you can do about it. Note that 14343if the manual is unclear, that can be considered a bug 14344in the manual, so these problems are often worth doing 14345something about as well as problems with @sc{cvs} itself. 14346 14347@cindex Reporting bugs 14348@cindex Bugs, reporting 14349@cindex Errors, reporting 14350@itemize @bullet 14351@item 14352If you want someone to help you and fix bugs that you 14353report, there are companies which will do that for a 14354fee. One such company is: 14355 14356@cindex Ximbiot 14357@cindex Support, getting CVS support 14358@example 14359Ximbiot 14360319 S. River St. 14361Harrisburg, PA 17104-1657 14362USA 14363Email: info@@ximbiot.com 14364Phone: (717) 579-6168 14365Fax: (717) 234-3125 14366http://ximbiot.com/ 14367 14368@end example 14369 14370@item 14371If you got @sc{cvs} through a distributor, such as an 14372operating system vendor or a vendor of freeware 14373@sc{cd-rom}s, you may wish to see whether the 14374distributor provides support. Often, they will provide 14375no support or minimal support, but this may vary from 14376distributor to distributor. 14377 14378@item 14379If you have the skills and time to do so, you may wish 14380to fix the bug yourself. If you wish to submit your 14381fix for inclusion in future releases of @sc{cvs}, see 14382the file @sc{hacking} in the @sc{cvs} source 14383distribution. It contains much more information on the 14384process of submitting fixes. 14385 14386@item 14387There may be resources on the net which can help. Two 14388good places to start are: 14389 14390@example 14391http://www.cvshome.org 14392http://www.loria.fr/~molli/cvs-index.html 14393@end example 14394 14395If you are so inspired, increasing the information 14396available on the net is likely to be appreciated. For 14397example, before the standard @sc{cvs} distribution 14398worked on Windows 95, there was a web page with some 14399explanation and patches for running @sc{cvs} on Windows 1440095, and various people helped out by mentioning this 14401page on mailing lists or newsgroups when the subject 14402came up. 14403 14404@item 14405It is also possible to report bugs to @code{bug-cvs}. 14406Note that someone may or may not want to do anything 14407with your bug report---if you need a solution consider 14408one of the options mentioned above. People probably do 14409want to hear about bugs which are particularly severe 14410in consequences and/or easy to fix, however. You can 14411also increase your odds by being as clear as possible 14412about the exact nature of the bug and any other 14413relevant information. The way to report bugs is to 14414send email to @code{bug-cvs@@gnu.org}. Note 14415that submissions to @code{bug-cvs} may be distributed 14416under the terms of the @sc{gnu} Public License, so if 14417you don't like this, don't submit them. There is 14418usually no justification for sending mail directly to 14419one of the @sc{cvs} maintainers rather than to 14420@code{bug-cvs}; those maintainers who want to hear 14421about such bug reports read @code{bug-cvs}. Also note 14422that sending a bug report to other mailing lists or 14423newsgroups is @emph{not} a substitute for sending it to 14424@code{bug-cvs}. It is fine to discuss @sc{cvs} bugs on 14425whatever forum you prefer, but there are not 14426necessarily any maintainers reading bug reports sent 14427anywhere except @code{bug-cvs}. 14428@end itemize 14429 14430@cindex Known bugs in this manual or CVS 14431People often ask if there is a list of known bugs or 14432whether a particular bug is a known one. The file 14433@sc{bugs} in the @sc{cvs} source distribution is one 14434list of known bugs, but it doesn't necessarily try to 14435be comprehensive. Perhaps there will never be a 14436comprehensive, detailed list of known bugs. 14437 14438@c --------------------------------------------------------------------- 14439@node Index 14440@unnumbered Index 14441@cindex Index 14442 14443@printindex cp 14444 14445@summarycontents 14446 14447@contents 14448 14449@bye 14450