/contrib/cvs/doc/cvs.texinfo
Unknown | 14187 lines | 11978 code | 2209 blank | 0 comment | 0 complexity | 5b2b61113ddb78ea6f25ebc2d0559833 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
Large files files are truncated, but you can click here to view the full file
1\input texinfo @c -*-texinfo-*- 2@comment Documentation for CVS. 3@setfilename cvs.info 4@macro copyleftnotice 5@noindent 6Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 7 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 8 Free Software Foundation, Inc. 9 10@multitable @columnfractions .12 .88 11@item Portions 12@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 13 2006, 2007 Derek R. Price, 14@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007 15 Ximbiot @url{http://ximbiot.com}, 16@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB, 17@item @tab and Copyright @copyright{} others. 18@end multitable 19 20@ignore 21Permission is granted to process this file through Tex and print the 22results, provided the printed document carries copying permission 23notice identical to this one except for the removal of this paragraph 24(this paragraph not being relevant to the printed manual). 25 26@end ignore 27Permission is granted to make and distribute verbatim copies of 28this manual provided the copyright notice and this permission notice 29are preserved on all copies. 30 31Permission is granted to copy and distribute modified versions of this 32manual under the conditions for verbatim copying, provided also that the 33entire resulting derived work is distributed under the terms of a 34permission notice identical to this one. 35 36Permission is granted to copy and distribute translations of this manual 37into another language, under the above conditions for modified versions, 38except that this permission notice may be stated in a translation 39approved by the Free Software Foundation. 40@end macro 41 42@comment This file is part of the CVS distribution. 43 44@comment CVS is free software; you can redistribute it and/or modify 45@comment it under the terms of the GNU General Public License as published by 46@comment the Free Software Foundation; either version 2, or (at your option) 47@comment any later version. 48 49@comment CVS is distributed in the hope that it will be useful, 50@comment but WITHOUT ANY WARRANTY; without even the implied warranty of 51@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 52@comment GNU General Public License for more details. 53 54@c See ../README for A4 vs. US letter size. 55@c When we provided A4 postscript, and people tried to 56@c print it on US letter, the usual complaint was that the 57@c page numbers would get cut off. 58@c If one prints US letter on A4, reportedly there is 59@c some extra space at the top and/or bottom, and the side 60@c margins are a bit narrow, but no text is lost. 61@c 62@c See 63@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html 64@c for more on paper sizes. Insuring that margins are 65@c big enough to print on either A4 or US letter does 66@c indeed seem to be the usual approach (RFC2346). 67 68@c This document seems to get overfull hboxes with some 69@c frequency (probably because the tendency is to 70@c sanity-check it with "make info" and run TeX less 71@c often). The big ugly boxes just seem to add insult 72@c to injury, and I'm not aware of them helping to fix 73@c the overfull hboxes at all. 74@finalout 75 76@include version.texi 77@settitle CVS---Concurrent Versions System v@value{VERSION} 78@setchapternewpage odd 79 80@c -- TODO list: 81@c -- Fix all lines that match "^@c -- " 82@c -- Also places marked with FIXME should be manual 83@c problems (as opposed to FIXCVS for CVS problems). 84 85@c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by 86@c @asis when generating info and dvi, and by <i></i> in the generated html, 87@c such that keywords are not expanded in the generated html. 88@ifnothtml 89@macro splitrcskeyword {arg} 90@asis{}\arg\ 91@end macro 92@end ifnothtml 93 94@ifhtml 95@macro splitrcskeyword {arg} 96@i{}\arg\ 97@end macro 98@end ifhtml 99 100@dircategory GNU Packages 101@direntry 102* CVS: (cvs). Concurrent Versions System 103@end direntry 104@dircategory Individual utilities 105@direntry 106* cvs: (cvs)CVS commands. Concurrent Versions System 107@end direntry 108 109@comment The titlepage section does not appear in the Info file. 110@titlepage 111@sp 4 112@comment The title is printed in a large font. 113@center @titlefont{Version Management} 114@sp 115@center @titlefont{with} 116@sp 117@center @titlefont{CVS} 118@sp 2 119@center for @sc{cvs} @value{VERSION} 120@comment -release- 121@sp 3 122@center Per Cederqvist et al 123 124@comment The following two commands start the copyright page 125@comment for the printed manual. This will not appear in the Info file. 126@page 127@vskip 0pt plus 1filll 128@copyleftnotice 129@end titlepage 130 131@summarycontents 132 133@contents 134 135@comment ================================================================ 136@comment The real text starts here 137@comment ================================================================ 138 139@ifnottex 140@c --------------------------------------------------------------------- 141@node Top 142@top 143 144This info manual describes how to use and administer 145@sc{cvs} version @value{VERSION}. 146@end ifnottex 147 148@ifinfo 149@copyleftnotice 150@end ifinfo 151 152@c This menu is pretty long. Not sure how easily that 153@c can be fixed (no brilliant ideas right away)... 154@menu 155* Overview:: An introduction to CVS 156* Repository:: Where all your sources are stored 157* Starting a new project:: Starting a project with CVS 158* Revisions:: Numeric and symbolic names for revisions 159* Branching and merging:: Diverging/rejoining branches of development 160* Recursive behavior:: CVS descends directories 161* Adding and removing:: Adding/removing/renaming files/directories 162* History browsing:: Viewing the history of files in various ways 163 164CVS and the Real World. 165----------------------- 166* Binary files:: CVS can handle binary files 167* Multiple developers:: How CVS helps a group of developers 168* Revision management:: Policy questions for revision management 169* Keyword substitution:: CVS can include the revision inside the file 170* Tracking sources:: Tracking third-party sources 171* Builds:: Issues related to CVS and builds 172* Special Files:: Devices, links and other non-regular files 173 174References. 175----------- 176* CVS commands:: CVS commands share some things 177* Invoking CVS:: Quick reference to CVS commands 178* Administrative files:: Reference manual for the Administrative files 179* Environment variables:: All environment variables which affect CVS 180* Compatibility:: Upgrading CVS versions 181* Troubleshooting:: Some tips when nothing works 182* Credits:: Some of the contributors to this manual 183* BUGS:: Dealing with bugs in CVS or this manual 184* Index:: Index 185@end menu 186 187@c --------------------------------------------------------------------- 188@node Overview 189@chapter Overview 190@cindex Overview 191 192This chapter is for people who have never used 193@sc{cvs}, and perhaps have never used version control 194software before. 195 196If you are already familiar with @sc{cvs} and are just 197trying to learn a particular feature or remember a 198certain command, you can probably skip everything here. 199 200@menu 201* What is CVS?:: What you can do with @sc{cvs} 202* What is CVS not?:: Problems @sc{cvs} doesn't try to solve 203* A sample session:: A tour of basic @sc{cvs} usage 204@end menu 205 206@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 207@node What is CVS? 208@section What is CVS? 209@cindex What is CVS? 210@cindex Introduction to CVS 211@cindex CVS, introduction to 212 213@sc{cvs} is a version control system. Using it, you can 214record the history of your source files. 215 216@c -- /// 217@c -- ///Those who cannot remember the past are condemned to repeat it. 218@c -- /// -- George Santayana 219@c -- ////// 220 221@c -- Insert history quote here! 222For example, bugs sometimes creep in when 223software is modified, and you might not detect the bug 224until a long time after you make the modification. 225With @sc{cvs}, you can easily retrieve old versions to see 226exactly which change caused the bug. This can 227sometimes be a big help. 228 229You could of course save every version of every file 230you have ever created. This would 231however waste an enormous amount of disk space. @sc{cvs} 232stores all the versions of a file in a single file in a 233clever way that only stores the differences between 234versions. 235 236@sc{cvs} also helps you if you are part of a group of people working 237on the same project. It is all too easy to overwrite 238each others' changes unless you are extremely careful. 239Some editors, like @sc{gnu} Emacs, try to make sure that 240two people never modify the same file at the 241same time. Unfortunately, if someone is using another 242editor, that safeguard will not work. @sc{cvs} solves this problem 243by insulating the different developers from each other. Every 244developer works in his own directory, and @sc{cvs} merges 245the work when each developer is done. 246 247@cindex History of CVS 248@cindex CVS, history of 249@cindex Credits (CVS program) 250@cindex Contributors (CVS program) 251@sc{cvs} started out as a bunch of shell scripts written by 252Dick Grune, posted to the newsgroup 253@code{comp.sources.unix} in the volume 6 254release of July, 1986. While no actual code from 255these shell scripts is present in the current version 256of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms 257come from them. 258 259In April, 1989, Brian Berliner designed and coded @sc{cvs}. 260Jeff Polk later helped Brian with the design of the @sc{cvs} 261module and vendor branch support. 262 263@cindex Source, getting CVS source 264You can get @sc{cvs} in a variety of ways, including 265free download from the Internet. For more information 266on downloading @sc{cvs} and other @sc{cvs} topics, see: 267 268@example 269@url{http://cvs.nongnu.org/} 270@end example 271 272@cindex Mailing list 273@cindex List, mailing list 274@cindex Newsgroups 275There is a mailing list, known as @email{info-cvs@@nongnu.org}, 276devoted to @sc{cvs}. To subscribe or 277unsubscribe 278write to 279@email{info-cvs-request@@nongnu.org}. 280If you prefer a Usenet group, there is a one-way mirror (posts to the email 281list are usually sent to the news group, but not vice versa) of 282@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}. The right 283Usenet group for posts is @url{news:comp.software.config-mgmt} which is for 284@sc{cvs} discussions (along with other configuration 285management systems). In the future, it might be 286possible to create a 287@code{comp.software.config-mgmt.cvs}, but probably only 288if there is sufficient @sc{cvs} traffic on 289@url{news:comp.software.config-mgmt}. 290@c Other random data is that the tale was very 291@c skeptical of comp.software.config-mgmt.cvs when the 292@c subject came up around 1995 or so (for one 293@c thing, because creating it would be a "reorg" which 294@c would need to take a more comprehensive look at the 295@c whole comp.software.config-mgmt.* hierarchy). 296 297You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list, 298described in more detail in @ref{BUGS}. To subscribe 299send mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way 300Usenet mirror (posts to the Usenet group are usually sent to the email list and 301vice versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}. 302 303@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 304@node What is CVS not? 305@section What is CVS not? 306@cindex What is CVS not? 307 308@sc{cvs} can do a lot of things for you, but it does 309not try to be everything for everyone. 310 311@table @asis 312@item @sc{cvs} is not a build system. 313 314Though the structure of your repository and modules 315file interact with your build system 316(e.g. @file{Makefile}s), they are essentially 317independent. 318 319@sc{cvs} does not dictate how you build anything. It 320merely stores files for retrieval in a tree structure 321you devise. 322 323@sc{cvs} does not dictate how to use disk space in the 324checked out working directories. If you write your 325@file{Makefile}s or scripts in every directory so they 326have to know the relative positions of everything else, 327you wind up requiring the entire repository to be 328checked out. 329 330If you modularize your work, and construct a build 331system that will share files (via links, mounts, 332@code{VPATH} in @file{Makefile}s, etc.), you can 333arrange your disk usage however you like. 334 335But you have to remember that @emph{any} such system is 336a lot of work to construct and maintain. @sc{cvs} does 337not address the issues involved. 338 339Of course, you should place the tools created to 340support such a build system (scripts, @file{Makefile}s, 341etc.) under @sc{cvs}. 342 343Figuring out what files need to be rebuilt when 344something changes is, again, something to be handled 345outside the scope of @sc{cvs}. One traditional 346approach is to use @code{make} for building, and use 347some automated tool for generating the dependencies which 348@code{make} uses. 349 350See @ref{Builds}, for more information on doing builds 351in conjunction with @sc{cvs}. 352 353@item @sc{cvs} is not a substitute for management. 354 355Your managers and project leaders are expected to talk 356to you frequently enough to make certain you are aware 357of schedules, merge points, branch names and release 358dates. If they don't, @sc{cvs} can't help. 359 360@sc{cvs} is an instrument for making sources dance to 361your tune. But you are the piper and the composer. No 362instrument plays itself or writes its own music. 363 364@item @sc{cvs} is not a substitute for developer communication. 365 366When faced with conflicts within a single file, most 367developers manage to resolve them without too much 368effort. But a more general definition of ``conflict'' 369includes problems too difficult to solve without 370communication between developers. 371 372@sc{cvs} cannot determine when simultaneous changes 373within a single file, or across a whole collection of 374files, will logically conflict with one another. Its 375concept of a @dfn{conflict} is purely textual, arising 376when two changes to the same base file are near enough 377to spook the merge (i.e., @code{diff3}) command. 378 379@sc{cvs} does not claim to help at all in figuring out 380non-textual or distributed conflicts in program logic. 381 382For example: Say you change the arguments to function 383@code{X} defined in file @file{A}. At the same time, 384someone edits file @file{B}, adding new calls to 385function @code{X} using the old arguments. You are 386outside the realm of @sc{cvs}'s competence. 387 388Acquire the habit of reading specs and talking to your 389peers. 390 391 392@item @sc{cvs} does not have change control 393 394Change control refers to a number of things. First of 395all it can mean @dfn{bug-tracking}, that is being able 396to keep a database of reported bugs and the status of 397each one (Is it fixed? In what release? Has the bug 398submitter agreed that it is fixed?). For interfacing 399@sc{cvs} to an external bug-tracking system, see the 400@file{rcsinfo} and @file{verifymsg} files 401(@pxref{Administrative files}). 402 403Another aspect of change control is keeping track of 404the fact that changes to several files were in fact 405changed together as one logical change. If you check 406in several files in a single @code{cvs commit} 407operation, @sc{cvs} then forgets that those files were 408checked in together, and the fact that they have the 409same log message is the only thing tying them 410together. Keeping a @sc{gnu} style @file{ChangeLog} 411can help somewhat. 412@c FIXME: should have an xref to a section which talks 413@c more about keeping ChangeLog's with CVS, but that 414@c section hasn't been written yet. 415 416Another aspect of change control, in some systems, is 417the ability to keep track of the status of each 418change. Some changes have been written by a developer, 419others have been reviewed by a second developer, and so 420on. Generally, the way to do this with @sc{cvs} is to 421generate a diff (using @code{cvs diff} or @code{diff}) 422and email it to someone who can then apply it using the 423@code{patch} utility. This is very flexible, but 424depends on mechanisms outside @sc{cvs} to make sure 425nothing falls through the cracks. 426 427@item @sc{cvs} is not an automated testing program 428 429It should be possible to enforce mandatory use of a 430test suite using the @code{commitinfo} file. I haven't 431heard a lot about projects trying to do that or whether 432there are subtle gotchas, however. 433 434@item @sc{cvs} does not have a built-in process model 435 436Some systems provide ways to ensure that changes or 437releases go through various steps, with various 438approvals as needed. Generally, one can accomplish 439this with @sc{cvs} but it might be a little more work. 440In some cases you'll want to use the @file{commitinfo}, 441@file{loginfo}, @file{rcsinfo}, or @file{verifymsg} 442files, to require that certain steps be performed 443before cvs will allow a checkin. Also consider whether 444features such as branches and tags can be used to 445perform tasks such as doing work in a development tree 446and then merging certain changes over to a stable tree 447only once they have been proven. 448@end table 449 450@c --------------------------------------------------------------------- 451@node A sample session 452@section A sample session 453@cindex Example of a work-session 454@cindex Getting started 455@cindex Work-session, example of 456@cindex tc, Trivial Compiler (example) 457@cindex Trivial Compiler (example) 458 459@c I think an example is a pretty good way to start. But 460@c somewhere in here, maybe after the sample session, 461@c we need something which is kind of 462@c a "roadmap" which is more directed at sketching out 463@c the functionality of CVS and pointing people to 464@c various other parts of the manual. As it stands now 465@c people who read in order get dumped right into all 466@c manner of hair regarding remote repositories, 467@c creating a repository, etc. 468@c 469@c The following was in the old Basic concepts node. I don't 470@c know how good a job it does at introducing modules, 471@c or whether they need to be introduced so soon, but 472@c something of this sort might go into some 473@c introductory material somewhere. 474@ignore 475@cindex Modules (intro) 476The repository contains directories and files, in an 477arbitrary tree. The @dfn{modules} feature can be used 478to group together a set of directories or files into a 479single entity (@pxref{modules}). A typical usage is to 480define one module per project. 481@end ignore 482 483As a way of introducing @sc{cvs}, we'll go through a 484typical work-session using @sc{cvs}. The first thing 485to understand is that @sc{cvs} stores all files in a 486centralized @dfn{repository} (@pxref{Repository}); this 487section assumes that a repository is set up. 488@c I'm not sure that the sentence concerning the 489@c repository quite tells the user what they need to 490@c know at this point. Might need to expand on "centralized" 491@c slightly (maybe not here, maybe further down in the example?) 492 493Suppose you are working on a simple compiler. The source 494consists of a handful of C files and a @file{Makefile}. 495The compiler is called @samp{tc} (Trivial Compiler), 496and the repository is set up so that there is a module 497called @samp{tc}. 498 499@menu 500* Getting the source:: Creating a workspace 501* Committing your changes:: Making your work available to others 502* Cleaning up:: Cleaning up 503* Viewing differences:: Viewing differences 504@end menu 505 506@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 507@node Getting the source 508@subsection Getting the source 509@cindex Getting the source 510@cindex Checking out source 511@cindex Fetching source 512@cindex Source, getting from CVS 513@cindex Checkout, example 514 515The first thing you must do is to get your own working copy of the 516source for @samp{tc}. For this, you use the @code{checkout} command: 517 518@example 519$ cvs checkout tc 520@end example 521 522@noindent 523This will create a new directory called @file{tc} and populate it with 524the source files. 525 526@example 527$ cd tc 528$ ls 529CVS Makefile backend.c driver.c frontend.c parser.c 530@end example 531 532The @file{CVS} directory is used internally by 533@sc{cvs}. Normally, you should not modify or remove 534any of the files in it. 535 536You start your favorite editor, hack away at @file{backend.c}, and a couple 537of hours later you have added an optimization pass to the compiler. 538A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that 539you want to edit. @xref{Multiple developers}, for an explanation. 540 541@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 542@node Committing your changes 543@subsection Committing your changes 544@cindex Committing changes to files 545@cindex Log message entry 546 547When you have checked that the compiler is still compilable you decide 548to make a new version of @file{backend.c}. This will 549store your new @file{backend.c} in the repository and 550make it available to anyone else who is using that same 551repository. 552 553@example 554$ cvs commit backend.c 555@end example 556 557@noindent 558@sc{cvs} starts an editor, to allow you to enter a log 559message. You type in ``Added an optimization pass.'', 560save the temporary file, and exit the editor. 561 562@cindex CVSEDITOR, environment variable 563@cindex EDITOR, environment variable 564The environment variable @code{$CVSEDITOR} determines 565which editor is started. If @code{$CVSEDITOR} is not 566set, then if the environment variable @code{$EDITOR} is 567set, it will be used. If both @code{$CVSEDITOR} and 568@code{$EDITOR} are not set then there is a default 569which will vary with your operating system, for example 570@code{vi} for unix or @code{notepad} for Windows 571NT/95. 572 573@cindex VISUAL, environment variable 574In addition, @sc{cvs} checks the @code{$VISUAL} environment 575variable. Opinions vary on whether this behavior is desirable and 576whether future releases of @sc{cvs} should check @code{$VISUAL} or 577ignore it. You will be OK either way if you make sure that 578@code{$VISUAL} is either unset or set to the same thing as 579@code{$EDITOR}. 580 581@c This probably should go into some new node 582@c containing detailed info on the editor, rather than 583@c the intro. In fact, perhaps some of the stuff with 584@c CVSEDITOR and -m and so on should too. 585When @sc{cvs} starts the editor, it includes a list of 586files which are modified. For the @sc{cvs} client, 587this list is based on comparing the modification time 588of the file against the modification time that the file 589had when it was last gotten or updated. Therefore, if 590a file's modification time has changed but its contents 591have not, it will show up as modified. The simplest 592way to handle this is simply not to worry about it---if 593you proceed with the commit @sc{cvs} will detect that 594the contents are not modified and treat it as an 595unmodified file. The next @code{update} will clue 596@sc{cvs} in to the fact that the file is unmodified, 597and it will reset its stored timestamp so that the file 598will not show up in future editor sessions. 599@c FIXCVS: Might be nice if "commit" and other commands 600@c would reset that timestamp too, but currently commit 601@c doesn't. 602@c FIXME: Need to talk more about the process of 603@c prompting for the log message. Like show an example 604@c of what it pops up in the editor, for example. Also 605@c a discussion of how to get the "a)bort, c)ontinue, 606@c e)dit" prompt and what to do with it. Might also 607@c work in the suggestion that if you want a diff, you 608@c should make it before running commit (someone 609@c suggested that the diff pop up in the editor. I'm 610@c not sure that is better than telling people to run 611@c "cvs diff" first if that is what they want, but if 612@c we want to tell people that, the manual possibly 613@c should say it). 614 615If you want to avoid 616starting an editor you can specify the log message on 617the command line using the @samp{-m} flag instead, like 618this: 619 620@example 621$ cvs commit -m "Added an optimization pass" backend.c 622@end example 623 624@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 625@node Cleaning up 626@subsection Cleaning up 627@cindex Cleaning up 628@cindex Working copy, removing 629@cindex Removing your working copy 630@cindex Releasing your working copy 631 632Before you turn to other tasks you decide to remove your working copy of 633tc. One acceptable way to do that is of course 634 635@example 636$ cd .. 637$ rm -r tc 638@end example 639 640@noindent 641but a better way is to use the @code{release} command (@pxref{release}): 642 643@example 644$ cd .. 645$ cvs release -d tc 646M driver.c 647? tc 648You have [1] altered files in this repository. 649Are you sure you want to release (and delete) directory `tc': n 650** `release' aborted by user choice. 651@end example 652 653The @code{release} command checks that all your modifications have been 654committed. If history logging is enabled it also makes a note in the 655history file. @xref{history file}. 656 657When you use the @samp{-d} flag with @code{release}, it 658also removes your working copy. 659 660In the example above, the @code{release} command wrote a couple of lines 661of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. 662That is nothing to worry about: @file{tc} is the executable compiler, 663and it should not be stored in the repository. @xref{cvsignore}, 664for information about how to make that warning go away. 665@xref{release output}, for a complete explanation of 666all possible output from @code{release}. 667 668@samp{M driver.c} is more serious. It means that the 669file @file{driver.c} has been modified since it was 670checked out. 671 672The @code{release} command always finishes by telling 673you how many modified files you have in your working 674copy of the sources, and then asks you for confirmation 675before deleting any files or making any note in the 676history file. 677 678You decide to play it safe and answer @kbd{n @key{RET}} 679when @code{release} asks for confirmation. 680 681@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 682@node Viewing differences 683@subsection Viewing differences 684@cindex Viewing differences 685@cindex Diff 686 687You do not remember modifying @file{driver.c}, so you want to see what 688has happened to that file. 689 690@example 691$ cd tc 692$ cvs diff driver.c 693@end example 694 695This command runs @code{diff} to compare the version of @file{driver.c} 696that you checked out with your working copy. When you see the output 697you remember that you added a command line option that enabled the 698optimization pass. You check it in, and release the module. 699@c FIXME: we haven't yet defined the term "check in". 700 701@example 702$ cvs commit -m "Added an optimization pass" driver.c 703Checking in driver.c; 704/usr/local/cvsroot/tc/driver.c,v <-- driver.c 705new revision: 1.2; previous revision: 1.1 706done 707$ cd .. 708$ cvs release -d tc 709? tc 710You have [0] altered files in this repository. 711Are you sure you want to release (and delete) directory `tc': y 712@end example 713 714@c --------------------------------------------------------------------- 715@node Repository 716@chapter The Repository 717@cindex Repository (intro) 718@cindex Repository, example 719@cindex Layout of repository 720@cindex Typical repository 721@cindex /usr/local/cvsroot, as example repository 722@cindex cvsroot 723 724The @sc{cvs} @dfn{repository} stores a complete copy of 725all the files and directories which are under version 726control. 727 728Normally, you never access any of the files in the 729repository directly. Instead, you use @sc{cvs} 730commands to get your own copy of the files into a 731@dfn{working directory}, and then 732work on that copy. When you've finished a set of 733changes, you check (or @dfn{commit}) them back into the 734repository. The repository then contains the changes 735which you have made, as well as recording exactly what 736you changed, when you changed it, and other such 737information. Note that the repository is not a 738subdirectory of the working directory, or vice versa; 739they should be in separate locations. 740@c Need some example, e.g. repository 741@c /usr/local/cvsroot; working directory 742@c /home/joe/sources. But this node is too long 743@c as it is; need a little reorganization... 744 745@cindex :local:, setting up 746@sc{cvs} can access a repository by a variety of 747means. It might be on the local computer, or it might 748be on a computer across the room or across the world. 749To distinguish various ways to access a repository, the 750repository name can start with an @dfn{access method}. 751For example, the access method @code{:local:} means to 752access a repository directory, so the repository 753@code{:local:/usr/local/cvsroot} means that the 754repository is in @file{/usr/local/cvsroot} on the 755computer running @sc{cvs}. For information on other 756access methods, see @ref{Remote repositories}. 757 758@c Can se say this more concisely? Like by passing 759@c more of the buck to the Remote repositories node? 760If the access method is omitted, then if the repository 761starts with @samp{/}, then @code{:local:} is 762assumed. If it does not start with @samp{/} then either 763@code{:ext:} or @code{:server:} is assumed. For 764example, if you have a local repository in 765@file{/usr/local/cvsroot}, you can use 766@code{/usr/local/cvsroot} instead of 767@code{:local:/usr/local/cvsroot}. But if (under 768Windows NT, for example) your local repository is 769@file{c:\src\cvsroot}, then you must specify the access 770method, as in @code{:local:c:/src/cvsroot}. 771 772@c This might appear to go in Repository storage, but 773@c actually it is describing something which is quite 774@c user-visible, when you do a "cvs co CVSROOT". This 775@c isn't necessary the perfect place for that, though. 776The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains 777administrative files for @sc{cvs}. The other directories contain the actual 778user-defined modules. 779 780@menu 781* Specifying a repository:: Telling CVS where your repository is 782* Repository storage:: The structure of the repository 783* Working directory storage:: The structure of working directories 784* Intro administrative files:: Defining modules 785* Multiple repositories:: Multiple repositories 786* Creating a repository:: Creating a repository 787* Backing up:: Backing up a repository 788* Moving a repository:: Moving a repository 789* Remote repositories:: Accessing repositories on remote machines 790* Read-only access:: Granting read-only access to the repository 791* Server temporary directory:: The server creates temporary directories 792@end menu 793 794@node Specifying a repository 795@section Telling CVS where your repository is 796 797There are several ways to tell @sc{cvs} 798where to find the repository. You can name the 799repository on the command line explicitly, with the 800@code{-d} (for "directory") option: 801 802@example 803cvs -d /usr/local/cvsroot checkout yoyodyne/tc 804@end example 805 806@cindex .profile, setting CVSROOT in 807@cindex .cshrc, setting CVSROOT in 808@cindex .tcshrc, setting CVSROOT in 809@cindex .bashrc, setting CVSROOT in 810@cindex CVSROOT, environment variable 811 Or you can set the @code{$CVSROOT} environment 812variable to an absolute path to the root of the 813repository, @file{/usr/local/cvsroot} in this example. 814To set @code{$CVSROOT}, @code{csh} and @code{tcsh} 815users should have this line in their @file{.cshrc} or 816@file{.tcshrc} files: 817 818@example 819setenv CVSROOT /usr/local/cvsroot 820@end example 821 822@noindent 823@code{sh} and @code{bash} users should instead have these lines in their 824@file{.profile} or @file{.bashrc}: 825 826@example 827CVSROOT=/usr/local/cvsroot 828export CVSROOT 829@end example 830 831@cindex Root file, in CVS directory 832@cindex CVS/Root file 833 A repository specified with @code{-d} will 834override the @code{$CVSROOT} environment variable. 835Once you've checked a working copy out from the 836repository, it will remember where its repository is 837(the information is recorded in the 838@file{CVS/Root} file in the working copy). 839 840The @code{-d} option and the @file{CVS/Root} file both 841override the @code{$CVSROOT} environment variable. If 842@code{-d} option differs from @file{CVS/Root}, the 843former is used. Of course, for proper operation they 844should be two ways of referring to the same repository. 845 846@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 847@node Repository storage 848@section How data is stored in the repository 849@cindex Repository, how data is stored 850 851For most purposes it isn't important @emph{how} 852@sc{cvs} stores information in the repository. In 853fact, the format has changed in the past, and is likely 854to change in the future. Since in almost all cases one 855accesses the repository via @sc{cvs} commands, such 856changes need not be disruptive. 857 858However, in some cases it may be necessary to 859understand how @sc{cvs} stores data in the repository, 860for example you might need to track down @sc{cvs} locks 861(@pxref{Concurrency}) or you might need to deal with 862the file permissions appropriate for the repository. 863 864@menu 865* Repository files:: What files are stored in the repository 866* File permissions:: File permissions 867* Windows permissions:: Issues specific to Windows 868* Attic:: Some files are stored in the Attic 869* CVS in repository:: Additional information in CVS directory 870* Locks:: CVS locks control concurrent accesses 871* CVSROOT storage:: A few things about CVSROOT are different 872@end menu 873 874@node Repository files 875@subsection Where files are stored within the repository 876 877@c @cindex Filenames, legal 878@c @cindex Legal filenames 879@c Somewhere we need to say something about legitimate 880@c characters in filenames in working directory and 881@c repository. Not "/" (not even on non-unix). And 882@c here is a specific set of issues: 883@c Files starting with a - are handled inconsistently. They can not 884@c be added to a repository with an add command, because it they are 885@c interpreted as a switch. They can appear in a repository if they are 886@c part of a tree that is imported. They can not be removed from the tree 887@c once they are there. 888@c Note that "--" *is* supported (as a 889@c consequence of using GNU getopt). Should document 890@c this somewhere ("Common options"?). The other usual technique, 891@c "./-foo", isn't as effective, at least for "cvs add" 892@c which doesn't support pathnames containing "/". 893 894The overall structure of the repository is a directory 895tree corresponding to the directories in the working 896directory. For example, supposing the repository is in 897 898@example 899/usr/local/cvsroot 900@end example 901 902@noindent 903here is a possible directory tree (showing only the 904directories): 905 906@example 907@t{/usr} 908 | 909 +--@t{local} 910 | | 911 | +--@t{cvsroot} 912 | | | 913 | | +--@t{CVSROOT} 914 | (administrative files) 915 | 916 +--@t{gnu} 917 | | 918 | +--@t{diff} 919 | | (source code to @sc{gnu} diff) 920 | | 921 | +--@t{rcs} 922 | | (source code to @sc{rcs}) 923 | | 924 | +--@t{cvs} 925 | (source code to @sc{cvs}) 926 | 927 +--@t{yoyodyne} 928 | 929 +--@t{tc} 930 | | 931 | +--@t{man} 932 | | 933 | +--@t{testing} 934 | 935 +--(other Yoyodyne software) 936@end example 937 938With the directories are @dfn{history files} for each file 939under version control. The name of the history file is 940the name of the corresponding file with @samp{,v} 941appended to the end. Here is what the repository for 942the @file{yoyodyne/tc} directory might look like: 943@c FIXME: Should also mention CVS (CVSREP) 944@c FIXME? Should we introduce Attic with an xref to 945@c Attic? Not sure whether that is a good idea or not. 946@example 947 @code{$CVSROOT} 948 | 949 +--@t{yoyodyne} 950 | | 951 | +--@t{tc} 952 | | | 953 +--@t{Makefile,v} 954 +--@t{backend.c,v} 955 +--@t{driver.c,v} 956 +--@t{frontend.c,v} 957 +--@t{parser.c,v} 958 +--@t{man} 959 | | 960 | +--@t{tc.1,v} 961 | 962 +--@t{testing} 963 | 964 +--@t{testpgm.t,v} 965 +--@t{test2.t,v} 966@end example 967 968@cindex History files 969@cindex RCS history files 970@c The first sentence, about what history files 971@c contain, is kind of redundant with our intro to what the 972@c repository does in node Repository.... 973The history files contain, among other things, enough 974information to recreate any revision of the file, a log 975of all commit messages and the user-name of the person 976who committed the revision. The history files are 977known as @dfn{RCS files}, because the first program to 978store files in that format was a version control system 979known as @sc{rcs}. For a full 980description of the file format, see the @code{man} page 981@cite{rcsfile(5)}, distributed with @sc{rcs}, or the 982file @file{doc/RCSFILES} in the @sc{cvs} source 983distribution. This 984file format has become very common---many systems other 985than @sc{cvs} or @sc{rcs} can at least import history 986files in this format. 987@c FIXME: Think about including documentation for this 988@c rather than citing it? In the long run, getting 989@c this to be a standard (not sure if we can cope with 990@c a standards process as formal as IEEE/ANSI/ISO/etc, 991@c though...) is the way to go, so maybe citing is 992@c better. 993 994The @sc{rcs} files used in @sc{cvs} differ in a few 995ways from the standard format. The biggest difference 996is magic branches; for more information see @ref{Magic 997branch numbers}. Also in @sc{cvs} the valid tag names 998are a subset of what @sc{rcs} accepts; for @sc{cvs}'s 999rules see @ref{Tags}. 1000 1001@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002@node File permissions 1003@subsection File permissions 1004@c -- Move this to @node Creating a repository or similar 1005@cindex Security, file permissions in repository 1006@cindex File permissions, general 1007@cindex Permissions, general 1008@c FIXME: we need to somehow reflect "permissions in 1009@c repository" versus "permissions in working 1010@c directory" in the index entries. 1011@cindex Group, UNIX file permissions, in repository 1012@cindex Read-only files, in repository 1013All @samp{,v} files are created read-only, and you 1014should not change the permission of those files. The 1015directories inside the repository should be writable by 1016the persons that have permission to modify the files in 1017each directory. This normally means that you must 1018create a UNIX group (see group(5)) consisting of the 1019persons that are to edit the files in a project, and 1020set up the repository so that it is that group that 1021owns the directory. 1022(On some systems, you also need to set the set-group-ID-on-execution bit 1023on the repository directories (see chmod(1)) so that newly-created files 1024and directories get the group-ID of the parent directory rather than 1025that of the current process.) 1026 1027@c See also comment in commitinfo node regarding cases 1028@c which are really awkward with unix groups. 1029 1030This means that you can only control access to files on 1031a per-directory basis. 1032 1033Note that users must also have write access to check 1034out files, because @sc{cvs} needs to create lock files 1035(@pxref{Concurrency}). You can use LockDir in CVSROOT/config 1036to put the lock files somewhere other than in the repository 1037if you want to allow read-only access to some directories 1038(@pxref{config}). 1039 1040@c CVS seems to use CVSUMASK in picking permissions for 1041@c val-tags, but maybe we should say more about this. 1042@c Like val-tags gets created by someone who doesn't 1043@c have CVSUMASK set right? 1044@cindex CVSROOT/val-tags file, and read-only access to projects 1045@cindex val-tags file, and read-only access to projects 1046Also note that users must have write access to the 1047@file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep 1048track of what tags are valid tag names (it is sometimes 1049updated when tags are used, as well as when they are 1050created). 1051 1052Each @sc{rcs} file will be owned by the user who last 1053checked it in. This has little significance; what 1054really matters is who owns the directories. 1055 1056@cindex CVSUMASK, environment variable 1057@cindex Umask, for repository files 1058@sc{cvs} tries to set up reasonable file permissions 1059for new directories that are added inside the tree, but 1060you must fix the permissions manually when a new 1061directory should have different permissions than its 1062parent directory. If you set the @code{CVSUMASK} 1063environment variable, that will control the file 1064permissions which @sc{cvs} uses in creating directories 1065and/or files in the repository. @code{CVSUMASK} does 1066not affect the file permissions in the working 1067directory; such files have the permissions which are 1068typical for newly created files, except that sometimes 1069@sc{cvs} creates them read-only (see the sections on 1070watches, @ref{Setting a watch}; -r, @ref{Global 1071options}; or @code{CVSREAD}, @ref{Environment variables}). 1072@c FIXME: Need more discussion of which 1073@c group should own the file in the repository. 1074@c Include a somewhat detailed example of the usual 1075@c case where CVSUMASK is 007, the developers are all 1076@c in a group, and that group owns stuff in the 1077@c repository. Need to talk about group ownership of 1078@c newly-created directories/files (on some unices, 1079@c such as SunOS4, setting the setgid bit on the 1080@c directories will make files inherit the directory's 1081@c group. On other unices, your mileage may vary. I 1082@c can't remember what POSIX says about this, if 1083@c anything). 1084 1085Note that using the client/server @sc{cvs} 1086(@pxref{Remote repositories}), there is no good way to 1087set @code{CVSUMASK}; the setting on the client machine 1088has no effect. If you are connecting with @code{rsh}, you 1089can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as 1090described in the documentation for your operating 1091system. This behavior might change in future versions 1092of @sc{cvs}; do not rely on the setting of 1093@code{CVSUMASK} on the client having no effect. 1094@c FIXME: need to explain what a umask is or cite 1095@c someplace which does. 1096@c 1097@c There is also a larger (largely separate) issue 1098@c about the meaning of CVSUMASK in a non-unix context. 1099@c For example, whether there is 1100@c an equivalent which fits better into other 1101@c protection schemes like POSIX.6, VMS, &c. 1102@c 1103@c FIXME: Need one place which discusses this 1104@c read-only files thing. Why would one use -r or 1105@c CVSREAD? Why would one use watches? How do they 1106@c interact? 1107@c 1108@c FIXME: We need to state 1109@c whether using CVSUMASK removes the need for manually 1110@c fixing permissions (in fact, if we are going to mention 1111@c manually fixing permission, we better document a lot 1112@c better just what we mean by "fix"). 1113 1114Using pserver, you will generally need stricter 1115permissions on the @sc{cvsroot} directory and 1116directories above it in the tree; see @ref{Password 1117authentication security}. 1118 1119@cindex Setuid 1120@cindex Setgid 1121@cindex Security, setuid 1122@cindex Installed images (VMS) 1123Some operating systems have features which allow a 1124particular program to run with the ability to perform 1125operations which the caller of the program could not. 1126For example, the set user ID (setuid) or set group ID 1127(setgid) features of unix or the installed image 1128feature of VMS. @sc{cvs} was not written to use such 1129features and therefore attempting to install @sc{cvs} in 1130this fashion will provide protection against only 1131accidental lapses; anyone who is trying to circumvent 1132the measure will be able to do so, and depending on how 1133you have set it up may gain access to more than just 1134@sc{cvs}. You may wish to instead consider pserver. It 1135shares some of the same attributes, in terms of 1136possibly providing a false sense of security or opening 1137security holes wider than the ones you are trying to 1138fix, so read the documentation on pserver security 1139carefully if you are considering this option 1140(@ref{Password authentication security}). 1141 1142@node Windows permissions 1143@subsection File Permission issues specific to Windows 1144@cindex Windows, and permissions 1145@cindex File permissions, Windows-specific 1146@cindex Permissions, Windows-specific 1147 1148Some file permission issues are specific to Windows 1149operating systems (Windows 95, Windows NT, and 1150presumably future operating systems in this family. 1151Some of the following might apply to OS/2 but I'm not 1152sure). 1153 1154If you are using local @sc{cvs} and the repository is on a 1155networked file system which is served by the Samba SMB 1156server, some people have reported problems with 1157permissions. Enabling WRITE=YES in the samba 1158configuration is said to fix/workaround it. 1159Disclaimer: I haven't investigated enough to know the 1160implications of enabling that option, nor do I know 1161whether there is something which @sc{cvs} could be doing 1162differently in order to avoid the problem. If you find 1163something out, please let us know as described in 1164@ref{BUGS}. 1165 1166@node Attic 1167@subsection The attic 1168@cindex Attic 1169 1170You will notice that sometimes @sc{cvs} stores an 1171@sc{rcs} file in the @code{Attic}. For example, if the 1172@sc{cvsroot} is @file{/usr/local/cvsroot} and we are 1173talking about the file @file{backend.c} in the 1174directory @file{yoyodyne/tc}, then the file normally 1175would be in 1176 1177@example 1178/usr/local/cvsroot/yoyodyne/tc/backend.c,v 1179@end example 1180 1181@noindent 1182but if it goes in the attic, it would be in 1183 1184@example 1185/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v 1186@end example 1187 1188@noindent 1189@cindex Dead state 1190instead. It should not matter from a user point of 1191view whether a file is in the attic; @sc{cvs} keeps 1192track of this and looks in the attic when it needs to. 1193But in case you want to know, the rule is that the RCS 1194file is stored in the attic if and only if the head 1195revision on the trunk has state @code{dead}. A 1196@code{dead} state means that file has been removed, or 1197never added, for that revision. For example, if you 1198add a file on a branch, it will have a trunk revision 1199in @code{dead} state, and a branch revision in a 1200non-@code{dead} state. 1201@c Probably should have some more concrete examples 1202@c here, or somewhere (not sure exactly how we should 1203@c arrange the discussion of the dead state, versus 1204@c discussion of the attic). 1205 1206@node CVS in repository 1207@subsection The CVS directory in the repository 1208@cindex CVS directory, in repository 1209 1210The @file{CVS} directory in each repository directory 1211contains information such as file attributes (in a file 1212called @file{CVS/fileattr}. In the 1213future additional files may be added to this directory, 1214so implementations should silently ignore additional 1215files. 1216 1217This behavior is implemented only by @sc{cvs} 1.7 and 1218later; for details see @ref{Watches Compatibility}. 1219 1220The format of the @file{fileattr} file is a series of entries 1221of the following form (where @samp{@{} and @samp{@}} 1222means the text between the braces can be repeated zero 1223or more times): 1224 1225@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval} 1226 @{; @var{attrname} = @var{attrval}@} <linefeed> 1227 1228@var{ent-type} is @samp{F} for a file, in which case the entry specifies the 1229attributes for that file. 1230 1231@var{ent-type} is @samp{D}, 1232and @var{filename} empty, to specify default attributes 1233to be used for newly added files. 1234 1235Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older 1236will delete them any time it writes file attributes. 1237@sc{cvs} 1.10 and later will preserve them. 1238 1239Note that the order of the lines is not significant; 1240a program writing the fileattr file may 1241rearrange them at its convenience. 1242 1243There is currently no way of quoting tabs or line feeds in the 1244filename, @samp{=} in @var{attrname}, 1245@samp{;} in @var{attrval}, etc. Note: some implementations also 1246don't handle a NUL character in any of the fields, but 1247implementations are encouraged to allow it. 1248 1249By convention, @var{attrname} starting with @samp{_} is for an attribute given 1250special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes 1251(or will be, once implementations start supporting user-defined attributes). 1252 1253Built-in attributes: 1254 1255@table @code 1256@item _watched 1257Present means the file is watched and should be checked out 1258read-only. 1259 1260@item _watchers 1261Users with watches for this file. Value is 1262@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @} 1263where @var{watcher} is a username, and @var{type} 1264is zero or more of edit,unedit,commit separated by 1265@samp{+} (that is, nothing if none; there is no "none" or "all" keyword). 1266 1267@item _editors 1268Users editing this file. Value is 1269@var{editor} > @var{val} @{ , @var{editor} > @var{val} @} 1270where @var{editor} is a username, and @var{val} is 1271@var{time}+@var{hostname}+@var{pathname}, where 1272@var{time} is when the @code{cvs edit} command (or 1273equivalent) happened, 1274and @var{hostname} and @var{pathname} are for the working directory. 1275@end table 1276 1277Example: 1278 1279@c FIXME: sanity.sh should contain a similar test case 1280@c so we can compare this example from something from 1281@c Real Life(TM). See cvsclient.texi (under Notify) for more 1282@c discussion of the date format of _editors. 1283@example 1284Ffile1 _watched=;_watchers=joe>edit,mary>commit 1285Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs 1286D _watched= 1287@end example 1288 1289@noindent 1290means that the file @file{file1} should be checked out 1291read-only. Furthermore, joe is watching for edits and 1292mary is watching for commits. The file @file{file2} 1293should be checked out read-only; sue started editing it 1294on 8 Jan 1975 in the directory @file{/home/sue/cvs} on 1295the machine @code{workstn1}. Future files which are 1296added should be checked out read-only. To represent 1297this example here, we have shown a space after 1298@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact 1299there must be a single tab character there and no spaces. 1300 1301@node Locks 1302@subsection CVS locks in the repository 1303 1304@cindex #cvs.rfl, technical details 1305@cindex #cvs.wfl, technical details 1306@cindex #cvs.lock, technical details 1307@cindex Locks, cvs, technical details 1308For an introduction to @sc{cvs} locks focusing on 1309user-visible behavior, see @ref{Concurrency}. The 1310following section is aimed at people who are writing 1311tools which want to access a @sc{cvs} repository without 1312interfering with other tools accessing the same 1313repository. If you find yourself confused by concepts 1314described here, like @dfn{read lock}, @dfn{write lock}, 1315and @dfn{deadlock}, you might consult the literature on 1316operating systems or databases. 1317 1318@cindex #cvs.tfl 1319Any file in the repository with a name starting 1320with @file{#cvs.rfl.} is a read lock. Any file in 1321the repository with a name starting with 1322@file{#cvs.wfl} is a write lock. Old versions of @sc{cvs} 1323(before @sc{cvs} 1.5) also created files with names starting 1324with @file{#cvs.tfl}, but they are not discussed here. 1325The directory @file{#cvs.lock} serves as a master 1326lock. That is, one must obtain this lock fi…
Large files files are truncated, but you can click here to view the full file