PageRenderTime 77ms CodeModel.GetById 21ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/cvs/doc/cvs.texinfo

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 14187 lines | 11978 code | 2209 blank | 0 comment | 0 complexity | 5b2b61113ddb78ea6f25ebc2d0559833 MD5 | raw file

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