diff options
| author | nate <nate@FreeBSD.org> | 1995-03-31 07:45:34 +0000 |
|---|---|---|
| committer | nate <nate@FreeBSD.org> | 1995-03-31 07:45:34 +0000 |
| commit | 97dcd3ee2c52c29f7f4f4ad1a792395166114f77 (patch) | |
| tree | 839b28261115079f11388074d28948dfe43a9c4d /gnu/usr.bin/cvs/doc | |
| parent | 02981a52b9b7d28ced57a7a8115421fdd16789eb (diff) | |
| download | FreeBSD-src-97dcd3ee2c52c29f7f4f4ad1a792395166114f77.zip FreeBSD-src-97dcd3ee2c52c29f7f4f4ad1a792395166114f77.tar.gz | |
Original sources from CVS-1.4A2 munged to fit our directory structure.
Diffstat (limited to 'gnu/usr.bin/cvs/doc')
| -rw-r--r-- | gnu/usr.bin/cvs/doc/cvs-paper.ms | 1073 | ||||
| -rw-r--r-- | gnu/usr.bin/cvs/doc/cvs.texinfo | 6644 |
2 files changed, 7717 insertions, 0 deletions
diff --git a/gnu/usr.bin/cvs/doc/cvs-paper.ms b/gnu/usr.bin/cvs/doc/cvs-paper.ms new file mode 100644 index 0000000..567179b --- /dev/null +++ b/gnu/usr.bin/cvs/doc/cvs-paper.ms @@ -0,0 +1,1073 @@ +.\" soelim cvs.ms | pic | tbl | troff -ms +.\" @(#)cvs.ms 1.2 92/01/30 +.\" +.\" troff source to the cvs USENIX article, Winter 1990, Washington, D.C. +.\" Copyright (c) 1989, Brian Berliner +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 1, or (at your option) +.\" any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +.\" +.\" The author can be reached at: berliner@prisma.com +.\" +.de SP +.if n .sp +.if t .sp .5 +.. +.de hl +.br +.in +0.5i +\l'\\n(LLu-1i' +.in -0.5i +.sp +.. +.OH "" +.nr PS 11 +.nr PO 1.25i +.pl -0.2i +.TL +.ps 14 +.ft B +.nf +CVS II: +Parallelizing Software Development +.fi +.ft +.ps +.AU +.ps 12 +.ft I +Brian Berliner +.ft +.ps +.AI +.ps 12 +.ft I +Prisma, Inc. +5465 Mark Dabling Blvd. +Colorado Springs, CO 80918 +berliner@prisma.com +.ft +.ps +.AB +The program described in this paper fills a need in the UNIX +community for a freely available tool to manage software revision and +release control in a multi-developer, multi-directory, multi-group +environment. +This tool also addresses the increasing need for tracking third-party vendor +source distributions while trying to maintain local modifications to +earlier releases. +.AE +.NH +Background +.PP +In large software development projects, it is usually necessary for more +than one software developer to be modifying (usually different) modules of the +code at the same time. +Some of these code modifications are done in an +experimental sense, at least until the code functions correctly, and some +testing of the entire program is usually necessary. +Then, the modifications are returned to a master source repository +so that others in the project can +enjoy the new bug-fix or functionality. +In order to manage such a project, some sort of revision control system is +necessary. +.PP +Specifically, UNIX\** +.FS +UNIX is a registered trademark of AT&T. +.FE +kernel development is an excellent example of the +problems that an adequate revision control system must address. +The SunOS\** +.FS +SunOS is a trademark of Sun Microsystems, Inc. +.FE +kernel is composed of over a thousand files spread across a +hierarchy of dozens of directories.\** +.FS +Yes, the SunOS 4.0 kernel is composed of over a \fIthousand\fP files! +.FE +Pieces of the kernel must be edited +by many software developers within an organization. +While undesirable in +theory, it is not uncommon to have two or more people making +modifications to the same file within the kernel sources in +order to facilitate a desired change. +Existing revision control systems like +.SM +RCS +.LG +[Tichy] or +.SM +SCCS +.LG +[Bell] serialize file modifications by +allowing only one developer to have a writable copy of a particular file at +any one point in time. +That developer is said to +have \*Qlocked\*U the file for his exclusive use, and no other developer is +allowed to check out a writable copy of the file until the locking +developer has finished impeding others' productivity. +Development pressures of productivity and deadlines +often force organizations to require that multiple developers be able to +simultaneously edit +copies of the same revision controlled file. +.PP +The necessity for multiple developers to modify the same file concurrently +questions the value of serialization-based policies in traditional revision +control. +This paper discusses the approach that +Prisma took in adapting a standard revision control system, +.SM +RCS\c +.LG +, along with an existing public-domain collection of shell scripts that sits +atop +.SM +RCS +.LG +and provides the basic conflict-resolution algorithms. +The resulting +program, \fBcvs\fP, addresses not only the issue of conflict-resolution in +a multi-developer open-editing environment, but also the issues of +software release control and vendor source support and integration. +.NH +The CVS Program +.PP +\fBcvs\fP +(Concurrent Versions System) +is a front end to the +.SM +RCS +.LG +revision control system which extends +the notion of revision control from a collection of files in a single +directory to a hierarchical collection of directories each containing +revision controlled files. +Directories and files in the \fBcvs\fP system can be combined together in +many ways to form a software release. +\fBcvs\fP +provides the functions necessary to manage these software releases and to +control the concurrent editing of source files among multiple software +developers. +.PP +The six major features of \fBcvs\fP are listed below, and will be +described in more detail in the following sections: +.RS +.IP 1. +Concurrent access and conflict-resolution algorithms to guarantee that +source changes are not \*Qlost.\*U +.IP 2. +Support for tracking third-party vendor source distributions while +maintaining the local modifications made to those sources. +.IP 3. +A flexible module database that provides a symbolic mapping of names to +components of a larger software distribution. +This symbolic mapping provides for location independence within the software +release and, for example, allows one to check out a copy of the \*Qdiff\*U +program without ever knowing that the sources to \*Qdiff\*U actually reside +in the \*Qbin/diff\*U directory. +.IP 4. +Configurable logging support allows all \*Qcommitted\*U source file changes +to be logged using an arbitrary program to save the log messages in a file, +notesfile, or news database. +.IP 5. +A software release can be symbolically tagged and checked out at any time +based on that tag. +An exact copy of a previous software release can be checked out at +any time, \fIregardless\fP of whether files or directories have been +added/removed from the \*Qcurrent\*U software release. +As well, +a \*Qdate\*U can be used to check out the \fIexact\fP version of the software +release as of the specified date. +.IP 6. +A \*Qpatch\*U format file [Wall] can be produced between two software +releases, even if the releases span multiple directories. +.RE +.PP +The sources maintained by \fBcvs\fP are kept within a single directory +hierarchy known as the \*Qsource repository.\*U +This \*Qsource repository\*U holds the actual +.SM +RCS +.LG +\*Q,v\*U files directly, as well as a special per-repository directory +(\c +.SM +CVSROOT.adm\c +.LG +) which contains a small number of administrative files that describe the +repository and how it can be accessed. +See Figure 1 for a picture of the \fBcvs\fP tree. +.KF +.hl +.DS B +.PS +line from 4.112,9.200 to 5.550,8.887 +line from 5.447,8.884 to 5.550,8.887 to 5.458,8.933 +line from 4.112,9.200 to 4.550,8.950 +line from 4.451,8.978 to 4.550,8.950 to 4.476,9.021 +line from 4.112,9.200 to 3.737,8.887 +line from 3.798,8.971 to 3.737,8.887 to 3.830,8.932 +line from 3.612,8.762 to 4.737,8.137 +line from 4.638,8.164 to 4.737,8.137 to 4.662,8.208 +line from 3.612,8.762 to 3.737,8.137 +line from 3.693,8.231 to 3.737,8.137 to 3.742,8.240 +line from 3.612,8.762 to 2.612,8.200 +line from 2.687,8.271 to 2.612,8.200 to 2.712,8.227 +line from 2.362,9.262 to 2.737,8.950 +line from 2.645,8.995 to 2.737,8.950 to 2.677,9.033 +line from 2.362,9.262 to 1.925,8.950 +line from 1.992,9.028 to 1.925,8.950 to 2.021,8.988 +line from 3.362,9.762 to 4.050,9.387 +line from 3.950,9.413 to 4.050,9.387 to 3.974,9.457 +line from 3.362,9.762 to 2.487,9.387 +line from 2.570,9.450 to 2.487,9.387 to 2.589,9.404 +.ps 11 +"newfs.c,v" at 4.487,8.043 ljust +.ps 11 +"mkfs.c,v" at 3.487,8.043 ljust +.ps 11 +"Makefile,v" at 2.237,8.043 ljust +.ps 11 +"newfs" at 3.487,8.793 ljust +.ps 11 +"halt.c,v" at 5.487,8.793 ljust +.ps 11 +"Makefile,v" at 4.237,8.793 ljust +.ps 11 +"modules,v" at 2.487,8.793 ljust +.ps 11 +"loginfo,v" at 1.488,8.793 ljust +.ps 11 +"etc" at 3.987,9.293 ljust +.ps 11 +"CVSROOT.adm" at 1.988,9.293 ljust +.ps 11 +"/src/master" at 2.987,9.793 ljust +.PE +.DE +.hl +.ce 100 +.LG +\fBFigure 1.\fP +.SM +\fBcvs\fP Source Repository +.ce 0 +.sp +.KE +.NH 2 +Software Conflict Resolution\** +.FS +The basic conflict-resolution algorithms +used in the \fBcvs\fP program find their roots +in the original work done by Dick Grune at Vrije Universiteit in Amsterdam +and posted to \fBcomp.sources.unix\fP in the volume 6 release sometime in 1986. +This original version of \fBcvs\fP was a collection of shell scripts that +combined to form a front end to the +.SM +RCS +.LG +programs. +.FE +.PP +\fBcvs\fP allows several software developers to edit personal copies of a +revision controlled file concurrently. +The revision number of each checked out file is maintained independently +for each user, and \fBcvs\fP forces the checked out file to be current with +the \*Qhead\*U revision before it can be \*Qcommitted\*U as a permanent change. +A checked out file is brought up-to-date with the \*Qhead\*U revision using +the \*Qupdate\*U command of \fBcvs\fP. +This command compares the \*Qhead\*U revision number with that of the user's +file and performs an +.SM +RCS +.LG +merge operation if they are not the same. +The result of the merge is a file that contains the user's modifications +and those modifications that were \*Qcommitted\*U after the user +checked out his version of the file (as well as a backup copy of the +user's original file). +\fBcvs\fP points out any conflicts during the merge. +It is the user's responsibility to resolve these conflicts +and to \*Qcommit\*U his/her changes when ready. +.PP +Although the \fBcvs\fP conflict-resolution algorithm was defined in 1986, +it is remarkably similar to the \*QCopy-Modify-Merge\*U scenario included +with NSE\** +.FS +NSE is the Network Software Environment, a product of Sun Microsystems, Inc. +.FE +and described in [Honda] and [Courington]. +The following explanation from [Honda] also applies to \fBcvs\fP: +.QP +Simply stated, a developer copies an object without locking it, modifies +the copy, and then merges the modified copy with the original. +This paradigm allows developers to work in isolation from one another since +changes are made to copies of objects. +Because locks are not used, development is not serialized and can proceed +in parallel. +Developers, however, must merge objects after the changes have been made. +In particular, a developer must resolve conflicts when the same object has +been modified by someone else. +.PP +In practice, Prisma has found that conflicts that occur when the same +object has been modified by someone else are quite rare. +When they do happen, the changes made by the other developer are usually +easily resolved. +This practical use has shown that the \*QCopy-Modify-Merge\*U paradigm is a +correct and useful one. +.NH 2 +Tracking Third-Party Source Distributions +.PP +Currently, a large amount of software is based on source +distributions from a third-party distributor. +It is often the case that local modifications are to be made to this +distribution, \fIand\fP that the vendor's future releases should be +tracked. +Rolling your local modifications forward into the new vendor release is a +time-consuming task, but \fBcvs\fP can ease this burden somewhat. +The \fBcheckin\fP program of \fBcvs\fP initially sets up a source +repository by integrating the source modules directly from the vendor's +release, preserving the directory hierarchy of the vendor's distribution. +The branch support of +.SM +RCS +.LG +is used to build this vendor release as a branch of the main +.SM +RCS +.LG +trunk. +Figure 2 shows how the \*Qhead\*U tracks a sample vendor +branch when no local modifications have been made to the file. +.KF +.hl +.DS B +.PS +ellipse at 3.237,6.763 wid 1.000 ht 0.500 +dashwid = 0.050i +line dashed from 3.237,7.513 to 3.737,7.513 to 3.737,9.762 to 4.237,9.762 +line from 4.138,9.737 to 4.237,9.762 to 4.138,9.787 +line dashed from 2.237,8.262 to 3.237,8.262 to 3.237,7.013 +line from 3.212,7.112 to 3.237,7.013 to 3.262,7.112 +line from 3.737,6.763 to 4.237,6.763 +line from 4.138,6.737 to 4.237,6.763 to 4.138,6.788 +line from 2.237,6.763 to 2.737,6.763 +line from 2.637,6.737 to 2.737,6.763 to 2.637,6.788 +line from 1.738,6.013 to 1.738,6.513 +line from 1.762,6.413 to 1.738,6.513 to 1.713,6.413 +line from 1.238,7.013 to 2.237,7.013 to 2.237,6.513 to 1.238,6.513 to 1.238,7.013 +line from 4.237,9.012 to 5.237,9.012 to 5.237,8.512 to 4.237,8.512 to 4.237,9.012 +line from 4.237,8.012 to 5.237,8.012 to 5.237,7.513 to 4.237,7.513 to 4.237,8.012 +line from 4.237,7.013 to 5.237,7.013 to 5.237,6.513 to 4.237,6.513 to 4.237,7.013 +line from 4.737,7.013 to 4.737,7.513 +line from 4.763,7.413 to 4.737,7.513 to 4.712,7.413 +line from 4.737,8.012 to 4.737,8.512 +line from 4.763,8.412 to 4.737,8.512 to 4.712,8.412 +line from 4.237,10.012 to 5.237,10.012 to 5.237,9.512 to 4.237,9.512 to 4.237,10.012 +line from 4.737,9.012 to 4.737,9.512 +line from 4.763,9.412 to 4.737,9.512 to 4.712,9.412 +line from 5.987,5.013 to 5.987,6.013 to 0.988,6.013 to 0.988,5.013 to 5.987,5.013 +.ps 11 +"\"HEAD\"" at 1.550,8.231 ljust +.ps 11 +"'SunOS'" at 2.987,6.293 ljust +.ps 11 +"1.1.1" at 3.050,6.793 ljust +.ps 11 +"1.1" at 1.613,6.793 ljust +.ps 11 +"1.1.1.1" at 4.487,6.793 ljust +.ps 11 +"1.1.1.2" at 4.487,7.793 ljust +.ps 11 +"1.1.1.3" at 4.487,8.793 ljust +.ps 11 +"1.1.1.4" at 4.487,9.793 ljust +.ps 11 +"'SunOS_4_0'" at 5.487,6.793 ljust +.ps 11 +"'SunOS_4_0_1'" at 5.487,7.793 ljust +.ps 11 +"'YAPT_5_5C'" at 5.487,8.793 ljust +.ps 11 +"'SunOS_4_0_3'" at 5.487,9.793 ljust +.ps 11 +"rcsfile.c,v" at 2.987,5.543 ljust +.PE +.DE +.hl +.ce 100 +.LG +\fBFigure 2.\fP +.SM +\fBcvs\fP Vendor Branch Example +.ce 0 +.sp .3 +.KE +Once this is done, developers can check out files and make local changes to +the vendor's source distribution. +These local changes form a new branch to the tree which is then used as the +source for future check outs. +Figure 3 shows how the \*Qhead\*U moves to the main +.SM +RCS +.LG +trunk when a local modification is made. +.KF +.hl +.DS B +.PS +ellipse at 3.237,6.763 wid 1.000 ht 0.500 +dashwid = 0.050i +line dashed from 2.800,9.075 to 1.738,9.075 to 1.738,8.012 +line from 1.713,8.112 to 1.738,8.012 to 1.762,8.112 +line from 1.738,7.013 to 1.738,7.513 +line from 1.762,7.413 to 1.738,7.513 to 1.713,7.413 +line from 1.238,8.012 to 2.237,8.012 to 2.237,7.513 to 1.238,7.513 to 1.238,8.012 +line from 3.737,6.763 to 4.237,6.763 +line from 4.138,6.737 to 4.237,6.763 to 4.138,6.788 +line from 2.237,6.763 to 2.737,6.763 +line from 2.637,6.737 to 2.737,6.763 to 2.637,6.788 +line from 1.738,6.013 to 1.738,6.513 +line from 1.762,6.413 to 1.738,6.513 to 1.713,6.413 +line from 1.238,7.013 to 2.237,7.013 to 2.237,6.513 to 1.238,6.513 to 1.238,7.013 +line from 4.237,9.012 to 5.237,9.012 to 5.237,8.512 to 4.237,8.512 to 4.237,9.012 +line from 4.237,8.012 to 5.237,8.012 to 5.237,7.513 to 4.237,7.513 to 4.237,8.012 +line from 4.237,7.013 to 5.237,7.013 to 5.237,6.513 to 4.237,6.513 to 4.237,7.013 +line from 4.737,7.013 to 4.737,7.513 +line from 4.763,7.413 to 4.737,7.513 to 4.712,7.413 +line from 4.737,8.012 to 4.737,8.512 +line from 4.763,8.412 to 4.737,8.512 to 4.712,8.412 +line from 4.237,10.012 to 5.237,10.012 to 5.237,9.512 to 4.237,9.512 to 4.237,10.012 +line from 4.737,9.012 to 4.737,9.512 +line from 4.763,9.412 to 4.737,9.512 to 4.712,9.412 +line from 5.987,5.013 to 5.987,6.013 to 0.988,6.013 to 0.988,5.013 to 5.987,5.013 +.ps 11 +"1.2" at 1.613,7.793 ljust +.ps 11 +"\"HEAD\"" at 2.862,9.043 ljust +.ps 11 +"'SunOS'" at 2.987,6.293 ljust +.ps 11 +"1.1.1" at 3.050,6.793 ljust +.ps 11 +"1.1" at 1.613,6.793 ljust +.ps 11 +"1.1.1.1" at 4.487,6.793 ljust +.ps 11 +"1.1.1.2" at 4.487,7.793 ljust +.ps 11 +"1.1.1.3" at 4.487,8.793 ljust +.ps 11 +"1.1.1.4" at 4.487,9.793 ljust +.ps 11 +"'SunOS_4_0'" at 5.487,6.793 ljust +.ps 11 +"'SunOS_4_0_1'" at 5.487,7.793 ljust +.ps 11 +"'YAPT_5_5C'" at 5.487,8.793 ljust +.ps 11 +"'SunOS_4_0_3'" at 5.487,9.793 ljust +.ps 11 +"rcsfile.c,v" at 2.987,5.543 ljust +.PE +.DE +.hl +.ce 100 +.LG +\fBFigure 3.\fP +.SM +\fBcvs\fP Local Modification to Vendor Branch +.ce 0 +.sp +.KE +.PP +When a new version of the vendor's source distribution arrives, the +\fBcheckin\fP program adds the new and changed vendor's files to the +already existing source repository. +For files that have not been changed locally, the new file from the +vendor becomes the current \*Qhead\*U revision. +For files that have been modified locally, \fBcheckin\fP warns that the +file must be merged with the new vendor release. +The \fBcvs\fP \*Qjoin\*U command is a useful tool that aids this process by +performing the necessary +.SM +RCS +.LG +merge, as is done above when performing an \*Qupdate.\*U +.PP +There is also limited support for \*Qdual\*U derivations for source files. +See Figure 4 for a sample dual-derived file. +.KF +.hl +.DS B +.PS +ellipse at 2.337,8.575 wid 0.700 ht 0.375 +ellipse at 2.312,9.137 wid 0.700 ht 0.375 +line from 1.225,9.012 to 1.225,9.363 +line from 1.250,9.263 to 1.225,9.363 to 1.200,9.263 +line from 0.875,9.725 to 1.600,9.725 to 1.600,9.363 to 0.875,9.363 to 0.875,9.725 +line from 0.875,9.012 to 1.600,9.012 to 1.600,8.650 to 0.875,8.650 to 0.875,9.012 +line from 4.050,10.200 to 4.775,10.200 to 4.775,9.850 to 4.050,9.850 to 4.050,10.200 +line from 4.050,9.475 to 4.775,9.475 to 4.775,9.113 to 4.050,9.113 to 4.050,9.475 +line from 4.050,8.762 to 4.775,8.762 to 4.775,8.400 to 4.050,8.400 to 4.050,8.762 +line from 4.425,8.762 to 4.425,9.113 +line from 4.450,9.013 to 4.425,9.113 to 4.400,9.013 +line from 4.425,9.475 to 4.425,9.850 +line from 4.450,9.750 to 4.425,9.850 to 4.400,9.750 +line from 3.050,10.000 to 3.775,10.000 to 3.775,9.637 to 3.050,9.637 to 3.050,10.000 +line from 3.050,9.312 to 3.775,9.312 to 3.775,8.950 to 3.050,8.950 to 3.050,9.312 +line from 0.713,7.325 to 0.713,8.075 to 4.925,8.075 to 4.925,7.325 to 0.713,7.325 +line from 1.238,8.075 to 1.238,8.637 +line from 1.262,8.537 to 1.238,8.637 to 1.213,8.537 +line from 1.613,8.825 to 1.975,8.575 +line from 1.878,8.611 to 1.975,8.575 to 1.907,8.652 +line from 2.675,8.575 to 4.050,8.575 +line from 3.950,8.550 to 4.050,8.575 to 3.950,8.600 +line from 2.675,9.137 to 3.050,9.137 +line from 2.950,9.112 to 3.050,9.137 to 2.950,9.162 +line from 3.425,9.325 to 3.425,9.637 +line from 3.450,9.537 to 3.425,9.637 to 3.400,9.537 +line from 1.613,8.825 to 1.925,9.137 +line from 1.872,9.049 to 1.925,9.137 to 1.837,9.084 +.ps 11 +"'BSD'" at 2.138,9.481 ljust +.ps 11 +"1.2" at 1.113,9.543 ljust +.ps 11 +"1.1" at 1.125,8.831 ljust +.ps 11 +"1.1.1.1" at 4.175,8.543 ljust +.ps 11 +"1.1.1.2" at 4.175,9.281 ljust +.ps 11 +"1.1.1.3" at 4.175,9.993 ljust +.ps 11 +"1.1.2.2" at 3.175,9.793 ljust +.ps 11 +"1.1.2.1" at 3.175,9.106 ljust +.ps 11 +"rcsfile.c,v" at 2.425,7.706 ljust +.ps 11 +"1.1.1" at 2.175,8.568 ljust +.ps 11 +"'SunOS'" at 2.125,8.243 ljust +.ps 11 +"1.1.2" at 2.163,9.131 ljust +.PE +.DE +.hl +.ce 100 +.LG +\fBFigure 4.\fP +.SM +\fBcvs\fP Support For \*QDual\*U Derivations +.ce 0 +.sp +.KE +This example tracks the SunOS distribution but includes major changes from +Berkeley. +These BSD files are saved directly in the +.SM +RCS +.LG +file off a new branch. +.NH 2 +Location Independent Module Database +.PP +\fBcvs\fP contains support for a simple, yet powerful, \*Qmodule\*U database. +For reasons of efficiency, this database is stored in \fBndbm\fP\|(3) format. +The module database is used to apply names to collections of directories +and files as a matter of convenience for checking out pieces of a large +software distribution. +The database records the physical location of the sources as a form of +information hiding, allowing one to check out whole directory hierarchies +or individual files without regard for their actual location within the +global source distribution. +.PP +Consider the following small sample of a module database, which must be +tailored manually to each specific source repository environment: +.DS +\f(CW #key [-option argument] directory [files...] + diff bin/diff + libc lib/libc + sys -o sys/tools/make_links sys + modules -i mkmodules CVSROOT.adm modules + kernel -a sys lang/adb + ps bin Makefile ps.c\fP +.DE +.PP +The \*Qdiff\*U and \*Qlibc\*U modules refer to whole directory hierarchies that +are extracted on check out. +The \*Qsys\*U module extracts the \*Qsys\*U hierarchy, and runs the +\*Qmake_links\*U program at the end of the check out process (the \fI-o\fP +option specifies a program to run on check\fIo\fPut). +The \*Qmodules\*U module allows one to edit the module database file and +runs the \*Qmkmodules\*U program on check\fIi\fPn to regenerate the +\fBndbm\fP database that \fBcvs\fP uses. +The \*Qkernel\*U module is an alias (as the \fI-a\fP option specifies) +which causes the remaining arguments after the \fI-a\fP to be interpreted +exactly as if they had been specified on the command line. +This is useful for objects that require shared pieces of code from far away +places to be compiled (as is the case with the kernel debugger, \fBkadb\fP, +which shares code with the standard \fBadb\fP debugger). +The \*Qps\*U module shows that the source for \*Qps\*U lives in the \*Qbin\*U +directory, but only \fIMakefile\fP and \fIps.c\fP are required to build the +object. +.PP +The module database at Prisma is now populated for the entire UNIX +distribution and thereby allows us to issue the +following convenient commands to check out components of the UNIX +distribution without regard for their actual location within the master source +repository: +.DS +\f(CW example% cvs checkout diff + example% cvs checkout libc ps + example% cd diff; make\fP +.DE +.PP +In building the module database file, it is quite possible to have name +conflicts within a global software distribution. +For example, SunOS provides two \fBcat\fP programs: +one for the standard environment, \fI/bin/cat\fP, and one for the System V +environment, \fI/usr/5bin/cat\fP. +We resolved this conflict by naming the standard \fBcat\fP module +\*Qcat\*U, and the System V \fBcat\fP module \*Q5cat\*U. +Similar name modifications must be applied to other conflicting names, as +might be found between a utility program and a library function, though +Prisma chose not to include individual library functions within the module +database at this time. +.NH 2 +Configurable Logging Support +.PP +The \fBcvs\fP \*Qcommit\*U command is used to make a permanent change to the +master source repository (where the +.SM +RCS +.LG +\*Q,v\*U files live). +Whenever a \*Qcommit\*U is done, the log message for the change is carefully +logged by an arbitrary program (in a file, notesfile, news database, or +mail). +For example, a collection of these updates can be used to produce release +notices. +\fBcvs\fP can be configured to send log updates through one or more filter +programs, based on a regular expression match on the directory that is +being changed. +This allows multiple related or unrelated projects to exist within a single +\fBcvs\fP source repository tree, with each different project sending its +\*Qcommit\*U reports to a unique log device. +.PP +A sample logging configuration file might look as follows: +.DS +\f(CW #regex filter-program + DEFAULT /usr/local/bin/nfpipe -t %s utils.updates + ^diag /usr/local/bin/nfpipe -t %s diag.updates + ^local /usr/local/bin/nfpipe -t %s local.updates + ^perf /usr/local/bin/nfpipe -t %s perf.updates + ^sys /usr/local/bin/nfpipe -t %s kernel.updates\fP +.DE +.PP +This sample allows the diagnostics and performance groups to +share the same source repository with the kernel and utilities groups. +Changes that they make are sent directly to their own notesfile [Essick] +through the \*Qnfpipe\*U program. +A sufficiently simple title is substituted for the \*Q%s\*U argument before +the filter program is executed. +This logging configuration file is tailored manually to each specific +source repository environment. +.NH 2 +Tagged Releases and Dates +.PP +Any release can be given a symbolic tag name that is stored directly in the +.SM +RCS +.LG +files. +This tag can be used at any time to get an exact copy of any previous +release. +With equal ease, one can also extract an exact copy of the source files as +of any arbitrary date in the past as well. +Thus, all that's required to tag the current kernel, and to tag the kernel +as of the Fourth of July is: +.DS +\f(CW example% cvs tag TEST_KERNEL kernel + example% cvs tag -D 'July 4' PATRIOTIC_KERNEL kernel\fP +.DE +The following command would retrieve an exact copy of the test kernel at +some later date: +.DS +\f(CW example% cvs checkout -fp -rTEST_KERNEL kernel\fP +.DE +The \fI-f\fP option causes only files that match the specified tag to be +extracted, while the \fI-p\fP option automatically prunes empty directories. +Consequently, directories added to the kernel after the test kernel was +tagged are not included in the newly extracted copy of the test kernel. +.PP +The \fBcvs\fP date support has exactly the same interface as that provided +with +.SM +RCS\c +.LG +, however \fBcvs\fP must process the \*Q,v\*U files directly due to the +special handling required by the vendor branch support. +The standard +.SM +RCS +.LG +date handling only processes one branch (or the main trunk) when checking +out based on a date specification. +\fBcvs\fP must instead process the current \*Qhead\*U branch and, if a +match is not found, proceed to look for a match on the vendor branch. +This, combined with reasons of performance, is why \fBcvs\fP processes +revision (symbolic and numeric) and date specifications directly from the +\*Q,v\*U files. +.NH 2 +Building \*Qpatch\*U Source Distributions +.PP +\fBcvs\fP can produce a \*Qpatch\*U format [Wall] output file which can be +used to bring a previously released software distribution current with the +newest release. +This patch file supports an entire directory hierarchy within a single +patch, as well as being able to add whole new files to the previous +release. +One can combine symbolic revisions and dates together to display changes in +a very generic way: +.DS +\f(CW example% cvs patch -D 'December 1, 1988' \e + -D 'January 1, 1989' sys\fP +.DE +This example displays the kernel changes made in the month of December, +1988. +To release a patch file, for example, to take the \fBcvs\fP distribution +from version 1.0 to version 1.4 might be done as follows: +.DS +\f(CW example% cvs patch -rCVS_1_0 -rCVS_1_4 cvs\fP +.DE +.NH +CVS Experience +.NH 2 +Statistics +.PP +A quick summary of the scale that \fBcvs\fP is addressing today +can be found in Table 1. +.KF +.TS +box center tab(:); +c s +c s +c | c +l | n . +\fB\s+2Revision Control Statistics at Prisma +as of 11/11/89\fP\s-2 +_ +How Many...:Total += +Files:17243 +Directories:1005 +Lines of code:3927255 +Removed files:131 +Software developers:14 +Software groups:6 +Megabytes of source:128 +.TE +.ce 100 +.LG +\fBTable 1.\fP +.SM +\fBcvs\fP Statistics +.ce 0 +.sp .3 +.KE +Table 2 shows the history of files changed or added and the number +of source lines affected by the change at Prisma. +Only changes made to the kernel sources are included. +.KF +.TS +box center tab(:); +c s s s s +c s s s s +c || c | c || c | c +c || c | c || c | c +l || n | n || n | n. +\fB\s+2Prisma Kernel Source File Changes +By Month, 1988-1989\fP\s-2 +_ +Month:# Changed:# Lines:# Added:# Lines +\^:Files:Changed:Files:Added += +Dec:87:3619:68:9266 +Jan:39:4324:0:0 +Feb:73:1578:5:3550 +Mar:99:5301:18:11461 +Apr:112:7333:11:5759 +May:138:5371:17:13986 +Jun:65:2261:27:12875 +Jul:34:2000:1:58 +Aug:65:6378:8:4724 +Sep:266:23410:113:39965 +Oct:22:621:1:155 +Total:1000:62196:269:101799 +.TE +.ce 100 +.LG +\fBTable 2.\fP +.SM +\fBcvs\fP Usage History for the Kernel +.ce 0 +.sp +.KE +The large number of source file changes made in September are the result of +merging the SunOS 4.0.3 sources into the kernel. +This merge process is described in section 3.3. +.NH 2 +Performance +.PP +The performance of \fBcvs\fP is currently quite reasonable. +Little effort has been expended on tuning \fBcvs\fP, although performance +related decisions were made during the \fBcvs\fP design. +For example, \fBcvs\fP parses the +.SM +RCS +.LG +\*Q,v\*U files directly instead of running an +.SM +RCS +.LG +process. +This includes following branches as well as integrating with the vendor +source branches and the main trunk when checking out files based on a date. +.PP +Checking out the entire kernel source tree (1223 files/59 directories) +currently takes 16 wall clock minutes on a Sun-4/280. +However, bringing the tree up-to-date with the current kernel sources, once +it has been checked out, takes only 1.5 wall clock minutes. +Updating the \fIcomplete\fP 128 MByte source tree under \fBcvs\fP control +(17243 files/1005 directories) takes roughly 28 wall clock minutes and +utilizes one-third of the machine. +For now this is entirely acceptable; improvements on these numbers will +possibly be made in the future. +.NH 2 +The SunOS 4.0.3 Merge +.PP +The true test of the \fBcvs\fP vendor branch support came with the arrival +of the SunOS 4.0.3 source upgrade tape. +As described above, the \fBcheckin\fP program was used to install the new +sources and the resulting output file listed the files that had been +locally modified, needing to be merged manually. +For the kernel, there were 94 files in conflict. +The \fBcvs\fP \*Qjoin\*U command was used on each of the 94 conflicting +files, and the remaining conflicts were resolved. +.PP +The \*Qjoin\*U command performs an \fBrcsmerge\fP operation. +This in turn uses \fI/usr/lib/diff3\fP to produce a three-way diff file. +As it happens, the \fBdiff3\fP program has a hard-coded limit of 200 +source-file changes maximum. +This proved to be too small for a few of the kernel files that needed +merging by hand, due to the large number of local changes that Prisma had +made. +The \fBdiff3\fP problem was solved by increasing the hard-coded limit by an +order of magnitude. +.PP +The SunOS 4.0.3 kernel source upgrade distribution contained +346 files, 233 of which were modifications to previously released files, +and 113 of which were newly added files. +\fBcheckin\fP added the 113 new files to the source repository +without intervention. +Of the 233 modified files, 139 dropped in cleanly by \fBcheckin\fP, since +Prisma had not made any local changes to them, and 94 required manual +merging due to local modifications. +The 233 modified files consisted of 20,766 lines of differences. +It took one developer two days to manually merge the 94 files using the +\*Qjoin\*U command and resolving conflicts manually. +An additional day was required for kernel debugging. +The entire process of merging over 20,000 lines of differences was +completed in less than a week. +This one time-savings alone was justification enough for the \fBcvs\fP +development effort; we expect to gain even more when tracking future SunOS +releases. +.NH +Future Enhancements and Current Bugs +.PP +Since \fBcvs\fP was designed to be incomplete, for reasons of design +simplicity, there are naturally a good +number of enhancements that can be made to make it more useful. +As well, some nuisances exist in the current implementation. +.RS +.IP \(bu 3 +\fBcvs\fP does not currently \*Qremember\*U who has a checked out a copy of a +module. +As a result, it is impossible to know who might be working on the same +module that you are. +A simple-minded database that is updated nightly would likely suffice. +.IP \(bu 3 +Signal processing, keyboard interrupt handling in particular, is currently +somewhat weak. +This is due to the heavy use of the \fBsystem\fP\|(3) library +function to execute +.SM +RCS +.LG +programs like \fBco\fP and \fBci\fP. +It sometimes takes multiple interrupts to make \fBcvs\fP quit. +This can be fixed by using a home-grown \fBsystem\fP\|() replacement. +.IP \(bu 3 +Security of the source repository is currently not dealt with directly. +The usual UNIX approach of user-group-other security permissions through +the file system is utilized, but nothing else. +\fBcvs\fP could likely be a set-group-id executable that checks a +protected database to verify user access permissions for particular objects +before allowing any operations to affect those objects. +.IP \(bu 3 +With every checked-out directory, \fBcvs\fP maintains some administrative +files that record the current revision numbers of the checked-out files as +well as the location of the respective source repository. +\fBcvs\fP does not recover nicely at all if these administrative files are +removed. +.IP \(bu 3 +The source code for \fBcvs\fP has been tested extensively on Sun-3 and +Sun-4 systems, all running SunOS 4.0 or later versions of the operating +system. +Since the code has not yet been compiled under other platforms, the overall +portability of the code is still questionable. +.IP \(bu 3 +As witnessed in the previous section, the \fBcvs\fP method for tracking +third party vendor source distributions can work quite nicely. +However, if the vendor changes the directory structure or the file names +within the source distribution, \fBcvs\fP has no way of matching the old +release with the new one. +It is currently unclear as to how to solve this, though it is certain to +happen in practice. +.RE +.NH +Availability +.PP +The \fBcvs\fP program sources can be found in a recent posting to the +\fBcomp.sources.unix\fP newsgroup. +It is also currently available via anonymous ftp from \*Qprisma.com\*U. +Copying rights for \fBcvs\fP will be covered by the GNU General Public +License. +.NH +Summary +.PP +Prisma has used \fBcvs\fP since December, 1988. +It has evolved to meet our specific needs of revision and release control. +We will make our code freely available so that others can +benefit from our work, and can enhance \fBcvs\fP to meet broader needs yet. +.PP +Many of the other software release and revision control systems, like the +one described in [Glew], appear to use a collection of tools that are +geared toward specific environments \(em one set of tools for the kernel, +one set for \*Qgeneric\*U software, one set for utilities, and one set for +kernel and utilities. +Each of these tool sets apparently handle some specific aspect of the +problem uniquely. +\fBcvs\fP took a somewhat different approach. +File sharing through symbolic or hard links is not addressed; instead, the +disk space is simply burned since it is \*Qcheap.\*U +Support for producing objects for multiple architectures is not addressed; +instead, a parallel checked-out source tree must be used for each +architecture, again wasting disk space to simplify complexity and ease of +use \(em punting on this issue allowed \fIMakefile\fPs to remain +unchanged, unlike the approach taken in [Mahler], thereby maintaining closer +compatibility with the third-party vendor sources. +\fBcvs\fP is essentially a source-file server, making no assumptions or +special handling of the sources that it controls. +To \fBcvs\fP: +.QP +A source is a source, of course, of course, unless of course the source is +Mr. Ed.\** +.FS +\fBcvs\fP, of course, does not really discriminate against Mr. Ed.\** +.FE +.FS +Yet. +.FE +.LP +Sources are maintained, saved, and retrievable at any time based on +symbolic or numeric revision or date in the past. +It is entirely up to \fBcvs\fP wrapper programs to provide for release +environments and such. +.PP +The major advantage of \fBcvs\fP over the +many other similar systems that have already been designed is the +simplicity of \fBcvs\fP. +\fBcvs\fP contains only three programs that do all the work of release +and revision control, and two manually-maintained administrative +files for each source repository. +Of course, the deciding factor of any tool is whether people use it, and if +they even \fIlike\fP to use it. +At Prisma, \fBcvs\fP prevented members of the kernel +group from killing each other. +.NH +Acknowledgements +.PP +Many thanks to Dick Grune at Vrije Universiteit in Amsterdam for his work +on the original version of \fBcvs\fP and for making it available to the +world. +Thanks to Jeff Polk of Prisma for helping with the design of the module +database, vendor branch support, and for writing the \fBcheckin\fP shell +script. +Thanks also to the entire software group at Prisma for taking the +time to review the paper and correct my grammar. +.NH +References +.IP [Bell] 12 +Bell Telephone Laboratories. +\*QSource Code Control System User's Guide.\*U +\fIUNIX System III Programmer's Manual\fP, October 1981. +.IP [Courington] 12 +Courington, W. +\fIThe Network Software Environment\fP, +Sun Technical Report FE197-0, Sun Microsystems Inc, February 1989. +.IP [Essick] 12 +Essick, Raymond B. and Robert Bruce Kolstad. +\fINotesfile Reference Manual\fP, +Department of Computer Science Technical Report #1081, +University of Illinois at Urbana-Champaign, Urbana, Illinois, +1982, p. 26. +.IP [Glew] 12 +Glew, Andy. +\*QBoxes, Links, and Parallel Trees: +Elements of a Configuration Management System.\*U +\fIWorkshop Proceedings of the Software Management Conference\fP, USENIX, +New Orleans, April 1989. +.IP [Grune] 12 +Grune, Dick. +Distributed the original shell script version of \fBcvs\fP in the +\fBcomp.sources.unix\fP volume 6 release in 1986. +.IP [Honda] 12 +Honda, Masahiro and Terrence Miller. +\*QSoftware Management Using a CASE Environment.\*U +\fIWorkshop Proceedings of the Software Management Conference\fP, USENIX, +New Orleans, April 1989. +.IP [Mahler] 12 +Mahler, Alex and Andreas Lampen. +\*QAn Integrated Toolset for Engineering Software Configurations.\*U +\fIProceedings of the ACM SIGSOFT/SIGPLAN Software Engineering Symposium on +Practical Software Development Environments\fP, ACM, Boston, November 1988. +Described is the \fBshape\fP toolkit posted to the +\fBcomp.sources.unix\fP newsgroup in the volume 19 release. +.IP [Tichy] 12 +Tichy, Walter F. +\*QDesign, Implementation, and Evaluation of a Revision Control System.\*U +\fIProceedings of the 6th International Conference on Software +Engineering\fP, IEEE, Tokyo, September 1982. +.IP [Wall] 12 +Wall, Larry. +The \fBpatch\fP program is an indispensable tool for applying a diff file +to an original. +Can be found on uunet.uu.net in ~ftp/pub/patch.tar. diff --git a/gnu/usr.bin/cvs/doc/cvs.texinfo b/gnu/usr.bin/cvs/doc/cvs.texinfo new file mode 100644 index 0000000..c38166f --- /dev/null +++ b/gnu/usr.bin/cvs/doc/cvs.texinfo @@ -0,0 +1,6644 @@ +\input texinfo @c -*-texinfo-*- +@comment cvs.texinfo,v 1.3 1994/09/15 23:39:26 zoo Exp +@comment Documentation for CVS. +@comment Copyright (C) 1992, 1993 Signum Support AB +@comment Copyright (C) 1993 Free Software Foundation, Inc. + +@comment This file is part of the CVS distribution. + +@comment CVS is free software; you can redistribute it and/or modify +@comment it under the terms of the GNU General Public License as published by +@comment the Free Software Foundation; either version 1, or (at your option) +@comment any later version. + +@comment CVS is distributed in the hope that it will be useful, +@comment but WITHOUT ANY WARRANTY; without even the implied warranty of +@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +@comment GNU General Public License for more details. + +@comment You should have received a copy of the GNU General Public License +@comment along with CVS; see the file COPYING. If not, write to +@comment the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. + +@afourpaper +@setfilename cvs.info +@settitle CVS---Concurrent Versions System +@setchapternewpage odd + +@c -- TODO list: +@c -- Fix all lines that match "^@c -- " +@c -- Document how CVS finds the binaries it executes. +@c Things to include in the index: +@c Finding RCS binaries +@c Path to RCS binaries +@c RCS, how CVS finds them +@c s/RCS/diff/ +@c -- More on binary files + +@ifinfo +Copyright @copyright{} 1992, 1993 Signum Support AB +Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' and +this permission notice may be included in translations approved by the +Free Software Foundation instead of in the original English. +@end ifinfo + +@comment The titlepage section does not appear in the Info file. +@titlepage +@sp 4 +@comment The title is printed in a large font. +@center @titlefont{Version Management} +@sp +@center @titlefont{with} +@sp +@center @titlefont{CVS} +@sp 2 +@center release 0.9, for @sc{cvs} 1.3+ +@comment -release- +@sp 3 +@center Per Cederqvist +@sp 3 +@center last updated 2 Nov 1993 +@comment -date- + +@comment The following two commands start the copyright page +@comment for the printed manual. This will not appear in the Info file. +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993 Signum Support AB + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' and +this permission notice may be included in translations approved by the +Free Software Foundation instead of in the original English. +@end titlepage + +@comment ================================================================ +@comment The real text starts here +@comment ================================================================ + +@ifinfo +@c --------------------------------------------------------------------- +@node Top +@top + +This info manual describes @sc{cvs} and is updated to +release 1.4 or something similar. +@end ifinfo + +@menu +* Preface:: About this manual +* What is CVS?:: What is CVS? +* Basic concepts:: Basic concepts of revision management +* A sample session:: A tour of basic CVS usage +* Repository:: Where all your sources are stored +* Starting a new project:: Starting a project with CVS +* Multiple developers:: How CVS helps a group of developers +* Branches:: Parallel development explained +* Merging:: How to move changes between branches +* Recursive behavior:: CVS descends directories +* Adding files:: Adding files to a module +* Removing files:: Removing files from a module +* Tracking sources:: Tracking third-party sources +* Moving files:: Moving and renaming files +* Moving directories:: Moving and renaming directories +* Keyword substitution:: CVS can include the revision inside the file +* Revision management:: Policy questions for revision management +* Invoking CVS:: Reference manual for CVS commands +* Administrative files:: Reference manual for the Administrative files +* Environment variables:: All environment variables which affect CVS +* Troubleshooting:: Some tips when nothing works +* Copying:: GNU GENERAL PUBLIC LICENSE +* Index:: Index +@end menu + +@c --------------------------------------------------------------------- +@node Preface +@unnumbered About this manual +@cindex Preface +@cindex About this manual + +Up to this point, one of the weakest parts of @sc{cvs} +has been the documentation. @sc{cvs} is a complex +program. Previous versions of the manual were written +in the manual page format, which is not really well +suited for such a complex program. + +When writing this manual, I had several goals in mind: + +@itemize @bullet +@item +No knowledge of @sc{rcs} should be necessary. + +@item +No previous knowledge of revision control software +should be necessary. All terms, such as @dfn{revision +numbers}, @dfn{revision trees} and @dfn{merging} are +explained as they are introduced. + +@item +The manual should concentrate on the things @sc{cvs} users +want to do, instead of what the @sc{cvs} commands can do. +The first part of this manual leads you through things +you might want to do while doing development, and +introduces the relevant @sc{cvs} commands as they are +needed. + +@item +Information should be easy to find. In the reference +manual in the appendices almost all information about +every @sc{cvs} command is gathered together. There is also +an extensive index, and a lot of cross references. +@end itemize + +@cindex Signum Support +@cindex Support, getting CVS support +This manual was contributed by Signum Support AB in +Sweden. Signum is yet another in the growing list of +companies that support free software. You are free to +copy both this manual and the @sc{cvs} program. +@xref{Copying}, for the details. Signum Support offers +@c -- Check this reference! It has been bogus in the past. +support contracts and binary distribution for many +programs, such as @sc{cvs}, @sc{gnu} Emacs, the +@sc{gnu} C compiler and others. You can also buy +hardcopies of this manual from us. Write to us for +more information. + +@example +Signum Support AB +Box 2044 +S-580 02 Linkoping +Sweden + +Email: info@@signum.se +Phone: +46 (0)13 - 21 46 00 +Fax: +46 (0)13 - 21 47 00 +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@menu +* Checklist:: +* Credits:: +* BUGS:: +@end menu + +@node Checklist +@unnumberedsec Checklist for the impatient reader + +@sc{cvs} is a complex system. You will need to read +the manual to be able to use all of its capabilities. +There are dangers that can easily be avoided if you +know about them, and this manual tries to warn you +about them. This checklist is intended to help you +avoid the dangers without reading the entire manual. +If you intend to read the entire manual you can skip +this table. + +@table @asis +@item Binary files +@sc{cvs} can handle binary files, but +you must have @sc{rcs} release 5.5 or later and +a release of @sc{gnu} diff that supports the @samp{-a} +flag (release 1.15 and later are OK). You must also +configure both @sc{rcs} and @sc{cvs} to handle binary +files when you install them. + +Keword substitution can be a source of trouble with +binary files. @xref{Keyword substitution}, for +solutions. + +@item The @code{admin} command +Uncareful use of the @code{admin} command can cause +@sc{cvs} to cease working. @xref{admin}, before trying +to use it. +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Credits +@unnumberedsec Credits + +@cindex Contributors (manual) +@cindex Credits (manual) +Roland Pesch, Cygnus Support <@t{pesch@@cygnus.com}> +wrote the manual pages which were distributed with +@sc{cvs} 1.3. Appendix A and B contain much text that +was extracted from them. He also read an early draft +of this manual and contributed many ideas and +corrections. + +The mailing-list @code{info-cvs} is sometimes +informative. I have included information from postings +made by the following persons: +David G. Grubbs <@t{dgg@@think.com}>. + +Some text has been extracted from the man pages for +@sc{rcs}. + +The @sc{cvs} @sc{faq} (@pxref{What is CVS?}) by David +G. Grubbs has been used as a check-list to make sure +that this manual is as complete as possible. (This +manual does however not include all of the material in +the @sc{faq}). The @sc{faq} contains a lot of useful +information. + +In addition, the following persons have helped by +telling me about mistakes I've made: +Roxanne Brunskill <@t{rbrunski@@datap.ca}>, +Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>, +Karl Pingle <@t{pingle@@acuson.com}>, +Thomas A Peterson <@t{tap@@src.honeywell.com}>, +Inge Wallin <@t{ingwa@@signum.se}>, +Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}> +and Michael Brown <@t{brown@@wi.extrel.com}>. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node BUGS +@unnumberedsec BUGS + +@cindex Bugs, known in this manual +@cindex Known bugs in this manual +This manual is still very new. Here is a +list of known deficiencies in it: + +@itemize @bullet +@item +In the examples, the output from @sc{cvs} is sometimes +displayed, sometimes not. + +@item +The input that you are supposed to type in the examples +should have a different font than the output from the +computer. + +@item +This manual should be clearer about what file +permissions you should set up in the repository, and +about setuid/setgid. + +@item +Some of the chapters are not yet complete. They are +noted by comments in the @file{cvs.texinfo} file. + +@item +@cindex Reporting bugs (manual) +@cindex Bugs, reporting (manual) +@cindex Errors, reporting (manual) +This list is not complete. If you notice any error, +omission, or something that is unclear, please send +mail to @t{ceder@@signum.se}. +@end itemize + +I hope that you will find this manual useful, despite +the above-mentioned shortcomings. + +@flushright + +Linkoping, October 1993 +Per Cederqvist +@end flushright + +@c --------------------------------------------------------------------- +@node What is CVS? +@chapter What is CVS? +@cindex What is CVS? +@cindex Introduction to CVS +@cindex CVS, introduction to + +@sc{cvs} is a version control system. Using it, you can +record the history of your source files. + +@c -- /// +@c -- ///Those who cannot remember the past are condemned to repeat it. +@c -- /// -- George Santayana +@c -- ////// + +@c -- Insert history quote here! +For example, bugs sometimes creep in when +software is modified, and you might not detect the bug +until a long time after you make the modification. +With @sc{cvs}, you can easily retrieve old versions to see +exactly which change caused the bug. This can +sometimes be a big help. + +You could of course save every version of every file +you have ever created. This would +however waste an enormous amount of disk space. @sc{cvs} +stores all the versions of a file in a single file in a +clever way that only stores the differences between +versions. + +@sc{cvs} also helps you if you are part of a group of people working +on the same project. It is all too easy to overwrite +each others' changes unless you are extremely careful. +Some editors, like @sc{gnu} Emacs, try to make sure that +the same file is never modified by two people at the +same time. Unfortunately, if someone is using another +editor, that safeguard will not work. @sc{cvs} solves this problem +by insulating the different developers from each other. Every +developer works in his own directory, and @sc{cvs} merges +the work when each developer is done. + +@cindex History of CVS +@cindex CVS, history of +@cindex Credits (CVS program) +@cindex Contributors (CVS program) +@sc{cvs} started out as a bunch of shell scripts written by +Dick Grune, posted to @code{comp.sources.unix} in the volume 6 +release of December, 1986. While no actual code from +these shell scripts is present in the current version +of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms +come from them. + +In April, 1989, Brian Berliner designed and coded @sc{cvs}. +Jeff Polk later helped Brian with the design of the @sc{cvs} +module and vendor branch support. + +@cindex Source, getting CVS source +You can get @sc{cvs} via anonymous ftp from a number of +sites, for instance @t{prep.ai.mit.edu} in +@file{pub/gnu}. + +@cindex Mailing list +@cindex List, mailing list +There is a mailing list for @sc{cvs} where bug reports +can be sent, questions can be asked, an FAQ is posted, +and discussion about future enhancements to @sc{cvs} +take place. To submit a message to the list, write to +<@t{info-cvs@@prep.ai.mit.edu}>. To subscribe or +unsubscribe, write to +<@t{info-cvs-request@@prep.ai.mit.edu}>. Please be +specific about your email address. + +Work is in progress on creating a newsgroup for +@sc{cvs}-related topics. It will appear somewhere +under the @samp{gnu.} hierarchy. Gateways to and from +the mailing list will be set up. +@c -- Newsgroup? gnu.cvs.info? + +@cindex FTP site +@cindex Patches to CVS +@cindex CVS FTP site +@cindex Fixes to CVS +@cindex FAQ +@cindex CVS FAQ +The @sc{ftp} site @t{think.com} has some @sc{cvs} +material in the @file{/pub/cvs} subdirectory. +Currently (late summer 1993) it contains an excellent +@sc{faq} (Frequently Asked Questions, with answers), +and an improved (but unofficial) version of @sc{cvs}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@unnumberedsec CVS is not@dots{} + +@sc{cvs} can do a lot of things for you, but it does +not try to be everything for everyone. + +@table @asis +@item @sc{cvs} is not a build system. + +Though the structure of your repository and modules +file interact with your build system +(e.g. @file{Makefile}s), they are essentially +independent. + +@sc{cvs} does not dictate how you build anything. It +merely stores files for retrieval in a tree structure +you devise. + +@sc{cvs} does not dictate how to use disk space in the +checked out working directories. If you write your +@file{Makefile}s or scripts in every directory so they +have to know the relative positions of everything else, +you wind up requiring the entire repository to be +checked out. That's simply bad planning. + +If you modularize your work, and construct a build +system that will share files (via links, mounts, +@code{VPATH} in @file{Makefile}s, etc.), you can +arrange your disk usage however you like. + +But you have to remember that @emph{any} such system is +a lot of work to construct and maintain. @sc{cvs} does +not address the issues involved. You must use your +brain and a collection of other tools to provide a +build scheme to match your plans. + +Of course, you should place the tools created to +support such a build system (scripts, @file{Makefile}s, +etc) under @sc{cvs}. + +@item @sc{cvs} is not a substitute for management. + +Your managers and project leaders are expected to talk +to you frequently enough to make certain you are aware +of schedules, merge points, branch names and release +dates. If they don't, @sc{cvs} can't help. + +@sc{cvs} is an instrument for making sources dance to +your tune. But you are the piper and the composer. No +instrument plays itself or writes its own music. + +@item @sc{cvs} is not a substitute for developer communication. + +When faced with conflicts within a single file, most +developers manage to resolve them without too much +effort. But a more general definition of ``conflict'' +includes problems too difficult to solve without +communication between developers. + +@sc{cvs} cannot determine when simultaneous changes +within a single file, or across a whole collection of +files, will logically conflict with one another. Its +concept of a @dfn{conflict} is purely textual, arising +when two changes to the same base file are near enough +to spook the merge (i.e. @code{diff3}) command. + +@sc{cvs} does not claim to help at all in figuring out +non-textual or distributed conflicts in program logic. + +For example: Say you change the arguments to function +@code{X} defined in file @file{A}. At the same time, +someone edits file @file{B}, adding new calls to +function @code{X} using the old arguments. You are +outside the realm of @sc{cvs}'s competence. + +Acquire the habit of reading specs and talking to your +peers. + + +@item @sc{cvs} is not a configuration management system. + +@sc{cvs} is a source control system. The phrase +``configuration management'' is a marketing term, not +an industry-recognized set of functions. + +A true ``configuration management system'' would contain +elements of the following: + +@itemize @bullet +@item Source control. +@item Dependency tracking. +@item Build systems (i.e. What to build and how to find +things during a build. What is shared? What is local?) +@item Bug tracking. +@item Automated Testing procedures. +@item Release Engineering documentation and procedures. +@item Tape Construction. +@item Customer Installation. +@item A way for users to run different versions of the same +software on the same host at the same time. +@end itemize + +@sc{cvs} provides only the first. +@end table + +This section is taken from release 2.3 of the @sc{cvs} +@sc{faq}. + +@c --------------------------------------------------------------------- +@node Basic concepts +@chapter Basic concepts +@cindex Modules (intro) +@cindex Repository (intro) + +@sc{cvs} stores all files in a centralized @dfn{repository}: a +directory (such as @file{/usr/local/cvsroot}) which is populated with a +hierarchy of files and directories. + +Normally, you never access any of the files in the +repository directly. Instead, you use @sc{cvs} commands to +get your own copy of the files, and then work on that copy. + +The files in the repository are organized in +@dfn{modules}. Each module is made up of one or more +files, and can include files from several directories. +A typical usage is to define one module per project. + +@menu +* Revision numbers:: The meaning of a revision number +* Versions revisions releases:: Terminology used in this manual +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Revision numbers +@section Revision numbers +@cindex Revision numbers +@cindex Revision tree +@cindex Linear development +@cindex Number, revision- +@cindex Decimal revision number +@cindex Main trunk (intro) +@cindex Branch number +@cindex Number, branch + +Each version of a file has a unique @dfn{revision +number}. Revision numbers look like @samp{1.1}, +@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}. +A revision number always has an even number of +period-separated decimal integers. By default revision +1.1 is the first revision of a file. Each successive +revision is given a new number by increasing the +rightmost number by one. The following figure displays +a few revisions, with newer revisions to the right. + +@example + +-----+ +-----+ +-----+ +-----+ +-----+ + ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! + +-----+ +-----+ +-----+ +-----+ +-----+ +@end example + +@sc{cvs} is not limited to linear development. The +@dfn{revision tree} can be split into @dfn{branches}, +where each branch is a self-maintained line of +development. Changes made on one branch can easily be +moved back to the main trunk. + +Each branch has a @dfn{branch number}, consisting of an +odd number of period-separated decimal integers. The +branch number is created by appending an integer to the +revision number where the corresponding branch forked +off. Having branch numbers allows more than one branch +to be forked off from a certain revision. + +@need 3500 +All revisions on a branch have revision numbers formed +by appending an ordinal number to the branch number. +The following figure illustrates branching with an +example. + +@example +@group + +-------------+ + Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 ! + / +-------------+ + / + / + +---------+ +---------+ +---------+ +---------+ +Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 ! + / +---------+ +---------+ +---------+ +---------+ + / + / ++-----+ +-----+ +-----+ +-----+ +-----+ +! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk ++-----+ +-----+ +-----+ +-----+ +-----+ + ! + ! + ! +---------+ +---------+ +---------+ +Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 ! + +---------+ +---------+ +---------+ + +@end group +@end example + +@c -- However, at least for me the figure is not enough. I suggest more +@c -- text to accompany it. "A picture is worth a thousand words", so you +@c -- have to make sure the reader notices the couple of hundred words +@c -- *you* had in mind more than the others! + +@c -- Why an even number of segments? This section implies that this is +@c -- how the main trunk is distinguished from branch roots, but you never +@c -- explicitly say that this is the purpose of the [by itself rather +@c -- surprising] restriction to an even number of segments. + +The exact details of how the branch number is +constructed is not something you normally need to be +concerned about, but here is how it works: When +@sc{cvs} creates a branch number it picks the first +unused even integer, starting with 2. So when you want +to create a branch from revision 6.4 it will be +numbered 6.4.2. All branch numbers ending in a zero +(such as 6.4.0) are used internally by @sc{cvs} +(@pxref{Magic branch numbers}). The branch 1.1.1 has a +special meaning. @xref{Tracking sources}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Versions revisions releases +@section Versions, revisions and releases +@cindex Revisions, versions and releases +@cindex Versions, revisions and releases +@cindex Releases, revisions and versions + +A file can have several versions, as described above. +Likewise, a software product can have several versions. +A software product is often given a version number such +as @samp{4.1.1}. + +Versions in the first sense are called @dfn{revisions} +in this document, and versions in the second sense are +called @dfn{releases}. To avoid confusion, the word +@dfn{version} is almost never used in this document. + +@c --------------------------------------------------------------------- +@node A sample session +@chapter A sample session +@cindex A sample session +@cindex Example of a work-session +@cindex Getting started +@cindex Work-session, example of +@cindex tc, Trivial Compiler (example) +@cindex Trivial Compiler (example) + +This section describes a typical work-session using +@sc{cvs}. It assumes that a repository is set up +(@pxref{Repository}). + +Suppose you are working on a simple compiler. The source +consists of a handful of C files and a @file{Makefile}. +The compiler is called @samp{tc} (Trivial Compiler), +and the repository is set up so that there is a module +called @samp{tc}. + +@menu +* Getting the source:: Creating a workspace +* Committing your changes:: Making your work available to others +* Cleaning up:: Cleaning up +* Viewing differences:: Viewing differences +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Getting the source +@section Getting the source +@cindex Getting the source +@cindex Checking out source +@cindex Fetching source +@cindex Source, getting from CVS +@cindex Checkout, example + +The first thing you must do is to get your own working copy of the +source for @samp{tc}. For this, you use the @code{checkout} command: + +@example +$ cvs checkout tc +@end example + +@noindent +This will create a new directory called @file{tc} and populate it with +the source files. + +@example +$ cd tc +$ ls tc +CVS Makefile backend.c driver.c frontend.c parser.c +@end example + +The @file{CVS} directory is used internally by +@sc{cvs}. Normally, you should not modify or remove +any of the files in it. + +You start your favorite editor, hack away at @file{backend.c}, and a couple +of hours later you have added an optimization pass to the compiler. +A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that +you want to edit. @xref{Multiple developers} for an explanation. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Committing your changes +@section Committing your changes +@cindex Committing changes +@cindex Log message entry +@cindex CVSEDITOR, environment variable +@cindex EDITOR, environment variable + +When you have checked that the compiler is still compilable you decide +to make a new version of @file{backend.c}. + +@example +$ cvs commit backend.c +@end example + +@noindent +@sc{cvs} starts an editor, to allow you to enter a log +message. You type in ``Added an optimization pass.'', +save the temporary file, and exit the editor. + +The environment variable @code{$CVSEDITOR} determines +which editor is started. If @code{$CVSEDITOR} is not +set, then if the environment variable @code{$EDITOR} is +set, it will be used. If both @code{$CVSEDITOR} and +@code{$EDITOR} are not set then the editor defaults to +@code{vi}. If you want to avoid the overhead of +starting an editor you can specify the log message on +the command line using the @samp{-m} flag instead, like +this: + +@example +$ cvs commit -m "Added an optimization pass" backend.c +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Cleaning up +@section Cleaning up +@cindex Cleaning up +@cindex Working copy, removing +@cindex Removing your working copy +@cindex Releasing your working copy + +Before you turn to other tasks you decide to remove your working copy of +tc. One acceptable way to do that is of course + +@example +$ cd .. +$ rm -r tc +@end example + +@noindent +but a better way is to use the @code{release} command (@pxref{release}): + +@example +$ cd .. +$ cvs release -d tc +M driver.c +? tc +You have [1] altered files in this repository. +Are you sure you want to release (and delete) module `tc': n +** `release' aborted by user choice. +@end example + +The @code{release} command checks that all your modifications have been +committed. If history logging is enabled it also makes a note in the +history file. @xref{history file}. + +When you use the @samp{-d} flag with @code{release}, it +also removes your working copy. + +In the example above, the @code{release} command wrote a couple of lines +of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}. +That is nothing to worry about: @file{tc} is the executable compiler, +and it should not be stored in the repository. @xref{cvsignore}, +for information about how to make that warning go away. +@xref{release output}, for a complete explanation of +all possible output from @code{release}. + +@samp{M driver.c} is more serious. It means that the +file @file{driver.c} has been modified since it was +checked out. + +The @code{release} command always finishes by telling +you how many modified files you have in your working +copy of the sources, and then asks you for confirmation +before deleting any files or making any note in the +history file. + +You decide to play it safe and answer @kbd{n @key{RET}} +when @code{release} asks for confirmation. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Viewing differences +@section Viewing differences +@cindex Viewing differences +@cindex Diff + +You do not remember modifying @file{driver.c}, so you want to see what +has happened to that file. + +@example +$ cd tc +$ cvs diff driver.c +@end example + +This command runs @code{diff} to compare the version of @file{driver.c} +that you checked out with your working copy. When you see the output +you remember that you added a command line option that enabled the +optimization pass. You check it in, and release the module. + +@example +$ cvs commit -m "Added an optimization pass" driver.c +Checking in driver.c; +/usr/local/cvsroot/tc/driver.c,v <-- driver.c +new revision: 1.2; previous revision: 1.1 +done +$ cd .. +$ cvs release -d tc +? tc +You have [0] altered files in this repository. +Are you sure you want to release (and delete) module `tc': y +@end example + +@c --------------------------------------------------------------------- +@node Repository +@chapter The Repository +@cindex Repository, example +@cindex Layout of repository +@cindex Typical repository +@cindex CVSROOT, environment variable +@cindex .profile +@cindex .cshrc +@cindex .tcshrc +@cindex .bashrc +@cindex /usr/local/cvsroot +@cindex cvsroot + +Figure 3 below shows a typical setup of a repository. +Only directories are shown below. + +@example +@t{/usr} + | + +--@t{local} + | | + | +--@t{cvsroot} + | | | + | | +--@t{CVSROOT} + | (administrative files) + | + +--@t{gnu} + | | + | +--@t{diff} + | | (source code to @sc{gnu} diff) + | | + | +--@t{rcs} + | | (source code to @sc{rcs}) + | | + | +--@t{cvs} + | (source code to @sc{cvs}) + | + +--@t{yoyodyne} + | + +--@t{tc} + | | + | +--@t{man} + | | + | +--@t{testing} + | + +--(other Yoyodyne software) +@end example + +The @code{$CVSROOT} environment variable should always +be set to an absolute path to the root of the +repository, @file{/usr/local/cvsroot} in this example. +With this setup all @code{csh} and @code{tcsh} users +should have this line in their @file{.cshrc} or +@file{.tcshrc} files: + +@example +setenv CVSROOT /usr/local/cvsroot +@end example + +@noindent +@code{sh} and @code{bash} users should instead have these lines in their +@file{.profile} or @file{.bashrc}: + +@example +CVSROOT=/usr/local/cvsroot +export CVSROOT +@end example + +There is nothing magical about the name +@file{/usr/local/cvsroot}. You can choose to place the +repository anywhere you like, but @code{$CVSROOT} must +always point to it. + +The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains +administrative files for @sc{cvs}. The other directories contain the actual +user-defined modules. + +@menu +* User modules:: The structure of the repository +* Intro administrative files:: Defining modules +* Multiple repositories:: Multiple repositories +* Creating a repository:: Creating a repository +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node User modules +@section User modules +@cindex User modules +@cindex Repository, user parts + +@example + @code{$CVSROOT} + | + +--@t{yoyodyne} + | | + | +--@t{tc} + | | | + +--@t{Makefile,v} + +--@t{backend.c,v} + +--@t{driver.c,v} + +--@t{frontend.c,v} + +--@t{parser.c,v} + +--@t{man} + | | + | +--@t{tc.1,v} + | + +--@t{testing} + | + +--@t{testpgm.t,v} + +--@t{test2.t,v} +@end example + +@cindex History files +@cindex RCS history files +@cindex RCS, CVS uses RCS +The figure above shows the contents of the @samp{tc} +module inside the repository. As you can see all file +names end in @samp{,v}. The files are @dfn{history +files}. They contain, among other things, enough +information to recreate any revision of the file, a log +of all commit messages and the user-name of the person +who committed the revision. @sc{cvs} uses the +facilities of @sc{rcs}, a simpler version control +system, to maintain these files. For a full +description of the file format, see the @code{man} page +@cite{rcsfile(5)}. +@c -- Use this format for all references to man pages, +@c -- or use something better! + +@menu +* File permissions:: File permissions +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node File permissions +@subsection File permissions +@c -- Move this to @node Setting up +@cindex Security +@cindex File permissions +@cindex Group +All @samp{,v} files are created read-only, and you +should not change the permission of those files. The +directories inside the repository should be writable by +the persons that have permission to modify the files in +each directory. This normally means that you must +create a UNIX group (see group(5)) consisting of the +persons that are to edit the files in a project, and +set up the repository so that it is that group that +owns the directory. + +This means that you can only control access to files on +a per-directory basis. + +@sc{cvs} tries to set up reasonable file permissions +for new directories that are added inside the tree, but +you must fix the permissions manually when a new +directory should have different permissions than its +parent directory. + +@cindex setuid +@cindex setgid +Since @sc{cvs} was not written to be run setuid, it is +unsafe to try to run it setuid. You cannot use the +setuid features of @sc{rcs} together with @sc{cvs}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Intro administrative files +@section The administrative files +@cindex Administrative files (intro) +@cindex Modules file +@cindex CVSROOT, module name +@cindex Defining modules (intro) + +The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative +files}. @xref{Administrative files}, for a complete description. +You can use @sc{cvs} without any of these files, but +some commands work better when at least the +@file{modules} file is properly set up. + +The most important of these files is the @file{modules} +file. It defines all modules in the repository. This +is a sample @file{modules} file. + +@example +CVSROOT -i mkmodules CVSROOT +modules -i mkmodules CVSROOT modules +cvs gnu/cvs +rcs gnu/rcs +diff gnu/diff +tc yoyodyne/tc +@end example + +The @file{modules} file is line oriented. In its simplest form each +line contains the name of the module, whitespace, and the directory +where the module resides. The directory is a path relative to +@code{$CVSROOT}. The last for lines in the example +above are examples of such lines. + +@cindex mkmodules +Each module definition can contain options. The @samp{-i mkmodules} is +an example of an option. It arranges for @sc{cvs} to run the +@code{mkmodules} program whenever any file in the module CVSROOT is +committed. That program is responsible for checking out read-only +copies from the @sc{rcs} @dfn{history files} of all the administrative files. +These read-only copies are used internally by @sc{cvs}. You +should never edit them directly. + +The line that defines the module called @samp{modules} +uses features that are not explained here. +@xref{modules}, for a full explanation of all the +available features. + +@subsection Editing administrative files +@cindex Editing administrative files +@cindex Administrative files, editing them + +You edit the administrative files in the same way that you would edit +any other module. Use @samp{cvs checkout CVSROOT} to get a working +copy, edit it, and commit your changes in the normal way. + +It is possible to commit an erroneous administrative +file. You can often fix the error and check in a new +revision, but sometimes a particularly bad error in the +administrative file makes it impossible to commit new +revisions. +@c @xref{Bad administrative files} for a hint +@c about how to solve such situations. +@c -- administrative file checking-- + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Multiple repositories +@section Multiple repositories +@cindex Multiple repositories +@cindex Repositories, multiple +@cindex Many repositories +@cindex Parallel repositories +@cindex Disjoint repositories +@cindex CVSROOT, multiple repositories + +In some situations it is a good idea to have more than +one repository, for instance if you have two +development groups that work on separate projects +without sharing any code. All you have to do to have +several repositories is to set @code{$CVSROOT} to the +repository you want to use at the moment. + +There are disadvantages to having more than one +repository. In @sc{cvs} 1.3 you @emph{must} make sure +that @code{$CVSROOT} always points to the correct +repository. If the same filename is used in two +repositories, and you mix up the setting of +@code{$CVSROOT}, you might lose data. @sc{cvs} 1.4 +solves this problem by saving the repository +information in the local @file{CVS} administration +files. If you try to use the wrong repository, +@sc{cvs} will warn you of the attempt and then exit. + +Notwithstanding, it can be confusing to have two or +more repositories. + +All examples in this manual assume that you have a +single repository. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Creating a repository +@section Creating a repository +@c -- Well, how do you do? + +See the instructions in the @file{INSTALL} file in the +@sc{cvs} distribution. + +@c --------------------------------------------------------------------- +@node Starting a new project +@chapter Starting a project with CVS +@cindex Starting a project with CVS +@cindex Creating a project + +@comment --moduledb-- +Since @sc{cvs} 1.x is bad at renaming files and moving +them between directories, the first thing you do when +you start a new project should be to think through your +file organization. It is not impossible---just +awkward---to rename or move files in @sc{cvs} 1.x. +@xref{Moving files}. + +What to do next depends on the situation at hand. + +@menu +* Setting up the files:: Getting the files into the repository +* Defining the module:: How to make a module of the files +@end menu +@c -- File permissions! + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Setting up the files +@section Setting up the files + +The first step is to create the files inside the repository. This can +be done in a couple of different ways. + +@c -- The contributed scripts +@menu +* From files:: This method is useful with old projects + where files already exists. + +* From scratch:: Creating a module from scratch. +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node From files +@subsection Creating a module from a number of files +@cindex Importing files + +When you begin using @sc{cvs}, you will probably already have several +projects that can be +put under @sc{cvs} control. In these cases the easiest way is to use the +@code{import} command. An example is probably the easiest way to +explain how to use it. If the files you want to install in +@sc{cvs} reside in @file{@var{dir}}, and you want them to appear in the +repository as @file{$CVSROOT/yoyodyne/@var{dir}}, you can do this: + +@example +$ cd @var{dir} +$ cvs import -m "Imported sources" yoyodyne/@var{dir} yoyo start +@end example + +Unless you supply a log message with the @samp{-m} +flag, @sc{cvs} starts an editor and prompts for a +message. The string @samp{yoyo} is a @dfn{vendor tag}, +and @samp{start} is a @dfn{release tag}. They may fill +no purpose in this context, but since @sc{cvs} requires +them they must be present. @xref{Tracking sources}, for +more information about them. + +You can now verify that it worked, and remove your +original source directory. + +@example +$ cd .. +$ mv @var{dir} @var{dir}.orig +$ cvs checkout yoyodyne/@var{dir} # @r{Explanation below} +$ ls -R yoyodyne +$ rm -r @var{dir}.orig +@end example + +@noindent +Erasing the original sources is a good idea, to make sure that you do +not accidentally edit them in @var{dir}, bypassing @sc{cvs}. +Of course, it would be wise to make sure that you have +a backup of the sources before you remove them. + +The @code{checkout} command can either take a module +name as argument (as it has done in all previous +examples) or a path name relative to @code{$CVSROOT}, +as it did in the example above. + +It is a good idea to check that the permissions +@sc{cvs} sets on the directories inside @samp{$CVSROOT} +are reasonable, and that they belong to the proper +groups. @xref{File permissions}. + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node From scratch +@subsection Creating a module from scratch + +For a new project, the easiest thing to do is probably +to create an empty directory structure, like this: + +@example +$ mkdir tc +$ mkdir tc/man +$ mkdir tc/testing +@end example + +After that, you use the @code{import} command to create +the corresponding (empty) directory structure inside +the repository: + +@example +$ cd tc +$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start +@end example + +Then, use @code{add} to add files (and new directories) +as they appear. + +Check that the permissions @sc{cvs} sets on the +directories inside @samp{$CVSROOT} are reasonable. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Defining the module +@section Defining the module +@cindex Defining a module +@cindex Editing the modules file +@cindex Module, defining +@cindex Modules file, changing + +The next step is to define the module in the @file{modules} file. Some +@sc{cvs} commands work without this step, but others (most notably +@code{release}) require that all modules are properly defined in the +@file{modules} file. + +In simple cases these steps are sufficient to define a module. + +@enumerate +@item +Get a working copy of the modules file. + +@example +$ cvs checkout modules +$ cd modules +@end example + +@item +Edit the file and insert a line that defines the module. @xref{Intro +administrative files}, for an introduction. @xref{modules}, for a full +description of the modules file. You can use the +following line to define the module @samp{tc}: + +@example +tc yoyodyne/tc +@end example + +@item +Commit your changes to the modules file. + +@example +$ cvs commit -m "Added the tc module." modules +@end example + +@item +Release the modules module. + +@example +$ cd .. +$ cvs release -d modules +@end example +@end enumerate + +@c --------------------------------------------------------------------- +@node Multiple developers +@chapter Multiple developers +@cindex Multiple developers +@cindex Team of developers +@cindex File locking +@cindex Locking files +@cindex Working copy + +When more than one person works on a software project +things often get complicated. Often, two people try to +edit the same file simultaneously. Some other version +control systems (including @sc{rcs} and @sc{sccs}) +try to solve that particular problem by introducing +@dfn{file locking}, so that only one person can edit +each file at a time. Unfortunately, file locking can +be very counter-productive. If two persons want +to edit different parts of a file, there may be no +reason to prevent either of them from doing so. + +@sc{cvs} does not use file locking. Instead, it allows many +people to edit their own @dfn{working copy} of a file +simultaneously. The first person that commits his +changes has no automatic way of knowing that another has started to +edit it. Others will get an error message when they +try to commit the file. They must then use @sc{cvs} +commands to bring their working copy up to date with +the repository revision. This process is almost +automatic, and explained in this chapter. + +There are many ways to organize a team of developers. +@sc{cvs} does not try to enforce a certain +organization. It is a tool that can be used in several +ways. It is often useful to inform the group of +commits you have done. @sc{cvs} has several ways of +automating that process. @xref{Informing others}. +@xref{Revision management}, for more tips on how to use +@sc{cvs}. + +@menu +* File status:: A file can be in several states +* Updating a file:: Bringing a file up-to-date +* Conflicts example:: An informative example +* Informing others:: To cooperate you must inform +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node File status +@section File status +@cindex File status +@cindex Status of a file +@cindex Four states of a file + +After you have checked out a file out from @sc{cvs}, it is in +one of these four states: + +@table @asis +@cindex Up-to-date +@item Up-to-date +The file is identical with the latest revision in the +repository. +@c -- The above is not always true if branching is used. + +@item Locally modified +@cindex Locally modified +You have edited the file, and not yet committed your changes. + +@item Needing update +@cindex Needing update +Someone else has committed a newer revision to the repository. + +@item Needing merge +@cindex Needing merge +Someone else have committed a newer revision to the repository, and you +have also made modifications to the file. +@c -- What about "added" "removed" and so on? +@end table + +You can use the @code{status} command to find out the status of a given +file. @xref{status}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Updating a file +@section Bringing a file up to date +@cindex Bringing a file up to date +@cindex Updating a file +@cindex Merging a file +@cindex update, introduction + +When you want to update or merge a file, use the @code{update} +command. For files that are not up to date this is roughly equivalent +to a @code{checkout} command: the newest revision of the file is +extracted from the repository and put in your working copy of the +module. + +Your modifications to a file are never lost when you +use @code{update}. If no newer revision exists, +running @code{update} has no effect. If you have +edited the file, and a newer revision is available, +@sc{cvs} will merge all changes into your working copy. + +For instance, imagine that you checked out revision 1.4 and started +editing it. In the meantime someone else committed revision 1.5, and +shortly after that revision 1.6. If you run @code{update} on the file +now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into +your file. + +@cindex Overlap +If any of the changes between 1.4 and 1.6 were made too +close to any of the changes you have made, an +@dfn{overlap} occurs. In such cases a warning is +printed, and the resulting file includes both +versions of the lines that overlap, delimited by +special markers. +@xref{update}, for a complete description of the +@code{update} command. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Conflicts example +@section Conflicts example +@cindex Merge, an example +@cindex Example of merge +@cindex driver.c (merge example) + +Suppose revision 1.4 of @file{driver.c} contains this: + +@example +#include <stdio.h> + +void main() +@{ + parse(); + if (nerr == 0) + gencode(); + else + fprintf(stderr, "No code generated.\n"); + exit(nerr == 0 ? 0 : 1); +@} +@end example + +@noindent +Revision 1.6 of @file{driver.c} contains this: + +@example +#include <stdio.h> + +int main(int argc, + char **argv) +@{ + parse(); + if (argc != 1) + @{ + fprintf(stderr, "tc: No args expected.\n"); + exit(1); + @} + if (nerr == 0) + gencode(); + else + fprintf(stderr, "No code generated.\n"); + exit(!!nerr); +@} +@end example + +@noindent +Your working copy of @file{driver.c}, based on revision +1.4, contains this before you run @samp{cvs update}: +@c -- Really include "cvs"? + +@example +#include <stdlib.h> +#include <stdio.h> + +void main() +@{ + init_scanner(); + parse(); + if (nerr == 0) + gencode(); + else + fprintf(stderr, "No code generated.\n"); + exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +@} +@end example + +@noindent +You run @samp{cvs update}: +@c -- Really include "cvs"? + +@example +$ cvs update driver.c +RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v +retrieving revision 1.4 +retrieving revision 1.6 +Merging differences between 1.4 and 1.6 into driver.c +rcsmerge warning: overlaps during merge +cvs update: conflicts found in driver.c +C driver.c +@end example + +@noindent +@cindex Conflicts (merge example) +@sc{cvs} tells you that there were some conflicts. +Your original working file is saved unmodified in +@file{.#driver.c.1.4}. The new version of +@file{driver.c} contains this: + +@example +#include <stdlib.h> +#include <stdio.h> + +int main(int argc, + char **argv) +@{ + init_scanner(); + parse(); + if (argc != 1) + @{ + fprintf(stderr, "tc: No args expected.\n"); + exit(1); + @} + if (nerr == 0) + gencode(); + else + fprintf(stderr, "No code generated.\n"); +<<<<<<< driver.c + exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +======= + exit(!!nerr); +>>>>>>> 1.6 +@} +@end example + +@noindent +@cindex Markers, conflict +@cindex Conflict markers +@cindex <<<<<<< +@cindex >>>>>>> +@cindex ======= + +Note how all non-overlapping modifications are incorporated in your working +copy, and that the overlapping section is clearly marked with +@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}. + +@cindex Resolving a conflict +@cindex Conflict resolution +You resolve the conflict by editing the file, removing the markers and +the erroneous line. Suppose you end up with this file: +@c -- Add xref to the pcl-cvs manual when it talks +@c -- about this. +@example +#include <stdlib.h> +#include <stdio.h> + +int main(int argc, + char **argv) +@{ + init_scanner(); + parse(); + if (argc != 1) + @{ + fprintf(stderr, "tc: No args expected.\n"); + exit(1); + @} + if (nerr == 0) + gencode(); + else + fprintf(stderr, "No code generated.\n"); + exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE); +@} +@end example + +@noindent +You can now go ahead and commit this as revision 1.7. + +@example +$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c +Checking in driver.c; +/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c +new revision: 1.7; previous revision: 1.6 +done +@end example + +@cindex emerge +If you use release 1.04 or later of pcl-cvs (a @sc{gnu} +Emacs front-end for @sc{cvs}) you can use an Emacs +package called emerge to help you resolve conflicts. +See the documentation for pcl-cvs. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Informing others +@section Informing others about commits +@cindex Informing others +@cindex Spreading information +@cindex Mail, automatic mail on commit + +It is often useful to inform others when you commit a +new revision of a file. The @samp{-i} option of the +@file{modules} file, or the @file{loginfo} file, can be +used to automate this process. @xref{modules}. +@xref{loginfo}. You can use these features of @sc{cvs} +to, for instance, instruct @sc{cvs} to mail a +message to all developers, or post a message to a local +newsgroup. +@c -- More text would be nice here. + +@c --------------------------------------------------------------------- +@node Branches +@chapter Branches +@cindex Branches +@cindex Main trunk and branches +@cindex Revision tree, making branches + +So far, all revisions shown in this manual have been on +the @dfn{main trunk} +of the revision tree, i.e., all revision numbers +have been of the form @var{x}.@var{y}. One useful +feature, especially when maintaining several releases +of a software product at once, is the ability to make +branches on the revision tree. @dfn{Tags}, symbolic +names for revisions, will also be +introduced in this chapter. + +@menu +* Tags:: Tags--Symbolic revisions +* Branches motivation:: What branches are good for +* Creating a branch:: Creating a branch +* Sticky tags:: Sticky tags +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Tags +@section Tags--Symbolic revisions +@cindex Tags + +The revision numbers live a life of their own. They +need not have anything at all to do with the release +numbers of your software product. Depending +on how you use @sc{cvs} the revision numbers might change several times +between two releases. As an example, some of the +source files that make up @sc{rcs} 5.6 have the following +revision numbers: +@cindex RCS revision numbers + +@example +ci.c 5.21 +co.c 5.9 +ident.c 5.3 +rcs.c 5.12 +rcsbase.h 5.11 +rcsdiff.c 5.10 +rcsedit.c 5.11 +rcsfcmp.c 5.9 +rcsgen.c 5.10 +rcslex.c 5.11 +rcsmap.c 5.2 +rcsutil.c 5.10 +@end example + +@cindex tag, command, introduction +@cindex Tag, symbolic name +@cindex Symbolic name (tag) +@cindex Name, symbolic (tag) +You can use the @code{tag} command to give a symbolic name to a +certain revision of a file. You can use the @samp{-v} flag to the +@code{status} command to see all tags that a file has, and +which revision numbers they represent. (The output of @code{status} +unfortunately uses the word ``version'' instead of ``revision''.) +@c -- Is this fixed in CVS 1.3.1? + +@cindex Adding a tag +@cindex tag, example +The following example shows how you can add a tag to a +file. The commands must be issued inside your working +copy of the module. That is, you should issue the +command in the directory where @file{backend.c} +resides. + +@example +$ cvs tag release-0-4 backend.c +T backend.c +$ cvs status -v backend.c +=================================================================== +File: backend.c Status: Up-to-date + + Version: 1.4 Tue Dec 1 14:39:01 1992 + RCS Version: 1.4 /usr/local/cvsroot/yoyodyne/tc/backend.c,v + Sticky Tag: (none) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + release-0-4 (revision: 1.4) + +@end example + +There is seldom reason to tag a file in isolation. A more common use is +to tag all the files that constitute a module with the same tag at +strategic points in the development life-cycle, such as when a release +is made. + +@example +$ cvs tag release-1-0 . +cvs tag: Tagging . +T Makefile +T backend.c +T driver.c +T frontend.c +T parser.c +@end example + +(When you give @sc{cvs} a directory as argument, it generally applies the +operation to all the files in that directory, and (recursively), to any +subdirectories that it may contain. @xref{Recursive behavior}.) + +@cindex Retrieving an old revision using tags +@cindex Tag, retrieving old revisions +The @code{checkout} command has a flag, @samp{-r}, that lets you check out +a certain revision of a module. This flag makes it easy to +retrieve the sources that make up release 1.0 of the module @samp{tc} at +any time in the future: + +@example +$ cvs checkout -r release-1-0 tc +@end example + +@noindent +This is useful, for instance, if someone claims that there is a bug in +that release, but you cannot find the bug in the current working copy. + +You can also check out a module as it was at any given date. +@xref{checkout options}. + +When you tag more than one file with the same tag you +can think about the tag as "a curve drawn through a +matrix of filename vs. revision number." Say we have 5 +files with the following revisions: + +@example +@group + file1 file2 file3 file4 file5 + + 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG + 1.2*- 1.2 1.2 -1.2*- + 1.3 \- 1.3*- 1.3 / 1.3 + 1.4 \ 1.4 / 1.4 + \-1.5*- 1.5 + 1.6 +@end group +@end example + +At some time in the past, the @code{*} versions were tagged. +You can think of the tag as a handle attached to the curve +drawn through the tagged revisions. When you pull on +the handle, you get all the tagged revisions. Another +way to look at it is that you "sight" through a set of +revisions that is "flat" along the tagged revisions, +like this: + +@example +@group + file1 file2 file3 file4 file5 + + 1.1 + 1.2 + 1.1 1.3 _ + 1.1 1.2 1.4 1.1 / + 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here + 1.3 1.6 1.3 \_ + 1.4 1.4 + 1.5 +@end group +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Branches motivation +@section What branches are good for +@cindex Branches motivation +@cindex What branches are good for +@cindex Motivation for branches + +Suppose that release 1.0 of tc has been made. You are continuing to +develop tc, planning to create release 1.1 in a couple of months. After a +while your customers start to complain about a fatal bug. You check +out release 1.0 (@pxref{Tags}) and find the bug +(which turns out to have a trivial fix). However, the current revision +of the sources are in a state of flux and are not expected to be stable +for at least another month. There is no way to make a +bugfix release based on the newest sources. + +The thing to do in a situation like this is to create a @dfn{branch} on +the revision trees for all the files that make up +release 1.0 of tc. You can then make +modifications to the branch without disturbing the main trunk. When the +modifications are finished you can select to either incorporate them on +the main trunk, or leave them on the branch. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Creating a branch +@section Creating a branch +@cindex Creating a branch +@cindex Branch, creating a +@cindex rtag, creating a branch using + +The @code{rtag} command can be used to create a branch. +The @code{rtag} command is much like @code{tag}, but it +does not require that you have a working copy of the +module. @xref{rtag}. (You can also use the @code{tag} +command; @pxref{tag}). + +@example +$ cvs rtag -b -r release-1-0 release-1-0-patches tc +@end example + +The @samp{-b} flag makes @code{rtag} create a branch +(rather than just a symbolic revision name). @samp{-r +release-1-0} says that this branch should be rooted at the node (in +the revision tree) that corresponds to the tag +@samp{release-1-0}. Note that the numeric revision number that matches +@samp{release-1-0} will probably be different from file to file. The +name of the new branch is @samp{release-1-0-patches}, and the +module affected is @samp{tc}. + +To fix the problem in release 1.0, you need a working +copy of the branch you just created. + +@example +$ cvs checkout -r release-1-0-patches tc +$ cvs status -v driver.c backend.c +=================================================================== +File: driver.c Status: Up-to-date + + Version: 1.7 Sat Dec 5 18:25:54 1992 + RCS Version: 1.7 /usr/local/cvsroot/yoyodyne/tc/driver.c,v + Sticky Tag: release-1-0-patches (branch: 1.7.2) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + release-1-0-patches (branch: 1.7.2) + release-1-0 (revision: 1.7) + +=================================================================== +File: backend.c Status: Up-to-date + + Version: 1.4 Tue Dec 1 14:39:01 1992 + RCS Version: 1.4 /usr/local/cvsroot/yoyodyne/tc/backend.c,v + Sticky Tag: release-1-0-patches (branch: 1.4.2) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + release-1-0-patches (branch: 1.4.2) + release-1-0 (revision: 1.4) + release-0-4 (revision: 1.4) + +@end example + +@cindex Branch numbers +As the output from the @code{status} command shows the branch +number is created by adding a digit at the tail of the revision number +it is based on. (If @samp{release-1-0} corresponds to revision 1.4, the +branch's revision number will be 1.4.2. For obscure reasons @sc{cvs} always +gives branches even numbers, starting at 2. +@xref{Revision numbers}). + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Sticky tags +@section Sticky tags +@cindex Sticky tags +@cindex Tags, sticky +@cindex Branches, sticky + +The @samp{-r release-1-0-patches} flag that was given to @code{checkout} +is @dfn{sticky}, that is, it will apply to subsequent commands +in this directory. If you commit any modifications, they are +committed on the branch. You can later merge the modifications into +the main trunk. @xref{Merging}. + +@example +$ vi driver.c # @r{Fix the bugs} +$ cvs commit -m "Fixed initialization bug" driver.c +Checking in driver.c; +/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c +new revision: 1.7.2.1; previous revision: 1.7 +done +$ cvs status -v driver.c +=================================================================== +File: driver.c Status: Up-to-date + + Version: 1.7.2.1 Sat Dec 5 19:35:03 1992 + RCS Version: 1.7.2.1 /usr/local/cvsroot/yoyodyne/tc/driver.c,v + Sticky Tag: release-1-0-patches (branch: 1.7.2) + Sticky Date: (none) + Sticky Options: (none) + + Existing Tags: + release-1-0-patches (branch: 1.7.2) + release-1-0 (revision: 1.7) + +@end example + +@cindex Resetting sticky tags +@cindex Sticky tags, resetting +@cindex Deleting sticky tags +The sticky tags will remain on your working files until +you delete them with @samp{cvs update -A}. @xref{update}. + +Sticky tags are not just for branches. If you check +out a certain revision (such as 1.4) it will also +become sticky. Subsequent @samp{cvs update} will not +retrieve the latest revision until you reset the tag +with @samp{cvs update -A}. + +See the descriptions in Appendix A for more information +about sticky tags. Dates and some other options can +also be sticky. Again, see Appendix A for details. +@c -- xref to relevant part of App A. +@c -- Re-evaluate this node. + +@c --------------------------------------------------------------------- +@node Merging +@chapter Merging +@cindex Merging +@cindex Copying changes +@cindex Branches, copying changes between +@cindex Changes, copying between branches +@cindex Modifications, copying between branches + +You can include the changes made between any two +revisions into your working copy, by @dfn{merging}. +You can then commit that revision, and thus effectively +copy the changes onto another branch. + +@menu +* Merging a branch:: Merging an entire branch +* Merging two revisions:: Merging differences between two revisions +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Merging a branch +@section Merging an entire branch +@cindex Merging a branch +@cindex -j (merging branches) + +You can merge changes made on a branch into your working copy by giving +the @samp{-j @var{branch}} flag to the @code{update} command. With one +@samp{-j @var{branch}} option it merges the changes made between the +point where the branch forked and newest revision on that branch (into +your working copy). + +@cindex Join +The @samp{-j} stands for ``join''. In previous +versions of @sc{cvs} there was a special command, +@samp{cvs join}, that was used to merge changes between +branches. + +@cindex Branch merge example +@cindex Example, branch merge +@cindex Merge, branch example +Consider this revision tree: + +@example ++-----+ +-----+ +-----+ +-----+ +-----+ +! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk ++-----+ +-----+ +-----+ +-----+ +-----+ + ! + ! + ! +---------+ +---------+ +---------+ +Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 ! + +---------+ +---------+ +---------+ +@end example + +@noindent +The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The +following example assumes that the module @samp{mod} contains only one +file, @file{m.c}. + +@example +$ cvs checkout mod # @r{Retrieve the latest revision, 1.5} + +$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,} + # @r{i.e. the changes between revision 1.2} + # @r{and 1.2.2.3, into your working copy} + # @r{of the file.} + +$ cvs commit -m "Included R1fix" # @r{Create revision 1.6.} +@end example + +A conflict can result from a merge operation. If that +happens, you should resolve it before committing the +new revision. @xref{Conflicts example}. + +The @code{checkout} command also supports the @samp{-j @var{branch}} flag. The +same effect as above could be achieved with this: + +@example +$ cvs checkout -j R1fix mod +$ cvs commit -m "Included R1fix" +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Merging two revisions +@section Merging differences between any two revisions +@cindex Merging two revisions +@cindex Revisions, merging differences between +@cindex Differences, merging + +With two @samp{-j @var{revision}} flags, the @code{update} +(and @code{checkout}) command can merge the differences +between any two revisions into your working file. + +@cindex Undoing a change +@cindex Removing a change +@example +$ cvs update -j 1.5 -j 1.3 backend.c +@end example + +@noindent +will @emph{remove} all changes made between revision +1.3 and 1.5. Note the order of the revisions! + +If you try to use this option with the @code{checkout} +command, remember that the numeric revisions will +probably be very different between the various files +that make up a module. You almost always use symbolic +tags rather than revision numbers with the +@code{checkout} command. + +@c --------------------------------------------------------------------- +@node Recursive behavior +@chapter Recursive behavior +@cindex Recursive (directory descending) +@cindex Directory, descending +@cindex Descending directories +@cindex Subdirectories + +Almost all of the subcommands of @sc{cvs} work +recursively when you specify a directory as an +argument. For instance, consider this directory +structure: + +@example + @code{$HOME} + | + +--@t{tc} + | | + +--@t{CVS} + | (internal @sc{cvs} files) + +--@t{Makefile} + +--@t{backend.c} + +--@t{driver.c} + +--@t{frontend.c} + +--@t{parser.c} + +--@t{man} + | | + | +--@t{CVS} + | | (internal @sc{cvs} files) + | +--@t{tc.1} + | + +--@t{testing} + | + +--@t{CVS} + | (internal @sc{cvs} files) + +--@t{testpgm.t} + +--@t{test2.t} +@end example + +@noindent +If @file{tc} is the current working directory, the +following is true: + +@itemize @bullet +@item +@samp{cvs update testing} is equivalent to @samp{cvs +update testing/testpgm.t testing/test2.t} + +@item +@samp{cvs update testing man} updates all files in the +subdirectories + +@item +@samp{cvs update .} or just @samp{cvs update} updates +all files in the @code{tc} module +@end itemize + +If no arguments are given to @code{update} it will +update all files in the current working directory and +all its subdirectories. In other words, @file{.} is a +default argument to @code{update}. This is also true +for most of the @sc{cvs} subcommands, not only the +@code{update} command. + +The recursive behavior of the @sc{cvs} subcommands can be +turned off with the @samp{-l} option. + +@example +$ cvs update -l # @r{Don't update files in subdirectories} +@end example + +@c --------------------------------------------------------------------- +@node Adding files +@chapter Adding files to a module +@cindex Adding files + +To add a new file to a module, follow these steps. + +@itemize @bullet +@item +You must have a working copy of the module. +@xref{Getting the source}. + +@item +Create the new file inside your working copy of the module. + +@item +Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you +want to version control the file. + +@item +Use @samp{cvs commit @var{filename}} to actually check +in the file into the repository. Other developers +cannot see the file until you perform this step. + +@item +If the file contains binary data it might be necessary +to change the default keyword substitution. +@xref{Keyword substitution}. @xref{admin examples}. +@end itemize + +You can also use the @code{add} command to add a new +directory inside a module. + +Unlike most other commands, the @code{add} command is +not recursive. You cannot even type @samp{cvs add +foo/bar}! Instead, you have to + +@example +$ cd foo +$ cvs add bar +@end example + +@xref{add}, for a more complete description of the @code{add} +command. + +@c --------------------------------------------------------------------- +@node Removing files +@chapter Removing files from a module +@cindex Removing files +@cindex Deleting files + +Modules change. New files are added, and old files +disappear. Still, you want to be able to retrieve an +exact copy of old releases of the module. + +Here is what you can do to remove a file from a module, +but remain able to retrieve old revisions: + +@itemize @bullet +@item +Make sure that you have not made any uncommitted +modifications to the file. @xref{Viewing differences}, +for one way to do that. You can also use the +@code{status} or @code{update} command. If you remove +the file without committing your changes, you will of +course not be able to retrieve the file as it was +immediately before you deleted it. + +@item +Remove the file from your working copy of the module. +You can for instance use @code{rm}. + +@item +Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that +you really want to delete the file. + +@item +Use @samp{cvs commit @var{filename}} to actually +perform the removal of the file from the repository. +@end itemize + +What happens when you commit the removal of the file is +that inside the source repository, it is moved into a +subdirectory called @file{Attic}. @sc{cvs} normally doesn't +look in that directory when you run e.g. +@code{checkout}. However, if you are retrieving a +certain revision via e.g. @samp{cvs checkout -r +@var{some-tag}}, it will look at the files inside the +@file{Attic} and include any files that contain the +specified tag. + +This method is simple and works quite well, but it has +some known deficiencies: + +@itemize @bullet +@item +If you remove the file @file{foo.c}, you cannot later +create a new file called @file{foo.c} unless you +manually remove the file @file{Attic/foo.c,v} inside +the repository. On the other hand, if you remove +@file{Attic/foo.c,v} you will of course not be able to +retrieve any revision of the old file @file{foo.c}. + +@item +If the file @file{bar.c} is present in release 1.0 of a +product, and was accidentally removed in release 1.1, +you cannot easily resurrect it to release 1.2. You +have to move the file out of the @file{Attic} manually +inside the repository. (Do a @samp{mv Attic/@var{file} +@var{file}}). +@end itemize + +There is a design for a @dfn{rename database} that will +solve these problems and many others, but it is not yet +implemented. + +@c --------------------------------------------------------------------- +@node Tracking sources +@chapter Tracking third-party sources +@cindex Third-party sources +@cindex Tracking sources + +If you modify a program to better fit your site, you +probably want to include your modifications when the next +release of the program arrives. @sc{cvs} can help you with +this task. + +@cindex Vendor +@cindex Vendor branch +@cindex Branch, vendor- +In the terminology used in @sc{cvs}, the supplier of the +program is called a @dfn{vendor}. The unmodified +distribution from the vendor is checked in on its own +branch, the @dfn{vendor branch}. @sc{cvs} reserves branch +1.1.1 for this use. + +When you modify the source and commit it, your revision +will end up on the main trunk. When a new release is +made by the vendor, you commit it on the vendor branch +and copy the modifications onto the main trunk. + +Use the @code{import} command to create and update +the vendor branch. After a successful @code{import} +the vendor branch is made the `head' revision, so +anyone that checks out a copy of the file gets that +revision. When a local modification is committed it is +placed on the main trunk, and made the `head' +revision. + +@menu +* First import:: Importing a module for the first time +* Update imports:: Updating a module with the import command +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node First import +@section Importing a module for the first time +@cindex Importing modules + +Use the @code{import} command to check in the sources +for the first time. When you use the @code{import} +command to track third-party sources, the @dfn{vendor +tag} and @dfn{release tags} are useful. The +@dfn{vendor tag} is a symbolic name for the branch +(which is always 1.1.1, unless you use the @samp{-b +@var{branch}} flag---@xref{import options}). The +@dfn{release tags} are symbolic names for a particular +release, such as @samp{FSF_0_04}. + +@cindex Wdiff (import example) +Suppose you use @code{wdiff} (a variant of @code{diff} +that ignores changes that only involve whitespace), and +are going to make private modifications that you want +to be able to use even when new releases are made in +the future. You start by importing the source to your +repository: + +@example +$ tar xfz wdiff-0.04.tar.gz +$ cd wdiff-0.04 +$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF WDIFF_0_04 +@end example + +The vendor tag is named @samp{FSF} in the above +example, and the only release tag assigned is +@samp{WDIFF_0_04}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Update imports +@section Updating a module with the import command + +When a new release of the source arrives, you import it into the +repository with the same @code{import} command that you used to set up +the repository in the first place. The only difference is that you +specify a different release tag this time. + +@example +$ tar xfz wdiff-0.05.tar.gz +$ cd wdiff-0.05 +$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF WDIFF_0_05 +@end example + +For files that have not been modified locally, the newly created +revision becomes the head revision. If you have made local +changes, @code{import} will warn you that you must merge the changes +into the main trunk, and tell you to use @samp{checkout -j} to do so. + +@example +$ cvs checkout -jFSF:yesterday -jFSF wdiff +@end example + +@noindent +The above command will check out the latest revision of +@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF} +since yesterday into the working copy. If any conflicts arise during +the merge they should be resolved in the normal way (@pxref{Conflicts +example}). Then, the modified files may be committed. + +@sc{cvs} assumes that you do not import more than one +release of a product per day. If you do, you can always +use something like this instead: + +@example +$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff +@end example + +@noindent +In this case, the two above commands are equivalent. + +@c --------------------------------------------------------------------- +@node Moving files +@chapter Moving and renaming files +@cindex Moving files +@cindex Renaming files +@cindex Files, moving + +One of the biggest design flaws with the current release of @sc{cvs} is that +it is very difficult to move a file to a different directory or +rename it. There are workarounds, and they all have their strong and weak +points. (Moving or renaming a directory is even harder. @xref{Moving +directories}). + +The examples below assume that the file @var{old} is renamed to +@var{new}. Both files reside in the same module, +@var{module}, but not necessarily in the same directory. +The relative path to the module inside the repository is assumed +to be @var{module}. + +@menu +* Outside:: Moving outside the repository +* Inside:: Moving the history file +* Rename by copying:: +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Outside +@section Moving outside the repository + +One way to move the file is to copy @var{old} to +@var{new}, and then issue the normal @sc{cvs} commands to +remove @var{old} from the repository, and add @var{new} +to it. (Both @var{old} and @var{new} could contain +relative paths inside the module). + +@example +$ mv @var{old} @var{new} +$ cvs remove @var{old} +$ cvs add @var{new} +$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new} +@end example + +@noindent +Advantages: + +@itemize @bullet +@item +Checking out old revisions works correctly. +@end itemize + +@noindent +Disadvantages: + +@itemize @bullet +@item +You cannot easily see the history of the file across the rename. +@item +Unless you use the @samp{-r rev} (@pxref{commit +options}) flag when @var{new} is committed its revision +numbers will start at 1.0 again. +@end itemize + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Inside +@section Moving the history file + +This method is more dangerous, since it involves moving +files inside the repository. Read this entire section +before trying it out! + +@example +$ cd $CVSROOT/module +$ mv @var{old},v @var{new},v +@end example + +@noindent +Advantages: + +@itemize @bullet +@item +The log of changes is maintained intact. + +@item +The revision numbers are not affected. +@end itemize + +@noindent +Disadvantages: + +@itemize @bullet +@item +Old releases of the module cannot easily be fetched from the +repository. (The file will show up as @var{new} even +in revisions from the time before it was renamed). + +@item +There is no log information of when the file was renamed. + +@item +Nasty things might happen if someone accesses the history file +while you are moving it. Make sure no one else runs any of the @sc{cvs} +commands while you move it. +@end itemize + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Rename by copying +@section Copying the history file + +This is probably the best way to do the renaming. It is +safe, but not without drawbacks. + +@example +# @r{Copy the @sc{rcs} file inside the repository} +$ cd $CVSROOT/module +$ cp @var{old},v @var{new},v +# @r{Remove the old file} +$ cd ~/module +$ rm @var{old} +$ cvs remove @var{old} +$ cvs commit @var{old} +# @r{Remove all tags from @var{new}} +$ cvs update @var{new} +$ cvs log @var{new} # @r{Remember the tag names} +$ cvs tag -d @var{tag1} +$ cvs tag -d @var{tag2} +@dots{} +@end example + +By removing the tags you will be able to check out old +revisions of the module. + +@noindent +Advantages: + +@itemize @bullet +@item +Checking out old revisions works correctly, as long as +you use @samp{-r@var{tag}} and not @samp{-D@var{date}} +to retrieve the revisions. + +@item +The log of changes is maintained intact. + +@item +The revision numbers are not affected. +@end itemize + +@noindent +Disadvantages: + +@itemize @bullet +@item +You cannot easily see the history of the file across the rename. + +@item +Unless you use the @samp{-r rev} (@pxref{commit +options}) flag when @var{new} is committed its revision +numbers will start at 1.0 again. +@end itemize + +@c --------------------------------------------------------------------- +@node Moving directories +@chapter Moving and renaming directories +@cindex Moving directories +@cindex Renaming directories +@cindex Directories, moving + +If you want to be able to retrieve old versions of the +module, you must move each file in the directory +with the @sc{cvs} commands. @xref{Outside}. The old, empty +directory will remain inside the repository, but it +will not appear in your workspace when you check out +the module in the future. +@c -- rephrase + +If you really want to rename or delete a directory, you +can do it like this: + +@enumerate +@item +Inform everyone who has a copy of the module that the +directory will be renamed. They should commit all +their changes, and remove their working copies of the +module, before you take the steps below. + +@item +Rename the directory inside the repository. + +@example +$ cd $CVSROOT/@var{module} +$ mv @var{old-dir} @var{new-dir} +@end example + +@item +Fix the @sc{cvs} administrative files, if necessary (for +instance if you renamed an entire module). + +@item +Tell everyone that they can check out the module and continue +working. + +@end enumerate + +If someone had a working copy of the module the @sc{cvs} commands will +cease to work for him, until he removes the directory +that disappeared inside the repository. + +It is almost always better to move the files in the +directory instead of moving the directory. If you move the +directory you are unlikely to be able to retrieve old +releases correctly, since they probably depend on the +name of the directories. + +@ignore +@c --------------------------------------------------------------------- +@c @node History browsing +@chapter History browsing +@cindex History browsing +@cindex Traceability +@cindex Isolation + +@c -- @quote{To lose ones history is to lose ones soul.} +@c -- /// +@c -- ///Those who cannot remember the past are condemned to repeat it. +@c -- /// -- George Santayana +@c -- /// + +@sc{cvs} tries to make it easy for a group of people to work +together. This is done in two ways: + +@itemize @bullet +@item +Isolation---You have your own working copy of the +source. You are not affected by modifications made by +others until you decide to incorporate those changes +(via the @code{update} command---@pxref{update}). + +@item +Traceability---When something has changed, you can +always see @emph{exactly} what changed. +@end itemize + +There are several features of @sc{cvs} that together lead +to traceability: + +@itemize @bullet +@item +Each revision of a file has an accompanying log +message. + +@item +All commits are optionally logged to a central history +database. + +@item +Logging information can be sent to a user-defined +program (@pxref{loginfo}). +@end itemize + +@c -- More text here. + +This chapter should talk about the history file, the +@code{log} command, the usefulness of ChangeLogs +even when you run @sc{cvs}, and things like that. + +@menu +* log messages:: Log messages +* history database:: The history database +* user-defined logging:: User-defined logging +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node log messages +@section Log messages + +Whenever you commit a file you specify a log message. /// +@c -- + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node history database +@section The history database + +/// + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node user-defined logging +@section User-defined logging + +/// + +@end ignore + +@c --------------------------------------------------------------------- +@node Keyword substitution +@chapter Keyword substitution +@cindex Keyword substitution +@cindex Keyword expansion +@cindex Identifying files + +@comment Be careful when editing this chapter. +@comment Remember that this file is kept under +@comment version control, so we must not accidentally +@comment include a valid keyword in the running text. + +As long as you edit source files inside your working +copy of a module you can always find out the state of +your files via @samp{cvs status} and @samp{cvs log}. +But as soon as you export the files from your +development environment it becomes harder to identify +which revisions they are. + +@sc{Rcs} uses a mechanism known as @dfn{keyword +substitution} (or @dfn{keyword expansion}) to help +identifying the files. Embedded strings of the form +@code{$@var{keyword}$} and +@code{$@var{keyword}:@dots{}$} in a file are replaced +with strings of the form +@code{$@var{keyword}:@var{value}$} whenever you obtain +a new revision of the file. + +@menu +* Keyword list:: RCS Keywords +* Using keywords:: Using keywords +* Avoiding substitution:: Avoiding substitution +* Substitution modes:: Substitution modes +* Log keyword:: Problems with the $@asis{}Log$ keyword. +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Keyword list +@section RCS Keywords +@cindex RCS keywords + +This is a list of the keywords that @sc{rcs} currently +(in release 5.6.0.1) supports: + +@table @code +@cindex Author keyword +@item $@asis{Author}$ +The login name of the user who checked in the revision. + +@cindex Date keyword +@item $@asis{Date}$ +The date and time (UTC) the revision was checked in. + +@cindex Header keyword +@item $@asis{Header}$ +A standard header containing the full pathname of the +@sc{rcs} file, the revision number, the date (UTC), the +author, the state, and the locker (if locked). Files +will normally never be locked when you use @sc{cvs}. + +@cindex Id keyword +@item $@asis{Id}$ +Same as @code{$@asis{Header}$}, except that the @sc{rcs} +filename is without a path. + +@cindex Locker keyword +@item $@asis{Locker}$ +The login name of the user who locked the revision +(empty if not locked, and thus almost always useless +when you are using @sc{cvs}). + +@cindex Log keyword +@item $@asis{Log}$ +The log message supplied during commit, preceded by a +header containing the @sc{rcs} filename, the revision +number, the author, and the date (UTC). Existing log +messages are @emph{not} replaced. Instead, the new log +message is inserted after @code{$@asis{Log:@dots{}}$}. +Each new line is prefixed with a @dfn{comment leader} +which @sc{rcs} guesses from the file name extension. +It can be changed with @code{cvs admin -c}. +@xref{admin options}. This keyword is useful for +accumulating a complete change log in a source file, +but for several reasons it can be problematic. +@xref{Log keyword}. + +@cindex RCSfile keyword +@item $@asis{RCSfile}$ +The name of the RCS file without a path. + +@cindex Revision keyword +@item $@asis{Revision}$ +The revision number assigned to the revision. + +@cindex Source keyword +@item $@asis{Source}$ +The full pathname of the RCS file. + +@cindex State keyword +@item $@asis{State}$ +The state assigned to the revision. States can be +assigned with @code{cvs admin -s}---@xref{admin options}. + +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Using keywords +@section Using keywords + +To include a keyword string you simply include the +relevant text string, such as @code{$@asis{Id}$}, inside the +file, and commit the file. @sc{cvs} will automatically +expand the string as part of the commit operation. + +@need 800 +It is common to embed @code{$@asis{}Id$} string in the +C source code. This example shows the first few lines +of a typical file, after keyword substitution has been +performed: + +@example +static char *rcsid="$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; +/* @r{The following lines will prevent @code{gcc} version 2.@var{x}} + @r{from issuing an "unused variable" warning}. */ +#if __GNUC__ == 2 +#define USE(var) static void * use_##var = (&use_##var, (void *) &var) +USE (rcsid); +#endif +@end example + +Even though a clever optimizing compiler could remove +the unused variable @code{rcsid}, most compilers tend +to include the string in the binary. Some compilers +have a @code{#pragma} directive to include literal text +in the binary. + +@cindex Ident (shell command) +The @code{ident} command (which is part of the @sc{rcs} +package) can be used to extract keywords and their +values from a file. This can be handy for text files, +but it is even more useful for extracting keywords from +binary files. + +@example +$ ident samp.c +samp.c: + $@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ +$ gcc samp.c +$ ident a.out +a.out: + $@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $ +@end example + +@cindex What (shell command) +S@sc{ccs} is another popular revision control system. +It has a command, @code{what}, which is very similar to +@code{ident} and used for the same purpose. Many sites +without @sc{rcs} have @sc{sccs}. Since @code{what} +looks for the character sequence @code{@@(#)} it is +easy to include keywords that are detected by either +command. Simply prefix the @sc{rcs} keyword with the +magic @sc{sccs} phrase, like this: + +@example +static char *id="@@(#) $@asis{}Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $"; +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Avoiding substitution +@section Avoiding substitution + +Keyword substitution has its disadvantages. Sometimes +you might want the literal text string +@samp{$@asis{}Author$} to appear inside a file without +@sc{rcs} interpreting it as a keyword and expanding it +into something like @samp{$@asis{}Author: ceder $}. + +There is unfortunately no way to selectively turn off +keyword substitution. You can use @samp{-ko} +(@pxref{Substitution modes}) to turn off keyword +substitution entirely. (If you put binaries under +version control you are strongly encouraged to use that +option, for obvious reasons). + +In many cases you can avoid using @sc{rcs} keywords in +the source, even though they appear in the final +product. For example, the source for this manual +contains @samp{$@@asis@{@}Author$} whenever the text +@samp{$@asis{}Author$} should appear. In @code{nroff} +and @code{troff} you can embed the null-character +@code{\&} inside the keyword for a similar effect. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Substitution modes +@section Substitution modes +@cindex -k (RCS kflags) +@cindex Kflag + +You can control how @sc{rcs} expands keywords +through the use of the @samp{-k} option (@pxref{Common +options}). The @samp{-k} option is available with the +@code{add}, @code{checkout}, @code{diff} and +@code{update} commands. + +Five different modes are available. They are: + +@table @samp +@item -kkv +Generate keyword strings using the default form, e.g. +@code{$@asis{}Revision: 5.7 $} for the @code{Revision} +keyword. + +@item -kkvl +Like @samp{-kkv}, except that a locker's name is always +inserted if the given revision is currently locked. +This option is normally not useful when @sc{cvs} is used. + +@item -kk +Generate only keyword names in keyword strings; omit +their values. For example, for the @code{Revision} +keyword, generate the string @code{$@asis{}Revision$} +instead of @code{$@asis{}Revision: 5.7 $}. This option +is useful to ignore differences due to keyword +substitution when comparing different revisions of a +file. + +@item -ko +Generate the old keyword string, present in the working +file just before it was checked in. For example, for +the @code{Revision} keyword, generate the string +@code{$@asis{}Revision: 1.1 $} instead of +@code{$@asis{}Revision: 5.7 $} if that is how the +string appeared when the file was checked in. This can +be useful for binary file formats that cannot tolerate +any changes to substrings that happen to take the form +of keyword strings. + +@item -kv +Generate only keyword values for keyword strings. For +example, for the @code{Revision} keyword, generate the string +@code{5.7} instead of @code{$@asis{}Revision: 5.7 $}. +This can help generate files in programming languages +where it is hard to strip keyword delimiters like +@code{$@asis{}Revision: $} from a string. However, +further keyword substitution cannot be performed once +the keyword names are removed, so this option should be +used with care. + +This option is always use by @code{cvs +export}---@pxref{export}. + +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Log keyword +@section Problems with the $@asis{}Log$ keyword. + +The @code{$@asis{}Log$} keyword is somewhat +controversial. As long as you are working on your +development system the information is easily accessible +even if you do not use the @code{$@asis{}Log$} +keyword---just do a @code{cvs log}. Once you export +the file the history information might be useless +anyhow. + +A more serious concern is that @sc{rcs} is not good at +handling @code{$@asis{}Log$} entries when a branch is +merged onto the main trunk. Conflicts often result +from the merging operation. + +People also tend to "fix" the log entries in the file +(correcting spelling mistakes and maybe even factual +errors). If that is done the information from +@code{cvs log} will not be consistent with the +information inside the file. This may or may not be a +problem in real life. + +It has been suggested that the @code{$@asis{}Log$} +keyword should be inserted @emph{last} in the file, and +not in the files header, if it is to be used at all. +That way the long list of change messages will not +interfere with everyday source file browsing. + +@c --------------------------------------------------------------------- +@node Revision management +@chapter Revision management +@cindex Revision management + +@c -- This chapter could be expanded a lot. +@c -- Experiences are very welcome! + +If you have read this far, you probably have a pretty +good grasp on what @sc{cvs} can do for you. This +chapter talks a little about things that you still have +to decide. + +If you are doing development on your own using @sc{cvs} +you could probably skip this chapter. The questions +this chapter takes up become more important when more +than one person is working in a repository. + +@menu +* When to commit:: Some discussion on the subject +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node When to commit +@section When to commit? +@cindex When to commit +@cindex Commit, when to +@cindex Policy + +Your group should decide which policy to use regarding +commits. Several policies are possible, and as your +experience with @sc{cvs} grows you will probably find +out what works for you. + +If you commit files too quickly you might commit files +that do not even compile. If your partner updates his +working sources to include your buggy file, he will be +unable to compile the code. On the other hand, other +persons will not be able to benefit from the +improvements you make to the code if you commit very +seldom, and conflicts will probably be more common. + +It is common to only commit files after making sure +that they can be compiled. Some sites require that the +files pass a test suite. Policies like this can be +enforced using the commitinfo file +(@pxref{commitinfo}), but you should think twice before +you enforce such a convention. By making the +development environment too controlled it might become +too regimented and thus counter-productive to the real +goal, which is to get software written. + +@c --------------------------------------------------------------------- +@node Invoking CVS +@appendix Reference manual for CVS commands +@cindex Command reference +@cindex Reference, commands +@cindex Invoking CVS + +This appendix describes every subcommand of @sc{cvs} in +detail. It also describes how to invoke CVS. + +@menu +* Structure:: Overall structure of CVS commands +* ~/.cvsrc:: Default options with the ~/.csvrc file +* Global options:: Options you give to the left of cvs_command +* Common options:: Options you give to the right of cvs_command +* add:: Add a new file/directory to the repository +* admin:: Administration front end for rcs +* checkout:: Checkout sources for editing +* commit:: Check files into the repository +* diff:: Run diffs between revisions +* export:: Export sources from CVS, similar to checkout +* history:: Show status of files and users +* import:: Import sources into CVS, using vendor branches +* log:: Print out 'rlog' information for files +* rdiff:: 'patch' format diffs between releases +* release:: Indicate that a Module is no longer in use +* remove:: Remove an entry from the repository +* rtag:: Add a tag to a module +* status:: Status info on the revisions +* tag:: Add a tag to checked out version +* update:: Bring work tree in sync with repository +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Structure +@appendixsec Overall structure of CVS commands +@cindex Structure +@cindex CVS command structure +@cindex Command structure +@cindex Format of CVS commands + +The first release of @sc{cvs} consisted of a number of shell-scripts. +Today @sc{cvs} is implemented as a single program that is a front-end +to @sc{rcs} and @code{diff}. The overall format of all +@sc{cvs} commands is: + +@example +cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] +@end example + +@table @code +@item cvs +The program that is a front-end to @sc{rcs}. + +@item cvs_options +Some options that affect all sub-commands of @sc{cvs}. These are +described below. + +@item cvs_command +One of several different sub-commands. Some of the commands have +aliases that can be used instead; those aliases are noted in the +reference manual for that command. There are only two situations +where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a +list of available commands, and @samp{cvs -v} displays version +information on @sc{cvs} itself. + +@item command_options +Options that are specific for the command. + +@item command_args +Arguments to the commands. +@end table + +There is unfortunately some confusion between +@code{cvs_options} and @code{command_options}. For +example, @samp{-q} can often (but not always) be given +as both a @code{cvs_option} and a +@code{command_option}. @samp{-l}, when given as a +@code{cvs_option}, only affects some of the commands. +When it is given as a @code{command_option} is has a +different meaning, and is accepted by more commands. +In other words, do not take the above categorization +too seriously. Look at the documentation instead. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node ~/.cvsrc +@appendixsec Default options and the ~/.cvsrc file +@cindex .cvsrc file +@cindex option defaults + +There are some @code{command_options} that are used so +often that you might have set up an alias or some other +means to make sure you always specify that option. One +example @footnote{being the one that drove the +implementation of the .cvsrc support} is that many +people find the default output of the @samp{diff} +command to be very hard to read, and that either +context diffs or unidiffs are much easier to +understand. + +The @file{~/.cvsrc} file is a way that you can add +default options to @code{cvs_commands} within cvs, +instead of relying on aliases or other shell scripts. + +The format of the @file{~/.cvsrc} file is simple. The +file is searched for a line that begins with the same +name as the @code{cvs_command} being executed. If a +match is found, then the remainder of the line is split +up (at whitespace characters) into separate options and +added to the command arguments @emph{before} any +options from the command line. + +If a command has two names (e.g., @code{checkout} and +@code{co}), only the name used on the command line will +be used to match against the file. So if this is the +contents of the user's @file{~/.cvsrc} file: + +@example +log -N +diff -u +update -P +co -P +@end example + +@noindent +the command @samp{cvs checkout foo} would not have the +@samp{-P} option added to the arguments, while +@samp{cvs co foo} would. + +With the example file above, the output from @samp{cvs +diff foobar} will be in unidiff format. @samp{cvs diff +-c foobar} will provide context diffs, as usual. Since +@code{diff} doesn't have an option to specify use of +the "old" format, you would need to use the @samp{-f} +option to @samp{cvs} to turn off use of the +@file{~/.cvsrc} options. + + + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Global options +@appendixsec Global options +@cindex Options, global +@cindex Global options +@cindex Left-hand options + +The available @samp{cvs_options} (that are given to the +left of @samp{cvs_command}) are: + +@table @code +@cindex RCSBIN, overriding +@cindex Overriding RCSBIN +@item -b @var{bindir} +Use @var{bindir} as the directory where @sc{rcs} programs are +located. Overrides the setting of the @code{$RCSBIN} environment +variable and any precompiled directory. This parameter should be +specified as an absolute pathname. + +@cindex CVSROOT, overriding +@cindex Overriding CVSROOT +@item -d @var{cvs_root_directory} +Use @var{cvs_root_directory} as the root directory +pathname of the repository. Overrides the setting of +the @code{$CVSROOT} environment variable. This parameter +should be specified as an absolute pathname. + +@cindex EDITOR, overriding +@cindex Overriding EDITOR +@item -e @var{editor} +Use @var{editor} to enter revision log information. Overrides the +setting of the @code{$CVSEDITOR} and @code{$EDITOR} environment variables. + +@item -f +Do not read the @file{~/.cvsrc} file. This +option is most often used because of the +non-orthogonality of the @sc{cvs} option set. For +example, the @samp{cvs log} option @samp{-N} (turn off +display of tag names) does not have a corresponding +option to turn the display on. So if you have +@samp{-N} in the @file{~/.cvsrc} entry for @samp{diff}, +you may need to use @samp{-f} to show the tag names. +@footnote{Yes, this really should be fixed, and it's +being worked on} + +@item -H +Display usage information about the specified @samp{cvs_command} +(but do not actually execute the command). If you don't specify +a command name, @samp{cvs -H} displays a summary of all the +commands available. + +@item -l +Do not log the cvs_command in the command history (but execute it +anyway). @xref{history}, for information on command history. + +@cindex Read-only mode +@item -n +Do not change any files. Attempt to execute the +@samp{cvs_command}, but only to issue reports; do not remove, +update, or merge any existing files, or create any new files. + +@item -Q +Cause the command to be really quiet; the command will only +generate output for serious problems. + +@item -q +Cause the command to be somewhat quiet; informational messages, +such as reports of recursion through subdirectories, are +suppressed. + +@cindex Read-only files +@item -r +Make new working files files read-only. Same effect +as if the @code{$CVSREAD} environment variable is set +(@pxref{Environment variables}). The default is to +make working files writable. + +@cindex Trace +@item -t +Trace program execution; display messages showing the steps of +@sc{cvs} activity. Particularly useful with @samp{-n} to explore the +potential impact of an unfamiliar command. + +@item -v +Display version and copyright information for @sc{cvs}. + +@cindex CVSREAD, overriding +@cindex Overriding CVSREAD +@item -w +Make new working files read-write. Overrides the +setting of the @code{$CVSREAD} environment variable. +Files are created read-write by default, unless @code{$CVSREAD} is +set or @samp{-r} is given. + +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Common options +@appendixsec Common command options +@cindex Common options +@cindex Right-hand options + +This section describes the @samp{command_options} that +are available across several @sc{cvs} commands. These +options are always given to the right of +@samp{cvs_command}. Not all +commands support all of these options; each option is +only supported for commands where it makes sense. +However, when a command has one of these options you +can almost always count on the same behavior of the +option as in other commands. (Other command options, +which are listed with the individual commands, may have +different behavior from one @sc{cvs} command to the other). + +@strong{Warning:} the @samp{history} command is an exception; it supports +many options that conflict even with these standard options. + +@table @code +@cindex Dates +@cindex Time +@cindex Specifying dates +@item -D @var{date_spec} +Use the most recent revision no later than @var{date_spec}. +@var{date_spec} is a single argument, a date description +specifying a date in the past. + +The specification is @dfn{sticky} when you use it to make a +private copy of a source file; that is, when you get a working +file using @samp{-D}, @sc{cvs} records the date you specified, so that +further updates in the same directory will use the same date +(unless you explicitly override it; @pxref{update}). + +A wide variety of date formats are supported by the underlying +@sc{rcs} facilities, similar to those described in co(1), but not +exactly the same. The @var{date_spec} is interpreted as being +in the local timezone, unless a specific timezone is specified. +Examples of valid date specifications include: + +@example + 1 month ago + 2 hours ago + 400000 seconds ago + last year + last Monday + yesterday + a fortnight ago + 3/31/92 10:00:07 PST + January 23, 1987 10:05pm + 22:00 GMT +@end example + +@samp{-D} is available with the @code{checkout}, +@code{diff}, @code{export}, @code{history}, +@code{rdiff}, @code{rtag}, and @code{update} commands. +(The @code{history} command uses this option in a +slightly different way; @pxref{history options}). + +Remember to quote the argument to the @samp{-D} +flag so that your shell doesn't interpret spaces as +argument separators. A command using the @samp{-D} +flag can look like this: + +@example +$ cvs diff -D "1 hour ago" cvs.texinfo +@end example + +@cindex Forcing a tag match +@item -f +When you specify a particular date or tag to @sc{cvs} commands, they +normally ignore files that do not contain the tag (or did not +exist prior to the date) that you specified. Use the @samp{-f} option +if you want files retrieved even when there is no match for the +tag or date. (The most recent revision of the file +will be used). + +@need 800 +@samp{-f} is available with these commands: @code{checkout}, +@code{export}, @code{rdiff}, @code{rtag}, and @code{update}. + +@strong{Warning:} The @code{commit} command also has a +@samp{-f} option, but it has a different behavior for +that command. @xref{commit options}. + +@item -H +Help; describe the options available for this command. This is +the only option supported for all @sc{cvs} commands. + +@item -k @var{kflag} +Alter the default @sc{rcs} processing of keywords. +@xref{Keyword substitution}, for the meaning of +@var{kflag}. Your @var{kflag} specification is +@dfn{sticky} when you use it to create a private copy +of a source file; that is, when you use this option +with the @code{checkout} or @code{update} commands, +@sc{cvs} associates your selected @var{kflag} with the +file, and continues to use it with future update +commands on the same file until you specify otherwise. + +The @samp{-k} option is available with the @code{add}, +@code{checkout}, @code{diff} and +@code{update} commands. + +@item -l +Local; run only in current working directory, rather than +recursing through subdirectories. + +@strong{Warning:} this is not the same +as the overall @samp{cvs -l} option, which you can specify to the +left of a cvs command! + +Available with the following commands: @code{checkout}, +@code{commit}, @code{diff}, @code{export}, @code{log}, +@code{remove}, @code{rdiff}, @code{rtag}, +@code{status}, @code{tag}, and @code{update}. + +@cindex Editor, avoiding invocation of +@cindex Avoiding editor invocation +@item -m @var{message} +Use @var{message} as log information, instead of +invoking an editor. + +Available with the following commands: @code{add}, +@code{commit} and @code{import}. + +@item -n +Do not run any checkout/commit/tag program. (A program can be +specified to run on each of these activities, in the modules +database (@pxref{modules}); this option bypasses it). + +@strong{Warning:} this is not the same as the overall @samp{cvs -n} +option, which you can specify to the left of a cvs command! + +Available with the @code{checkout}, @code{commit}, @code{export}, +and @code{rtag} commands. + +@item -P +Prune (remove) directories that are empty after being updated, on +@code{checkout}, or @code{update}. Normally, an empty directory +(one that is void of revision-controlled files) is left alone. +Specifying @samp{-P} will cause these directories to be silently +removed from your checked-out sources. This does not remove the +directory from the repository, only from your checked out copy. +Note that this option is implied by the @samp{-r} or @samp{-D} +options of @code{checkout} and @code{export}. +@c -- implied-- + +@item -p +Pipe the files retrieved from the repository to standard output, +rather than writing them in the current directory. Available +with the @code{checkout} and @code{update} commands. + +@item -Q +Cause the command to be really quiet; the command will only +generate output for serious problems. Available with the following +commands: @code{checkout}, @code{import}, @code{export}, +@code{rdiff}, @code{rtag}, @code{tag}, and @code{update}. + +@item -q +Cause the command to be somewhat quiet; informational messages, +such as reports of recursion through subdirectories, are +suppressed. Available with the following commands: +@code{checkout}, @code{import}, @code{export}, @code{rtag}, +@code{tag}, and @code{update}. + +@item -r @var{tag} +Use the revision specified by the @var{tag} argument instead of the +default @dfn{head} revision. As well as arbitrary tags defined +with the @code{tag} or @code{rtag} command, two special tags are +always available: @samp{HEAD} refers to the most recent version +available in the repository, and @samp{BASE} refers to the +revision you last checked out into the current working directory. + +The tag specification is sticky when you use this option +with @code{checkout} or @code{update} to make your own +copy of a file: @sc{cvs} remembers the tag and continues to use it on +future update commands, until you specify otherwise. The +tag can be either a symbolic or numeric tag. +@xref{Tags}. + +Specifying the @samp{-q} option along with the @samp{-r} option is often +useful, to suppress the warning messages when the @sc{rcs} history file does +not contain the specified tag. + +@strong{Warning:} this is not the same as the overall `cvs -r' option, +which you can specify to the left of a cvs command! + +@samp{-r} is available with the @code{checkout}, @code{commit}, +@code{diff}, @code{history}, @code{export}, @code{rdiff}, +@code{rtag}, and @code{update} commands. + +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node add +@appendixsec add---Add a new file/directory to the repository +@cindex Add (subcommand) + +@itemize @bullet +@item +Synopsis: add [-k kflag] [-m 'message'] files@dots{} +@item +Requires: repository, working directory. +@item +Changes: working directory. +@item +Synonym: new +@end itemize + +Use the @code{add} command to create a new file or directory in the +source repository. The files or directories specified with @code{add} +must already exist in the current directory (which must have been +created with the @code{checkout} command). To add a whole new directory +hierarchy to the source repository (for example, files received +from a third-party vendor), use the @code{import} command +instead. @xref{import}. + +If the argument to @code{add} refers to an immediate +sub-directory, the directory is created at the correct place in +the source repository, and the necessary @sc{cvs} administration +files are created in your working directory. If the directory +already exists in the source repository, @code{add} still creates +the administration files in your version of the directory. +This allows you to use @code{add} to add a particular directory +to your private sources even if someone else created that +directory after your checkout of the sources. You can do the +following: + +@example +$ mkdir new_directory +$ cvs add new_directory +$ cvs update new_directory +@end example + +An alternate approach using @code{update} might be: + +@example +$ cvs update -d new_directory +@end example + +(To add any available new directories to your working directory, +it's probably simpler to use @code{checkout} (@pxref{checkout}) +or @samp{update -d} (@pxref{update})). + +The added files are not placed in the source repository until you +use @code{commit} to make the change permanent. Doing an +@code{add} on a file that was removed with the @code{remove} +command will resurrect the file, unless a @code{commit} command +intervened. +@xref{remove examples} for an example. + + +Unlike most other commands @code{add} never recurses down +directories. It cannot yet handle relative paths. Instead of + +@example +$ cvs add foo/bar.c +@end example + +you have to do + +@example +$ cd foo +$ cvs add bar.c +@end example + +@menu +* add options:: add options +* add examples:: add examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node add options +@appendixsubsec add options +@cindex Add options + +There are only two options you can give to @samp{add}: + +@table @code +@item -k @var{kflag} +This option specifies the default way that this file +will be checked out. See rcs(1) and co(1). The +@var{kflag} argument (@pxref{Substitution modes}) is +stored in the @sc{rcs} file and can be changed with +@code{admin -k} (@pxref{admin options}). Specifying +@samp{-ko} is useful for checking in binaries that +should not have the @sc{rcs} id strings expanded. + +@strong{Warning:} this option is reported to be broken in +version 1.3 and 1.3-s2 of @sc{cvs}. Use @samp{admin -k} +after the commit instead. @xref{admin examples}. +@c -- broken-- + +@item -m @var{description} +Using this option, you can give a description for the file. This +description appears in the history log (if it is enabled, +@pxref{history file}). It will also be saved in the @sc{rcs} history +file inside the repository when the file is committed. The +@code{log} command displays this description. + +The description can be changed using @samp{admin -t}. +@xref{admin}. + +If you omit the @samp{-m @var{description}} flag, an empty string will be +used. You will not be prompted for a description. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node add examples +@appendixsubsec add examples + +To add the file @file{backend.c} to the repository, with a +description, the following can be used. + +@example +$ cvs add -m "Optimizer and code generation passes." backend.c +$ cvs commit -m "Early version. Not yet compilable." backend.c +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node admin +@appendixsec admin---Administration front end for rcs +@cindex Admin (subcommand) + +@itemize @bullet +@item +Requires: repository, working directory. +@item +Changes: repository. +@item +Synonym: rcs +@end itemize + +This is the @sc{cvs} interface to assorted administrative @sc{rcs} +facilities, documented in rcs(1). @code{admin} simply passes +all its options and arguments to the @code{rcs} command; it does +no filtering or other processing. This command @emph{does} work +recursively, however, so extreme care should be used. + +@menu +* admin options:: admin options +* admin examples:: admin examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node admin options +@appendixsubsec admin options + +Not all valid @code{rcs} options are useful together +with @sc{cvs}. Some even makes it impossible to use +@sc{cvs} until you undo the effect! + +This description of the available options is based on +the @samp{rcs(1)} man page, but modified to suit +readers that are more interrested in @sc{cvs} than +@sc{rcs}. + +@table @code +@item -A@var{oldfile} +Might not work together with @sc{cvs}. Append the +access list of @var{oldfile} to the access list of the +@sc{rcs} file. + +@item -a@var{logins} +Might not work together with @sc{cvs}. Append the +login names appearing in the comma-separated list +@var{logins} to the access list of the @sc{rcs} file. + +@item -b[@var{rev}] +Breaks @sc{cvs}. When used with bare @sc{rcs}, this +option sets the default branch to @var{rev}. +If @var{rev} is omitted, the default branch is reset to +the (dynamically) highest branch on the trunk. Use +sticky tags instead, as in @code{cvs co -r}. +@xref{Sticky tags}. + +@item -c@var{string} +Useful with @sc{cvs}. Sets the comment leader to +@var{string}. The comment leader is printed before +every log message line generated by the keyword +@code{$@asis{}Log$} (@pxref{Keyword substitution}). +This is useful for programming languages without +multi-line comments. @sc{Rcs} initially guesses the +value of the comment leader from the file name +extension when the file is first committed. + +@item -e[@var{logins}] +Might not work together with @sc{cvs}. Erase the login +names appearing in the comma-separated list +@var{logins} from the access list of the RCS file. If +@var{logins} is omitted, erase the entire access list. + +@item -I +Run interactively, even if the standard input is not a +terminal. + +@item -i +Useless with @sc{cvs}. When using bare @sc{rcs}, this +is used to create and initialize a new @sc{rcs} file, +without depositing a revision. + +@item -k@var{subst} +Useful with @sc{cvs}. Set the default keyword +substitution to @var{subst}. @xref{Keyword +substitution}. Giving an explicit @samp{-k} option to +@code{cvs update} or @code{cvs checkout} overrides this +default. @code{cvs export} always uses @code{-kv}, +regardless of which keyword substitution is set with +@code{cvs admin}. + +@item -l[@var{rev}] +Probably useless with @sc{cvs}. With bare @sc{rcs}, +this option can be used to lock the revision with +number @var{rev}. If a branch is given, lock the +latest revision on that branch. If @var{rev} is +omitted, lock the latest revision on the default +branch. + +@item -L +Probably useless with @sc{cvs}. Used with bare +@sc{rcs} to set locking to strict. Strict +locking means that the owner of an RCS file is not +exempt from locking for checkin. + +@cindex Changing a log message +@cindex Replacing a log message +@cindex Correcting a log message +@cindex Fixing a log message +@cindex Log message, correcting +@item -m@var{rev}:@var{msg} +Replace the log message of revision @var{rev} with +@var{msg}. + +@item -N@var{name}[:[@var{rev}]] +Act like @samp{-n}, except override any previous +assignment of @var{name}. + +@item -n@var{name}[:[@var{rev}]] +Associate the symbolic name @var{name} with the branch +or revision @var{rev}. It is normally better to use +@samp{cvs tag} or @samp{cvs rtag} instead. Delete the +symbolic name if both @samp{:} and @var{rev} are +omitted; otherwise, print an error message if +@var{name} is already associated with another number. +If @var{rev} is symbolic, it is expanded before +association. A @var{rev} consisting of a branch number +followed by a @samp{.} stands for the current latest +revision in the branch. A @samp{:} with an empty +@var{rev} stands for the current latest revision on the +default branch, normally the trunk. For example, +@samp{rcs -n@var{name}: RCS/*} associates @var{name} with the +current latest revision of all the named RCS files; +this contrasts with @samp{rcs -n@var{name}:$ RCS/*} which +associates @var{name} with the revision numbers +extracted from keyword strings in the corresponding +working files. + +@cindex Deleting revisions +@cindex Outdating revisions +@cindex Saving space +@item -o@var{range} +Useful, but dangerous, with @sc{cvs} (see below). +Deletes (@dfn{outdates}) the revisions given by +@var{range}. A range consisting of a single revision +number means that revision. A range consisting of a +branch number means the latest revision on that branch. +A range of the form @samp{@var{rev1}:@var{rev2}} means +revisions @var{rev1} to @var{rev2} on the same branch, +@samp{:@var{rev}} means from the beginning of the +branch containing @var{rev} up to and including +@var{rev}, and @samp{@var{rev}:} means from revision +@var{rev} to the end of the branch containing +@var{rev}. None of the outdated revisions may have +branches or locks. + +Due to the way @sc{cvs} handles branches @var{rev} +cannot be specified symbolically if it is a branch. +@xref{Magic branch numbers}, for an explanation. + +Make sure that no-one has checked out a copy of the +revision you outdate. Strange things will happen if he +starts to edit it and tries to check it back in. For +this reason, you should never use this option to take +back a bogus commit unless you work alone. Instead, +you should fix the file and commit a new revision. + +@item -q +Run quietly; do not print diagnostics. + +@item -s@var{state}[:@var{rev}] +Useful with @sc{cvs}. Set the state attribute of the +revision @var{rev} to @var{state}. If @var{rev} is a +branch number, assume the latest revision on that +branch. If @var{rev} is omitted, assume the latest +revision on the default branch. Any identifier is +acceptable for @var{state}. A useful set of states is +@samp{Exp} (for experimental), @samp{Stab} (for +stable), and @samp{Rel} (for released). By default, +the state of a new revision is set to @samp{Exp} when +it is created. The state is visible in the output from +@var{cvs log} (@pxref{log}), and in the +@samp{$@asis{}Log$} and @samp{$@asis{}State$} keywords +(@pxref{Keyword substitution}). + +@item -t[@var{file}] +Useful with @sc{cvs}. Write descriptive text from the +contents of the named @var{file} into the RCS file, +deleting the existing text. The @var{file} pathname +may not begin with @samp{-}. If @var{file} is omitted, +obtain the text from standard input, terminated by +end-of-file or by a line containing @samp{.} by itself. +Prompt for the text if interaction is possible; see +@samp{-I}. The descriptive text can be seen in the +output from @samp{cvs log} (@pxref{log}). + +@item -t-@var{string} +Similar to @samp{-t@var{file}}. Write descriptive text +from the @var{string} into the @sc{rcs} file, deleting +the existing text. + +@item -U +Probably useless with @sc{cvs}. Used with bare +@sc{rcs} to set locking to non-strict. Non-strict +locking means that the owner of a file need not lock a +revision for checkin. + +@item -u[@var{rev}] +Probably useless with @sc{cvs}. With bare @sc{rcs}, +unlock the revision with number @var{rev}. If a branch +is given, unlock the latest revision on that branch. +If @var{rev} is omitted, remove the latest lock held by +the caller. Normally, only the locker of a revision +may unlock it. Somebody else unlocking a revision +breaks the lock. This causes a mail message to be sent +to the original locker. The message contains a +commentary solicited from the breaker. The commentary +is terminated by end-of-file or by a line containing +@code{.} by itself. + +@item -V@var{n} +Emulate @sc{rcs} version @var{n}. Use -V@var{n} to make +an @sc{rcs} file acceptable to @sc{rcs} version @var{n} +by discarding information that would confuse version +@var{n}. + +@item -x@var{suffixes} +Useless with @sc{cvs}. Use @var{suffixes} to +characterize RCS files. +@end table + + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node admin examples +@appendixsubsec admin examples + +@appendixsubsubsec Outdating is dangerous + +First, an example of how @emph{not} to use the +@code{admin} command. It is included to stress the +fact that this command can be quite dangerous unless +you know @emph{exactly} what you are doing. + +The @samp{-o} option can be used to @dfn{outdate} old revisions +from the history file. If you are short on disc this option +might help you. But think twice before using it---there is no +way short of restoring the latest backup to undo this command! + +The next line is an example of a command that you would +@emph{not} like to execute. + +@example +$ cvs admin -o:R_1_02 . +@end example + +The above command will delete all revisions up to, and +including, the revision that corresponds to the tag +R_1_02. But beware! If there are files that have not +changed between R_1_02 and R_1_03 the file will have +@emph{the same} numerical revision number assigned to +the tags R_1_02 and R_1_03. So not only will it be +impossible to retrieve R_1_02; R_1_03 will also have to +be restored from the tapes! + +@need 1200 +@appendixsubsubsec Handling binary files +@cindex Binary files (inhibit keyword expansion) +@cindex Inhibiting keyword expansion +@cindex Keyword expansion, inhibiting + +If you use @sc{cvs} to store binary files, where +keyword strings (@pxref{Keyword substitution}) might +accidentally appear inside the file, you should use +@code{cvs admin -ko} to make sure that they are not +modified automatically. Here is an example of how you +can create a new file using the @samp{-ko} flag: + +@example +$ echo '$@asis{}Id$' > kotest +$ cvs add -m"A test file" kotest +$ cvs ci -m"First checkin; contains a keyword" kotest +$ cvs admin -ko kotest +$ rm kotest +$ cvs update kotest +@end example + +When you check in the file @file{kotest} the keywords +are expanded. (Try the above example, and do a +@code{cat kotest} after every command!) The @code{cvs +admin -ko} command sets the default keyword +substitution method for this file, but it does not +alter the working copy of the file that you have. The +easiest way to get the unexpanded version of +@file{kotest} is to remove it and check it out again. + +@appendixsubsubsec Comment leaders +@cindex Comment leader +@cindex Log keyword, selecting comment leader +@cindex Nroff (selecting comment leader) + +If you use the @code{$@asis{}Log$} keyword and you do +not agree with the guess for comment leader that +@sc{cvs} has done, you can enforce your will with +@code{cvs admin -c}. This might be suitable for +@code{nroff} source: + +@example +$ cvs admin -c'.\" ' *.man +$ rm *.man +$ cvs update +@end example + +The two last steps are to make sure that you get the +versions with correct comment leaders in your working +files. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node checkout +@appendixsec checkout---Check out sources for editing +@cindex Checkout (subcommand) +@cindex Co (subcommand) + +@itemize @bullet +@item +Synopsis: checkout [options] modules@dots{} +@item +Requires: repository. +@item +Changes: working directory. +@item +Synonyms: co, get +@end itemize + +Make a working directory containing copies of the +source files specified by @var{modules}. You must execute +@code{checkout} before using most of the other @sc{cvs} +commands, since most of them operate on your working +directory. + +The @var{modules} part of the command are either +symbolic names for some +collection of source directories and files, or paths to +directories or files in the repository. The symbolic +names are defined in the @samp{modules} file. +@xref{modules}. + +Depending on the modules you specify, @code{checkout} may +recursively create directories and populate them with +the appropriate source files. You can then edit these +source files at any time (regardless of whether other +software developers are editing their own copies of the +sources); update them to include new changes applied by +others to the source repository; or commit your work as +a permanent change to the source repository. + +Note that @code{checkout} is used to create +directories. The top-level directory created is always +added to the directory where @code{checkout} is +invoked, and usually has the same name as the specified +module. In the case of a module alias, the created +sub-directory may have a different name, but you can be +sure that it will be a sub-directory, and that +@code{checkout} will show the relative path leading to +each file as it is extracted into your private work +area (unless you specify the @samp{-Q} option). + +Running @code{checkout} on a directory that was already +built by a prior @code{checkout} is also permitted, and +has the same effect as specifying the @samp{-d} option +to the @code{update} command, that is, any new +directories that have been created in the repository +will appear in your work area. @xref{update}. + +@menu +* checkout options:: checkout options +* checkout examples:: checkout examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node checkout options +@appendixsubsec checkout options + +These standard options are supported by @code{checkout} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -D @var{date} +Use the most recent revision no later than @var{date}. +This option is sticky, and implies @samp{-P}. + +@item -f +Only useful with the @samp{-D @var{date}} or @samp{-r +@var{tag}} flags. If no matching revision is found, +retrieve the most recent revision (instead of ignoring +the file). + +@item -k @var{kflag} +Process @sc{rcs} keywords according to @var{kflag}. See +co(1). This option is sticky; future updates of +this file in this working directory will use the same +@var{kflag}. The @code{status} command can be viewed +to see the sticky options. @xref{status}. + +@item -l +Local; run only in current working directory. + +@item -n +Do not run any checkout program (as specified +with the @samp{-o} option in the modules file; +@pxref{modules}). + +@item -P +Prune empty directories. + +@item -p +Pipe files to the standard output. + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. + +@item -r @var{tag} +Use revision @var{tag}. This option is sticky, and implies @samp{-P}. +@end table + +In addition to those, you can use these special command +options with @code{checkout}: + +@table @code +@item -A +Reset any sticky tags, dates, or @samp{-k} options. +(If you get a working file using one of the @samp{-r}, +@samp{-D}, or @samp{-k} options, @sc{cvs} remembers the +corresponding tag, date, or @var{kflag} and continues using +it for future updates; use the @samp{-A} option to make +@sc{cvs} forget these specifications, and retrieve the +`head' revision of the file). + +@item -c +Copy the module file, sorted, to the standard output, +instead of creating or modifying any files or +directories in your working directory. + +@item -d @var{dir} +Create a directory called @var{dir} for the working +files, instead of using the module name. Unless you +also use @samp{-N}, the paths created under @var{dir} +will be as short as possible. + +@item -j @var{tag} +Merge the changes made between the resulting revision +and the revision that it is based on (e.g., if +@var{tag} refers to a branch, @sc{cvs} will merge all +changes made on that branch into your working file). + +With two @samp{-j @var{tag}} options, @sc{cvs} will merge in the +changes between the two respective revisions. This can +be used to undo changes made between two revisions +(@pxref{Merging two revisions}) in your working copy, +or to move changes between different branches. + +In addition, each -j option can contain an optional +date specification which, when used with branches, can +limit the chosen revision to one within a specific +date. An optional date is specified by adding a colon +(:) to the tag. An example might be what @code{import} +tells you to do when you have just imported sources +that have conflicts with local changes: + +@example +$ cvs checkout -jTAG:yesterday -jTAG module +@end example + +@item -N +Only useful together with @samp{-d @var{dir}}. With this +option, @sc{cvs} will not shorten module paths in your +working directory. (Normally, @sc{cvs} shortens paths as +much as possible when you specify an explicit target +directory). + +@item -s +Like @samp{-c}, but include the status of all modules, +and sort it by the status string. @xref{modules}, for +info about the @samp{-s} option that is used inside the +modules file to set the module status. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node checkout examples +@appendixsubsec checkout examples + +Get a copy of the module @samp{tc}: + +@example +$ cvs checkout tc +@end example + +Get a copy of the module @samp{tc} as it looked one day +ago: + +@example +$ cvs checkout -D yesterday tc +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node commit +@appendixsec commit---Check files into the repository +@cindex Commit (subcommand) + +@itemize @bullet +@item +Version 1.3 Synopsis: commit [-lnR] [-m 'log_message' | +-f file] [-r revision] [files@dots{}] +@item +Version 1.3.1 Synopsis: commit [-lnRf] [-m 'log_message' | +-F file] [-r revision] [files@dots{}] +@c -- rename-f-F-- +@item +Requires: working directory, repository. +@item +Changes: repository. +@item +Synonym: ci +@end itemize + +@strong{Warning:} The @samp{-f @var{file}} option will +probably be renamed to @samp{-F @var{file}}, and @samp{-f} +will be given a new behavior in future releases of @sc{cvs}. +@c -- rename-f-F-- + +Use @code{commit} when you want to incorporate changes +from your working source files into the source +repository. + +If you don't specify particular files to commit, all of +the files in your working current directory are +examined. @code{commit} is careful to change in the +repository only those files that you have really +changed. By default (or if you explicitly specify the +@samp{-R} option), files in subdirectories are also +examined and committed if they have changed; you can +use the @samp{-l} option to limit @code{commit} to the +current directory only. + +@code{commit} verifies that the selected files are up +to date with the current revisions in the source +repository; it will notify you, and exit without +committing, if any of the specified files must be made +current first with @code{update} (@pxref{update}). +@code{commit} does not call the @code{update} command +for you, but rather leaves that for you to do when the +time is right. + +When all is well, an editor is invoked to allow you to +enter a log message that will be written to one or more +logging programs (@pxref{modules}, and @pxref{loginfo}) +and placed in the @sc{rcs} history file inside the +repository. This log message can be retrieved with the +@code{log} command; @xref{log}. You can specify the +log message on the command line with the @samp{-m +@var{message}} option, and thus avoid the editor invocation, +or use the @samp{-f @var{file}} option to specify +@c -- rename-f-F-- +that the argument file contains the log message. + +@menu +* commit options:: commit options +* commit examples:: commit examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node commit options +@appendixsubsec commit options + +These standard options are supported by @code{commit} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -l +Local; run only in current working directory. + +@item -n +Do not run any module program. + +@item -R +Commit directories recursively. This is on by default. + +@item -r @var{revision} +Commit to @var{revision}. @var{revision} must be +either a branch, or a revision on the main trunk that +is higher than any existing revision number. You +cannot commit to a specific revision on a branch. +@end table + +@code{commit} also supports these options: + +@table @code +@item -F @var{file} +This option is present in @sc{cvs} releases 1.3-s3 and +later. Read the log message from @var{file}, instead +of invoking an editor. + +@item -f +@c -- rename-f-F-- +This option is present in @sc{cvs} 1.3-s3 and later releases +of @sc{cvs}. Note that this is not the standard behavior of +the @samp{-f} option as defined in @xref{Common options}. + +Force @sc{cvs} to commit a new revision even if you haven't +made any changes to the file. If the current revision +of @var{file} is 1.7, then the following two commands +are equivalent: + +@example +$ cvs commit -f @var{file} +$ cvs commit -r 1.8 @var{file} +@end example + +@item -f @var{file} +@c -- rename-f-F-- +This option is present in @sc{cvs} releases 1.3, 1.3-s1 and +1.3-s2. Note that this is not the standard behavior of +the @samp{-f} option as defined in @xref{Common options}. + +Read the log message from @var{file}, instead +of invoking an editor. + +@item -m @var{message} +Use @var{message} as the log message, instead of +invoking an editor. +@end table + +@need 2000 +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node commit examples +@appendixsubsec commit examples + +@appendixsubsubsec New major release number + +When you make a major release of your product, you +might want the revision numbers to track your major +release number. You should normally not care about +the revision numbers, but this is a thing that many +people want to do, and it can be done without doing any +harm. + +To bring all your files up to the @sc{rcs} revision 3.0 +(including those that haven't changed), you might do: + +@example +$ cvs commit -r 3.0 +@end example + +Note that it is generally a bad idea to try to make the +@sc{rcs} revision number equal to the current release number +of your product. You should think of the revision +number as an internal number that the @sc{cvs} package +maintains, and that you generally never need to care +much about. Using the @code{tag} and @code{rtag} +commands you can give symbolic names to the releases +instead. @xref{tag} and @xref{rtag}. + +Note that the number you specify with @samp{-r} must be +larger than any existing revision number. That is, if +revision 3.0 exists, you cannot @samp{cvs commit +-r 1.3}. + +@appendixsubsubsec Committing to a branch + +You can commit to a branch revision (one that has an +even number of dots) with the @samp{-r} option. To +create a branch revision, use the @samp{-b} option +of the @code{rtag} or @code{tag} commands (@pxref{tag} +or @pxref{rtag}). Then, either @code{checkout} or +@code{update} can be used to base your sources on the +newly created branch. From that point on, all +@code{commit} changes made within these working sources +will be automatically added to a branch revision, +thereby not disturbing main-line development in any +way. For example, if you had to create a patch to the +1.2 version of the product, even though the 2.0 version +is already under development, you might do: + +@example +$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module +$ cvs checkout -r FCS1_2_Patch product_module +$ cd product_module +[[ hack away ]] +$ cvs commit +@end example + +@noindent +This works automatically since the @samp{-r} option is +sticky. + +@appendixsubsubsec Creating the branch after editing + +Say you have been working on some extremely +experimental software, based on whatever revision you +happened to checkout last week. If others in your +group would like to work on this software with you, but +without disturbing main-line development, you could +commit your change to a new branch. Others can then +checkout your experimental stuff and utilize the full +benefit of @sc{cvs} conflict resolution. The scenario might +look like: + +@example +[[ hacked sources are present ]] +$ cvs tag -b EXPR1 +$ cvs update -r EXPR1 +$ cvs commit +@end example + +The @code{update} command will make the @samp{-r +EXPR1} option sticky on all files. Note that your +changes to the files will never be removed by the +@code{update} command. The @code{commit} will +automatically commit to the correct branch, because the +@samp{-r} is sticky. You could also do like this: + +@example +[[ hacked sources are present ]] +$ cvs tag -b EXPR1 +$ cvs commit -r EXPR1 +@end example + +@noindent +but then, only those files that were changed by you +will have the @samp{-r EXPR1} sticky flag. If you hack +away, and commit without specifying the @samp{-r EXPR1} +flag, some files may accidentally end up on the main +trunk. + +To work with you on the experimental change, others +would simply do + +@example +$ cvs checkout -r EXPR1 whatever_module +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node diff +@appendixsec diff---Run diffs between revisions +@cindex Diff (subcommand) + +@itemize @bullet +@item +Synopsis: diff [-l] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}] +@item +Requires: working directory, repository. +@item +Changes: nothing. +@end itemize + +The @code{diff} command is used to compare different +revisions of files. The default action is to compare +your working files with the revisions they were based +on, and report any differences that are found. + +If any file names are given, only those files are +compared. If any directories are given, all files +under them will be compared. + +The exit status will be 0 if no differences were found, +1 if some differences were found, and 2 if any error +occurred. + +@menu +* diff options:: diff options +* diff examples:: diff examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node diff options +@appendixsubsec diff options + +These standard options are supported by @code{diff} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -D @var{date} +Use the most recent revision no later than @var{date}. +See @samp{-r} for how this affects the comparison. + +@sc{cvs} can be configured to pass the @samp{-D} option +through to @code{rcsdiff} (which in turn passes it on +to @code{diff}. @sc{Gnu} diff uses @samp{-D} as a way to +put @code{cpp}-style @samp{#define} statements around the output +differences. There is no way short of testing to +figure out how @sc{cvs} was configured. In the default +configuration @sc{cvs} will use the @samp{-D @var{date}} option. + +@item -k @var{kflag} +Process @sc{rcs} keywords according to @var{kflag}. See +co(1). + +@item -l +Local; run only in current working directory. + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. + +@item -R +Examine directories recursively. This option is on by +default. + +@item -r @var{tag} +Compare with revision @var{tag}. Zero, one or two +@samp{-r} options can be present. With no @samp{-r} +option, the working file will be compared with the +revision it was based on. With one @samp{-r}, that +revision will be compared to your current working file. +With two @samp{-r} options those two revisions will be +compared (and your working file will not affect the +outcome in any way). + +One or both @samp{-r} options can be replaced by a +@samp{-D @var{date}} option, described above. +@end table + +Any other options that are found are passed through to +@code{rcsdiff}, which in turn passes them to +@code{diff}. The exact meaning of the options depends +on which @code{diff} you are using. The long options +introduced in @sc{gnu} diff 2.0 are not yet supported in +@sc{cvs}. See the documentation for your @code{diff} to see +which options are supported. + +@c -- Document some common useful diff options, such as +@c -u and -c. +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node diff examples +@appendixsubsec diff examples + +The following line produces a Unidiff (@samp{-u} flag) +between revision 1.14 and 1.19 of +@file{backend.c}. Due to the @samp{-kk} flag no +keywords are substituted, so differences that only depend +on keyword substitution are ignored. + +@example +$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c +@end example + +Suppose the experimental branch EXPR1 was based on a +set of files tagged RELEASE_1_0. To see what has +happened on that branch, the following can be used: + +@example +$ cvs diff -r RELEASE_1_0 -r EXPR1 +@end example + +A command like this can be used to produce a context +diff between two releases: + +@example +$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs +@end example + +If you are maintaining ChangeLogs, a command like the following +just before you commit your changes may help you write +the ChangeLog entry. All local modifications that have +not yet been committed will be printed. + +@example +$ cvs diff -u | less +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node export +@appendixsec export---Export sources from CVS, similar to checkout +@cindex Export (subcommand) + +@itemize @bullet +@item +Synopsis: export [-flNnQq] -r rev|-D date [-d dir] module@dots{} +@item +Requires: repository. +@item +Changes: current directory. +@end itemize + +This command is a variant of @code{checkout}; use it +when you want a copy of the source for module without +the @sc{cvs} administrative directories. For example, you +might use @code{export} to prepare source for shipment +off-site. This command requires that you specify a +date or tag (with @samp{-D} or @samp{-r}), so that you +can count on reproducing the source you ship to others. + +The keyword substitution option @samp{-kv} is always set when +export is used. This causes any @sc{rcs} keywords to be +expanded such that an import done at some other site +will not lose the keyword revision information. There +is no way to override this. Note that this breaks the +@code{ident} command (which is part of the @sc{rcs} +suite---see ident(1)) which looks for @sc{rcs} keyword +strings. If you want to be able to use @code{ident} +you must use @code{checkout} instead. + +@menu +* export options:: export options +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node export options +@appendixsubsec export options + +These standard options are supported by @code{export} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -D @var{date} +Use the most recent revision no later than @var{date}. + +@item -f +If no matching revision is found, retrieve the most +recent revision (instead of ignoring the file). + +@item -l +Local; run only in current working directory. + +@item -n +Do not run any checkout program. + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. + +@item -R +Export directories recursively. This is on by default. + +@item -r @var{tag} +Use revision @var{tag}. +@end table + +In addition, these options (that are common to +@code{checkout} and @code{export}) are also supported: + +@table @code +@item -d @var{dir} +Create a directory called @var{dir} for the working +files, instead of using the module name. Unless you +also use @samp{-N}, the paths created under @var{dir} +will be as short as possible. + +@item -N +Only useful together with @samp{-d @var{dir}}. With this +option, @sc{cvs} will not shorten module paths in your +working directory. (Normally, @sc{cvs} shortens paths as +much as possible when you specify an explicit target +directory.) +@end table + +@ignore +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@c @node export examples +@appendixsubsec export examples + +Contributed examples are gratefully accepted. +@c -- Examples here!! +@end ignore + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node history +@appendixsec history---Show status of files and users +@cindex History (subcommand) + +@itemize @bullet +@item +Synopsis: history [-report] [-flags] [-options args] [files@dots{}] +@item +Requires: the file @file{$CVSROOT/CVSROOT/history} +@item +Changes: nothing. +@end itemize + +@sc{cvs} can keep a history file that tracks each use of the +@code{checkout}, @code{commit}, @code{rtag}, +@code{update}, and @code{release} commands. You can +use @code{history} to display this information in +various formats. + +Logging must be enabled by creating the file +@file{$CVSROOT/CVSROOT/history}. + +@strong{Warning:} @code{history} uses @samp{-f}, @samp{-l}, +@samp{-n}, and @samp{-p} in ways that conflict with the +normal use inside @sc{cvs} (@pxref{Common options}). + +@menu +* history options:: history options +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node history options +@appendixsubsec history options + +Several options (shown above as @samp{-report}) control what +kind of report is generated: + +@table @code +@item -c +Report on each time commit was used (i.e., each time +the repository was modified). + +@item -e +Everything (all record types); equivalent to specifying +@samp{-xMACFROGWUT}. + +@item -m @var{module} +Report on a particular module. (You can meaningfully +use @samp{-m} more than once on the command line.) + +@item -o +Report on checked-out modules. + +@item -T +Report on all tags. + +@item -x @var{type} +Extract a particular set of record types @var{type} from the @sc{cvs} +history. The types are indicated by single letters, +which you may specify in combination. + +Certain commands have a single record type: + +@table @code +@item F +release +@item O +checkout +@item T +rtag +@end table + +@noindent +One of four record types may result from an update: + +@table @code +@item C +A merge was necessary but collisions were +detected (requiring manual merging). +@item G +A merge was necessary and it succeeded. +@item U +A working file was copied from the repository. +@item W +The working copy of a file was deleted during +update (because it was gone from the repository). +@end table + +@noindent +One of three record types results from commit: + +@table @code +@item A +A file was added for the first time. +@item M +A file was modified. +@item R +A file was removed. +@end table +@end table + +The options shown as @samp{-flags} constrain or expand +the report without requiring option arguments: + +@table @code +@item -a +Show data for all users (the default is to show data +only for the user executing @code{history}). + +@item -l +Show last modification only. + +@item -w +Show only the records for modifications done from the +same working directory where @code{history} is +executing. +@end table + +The options shown as @samp{-options @var{args}} constrain the report +based on an argument: + +@table @code +@item -b @var{str} +Show data back to a record containing the string +@var{str} in either the module name, the file name, or +the repository path. + +@item -D @var{date} +Show data since @var{date}. This is slightly different +from the normal use of @samp{-D @var{date}}, which +selects the newest revision older than @var{date}. + +@item -p @var{repository} +Show data for a particular source repository (you +can specify several @samp{-p} options on the same command +line). + +@item -r @var{rev} +Show records referring to revisions since the revision +or tag named @var{rev} appears in individual @sc{rcs} +files. Each @sc{rcs} file is searched for the revision or +tag. + +@item -t @var{tag} +Show records since tag @var{tag} was last added to the the +history file. This differs from the @samp{-r} flag +above in that it reads only the history file, not the +@sc{rcs} files, and is much faster. + +@item -u @var{name} +Show records for user @var{name}. +@end table + +@ignore +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@c @node history examples +@appendixsubsec history examples + +Contributed examples will gratefully be accepted. +@c -- Examples here! +@end ignore + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node import +@appendixsec import---Import sources into CVS, using vendor branches +@cindex Import (subcommand) + +@itemize @bullet +@item +Synopsis: import [-options] repository vendortag releasetag@dots{} +@item +Requires: Repository, source distribution directory. +@item +Changes: repository. +@end itemize + +Use @code{import} to incorporate an entire source +distribution from an outside source (e.g., a source +vendor) into your source repository directory. You can +use this command both for initial creation of a +repository, and for wholesale updates to the module +from the outside source. @xref{Tracking sources}, for +a discussion on this subject. + +The @var{repository} argument gives a directory name +(or a path to a directory) under the @sc{cvs} root directory +for repositories; if the directory did not exist, +import creates it. + +When you use import for updates to source that has been +modified in your source repository (since a prior +import), it will notify you of any files that conflict +in the two branches of development; use @samp{checkout +-j} to reconcile the differences, as import instructs +you to do. + +By default, certain file names are ignored during +@code{import}: names associated with @sc{cvs} +administration, or with other common source control +systems; common names for patch files, object files, +archive files, and editor backup files; and other names +that are usually artifacts of assorted utilities. +Currently, the default list of ignored files includes +files matching these names: + +@example + RCSLOG RCS SCCS + CVS* cvslog.* + tags TAGS + .make.state .nse_depinfo + *~ #* .#* ,* + *.old *.bak *.BAK *.orig *.rej .del-* + *.a *.o *.so *.Z *.elc *.ln + core +@end example + +If the file @file{$CVSROOT/CVSROOT/cvsignore} exists, +any files whose names match the specifications in that +file will also be ignored. + +The outside source is saved in a first-level @sc{rcs} +branch, by default 1.1.1. Updates are leaves of this +branch; for example, files from the first imported +collection of source will be revision 1.1.1.1, then +files from the first imported update will be revision +1.1.1.2, and so on. + +At least three arguments are required. +@var{repository} is needed to identify the collection +of source. @var{vendortag} is a tag for the entire +branch (e.g., for 1.1.1). You must also specify at +least one @var{releasetag} to identify the files at +the leaves created each time you execute @code{import}. + +@menu +* import options:: import options +* import examples:: import examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node import options +@appendixsubsec import options + +These standard options are supported by @code{import} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -m @var{message} +Use @var{message} as log information, instead of +invoking an editor. + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. +@end table + +There are three additional special options. + +@table @code +@item -b @var{branch} +Specify a first-level branch other than 1.1.1. Unless +the @samp{-b @var{branch}} flag is given, revisions will +@emph{always} be made to the branch 1.1.1---even if a +@var{vendortag} that matches another branch is given! +What happens in that case, is that the tag will be +reset to 1.1.1. Warning: This behavior might change +in the future. + +@item -k @var{subst} +Indicate the RCS keyword expansion mode desired. This setting will +apply to all files created during the import, but not to any files that +previously existed in the repository. See co(1) for a complete list of +valid @samp{-k} settings. + +If you are checking in sources that contain @sc{rcs} keywords, and you +wish those keywords to remain intact, use the @samp{-ko} flag when +importing the files. This setting indicates that no keyword expansion +is to be performed by @sc{rcs} when checking files out. It is also +useful for checking in binaries. + +@item -I @var{name} +Specify file names that should be ignored during +import. You can use this option repeatedly. To avoid +ignoring any files at all (even those ignored by +default), specify `-I !'. + +@var{name} can be a file name pattern of the same type +that you can specify in the @file{.cvsignore} file. +@xref{cvsignore}. +@c -- Is this really true? +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node import examples +@appendixsubsec import examples + +@xref{Tracking sources}, and @xref{From files}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node log +@appendixsec log---Print out 'rlog' information for files +@cindex Log (subcommand) + +@itemize @bullet +@item +Synopsis: log [-l] rlog-options [files@dots{}] +@item +Requires: repository, working directory. +@item +Changes: nothing. +@item +Synonym: rlog +@end itemize + +Display log information for files. @code{log} calls +the @sc{rcs} utility @code{rlog}, which prints all available +information about the @sc{rcs} history file. This includes +the location of the @sc{rcs} file, the @dfn{head} revision +(the latest revision on the trunk), all symbolic names (tags) +and some other things. For each revision, the revision +number, the author, the number of lines added/deleted and +the log message are printed. All times are displayed in +Coordinated Universal Time (UTC). (Other parts of @sc{cvs} +print times in the local timezone). +@c -- timezone-- + +@menu +* log options:: log options +* log examples:: log examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node log options +@appendixsubsec log options + +Only one option is interpreted by @sc{cvs} and not passed on to @code{rlog}: + +@table @code +@item -l +Local; run only in current working directory. (Default +is to run recursively). +@end table + +By default, @code{rlog} prints all information that is +available. All other options (including those that +normally behave differently) are passed through to +@code{rlog} and restrict the output. See rlog(1) for a +complete description of options. This incomplete list +(which is a slightly edited extract from rlog(1)) lists +all options that are useful in conjunction with @sc{cvs}. + +@strong{Please note:} There can be no space between the option +and its argument, since @code{rlog} parses its options +in a different way than @sc{cvs}. + +@table @code +@item -b +Print information about the revisions on the default +branch, normally the highest branch on the trunk. + +@item -d@var{dates} +Print information about revisions with a checkin +date/time in the range given by the +semicolon-separated list of dates. The following table +explains the available range formats: + +@table @code +@item @var{d1}<@var{d2} +@itemx @var{d2}>@var{d1} +Select the revisions that were deposited between +@var{d1} and @var{d2} inclusive. + +@item <@var{d} +@itemx @var{d}> +Select all revisions dated @var{d} or earlier. + +@item @var{d}< +@itemx >@var{d} +Select all revisions dated @var{d} or later. + +@item @var{d} +Select the single, latest revision dated @var{d} or +earlier. +@end table + +The date/time strings @var{d}, @var{d1}, and @var{d2} +are in the free format explained in co(1). Quoting is +normally necessary, especially for < and >. Note that +the separator is a semicolon (;). + +@item -h +Print only the @sc{rcs} pathname, working pathname, head, +default branch, access list, locks, symbolic names, and +suffix. + +@item -N +Do not print the list of tags for this file. This +option can be very useful when your site uses a lot of +tags, so rather than "more"'ing over 3 pages of tag +information, the log information is presented without +tags at all. + +@item -R +Print only the name of the @sc{rcs} history file. + +@item -r@var{revisions} +Print information about revisions given in the +comma-separated list @var{revisions} of revisions and +ranges. The following table explains the available +range formats: + +@table @code +@item @var{rev1}:@var{rev2} +Revisions @var{rev1} to @var{rev2} (which must be on +the same branch). + +@item :@var{rev} +Revisions from the beginning of the branch up to +and including @var{rev}. + +@item @var{rev}: +Revisions starting with @var{rev} to the end of the +branch containing @var{rev}. + +@item @var{branch} +An argument that is a branch means all revisions on +that branch. You can unfortunately not specify a +symbolic branch here. You must specify the numeric +branch number. @xref{Magic branch numbers}, for an +explanation. + +@item @var{branch1}:@var{branch2} +A range of branches means all revisions +on the branches in that range. + +@item @var{branch}. +The latest revision in @var{branch}. +@end table + +A bare @samp{-r} with no revisions means the latest +revision on the default branch, normally the trunk. + +@item -s@var{states} +Print information about revisions whose state +attributes match one of the states given in the +comma-separated list @var{states}. + +@item -t +Print the same as @samp{-h}, plus the descriptive text. + +@item -w@var{logins} +Print information about revisions checked in by users +with login names appearing in the comma-separated list +@var{logins}. If @var{logins} is omitted, the user's +login is assumed. +@end table + +@code{rlog} prints the intersection of the revisions +selected with the options @samp{-d}, @samp{-l}, +@samp{-s}, and @samp{-w}, intersected with the union of +the revisions selected by @samp{-b} and @samp{-r}. + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node log examples +@appendixsubsec log examples + +Contributed examples are gratefully accepted. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node rdiff +@appendixsec rdiff---'patch' format diffs between releases +@cindex Rdiff (subcommand) + +@itemize @bullet +@item +rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{} +@item +Requires: repository. +@item +Changes: nothing. +@item +Synonym: patch +@end itemize + +Builds a Larry Wall format patch(1) file between two +releases, that can be fed directly into the patch +program to bring an old release up-to-date with the new +release. (This is one of the few @sc{cvs} commands that +operates directly from the repository, and doesn't +require a prior checkout.) The diff output is sent to +the standard output device. + +You can specify (using the standard @samp{-r} and +@samp{-D} options) any combination of one or two +revisions or dates. If only one revision or date is +specified, the patch file reflects differences between +that revision or date and the current head revisions in +the @sc{rcs} file. + +Note that if the software release affected is contained +in more than one directory, then it may be necessary to +specify the @samp{-p} option to the patch command when +patching the old sources, so that patch is able to find +the files that are located in other directories. + +@menu +* rdiff options:: rdiff options +* rdiff examples:: rdiff examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node rdiff options +@appendixsubsec rdiff options + +These standard options are supported by @code{rdiff} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -D @var{date} +Use the most recent revision no later than @var{date}. + +@item -f +If no matching revision is found, retrieve the most +recent revision (instead of ignoring the file). + +@item -l +Local; don't descend subdirectories. + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. + +@item -r @var{tag} +Use revision @var{tag}. +@end table + +In addition to the above, these options are available: + +@table @code +@item -c +Use the context diff format. This is the default format. + +@item -s +Create a summary change report instead of a patch. The +summary includes information about files that were +changed or added between the releases. It is sent to +the standard output device. This is useful for finding +out, for example, which files have changed between two +dates or revisions. + +@item -t +A diff of the top two revisions is sent to the standard +output device. This is most useful for seeing what the +last change to a file was. + +@item -u +Use the unidiff format for the context diffs. +This option is not available if your diff does not +support the unidiff format. Remember that old versions +of the @code{patch} program can't handle the unidiff +format, so if you plan to post this patch to the net +you should probably not use @samp{-u}. + +@item -V @var{vn} +Expand @sc{rcs} keywords according to the rules current in +@sc{rcs} version @var{vn} (the expansion format changed with +@sc{rcs} version 5). +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node rdiff examples +@appendixsubsec rdiff examples + +Suppose you receive mail from @t{foo@@bar.com} asking for an +update from release 1.2 to 1.4 of the tc compiler. You +have no such patches on hand, but with @sc{cvs} that can +easily be fixed with a command such as this: + +@example +$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \ +$$ Mail -s 'The patches you asked for' foo@@bar.com +@end example + +Suppose you have made release 1.3, and forked a branch +called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1} +corresponds to release 1.3.1, which was made some time +ago. Now, you want to see how much development has been +done on the branch. This command can be used: + +@example +$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name +cvs rdiff: Diffing module-name +File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6 +File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4 +File bar.h,v changed from revision 1.29.2.1 to 1.2 +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node release +@appendixsec release---Indicate that a Module is no longer in use +@cindex Release (subcommand) + +@itemize @bullet +@item +release [-dQq] modules@dots{} +@item +Requires: Working directory. +@item +Changes: Working directory, history log. +@end itemize + +This command is meant to safely cancel the effect of +@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it +isn't strictly necessary to use this command. You can +always simply delete your working directory, if you +like; but you risk losing changes you may have +forgotten, and you leave no trace in the @sc{cvs} history +file (@pxref{history file}) that you've abandoned your +checkout. + +Use @samp{cvs release} to avoid these problems. This +command checks that no uncommitted changes are +present; that you are executing it from immediately +above a @sc{cvs} working directory; and that the repository +recorded for your files is the same as the repository +defined in the module database. + +If all these conditions are true, @samp{cvs release} +leaves a record of its execution (attesting to your +intentionally abandoning your checkout) in the @sc{cvs} +history log. + +@menu +* release options:: release options +* release output:: release options +* release examples:: release examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node release options +@appendixsubsec release options + +Only these standard options are supported by @code{release}. + +@table @code +@item -Q +Really quiet. + +@item -q +Somewhat quiet. +@end table + +In addition to the above, it supports one additional +flag. + +@table @code +@item -d +Delete your working copy of the file if the release +succeeds. If this flag is not given your files will +remain in your working directory. + +@strong{Warning:} The @code{release} command uses +@samp{rm -r @file{module}} to delete your file. This +has the very serious side-effect that any directory +that you have created inside your checked-out sources, +and not added to the repository (using the @code{add} +command; @pxref{add}) will be silently deleted---even +if it is non-empty! +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node release output +@appendixsubsec release output + +Before @code{release} releases your sources it will +print a one-line message for any file that is not +up-to-date. + +@strong{Warning:} Any new directories that you have +created, but not added to the @sc{cvs} directory hierarchy +with the @code{add} command (@pxref{add}) will be +silently ignored (and deleted, if @samp{-d} is +specified), even if they contain files. + +@table @code +@item U @var{file} +There exists a newer revision of this file in the +repository, and you have not modified your local copy +of the file. + +@item A @var{file} +The file has been added to your private copy of the +sources, but has not yet been committed to the +repository. If you delete your copy of the sources +this file will be lost. + +@item R @var{file} +The file has been removed from your private copy of the +sources, but has not yet been removed from the +repository, since you have not yet committed the +removal. @xref{commit}. + +@item M @var{file} +The file is modified in your working directory. There +might also be a newer revision inside the repository. + +@item ? @var{file} +@var{file} is in your working directory, but does not +correspond to anything in the source repository, and is +not in the list of files for @sc{cvs} to ignore (see the +description of the @samp{-I} option, and +@pxref{cvsignore}). If you remove your working +sources, this file will be lost. + +Note that no warning message like this is printed for +spurious directories that @sc{cvs} encounters. The +directory, and all its contents, are silently ignored. + +@c FIXME -- this should be fixed for CVS 1.4 +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node release examples +@appendixsubsec release examples + +Release the module, and delete your local working copy +of the files. + +@example +$ cd .. # @r{You must stand immediately above the} + # @r{sources when you issue @samp{cvs release}.} +$ cvs release -d tc +You have [0] altered files in this repository. +Are you sure you want to release (and delete) module `tc': y +$ +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node remove +@appendixsec remove---Remove an entry from the repository +@cindex Remove (subcommand) + +@itemize @bullet +@item +remove [-lR] [files@dots{}] +@item +Requires: Working directory. +@item +Changes: Working directory. +@item +Synonyms: rm, delete +@end itemize + +Use this command to declare that you wish to remove +files from the source repository. Like most @sc{cvs} +commands, @samp{cvs remove} works on files in your working +directory, not directly on the repository. As a +safeguard, it also requires that you first erase the +specified files from your working directory. + +The files are not actually removed until you apply your +changes to the repository with @code{commit}; at that +point, the corresponding @sc{rcs} files in the source +repository are moved into the @file{Attic} directory +(also within the source repository). + +This command is recursive by default, scheduling all +physically removed files that it finds for removal by +the next commit. Use the @samp{-l} option to avoid +this recursion, or just specify the actual files that +you wish removed. + + +@menu +* remove options:: remove options +* remove examples:: remove examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node remove options +@appendixsubsec remove options + +Two of the standard options are the only options +supported by @code{remove}. + +@table @code +@item -l +Local; run only in current working directory. + +@item -R +Commit directories recursively. This is on by default. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node remove examples +@appendixsubsec remove examples + +@appendixsubsubsec Remove a couple of files. + +@example +$ cd test +$ rm ?.c +$ cvs remove +cvs remove: Removing . +cvs remove: scheduling a.c for removal +cvs remove: scheduling b.c for removal +cvs remove: use 'cvs commit' to remove these files permanently +$ cvs ci -m "Removed unneeded files" +cvs commit: Examining . +cvs commit: Committing . +@end example + +@appendixsubsubsec Resurrecting removed files + +If you change your mind you can easily resurrect the +file before you commit it, using the @code{add} +command. + +@example +$ ls +CVS ja.h oj.c +$ rm oj.c +$ cvs remove oj.c +cvs remove: scheduling oj.c for removal +cvs remove: use 'cvs commit' to remove this file permanently +$ cvs add oj.c +U oj.c +cvs add: oj.c, version 1.1.1.1, resurrected +@end example + +If you realize your mistake before you run the +@code{remove} command you can use @code{update} to +resurrect the file: + +@example +$ rm oj.c +$ cvs update oj.c +cvs update: warning: oj.c was lost +U oj.c +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node rtag +@appendixsec rtag---Add a tag to the RCS file +@cindex Rtag (subcommand) + +@itemize @bullet +@item +rtag [-falnRQq] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules@dots{} +@item +Requires: repository. +@item +Changes: repository. +@item +Synonym: rfreeze +@end itemize + +You can use this command to assign symbolic tags to +particular, explicitly specified source revisions in +the repository. @code{rtag} works directly on the +repository contents (and requires no prior checkout). +Use @code{tag} instead (@pxref{tag}), to base the +selection of revisions on the contents of your +working directory. + +If you attempt to use a tag name that already exists, +@sc{cvs} will complain and not overwrite that tag. Use +the @samp{-F} option to force the new tag value. + +@menu +* rtag options:: rtag options +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node rtag options +@appendixsubsec rtag options + +These standard options are supported by @code{rtag} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -D @var{date} +Tag the most recent revision no later than @var{date}. + +@item -f +Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}} +flags. If no matching revision is found, use the most +recent revision (instead of ignoring the file). + +@item -F +Overwrite an existing tag of the same name on a +different revision. This option is new in @sc{cvs} +1.4. The old behavior is matched by @samp{cvs tag -F}. + +@item -l +Local; run only in current working directory. + +@item -n +Do not run any tag program that was specified with the +@samp{-t} flag inside the @file{modules} file. +(@pxref{modules}). + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. + +@item -R +Commit directories recursively. This is on by default. + +@item -r @var{tag} +Only tag those files that contain @var{tag}. This can +be used to rename a tag: tag only the files identified +by the old tag, then delete the old tag, leaving the +new tag on exactly the same files as the old tag. +@end table + +In addition to the above common options, these options +are available: + +@table @code +@item -a +Use the @samp{-a} option to have @code{rtag} look in the +@file{Attic} (@pxref{Removing files}) for removed files +that contain the specified tag. The tag is removed from +these files, which makes it convenient to re-use a +symbolic tag as development continues (and files get +removed from the up-coming distribution). + +@item -b +Make the tag a branch tag. @xref{Branches}. + +@item -d +Delete the tag instead of creating it. + +In general, tags (often the symbolic names of software +distributions) should not be removed, but the @samp{-d} +option is available as a means to remove completely +obsolete symbolic names if necessary (as might be the +case for an Alpha release, or if you mistagged a +module). +@end table + +@ignore +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@c @node rtag examples +@appendixsubsec rtag examples + +@c -- Examples here! +@end ignore + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node status +@appendixsec status---Status info on the revisions +@cindex Status (subcommand) + +@itemize @bullet +@item +status [-lR] [-v] [-Q] [files@dots{}] +@item +Requires: working directory, repository. +@item +Changes: nothing. +@end itemize + +Display a brief report on the current status of files +with respect to the source repository, including any +sticky tags, dates, or @samp{-k} options. + +You can also use this command to determine the +potential impact of a @samp{cvs update} on your working +source directory---but remember that things might +change in the repository before you run @code{update}. + +@menu +* status options:: status options +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node status options +@appendixsubsec status options + +These standard options are supported by @code{status} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -l +Local; run only in current working directory. + +@item -R +Commit directories recursively. This is on by default. + +@item -Q +Really quiet. Do not print empty sticky parts. This +option is not available in @sc{cvs} 1.3. +@end table + +There is one additional option: + +@table @code +@item -v +Verbose. In addition to the information normally +displayed, print all symbolic tags, together with the +numerical value of the revision or branch they refer +to. +@end table + +@ignore +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@c @node status examples +@appendixsubsec status examples + +@c -- FIXME +@end ignore + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node tag +@appendixsec tag---Add a symbolic tag to checked out version of RCS file +@c -- //////// - unnecessary. Also +@c -- in a lot of other +@c -- places. +@cindex Tag (subcommand) + +@itemize @bullet +@item +tag [-lQqR] [-b] [-d] symbolic_tag [files@dots{}] +@item +Requires: working directory, repository. +@item +Changes: repository. +@item +Synonym: freeze +@end itemize + +Use this command to assign symbolic tags to the nearest +repository versions to your working sources. The tags +are applied immediately to the repository, as with +@code{rtag}, but the versions are supplied implicitly by the +@sc{cvs} records of your working files' history rather than +applied explicitly. + +One use for tags is to record a snapshot of the +current sources when the software freeze date of a +project arrives. As bugs are fixed after the freeze +date, only those changed sources that are to be part of +the release need be re-tagged. + +The symbolic tags are meant to permanently record which +revisions of which files were used in creating a +software distribution. The @code{checkout} and +@code{update} commands allow you to extract an exact +copy of a tagged release at any time in the future, +regardless of whether files have been changed, added, +or removed since the release was tagged. + +This command can also be used to delete a symbolic tag, +or to create a branch. See the options section below. + +If you attempt to use a tag name that already exists, +@sc{cvs} will complain and not overwrite that tag. Use +the @samp{-F} option to force the new tag value. + + +@menu +* tag options:: tag options +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node tag options +@appendixsubsec tag options + +These standard options are supported by @code{tag} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -F +Overwrite an existing tag of the same name on a +different revision. This option is new in @sc{cvs} +1.4. The old behavior is matched by @samp{cvs tag -F}. + +@item -l +Local; run only in current working directory. + +@item -R +Commit directories recursively. This is on by default. + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. +@end table + +Two special options are available: + +@table @code +@item -b +The -b option makes the tag a branch tag +(@pxref{Branches}), allowing concurrent, isolated +development. This is most useful for creating a patch +to a previously released software distribution. + +@item -d +Delete a tag. + +If you use @samp{cvs tag -d symbolic_tag}, the symbolic +tag you specify is deleted instead of being added. +Warning: Be very certain of your ground before you +delete a tag; doing this permanently discards some +historical information, which may later turn out to +be valuable. +@end table + +@ignore +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@c @node tag examples +@appendixsubsec tag examples + +@c -- FIXME +@end ignore + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node update +@appendixsec update---Bring work tree in sync with repository +@cindex Update (subcommand) + +@itemize @bullet +@item +update [-AdflPpQqR] [-d] [-r tag|-D date] files@dots{} +@item +Requires: repository, working directory. +@item +Changes: working directory. +@end itemize + +After you've run checkout to create your private copy +of source from the common repository, other developers +will continue changing the central source. From time +to time, when it is convenient in your development +process, you can use the @code{update} command from +within your working directory to reconcile your work +with any revisions applied to the source repository +since your last checkout or update. + +@menu +* update options:: update options +* update output:: update output +* update examples:: update examples +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node update options +@appendixsubsec update options + +These standard options are available with @code{update} +(@pxref{Common options}, for a complete description of +them): + +@table @code +@item -D date +Use the most recent revision no later than @var{date}. +This option is sticky, and implies @samp{-P}. + +@item -f +Only useful with the @samp{-D @var{date}} or @samp{-r +@var{tag}} flags. If no matching revision is found, +retrieve the most recent revision (instead of ignoring +the file). + +@item -k @var{kflag} +Process @sc{rcs} keywords according to @var{kflag}. See +co(1). This option is sticky; future updates of +this file in this working directory will use the same +@var{kflag}. The @code{status} command can be viewed +to see the sticky options. @xref{status}. + +@item -l +Local; run only in current working directory. + +@item -P +Prune empty directories. + +@item -p +Pipe files to the standard output. + +@item -Q +Really quiet. + +@item -q +Somewhat quiet. + +@item -R +Commit directories recursively. This is on by default. + +@item -r tag +Retrieve revision @var{tag}. This option is sticky, +and implies @samp{-P}. +@end table + +@need 800 +These special options are also available with +@code{update}. + +@table @code +@item -A +Reset any sticky tags, dates, or @samp{-k} options. +(If you get a working copy of a file by using one of +the @samp{-r}, @samp{-D}, or @samp{-k} options, @sc{cvs} +remembers the corresponding tag, date, or @var{kflag} and +continues using it on future updates; use the @samp{-A} +option to make @sc{cvs} forget these specifications, and +retrieve the head revision of the file). + +@item -d +Create any directories that exist in the repository if +they're missing from the working directory. Normally, +@code{update} acts only on directories and files that +were already enrolled in your working directory. + +This is useful for updating directories that were +created in the repository since the initial checkout; +but it has an unfortunate side effect. If you +deliberately avoided certain directories in the +repository when you created your working directory +(either through use of a module name or by listing +explicitly the files and directories you wanted on the +command line), then updating with @samp{-d} will create +those directories, which may not be what you want. + +@item -I @var{name} +Ignore files whose names match @var{name} (in your +working directory) during the update. You can specify +@samp{-I} more than once on the command line to specify +several files to ignore. By default, @code{update} +ignores files whose names match any of the following: + +@example + RCSLOG RCS SCCS + CVS* cvslog.* + tags TAGS + .make.state .nse_depinfo + *~ #* .#* ,* + *.old *.bak *.BAK *.orig *.rej .del-* + *.a *.o *.so *.Z *.elc *.ln + core +@end example + +Use @samp{-I !} to avoid ignoring any files at all. +@xref{cvsignore}, for other ways to make @sc{cvs} ignore +some files. + +@item -j@var{branch} +Merge the changes made between the resulting revision +and the revision that it is based on (e.g., if the tag +refers to a branch, @sc{cvs} will merge all changes made in +that branch into your working file). + +With two @samp{-j} options, @sc{cvs} will merge in the +changes between the two respective revisions. This can +be used to remove a certain delta from your working +file; if the file @file{foo.c} is based on +revision 1.6 and you want to remove the changes made +between 1.3 and 1.5, you might do: + +@example +$ cvs update -j1.5 -j1.3 foo.c # @r{note the order@dots{}} +@end example + +In addition, each -j option can contain an optional +date specification which, when used with branches, can +limit the chosen revision to one within a specific +date. An optional date is specified by adding a colon +(:) to the tag: +@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node update output +@appendixsubsec update output + +@code{update} keeps you informed of its progress by +printing a line for each file, preceded by one +character indicating the status of the file: + +@table @code +@item U @var{file} +The file was brought up to date with respect to the +repository. This is done for any file that exists in +the repository but not in your source, and for files +that you haven't changed but are not the most recent +versions available in the repository. + +@item A @var{file} +The file has been added to your private copy of the +sources, and will be added to the source repository +when you run @code{commit} on the file. This is a +reminder to you that the file needs to be committed. + +@item R @var{file} +The file has been removed from your private copy of the +sources, and will be removed from the source repository +when you run @code{commit} on the file. This is a +reminder to you that the file needs to be committed. + +@item M @var{file} +The file is modified in your working directory. + +@samp{M} can indicate one of two states for a file +you're working on: either there were no modifications +to the same file in the repository, so that your file +remains as you last saw it; or there were modifications +in the repository as well as in your copy, but they +were merged successfully, without conflict, in your +working directory. + +@sc{cvs} will print some messages if it merges your work, +and a backup copy of your working file (as it looked +before you ran @code{update}) will be made. The exact +name of that file is printed while @code{update} runs. + +@item C @var{file} +A conflict was detected while trying to merge your +changes to @var{file} with changes from the source +repository. @var{file} (the copy in your working +directory) is now the output of the rcsmerge(1) command +on the two revisions; an unmodified copy of your file +is also in your working directory, with the name +@file{.#@var{file}.@var{revision}} where @var{revision} +is the @sc{rcs} revision that your modified file started +from. (Note that some systems automatically purge +files that begin with @file{.#} if they have not been +accessed for a few days. If you intend to keep a copy +of your original file, it is a very good idea to rename +it.) + +@item ? @var{file} +@var{file} is in your working directory, but does not +correspond to anything in the source repository, and is +not in the list of files for @sc{cvs} to ignore (see the +description of the @samp{-I} option, and +@pxref{cvsignore}). + +Note that no warning message like this is printed for +spurious directories that @sc{cvs} encounters. The +directory, and all its contents, are silently ignored. +@end table + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node update examples +@appendixsubsec update examples + +The following line will display all files which are not +up-to-date without actually change anything in your +working directory. It can be used to check what has +been going on with the project. + +@example +$ cvs -n -q update +@end example + +@c --------------------------------------------------------------------- +@node Administrative files +@appendix Reference manual for the Administrative files +@cindex Administrative files (reference) +@cindex Files, reference manual +@cindex Reference manual (files) +@cindex CVSROOT (file) + +Inside the repository, in the directory +@file{$CVSROOT/CVSROOT}, there are a number of +supportive files for @sc{cvs}. You can use @sc{cvs} in a limited +fashion without any of them, but if they are set up +properly they can help make life easier. + +The most important of these files is the @file{modules} +file, which defines the modules inside the repository. + +@menu +* modules:: Defining modules +* commit files:: The commit support files +* commitinfo:: Pre-commit checking +* editinfo:: Specifying how log messages are created +* loginfo:: Where should log messages be sent? +* rcsinfo:: Templates for the log messages +* cvsignore:: Ignoring files via cvsignore +* history file:: History information +* Setting up:: Setting up the repository +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node modules +@appendixsec The modules file +@cindex Modules (admin file) +@cindex Defining modules (reference manual) + +The @file{modules} file records your definitions of +names for collections of source code. @sc{cvs} will use +these definitions if you create a file with the right +format in @file{$CVSROOT/CVSROOT/modules,v}. The +mkmodules(1) command should be run whenever the modules +file changes, so that the appropriate files can be +generated (depending on how you have configured @sc{cvs} +operation). + +To allow convenient editing of the @file{modules} file +itself, the file should include an entry like the +following (where @var{localbin} represents the +directory where your site installs programs like +mkmodules(1)): + +@example +modules -i /@var{localbin}/mkmodules CVSROOT modules +@end example + +@noindent +This defines the name @samp{modules} as the module name +for the file itself, so that you can use + +@example +$ cvs checkout modules +@end example + +@noindent +to get a copy of the file that you can edit. You should define +similar module entries for the other configuration +files described in this appendix, except +@file{history}). + +The @file{modules} file may contain blank lines and +comments (lines beginning with @samp{#}) as well as +module definitions. Long lines can be continued on the +next line by specifying a backslash (@samp{\}) as the +last character on the line. + +A module definition is a single line of the +@file{modules} file, in either of two formats. In both +cases, @var{mname} represents the symbolic module name, +and the remainder of the line is its definition. + +@table @code +@item @var{mname} -a @var{aliases}@dots{} +This represents the simplest way of defining a module +@var{mname}. The @samp{-a} flags the definition as a +simple alias: @sc{cvs} will treat any use of @var{mname} (as +a command argument) as if the list of names +@var{aliases} had been specified instead. +@var{aliases} may contain either other module names or +paths. When you use paths in aliases, @code{checkout} +creates all intermediate directories in the working +directory, just as if the path had been specified +explicitly in the @sc{cvs} arguments. + +@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] [ &@var{module}@dots{} ] +In the simplest case, this form of module definition +reduces to @samp{@var{mname} @var{dir}}. This defines +all the files in directory @var{dir} as module mname. +@var{dir} is a relative path (from @code{$CVSROOT}) to a +directory of source in the source repository. In this +case, on checkout, a single directory called +@var{mname} is created as a working directory; no +intermediate directory levels are used by default, even +if @var{dir} was a path involving several directory +levels. + +By explicitly specifying files in the module definition +after @var{dir}, you can select particular files from +directory @var{dir}. The sample definition for +@samp{modules} is an example of a module defined with a +single file from a particular directory. Here is +another example: + +@example +m4test unsupported/gnu/m4 foreach.m4 forloop.m4 +@end example + +@noindent +With this definition, executing @samp{cvs checkout +m4test} will create a single working directory +@file{m4test} containing the two files listed, which +both come from a common directory several levels deep +in the @sc{cvs} source repository. + +A module definition can refer to other modules by +including @samp{&@var{module}} in its definition. +@code{checkout} creates a subdirectory for each such +module, in your working directory. +@c -- Nope. "in your working directory" is wrong. What +@c -- is right? + +@table @code +@item -d @var{name} +Name the working directory something other than the +module name. + +@cindex Checkin program +@item -i @var{prog} +Specify a program @var{prog} to run whenever files in a +module are committed. @var{prog} runs with a single +argument, the full pathname of the affected directory +in a source repository. The @file{commitinfo}, +@file{loginfo}, and @file{editinfo} files provide other +ways to call a program on commit. + +@cindex Checkout program +@item -o @var{prog} +Specify a program @var{prog} to run whenever files in a +module are checked out. @var{prog} runs with a single +argument, the module name. + +@cindex Status of a module +@cindex Module status +@item -s @var{status} +Assign a status to the module. When the module file is +printed with @samp{cvs checkout -s} the modules are +sorted according to primarily module status, and +secondarily according to the module name. This option +has no other meaning. You can use this option for +several things besides status: for instance, list the +person that is responsible for this module. + +@cindex Tag program +@item -t @var{prog} +Specify a program @var{prog} to run whenever files in a +module are tagged with @code{rtag}. @var{prog} runs +with two arguments: the module name and the symbolic +tag specified to @code{rtag}. There is no way to +specify a program to run when @code{tag} is executed. + +@cindex Update program +@item -u @var{prog} +Specify a program @var{prog} to run whenever @samp{cvs +update} is executed from the top-level directory of the +checked-out module. @var{prog} runs with a single +argument, the full path to the source repository for +this module. +@end table +@end table + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node commit files +@appendixsec The commit support files +@cindex Commit files + +The @samp{-i} flag in the @file{modules} file can be +used to run a certain program whenever files are +committed (@pxref{modules}). The files described in +this section provide other, more flexible, ways to run +programs whenever something is committed. + +There are three kind of programs that can be run on +commit. They are specified in files in the repository, +as described below. The following table summarizes the +file names and the purpose of the corresponding +programs. + +@table @file +@item commitinfo +The program is responsible for checking that the commit +is allowed. If it exits with a non-zero exit status +the commit will be aborted. + +@item editinfo +The specified program is used to edit the log message, +and possibly verify that it contains all required +fields. This is most useful in combination with the +@file{rcsinfo} file, which can hold a log message +template (@pxref{rcsinfo}). + +@item loginfo +The specified program is called when the commit is +complete. It receives the log message and some +additional information and can store the log message in +a file, or mail it to appropriate persons, or maybe +post it to a local newsgroup, or@dots{} Your +imagination is the limit! +@end table + +@menu +* syntax:: The common syntax +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node syntax +@appendixsubsec The common syntax +@cindex Info files (syntax) +@cindex Syntax of info files +@cindex Common syntax of info files + +The four files @file{commitinfo}, @file{loginfo}, +@file{rcsinfo} and @file{editinfo} all have a common +format. The purpose of the files are described later +on. The common syntax is described here. + +Each line contains the following: +@itemize @bullet +@item +A regular expression + +@item +A whitespace separator---one or more spaces and/or tabs. + +@item +A file name or command-line template. +@end itemize + +@noindent +Blank lines are ignored. Lines that start with the +character @samp{#} are treated as comments. Long lines +unfortunately can @emph{not} be broken in two parts in +any way. + +Whenever one of the regular expressions matches a +directory name in the repository, the rest of the line +is used. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node commitinfo +@appendixsec Commitinfo +@cindex Commitinfo +@cindex Checking commits +@cindex Precommit checking + +The @file{commitinfo} file defines programs to execute +whenever @samp{cvs commit} is about to execute. These +programs are used for pre-commit checking to verify +that the modified, added and removed files are really +ready to be committed. This could be used, for +instance, to verify that the changed files conform to +to your site's standards for coding practice. + +As mentioned earlier, each line in the +@file{commitinfo} file consists of a regular expression +and a command-line template. The template can include +a program name and any number of arguments you wish to +supply to it. The full path to the current source +repository is appended to the template, followed by the +file names of any files involved in the commit (added, +removed, and modified files). + +All lines with a regular expression matching the +relative path to the module will be used. If any of +the commands return a non-zero exit status the commit +will be aborted. + +@cindex DEFAULT in commitinfo +If the repository name does not match any of the +regular expressions in this file, the @samp{DEFAULT} +line is used, if it is specified. + +@cindex ALL in commitinfo +If the name @samp{ALL} appears as a regular expression +it is always used in addition to any matching regular +expression or @samp{DEFAULT}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node editinfo +@appendixsec Editinfo +@cindex Editinfo +@cindex Editor, specifying per module +@cindex Per-module editor +@cindex Log messages, editing + +If you want to make sure that all log messages look the +same way, you can use the @file{editinfo} file to +specify a program that is used to edit the log message. +This program could be a custom-made editor that always +enforces a certain style of the log message, or maybe a +simple shell script that calls an editor, and checks +that the entered message contains the required fields. + +If no matching line is found in the @file{editinfo} +file, the editor specified in the environment variable +@code{$CVSEDITOR} is used instead. If that variable is +not set, then the environment variable @code{$EDITOR} +is used instead. If that variable is not +set a precompiled default, normally @code{vi}, will be +used. + +The @file{editinfo} file is often most useful together +with the @file{rcsinfo} file, which can be used to +specify a log message template. + +Each line in the @file{editinfo} file consists of a +regular expression and a command-line template. The template must +include a program name, and can include any number of +arguments. The full path to the current log message +template file is appended to the template. + +One thing that should be noted is that the ALL keyword +is not supported. If more than one matching line is +found, the last one is used. This can be useful for +specifying a default edit script in a module, and then +overriding it in a subdirectory. + +If the edit script exits with a non-zero exit status, +the commit is aborted. + +@menu +* editinfo example:: Editinfo example +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node editinfo example +@appendixsubsec Editinfo example + +The following is a little silly example of a +@file{editinfo} file, together with the corresponding +@file{rcsinfo} file, the log message template and an +editor script. We begin with the log message template. +We want to always record a bug-id number on the first +line of the log message. The rest of log message is +free text. The following template is found in the file +@file{/usr/cvssupport/tc.template}. + +@example +BugId: +@end example + +The script @file{/usr/cvssupport/bugid.edit} is used to +edit the log message. + +@example +#!/bin/sh +# +# bugid.edit filename +# +# Call $EDITOR on FILENAME, and verify that the +# resulting file contains a valid bugid on the first +# line. +if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi +if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi +$CVSEDITOR $1 +until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1 +do echo -n "No BugId found. Edit again? ([y]/n)" + read ans + case $@{ans@} in + n*) exit 1;; + esac + $CVSEDITOR $1 +done +@end example + +The @file{editinfo} file contains this line: + +@example +^tc /usr/cvssupport/bugid.edit +@end example + +The @file{rcsinfo} file contains this line: + +@example +^tc /usr/cvssupport/tc.template +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node loginfo +@appendixsec Loginfo +@cindex Loginfo +@cindex Storing log messages +@cindex Mailing log messages +@cindex Distributing log messages +@cindex Log messages + +The @file{loginfo} file is used to control where +@samp{cvs commit} log information is sent. The first +entry on a line is a regular expression which is tested +against the directory that the change is being made to, +relative to the @code{$CVSROOT}. If a match is found, then +the remainder of the line is a filter program that +should expect log information on its standard input. + +The filter program may use one and only one % modifier +(a la printf). If @samp{%s} is specified in the filter +program, a brief title is included (enclosed in single +quotes) showing the modified file names. + +If the repository name does not match any of the +regular expressions in this file, the @samp{DEFAULT} +line is used, if it is specified. + +If the name @samp{ALL} appears as a regular expression +it is always used in addition to any matching regular expression or +@samp{DEFAULT}. + +All matching regular expressions are used. + +@xref{commit files}, for a description of the syntax of +the @file{loginfo} file. + +@menu +* loginfo example:: Loginfo example +@end menu + +@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . +@node loginfo example +@appendixsubsec Loginfo example + +The following @file{loginfo} file, together with the +tiny shell-script below, appends all log messages +to the file @file{$CVSROOT/CVSROOT/commitlog}, +and any commits to the administrative files (inside +the @file{CVSROOT} directory) are also logged in +@file{/usr/adm/cvsroot-log} and mailed to @t{ceder}. + +@example +ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog +^CVSROOT Mail -s %s ceder +^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log +@end example + +The shell-script @file{/usr/local/bin/cvs-log} looks +like this: + +@example +#!/bin/sh +(echo "-----------------------------------------------------------------"; + echo -n $USER" "; + date; + echo; + sed '1s+'$@{CVSROOT@}'++') >> $1 +@end example + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node rcsinfo +@appendixsec Rcsinfo +@cindex Rcsinfo +@cindex Form for log message +@cindex Log message template +@cindex Template for log message + +The @file{rcsinfo} file can be used to specify a form to +edit when filling out the commit log. The +@file{rcsinfo} file has a syntax similar to the +@file{editinfo}, @file{commitinfo} and @file{loginfo} +files. @xref{syntax}. Unlike the other files the second +part is @emph{not} a command-line template. Instead, +the part after the regular expression should be a full pathname to +a file containing the log message template. + +If the repository name does not match any of the +regular expressions in this file, the @samp{DEFAULT} +line is used, if it is specified. + +If the name @samp{ALL} appears as a regular expression +it is always used in addition to the first matching +regular expression or @samp{DEFAULT}. + +The log message template will be used as a default log +message. If you specify a log message with @samp{cvs +commit -m @var{message}} or @samp{cvs commit -f +@var{file}} that log message will override the +template. + +@xref{editinfo example}, for an example @file{rcsinfo} +file. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node cvsignore +@appendixsec Ignoring files via cvsignore +@cindex Cvsignore, global +@cindex Global cvsignore +@cindex Ignoring files +@c -- This chapter should maybe be moved to the +@c tutorial part of the manual? + +There are certain file names that frequently occur +inside your working copy, but that you don't want to +put under @sc{cvs} control. Examples are all the object +files that you get while you compile your sources. +Normally, when you run @samp{cvs update}, it prints a +line for each file it encounters that it doesn't know +about (@pxref{update output}). + +@sc{cvs} has a list of files (or sh(1) file name patterns) +that it should ignore while running @code{update}, +@code{import} and @code{release}. +@c -- Are those the only three commands affected? +This list is constructed in the following way. + +@itemize @bullet +@item +The list is initialized to the following file name +patterns: + +@cindex Ignored files +@cindex Automatically ignored files +@example + RCSLOG RCS SCCS + CVS* cvslog.* + tags TAGS + .make.state .nse_depinfo + *~ #* .#* ,* + *.old *.bak *.BAK *.orig *.rej .del-* + *.a *.o *.so *.Z *.elc *.ln + core +@end example + +@item +The per-repository list in +@file{$CVSROOT/CVSROOT/cvsignore} is appended to +the list, if that file exists. + +@item +The per-user list in @file{.cvsignore} in your home +directory is appended to the list, if it exists. + +@item +Any entries in the environment variable +@code{$CVSIGNORE} is appended to the list. + +@item +Any @samp{-I} options given to @sc{cvs} is appended. + +@item +As @sc{cvs} traverses through your directories, the contents +of any @file{.cvsignore} will be appended to the list. +The patterns found in @file{.cvsignore} are only valid +for the directory that contains them, not for +any sub-directories. +@end itemize + +In any of the 5 places listed above, a single +exclamation mark (@samp{!}) clears the ignore list. +This can be used if you want to store any file which +normally is ignored by @sc{cvs}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node history file +@appendixsec The history file +@cindex History file +@cindex Log information, saving + +The file @file{$CVSROOT/CVSROOT/history} is used +to log information for the @code{history} command +(@pxref{history}). This file must be created to turn +on logging. This is done automatically if the +@code{cvsinit} script is used to set up the repository. + +The file format of the @file{history} file is +unfortunately not yet documented anywhere, but it is +fairly easy to understand most of it. +@c -- document it here? + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Setting up +@appendixsec Setting up the repository +@cindex Repository, setting up +@cindex Creating a repository +@cindex Setting up a repository + +When you install @sc{cvs} for the first time, you should +follow the instructions in the @file{INSTALL} file to +set up the repository. + +If you want to set up another repository, the easiest +way to get a reasonable set of working administrative +files is to get the source to @sc{cvs}, and run the +@code{cvsinit} shell script. It will set up an empty +repository in the directory defined by the environment +variable @code{$CVSROOT}. (@code{cvsinit} is careful to +never overwrite any existing files in the repository, +so no harm is done if you run @code{cvsinit} on +an already set-up repository.) + +@c --------------------------------------------------------------------- +@node Environment variables +@appendix All environment variables which affect CVS +@cindex Environment variables +@cindex Reference manual for variables + +This is a complete list of all environment variables +that affect @sc{cvs}. + +@table @code +@cindex CVSIGNORE +@item $CVSIGNORE +A whitespace-separated list of file name patterns that +@sc{cvs} should ignore. @xref{cvsignore}. + +@cindex CVSREAD +@item $CVSREAD +If this is set, @code{checkout} and @code{update} will +try hard to make the files in your working directory +read-only. When this is not set, the default behavior +is to permit modification of your working files. + +@cindex CVSROOT +@item $CVSROOT +Should contain the full pathname to the root of the @sc{cvs} +source repository (where the @sc{rcs} history files are +kept). This information must be available to @sc{cvs} for +most commands to execute; if @code{$CVSROOT} is not set, +or if you wish to override it for one invocation, you +can supply it on the command line: @samp{cvs -d cvsroot +cvs_command@dots{}} You may not need to set +@code{$CVSROOT} if your @sc{cvs} binary has the right path +compiled in. + +If your site has several repositories, you must be +careful to set @code{$CVSROOT} to the appropriate one +when you use @sc{cvs}, even if you just run @samp{cvs +update} inside an already checked-out module. Future +releases of @sc{cvs} will probably store information about +which repository the module came from inside the +@file{CVS} directory, but version 1.3 relies totally on +@code{$CVSROOT}. + +@cindex EDITOR +@cindex CVSEDITOR +@item $EDITOR +@itemx $CVSEDITOR +Specifies the program to use for recording log messages +during commit. If not set, the default is +@samp{/usr/ucb/vi}. @code{$CVSEDITOR} overrides +@code{$EDITOR}. @code{$CVSEDITOR} does not exist in +@sc{cvs} 1.3, but the next release will probably +include it. + +@cindex PATH +@item $PATH +If @code{$RCSBIN} is not set, and no path is compiled +into @sc{cvs}, it will use @code{$PATH} to try to find all +programs it uses. + +@cindex RCSBIN +@item $RCSBIN +Specifies the full pathname of the location of @sc{rcs} programs, +such as co(1) and ci(1). If not set, a compiled-in +value is used, or your @code{$PATH} is searched. +@end table + +@sc{cvs} is a front-end to @sc{rcs}. The following environment +variables affect @sc{rcs}: + +@table @code +@cindex LOGNAME +@item $LOGNAME +@cindex USER +@itemx $USER +If set, they affect who @sc{rcs} thinks you are. If you +have trouble checking in files it might be because your +login name differs from the setting of e.g. +@code{$LOGNAME}. + +@cindex RCSINIT +@item $RCSINIT +Options prepended to the argument list, separated by +spaces. A backslash escapes spaces within an option. +The @code{$RCSINIT} options are prepended to the +argument lists of most @sc{rcs} commands. + +@cindex TMPDIR +@item $TMPDIR +@cindex TMP +@itemx $TMP +@cindex TEMP +@itemx $TEMP +Name of the temporary directory. The environment +variables are inspected in the order they appear above +and the first value found is taken; if none of them are +set, a host-dependent default is used, typically +@file{/tmp}. +@end table + +@c --------------------------------------------------------------------- +@node Troubleshooting +@appendix Troubleshooting + +@menu +* Magic branch numbers:: Magic branch numbers +@end menu + +@ignore +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@c @node Bad administrative files +@appendixsec Bad administrative files + +@c -- Give hints on how to fix them +@end ignore + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Magic branch numbers +@appendixsec Magic branch numbers + +Externally, branch numbers consist of an odd number of +dot-separated decimal integers. @xref{Revision +numbers}. That is not the whole truth, however. For +efficiency reasons @sc{cvs} sometimes inserts an extra 0 +in the second rightmost position (1.2.3 becomes +1.2.0.3, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so +on). + +@sc{cvs} does a pretty good job at hiding these so +called magic branches, but in at least four places the +hiding is incomplete. + +@itemize @bullet +@item +The magic branch can appear in the output from +@code{cvs status} in vanilla @sc{cvs} 1.3. This is +fixed in @sc{cvs} 1.3-s2. + +@item +The magic branch number appears in the output from +@code{cvs log}. This is much harder to fix, since +@code{cvs log} runs @code{rlog} (which is part of the +@sc{rcs} distribution), and modifying @code{rlog} to +know about magic branches would probably break someone's +habits (if they use branch 0 for their own purposes). + +@item +You cannot specify a symbolic branch name to @code{cvs log}. + +@item +You cannot specify a symbolic branch name to @code{cvs +admin}. + +@end itemize + +You can use the @code{admin} command to reassign a +symbolic name to a branch the way @sc{rcs} expects it +to be. If @code{R4patches} is assigned to the branch +1.4.2 (magic branch number 1.4.0.2) in file +@file{numbers.c} you can do this: + +@example +$ cvs admin -NR4patches:1.4.2 numbers.c +@end example + +It only works if at least one revision is already +committed on the branch. Be very careful so that you +do not assign the tag to the wrong number. (There is +no way to see how the tag was assigned yesterday). + +@c --------------------------------------------------------------------- +@node Copying +@appendix GNU GENERAL PUBLIC LICENSE +@c @include gpl.texinfo + +@c --------------------------------------------------------------------- +@node Index +@unnumbered Index +@cindex Index + +If you cannot find what you are looking for here write +to <@t{ceder@@signum.se}> so that an entry can be added +to the next release of this manual. + +@printindex cp + +@summarycontents + +@contents + +@bye + +Local Variables: +fill-column: 55 +End: |
