1@c --------------------------------------------------------------------- 2@node Repository Administration 3@unnumbered Repository Administration 4 5In @ref{An Overview of CVS}, you learned enough CVS to use it 6effectively as a project participant. If you're going to be a project 7maintainer, however, you'll need to know how to install CVS and 8administer repositories. In this chapter, we'll throw back the curtain 9and look in detail at how the repository is structured, and how CVS uses 10it. You'll learn all the major steps CVS goes through during updates 11and commits, and how you can modify its behavior. By understanding how 12CVS works, you'll also be able to trace problems to their causes, and 13fix them in maintainable ways. 14 15This may sound very involved, but remember that CVS has already proven 16quite long-lived, and will probably be around for many years to come. 17Whatever you learn now will be useful for a long time. CVS also tends 18to become more indispensable the more you use it. If you're going to be 19that dependent on something (and trust me, you are), it's worth really 20getting to know it. 21 22With that in mind, let's begin at the beginning: putting CVS on your 23system. 24 25@menu 26* Getting And Installing CVS:: Putting CVS on your system. 27* Anatomy Of A CVS Distribution:: What's in the CVS distribution. 28* Starting A Repository:: Setting up a repository. 29* The Password-Authenticating Server:: One method of remote access. 30* Anonymous Access:: Granting access to the public. 31* Repository Structure:: How the repository is arranged. 32* RCS Format:: How repository storage works. 33* What Happens When You Remove A File:: CVS keeps an Attic for old files. 34* The CVSROOT/ Administrative Directory:: Run-time server configuration files. 35* Commit Emails:: Arranging automatic commit notices. 36* Finding Out More:: Other sources of information. 37@end menu 38 39@c ----------------------------------------------------- 40@node Getting And Installing CVS 41@section Getting And Installing CVS 42 43In many cases, you won't have to go out and get CVS, because it will 44already be on your system. If you run one of the major Linux or FreeBSD 45distributions, it's probably already installed in /usr/bin or some other 46likely location. If not, Red Hat Linux users can usually find an RPM 47(Red Hat Package) for the latest, or nearly latest, version of CVS in 48their distributions. And Debian users can install the latest Debian 49package with these commands: 50 51@example 52floss$ apt-get update 53floss$ apt-get install cvs 54@end example 55 56If CVS isn't already on your machine, you'll probably have to build it 57from source. If you're a non-Unix user, you'll probably find it easier 58to get a prebuilt binary for your operating system (more on that later). 59Fortunately, CVS is fully @dfn{autoconfiscated} -- that is, it uses the 60GNU autoconfiguration mechanism, making compilation from source 61surprisingly easy. 62 63@menu 64* Getting And Building CVS Under Unix:: 65* Getting And Installing CVS Under Windows:: 66* Getting And Installing CVS On A Macintosh:: 67* Limitations Of The Windows And Macintosh Versions:: 68@end menu 69 70@c --------------------------- 71@node Getting And Building CVS Under Unix 72@subsection Getting And Building CVS Under Unix 73 74As of this writing, there are two canonical sites from which you can 75download CVS. One is the Free Software Foundation's FTP site, 76@uref{ftp://ftp.gnu.org/gnu/cvs/}, which offers CVS as an official GNU 77tool. The other is Cyclic Software's download site. Cyclic Software 78is, if not the maintainer of CVS, then the "maintainer of the 79maintainers", by providing a repository server and download access for 80users and developers. They distribute releases from 81@uref{http://download.cyclic.com/pub/}. 82 83Either location is fine. In the following example, I use Cyclic 84Software's site. If you point your FTP client (probably your Web 85browser) there, you'll see a list of directories, something like this: 86 87@example 88Index of /pub 89 cvs-1.10.5/ 18-Feb-99 21:36 - 90 cvs-1.10.6/ 17-May-99 10:34 - 91 cvs-1.10/ 09-Dec-98 17:26 - 92 macintosh/ 23-Feb-99 00:53 - 93 os2/ 09-Dec-98 17:26 - 94 packages/ 09-Dec-98 17:26 - 95 rcs/ 09-Dec-98 17:26 - 96 tkcvs/ 09-Dec-98 17:26 - 97 training/ 09-Dec-98 17:26 - 98 unix/ 09-Dec-98 17:26 - 99 vms/ 09-Dec-98 17:26 - 100@end example 101 102Pay attention to the directories beginning with "cvs-" (you can ignore 103most of the others). There are three such directories, which means that 104you're already faced with a choice: Get the designated "stable" release, 105or go with a newer (but less-tested) interim release. The stable 106releases have only one decimal point, as in "cvs-1.10", whereas the 107interim releases have minor version increments tacked on the end, as in 108"1.10.5". 109 110The GNU site usually only offers the major releases, not the interim 111ones, so you won't see all of this if you get CVS from there. In 112general, the interim releases have been pretty safe, and sometimes 113contain fixes to bugs that were found in the major release. Your best 114policy is to go with the highest interim release, but if you encounter 115any problems with it, be prepared to drop back to the previous release, 116as many times as necessary. The highest release listed in the earlier 117example is cvs-1.10.6. Entering that directory, we see this: 118 119@example 120Index of /pub/cvs-1.10.6 121 cvs-1.10.6.tar.gz 17-May-99 08:44 2.2M 122@end example 123 124That's it -- the full source code to CVS. Just download it to your 125machine, and you're ready to build. At this point, if you're already 126familiar with the standard build process for GNU tools, you know what to 127do and probably don't need to read anything between here and the section 128@ref{Anatomy Of A CVS Distribution}. On the other hand, if you're not 129sure how to proceed, then read on.... 130 131The following compilation instructions and examples assume that you have 132a fairly standard distribution of Unix. Any of the free versions of 133Unix (for example, FreeBSD or Linux) should work with no problem, as 134should the major commercial Unix versions (such as SunOS/Solaris, AIX, 135HP-UX, or Ultrix). Even if these instructions don't work for you 136exactly as written, don't give up hope. Although covering the details 137of compiling on every operating system is beyond the scope of this book, 138I'll give some pointers to other help resources later in this chapter. 139 140Anyway, to proceed with the compilation, first unpack the tar file using 141GNU gunzip and tar (if you don't have these installed on your system, 142you can get gunzip from @uref{ftp://ftp.gnu.org/gnu/gzip/} and GNU's 143version of tar from @uref{ftp://ftp.gnu.org/gnu/tar/}): 144 145@example 146floss$ gunzip cvs-1.10.6.tar.gz 147floss$ tar xvf cvs-1.10.6.tar 148@end example 149 150You'll see a lot of file names fly by on your screen. 151 152Now you have a new directory on your machine -- cvs-1.10.6 -- and it is 153populated with the CVS source code. Go into that directory and 154configure CVS for your system, by using the provided configure script: 155 156@example 157floss$ cd cvs-1.10.6 158floss$ ./configure 159creating cache ./config.cache 160checking for gcc... gcc 161checking whether we are using GNU C... yes 162checking whether gcc accepts -g... yes 163checking how to run the C preprocessor... gcc -E 164 (etc) 165@end example 166 167When the configure command finishes, the source tree will know 168everything it needs to know about compiling on your machine. The next 169step is to type: 170 171@example 172floss$ make 173@end example 174 175You'll see lots of output fly by, then type: 176 177@example 178floss$ make install 179@end example 180 181You'll see yet more output fly by; when it's all over, CVS will be 182installed on your system. (You will probably need to do that last step 183as the superuser.) 184 185By default, the CVS executable will end up as @file{/usr/local/bin/cvs}. 186This assumes you have a decent make program installed on your system 187(again, if you don't have one, get the GNU project's make from 188@uref{ftp://ftp.gnu.org/gnu/make/}). 189 190If you want CVS to install to a location other than /usr/local/bin, you 191should change how you run the initial configuration step. For example, 192 193@example 194floss$ ./configure --prefix=/usr 195@end example 196 197results in CVS being installed as /usr/bin/cvs (it always ends up as 198PREFIX/bin/cvs). The default prefix is /usr/local, which is fine for 199most installations. 200 201Note To Experienced Users: Although older versions of CVS consisted of 202more than just an executable in that they depended on having RCS 203installed as well, this has not been the case since Version 1.10. 204Therefore, you don't need to worry about any libraries or executables 205other than cvs itself. 206 207If you just intend to use CVS to access remote repositories, the 208preceding is all you need to do. If you also plan to serve a repository 209from this system, a few additional steps are necessary, which are 210covered later in this chapter. 211 212@c --------------------------- 213@node Getting And Installing CVS Under Windows 214@subsection Getting And Installing CVS Under Windows 215 216Unless you're truly religious about having the source code to your 217executable, you don't need to compile CVS from source on your Windows 218box. Unlike Unix, the necessary compilation tools probably do not 219already exist on your system, so a source build would involve first 220going out and getting those tools. Because such a project is beyond the 221scope of this book, I'll just give instructions for getting a 222precompiled CVS binary. 223 224First, note that Windows binary distributions of CVS are usually made 225only for major releases of CVS -- not for the interim releases -- and 226are not found on the GNU FTP site. So you'll need to go to Cyclic 227Software's download site, where in the major version directory, 228@uref{http://download.cyclic.com/pub/cvs-1.10/}, you'll see an extra 229subdirectory 230 231@example 232Index of /pub/cvs-1.10 233 cvs-1.10.tar.gz 14-Aug-98 09:35 2.4M 234 windows/ 235@end example 236 237inside of which is a ZIP file: 238 239@example 240Index of /pub/cvs-1.10/windows 241 cvs-1.10-win.zip 14-Aug-98 10:10 589k 242@end example 243 244This ZIP file contains a binary distribution of CVS. Download and 245extract that ZIP file: 246 247@example 248floss$ unzip cvs-1.10-win.zip 249 250Archive: cvs-1.10-win.zip 251 inflating: cvs.html 252 inflating: cvs.exe 253 inflating: README 254 inflating: FAQ 255 inflating: NEWS 256 inflating: patch.exe 257 inflating: win32gnu.dll 258@end example 259 260The README there contains detailed instructions. For most 261installations, they can be summarized as follows: Put all of the EXE and 262DLL files in a directory in your PATH. Additionally, if you're going to 263be using the pserver method to access a remote repository, you may need 264to put the following in your @file{C:\AUTOEXEC.BAT} file and reboot: 265 266@example 267set HOME=C: 268@end example 269 270This tells CVS where to store the .cvspass file. 271 272CVS running under Windows cannot currently serve repositories to remote 273machines; it can be a client (connecting to remote repositories), and 274operate in local mode (using a repository on the same machine). For the 275most part, this book assumes that CVS under Windows is operating as a 276client. However, it shouldn't be too hard to set up a local repository 277under Windows after reading the Unix-oriented instructions in the rest 278of this chapter. 279 280If you are only accessing remote repositories, you may not even need to 281run CVS. There is a tool called WinCvs that implements only the 282client-side portion of CVS. It is distributed separately from CVS 283itself but, like CVS, is freely available under the GNU General Public 284License. More information is available from @uref{http://www.wincvs.org}. 285 286@c ------------------------- 287@node Getting And Installing CVS On A Macintosh 288@subsection Getting And Installing CVS On A Macintosh 289 290CVS is available for the Macintosh, but not as part of the main 291distribution. At the moment, there are actually three separate 292Macintosh CVS clients available: 293 294@itemize 295@item MacCvs -- @uref{http://www.wincvs.org} 296@item MacCVSClient -- @uref{http://www.glink.net.hk/~jb/MacCVSClient} 297 or @uref{http://www.cyclic.com/maccvsclient/} 298@item MacCVS Pro -- @uref{http://www.maccvs.org} 299@end itemize 300 301Frankly, I have no idea which one is best. Try them all, not 302necessarily in the order given, and see which one you like. MacCVS Pro 303seems to be under active development. MacCvs is apparently a companion 304project of WinCVS and shares a home page with it. (As of this writing, a 305notice on the WinCVS page states, "Development of MacCvs will be resumed 306soon.", whatever that means.) 307 308@c ------------------------------------------------------------- 309@node Limitations Of The Windows And Macintosh Versions 310@subsection Limitations Of The Windows And Macintosh Versions 311 312The Windows and Macintosh distributions of CVS are generally limited in 313functionality. They can all act as clients, meaning that they can 314contact a repository server to obtain a working copy, commit, update, 315and so on. But they can't serve repositories themselves. If you set it 316up right, the Windows port can use a local-disk repository, but it still 317can't serve projects from that repository to other machines. In 318general, if you want to have a network-accessible CVS repository, you 319must run the CVS server on a Unix box. 320 321@c ----------------------------------------------------- 322@node Anatomy Of A CVS Distribution 323@section Anatomy Of A CVS Distribution 324 325The preceding instructions are designed to get you up and running 326quickly, but there's a lot more inside a CVS source distribution than 327just the code. Here's a quick road map to the source tree, so you'll 328know which parts are useful resources and which can be ignored. 329 330@menu 331* Informational Files:: NEWS, BUGS, FAQ, etc. 332* Subdirectories:: How the distribution is laid out. 333* The Cederqvist Manual:: The CVS Online Manual. 334* Other Sources Of Information:: Where else to find help. 335@end menu 336 337@c --------------------------------------------------- 338@node Informational Files 339@subsection Informational Files 340 341In the top level of the distribution tree, you'll find several files 342containing useful information (and pointers to further information). 343They are, in approximate order of importance: 344 345@itemize 346 347@item 348@file{NEWS} -- This file lists the changes from one release to the next, 349in reverse chronological order (that is, most recent first). If you've 350already been using CVS for a while and have just upgraded to a new 351version, you should look at the NEWS file to see what new features are 352available. Also, although most changes to CVS preserve backward 353compatibility, noncompatible changes do occur from time to time. It's 354better to read about them here than be surprised when CVS doesn't behave 355the way you expect it to. 356 357@item 358@file{BUGS} -- This file contains exactly what you think it does: a list 359of known bugs in CVS. They usually aren't show-stoppers, but you should 360read over them whenever you install a new release. 361 362@item 363@file{DEVEL-CVS} -- This file is the CVS "constitution". It describes 364the process by which changes are accepted into the main CVS distribution 365and the procedures through which a person becomes a CVS developer. You 366don't really need to read it if you just want to use CVS; however, it's 367highly interesting if you want to understand how the mostly 368uncoordinated efforts of people scattered across the globe coalesce into 369a working, usable piece of software. And of course, it's required 370reading if you plan to submit a patch (be it a bug fix or new feature) 371to CVS. 372 373@item 374@file{HACKING} -- Despite its name, the HACKING file doesn't say much 375about the design or implementation of CVS. It's mainly a guide to 376coding standards and other technical administrivia for people thinking 377of writing a patch to CVS. It can be thought of as an addendum to the 378DEVEL-CVS file. After you understand the basic philosophy of CVS 379development, you must read the HACKING file to translate that into 380concrete coding practices. 381 382@item 383@file{FAQ} -- This is the CVS "Frequently Asked Questions" document. 384Unfortunately it has a rather spotty maintenance history. David Grubbs 385took care of it until 1995, then he (presumably) got too busy and it 386languished for a while. Eventually, in 1997, Pascal Molli took over 387maintenance. Molli also didn't have time to maintain it by hand, but at 388least he found time to put it into his automated FAQ-O-Matic system, 389which allows the public to maintain the FAQ in a decentralized manner 390(basically, anyone can edit or add entries via a Web form). This was 391probably a good thing, in that at least the FAQ was once again being 392maintained; however, its overall organization and quality control are 393not on the same level as if a person were maintaining it. 394 395The master version of the FAQ is always available from Molli's Web site 396(@uref{http://www.loria.fr/~molli/cvs-index.html}, under the link 397"Documentation"). The FAQ file shipped with CVS distributions is 398generated automatically from that FAQ-O-Matic database, so by the time 399it reaches the public it's already a little bit out of date. 400Nevertheless, it can be quite helpful when you're looking for hints and 401examples about how to do something specific (say, merging a large branch 402back into the trunk or resurrecting a removed file). The best way to 403use it is as a reference document; you can bring it up in your favorite 404editor and do text searches on terms that interest you. Trying to use 405it as a tutorial would be a mistake -- it's missing too many important 406facts about CVS to serve as a complete guide. 407 408@end itemize 409 410@c ------------------------- 411@node Subdirectories 412@subsection Subdirectories 413 414The CVS distribution contains a number of subdirectories. In the course 415of a normal installation, you won't have to navigate among them, but if 416you want to go poking around in the sources, it's nice to know what each 417one does. Here they are: 418 419@example 420contrib/ 421diff/ 422doc/ 423emx/ 424lib/ 425man/ 426os2/ 427src/ 428tools/ 429vms/ 430windows-NT/ 431zlib/ 432@end example 433 434The majority of these can be ignored. The emx/, os2/, vms/, and 435windows-NT/ subdirectories all contain operating-system-specific source 436code, which you would only need if you're actually trying to debug a 437code-level problem in CVS (an unlikely situation, though not unheard 438of). The diff/ and zlib/ subdirectories contain CVS's internal 439implementations of the diff program and the GNU gzip compression 440library, respectively. (CVS uses the latter to reduce the number of bits 441it has to send over the network when accessing remote repositories.) 442 443The contrib/ and tools/ subdirectories contain free third-party software 444meant to be used with CVS. In contrib/, you will find an assortment of 445small, specialized shell scripts (read contrib/README to find out what 446they do). The tools/ subdirectory used to contain contributed software, 447but now contains a README file, which says in part: 448 449@example 450This subdirectory formerly contained tools that can be used with CVS. 451In particular, it used to contain a copy of pcl-cvs version 1.x. 452Pcl-cvs is an Emacs interface to CVS. 453 454If you are looking for pcl-cvs, we'd suggest pcl-cvs version 2.x, at: 455 ftp://ftp.weird.com/pub/local/ 456@end example 457 458The PCL-CVS package it's referring to is very handy, and I'll have more 459to say about it in @ref{Third-Party Tools}. 460 461The src/ and lib/ subdirectories contain the bulk of the CVS source 462code, which involves the CVS internals. The main data structures and 463commands are implemented in src/, whereas lib/ contains small code 464modules of general utility that CVS uses. 465 466The man/ subdirectory contains the CVS man pages (intended for the Unix 467online manual system). When you ran make install, they were 468incorporated into your Unix system's regular man pages, so you can type 469 470@example 471floss$ man cvs 472@end example 473 474and get a rather terse introduction and subcommand reference to CVS. 475Although useful as a quick reference, the man pages may not be as up to 476date or complete as the Cederqvist manual (see the next section); 477however, the man pages are more likely to be incomplete than actually 478wrong, if it's any comfort. 479 480@c ------------------------- 481@node The Cederqvist Manual 482@subsection The Cederqvist Manual 483 484That leaves the doc/ subdirectory, whose most important inhabitant is 485the famed @dfn{Cederqvist}. These days, it's probably a stretch to call 486it "the Cederqvist". Although Per Cederqvist (of Signum Support, 487Linkoping Sweden, www.signum.se) wrote the first version around 1992, it 488has been updated since then by many other people. For example, when 489contributors add a new feature to CVS, they usually also document it in 490the Cederqvist. 491 492The Cederqvist manual is written in Texinfo format, which is used by the 493GNU project because it's relatively easy to produce both online and 494printed output from it (in Info and PostScript formats, respectively). 495The Texinfo master file is doc/cvs.texinfo, but CVS distributions come 496with the Info and PostScript pregenerated, so you don't have to worry 497about running any Texinfo tools yourself. 498 499Although the Cederqvist can be used as an introduction and tutorial, it 500is probably most useful as a reference document. For that reason, most 501people browse it online instead of printing it out (although the 502PostScript file is @file{doc/cvs.ps}, for those with paper to spare). 503If this is the first time you've installed CVS on your system, you'll 504have to take an extra step to make sure the manual is accessible online. 505 506The Info files (doc/cvs.info, doc/cvs.info-1, doc/cvs.info-2, and so on) 507were installed for you when you ran make install. Although the files 508were copied into the system's Info tree, you may still have to add a 509line for CVS to the Info table of contents, the "Top" node. (This will 510only be necessary if this is the first time CVS has been installed on 511your system; otherwise, the entry from previous installations should 512already be in the table of contents.) 513 514If you've added new Info documentation before, you may be familiar with 515the process. First figure out where the Info pages were installed. If 516you used the default installation (in /usr/local/), then the Info files 517are /usr/local/info/cvs.info*. If you installed using 518 519@example 520floss$ ./configure --prefix=/usr 521@end example 522 523the files ended up as /usr/info/cvs.*. After you locate the files, 524you'll need to add a line for CVS to the Info table of contents, which 525is in a file named dir in that directory (so in the latter case, it 526would be /usr/info/dir). If you don't have root access, ask your system 527administrator to do it. Here is an excerpt from dir before the 528reference to CVS documentation was added: 529 530@example 531* Bison: (bison). The Bison parser generator. 532* Cpp: (cpp). The GNU C preprocessor. 533* Flex: (flex). A fast scanner generator 534@end example 535 536And here is the same region of dir afterwards: 537 538@example 539* Bison: (bison). The Bison parser generator. 540* Cpp: (cpp). The GNU C preprocessor. 541* Cvs: (cvs). Concurrent Versions System 542* Flex: (flex). A fast scanner generator 543@end example 544 545The format of the line is very important. You must include the 546asterisk, spaces, and colon in @w{@samp{* Cvs:}} and the parentheses and 547period in @samp{(cvs).} after it. If any of these elements are missing, 548the Info dir format will be corrupt, and you'll be unable to read the 549Cederqvist. 550 551Once the manual is installed and referred to from the table of contents, 552you can read it with any Info-compatible browser. The ones most likely 553to be installed on a typical Unix system are either the command-line 554Info reader, which can be invoked this way if you want to go straight to 555the CVS pages 556 557@example 558floss$ info cvs 559@end example 560 561and the one within Emacs, which is invoked by typing 562 563@example 564M-x info 565@end example 566 567or 568 569@example 570C-h i 571@end example 572 573Take whatever time is necessary to get the Cederqvist set up properly on 574your system when you install CVS; it will pay off many times down the 575road when you need to look something up. 576 577@c ------------------------- 578@node Other Sources Of Information 579@subsection Other Sources Of Information 580 581In addition to the Cederqvist, the FAQ, and the other files in the 582distribution itself, there are Internet resources devoted to CVS. If 583you're going to administrate a CVS server, you'll probably want to join 584the info-cvs mailing list. To subscribe, send email to 585@email{info-cvs-request@@gnu.org} (the list itself is 586@email{info-cvs@@gnu.org}). Traffic can be medium to heavy, around 10 587to 20 emails a day, most of them questions seeking answers. The 588majority of these can be deleted without reading (unless you want to 589help people by answering their questions, which is always nice), but 590every now and then someone will announce the discovery of a bug or 591announce a patch that implements some feature you've been wanting. 592 593You can also join the formal bug report mailing list, which includes 594every bug report sent in. This probably isn't necessary, unless you 595intend to help fix the bugs, which would be great, or you're 596terrifically paranoid and want to know about every problem other people 597find with CVS. If you do want to join, send email to 598@email{bug-cvs-request@@gnu.org}. 599 600There's also a Usenet newsgroup, @code{comp.software.config-mgmt}, which 601is about version control and configuration management systems in 602general, in which there is a fair amount of discussion about CVS. 603 604Finally, there are at least three Web sites devoted to CVS. Cyclic 605Software's @uref{http://www.cyclic.com} has been CVS's informal home 606site for a few years, and probably will continue to be for the 607foreseeable future. Cyclic Software also provides server space and Net 608access for the repository where the CVS sources are kept. The Cyclic 609Web pages contain comprehensive links to experimental patches for CVS, 610third-party tools that work with CVS, documentation, mailing list 611archives, and just about everything else. If you can't find what you 612need in the distribution, @uref{http://www.cyclic.com} is the place to 613start looking. 614 615Two other good sites are Pascal Molli's 616@uref{http://www.loria.fr/~molli/cvs-index.html} and Sean Dreilinger's 617@uref{http://durak.org/cvswebsites/}. The biggest attraction at Molli's 618site is, of course, the FAQ, but it also has links to CVS-related tools 619and mailing list archives. Dreilinger's site specializes in information 620about using CVS to manage Web documents and also has a CVS-specific 621search engine. 622 623@c ----------------------------------------------------- 624@node Starting A Repository 625@section Starting A Repository 626 627Once the CVS executable is installed on your system, you can start using 628it right away as a client to access remote repositories, following the 629procedures described in @ref{An Overview of CVS}. However, if you want 630to serve revisions from your machine, you have to create a repository 631there. The command to do that is 632 633@example 634floss$ cvs -d /usr/local/newrepos init 635@end example 636 637where @file{/usr/local/newrepos} is a path to wherever you want the 638repository to be (of course, you must have write permission to that 639location, which may imply running the command as the root user). It may 640seem somewhat counterintuitive that the location of the new repository 641is specified before the init subcommand instead of after it, but by 642using the -d option, it stays consistent with other CVS commands. 643 644The command will return silently after it is run. Let's examine the new 645directory: 646 647@example 648floss$ ls -ld /usr/local/newrepos 649drwxrwxr-x 3 root root 1024 Jun 19 17:59 /usr/local/newrepos/ 650floss$ cd /usr/local/newrepos 651floss$ ls 652CVSROOT 653floss$ cd CVSROOT 654floss$ ls 655checkoutlist config,v history notify taginfo,v 656checkoutlist,v cvswrappers loginfo notify,v verifymsg 657commitinfo cvswrappers,v loginfo,v rcsinfo verifymsg,v 658commitinfo,v editinfo modules rcsinfo,v 659config editinfo,v modules,v taginfo 660 661floss$ 662@end example 663 664The single subdirectory in the new repository -- CVSROOT/ -- contains 665various administrative files that control CVS's behavior. Later on, 666we'll examine those files one by one; for now, the goal is just to get 667the repository working. In this case, "working" means users can import, 668check out, update, and commit projects. 669 670Don't confuse the CVSROOT environment variable introduced in @ref{An 671Overview of CVS} with this CVSROOT subdirectory in the repository. They 672are unrelated -- it is an unfortunate coincidence that they share the 673same name. The former is a way for users to avoid having to type 674@w{@samp{-d <repository-location>}} every time they use CVS; the latter 675is the administrative subdirectory of a repository. 676 677Once the repository is created, you must take care of its permissions. 678CVS does not require any particular, standardized permission or file 679ownership scheme; it merely needs write access to the repository. 680However -- partly for security reasons, but mainly for your own sanity 681as an administrator -- I highly recommend that you take the following 682steps: 683 684@enumerate 685 686@item 687Add a Unix group @code{cvs} to your system. Any users who need to 688access the repository should be in this group. For example, here's the 689relevant line from my machine's @file{/etc/group} file: 690 691@example 692cvs:*:105:kfogel,sussman,jimb,noel,lefty,fitz,craig,anonymous,jrandom 693@end example 694 695@item 696Make the repository's group ownership and permissions reflect this new 697group: 698 699@example 700floss$ cd /usr/local/newrepos 701floss$ chgrp -R cvs . 702floss$ chmod ug+rwx . CVSROOT 703@end example 704 705@end enumerate 706 707Now any of the users listed in that group can start a project by running 708@w{@code{cvs import}}, as described in @ref{An Overview of CVS}. 709Checkout, update, and commit should work as well. They can also reach 710the repository from remote locations by using the @code{:ext:} method, 711assuming that they have rsh or ssh access to the repository 712machine. (You may have noticed that the chgrp and chmod commands in that 713example gave write access to a user named @code{anonymous}, which is not 714what one would expect. The reason is that even anonymous, read-only 715repository users need system-level write access, so that their CVS 716processes can create temporary lockfiles inside the repository. CVS 717enforces the "read-only" restriction of anonymous access not through 718Unix file permissions, but by other means, which will be covered in 719@ref{Anonymous Access}.) 720 721If your repository is intended to serve projects to the general public, 722where contributors won't necessarily have accounts on the repository 723machine, you should set up the password-authenticating server now 724(@pxref{The Password-Authenticating Server}). It's necessary for 725anonymous read-only access, and it's also probably the easiest way to 726grant commit access to certain people without giving them full accounts 727on the machine. 728 729@c ----------------------------------------------------- 730@node The Password-Authenticating Server 731@section The Password-Authenticating Server 732 733Before running through the steps needed to set up the password server, 734let's examine how such connections work in the abstract. When a remote 735CVS client uses the @code{:pserver:} method to connect to a repository, 736the client is actually contacting a specific port number on the server 737machine -- specifically, port number 2401 (which is 49 squared, if you 738like that sort of thing). Port 2401 is the designated default port for 739the CVS pserver, although one could arrange for a different port to be 740used as long as both client and server agree on it. 741 742The CVS server is not actually waiting for connections at that port -- 743the server won't get started up until a connection actually arrives. 744Instead, the Unix inetd (InterNET Daemon) program is listening on that 745port, and needs to know that when it receives a connection request 746there, it should start up the CVS server and connect it to the incoming 747client. 748 749This is accomplished by modifying inetd's configuration files: 750@file{/etc/services} and @file{/etc/inetd.conf}. The services file maps 751raw port numbers to service names and then inetd.conf tells inetd what 752to do for a given service name. 753 754First, put a line like this into /etc/services (after checking to make 755sure it isn't already there): 756 757@example 758cvspserver 2401/tcp 759@end example 760 761Then in /etc/inetd.conf, put this: 762 763@example 764cvspserver stream tcp nowait root /usr/local/bin/cvs cvs \ 765 --allow-root=/usr/local/newrepos pserver 766@end example 767 768(In the actual file, this should be all one long line, with no 769backslash.) If your system uses tcpwrappers, you may want to use 770something like this instead: 771 772@example 773cvspserver stream tcp nowait root /usr/sbin/tcpd /usr/local/bin/cvs \ 774 --allow-root=/usr/local/newrepos pserver 775@end example 776 777Now, restart inetd so it notices the changes to its configuration files 778(if you don't know how to restart the daemon, just reboot the machine -- 779that will work too). 780 781That's enough to permit connections, but you'll also want to set up 782special CVS passwords -- separate from the users' regular login 783passwords -- so people can access the repository without compromising 784overall system security. 785 786The CVS password file is CVSROOT/passwd in the repository. It was not 787created by default when you ran cvs init, because CVS doesn't know for 788sure that you'll be using pserver. Even if the password file had been 789created, CVS would have no way of knowing what usernames and passwords 790to create. So, you'll have to create one yourself; here's a sample 791CVSRoot/passwd file: 792 793@example 794kfogel:rKa5jzULzmhOo 795anonymous:XR4EZcEs0szik 796melissa:tGX1fS8sun6rY:pubcvs 797@end example 798 799The format is as simple as it looks. Each line is: 800 801@c todo: get rid of angle brackets here? 802@example 803<USERNAME>:<ENCRYPTED_PASSWORD>:<OPTIONAL_SYSTEM_USERNAME> 804@end example 805 806The extra colon followed by an optional system username tells CVS that 807connections authenticated with USERNAME should run as the system account 808SYSTEM_USERNAME -- in other words, that CVS session would only be able 809to do things in the repository that someone logged in as SYSTEM_USERNAME 810could do. 811 812If no system username is given, USERNAME must match an actual login 813account name on the system, and the session will run with that user's 814permissions. In either case, the encrypted password should not be the 815same as the user's actual login password. It should be an independent 816password used only for CVS pserver connections. 817 818The password is encrypted using the same algorithm as the standard Unix 819system passwords stored in /etc/passwd. You may be wondering at this 820point, how does one acquire an encrypted version of a password? For 821Unix system passwords, the passwd command takes care of the encryption 822in /etc/passwd for you. Unfortunately, there is no corresponding cvs 823passwd command (it has been proposed several times, but no one's gotten 824around to writing it -- perhaps you'll do it?). 825 826This is an inconvenience, but only a slight one. If nothing else, you 827can always temporarily change a regular user's system password using 828passwd, cut and paste the encrypted text from /etc/passwd into 829CVSROOT/passwd, and then restore the old password (note that on some 830systems, the encrypted passwords are found in /etc/shadow and are 831readable only by root.) 832 833That scheme is workable but rather cumbersome. It would be much easier 834to have a command-line utility that takes a plain text password as its 835argument and outputs the encrypted version. Here is such a tool, 836written in Perl: 837 838@example 839#!/usr/bin/perl 840 841srand (time()); 842my $randletter = "(int (rand (26)) + (int (rand (1) + .5) % 2 ? 65 : 97))"; 843my $salt = sprintf ("%c%c", eval $randletter, eval $randletter); 844my $plaintext = shift; 845my $crypttext = crypt ($plaintext, $salt); 846 847print "$@{crypttext@}\n"; 848@end example 849 850I keep the preceding script in @file{/usr/local/bin/cryptout.pl}: 851 852@example 853floss$ ls -l /usr/local/bin/cryptout.pl 854 855-rwxr-xr-x 1 root root 265 Jun 14 20:41 /usr/local/bin/cryptout.pl 856floss$ cryptout.pl "some text" 857sB3A79YDX5L4s 858 859floss$ 860@end example 861 862If I took the output of this example and used it to create the following 863entry in CVSROOT/passwd 864 865@example 866jrandom:sB3A79YDX5L4s:craig 867@end example 868 869then someone could connect to the repository with the following command: 870 871@example 872remote$ cvs -d :pserver:jrandom@@floss.red-bean.com:/usr/local/newrepos login 873@end example 874 875They could then type @code{some text} as their password and thereafter 876be able to execute CVS commands with the same access privileges as the 877system user @code{craig}. 878 879If someone attempts to authenticate with a username and password that 880don't appear in CVSROOT/passwd, CVS will check to see if that username 881and password are present in /etc/passwd. If they are (and if the 882password matches, of course), CVS will grant access. It behaves this 883way for the administrator's convenience, so that separate CVSROOT/passwd 884entries don't have to be set up for regular system users. However, this 885behavior is also a security hole, because it means that if one of those 886users does connect to the CVS server, her regular login password will 887have crossed over the network in cleartext, potentially vulnerable to 888the eyes of password sniffers. A bit further on, you'll learn how to 889turn off this "fallback" behavior, so that CVS consults only its own 890passwd file. Whether you leave it on or off, you should probably force 891any CVS users who also have login accounts to maintain different 892passwords for the two functions. 893 894Although the passwd file authenticates for the whole repository, with a 895little extra work you can still use it to grant project-specific access. 896Here's one method: 897 898Suppose you want to grant some remote developers access to project 899@code{foo}, and others access to project @code{bar}, and you don't want 900developers from one project to have commit access to the other. You can 901accomplish this by creating project-specific user accounts and groups on 902the system and then mapping to those accounts in the CVSROOT/passwd 903file. 904 905Here's the relevant excerpt from /etc/passwd 906 907@example 908cvs-foo:*:600:600:Public CVS Account for Project Foo:/usr/local/cvs:/bin/false 909cvs-bar:*:601:601:Public CVS Account for Project Bar:/usr/local/cvs:/bin/false 910@end example 911 912and from /etc/group 913 914@example 915cvs-foo:*:600:cvs-foo 916cvs-bar:*:601:cvs-bar 917@end example 918 919and, finally, CVSROOT/passwd: 920 921@example 922kcunderh:rKa5jzULzmhOo:cvs-foo 923jmankoff:tGX1fS8sun6rY:cvs-foo 924brebard:cAXVPNZN6uFH2:cvs-foo 925xwang:qp5lsf7nzRzfs:cvs-foo 926dstone:JDNNF6HeX/yLw:cvs-bar 927twp:glUHEM8KhcbO6:cvs-bar 928ffranklin:cG6/6yXbS9BHI:cvs-bar 929yyang:YoEqcCeCUq1vQ:cvs-bar 930@end example 931 932Some of the CVS usernames map onto the system user account 933@code{cvs-foo} and some onto @code{cvs-bar}. Because CVS runs under the 934user ID of the system account, you just have to make sure that the 935relevant parts of the repository are writeable only by the appropriate 936users and groups. If you just make sure that the user accounts are 937locked down pretty tight (no valid login password, @file{/bin/false} as 938the shell), then this system is reasonably secure (but see later in this 939chapter about CVSROOT permissions!). Also, CVS does record changes and 940log messages under the CVS username, not the system username, so you can 941still tell who is responsible for a given change. 942 943 944@c ----------------------------------------------------- 945@node Anonymous Access 946@section Anonymous Access 947 948So far we've only seen how to use the password-authenticating server to 949grant normal full access to the repository (although admittedly one can 950restrict that access through carefully arranged Unix file permissions). 951Turning this into anonymous, read-only access is a simple step: You just 952have to add a new file, or possibly two, in CVSROOT/. The files' names 953are @code{readers} and @code{writers} -- the former containing a list of 954usernames who can only read the repository, the latter users who can 955read and write. 956 957If you list a username in CVSROOT/readers, that user will have only read 958access to all projects in the repository. If you list a username in 959CVSROOT/writers, that user will have write access, and every pserver 960user not listed in writers will have read-only access (that is, if the 961writers file exists at all, it implies read-only access for all those 962not listed in it). If the same username is listed in both files, CVS 963resolves the conflict in the more conservative way: the user will have 964read-only access. 965 966The format of the files is very simple: one user per line (don't forget 967to put a newline after the last user). Here is a sample readers file: 968 969@example 970anonymous 971splotnik 972guest 973jbrowse 974@end example 975 976Note that the files apply to CVS usernames, not system usernames. If 977you use user aliasing in the CVSROOT/passwd file (putting a system 978username after a second colon), the leftmost username is the one to list 979in a readers or writers file. 980 981Just to be painfully accurate about it, here is a formal description of 982the server's behavior in deciding whether to grant read-only or 983read-write access: 984 985If a readers file exists and this user is listed in it, then she gets 986read-only access. If a writers file exists and this user is not listed 987in it, then she also gets read-only access (this is true even if a 988readers file exists but that person is not listed there). If that 989person is listed in both, she gets read-only access. In all other 990cases, that person gets full read-write access. 991 992Thus, a typical repository with anonymous CVS access has this (or 993something like it) in CVSROOT/passwd 994 995@example 996anonymous:XR4EZcEs0szik 997@end example 998 999this (or something like it) in /etc/passwd 1000 1001@example 1002anonymous:!:1729:105:Anonymous CVS User:/usr/local/newrepos:/bin/false 1003@end example 1004 1005and this in CVSROOT/readers: 1006 1007@example 1008anonymous 1009@end example 1010 1011And, of course, the aforementioned setup in /etc/services and 1012/etc/inetd.conf. That's all there is to it! 1013 1014Note that some older Unix systems don't support usernames longer than 1015eight characters. One way to get around this would be to call the user 1016@code{anon} instead of @code{anonymous} in CVSROOT/passwd and in the 1017system files, because people often assume that anon is short for 1018anonymous anyway. But it might be better to put something like this 1019into the CVSROOT/passwd file 1020 1021@example 1022anonymous:XR4EZcEs0szik:cvsanon 1023@end example 1024 1025(and then of course use @code{cvsanon} in the system files). That way, 1026you'd be able to publish a repository address that uses 1027@code{anonymous}, which is more or less standard now. People accessing 1028the repository with 1029 1030@example 1031cvs -d :pserver:anonymous@@cvs.foobar.com:/usr/local/newrepos (etc...) 1032@end example 1033 1034would actually run on the server as cvsanon (or whatever). But they 1035wouldn't need to know or care about how things are set up on the server 1036side -- they'd only see the published address. 1037 1038@c ----------------------------------------------------- 1039@node Repository Structure 1040@section Repository Structure 1041 1042The new repository still has no projects in it. Let's re-run the 1043initial import from @ref{An Overview of CVS}, watching what happens to 1044the repository. (For simplicity's sake, all commands will assume that 1045the CVSROOT environment variable has been set to /usr/local/newrepos, so 1046there's no need to specify the repository with -d on imports and 1047checkouts.) 1048 1049@example 1050floss$ ls /usr/local/newrepos 1051CVSROOT/ 1052floss$ pwd 1053/home/jrandom/src/ 1054floss$ ls 1055myproj/ 1056floss$ cd myproj 1057floss$ cvs import -m "initial import into CVS" myproj jrandom start 1058N myproj/README.txt 1059N myproj/hello.c 1060cvs import: Importing /usr/local/newrepos/myproj/a-subdir 1061N myproj/a-subdir/whatever.c 1062cvs import: Importing /usr/local/newrepos/myproj/a-subdir/subsubdir 1063N myproj/a-subdir/subsubdir/fish.c 1064cvs import: Importing /usr/local/newrepos/myproj/b-subdir 1065N myproj/b-subdir/random.c 1066 1067No conflicts created by this import 1068 1069floss$ ls /usr/local/newrepos 1070CVSROOT/ myproj/ 1071floss$ cd /usr/local/newrepos/myproj 1072floss$ ls 1073README.txt,v a-subdir/ b-subdir/ hello.c,v 1074floss$ cd a-subdir 1075floss$ ls 1076subsubdir/ whatever.c,v 1077floss$ cd .. 1078 1079floss$ 1080@end example 1081 1082Before the import, the repository contained only its administrative 1083area, CVSROOT. After the import, a new directory -- @file{myproj} -- 1084appeared. The files and subdirectories inside that new directory look 1085suspiciously like the project we imported, except that the files have 1086the suffix @code{,v}. These are RCS-format version control files (the 1087@code{,v} stands for "version"), and they are the backbone of the 1088repository. Each RCS file stores the revision history of its 1089corresponding file in the project, including all branches and tags. 1090 1091@c ----------------------------------------------------- 1092@node RCS Format 1093@section RCS Format 1094 1095You do not need to know any of the RCS format to use CVS (although there 1096is an excellent writeup included with the source distribution, see 1097doc/RCSFILES). However, a basic understanding of the format can be of 1098immense help in troubleshooting CVS problems, so we'll take a brief peek 1099into one of the files, @file{hello.c,v}. Here are its contents: 1100 1101@example 1102head 1.1; 1103branch 1.1.1; 1104access ; 1105symbols start:1.1.1.1 jrandom:1.1.1; 1106locks ; strict; 1107comment @@ * @@; 1108 11091.1 1110date 99.06.20.17.47.26; author jrandom; state Exp; 1111branches 1.1.1.1; 1112next; 1113 11141.1.1.1 1115date 99.06.20.17.47.26; author jrandom; state Exp; 1116branches ; 1117next; 1118 1119desc 1120@@@@ 1121 11221.1 1123log 1124@@Initial revision 1125@@ 1126text 1127@@#include <stdio.h> 1128 1129void 1130main () 1131@{ 1132 printf ("Hello, world!\n"); 1133@} 1134@@ 1135 11361.1.1.1 1137log 1138@@initial import into CVS 1139@@ 1140text 1141@@@@ 1142@end example 1143 1144Whew! Most of that you can ignore; don't worry about the relationship 1145between 1.1 and 1.1.1.1, for example, or the implied 1.1.1 branch -- 1146they aren't really significant from a user's or even an administrator's 1147point of view. What you should try to grok is the overall format. At 1148the top is a collection of header fields: 1149 1150@example 1151head 1.1; 1152branch 1.1.1; 1153access ; 1154symbols start:1.1.1.1 jrandom:1.1.1; 1155locks ; strict; 1156comment @@ * @@; 1157@end example 1158 1159Farther down in the file are groups of meta-information about each 1160revision (but still not showing the contents of that revision), such as: 1161 1162@example 11631.1 1164date 99.06.20.17.47.26; author jrandom; state Exp; 1165branches 1.1.1.1; 1166next ; 1167@end example 1168 1169And finally, the log message and text of an actual revision: 1170 1171@example 11721.1 1173log 1174@@Initial revision 1175@@ 1176text 1177@@#include <stdio.h> 1178 1179void 1180main () 1181@{ 1182 printf ("Hello, world!\n"); 1183@} 1184@@ 1185 11861.1.1.1 1187log 1188@@initial import into CVS 1189@@ 1190text 1191@@@@ 1192@end example 1193 1194If you look closely, you'll see that the first revision's contents are 1195stored under the heading 1.1, but that the log message there is "Initial 1196revision", whereas the log message we actually used at import time was 1197"initial import into CVS", which appears farther down, under 1198@code{Revision 1.1.1.1}. You don't need to worry about this discrepancy 1199right now. It happens because imports are a special circumstance: In 1200order to make repeated imports into the same project have a useful 1201effect, import actually places the initial revision on both the main 1202trunk and on a special branch (the reasons for this will become clearer 1203when we look at vendor branches in @ref{Advanced CVS}). For now, you 1204can treat @code{1.1} and @code{1.1.1.1} as the same thing. 1205 1206The file becomes even more revealing after we commit the first 1207modification to hello.c: 1208 1209@example 1210floss$ cvs -Q co myproj 1211floss$ cd myproj 1212floss$ emacs hello.c 1213 (make some changes to the file) 1214 1215floss$ cvs ci -m "print goodbye too" 1216cvs commit: Examining . 1217cvs commit: Examining a-subdir 1218cvs commit: Examining a-subdir/subsubdir 1219cvs commit: Examining b-subdir 1220Checking in hello.c; 1221/usr/local/newrepos/myproj/hello.c,v <-- hello.c 1222new revision: 1.2; previous revision: 1.1 1223done 1224@end example 1225 1226If you look at hello.c,v in the repository now, you can see the effect 1227of the commit: 1228 1229@example 1230head 1.2; 1231access; 1232symbols 1233 start:1.1.1.1 jrandom:1.1.1; 1234locks; strict; 1235comment @@ * @@; 1236 12371.2 1238date 99.06.21.01.49.40; author jrandom; state Exp; 1239branches; 1240next 1.1; 1241 12421.1 1243date 99.06.20.17.47.26; author jrandom; state Exp; 1244branches 1245 1.1.1.1; 1246next ; 1247 12481.1.1.1 1249date 99.06.20.17.47.26; author jrandom; state Exp; 1250branches; 1251next ; 1252 1253desc 1254@@@@ 1255 12561.2 1257log 1258@@print goodbye too 1259@@ 1260text 1261@@#include <stdio.h> 1262 1263void 1264main () 1265@{ 1266 printf ("Hello, world!\n"); 1267 printf ("Goodbye, world!\n"); 1268@} 1269@@ 1270 12711.1 1272log 1273@@Initial revision 1274@@ 1275text 1276@@d7 1 1277@@ 1278 12791.1.1.1 1280log 1281@@initial import into CVS 1282@@ 1283text 1284@@@@ 1285@end example 1286 1287Now the full contents of Revision 1.2 are stored in the file, and the 1288text for Revision 1.1 has been replaced with the cryptic formula: 1289 1290@example 1291d7 1 1292@end example 1293 1294The @w{@code{d7 1}} is a diff code that means "starting at line 7, 1295delete 1 line". In other words, to derive Revision 1.1, delete line 7 1296from Revision 1.2! Try working through it yourself. You'll see that it 1297does indeed produce Revision 1.1 -- it simply does away with the line we 1298added to the file. 1299 1300This demonstrates the basic principle of RCS format: It stores only the 1301differences between revisions, thereby saving a lot of space compared 1302with storing each revision in full. To go backwards from the most 1303recent revision to the previous one, it patches the later revision using 1304the stored diff. Of course, this means that the further back you travel 1305in the revision history, the more patch operations must be performed 1306(for example, if the file is on Revision 1.7 and CVS is asked to 1307retrieve Revision 1.4, it has to produce 1.6 by patching backwards from 13081.7, then 1.5 by patching 1.6, then 1.4 by patching 1.5). Fortunately, 1309old revisions are also the ones least often retrieved, so the RCS system 1310works out pretty well in practice: The more recent the revision, the 1311cheaper it is to obtain. 1312 1313As for the header information at the top of the file, you don't need to 1314know what all of it means. However, the effects of certain operations 1315show up very clearly in the headers, and a passing familiarity with them 1316may prove useful. 1317 1318When you commit a new revision on the trunk, the @code{head} label is 1319updated (note how it became 1.2 in the preceding example, when the 1320second revision to hello.c was committed). When you add a file as 1321binary or tag it, those operations are recorded in the headers as well. 1322As an example, we'll add foo.jpg as a binary file and then tag it a 1323couple of times: 1324 1325@example 1326floss$ cvs add -kb foo.jpg 1327cvs add: scheduling file 'foo.jpg' for addition 1328cvs add: use 'cvs commit' to add this file permanently 1329floss$ cvs -q commit -m "added a random image; ask jrandom@@red-bean.com why" 1330RCS file: /usr/local/newrepos/myproj/foo.jpg,v 1331done 1332Checking in foo.jpg; 1333/usr/local/newrepos/myproj/foo.jpg,v <-- foo.jpg 1334initial revision: 1.1 1335done 1336floss$ cvs tag some_random_tag foo.jpg 1337T foo.jpg 1338floss$ cvs tag ANOTHER-TAG foo.jpg 1339T foo.jpg 1340floss$ 1341@end example 1342 1343Now examine the header section of foo.jpg,v in the repository: 1344 1345@example 1346head 1.1; 1347access; 1348symbols 1349 ANOTHER-TAG:1.1 1350 some_random_tag:1.1; 1351locks; strict; 1352comment @@# @@; 1353expand @@b@@; 1354@end example 1355 1356Notice the b in the expand line at the end -- it's due to our having 1357used the -kb flag when adding the file, and means the file won't undergo 1358any keyword or newline expansions, which would normally occur during 1359checkouts and updates if it were a regular text file. The tags appear 1360in the symbols section, one tag per line -- both of them are attached to 1361the first revision, since that's what was tagged both times. (This also 1362helps explain why tag names can only contain letters, numbers, hyphens, 1363and underscores. If the tag itself contained colons or dots, the RCS 1364file's record of it might be ambiguous, because there would be no way to 1365find the textual boundary between the tag and the revision to which it 1366is attached.) 1367 1368@c ----------------------------------------------------- 1369@heading RCS Format Always Quotes @@ Signs 1370 1371The @code{@@} symbol is used as a field delimiter in RCS files, which 1372means that if one appears in the text of a file or in a log message, it 1373must be quoted (otherwise, CVS would incorrectly interpret it as marking 1374the end of that field). It is quoted by doubling -- that is, CVS always 1375interprets @code{@@@@} as "literal @@ sign", never as "end of current 1376field". When we committed foo.jpg, the log message was 1377 1378@example 1379"added a random image; ask jrandom@@red-bean.com why" 1380@end example 1381 1382which is stored in foo.jpg,v like this: 1383 1384@example 13851.1 1386log 1387@@added a random image; ask jrandom@@@@red-bean.com why 1388@@ 1389@end example 1390 1391The @@ sign in jrandom@@@@red-bean.com will be automatically unquoted 1392whenever CVS retrieves the log message: 1393 1394@example 1395floss$ cvs log foo.jpg 1396RCS file: /usr/local/newrepos/myproj/foo.jpg,v 1397Working file: foo.jpg 1398head: 1.1 1399branch: 1400locks: strict 1401access list: 1402symbolic names: 1403 ANOTHER-TAG: 1.1 1404 some_random_tag: 1.1 1405keyword substitution: b 1406total revisions: 1; selected revisions: 1 1407description: 1408---------------------------- 1409revision 1.1 1410date: 1999/06/21 02:56:18; author: jrandom; state: Exp; 1411added a random image; ask jrandom@@red-bean.com why 1412============================================================================ 1413 1414floss$ 1415@end example 1416 1417The only reason you should care is that if you ever find yourself 1418hand-editing RCS files (a rare circumstance, but not unheard of), you 1419must remember to use double @@ signs in revision contents and log 1420messages. If you don't, the RCS file will be corrupt and will probably 1421exhibit strange and undesirable behaviors. 1422 1423Speaking of hand-editing RCS files, don't be fooled by the permissions 1424in the repository: 1425 1426@example 1427floss$ ls -l 1428total 6 1429-r--r--r-- 1 jrandom users 410 Jun 20 12:47 README.txt,v 1430drwxrwxr-x 3 jrandom users 1024 Jun 20 21:56 a-subdir/ 1431drwxrwxr-x 2 jrandom users 1024 Jun 20 21:56 b-subdir/ 1432-r--r--r-- 1 jrandom users 937 Jun 20 21:56 foo.jpg,v 1433-r--r--r-- 1 jrandom users 564 Jun 20 21:11 hello.c,v 1434 1435floss$ 1436@end example 1437 1438(For those not fluent in Unix ls output, the @code{-r--r--r--} lines on 1439the left essentially mean that the files can be read but not changed.) 1440Although the files appear to be read-only for everyone, the directory 1441permissions must also be taken into account: 1442 1443@example 1444floss$ ls -ld . 1445drwxrwxr-x 4 jrandom users 1024 Jun 20 22:16 ./ 1446floss$ 1447@end example 1448 1449The myproj/ directory itself -- and its subdirectories -- are all 1450writeable by the owner (jrandom) and the group (users). This means that 1451CVS (running as jrandom, or as anyone in the users group) can create and 1452delete files in those directories, even if it can't directly edit files 1453already present. CVS edits an RCS file by making a separate copy of it, 1454so you should also make all of your changes in a temporary copy, and 1455then replace the existing RCS file with the new one. (But please don't 1456ask why the files themselves are read-only -- there are historical 1457reasons for that, having to do with the way RCS works when run as a 1458standalone program.) 1459 1460Incidentally, having the files' group be @code{users} is probably not 1461what you want, considering that the top-level directory of the 1462repository was explicitly assigned group @code{cvs}. You can correct 1463the problem by running this command inside the repository: 1464 1465@example 1466floss$ cd /usr/local/newrepos 1467floss$ chgrp -R cvs myproj 1468@end example 1469 1470The usual Unix file-creation rules govern which group is assigned to new 1471files that appear in the repository, so once in a while you may need to 1472run chgrp or chmod on certain files or directories in the repository 1473(setting the SGID bit with @w{@code{chmod g+s}} is often a good 1474strategy: it makes children of a directory inherit the directory's group 1475ownership, which is usually what you want in the repository). There are 1476no hard and fast rules about how you should structure repository 1477permissions; it just depends on who is working on what projects. 1478 1479@c ----------------------------------------------------- 1480@node What Happens When You Remove A File 1481@section What Happens When You Remove A File 1482 1483When you remove a file from a project, it doesn't just disappear. CVS 1484must be able to retrieve such files when you request an old snapshot of 1485the project. Instead, the file gets put in the @code{Attic}, literally: 1486 1487@example 1488floss$ pwd 1489/home/jrandom/src/myproj 1490floss$ ls /usr/local/newrepos/myproj/ 1491README.txt,v a-subdir/ b-subdir/ foo.jpg,v hello.c,v 1492floss$ rm foo.jpg 1493floss$ cvs rm foo.jpg 1494cvs remove: scheduling 'foo.jpg' for removal 1495cvs remove: use 'cvs commit' to remove this file permanently 1496floss$ cvs ci -m "Removed foo.jpg" foo.jpg 1497Removing foo.jpg; 1498/usr/local/newrepos/myproj/foo.jpg,v <-- foo.jpg 1499new revision: delete; previous revision: 1.1 1500done 1501floss$ cd /usr/local/newrepos/myproj/ 1502floss$ ls 1503Attic/ README.txt,v a-subdir/ b-subdir/ hello.c,v 1504floss$ cd Attic 1505floss$ ls 1506foo.jpg,v 1507floss$ 1508@end example 1509 1510In each repository directory of a project, the presence of an 1511@file{Attic/} subdirectory means that at least one file has been removed 1512from that directory (this means that you shouldn't use directories named 1513Attic in your projects). CVS doesn't merely move the RCS file into 1514Attic/, however; it also commits a new revision into the file, with a 1515special revision state of @code{dead}. Here's the relevant section from 1516Attic/foo.jpg,v: 1517 1518@example 15191.2 1520date 99.06.21.03.38.07; author jrandom; state dead; 1521branches; 1522next 1.1; 1523@end example 1524 1525If the file is later brought back to life, CVS has a way of recording 1526that it was dead at some point in the past and is now alive again. 1527 1528This means that if you want to restore a removed file, you can't just 1529take it out of the Attic/ and put it back into the project. Instead, 1530you have to do something like this in a working copy: 1531 1532@example 1533floss$ pwd 1534/home/jrandom/src/myproj 1535floss$ cvs -Q update -p -r 1.1 foo.jpg > foo.jpg 1536floss$ ls 1537CVS/ README.txt a-subdir/ b-subdir/ foo.jpg hello.c 1538floss$ cvs add -kb foo.jpg 1539cvs add: re-adding file foo.jpg (in place of dead revision 1.2) 1540cvs add: use 'cvs commit' to add this file permanently 1541floss$ cvs ci -m "revived jpg image" foo.jpg 1542Checking in foo.jpg; 1543/usr/local/newrepos/myproj/foo.jpg,v <-- foo.jpg 1544new revision: 1.3; previous revision: 1.2 1545done 1546floss$ cd /usr/local/newrepos/myproj/ 1547floss$ ls 1548Attic/ a-subdir/ foo.jpg,v 1549README.txt,v b-subdir/ hello.c,v 1550floss$ ls Attic/ 1551floss$ 1552@end example 1553 1554There's a lot more to know about RCS format, but this is sufficient for 1555a CVS adminstrator to maintain a repository. It's quite rare to 1556actually edit an RCS file; you'll usually just have to tweak file 1557permissions in the repository, at least if my own experience is any 1558guide. Nevertheless, when CVS starts behaving truly weirdly (rare, but 1559not completely outside the realm of possibility), you may want to 1560actually look inside the RCS files to figure out what's going on. 1561 1562@c ----------------------------------------------------- 1563@node The CVSROOT/ Administrative Directory 1564@section The CVSROOT/ Administrative Directory 1565 1566The files in newrepos/CVSROOT/ are not part of any project, but are used 1567to control CVS's behavior in the repository. The best way to edit those 1568files is to check out a working copy of CVSROOT, just like a regular 1569project: 1570 1571@example 1572floss$ cvs co CVSROOT 1573cvs checkout: Updating CVSROOT 1574U CVSROOT/checkoutlist 1575U CVSROOT/commitinfo 1576U CVSROOT/config 1577U CVSROOT/cvswrappers 1578U CVSROOT/editinfo 1579U CVSROOT/loginfo 1580U CVSROOT/modules 1581U CVSROOT/notify 1582U CVSROOT/rcsinfo 1583U CVSROOT/taginfo 1584U CVSROOT/verifymsg 1585floss$ 1586@end example 1587 1588We'll take the files in their approximate order of importance. Note 1589that each of the files comes with an explanatory comment at the 1590beginning (the comment convention is the same across all of them: A 1591@code{#} sign at the beginning of the line signifies a comment, and CVS 1592ignores such lines when parsing the files). Remember that any change 1593you make to the administrative files in your checked out working copy 1594won't affect CVS's behavior until you commit the changes. 1595 1596If you're extremely security conscious, you may want to arrange the 1597Unix-level permissions on CVSROOT to be different from permissions 1598elsewhere in the repository, in order to have fine-grained control over 1599who can commit changes to CVSROOT. As you'll see a little later, being 1600able to modify the files in CVSROOT essentially gives any CVS user -- 1601even remote ones -- the ability to run arbitrary commands on the 1602repository machine. 1603 1604@menu 1605* The config File:: 1606* The modules File:: 1607* The commitinfo And loginfo And rcsinfo Files:: 1608* The verifymsg And rcsinfo Files:: 1609* The taginfo File:: 1610* The cvswrappers File:: 1611* The editinfo File:: 1612* The notify File:: 1613* The checkoutlist File:: 1614@end menu 1615 1616@c -------------------------------------- 1617@node The config File 1618@subsection The config File 1619@cindex config file 1620 1621The @dfn{config} file allows you to configure certain global behavioral 1622parameters. It follows a very strict format 1623 1624@example 1625PARAMETER=VALUE 1626(etc) 1627@end example 1628 1629with no extra spaces allowed. For example, here is a possible config 1630file: 1631 1632@example 1633SystemAuth=yes 1634TopLevelAdmin=no 1635PreservePermissions=no 1636@end example 1637 1638(An absent entry would be equivalent to @code{no}.) 1639 1640The @code{SystemAuth} parameter governs whether CVS should look in the 1641system passwd file if it fails to find a given username in the 1642CVSROOT/passwd file. CVS distributions are shipped with this set to 1643@code{no} to be conservative about your system's security. 1644 1645@code{TopLevelAdmin} tells CVS whether to make a sibling CVS/ directory 1646when it checks out a working copy. This CVS/ directory would not be 1647inside the working copy, but rather next to it. It might be convenient 1648to turn this on if you tend (and your repository's users tend) to check 1649out many different projects from the same repository. Otherwise, you 1650should leave it off, as it can be disconcerting to see an extra CVS/ 1651directory appear where you don't expect it. 1652 1653@code{PreservePermissions} governs whether to preserve file permissions 1654and similar metadata in the revision history. This is a somewhat 1655obscure feature that probably isn't worth describing in detail. See the 1656node @cite{Special Files} in the Cederqvist if you're interested 1657(@dfn{node} is Texinfo-speak for a particular location within an Info 1658document. To go to a node while reading Info, just type @kbd{g} 1659followed by the name of the node, from anywhere inside the document). 1660 1661@code{LockDir} is also a rarely used feature. In special circumstances, 1662you may want to tell CVS to create its lockfiles somewhere other than 1663directly in the project subdirectories, in order to avoid permission 1664problems. These lockfiles keep CVS from tripping over itself when 1665multiple operations are performed on the same repository directory 1666simultaneously. Generally, you never need to worry about them, but 1667sometimes users may have trouble updating or checking out from a 1668repository directory because they're unable to create a lockfile (even 1669on read-only operations, CVS needs to create a lockfile to avoid 1670situations where it could end up reading while another invocation of CVS 1671is writing). The usual fix for this is to change repository 1672permissions, but when that's not feasible, the LockDir parameter can 1673come in handy. 1674 1675There are no other parameters at this time, but future versions of CVS 1676may add new ones; you should always check the Cederqvist or the 1677distribution config file itself for updates. 1678@c todo: or the NEWS file! 1679 1680@c ---------------------------- 1681@node The modules File 1682@subsection The modules File 1683@cindex modules file 1684 1685In modules, you can define aliases and alternate groupings for projects 1686in the repository. The most basic module line is of the form: 1687 1688@example 1689MODULE_NAME DIRECTORY_IN_REPOSITORY 1690@end example 1691 1692for example, 1693 1694@example 1695mp myproj 1696asub myproj/a-subdir 1697@end example 1698 1699(The paths given on the right are relative to the top of the 1700repository.) This gives developers an alternate name by which to check 1701out a project or a portion of a project: 1702 1703@example 1704floss$ cvs co mp 1705cvs checkout: Updating mp 1706U mp/README.txt 1707U mp/foo.jpg 1708U mp/hello.c 1709cvs checkout: Updating mp/a-subdir 1710U mp/a-subdir/whatever.c 1711cvs checkout: Updating mp/a-subdir/subsubdir 1712U mp/a-subdir/subsubdir/fish.c 1713cvs checkout: Updating mp/b-subdir 1714U mp/b-subdir/random.c 1715@end example 1716 1717or 1718 1719@example 1720floss$ cvs -d /usr/local/newrepos/ co asub 1721cvs checkout: Updating asub 1722U asub/whatever.c 1723cvs checkout: Updating asub/subsubdir 1724U asub/subsubdir/fish.c 1725@end example 1726 1727Notice how in both cases the module's name became the name of the 1728directory created for the working copy. In the case of asub, it didn't 1729even bother with the intermediate myproj/ directory, but created a 1730top-level asub/ instead, even though it came from myproj/a-subdir in the 1731repository. Updates, commits, and all other CVS commands will behave 1732normally in those working copies -- the only thing unusual about them 1733are their names. 1734 1735By putting file names after the directory name, you can define a module 1736consisting of just some of the files in a given repository directory. 1737For example 1738 1739@example 1740readme myproj README.txt 1741@end example 1742 1743and 1744 1745@example 1746no-readme myproj hello.c foo.jpg 1747@end example 1748 1749would permit the following checkouts, respectively: 1750 1751@example 1752floss$ cvs -q co readme 1753U readme/README.txt 1754floss$ cvs -q co no-readme 1755U no-readme/hello.c 1756U no-readme/foo.jpg 1757floss$ 1758@end example 1759 1760You can define a module that will include multiple repository 1761directories by using the -a (for @code{alias}) flag, but note that the 1762directories will get them checked out under their original names. For 1763example, this line 1764 1765@example 1766twoproj -a myproj yourproj 1767@end example 1768 1769would allow you to do this (assuming that both myproj/ and yourproj/ are 1770in the repository): 1771 1772@example 1773floss$ cvs co twoproj 1774U myproj/README.txt 1775U myproj/foo.jpg 1776U myproj/hello.c 1777U myproj/a-subdir/whatever.c 1778U myproj/a-subdir/subsubdir/fish.c 1779U myproj/b-subdir/random.c 1780U yourproj/README 1781U yourproj/foo.c 1782U yourproj/some-subdir/file1.c 1783U yourproj/some-subdir/file2.c 1784U yourproj/some-subdir/another-subdir/blah.c 1785@end example 1786 1787The name @code{twoproj} was a convenient handle to pull in both 1788projects, but it didn't affect the names of the working copies. (There 1789is no requirement that alias modules refer to multiple directories, by 1790the way; we could have omitted twoproj, in which case myproj would still 1791have been checked out under the name @code{myproj}.) 1792 1793Modules can even refer to other modules, by prefixing them with an 1794ampersand: 1795 1796@example 1797mp myproj 1798asub myproj/a-subdir 1799twoproj -a myproj yourproj 1800tp &twoproj 1801@end example 1802 1803Doing a checkout of @code{tp} would have exactly the same result as the 1804checkout of @code{twoproj} did. 1805 1806There are a few other tricks you can do with modules, most of them less 1807frequently used than the ones just presented. See the node modules in 1808the Cederqvist for information about them. 1809 1810@c ---------------------------------------------------------- 1811@node The commitinfo And loginfo And rcsinfo Files 1812@subsection The commitinfo And loginfo And rcsinfo Files 1813 1814Most of the other administrative files provide programmatic @dfn{hooks} 1815into various parts of the commit process (for example, the ability to 1816validate log messages or file states before permitting the commit, or 1817the ability to notify a group of developers whenever a commit happens in 1818a certain directory of the repository). 1819 1820The files generally share a common syntax. Each line is of the form: 1821 1822@example 1823REGULAR_EXPRESSION PROGRAM_TO_RUN 1824@end example 1825 1826The regular expression will be tested against the directory into which 1827the commit is taking place (with the directory name relative to the top 1828of the repository). If it matches, the designated program will be run. 1829The program will be passed the names of each of the files in the commit; 1830it can do whatever it likes with those names, including opening up the 1831files and examining their contents. If the program returns with a 1832nonzero exit status, the commit is prevented from taking place. 1833 1834(@dfn{Regular expressions} are a system for concisely describing classes 1835of strings. If you aren't familiar with regular expressions, you can 1836get by with the following short summary: @code{foo} would match any file 1837whose name contains the string @code{foo}; and @code{foo.*bar} would 1838match any file whose name contains @code{foo}, followed by any number of 1839characters, followed by the string @code{bar}. That's because normal 1840substrings match themselves, but @code{.} and @code{*} are special. 1841@code{.} matches any character, and @code{*} means match any number of 1842the preceding character, including zero. The @code{^} and @code{$} 1843signs mean match at the beginning and end of the string, respectively; 1844thus, @code{^foo.*bar.*baz$} would match any string beginning with 1845@code{foo}, containing @code{bar} somewhere in the middle, and ending 1846with @code{baz}. That's all we'll go into here; this summary is a very 1847abbreviated subset of full regular expression syntax.) 1848 1849@cindex commitinfo 1850The @dfn{commitinfo} file is for generic hooks you want run on every 1851commit. Here are some example commitinfo lines: 1852 1853@example 1854^a-subdir* /usr/local/bin/check-asubdir.sh 1855ou /usr/local/bin/validate-project.pl 1856@end example 1857 1858So any commit into myproj/a-subdir/ would match the first line, which 1859would then run the check-asubdir.sh script. A commit in any project 1860whose name (actual repository directory name, not necessarily module 1861name) contained the string @code{ou} would run the validate-project.pl 1862script, unless the commit had already matched the previous a-subdir 1863line. 1864 1865In place of a regular expression, the word @code{DEFAULT} or @code{ALL} 1866may be used. The DEFAULT line (or the first DEFAULT line, if there are 1867more than one) will be run if no regular expression matches, and each of 1868the ALL lines will be run in addition to any other lines that may match. 1869 1870The file names passed to the program do not refer to RCS files -- they 1871point to normal files, whose contents are exactly the same as the 1872working-copy files being committed. The only unusual aspect is that CVS 1873has them temporarily placed inside the repository, so they'll be 1874available to programs running on the machine where the repository is 1875located. 1876 1877@cindex loginfo 1878The @dfn{loginfo} file is similar to commitinfo, except that instead of 1879acting on the files' contents, it acts on the log message. The left 1880side of the loginfo file contains regular expressions, including 1881possibly DEFAULT and ALL lines. The program invoked on the right side 1882receives the log message on its standard input; it can do whatever it 1883wants with that input. 1884 1885The program on the right side can also take an arbitrary number of 1886command-line arguments. One of those arguments can be a special 1887@code{%} code, to be expanded by CVS at runtime, as follows: 1888 1889@example 1890%s ------> name(s) of the file(s) being committed 1891%V ------> revision number(s) before the commit 1892%v ------> revision number(s) after the commit 1893@end example 1894 1895The expansion always begins with the repository subdirectory (relative 1896to the top of the repository), followed by the per-file information. 1897For example, if the files committed were foo, bar, and baz, all in 1898@file{myproj/a-subdir}, then @code{%s} would expand into 1899 1900@example 1901myproj/a-subdir foo bar baz 1902@end example 1903 1904whereas @code{%V} would expand to show their old revision numbers 1905 1906@example 1907myproj/a-subdir 1.7 1.134 1.12 1908@end example 1909 1910and @code{%v} their new revision numbers: 1911 1912@example 1913myproj/a-subdir 1.8 1.135 1.13 1914@end example 1915 1916You can combine @code{%} expressions by enclosing them in curly braces 1917following @code{%} sign -- this will expand them into a series of 1918comma-separated sublists, each containing the corresponding information 1919for one file in the commit. For instance, @code{%@{sv@}} would expand 1920to 1921 1922@example 1923myproj/a-subdir foo,1.8 bar,1.135 baz,1.13 1924@end example 1925 1926and @code{%@{sVv@}} would expand to 1927 1928@example 1929myproj/a-subdir foo,1.7,1.8 bar,1.134,1.135 baz,1.12,1.13 1930@end example 1931 1932(You may have to look carefully to distinguish the commas from the 1933periods in those examples.) 1934 1935Here is a sample loginfo file: 1936 1937@example 1938^myproj$ /usr/local/newrepos/CVSROOT/log.pl -m myproj-devel@@foobar.com %s 1939ou /usr/local/bin/ou-notify.pl %@{sv@} 1940DEFAULT /usr/local/bin/default-notify.pl %@{sVv@} 1941@end example 1942 1943In the first line, any commit in the myproj subdirectory of the 1944repository invokes @file{log.pl}, passing it an email address (to which 1945@file{log.pl} will send a mail containing the log message), followed by 1946the repository, followed by all the files in the commit. 1947 1948In the second line, any commit in a repository subdirectory containing 1949the string @code{ou} will invoke the (imaginary) @file{ou-notify.pl} 1950script, passing it the repository followed by the file names and new 1951revision numbers of the files in the commit. 1952 1953The third line invokes the (equally imaginary) @file{default-notify.pl} 1954script for any commit that didn't match either of the two previous 1955lines, passing it all possible information (path to repository, file 1956names, old revisions, and new revisions). 1957 1958@c ---------------------------------------------- 1959@node The verifymsg And rcsinfo Files 1960@subsection The verifymsg And rcsinfo Files 1961 1962Sometimes you may just want a program to automatically verify that the 1963log message conforms to a certain standard and to stop the commit if 1964that standard is not met. This can be accomplished by using 1965@code{verifymsg}, possibly with some help from @code{rcsinfo}. 1966 1967The @dfn{verifymsg} file is the usual combination of regular expressions 1968and programs. The program receives the log message on standard input; 1969presumably it runs some checks to verify that the log message meets 1970certain criteria, then it exits with status zero or nonzero. If the 1971latter, the commit will fail. 1972 1973Meanwhile, the left side of rcsinfo has the usual regular expressions, 1974but the right side points to template files instead of programs. A 1975template file might be something like this 1976 1977@example 1978Condition: 1979Fix: 1980Comments: 1981@end example 1982 1983or some other collection of fields that a developer is supposed to fill 1984out to form a valid log message. The template is not very useful if 1985everyone commits using the -m option explicitly, but many developers 1986prefer not to do that. Instead, they run 1987 1988@example 1989floss$ cvs commit 1990@end example 1991 1992and wait for CVS to automatically fire up a text editor (as specified in 1993the EDITOR environment variable). There they write a log message, then 1994save the file and exit the editor, after which CVS continues with the 1995commit. 1996 1997In that scenario, an rcsinfo template would insert itself into the 1998editor before the user starts typing, so the fields would be displayed 1999along with a reminder to fill them in. Then when the user commits, the 2000appropriate program in @file{verifymsg} is invoked. Presumably, it will 2001check that the message does follow that format, and its exit status will 2002reflect the results of its inquiry (with zero meaning success). 2003 2004As an aid to the verification programs, the path to the template from 2005the rcsinfo file is appended as the last argument to the program command 2006line in @code{verifymsg}; that way, the program can base its 2007verification process on the template itself, if desired. 2008 2009Note that when someone checks out a working copy to a remote machine, 2010the appropriate rcsinfo template file is sent to the client as well 2011(it's stored in the CVS/ subdirectory of the working copy). However, 2012this means that if the rcsinfo file on the server is changed after that, 2013the client won't see the changes without re-checking out the project 2014(merely doing an update won't work). 2015 2016Note also that in the verifymsg file, the ALL keyword is not supported 2017(although DEFAULT still is). This is to make it easier to override 2018default verification scripts with subdirectory-specific ones. 2019 2020@c ------------------------------------------- 2021@node The taginfo File 2022@subsection The taginfo File 2023 2024What loginfo does for log messages, taginfo does for tags. The left 2025side of taginfo is regular expressions, as usual, and the right side is 2026programs. Each program is automatically handed arguments when CVS tag 2027is invoked, in this order: 2028 2029@example 2030arg 1: tag name 2031arg 2: operation ("add" => tag, "mov" => tag -F, "del" => tag -d) 2032arg 3: repository 2033arg 4, 5, etc: file revision [file revision ...] 2034@end example 2035 2036If the program returns nonzero, the tag is aborted. 2037 2038We haven't covered the -F option to tag before now, but it's exactly 2039what the above implies: a way to move a tag from one revision to 2040another. For example, if the tag @code{Known_Working} is attached to 2041Revision 1.7 of a file and you want it attached to Revision 1.11 2042instead, you'd do this 2043 2044@example 2045cvs tag -r 1.11 -F Known_Working foo.c 2046@end example 2047 2048which removes the tag from 1.7, or wherever it was previously in that 2049file, and puts it at 1.11. 2050 2051@c ------------------------------------------ 2052@node The cvswrappers File 2053@subsection The cvswrappers File 2054 2055The redundantly-named cvswrappers file gives you a way to specify that 2056certain files should be treated as binary, based on their file name. 2057CVS does not assume that all .jpg files are JPG image data, for example, 2058so it doesn't automatically use -kb when adding JPG files. Nonetheless, 2059certain projects would find it very useful to simply designate all JPG 2060files as binary. Here is a line in cvswrappers to do that: 2061 2062@example 2063*.jpg -k 'b' 2064@end example 2065 2066The @code{b} is separate and in quotes because it's not the only 2067possible RCS keyword expansion mode; one could also specify @code{o}, 2068which means not to expand @code{$} sign keywords but to do newline 2069conversion. However, @code{b} is the most common parameter. 2070 2071There are a few other modes that can be specified from the wrappers 2072file, but they're for such rare situations that they're probably not 2073worth documenting here (translation: your author has never had to use 2074them). See the node @cite{Wrappers} in the Cederqvist if you're 2075curious. 2076 2077@c ---------------------------------------------------- 2078@node The editinfo File 2079@subsection The editinfo File 2080 2081This file is obsolete, even though it's still included in distributions. 2082Just ignore it. 2083 2084@c ---------------------------------------------------- 2085@node The notify File 2086@subsection The notify File 2087 2088This file is used in conjunction with CVS's @code{watch} features, which 2089are described in @ref{Advanced CVS}. Nothing about it will make sense 2090until you understand what watches are (they're a useful but 2091non-essential feature), so see @ref{Advanced CVS} for details about this 2092file and about watches. 2093 2094@c ---------------------------------------------------- 2095@node The checkoutlist File 2096@subsection The checkoutlist File 2097 2098If you look inside CVSROOT/, you'll see that working copies of the files 2099exist side by side with their RCS revision files: 2100 2101@example 2102floss$ ls /usr/local/newrepos/CVSROOT 2103checkoutlist config,v history notify taginfo 2104checkoutlist,v cvswrappers loginfo notify,v taginfo,v 2105commitinfo cvswrappers,v loginfo,v passwd verifymsg 2106commitinfo,v editinfo modules rcsinfo verifymsg,v 2107config editinfo,v modules,v rcsinfo,v 2108 2109floss$ 2110@end example 2111 2112CVS only pays attention to the working versions, not the RCS files, when 2113it's looking for guidance on how to behave. Therefore, whenever you 2114commit your working copy of CVSROOT/ (which might, after all, even be 2115checked out to a different machine), CVS automatically updates any 2116changed files in the repository itself. You will know that this has 2117happened because CVS will print a message at the end of such commits: 2118 2119@example 2120floss$ cvs ci -m "added mp and asub modules" modules 2121Checking in modules; 2122/usr/local/newrepos/CVSROOT/modules,v <-- modules 2123new revision: 1.2; previous revision: 1.1 2124done 2125cvs commit: Rebuilding administrative file database 2126@end example 2127 2128CVS automatically knows about the standard administrative files, and 2129will rebuild them in CVSROOT/ as necessary. If you decide to put custom 2130files in CVSROOT/ (such as programs or rcsinfo template files), you'll 2131have to tell CVS explicitly to treat them the same way. 2132 2133That's the purpose of the checkoutlist file. It has a different format 2134from most of the files we've looked at so far 2135 2136@example 2137FILENAME ERROR_MESSAGE_IF_FILE_CANNOT_BE_CHECKED_OUT 2138@end example 2139 2140for example, 2141 2142@example 2143log.pl unable to check out / update log.pl in CVSROOT 2144 2145bugfix.tmpl unable to check out / update bugfix.tmpl in CVSROOT 2146@end example 2147 2148Certain files in CVSROOT are traditionally not kept under revision 2149control. One such is the @dfn{history} file, which keeps a running 2150record of all actions in the repository, for use by the @w{@code{cvs 2151history}} command (which lists checkout, update, and tag activity for a 2152given file or project directory). Incidentally, if you just remove the 2153@file{history} file, CVS will obligingly stop keeping that log. 2154 2155Note: sometimes the history file is the cause of permission problems, 2156and the easiest way to solve them is to either make it world-writeable 2157or just remove it. 2158 2159Another @code{unrevisioned} administrative file is passwd, the 2160assumption being that having it checked out over the network might 2161compromise the passwords (even though they're encrypted). You'll have 2162to decide based on your own security situation whether you want to add 2163passwd to checkoutlist or not; by default, it is not in checkoutlist. 2164 2165Two final notes about the CVSROOT/ directory: It is possible, if you 2166make a big enough mistake, to commit an administrative file that is 2167broken in such a way as to prevent any commits from happening at all. 2168If you do that, naturally you won't be able to commit a fixed version of 2169the administrative file! The solution is to go in and hand-edit the 2170repository's working copy of the administrative file to correct the 2171problem; the whole repository may stay inaccessible until you do that. 2172 2173Also, for security's sake, make sure your CVSROOT/ directory is only 2174writeable by users you trust (by @code{trust}, I mean you trust both 2175their intentions and their ability not to compromise their password). 2176The @file{*info} files give people the ability to invoke arbitrary 2177programs, so anyone who can commit or edit files in the CVSROOT/ 2178directory can essentially run any command on the system. That's 2179something you should always keep in mind. 2180 2181@c ------------------------------------------------------- 2182@node Commit Emails 2183@section Commit Emails 2184 2185The loginfo file is how one sets up commit emails -- automated emails 2186that go out to everyone working on a project whenever a commit takes 2187place. (It may seem counterintuitive that this is done in loginfo 2188instead of commitinfo, but the point is that one wants to include the 2189log message in the email). The program to do the mailing -- 2190@file{contrib/log.pl} in the CVS source distribution -- can be installed 2191anywhere on your system. I customarily put it in the repository's 2192CVSROOT/ subdirectory, but that's just a matter of taste. 2193 2194You may need to edit @file{log.pl} a bit to get it to work on your 2195system, possibly changing the first line to point to your Perl 2196interpreter, and maybe changing this line 2197 2198@example 2199$mailcmd = "| Mail -s 'CVS update: $modulepath'"; 2200@end example 2201 2202to invoke your preferred mailer, which may or may not be named 2203@code{Mail}. Once you've got it set the way you like it, you can put 2204lines similar to these into your loginfo: 2205 2206@example 2207listerizer CVSROOT/log.pl %s -f CVSROOT/commitlog -m listerizer@@red-bean.com 2208RoadMail CVSROOT/log.pl %s -f CVSROOT/commitlog -m roadmail@@red-bean.com 2209bk/*score CVSROOT/log.pl %s -f CVSROOT/commitlog -m \ 2210 bkscore-devel@@red-bean.com 2211@end example 2212 2213The @code{%s} expands to the names of the files being committed; the -f 2214option to @file{log.pl} takes a file name, to which the log message will 2215be appended (so CVSROOT/commitlog is an ever-growing file of log 2216messages); and the -m flag takes an email address, to which 2217@file{log.pl} will send a message about the commit. The address is 2218usually a mailing list, but you can specify the -m option as many times 2219as necessary in one log.pl command line. 2220 2221@c -------------------------------------------------------------- 2222@node Finding Out More 2223@section Finding Out More 2224 2225Although this chapter tries to give a complete introduction to 2226installing and administering CVS, I've left out things that are either 2227too rarely used to be worth mentioning or already well documented in the 2228Cederqvist manual. The latter category includes setting up the other 2229remote access methods: RSH/SSH, kserver (Kerberos 4), and GSSAPI (which 2230includes Kerberos 5, among other things). It should be noted that 2231nothing special needs to be done for RSH/SSH connections, other than 2232making sure that the user in question can log into the repository 2233machine using RSH or SSH. If they can and CVS is installed on both 2234client and server, and they have the right permissions to use the 2235repository directly from the server machine, then they should be able to 2236access the repository remotely via the :ext: method. 2237 2238Descriptions of certain specialized features of CVS have been deferred 2239to later chapters, so they can be introduced in contexts where their 2240usefulness is obvious. General CVS troubleshooting tips are found in 2241@ref{Tips And Troubleshooting}. Although it's not necessary to read the 2242entire Cederqvist manual, you should familiarize yourself with it; it 2243will be an invaluable reference tool. If for some reason you don't have 2244Info working on your machine and don't want to print the manual, you can 2245browse it online at @uref{http://durak.org/cvswebsites/doc/} or 2246@uref{http://www.loria.fr/~molli/cvs/doc/cvs_toc.html}. 2247
