diff options
Diffstat (limited to 'contrib/cvs/doc')
| -rw-r--r-- | contrib/cvs/doc/ChangeLog | 569 | ||||
| -rw-r--r-- | contrib/cvs/doc/ChangeLog.fsf | 38 | ||||
| -rw-r--r-- | contrib/cvs/doc/Makefile.in | 203 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs-paper.ms | 1073 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvs.texinfo | 7738 | ||||
| -rw-r--r-- | contrib/cvs/doc/cvsclient.texi | 824 |
6 files changed, 10445 insertions, 0 deletions
diff --git a/contrib/cvs/doc/ChangeLog b/contrib/cvs/doc/ChangeLog new file mode 100644 index 0000000000000..01efb1a2ef796 --- /dev/null +++ b/contrib/cvs/doc/ChangeLog @@ -0,0 +1,569 @@ +Wed May 1 15:38:26 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Tags): Document un-revision of all-uppercase tag + names. + +Wed Apr 24 08:41:51 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication security): Rewrite sentence + on complex and unknown security bugs to clarify that it is + referring to people who have been give access to cvs, not to holes + in the authentication method (which is relatively simple). + +Tue Apr 23 09:31:29 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): Talk about what -m does (and does not + do). Other minor edits. + +Wed Apr 17 15:27:03 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (rcsinfo): Rewrite paragraph concerning remote CVS. + * cvsclient.texi (Responses): Document Template response. + +Sun Apr 14 16:01:39 1996 Karl Fogel <kfogel@floss.red-bean.com> + + * .cvsignore: added CVSvn.texi. + +Wed Apr 10 16:56:21 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (~/.cvsrc): Mention setting global options with "cvs". + + * cvs.texinfo (release): Change "modules" to "directories". + Release does not take module names as arguments. + + * cvs.texinfo (Creating a branch): Add comments about how we + should better document tagging the branchpoint. + +Tue Apr 9 19:59:45 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Top): Use @value{CVSVN}, not a vague refenece to 1.4. + + * cvs.texinfo (From other version control systems): New node. + +Mon Apr 8 15:59:37 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Connection and Authentication): Revise kerberos + and pserver sections to reflect the fact that port 2401 is now + officially registered. + +Thu Mar 28 09:51:13 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (History browsing): Reinstate this node. Try to get + it into some minimally useful state (it still needs a lot of + work). + (annotate): New node, subnode of History browing. + + * cvsclient.texi (Requests): Add annotate request. + +Tue Mar 26 08:46:39 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: In various examples, change tag names to avoid tag + names reserved to CVS. + + * cvs.texinfo (Tags): Document what is a valid tag name. + + * cvs.texinfo (Substitution modes): Try to describe how the + various keyword expansion settings interract. + (Binary files): Suggest cvs update -A, not removing file and then + updating it, to get effect of new keyword expansion options. + + * cvs.texinfo (admin options): Mention CVS's use of `dead' state. + +Thu Mar 21 08:25:17 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Environment variables): Expand introduction to RCS + environment variables. Expand and correct CVS_SERVER_SLEEP. + + * cvs.texinfo (Environment variables): Remove POSIXLY_CORRECT; cvs + requires options to precede arguments regardless of it. + +Thu Mar 21 08:18:42 1996 Norbert Kiesel <nk@col.sw-ley.de> + + * cvs.texinfo: Remove paragrahps about a forthcoming CVS + newsgroup and about sending patches to think.com. + (Environment): Document some more (all?) used environment + variables. + +Wed Mar 20 09:44:21 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Introduction): New node. + * Makefile.in: Add cruft to reflect fact that cvsclient.texi now + uses CVSvn.texi. + +Mon Mar 18 14:43:53 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Add Case request. + +Wed Mar 13 16:01:47 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Connection and Authentication): New node. + + * cvsclient.texi (Requests): Expand discussion of Root a bit. + + * cvs.texinfo (Setting up): Don't refer to INSTALL file; revise to + reflect some information which had been in the INSTALL file. + + * cvs.texinfo (history file): Update to reflect cvsinit -> cvs + init. Adjust discussion of whether history file format is + documented. + (Setting up): Update to reflect cvsinit -> cvs init. + + * cvsclient.texi (Requests): Document init request. + +Thu Feb 29 10:08:31 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (loginfo example): Adjust example to reflect the way + that CVS actually works. Add comments questioning whether that is + the best behavior. + + * cvs.texinfo (cvsignore): Document additions to default ignore list. + +Mon Feb 26 13:48:01 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Filenames): New node, documents / vs \, etc. + +Wed Feb 24 1996 Marcus Daniels <marcus@sayre.sysc.pdx.edu> + + * cvs.texinfo (Password authentication server): Mention + support for imaginary usernames. + +Thu Feb 15 16:34:56 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Variables): Add new internal variable $USER. + +Wed Feb 14 22:52:58 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (export, admin): Document -k option to cvs export. + + * cvs.texinfo (admin options): Mention using -l, -u, -L, and -U in + conjunction with rcslock.pl. + +Mon Feb 12 16:38:41 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Remove references to mkmodules. + +Sun Feb 11 12:31:36 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi: Add Set request. + + * cvs.texinfo (Variables): Rewrite to reflect user variables + replacing environment variables; motivate the discussion better. + (Global options): Add -s option. + +Sat Feb 10 11:18:37 1996 Jim Blandy <jimb@totoro.cyclic.com> + + * cvs.texinfo (Variables): Fix @table commands. + +Fri Feb 9 17:31:18 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Variables): New node. + + * Makefile.in (CVSvn.texi): New rule. + (OBJDIR_DISTFILES): Add CVSvn.texi. + (cvs.dvi,cvs.info): Add cruft to deal with it being in build dir + or srcdir. + * cvs.texinfo: Include CVSvn.texi and use the version number from + it instead of a hardcoded version number and date. + +Thu Feb 1 13:28:03 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Sticky tags): Expand so it really documents the + features it is talking about rather than referring to "Appendix + A". Add example of how to restore the old version of a dead + file. In various other parts of the manual refer to this node, in + some cases deleting duplicative text. In the case of cvs admin + -b, mention vendor branch usage. + (Removing files): Discuss removing files (in user-visible terms, + not in terms of the Attic and such). + (remove): Remove node; merge contents into Removing files. + +Tue Jan 30 17:52:06 1996 Jim Blandy <jimb@totoro.cyclic.com> + + * cvs.texinfo: Tweak @top node, to make file compatible with both + makeinfo and texinfo-format-buffer. Perhaps we should fix the + formatters to agree on what constitutes valid texinfo. + +Mon Jan 29 16:38:33 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requirements): New node, to talk about required + versus optional parts of the protocol. + +Sun Jan 28 09:00:34 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Modes): Add discussion what what the mode really + means (across diverse operating systems). + +Tue Jan 23 12:54:57 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Per mail from Per Cederqvist, change author to "Per + Cederqvist et al". Also remove sentence about Signum shipping + hardcopy manuals and add information on Cyclic. Change version + number to 1.6.87. + +Fri Jan 12 15:29:39 1996 Vince Demarco <vdemarco@bou.shl.com> + + * cvs.texinfo: Fix the documentation for the com/uncom change + to wrap/unwrap. make everything consistant + +Wed Jan 10 16:11:54 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Concurrency): Add index entries; minor clarification. + +Tue Jan 9 16:03:39 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Getting Notified): Document users file. + + * cvs.texinfo (cvsignore): Add *.obj to list of ignored files. + +Wed Jan 3 17:01:58 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (import): Adjust list of ignored files to match + recent change to CVS (CVS* -> CVS CVS.adm). Consolidate + discussion of ignored files in one place (with xrefs from others). + + * cvsclient.texi: Remove How To node. It was out of date + (again!), and I am getting sick of trying to update it (internals + documentation should be in the comments, where it at least has a + fighting chance of staying up to date). + (Protocol): Say what \n and \t mean in this document. + +Tue Jan 2 23:39:32 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Wrappers): Change comb/uncom to wrap/unwrap. + +Mon Jan 2 23:00:00 1996 Vince Demarco <vdemarco@bou.shl.com> + + * cvs.texinfo: update the Wrappers documentation so it isn't + so NEXTSTEP centric. The wrappers code has alot of other + general uses. The new version of the documentation tryes + to show that to the reader. + +Mon Jan 1 13:09:39 1996 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Clarify that Module-expansion is not + suitable for passing to co. + +Sun Dec 31 10:53:47 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Password authentication server): Suggest specifying + -b in inetd.conf. + + * cvs.texinfo (Password authentication): Variety of cleanups and + minor fixes, including shorter node names. + +Sun Dec 24 02:37:51 1995 Karl Fogel <kfogel@floss.cyclic.com> + + * cvs.texinfo (Using the client with password authentication): + tixed fypos. + +Sun Dec 24 00:00:16 1995 Karl Fogel <kfogel@floss.cyclic.com> + + * cvs.texinfo (Remote repositories): use @code{rsh} most places, + because it is the name of a program, and because I am a pedant. + Refer to new node "Password authenticated". + (Password authenticated): new node. + (Setting up the server for password authentication): new node. + (Using the client with password authentication): new node. + (Security considerations with password authentication): new node. + + These are all really long node names, but it seems necessary that + they be descriptive in case they're referenced elsewhere. If you + can think of a way out of this, please change them. + +Thu Dec 21 12:09:34 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Requests): Add Questionable. Revise + documentation of export and update to explain role of -I option. + +Tue Dec 19 16:44:18 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Update binary files info for -kb. + +Mon Dec 11 12:20:55 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Responses): Add Notified and Mode. + (Requests): Add Notify, noop, watch-on, watch-off, watch-add, + watch-remove, watchers, and editors. + * cvs.texinfo (Watches): New node, to describe new developer + communication features. + +Thu Nov 23 08:59:09 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (admin options): In saying that cvs admin -o is not + such a good way to undo a change, refer to the section which + describes the preferred way. + +Thu Nov 13 16:39:03 1995 Fred Fish <fnf@cygnus.com> + + * Makefile.in: Remove extraneous tab from empty line. + +Mon Nov 13 15:00:26 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Concurrency): New node, to describe user-visible + behaviors associated with cvs locks. + + * cvs.texinfo (Remote repositories): Add more details of how to + set things up (with rsh and kerberos). + +Thu Nov 9 11:41:37 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Remove -Q and -q options from command synopses. + +Wed Nov 8 09:38:00 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (Notes): Revise paragraph on server memory use + problem. + +Tue Nov 7 16:26:39 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Document merging more than once from a branch; + miscellaneous cleanups. + +Mon Oct 30 13:12:53 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (modules): Document -e. + +Thu Oct 26 11:15:40 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Tags): Update "version" vs. "revision" for CVS 1.5. + (Index,BUGS): Change bug reporting address from Per Cederqvist to + bug-cvs@prep.ai.mit.edu. + +Wed Oct 25 15:37:05 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Miscellaneous minor changes (clean up CVS/Root + stuff, don't say release requires a module entry, etc.). + +Tue Oct 24 11:01:22 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: More precisely describe scope of document. + * cvsclient.texi: Describe scope of document + +Thu Oct 12 11:25:40 1995 Karl Fogel <kfogel@totoro.cyclic.com> + + * cvs.texinfo: cover page now refers to CVS 1.6, and "last + updated" date has been upped to today. + +Wed Oct 11 22:30:10 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * Makefile.in (info): Look for *.info* either in build dir or in + srcdir. + +Mon Oct 2 17:10:49 1995 Norbert Kiesel <nk@col.sw-ley.de> + + * cvs.texinfo (admin): Describe usage of CVS_ADMIN_GROUP to + restrict usage of admin. + +Fri Oct 6 21:17:50 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (~/.cvsrc): Document change to command name matching. + +Thu Oct 5 18:03:41 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * Makefile.in (install-info): Add comment about srcdir. + +Wed Sep 13 12:45:53 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Moving files): Rewrite "Outside" node to clarify + that history is still there and describe how to get it. Assorted + cleanups. + +Tue Sep 12 19:02:47 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo (Removing files): Remove section on limitations + which are gone now that we have death support. + +Wed Aug 30 12:32:29 1995 Karl Fogel <kfogel@floss.cyclic.com> + + * cvs.texinfo (Remote Repositories): new node, referred to from + `Basics' and `Repository'. + (Repository): documented new `-d' vs. `$CVSROOT' vs. `CVS/Root' + behavior. + (commitinfo): document client/server-case behavior. + (editinfo): document client/server-case behavior. + (loginfo): document client/server-case behavior. + (rcsinfo): document client/server-case behavior. + +Mon Aug 21 00:23:45 1995 Jim Kingdon <kingdon@harvey.cyclic.com> + + * cvsclient.texi (How To): The way to force rsh is to set + CVS_CLIENT_PORT to -1, not to some bogus value. + +Tue Aug 15 17:12:08 1995 Karl Fogel <kfogel@floss.cyclic.com> + + * cvs.texinfo + (Basic concepts): talk about remote repositories. + (Repository): same. + +Mon Jul 24 19:09:12 1995 James Kingdon <kingdon@harvey.cyclic.com> + + * cvs.texinfo: Remove references to -q and -Q command options. + +Fri Jul 21 10:33:07 1995 Vince DeMarco <vdemarco@bou.shl.com> + + * cvs.texinfo: Changes for CVSEDITOR and wrappers. + +Thu Jul 13 23:04:12 CDT 1995 Jim Meyering (meyering@comco.com) + + * Makefile.in (cvs-paper.ps): *Never* redirect output directly to + the target (usu $@) of a rule. Instead, redirect to a temporary + file, and then move that temporary to the target. I chose to + name temporary files $@-t. Remember to be careful that the length + of the temporary file name not exceed the 14-character limit. + +Sun Jul 9 19:03:00 1995 Greg A. Woods <woods@most.weird.com> + + * doc/cvs.texinfo: + - document '-q' for 'cvs status' + - correction to regexp use in *info files + - correction to use of 'cvsinit' script + (from previous local changes) + +Tue Jun 20 18:57:55 1995 James Kingdon <kingdon@harvey.cyclic.com> + + * Makefile.in (dist-dir): Depend on $(OBJDIR_DISTFILES). + +Fri Jun 16 21:56:16 1995 Karl Fogel <kfogel@cyclic.com> + and Jim Meyering <meyering@comco.com> + + * update.c (update_file_proc): If noexec, just write 'C', don't merge. + +Fri Jun 16 07:56:04 1995 Jim Kingdon (kingdon@cyclic.com) + + * cvs-paper.ps: Added. + +Sat May 27 08:46:00 1995 Jim Meyering (meyering@comco.com) + + * Makefile.in (Makefile): Regenerate only Makefile in current + directory when Makefile.in is out of date. Depend on ../config.status. + +Sat May 27 08:08:18 1995 Jim Meyering (meyering@comco.com) + + * doc/Makefile.in (realclean): Remove more postscript and info files. + +Fri Apr 28 22:44:06 1995 Jim Blandy <jimb@totoro.bio.indiana.edu> + + * Makefile.in (DISTFILES): Updated. + (doc): Depend on cvsclient.ps too. + (cvs.aux, cvsclient.aux): Add target. + (cvsclient.dvi): Don't nuke the aux file. They're small and + helpful. + (cvsclient.ps): New target. + (dist-dir): Renamed from dist; changed to work with DISTDIR + variable from parent. + +Sun Apr 23 22:13:18 1995 Noel Cragg <noel@vo.com> + + * Makefile: Added more files to the `clean' target. + * .cvsignore: Added the same files. + +Mon Nov 28 10:22:46 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Notes): Remove item about commit options; now + fixed. Rewrite paragraph about server memory usage. + + * cvsclient.texi (Responses): Add Set-checkin-prog and + Set-update-prog. + (Requests): Add Checkin-prog and Update-prog. + * cvsclient.texi (TODO): Remove last item (it is fixed) and node. + +Fri Nov 18 16:51:36 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Requests): Add Max-dotdot. + +Thu Nov 3 07:04:24 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Add Directory request. + (TODO): Remove item about renaming directories. + (Protocol): Change @subheading to @node/@section. + +Fri Oct 28 07:51:13 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Add expand-module request and + Module-expansion response. + (Protocol Notes, TODO): Remove items about cvs co funkiness. + +Wed Oct 12 19:49:36 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Add Copy-file response. + + * cvsclient.texi (How To): Correct item about where declaration + of cvs commands go. + + * cvsclient.texi (Protocol): Add new commands. Merge description + of how commands work which was duplicated among the various + commands. Formatting cleanups. + (TODO): Remove item about bad error message on checking in a + nonexistent file; this works now (presumably fixed by the + Unchanged stuff). + (Notes): Remove thing about trying unsupported commands via NFS, + rdist, etc. Also remove item about some commands not being + supported. There are no unsupported commands anymore. + +Tue Sep 13 13:28:52 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Document New-entry response. + +Mon Sep 12 06:35:15 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Clarify that checksum is of patched + file, not patch itself. Fix typo (valid-requests -> Valid-requests). + + * cvsclient.texi (Protocol): Document Sticky request and + Set-sticky and Clear-sticky responses. + (Notes): Remove sticky tags from todo list. + +Thu Sep 8 14:23:58 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Document Static-directory requests + and Set-static-directory and Clear-static-directory responses. + (Notes): Remove Entries.Static support from todo list. + + * cvsclient.texi (Protocol): Document Unchanged and UseUnchanged + requests. Update documentation of Entry and Lost accordingly. + +Mon Aug 22 14:08:21 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Goals): Remove mention of rsh. + (Protocol Notes, TODO): Remove compression item. + (Protocol): Document "status" request. + (TODO): Remove suggestion to add "cvs status". + +Tue Jul 19 10:02:53 1994 Ian Lance Taylor (ian@sanguine.cygnus.com) + + * Makefile.in (install-info): Do not depend upon installdirs. + +Fri Jul 15 12:56:53 1994 Ian Lance Taylor (ian@sanguine.cygnus.com) + + * Makefile.in (all): Do not depend upon info. + (install): Do not depend upon install-info. + +Thu Jul 7 20:43:12 1994 Ian Lance Taylor (ian@sanguine.cygnus.com) + + * cvsclient.texi (Protocol): Add Checksum response. + +Thu Jun 30 15:16:50 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Add Global_option request. + +Wed Jun 29 14:09:42 1994 Ian Lance Taylor (ian@sanguine.cygnus.com) + + * cvsclient.texi: Describe sending patches, including the dummy + update-patches request and the Patched response. Mention Kerberos + authentication using ``cvs kserver''. Some other minor changes. + +Tue Jun 28 15:21:06 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol Notes): Remove note about sending diffs + in Updated; Ian did it. Remove note about adding encryption to rsh. + +Sat May 7 10:44:30 1994 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi (Protocol): Document Modified without Entry. Add + `add' and `remove' and `Remove-entry'. Formatting cleanups. + +Tue Apr 19 01:29:04 1994 John Gilmore (gnu@cygnus.com) + + * cvsclient.texi: New node How To; cleanups throughout. + * Makefile.in: Add dependencies on cvsclient.texi. + diff --git a/contrib/cvs/doc/ChangeLog.fsf b/contrib/cvs/doc/ChangeLog.fsf new file mode 100644 index 0000000000000..2f140999caf3d --- /dev/null +++ b/contrib/cvs/doc/ChangeLog.fsf @@ -0,0 +1,38 @@ +Thu Sep 15 14:19:50 1994 david d `zoo' zuhn <zoo@monad.armadillo.com> + + * Makefile.in: define TEXI2DVI + +Sat Dec 18 01:23:39 1993 david d zuhn (zoo@monad.armadillo.com) + + * cvs.texinfo: document -k SUBST options to 'cvs import'; + regularize use @sc{cvs} + + * Makefile.in (VPATH): don't use $(srcdir), but @srcdir@ instead + (install-info): grab all info files, not just *.info + +Mon Oct 11 16:23:54 1993 Jim Kingdon (kingdon@lioth.cygnus.com) + + * cvsclient.texi: New node TODO; various other changes. + +Wed Feb 26 18:04:40 1992 K. Richard Pixley (rich@cygnus.com) + + * Makefile.in, configure.in: removed traces of namesubdir, + -subdirs, $(subdir), $(unsubdir), some rcs triggers. Forced + copyrights to '92, changed some from Cygnus to FSF. + +Tue Dec 10 04:07:10 1991 K. Richard Pixley (rich at rtl.cygnus.com) + + * Makefile.in: infodir belongs in datadir. + +Thu Dec 5 22:46:01 1991 K. Richard Pixley (rich at rtl.cygnus.com) + + * Makefile.in: idestdir and ddestdir go away. Added copyrights + and shift gpl to v2. Added ChangeLog if it didn't exist. docdir + and mandir now keyed off datadir by default. + +Wed Nov 27 02:45:18 1991 K. Richard Pixley (rich at sendai) + + * brought Makefile.in's up to standards.text. + + * fresh changelog. + diff --git a/contrib/cvs/doc/Makefile.in b/contrib/cvs/doc/Makefile.in new file mode 100644 index 0000000000000..11c70519a3b08 --- /dev/null +++ b/contrib/cvs/doc/Makefile.in @@ -0,0 +1,203 @@ +# Makefile for GNU CVS documentation. +# Do not use this makefile directly, but only from `../Makefile'. +# Copyright (C) 1986, 1988-1990 Free Software Foundation, Inc. + +# 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 2, 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. + +# $CVSid: @(#)Makefile.in 1.8 94/10/22 $ + +SHELL = /bin/sh + +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ + +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +infodir = $(prefix)/info + +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ + +DISTFILES = \ + .cvsignore ChangeLog ChangeLog.fsf Makefile.in \ + cvs-paper.ms cvs-paper.ps \ + cvs.texinfo \ + cvsclient.texi + +OBJDIR_DISTFILES = cvs.ps cvs.info cvs.aux \ + cvsclient.ps cvsclient.info cvsclient.aux CVSvn.texi + +# these are part of the texinfo distribution +MAKEINFO=makeinfo +TEXI2DVI = texi2dvi + +# where to find texinfo; +TEXIDIR=${gdbdir}/../texinfo + +SET_TEXINPUTS = TEXINPUTS=.:$(srcdir):$$TEXINPUTS + +# Don Knuth's TeX formatter +TEX = tex + +# auxiliary program for sorting Texinfo indices +TEXINDEX = texindex + +DVIPS = dvips +DVIPSFLAGS = + +ROFF = groff + +# CYGNUS LOCAL: all does not depend upon info +all: +.PHONY: all + +# CYGNUS LOCAL: install does not depend on install-info +install: all +.PHONY: install + +doc: cvs.ps cvs-paper.ps cvsclient.ps + +info: cvs.info cvsclient.info + +cvs.info: cvs.texinfo CVSvn.texi + if [ ! -f ./CVSvn.texi ]; then \ + ln -s $(srcdir)/CVSvn.texi . || \ + ln $(srcdir)/CVSvn.texi . || \ + cp $(srcdir)/CVSvn.texi . ; else true; fi + $(MAKEINFO) $(srcdir)/cvs.texinfo -o cvs.info + +cvsclient.info: cvsclient.texi CVSvn.texi + if [ ! -f ./CVSvn.texi ]; then \ + ln -s $(srcdir)/CVSvn.texi . || \ + ln $(srcdir)/CVSvn.texi . || \ + cp $(srcdir)/CVSvn.texi . ; else true; fi + $(MAKEINFO) $(srcdir)/cvsclient.texi -o cvsclient.info + +# Version of the protocol suitable for emailing +cvsclient.txt: cvsclient.texi CVSvn.texi + if [ ! -f ./CVSvn.texi ]; then \ + ln -s $(srcdir)/CVSvn.texi . || \ + ln $(srcdir)/CVSvn.texi . || \ + cp $(srcdir)/CVSvn.texi . ; else true; fi + $(MAKEINFO) $(srcdir)/cvsclient.texi --no-headers -o cvsclient.txt + +# If the user gets a distribution (which contains *.info), unpacks +# it, and builds it in a seperate build dir, then *.info* are in srcdir. +# If the user builds *.info (e.g. after editing *.texi), then *.info* are +# in the build dir. +install-info: info + test -f cvs.info || cd $(srcdir); \ + for i in *.info* ; do \ + $(INSTALL_DATA) $$i $(infodir)/$$i ; \ + done + +installdirs: + $(SHELL) $(top_srcdir)/mkinstalldirs $(infodir) +.PHONY: installdirs + +dvi: cvs.dvi cvsclient.dvi + +CVSvn.texi: $(top_srcdir)/src/version.c + echo "@set CVSVN `sed < $(top_srcdir)/src/version.c \ + -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ + -e q`" >CVSvn.new + mv CVSvn.new CVSvn.texi + +cvs.dvi cvs.aux: cvs.texinfo CVSvn.texi + if [ ! -f ./CVSvn.texi ]; then \ + ln -s $(srcdir)/CVSvn.texi . || \ + ln $(srcdir)/CVSvn.texi . || \ + cp $(srcdir)/CVSvn.texi . ; else true; fi + $(TEXI2DVI) $(srcdir)/cvs.texinfo + +cvsclient.dvi cvsclient.aux: cvsclient.texi CVSvn.texi + if [ ! -f ./CVSvn.texi ]; then \ + ln -s $(srcdir)/CVSvn.texi . || \ + ln $(srcdir)/CVSvn.texi . || \ + cp $(srcdir)/CVSvn.texi . ; else true; fi + $(SET_TEXINPUTS) $(TEX) cvsclient.texi + $(SET_TEXINPUTS) $(TEX) cvsclient.texi + $(TEXINDEX) cvsclient.?? + $(SET_TEXINPUTS) $(TEX) cvsclient.texi + rm -f cvsclient.?? cvsclient.log cvsclient.toc cvsclient.??s + +cvs.ps: cvs.dvi + $(DVIPS) $(DVIPSFLAGS) cvs.dvi -o cvs.ps + +cvs-paper.ps: cvs-paper.ms + $(ROFF) -t -p -ms -Tps $(srcdir)/cvs-paper.ms > $@-t + mv $@-t $@ + +cvsclient.ps: cvsclient.dvi + $(DVIPS) $(DVIPSFLAGS) cvsclient.dvi -o cvsclient.ps + +tags: +.PHONY: tags + +TAGS: +.PHONY: TAGS + +ls: + @echo $(DISTFILES) +.PHONY: ls + +clean: + rm -f *.o core + rm -f cvs.cp cvs.fn cvs.ky cvs.pg cvs.tp cvs.vr + rm -f cvs.cps cvs.fns cvs.kys cvs.pgs cvs.tps cvs.vrs + rm -f cvs.aux cvs.dvi cvs.log cvs.toc + rm -f cvsclient.cp cvsclient.fn cvsclient.ky cvsclient.pg + rm -f cvsclient.tp cvsclient.vr cvsclient.cps cvsclient.fns + rm -f cvsclient.kys cvsclient.pgs cvsclient.tps cvsclient.vrs + rm -f cvsclient.aux cvsclient.dvi cvsclient.log cvsclient.toc + +.PHONY: clean + +distclean: clean + rm -f Makefile +.PHONY: distclean + +realclean: distclean + rm -f cvs.info* cvs.ps cvs-paper.ps cvsclient.info* cvsclient.ps +.PHONY: realclean + +dist-dir: $(DISTFILES) $(OBJDIR_DISTFILES) + mkdir ${DISTDIR} + for i in ${DISTFILES}; do \ + ln $(srcdir)/$${i} ${DISTDIR}; \ + done + ln ${OBJDIR_DISTFILES} ${DISTDIR} + if [ -f cvs.info-1 ]; \ + then ln -f cvs.info-* ${DISTDIR}; \ + else : Pacify Ultrix sh; \ + fi + if [ -f cvsclient.info-1 ]; \ + then ln -f cvsclient.info-* ${DISTDIR}; \ + else : Pacify Ultrix sh; \ + fi +.PHONY: dist-dir + +subdir = doc +Makefile: ../config.status Makefile.in + cd .. && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= ./config.status + +#../config.status: ../configure +# cd .. ; $(SHELL) config.status --recheck + +#../configure: ../configure.in +# cd $(top_srcdir) ; autoconf diff --git a/contrib/cvs/doc/cvs-paper.ms b/contrib/cvs/doc/cvs-paper.ms new file mode 100644 index 0000000000000..567179b393f84 --- /dev/null +++ b/contrib/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/contrib/cvs/doc/cvs.texinfo b/contrib/cvs/doc/cvs.texinfo new file mode 100644 index 0000000000000..29bc5f350601d --- /dev/null +++ b/contrib/cvs/doc/cvs.texinfo @@ -0,0 +1,7738 @@ +\input texinfo @c -*-texinfo-*- +@comment cvs.texinfo,v 1.6 1995/10/12 23:39:26 kfogel 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 +@include CVSvn.texi +@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 for @sc{cvs} @value{CVSVN} +@comment -release- +@sp 3 +@center Per Cederqvist et al + +@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 +@c Note: there is a space after that @top command. +@c The texinfo-format-buffer Emacs function and +@c the makeinfo shell command disagree on what arguments +@c @top takes; @top followed by a single space is +@c something they can both cope with. + +This info manual describes how to use and administer +@sc{cvs} version @value{CVSVN}. +@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 +* History browsing:: Viewing the history of files in various ways +* Keyword substitution:: CVS can include the revision inside the file +* Binary files:: CVS can handle binary files +* 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. 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 + +Another company selling support for @sc{cvs} is Cyclic +Software, web: @code{http://www.cyclic.com/}, email: +@code{info@@cyclic.com}. + +@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 known to have room for improvement. +Here is a list of known deficiencies: + +@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{bug-cvs@@prep.ai.mit.edu}. +@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. + + +@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} or +@file{user@@remotehost:/usr/local/cvsroot}) which is +populated with a hierarchy of files and directories. +(@pxref{Remote repositories} for information about +keeping the repository on a remote machine.) + +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. When you've finished a set of +changes, you check (or @dfn{commit}) them back into the +repository. + +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 + + +There are a couple of different ways to tell @sc{cvs} +where to find the repository. You can name the +repository on the command line explicitly, with the +@code{-d} (for "directory") option: + +@example +cvs -d /usr/local/cvsroot checkout yoyodyne/tc +@end example + + Or you can set the @code{$CVSROOT} environment +variable to an absolute path to the root of the +repository, @file{/usr/local/cvsroot} in this example. +To set @code{$CVSROOT}, 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 + + A repository specified with @code{-d} will +override the @code{$CVSROOT} environment variable. +Once you've checked a working copy out from the +repository, it will remember where its repository is +(the information is recorded in the +@file{CVS/Root} file in the working copy). + +The @code{-d} option and the @file{CVS/Root} file +both override the @code{$CVSROOT} environment variable; +however, @sc{CVS} will complain if the @file{-d} +argument and the @file{CVS/Root} file disagree. + +There is nothing magical about the name +@file{/usr/local/cvsroot}. You can choose to place the +repository anywhere you like. +@xref{Remote repositories} to learn how the repository can be on a +different machine than your working copy of the sources. + +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 +* Remote repositories:: Accessing repositories on remote machines +@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. + +@c FIXME: The CVSROOT line is a goofy example now that +@c mkmodules doesn't exist. +@example +CVSROOT CVSROOT +modules 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. + +@c FIXME: might want to introduce the concept of options in modules file +@c (the old example which was here, -i mkmodules, is obsolete). + +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 specify the appropriate +repository, using the @code{CVSROOT} environment +variable, the @samp{-d} option to @sc{cvs}, or (once +you have checked out a working directories) by +simply allowing @sc{cvs} to use the repository that was +used to check out the working directory (@pxref{Repository}). + +Notwithstanding, it can be confusing to have two or +more repositories. + +None of the examples in this manual show multiple +repositories. + +@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 Remote repositories +@section Remote repositories +@cindex Repositories, remote +@cindex Remote repositories +@cindex Client/Server Operation + + Your working copy of the sources can be on a +different machine than the repository. Generally, +using a remote repository is just like using a local +one, except that the format of the repository name is: + +@example + user@@hostname:/path/to/repository +@end example + +The details of exactly what needs to be set up depend +on how you are connecting to the server. + +@menu +* Connecting via rsh:: Using the @code{rsh} program to connect +* Password authenticated:: Direct connections using passwords +* Kerberos authenticated:: Direct connections with kerberos +@end menu + +@node Connecting via rsh +@subsection Connecting with rsh + +@cindex rsh +CVS uses the @file{rsh} protocol to perform these +operations, so the remote user host needs to have a +@file{.rhosts} file which grants access to the local +user. + +For example, suppose you are the user @file{mozart} on +the local machine @file{anklet.grunge.com}, and the +server machine is @file{chainsaw.brickyard.com}. On +chainsaw, put the following line into the file +@file{.rhosts} in @file{bach}'s home directory: + +@example +anklet.grunge.com mozart +@end example + +Then test that @code{rsh} is working with + +@example +rsh -l bach chainsaw.brickyard.com echo $PATH +@end example + +@cindex CVS_SERVER +Next you have to make sure that @code{rsh} will be able +to find the server. Make sure that the path which +@code{rsh} printed in the above example includes the +directory containing a program named @code{cvs} which +is the server. You need to set the path in +@file{.bashrc}, @file{.cshrc}, etc., not @file{.login} +or @file{.profile}. Alternately, you can set the +environment variable @code{CVS_SERVER} on the client +machine to the filename of the server you want to use, +for example @file{/usr/local/bin/cvs-1.6}. + +There is no need to edit @code{inetd.conf} or start a +@sc{cvs} server daemon. + +Continuing our example, supposing you want to access +the module @file{foo} in the repository +@file{/usr/local/cvsroot/}, on machine +@file{chainsaw.brickyard.com}, you are ready to go: + +@example +cvs -d bach@@chainsaw.brickyard.com:/user/local/cvsroot checkout foo +@end example + +(The @file{bach@@} can be omitted if the username is +the same on both the local and remote hosts.) + +@node Password authenticated +@subsection Direct connection with password authentication + +The @sc{cvs} client can also connect to the server +using a password protocol. This is particularly useful +if using @code{rsh} is not feasible (for example, +the server is behind a firewall), and Kerberos also is +not available. + + To use this method, it is necessary to make +some adjustments on both the server and client sides. + +@menu +* Password authentication server:: Setting up the server +* Password authentication client:: Using the client +* Password authentication security:: What this method does and does not do +@end menu + +@node Password authentication server +@subsubsection Setting up the server for password authentication + +@cindex Pserver (subcommand) +@cindex password server, setting up +@cindex authenticating server, setting up +On the server side, the file @file{/etc/inetd.conf} +needs to be edited so @code{inetd} knows to run the +command @code{cvs pserver} when it receives a +connection on the right port. By default, the port +number is 2401; it would be different if your client +were compiled with @code{CVS_AUTH_PORT} defined to +something else, though. + + If your @code{inetd} allows raw port numbers in +@file{/etc/inetd.conf}, then the following (all on a +single line in @file{inetd.conf}) should be sufficient: + +@example +2401 stream tcp nowait root /usr/local/bin/cvs +cvs -b /usr/local/bin pserver +@end example + +The @samp{-b} option specifies the directory which contains +the @sc{rcs} binaries on the server. + + If your @code{inetd} wants a symbolic service +name instead of a raw port number, then put this in +@file{/etc/services}: + +@example +cvspserver 2401/tcp +@end example + + and put @code{cvspserver} instead of +@code{2401} in @file{inetd.conf}. + + Once the above is taken care of, restart your +@code{inetd}, or do whatever is necessary to force it +to reread its initialization files. + +@cindex CVS passwd file +@cindex passwd file +Because the client stores and transmits passwords in +cleartext (almost---see @ref{Password authentication +security} for details), a separate @sc{cvs} password +file may be used, so people don't compromise their +regular passwords when they access the repository. +This file is @file{$CVSROOT/CVSROOT/passwd} +(@pxref{Intro administrative files}). Its format is +similar to @file{/etc/passwd}, except that it only has +two fields, username and password. For example: + +@example +bach:ULtgRLXo7NRxs +cwang:1sOp854gDF3DY +@end example + +The password is encrypted according to the standard +Unix @code{crypt()} function, so it is possible to +paste in passwords directly from regular Unix +@file{passwd} files. + +When authenticating a password, the server first checks +for the user in the @sc{cvs} @file{passwd} file. If it +finds the user, it compares against that password. If +it does not find the user, or if the @sc{cvs} +@file{passwd} file does not exist, then the server +tries to match the password using the system's +user-lookup routine. When using the @sc{cvs} +@file{passwd} file, the server runs under as the +username specified in the the third argument in the +entry, or as the first argument if there is no third +argument (in this way @sc{cvs} allows imaginary +usernames provided the @sc{cvs} @file{passwd} file +indicates corresponding valid system usernames). In +any case, @sc{cvs} will have no privileges which the +(valid) user would not have. + +Right now, the only way to put a password in the +@sc{cvs} @file{passwd} file is to paste it there from +somewhere else. Someday, there may be a @code{cvs +passwd} command. + +@node Password authentication client +@subsubsection Using the client with password authentication +@cindex Login (subcommand) +@cindex password client, using +@cindex authenticated client, using +Before connecting to the server, the client must @dfn{log +in} with the command @code{cvs login}. Logging in +verifies a password with the server, and also records +the password for later transactions with the server. +The @code{cvs login} command needs to know the +username, server hostname, and full repository path, +and it gets this information from the repository +argument or the @code{CVSROOT} environment variable. + +@code{cvs login} is interactive --- it prompts for a +password: + +@example +cvs -d bach@@chainsaw.brickyard.com:/usr/local/cvsroot login +CVS password: +@end example + +The password is checked with the server; if it is +correct, the @code{login} succeeds, else it fails, +complaining that the password was incorrect. + +Once you have logged in, you can force @sc{cvs} to +connect directly to the server and authenticate with +the stored password by prefixing the repository with +@samp{:pserver:}: + +@example +cvs -d :pserver:bach@@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo +@end example + +The @samp{:pserver:} is necessary because without it, +@sc{cvs} will assume it should use @code{rsh} to +connect with the server (@pxref{Connecting via rsh}). +(Once you have a working copy checked out and are +running @sc{cvs} commands from within it, there is no +longer any need to specify the repository explicitly, +because @sc{cvs} records it in the working copy's +@file{CVS} subdirectory.) + +@cindex CVS_PASSFILE, environment variable +Passwords are stored by default in the file +@file{$HOME/.cvspass}. Its format is human-readable, +but don't edit it unless you know what you are doing. +The passwords are not stored in cleartext, but are +trivially encoded to protect them from "innocent" +compromise (i.e., inadvertently being seen by a system +administrator who happens to look at that file). + +The @code{CVS_PASSFILE} environment variable overrides +this default. If you use this variable, make sure you +set it @emph{before} @code{cvs login} is run. If you +were to set it after running @code{cvs login}, then +later @sc{cvs} commands would be unable to look up the +password for transmission to the server. + +@cindex CVS_PASSWORD, environment variable +The @code{CVS_PASSWORD} environment variable overrides +@emph{all} stored passwords. If it is set, @sc{cvs} +will use it for all password-authenticated +connections. + +@node Password authentication security +@subsubsection Security considerations with password authentication + +The passwords are stored on the client side in a +trivial encoding of the cleartext, and transmitted in +the same encoding. The encoding is done only to +prevent inadvertent password compromises (i.e., a +system administrator accidentally looking at the file), +and will not prevent even a naive attacker from gaining +the password. + +The separate @sc{cvs} password file (@pxref{Password +authentication server}) allows people +to use a different password for repository access than +for login access. On the other hand, once a user has +access to the repository, she can execute programs on +the server system through a variety of means. Thus, repository +access implies fairly broad system access as well. It +might be possible to modify @sc{cvs} to prevent that, +but no one has done so as of this writing. +Furthermore, there may be other ways in which having +access to @sc{cvs} allows people to gain more general +access to the system; noone has done a careful audit. + +In summary, anyone who gets the password gets +repository access, and some measure of general system +access as well. The password is available to anyone +who can sniff network packets or read a protected +(i.e., user read-only) file. If you want real +security, get Kerberos. + +@node Kerberos authenticated +@subsection Direct connection with kerberos + +@cindex kerberos +The main disadvantage of using rsh is that all the data +needs to pass through additional programs, so it may be +slower. So if you have kerberos installed you can +connect via a direct @sc{tcp} connection, +authenticating with kerberos (note that the data +transmitted is @emph{not} encrypted). + +To do this, @sc{cvs} needs to be compiled with kerberos +support; when configuring @sc{cvs} it tries to detect +whether kerberos is present or you can use the +@file{--with-krb4} flag to configure. + +@cindex CVS_CLIENT_PORT +You need to edit @code{inetd.conf} on the server +machine to run @code{cvs kserver}. The client uses +port 1999 by default; if you want to use another port +specify it in the @code{CVS_CLIENT_PORT} environment +variable on the client. Set @code{CVS_CLIENT_PORT} to +@samp{-1} to force an rsh connection. + +@cindex kinit +When you want to use @sc{cvs}, get a ticket in the +usual way (generally @code{kinit}); it must be a ticket +which allows you to log into the server machine. Then +you are ready to go: + +@example +cvs -d chainsaw.brickyard.com:/user/local/cvsroot checkout foo +@end example + +If @sc{cvs} fails to connect, it will fall back to +trying rsh. + +@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. +@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 other version control systems:: Old projects where you want to + preserve history from another system. +* 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 The node name is too long, but I am having trouble +@c thinking of something more concise. +@node From other version control systems +@subsection Creating Files From Other Version Control Systems +@cindex Importing files, from other version control systesm + +If you have a project which you are maintaining with +another version control system, such as @sc{rcs}, you +may wish to put the files from that project into +@sc{cvs}, and preserve the revision history of the +files. + +@table @asis +@cindex RCS, importing files from +@item From RCS +If you have been using @sc{rcs}, find the @sc{rcs} +files---usually a file named @file{foo.c} will have its +@sc{rcs} file in @file{RCS/foo.c,v} (but it could be +other places; consult the @sc{rcs} documentation for +details). Then create the appropriate directories in +@sc{cvs} if they do not already exist. Then copy the +files into the appropriate directories in the @sc{cvs} +repository (the name in the repository must be the name +of the source file with @samp{,v} added; the files go +directly in the appopriate directory of the repository, +not in an @file{RCS} subdirectory). This is one of the +few times when it is a good idea to access the @sc{cvs} +repository directly, rather than using @sc{cvs} +commands. Then you are ready to check out a new +working directory. +@c Someday there probably should be a "cvs import -t +@c rcs" or some such. It could even create magic +@c branches. It could also do something about the case +@c where the RCS file had a (non-magic) "0" branch. + +@c How many is "many"? Or do they just import RCS files? +@item From another version control system +Many version control systems have the ability to export +@sc{rcs} files in the standard format. If yours does, +export the @sc{rcs} files and then follow the above +instructions. + +@cindex SCCS, importing files from +@item From SCCS +There is a script in the @file{contrib} directory of +the @sc{cvs} source distribution called @file{sccs2rcs} +which converts @sc{sccs} files to @sc{rcs} files. +Note: you must run it on a machine which has both +@sc{sccs} and @sc{rcs} installed, and like everything +else in contrib it is unsupported (your mileage may +vary). +@end table + +@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. This is not strictly necessary, +but modules can be convenient in grouping together +related files and directories. + +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 +* Concurrency:: Simultaneous repository access +* Watches:: Mechanisms to track who is editing files +@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. + +@node Concurrency +@section Several developers simultaneously attempting to run CVS + +@cindex locks, cvs +If several developers try to run @sc{cvs} at the same +time, one may get the following message: + +@example +[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo +@end example + +@sc{cvs} will try again every 30 seconds, and either +continue with the operation or print the message again, +if it still needs to wait. If a lock seems to stick +around for an undue amount of time, find the person +holding the lock and ask them about the cvs command +they are running. If they aren't running a cvs +command, look for and remove files starting with +@file{#cvs.tfl}, @file{#cvs.rfl}, or @file{#cvs.wfl} +from the repository. + +Note that these locks are to protect @sc{cvs}'s +internal data structures and have no relationship to +the word @dfn{lock} in the sense used by @sc{rcs}--a +way to prevent other developers from working on a +particular file. + +Any number of people can be reading from a given +repository at a time; only when someone is writing do +the locks prevent other people from reading or writing. + +@cindex Atomic transactions, lack of +@cindex Transactions, atomic, lack of +One might hope for the following property + +@example +If someone commits some changes in one cvs command, +then an update by someone else will either get all the +changes, or none of them. +@end example + +but @sc{cvs} does @emph{not} have this property. For +example, given the files + +@example +a/one.c +a/two.c +b/three.c +b/four.c +@end example + +if someone runs + +@example +cvs ci a/two.c b/three.c +@end example + +and someone else runs @code{cvs update} at the same +time, the person running @code{update} might get only +the change to @file{b/three.c} and not the change to +@file{a/two.c}. + +@node Watches +@section Mechanisms to track who is editing files +@cindex Watches + +For many groups, use of @sc{cvs} in its default mode is +perfectly satisfactory. Users may sometimes go to +check in a modification only to find that another +modification has intervened, but they deal with it and +proceed with their check in. Other groups prefer to be +able to know who is editing what files, so that if two +people try to edit the same file they can choose to +talk about who is doing what when rather than be +surprised at check in time. The features in this +section allow such coordination, while retaining the +ability of two developers to edit the same file at the +same time. + +For maximum benefit developers should use @code{cvs +edit} (not @code{chmod}) to make files read-write to +edit them, and @code{cvs release} (not @code{rm}) to +discard a working directory which is no longer in use, +but @sc{cvs} is not able to enforce this behavior. + +@c I'm a little dissatisfied with this presentation, +@c because "watch on"/"edit"/"editors" are one set of +@c functionality, and "watch add"/"watchers" is another +@c which is somewhat orthogonal even though they interact in +@c various ways. But I think it might be +@c confusing to describe them separately (e.g. "watch +@c add" with loginfo). I don't know. + +@menu +* Setting a watch:: Telling CVS to watch certain files +* Getting Notified:: Telling CVS to notify you +* Editing files:: How to edit a file which is being watched +* Watch information:: Information about who is watching and editing +* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier +@end menu + +@node Setting a watch +@subsection Telling CVS to watch certain files + +To enable the watch features, you first specify that +certain files are to be watched. + +@cindex watch on (subcommand) +@deffn Command {cvs watch on} [@code{-l}] files @dots{} + +Specify that developers should run @code{cvs edit} +before editing @var{files}. CVS will create working +copies of @var{files} read-only, to remind developers +to run the @code{cvs edit} command before working on +them. + +If @var{files} includes the name of a directory, CVS +arranges to watch all files added to the corresponding +repository directory, and sets a default for files +added in the future; this allows the user to set +notification policies on a per-directory basis. The +contents of the directory are processed recursively, +unless the @code{-l} option is given. + +If @var{files} is omitted, it defaults to the current directory. + +@cindex watch off (subcommand) +@end deffn + +@deffn Command {cvs watch off} [@code{-l}] files @dots{} + +Do not provide notification about work on @var{files}. CVS will create +working copies of @var{files} read-write. + +The @var{files} and @code{-l} arguments are processed as for @code{cvs +watch on}. + +@end deffn + +@node Getting Notified +@subsection Telling CVS to notify you + +You can tell @sc{cvs} that you want to receive +notifications about various actions taken on a file. +You can do this without using @code{cvs watch on} for +the file, but generally you will want to use @code{cvs +watch on}, so that developers use the @code{cvs edit} +command. + +@cindex watch add (subcommand) +@deffn Command {cvs watch add} [@code{-a} action] [@code{-l}] files @dots{} + +Add the current user to the list of people to receive notification of +work done on @var{files}. + +The @code{-a} option specifies what kinds of events CVS should notify +the user about. @var{action} is one of the following: + +@table @code + +@item edit +Another user has applied the @code{cvs edit} command (described +below) to a file. + +@item unedit +Another user has applied the @code{cvs unedit} command (described +below) or the @code{cvs release} command to a file, or has deleted +the file and allowed @code{cvs update} to recreate it. + +@item commit +Another user has committed changes to a file. + +@item all +All of the above. + +@item none +None of the above. (This is useful with @code{cvs edit}, +described below.) + +@end table + +The @code{-a} option may appear more than once, or not at all. If +omitted, the action defaults to @code{all}. + +The @var{files} and @code{-l} option are processed as for the +@code{cvs watch} commands. + +@end deffn + + +@cindex watch remove (subcommand) +@deffn Command {cvs watch remove} [@code{-a} action] [@code{-l}] files @dots{} + +Remove a notification request established using @code{cvs watch add}; +the arguments are the same. If the @code{-a} option is present, only +watches for the specified actions are removed. + +@end deffn + +When the conditions exist for notification, @sc{cvs} +calls the @file{notify} administrative file, passing it +the user to receive the notification and the user who +is taking the action which results in notification. +Normally @file{notify} will just send an email message. + +@cindex users (admin file) +Note that if you set this up in the straightforward +way, users receive notifications on the server machine. +One could of course write a @file{notify} script which +directed notifications elsewhere, but to make this +easy, @sc{cvs} allows you to associate a notification +address for each user. To do so create a file +@file{users} in @file{CVSROOT} with a line for each +user in the format @var{user}:@var{value}. Then +instead of passing the name of the user to be notified +to @file{notify}, @sc{cvs} will pass the @var{value} +(normally an email address on some other machine). + +@node Editing files +@subsection How to edit a file which is being watched + +Since a file which is being watched is checked out +read-only, you cannot simply edit it. To make it +read-write, and inform others that you are planning +to edit it, use the @code{cvs edit} command. + +@cindex edit (subcommand) +@deffn Command {cvs edit} [options] files @dots{} + +Prepare to edit the working files @var{files}. CVS makes the +@var{files} read-write, and notifies users who have requested +@code{edit} notification for any of @var{files}. + +The @code{cvs edit} command accepts the same @var{options} as the +@code{cvs watch add} command, and establishes a temporary watch for the +user on @var{files}; CVS will remove the watch when @var{files} are +@code{unedit}ed or @code{commit}ted. If the user does not wish to +receive notifications, she should specify @code{-a none}. + +The @var{files} and @code{-l} option are processed as for the @code{cvs +watch} commands. + +@end deffn + +Normally when you are done with a set of changes, you +use the @code{cvs commit} command, which checks in your +changes and returns the watched files to their usual +read-only state. But if you instead decide to abandon +your changes, or not to make any changes, you can use +the @code{cvs unedit} command. + +@cindex unedit (subcommand) +@deffn Command {cvs unedit} [@code{-l}] files @dots{} + +Abandon work on the working files @var{files}, and revert them to the +repository versions on which they are based. CVS makes those +@var{files} read-only for which users have requested notification using +@code{cvs watch on}. CVS notifies users who have requested @code{unedit} +notification for any of @var{files}. + +The @var{files} and @code{-l} option are processed as for the +@code{cvs watch} commands. + +@end deffn + +When using client/server @sc{cvs}, you can use the +@code{cvs edit} and @code{cvs unedit} commands even if +@sc{cvs} is unable to succesfully communicate with the +server; the notifications will be sent upon the next +successful @sc{cvs} command. + +@node Watch information +@subsection Information about who is watching and editing + +@cindex watchers (subcommand) +@deffn Command {cvs watchers} [@code{-l}] files @dots{} + +List the users currently watching changes to @var{files}. The report +includes the files being watched, and the mail address of each watcher. + +The @var{files} and @code{-l} arguments are processed as for the +@code{cvs watch} commands. + +@end deffn + + +@cindex editors (subcommand) +@deffn Command {cvs editors} [@code{-l}] files @dots{} + +List the users currently working on @var{files}. The report +includes the mail address of each user, the time when the user began +working with the file, and the host and path of the working directory +containing the file. + +The @var{files} and @code{-l} arguments are processed as for the +@code{cvs watch} commands. + +@end deffn + +@node Watches Compatibility +@subsection Using watches with old versions of CVS + +@cindex CVS 1.6, and watches +If you use the watch features on a repository, it +creates @file{CVS} directories in the repository and +stores the information about watches in that directory. +If you attempt to use @sc{cvs} 1.6 or earlier with the +repository, you get an error message such as + +@example +cvs update: cannot open CVS/Entries for reading: No such file or directory +@end example + +and your operation will likely be aborted. To use the +watch features, you must upgrade all copies of @sc{cvs} +which use that repository in local or server mode. If +you cannot upgrade, use the @code{watch off} and +@code{watch remove} commands to remove all watches, and +that will restore the repository to a state which +@sc{cvs} 1.6 can cope with. + +@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. Tag names can +contain uppercase and lowercase letters, digits, +@samp{-}, and @samp{_}. The two tag names @code{BASE} +and @code{HEAD} are reserved for use by @sc{cvs}. It +is expected that future names which are special to +@sc{cvs} will contain characters such as @samp{%} or +@samp{=}, rather than being named analogously to +@code{BASE} and @code{HEAD}, to avoid conflicts with +actual tag names. +@c FIXME: is the above list of valid characters in tag +@c names complete? + +@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 + +@c FIXME: should be more explicit about the value of +@c having a tag on the branchpoint. Also should talk +@c about creating a branch with tag not rtag. +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 + +@c FIXME: make this stand alone better; many places +@c @xref to this node. +The @samp{-r release-1-0-patches} flag that was given +to @code{checkout} in the previous example +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}. + +You can use the @code{status} command to see what +sticky tags or dates are set: + +@c FIXME: This example needs to stand alone better and it +@c would also better if it didn't use -v which only +@c clutters the output in this context. +@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}. The +@samp{-A} option retrieves the version of the file from +the head of the trunk, and forgets any sticky tags, +dates, or options. + +@c Is the fact that CVS works this way a bug or a +@c feature? If a feature, describe how you would use +@c it to do something useful. +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}. Likewise, use of the +@samp{-D} option to @code{update} or @code{checkout} +sets a @dfn{sticky date}, which, similarly, causes that +date to be used for future retrievals. + +@cindex Restoring old version of removed file +@cindex Resurrecting old version of dead file +Many times you will want to retrieve an old version of +a file without setting a sticky tag. The way to do +that is with the @samp{-p} option to @code{checkout} or +@code{update}, which sends the contents of the file to +standard output. For example, suppose you have a file +named @file{file1} which existed as revision 1.1, and +you then removed it (thus adding a dead revision 1.2). +Now suppose you want to add it again, with the same +contents it had previously. Here is how to do it: + +@example +$ cvs update -p -r 1.1 file1 >file1 +=================================================================== +Checking out file1 +RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v +VERS: 1.1 +*************** +$ cvs add file1 +cvs add: version 1.2 of `file1' will be resurrected +cvs add: use 'cvs commit' to add this file permanently +$ cvs commit -m test +Checking in file1; +/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 +new revision: 1.3; previous revision: 1.2 +done +$ +@end example + +@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 more than once:: Merging from a branch several times +* 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''. + +@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 ! <- The main trunk ++-----+ +-----+ +-----+ +-----+ + ! + ! + ! +---------+ +---------+ +Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! + +---------+ +---------+ +@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.4} + +$ 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.2, into your working copy} + # @r{of the file.} + +$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.} +@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 + +@node Merging more than once +@section Merging from a branch several times + +Continuing our example, the revision tree now looks +like this: + +@example ++-----+ +-----+ +-----+ +-----+ +-----+ +! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk ++-----+ +-----+ +-----+ +-----+ +-----+ + ! * + ! * + ! +---------+ +---------+ +Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 ! + +---------+ +---------+ +@end example + +where the starred line represents the merge from the +@samp{R1fix} branch to the main trunk, as just +discussed. + +Now suppose that development continues on the +@samp{R1fix} branch: + +@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 + +and then you want to merge those new changes onto the +main trunk. If you just use the @code{cvs update -j +R1fix m.c} command again, @sc{cvs} will attempt to +merge again the changes which you have already merged, +which can have undesirable side effects. + +So instead you need to specify that you only want to +merge the changes on the branch which have not yet been +merged into the trunk. To do that you specify two +@samp{-j} options, and @sc{cvs} merges the changes from +the first revision to the second revision. For +example, in this case the simplest way would be + +@example +cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the} + # @r{head of the R1fix branch} +@end example + +The problem with this is that you need to specify the +1.2.2.2 revision manually. A slightly better approach +might be to use the date the last merge was done: + +@example +cvs update -j R1fix:yesterday -j R1fix m.c +@end example + +Better yet, tag the R1fix branch after every merge into +the trunk, and then use that tag for subsequent merges: + +@example +cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c +@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 when operating on +multiple files, 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 when operating on +multiple files. + +@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 + +When you commit the removal of the file, @sc{cvs} +records the fact that the file no longer exists. It is +possible for a file to exist on only some branches and +not on others, or to re-add another file with the same +name later. CVS will correctly create or not create +the file, based on the @samp{-r} and @samp{-D} options +specified to @code{checkout} or @code{update}. + +@cindex Remove (subcommand) +@deffn Command {cvs remove} [@code{-lR}] files @dots{} + +Schedule file(s) to be removed from the repository +(files which have not already been removed from the +working directory are not processed). This command +does not actually remove the file from the repository +until you commit the removal. The @samp{-R} option +(the default) specifies that it will recurse into +subdirectories; @samp{-l} specifies that it will not. +@end deffn + +Here is an example of removing several 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 + +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 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_DIST WDIFF_0_04 +@end example + +The vendor tag is named @samp{FSF_DIST} 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_DIST 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_DIST:yesterday -jFSF_DIST 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_DIST} +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. + +Using a date, as suggested above, 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 + +Moving files to a different directory or renaming them +is not difficult, but some of the ways in which this +works may be non-obvious. (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}. + +@menu +* Outside:: The normal way to Rename +* Inside:: A tricky, alternative way +* Rename by copying:: Another tricky, alternative way +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Outside +@section The Normal way to Rename + +The normal way to move a 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, for example @file{foo/bar.c}). + +@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 + +This is the simplest way to move a file, it is not +error-prone, and it preserves the history of what was +done. Note that to access the history of the file you +must specify the old or the new name, depending on what +portion of the history you are accessing. For example, +@code{cvs log @var{old}} will give the log up until the +time of the rename. + +When @var{new} is committed its revision numbers will +start at 1.0 again, so if that bothers you, use the +@samp{-r rev} option to commit (@pxref{commit options}) + +@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/@var{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 way also involves direct modifications to the +repository. It is safe, but not without drawbacks. + +@example +# @r{Copy the @sc{rcs} file inside the repository} +$ cd $CVSROOT/@var{module} +$ cp @var{old},v @var{new},v +# @r{Remove the old file} +$ cd ~/@var{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 +@c FIXME: Is this true about -D now that we have death +@c support? See 5B.3 in the FAQ. +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. + +@c --------------------------------------------------------------------- +@node History browsing +@chapter History browsing +@cindex History browsing +@cindex Traceability +@cindex Isolation + +@ignore +@c This is too long for an introduction (goal is +@c one 20x80 character screen), and also mixes up a +@c variety of issues (parallel development, history, +@c maybe even touches on process control). + +@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. + +@end ignore + +@c kind of lame, in a lot of ways the above text inside +@c the @ignore motivates this chapter better +Once you have used @sc{cvs} to store a version control +history---what files have changed when, how, and by +whom, there are a variety of mechanisms for looking +through the history. + +@menu +* log messages:: Log messages +* history database:: The history database +* user-defined logging:: User-defined logging +* annotate:: What revision modified each line of a file? +@end menu + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node log messages +@section Log messages + +@c FIXME: @xref to place where we talk about how to +@c specify message to commit. +Whenever you commit a file you specify a log message. + +@c FIXME: bring the information here, and get rid of or +@c greatly shrink the "log" node. +To look through the log messages which have been +specified for every revision which has been committed, +use the @code{cvs log} command (@pxref{log}). + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node history database +@section The history database + +@c FIXME: bring the information from the history file +@c and history nodes here. Rewrite it to be motivated +@c better (start out by clearly explaining what gets +@c logged in history, for example). +You can use the history file (@pxref{history file}) to +log various @sc{cvs} actions. To retrieve the +information from the history file, use the @code{cvs +history} command (@pxref{history}). + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node user-defined logging +@section User-defined logging + +@c FIXME: should probably also mention the fact the -l +@c global option can disable most of the mechanisms +@c discussed here (why? What is the -l global option for?). +@c +@c FIXME: probably should centralize this information +@c here, at least to some extent. Maybe by moving the +@c loginfo, etc., nodes here and replacing +@c the "user-defined logging" node with one node for +@c each method. +You can customize @sc{cvs} to log various kinds of +actions, in whatever manner you choose. These +mechanisms operate by executing a script at various +times. The script might append a message to a file +listing the information and the programmer who created +it, or send mail to a group of developers, or, perhaps, +post a message to a particular newsgroup. To log +commits, use the @file{loginfo} file (@pxref{loginfo}). +@c FIXME: What is difference between doing it in the +@c modules file and using loginfo/taginfo? Why should +@c user use one or the other? +To log commits, checkouts, exports, and tags, +respectively, you can also use the @samp{-i}, +@samp{-o}, @samp{-e}, and @samp{-t} options in the +modules file. For a more flexible way of giving +notifications to various users, which requires less in +the way of keeping centralized scripts up to date, use +the @code{cvs watch add} command (@pxref{Getting +Notified}); this command is useful even if you are not +using @code{cvs watch on}. + +@cindex taginfo +The @file{taginfo} file defines programs to execute +when someone executes a @code{tag} or @code{rtag} +command. The @file{taginfo} file has the standard form +for administrative files (@pxref{Administrative +files}), where each line is a regular expression +followed by a command to execute. The arguments passed +to the command are, in order, the @var{tagname}, +@var{operation} (@code{add} for @code{tag}, +@code{mov} for @code{tag -F}, and @code{del} for +@code{tag -d}), @var{repository}, and any remaining are +pairs of @var{filename} @var{revision}. A non-zero +exit of the filter program will cause the tag to be +aborted. + +@node annotate +@section Annotate command +@cindex annotate (subcommand) + +@deffn Command {cvs annotate} [@code{-l}] files @dots{} + +For each file in @var{files}, print the head revision +of the trunk, together with information on the last +modification for each line. The @code{-l} option means +to process the local directory only, not to recurse +(@pxref{Common options}). For example: + +@example +$ cvs annotate ssfile +Annotations for ssfile +*************** +1.1 (mary 27-Mar-96): ssfile line 1 +1.2 (joe 28-Mar-96): ssfile line 2 +@end example + +The file @file{ssfile} currently contains two lines. +The @code{ssfile line 1} line was checked in by +@code{mary} on March 27. Then, on March 28, @code{joe} +added a line @code{ssfile line 2}, without modifying +the @code{ssfile line 1} line. This report doesn't +tell you anything about lines which have been deleted +or replaced; you need to use @code{cvs diff} for that +(@pxref{diff}). + +@end deffn + +@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. + +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 + +@c FIXME: This could be made more coherent, by expanding it +@c with more examples or something. +Each file has a stored default substitution mode, and +each working directory copy of a file also has a +substitution mode. The former is set by the @samp{-k} +option to @code{cvs add} and @code{cvs admin}; the +latter is set by the -k or -A options to @code{cvs +checkout} or @code{cvs update}. @code{cvs diff} also +has a @samp{-k} option. For some examples, +@xref{Binary files}. + +The modes available 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. + +@item -kb +Like @samp{-ko}, but also inhibit conversion of line +endings between the canonical form in which they are +stored in the repository (linefeed only), and the form +appropriate to the operating system in use on the +client. For systems, like unix, which use linefeed +only to terminate lines, this is the same as +@samp{-ko}. For more information on binary files, see +@ref{Binary files}. + +@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. + +One often would like to use @samp{-kv} with @code{cvs +export}---@pxref{export}. But be aware that doesn't +handle an export containing binary files correctly. + +@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 Binary files +@chapter Handling binary files +@cindex Binary files + +There are two issues with using @sc{cvs} to store +binary files. The first is that @sc{cvs} by default +convert line endings between the canonical form in +which they are stored in the repository (linefeed +only), and the form appropriate to the operating system +in use on the client (for example, carriage return +followed by line feed for Windows NT). + +The second is that a binary file might happen to +contain data which looks like a keyword (@pxref{Keyword +substitution}), so keyword expansion must be turned +off. + +The @samp{-kb} option available with some @sc{cvs} +commands insures that neither line ending conversion +nor keyword expansion will be done. If you are using +an old version of @sc{rcs} without this option, and you +are using an operating system, such as unix, which +terminates lines with linefeeds only, you can use +@samp{-ko} instead; if you are on another operating +system, upgrade to a version of @sc{rcs}, such as 5.7 +or later, which supports @samp{-kb}. + +Here is an example of how you can create a new file +using the @samp{-kb} flag: + +@example +$ echo '$@asis{}Id$' > kotest +$ cvs add -kb -m"A test file" kotest +$ cvs ci -m"First checkin; contains a keyword" kotest +@end example + +If a file accidentally gets added without @samp{-kb}, +one can use the @code{cvs admin} command to recover. +For example: + +@example +$ echo '$@asis{}Id$' > kotest +$ cvs add -m"A test file" kotest +$ cvs ci -m"First checkin; contains a keyword" kotest +$ cvs admin -kb kotest +$ cvs update -A 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 -kb} 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 @code{cvs update -A}. + +@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 how to invoke @sc{cvs}, and +describes in detail those subcommands of @sc{cvs} which +are not fully described elsewhere. To look up a +particular subcommand, see @ref{Index}. + +@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 +* 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}. +@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 (the one that drove the implementation of the +.cvsrc support, actually) 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}), the official name, not necessarily the one +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 have the +@samp{-P} option added to the arguments, as well as +@samp{cvs co foo}. + +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. +Getting "old" format diffs would be slightly more +complicated, because @code{diff} doesn't have an option +to specify use of the "old" format, so you would need +@samp{cvs -f diff foobar}. + +In place of the command name you can use @code{cvs} to +specify global options (@pxref{Global options}). For +example the following line in @file{.cvsrc} + +@example +cvs -z6 +@end example + +causes @sc{cvs} to use compression level 6 + +@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. @xref{Repository}. + +@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, unless watches are on +(@pxref{Watches}). + +@item -s @var{variable}=@var{value} +Set a user variable (@pxref{Variables}). + +@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. + +@item -z @var{gzip-level} +Set the compression level. Only has an effect on the +@sc{cvs} client. + +@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 +(for more information on sticky tags/dates, @pxref{Sticky tags}). + +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 -W +Specify file names that should be filtered. You can +use this option repeatedly. The spec can be a file +name pattern of the same type that you can specify in +the @file{.cvswrappers} file. +Avaliable with the following commands: @code{import}, +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 (for more information +on sticky tags/dates, @pxref{Sticky tags}). The +tag can be either a symbolic or numeric tag. +@xref{Tags}. + +Specifying the @samp{-q} global option along with the +@samp{-r} command 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{Removing files}, 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. 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}). See @ref{Binary files}, for +information on using this option for binary files. + +@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. + +If there is a group whose name matches a compiled in +value which defaults to @code{cvsadmin}, only members +of that group can use @code{cvs admin}. To disallow +@code{cvs admin} for all users, create a group with no +users in it. + +@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}] +When used with bare @sc{rcs}, this +option sets the default branch to @var{rev}; in +@sc{cvs} sticky tags (@pxref{Sticky tags}) are a better +way to decide which branch you want to work on. With +@sc{cvs}, this option can be used to control behavior +with respect to the vendor branch. +@c FIXME: document how you use it with the vendor +@c branch (or fix cvs so that there is a more graceful +@c way to handle the case). + +@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}, @code{cvs export}, or @code{cvs +checkout} overrides this default. + +@cindex Reserved checkouts +@cindex RCS-style locking +@item -l[@var{rev}] +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. + +This can be used in conjunction with the +@file{rcslock.pl} script in the @file{contrib} +directory of the @sc{cvs} source distribution to +provide reserved checkouts (where only one user can be +editing a given file at a time). See the comments in +that file for details (and see the @file{README} file +in that directory for disclaimers about the unsupported +nature of contrib). According to comments in that +file, locking must set to strict (which is the default). + +@item -L +Set locking to strict. Strict locking means that the +owner of an RCS file is not exempt from locking for +checkin. For use with @sc{cvs}, strict locking must be +set; see the discussion under the @samp{-l} option above. + +@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} +Potentially 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, this option is not a good way to take back +a bogus commit; commit a new revision undoing the bogus +change instead (@pxref{Merging two revisions}). + +@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}). Note that @sc{cvs} +uses the @code{dead} state for its own purposes; to +take a file to or from the @code{dead} state use +commands like @code{cvs remove} and @code{cvs add}, not +@code{cvs admin -s}. + +@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 +Set locking to non-strict. Non-strict locking means +that the owner of a file need not lock a revision for +checkin. For use with @sc{cvs}, strict locking must be +set; see the discussion under the @samp{-l} option +above. + +@item -u[@var{rev}] +See the option @samp{-l} above, for a discussion of +using this option with @sc{cvs}. 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! + +@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} global option). + +The files created by @code{checkout} are created +read-write, unless the @samp{-r} option to @sc{cvs} +(@pxref{Global options}) is specified, the +@code{CVSREAD} environment variable is specified +(@pxref{Environment variables}), or a watch is in +effect for that file (@pxref{Watches}). + +@c FIXME: misleading--checkout takes a module as +@c argument, and update does not--so -d behavior is not the only +@c difference. +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}. See +@ref{Sticky tags}, for more information on sticky tags/dates. + +@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 -r @var{tag} +Use revision @var{tag}. This option is sticky, and implies @samp{-P}. +See @ref{Sticky tags}, for more information on sticky tags/dates. +@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. +See @ref{Sticky tags}, for more information on sticky tags/dates. + +@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} +With two @samp{-j} options, merge changes from the +revision specified with the first @samp{-j} option to +the revision specified with the second @samp{j} option, +into the working directory. + +With one @samp{-j} option, merge changes from the +ancestor revision to the revision specified with the +@samp{-j} option, into the working directory. The +ancestor revision is the common ancestor of the +revision which the working directory is based on, and +the revision specified in the @samp{-j} option. + +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}}. + +@xref{Merging}. + +@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: + +@c FIXME: Should we be recommending tagging the branchpoint? +@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: + +@c FIXME: Should we be recommending tagging the branchpoint? +@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 -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 [-flNn] [-r rev|-D date] [-k subst] [-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. + +One often would like to use @samp{-kv} with @code{cvs +export}. 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. But be +aware that doesn't handle an export containing binary +files correctly. Also be aware that after having used +@samp{-kv}, one can no longer use 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 not +use @samp{-kv}. + +@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 -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 -k @var{subst} +Set keyword expansion mode (@pxref{Substitution modes}). + +@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. + +If @sc{cvs} decides a file should be ignored +(@pxref{cvsignore}), it does not import it and prints +@samp{I } followed by the filename + +If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists, +any file whose names match the specifications in that +file will be treated as packages and the appropriate +filtering will be performed on the file/directory +before being imported, @xref{Wrappers}. + +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 + +This standard option is supported by @code{import} +(@pxref{Common options}, for a complete description): + +@table @code +@item -m @var{message} +Use @var{message} as log information, instead of +invoking an editor. +@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 @ref{Substitution modes} for a +list of valid @samp{-k} settings. + +@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? + +@item -W @var{spec} +Specify file names that should be filtered during +import. You can use this option repeatedly. + +@var{spec} can be a file name pattern of the same type +that you can specify in the @file{.cvswrappers} +file. @xref{Wrappers}. +@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 -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 [-d] directories@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 + +The @code{release} command supports one command option: + +@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 -- CVS should be fixed to print "? foo" for +@c such spurious directories +@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 + +@node rtag +@appendixsec rtag---Add a tag to the RCS file +@cindex Rtag (subcommand) + +@itemize @bullet +@item +rtag [-falnR] [-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 -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] [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. +@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 [-lR] [-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. +@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 [-AdflPpR] [-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}. +See @ref{Sticky tags}, for more information on sticky tags/dates. + +@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. @xref{Recursive behavior}. + +@item -P +Prune empty directories. + +@item -p +Pipe files to the standard output. + +@item -R +Operate recursively. This is on by default. +@xref{Recursive behavior}. + +@item -r tag +Retrieve revision @var{tag}. This option is sticky, +and implies @samp{-P}. +See @ref{Sticky tags}, for more information on sticky tags/dates. +@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. +See @ref{Sticky tags}, for more information on sticky tags/dates. + +@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. Use @samp{-I !} to avoid +ignoring any files at all. @xref{cvsignore}, for other +ways to make @sc{cvs} ignore some files. + +@item -W@var{spec} +Specify file names that should be filtered during +update. You can use this option repeatedly. + +@var{spec} can be a file name pattern of the same type +that you can specify in the @file{.cvswrappers} +file. @xref{Wrappers}. + +@item -j@var{revision} +With two @samp{-j} options, merge changes from the +revision specified with the first @samp{-j} option to +the revision specified with the second @samp{j} option, +into the working directory. + +With one @samp{-j} option, merge changes from the +ancestor revision to the revision specified with the +@samp{-j} option, into the working directory. The +ancestor revision is the common ancestor of the +revision which the working directory is based on, and +the revision specified in the @samp{-j} option. + +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}}. + +@xref{Merging}. + +@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 +* Wrappers:: Treat directories as files +* 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 +* Variables:: Various variables are expanded +@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 use @sc{cvs} to update the +modules file (use normal commands like @code{add}, +@code{commit}, etc). + +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 Export program +@item -e @var{prog} +Specify a program @var{prog} to run whenever files in a +module are exported. @var{prog} runs with a single +argument, 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 Wrappers +@appendixsec The cvswrappers file +@cindex cvswrappers (admin file) +@cindex CVSWRAPPERS, environment variable +@cindex Wrappers + +Wrappers allow you to set a hook which transforms files on +their way in and out of @sc{cvs}. Most or all of the +wrappers features do not work with client/server @sc{cvs}. + +The file @file{cvswrappers} defines the script that will be +run on a file when its name matches a regular +expresion. There are two scripts that can be run on a +file or directory. One script is executed on the file/directory +before being checked into the repository (this is denoted +with the @code{-t} flag) and the other when the file is +checked out of the repository (this is denoted with the +@code{-f} flag) + +The @file{cvswrappers} also has a @samp{-m} option to +specify the merge methodology that should be used when +the file is updated. @code{MERGE} means the usual +@sc{cvs} behavior: try to merge the files (this +generally will not work for binary files). @code{COPY} +means that @code{cvs update} will merely copy one +version over the other, and require the user using +mechanisms outside @sc{cvs}, to insert any necessary +changes. +@c FIXME: which version is copied over which version? +The @samp{-m} wrapper option only affects behavior when +merging is done on update; it does not affect how files +are stored. See @xref{Binary files}, for more on +binary files. + +The basic format of the file @file{cvswrappers} is: + +@example +wildcard [option value][option value]... + +where option is one of +-f from cvs filter value: path tofilter +-t to cvs filter value: path to filter +-m update methodology value: MERGE or COPY + +and value is a single-quote delimited value. +@end example + +@example +*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY' +*.c -t 'indent %s %s' +@end example + +@noindent +The above example of a @file{cvswrappers} file +states that all files/directories that end with a @code{.nib} +should be filtered with the @file{wrap} program before +checking the file into the repository. The file should +be filtered though the @file{unwrap} program when the +file is checked out of the repository. The +@file{cvswrappers} file also states that a @code{COPY} +methodology should be used when updating the files in +the repository (that is no merging should be performed). + +The last example line says that all files that end with +a @code{*.c} should be filtered with @file{indent} +before being checked into the repository. Unlike the previous +example no filtering of the @code{*.c} file is done when +it is checked out of the repository. +@noindent +The @code{-t} filter is called with two arguments, +the first is the name of the file/directory to filter +and the second is the pathname to where the resulting +filtered file should be placed. + +@noindent +The @code{-f} filter is called with one argument, +which is the name of the file to filter from. The end +result of this filter will be a file in the users directory +that they can work on as they normally would. + +@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. + +The first regular expression that matches the current +directory name in the repository is used. The rest of the line +is used as a file name or command-line as appropriate. + +@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). + +The first line with a regular expression matching the +relative path to the module will be used. If the +command returns 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 +All occurances of the name @samp{ALL} appearing as a +regular expression are used in addition to the first +matching regular expression or the name @samp{DEFAULT}. + +Note: when @sc{CVS} is accessing a remote repository, +@file{commitinfo} will be run on the @emph{remote} +(i.e., server) side, not the client side (@pxref{Remote +repositories}). + +@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 @samp{ALL} +keyword is not supported. If more than one matching +line is found, the first one is used. This can be +useful for specifying a default edit script in a +module, and then overriding it in a subdirectory. + +@cindex DEFAULT in editinfo +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 edit script exits with a non-zero exit status, +the commit is aborted. + +Note: when @sc{CVS} is accessing a remote repository, +@file{editinfo} will be run on the @emph{remote} +(i.e., server) side, not the client side (@pxref{Remote +repositories}). + +@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. + +All occurances of the name @samp{ALL} appearing as a +regular expression are used in addition to the first +matching regular expression or @samp{DEFAULT}. + +The first matching regular expression is used. + +@xref{commit files}, for a description of the syntax of +the @file{loginfo} file. + +Note: when @sc{CVS} is accessing a remote repository, +@file{loginfo} will be run on the @emph{remote} +(i.e., server) side, not the client side (@pxref{Remote +repositories}). + +@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}. +@c and mailed to @t{ceder}. + +@c FIXME: is it a CVS feature or bug that only the +@c first matching line is used? It is documented +@c above, but is it useful? This example (with the +@c mail to ceder put back in) is awkward to write if +@c only the first matching line is used. +@example +ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog +@c ^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. + +All occurances of the name @samp{ALL} appearing as a +regular expression are 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. + +When @sc{CVS} is accessing a remote repository, +the contents of @file{rcsinfo} at the time a directory +is first checked out will specify a template which does +not then change. If you edit @file{rcsinfo} or its +templates, you may need to check out a new working +directory. +@c Would be nice to fix CVS so this isn't needed. For +@c example, a mechanism analogous to CVS/Entries, where +@c the client keeps track of what version of the template +@c it has. + +@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 include certain file name +patterns: 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 file name +patterns is: + +@cindex Ignored files +@cindex Automatically ignored files +@example + RCS SCCS CVS CVS.adm + RCSLOG cvslog.* + tags TAGS + .make.state .nse_depinfo + *~ #* .#* ,* _$* *$ + *.old *.bak *.BAK *.orig *.rej .del-* + *.a *.olb *.o *.obj *.so *.exe + *.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{cvs init} command is used to set up the +repository (@pxref{Setting up}). + +The file format of the @file{history} file is +documented only in comments in the @sc{cvs} source +code, but generally programs should use the @code{cvs +history} command to access it anyway, in case the +format changes with future releases of @sc{cvs}. + +@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +@node Setting up +@appendixsec Setting up the repository +@cindex Repository, setting up +@cindex Creating a repository +@cindex Setting up a repository + +To set up a @sc{cvs} repository, choose a directory +with ample disk space available for the revision +history of the source files. It should be accessable +(directly or via a networked file system) from all +machines which want to use @sc{cvs} in server or local +mode; the client machines need not have any access to +it other than via the @sc{cvs} protocol. + +To create a repository, run the @code{cvs init} +command. It will set up an empty repository in the +@sc{cvs} root specified in the usual way +(@pxref{Repository}). For example, + +@example +cvs -d /usr/local/cvsroot init +@end example + +@code{cvs init} is careful to never overwrite any +existing files in the repository, so no harm is done if +you run @code{cvs init} on an already set-up +repository. + +@code{cvs init} will enable history logging; if you +don't want that, remove the history file after running +@code{cvs init}. @xref{history file}. + +@node Variables +@appendixsec Expansions in administrative files + +Sometimes in writing an administrative file, you might +want the file to be able to know various things based +on environment @sc{cvs} is running in. There are +several mechanisms to do that. + +To find the home directory of the user running @sc{cvs} +(from the @code{HOME} environment variable), use +@samp{~} followed by @samp{/} or the end of the line. +Likewise for the home directory of @var{user}, use +@samp{~@var{user}}. These variables are expanded on +the server machine, and don't get any resonable +expansion if pserver (@pxref{Password authenticated}) +is in used; therefore user variables (see below) may be +a better choice to customize behavior based on the user +running @sc{cvs}. +@c Based on these limitations, should we deprecate ~? +@c What is it good for? Are people using it? + +One may want to know about various pieces of +information internal to @sc{cvs}. A @sc{cvs} internal +variable has the syntax @code{$@{@var{variable}@}}, +where @var{variable} starts with a letter and consists +of alphanumberic characters and @samp{_}. If the +character following @var{variable} is a +non-alphanumeric character other than @samp{_}, the +@samp{@{} and @samp{@}} can be omitted. The @sc{cvs} +internal variables are: + +@table @code +@item CVSROOT +This is the value of the @sc{cvs} root in use. +@xref{Repository}, for a description of the various +ways to specify this. + +@item RCSBIN +This is the value @sc{cvs} is using for where to find +@sc{rcs} binaries. @xref{Global options}, for a +description of how to specify this. + +@item CVSEDITOR +@itemx VISUAL +@itemx EDITOR +These all expand to the same value, which is the editor +that @sc{cvs} is using. @xref{Global options}, for how +to specify this. + +@item USER +Username of the user running @sc{cvs} (on the @sc{cvs} +server machine). +@end table + +If you want to pass a value to the administrative files +which the user that is running @sc{cvs} can specify, +use a user variable. To expand a user variable, the +administrative file contains +@code{$@{=@var{variable}@}}. To set a user variable, +specify the global option @samp{-s} to @sc{cvs}, with +argument @code{@var{variable}=@var{value}}. It may be +particularly useful to specify this option via +@file{.cvsrc} (@pxref{~/.cvsrc}). + +For example, if you want the administrative file to +refer to a test directory you might create a user +variable @code{TESTDIR}. Then if @sc{cvs} is invoked +as @code{cvs -s TESTDIR=/work/local/tests}, and the +administrative file contains @code{sh +$@{=TESTDIR@}/runtests}, then that string is expanded +to @code{sh /work/local/tests/runtests}. + +All other strings containing @samp{$} are reserved; +there is no way to quote a @samp{$} character so that +@samp{$} represents itself. + +@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 CVSWRAPPERS +@item $CVSWRAPPERS +A whitespace-separated list of file name patterns that +@sc{cvs} should treat as wrappers. @xref{Wrappers}. + +@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{}} Once you have checked out a working +directory, @sc{cvs} stores the appropriate root (in +the file @file{CVS/Root}), so normally you only need to +worry about this when initially checking out a working +directory. + +@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. + +@cindex HOME +@item $HOME +@cindex HOMEPATH +@item $HOMEPATH +Used to locate the directory where the @file{.cvsrc} +file is searched (@code{$HOMEPATH} is used for Windows-NT). +@pxref{~/.cvsrc} + +@cindex CVS_RSH +@item $CVS_RSH +Used in client-server mode when accessing a remote +repository using @sc{rsh}. The default value is +@code{rsh}. You can set it to use another program for +accssing the remote server (e.g. for HP-UX 9, you +should set it to @code{remsh} because @code{rsh} +invokes the restricted shell). @pxref{Connecting via +rsh} + +@item $CVS_SERVER +Used in client-server mode when accessing a remote +repository using @sc{rsh}. It specifies the name of +the program to start on the server side when accessing +a remote repository using @sc{rsh}. The default value +is @code{cvs}. @pxref{Connecting via rsh} + +@item $CVS_PASSFILE +Used in client-server mode when accessing the @code{cvs +login server}. Default value is @file{$HOME/.cvspass}. +@pxref{Password authentication client} + +@item $CVS_PASSWORD +Used in client-server mode when accessing the @code{cvs +login server}. +@pxref{Password authentication client} + +@item $CVS_CLIENT_PORT +Used in client-server mode when accessing the server +via Kerberos. +@pxref{Kerberos authenticated} + +@cindex CVS_RCMD_PORT +@item $CVS_RCMD_PORT +Used in client-server mode. If set, specifies the port +number to be used when accessing the @sc{rcmd} demon on +the server side. (Currently not used for Unix clients). + +@cindex CVS_CLIENT_LOG +@item $CVS_CLIENT_LOG +Used for debugging only in client-server +mode. If set, everything send to the server is logged +into @file{@code{$CVS_CLIENT_LOG}.in} and everything +send from the server is logged into +@file{@code{$CVS_CLIENT_LOG}.out}. + +@cindex CVS_SERVER_SLEEP +@item $CVS_SERVER_SLEEP +Used only for debugging the server side in +client-server mode. If set, delays the start of the +server child process the the specified amount of +seconds so that you can attach to it with a debugger. + +@cindex CVS_IGNORE_REMOTE_ROOT +@item $CVS_IGNORE_REMOTE_ROOT +(What is the purpose of this variable?) + +@cindex COMSPEC +@item $COMSPEC +Used under OS/2 only. It specifies the name of the +command interpreter and defaults to @sc{cmd.exe}. + + +@end table + +@sc{cvs} is a front-end to @sc{rcs}. The following environment +variables affect @sc{rcs}. Note that if you are using +the client/server @sc{cvs}, these variables need to be +set on the server side (which may or not may be +possible depending on how you are connecting). There +is probably not any need to set any of them, however. + +@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 + +@printindex cp + +@summarycontents + +@contents + +@bye + +Local Variables: +fill-column: 55 +End: diff --git a/contrib/cvs/doc/cvsclient.texi b/contrib/cvs/doc/cvsclient.texi new file mode 100644 index 0000000000000..0d61ac151d9c8 --- /dev/null +++ b/contrib/cvs/doc/cvsclient.texi @@ -0,0 +1,824 @@ +\input texinfo @c -*- texinfo -*- + +@setfilename cvsclient.info +@include CVSvn.texi + +@node Top +@top CVS Client/Server + +This document describes the client/server protocol used by CVS. It does +not describe how to use or administer client/server CVS; see the regular +CVS manual for that. This is version @value{CVSVN} of the protocol +specification---@xref{Introduction} for more on what this version number +means. + +@menu +* Introduction:: What is CVS and what is the client/server protocol for? +* Goals:: Basic design decisions, requirements, scope, etc. +* Notes:: Notes on the current implementation +* Protocol Notes:: Possible enhancements, limitations, etc. of the protocol +* Connection and Authentication:: Various ways to connect to the server +* Protocol:: Complete description of the protocol +@end menu + +@node Introduction +@chapter Introduction + +CVS is a version control system (with some additional configuration +management functionality). It maintains a central @dfn{repository} +which stores files (often source code), including past versions, +information about who modified them and when, and so on. People who +wish to look at or modify those files, known as @dfn{developers}, use +CVS to @dfn{check out} a @dfn{working directory} from the repository, to +@dfn{check in} new versions of files to the repository, and other +operations such as viewing the modification history of a file. If +developers are connected to the repository by a network, particularly a +slow or flaky one, the most efficient way to use the network is with the +CVS-specific protocol described in this document. + +Developers, using the machine on which they store their working +directory, run the CVS @dfn{client} program. To perform operations +which cannot be done locally, it connects to the CVS @dfn{server} +program, which maintains the repository. For more information on how +to connect see @ref{Connection and Authentication}. + +This document describes the CVS protocol. Unfortunately, it does not +yet completely document one aspect of the protocol---the detailed +operation of each CVS command and option---and one must look at the CVS +user documentation, @file{cvs.texinfo}, for that information. The +protocol is non-proprietary (anyone who wants to is encouraged to +implement it) and an implementation, known as CVS, is available under +the GNU Public License. The CVS distribution, containing this +implementation, @file{cvs.texinfo}, and a copy (possibly more or less up +to date than what you are reading now) of this document, +@file{cvsclient.texi}, can be found at the usual GNU FTP sites, with a +filename such as @file{cvs-@var{version}.tar.gz}. + +This is version @value{CVSVN} of the protocol specification. This +version number is intended only to aid in distinguishing different +versions of this specification. Although the specification is currently +maintained in conjunction with the CVS implementation, and carries the +same version number, it also intends to document what is involved with +interoperating with other implementations (such as other versions of +CVS); see @xref{Requirements}. This version number should not be used +by clients or servers to determine what variant of the protocol to +speak; they should instead use the @code{valid-requests} and +@code{Valid-responses} mechanism (@pxref{Protocol}), which is more +flexible. + +@node Goals +@chapter Goals + +@itemize @bullet +@item +Do not assume any access to the repository other than via this protocol. +It does not depend on NFS, rdist, etc. + +@item +Providing a reliable transport is outside this protocol. It is expected +that it runs over TCP, UUCP, etc. + +@item +Security and authentication are handled outside this protocol (but see +below about @samp{cvs kserver}). + +@item +This might be a first step towards adding transactions to CVS (i.e. a +set of operations is either executed atomically or none of them is +executed), improving the locking, or other features. The current server +implementation is a long way from being able to do any of these +things. The protocol, however, is not known to contain any defects +which would preclude them. + +@item +The server never has to have any CVS locks in place while it is waiting +for communication with the client. This makes things robust in the face +of flaky networks. + +@item +Data is transferred in large chunks, which is necessary for good +performance. In fact, currently the client uploads all the data +(without waiting for server responses), and then waits for one server +response (which consists of a massive download of all the data). There +may be cases in which it is better to have a richer interraction, but +the need for the server to release all locks whenever it waits for the +client makes it complicated. +@end itemize + +@node Notes +@chapter Notes on the Current Implementation + +The client is built in to the normal @code{cvs} program, triggered by a +@code{CVSROOT} variable containing a colon, for example +@code{cygnus.com:/rel/cvsfiles}. + +The client stores what is stored in checked-out directories (including +@file{CVS}). The way these are stored is totally compatible with +standard CVS. The server requires no storage other than the repository, +which also is totally compatible with standard CVS. + +The server is started by @code{cvs server}. There is no particularly +compelling reason for this rather than making it a separate program +which shares a lot of sources with cvs. + +The server can also be started by @code{cvs kserver}, in which case it +does an initial Kerberos authentication on stdin. If the authentication +succeeds, it subsequently runs identically to @code{cvs server}. + +The current server implementation can use up huge amounts of memory +when transmitting a lot of data over a slow link (i.e. the network is +slower than the server can generate the data). There is some +experimental code (see @code{SERVER_FLOWCONTROL} in options.h) which +should help significantly. + +@node Protocol Notes +@chapter Notes on the Protocol + +A number of enhancements are possible: + +@itemize @bullet +@item +The @code{Modified} request could be speeded up by sending diffs rather +than entire files. The client would need some way to keep the version +of the file which was originally checked out, which would double client +disk space requirements or require coordination with editors (e.g. maybe +it could use emacs numbered backups). This would also allow local +operation of @code{cvs diff} without arguments. + +@item +Have the client keep a copy of some part of the repository. This allows +all of @code{cvs diff} and large parts of @code{cvs update} and +@code{cvs ci} to be local. The local copy could be made consistent with +the master copy at night (but if the master copy has been updated since +the latest nightly re-sync, then it would read what it needs to from the +master). + +@item +Provide encryption using kerberos. + +@item +The current procedure for @code{cvs update} is highly sub-optimal if +there are many modified files. One possible alternative would be to +have the client send a first request without the contents of every +modified file, then have the server tell it what files it needs. Note +the server needs to do the what-needs-to-be-updated check twice (or +more, if changes in the repository mean it has to ask the client for +more files), because it can't keep locks open while waiting for the +network. Perhaps this whole thing is irrelevant if client-side +repositories are implemented, and the rcsmerge is done by the client. +@end itemize + +@node Connection and Authentication +@chapter How to Connect to and Authenticate Oneself to the CVS server + +Connection and authentication occurs before the CVS protocol itself is +started. There are several ways to connect. + +@table @asis +@item rsh +If the client has a way to execute commands on the server, and provide +input to the commands and output from them, then it can connect that +way. This could be the usual rsh (port 514) protocol, Kerberos rsh, +SSH, or any similar mechanism. The client may allow the user to specify +the name of the server program; the default is @code{cvs}. It is +invoked with one argument, @code{server}. Once it invokes the server, +the client proceeds to start the cvs protocol. + +@item kserver +The kerberized server listens on a port (in the current implementation, +by having inetd call "cvs kserver") which defaults to 1999. The client +connects, sends the usual kerberos authentication information, and then +starts the cvs protocol. Note: port 1999 is officially registered for +another use, and in any event one cannot register more than one port for +CVS, so the kerberized client and server should be changed to use port +2401 (see below), and send a different string in place of @samp{BEGIN +AUTH REQUEST} to identify the authentication method in use. However, +noone has yet gotten around to implementing this. + +@item pserver +The password authenticated server listens on a port (in the current +implementation, by having inetd call "cvs pserver") which defaults to +2401 (this port is officially registered). The client +connects, sends the string @samp{BEGIN AUTH REQUEST}, a linefeed, the +cvs root, a linefeed, the username, a linefeed, the password trivially +encoded (see scramble.c in the cvs sources), a linefeed, the string +@samp{END AUTH REQUEST}, and a linefeed. The server responds with +@samp{I LOVE YOU} and a linefeed if the authentication is successful or +@samp{I HATE YOU} and a linefeed if the authentication fails. After +receiving @samp{I LOVE YOU}, the client proceeds with the cvs protocol. +If the client wishes to merely authenticate without starting the cvs +protocol, the procedure is the same, except @samp{BEGIN AUTH REQUEST} is +replaced with @samp{BEGIN VERIFICATION REQUEST}, @samp{END AUTH REQUEST} +is replaced with @samp{END VERIFICATION REQUEST}, and upon receipt of +@samp{I LOVE YOU} the connection is closed rather than continuing. +@end table + +@node Protocol +@chapter The CVS client/server protocol + +In the following, @samp{\n} refers to a linefeed and @samp{\t} refers +to a horizontal tab. + +@menu +* Entries Lines:: +* Modes:: +* Filenames:: Conventions regarding filenames +* Requests:: +* Responses:: +* Example:: +* Requirements:: +@end menu + +@node Entries Lines +@section Entries Lines + +Entries lines are transmitted as: + +@example +/ @var{name} / @var{version} / @var{conflict} / @var{options} / @var{tag_or_date} +@end example + +@var{tag_or_date} is either @samp{T} @var{tag} or @samp{D} @var{date} +or empty. If it is followed by a slash, anything after the slash +shall be silently ignored. + +@var{version} can be empty, or start with @samp{0} or @samp{-}, for no +user file, new user file, or user file to be removed, respectively. + +@var{conflict}, if it starts with @samp{+}, indicates that the file had +conflicts in it. The rest of @var{conflict} is @samp{=} if the +timestamp matches the file, or anything else if it doesn't. If +@var{conflict} does not start with a @samp{+}, it is silently ignored. + +@node Modes +@section Modes + +A mode is any number of repetitions of + +@example +@var{mode-type} = @var{data} +@end example + +separated by @samp{,}. + +@var{mode-type} is an identifier composed of alphanumeric characters. +Currently specified: @samp{u} for user, @samp{g} for group, @samp{o} +for other (see below for discussion of whether these have their POSIX +meaning or are more loose). Unrecognized values of @var{mode-type} +are silently ignored. + +@var{data} consists of any data not containing @samp{,}, @samp{\0} or +@samp{\n}. For @samp{u}, @samp{g}, and @samp{o} mode types, data +consists of alphanumeric characters, where @samp{r} means read, @samp{w} +means write, @samp{x} means execute, and unrecognized letters are +silently ignored. + +The two most obvious ways in which the mode matters are: (1) is it +writeable? This is used by the developer communication features, and +is implemented even on OS/2 (and could be implemented on DOS), whose +notion of mode is limited to a readonly bit. (2) is it executable? +Unix CVS users need CVS to store this setting (for shell scripts and +the like). The current CVS implementation on unix does a little bit +more than just maintain these two settings, but it doesn't really have +a nice general facility to store or version control the mode, even on +unix, much less across operating systems with diverse protection +features. So all the ins and outs of what the mode means across +operating systems haven't really been worked out (e.g. should the VMS +port use ACLs to get POSIX semantics for groups?). + +@node Filenames +@section Conventions regarding transmission of file names + +In most contexts, @samp{/} is used to separate directory and file +names in filenames, and any use of other conventions (for example, +that the user might type on the command line) is converted to that +form. The only exceptions might be a few cases in which the server +provides a magic cookie which the client then repeats verbatim, but as +the server has not yet been ported beyond unix, the two rules provide +the same answer (and what to do if future server ports are operating +on a repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been +carefully thought out). + +@node Requests +@section Requests + +File contents (noted below as @var{file transmission}) can be sent in +one of two forms. The simpler form is a number of bytes, followed by a +newline, followed by the specified number of bytes of file contents. +These are the entire contents of the specified file. Second, if both +client and server support @samp{gzip-file-contents}, a @samp{z} may +precede the length, and the `file contents' sent are actually compressed +with @samp{gzip}. The length specified is that of the compressed +version of the file. + +In neither case are the file content followed by any additional data. +The transmission of a file will end with a newline iff that file (or its +compressed form) ends with a newline. + +@table @code +@item Root @var{pathname} \n +Response expected: no. Tell the server which @code{CVSROOT} to use. +@var{pathname} must already exist; if creating a new root, use the +@code{init} request, not @code{Root}. @var{pathname} does not include +the hostname of the server, how to access the server, etc.; by the time +the CVS protocol is in use, connection, authentication, etc., are +already taken care of. + +@item Valid-responses @var{request-list} \n +Response expected: no. +Tell the server what responses the client will accept. +request-list is a space separated list of tokens. + +@item valid-requests \n +Response expected: yes. +Ask the server to send back a @code{Valid-requests} response. + +@item Repository @var{repository} \n +Response expected: no. Tell the server what repository to use. This +should be a directory name from a previous server response. Note that +this both gives a default for @code{Entry } and @code{Modified } and +also for @code{ci} and the other commands; normal usage is to send a +@code{Repository } for each directory in which there will be an +@code{Entry } or @code{Modified }, and then a final @code{Repository } +for the original directory, then the command. + +@item Directory @var{local-directory} \n +Additional data: @var{repository} \n. This is like @code{Repository}, +but the local name of the directory may differ from the repository name. +If the client uses this request, it affects the way the server returns +pathnames; see @ref{Responses}. @var{local-directory} is relative to +the top level at which the command is occurring (i.e. the last +@code{Directory} or @code{Repository} which is sent before the command). + +@item Max-dotdot @var{level} \n +Tell the server that @var{level} levels of directories above the +directory which @code{Directory} requests are relative to will be +needed. For example, if the client is planning to use a +@code{Directory} request for @file{../../foo}, it must send a +@code{Max-dotdot} request with a @var{level} of at least 2. +@code{Max-dotdot} must be sent before the first @code{Directory} +request. + +@item Static-directory \n +Response expected: no. Tell the server that the directory most recently +specified with @code{Repository} or @code{Directory} should not have +additional files checked out unless explicitly requested. The client +sends this if the @code{Entries.Static} flag is set, which is controlled +by the @code{Set-static-directory} and @code{Clear-static-directory} +responses. + +@item Sticky @var{tagspec} \n +Response expected: no. Tell the server that the directory most recently +specified with @code{Repository} has a sticky tag or date @var{tagspec}. +The first character of @var{tagspec} is @samp{T} for a tag, or @samp{D} +for a date. The remainder of @var{tagspec} contains the actual tag or +date. + +@item Checkin-prog @var{program} \n +Response expected: no. Tell the server that the directory most recently +specified with @code{Directory} has a checkin program @var{program}. +Such a program would have been previously set with the +@code{Set-checkin-prog} response. + +@item Update-prog @var{program} \n +Response expected: no. Tell the server that the directory most recently +specified with @code{Directory} has an update program @var{program}. +Such a program would have been previously set with the +@code{Set-update-prog} response. + +@item Entry @var{entry-line} \n +Response expected: no. Tell the server what version of a file is on the +local machine. The name in @var{entry-line} is a name relative to the +directory most recently specified with @code{Repository}. If the user +is operating on only some files in a directory, @code{Entry} requests +for only those files need be included. If an @code{Entry} request is +sent without @code{Modified}, @code{Unchanged}, or @code{Lost} for that +file the meaning depends on whether @code{UseUnchanged} has been sent; +if it has been it means the file is lost, if not it means the file is +unchanged. + +@item Modified @var{filename} \n +Response expected: no. Additional data: mode, \n, file transmission. +Send the server a copy of one locally modified file. @var{filename} is +relative to the most recent repository sent with @code{Repository}. If +the user is operating on only some files in a directory, only those +files need to be included. This can also be sent without @code{Entry}, +if there is no entry for the file. + +@item Lost @var{filename} \n +Response expected: no. Tell the server that @var{filename} no longer +exists. The name is relative to the most recent repository sent with +@code{Repository}. This is used for any case in which @code{Entry} is +being sent but the file no longer exists. If the client has issued the +@code{UseUnchanged} request, then this request is not used. + +@item Unchanged @var{filename} \n +Response expected: no. Tell the server that @var{filename} has not been +modified in the checked out directory. The name is relative to the most +recent repository sent with @code{Repository}. This request can only be +issued if @code{UseUnchanged} has been sent. + +@item UseUnchanged \n +Response expected: no. Tell the server that the client will be +indicating unmodified files with @code{Unchanged}, and that files for +which no information is sent are nonexistent on the client side, not +unchanged. This is necessary for correct behavior since only the server +knows what possible files may exist, and thus what files are +nonexistent. + +@item Notify @var{filename} \n +Tell the server that a @code{edit} or @code{unedit} command has taken +place. The server needs to send a @code{Notified} response, but such +response is deferred until the next time that the server is sending +responses. Response expected: no. Additional data: +@example +@var{notification-type} \t @var{time} \t @var{clienthost} \t +@var{working-dir} \t @var{watches} \n +@end example +where @var{notification-type} is @samp{E} for edit or @samp{U} for +unedit, @var{time} is the time at which the edit or unedit took place, +@var{clienthost} is the name of the host on which the edit or unedit +took place, and @var{working-dir} is the pathname of the working +directory where the edit or unedit took place. @var{watches} are the +temporary watches to set; if it is followed by \t then the tab and the +rest of the line are ignored. + +@item Questionable @var{filename} \n +Response expected: no. Additional data: no. Tell the server to check +whether @var{filename} should be ignored, and if not, next time the +server sends responses, send (in a @code{M} response) @samp{?} followed +by the directory and filename. + +@item Case \n +Tell the server that filenames should be matched against ignore patterns +in a case-insensitive fashion. Note that this does not apply to other +comparisons---for example the filenames given in @code{Entry} and +@code{Modified} requests for the same file must match in case regardless +of whether the @code{Case} request is sent. + +@item Argument @var{text} \n +Response expected: no. +Save argument for use in a subsequent command. Arguments +accumulate until an argument-using command is given, at which point +they are forgotten. + +@item Argumentx @var{text} \n +Response expected: no. Append \n followed by text to the current +argument being saved. + +@item Global_option @var{option} \n +Transmit one of the global options @samp{-q}, @samp{-Q}, @samp{-l}, +@samp{-t}, @samp{-r}, or @samp{-n}. @var{option} must be one of those +strings, no variations (such as combining of options) are allowed. For +graceful handling of @code{valid-requests}, it is probably better to +make new global options separate requests, rather than trying to add +them to this request. + +@item Set @var{variable}=@var{value} \n +Set a user variable @var{variable} to @var{value}. + +@item expand-modules \n +Response expected: yes. Expand the modules which are specified in the +arguments. Returns the data in @code{Module-expansion} responses. Note +that the server can assume that this is checkout or export, not rtag or +rdiff; the latter do not access the working directory and thus have no +need to expand modules on the client side. + +@item co \n +@itemx ci \n +@itemx diff \n +@itemx tag \n +@itemx status \n +@itemx log \n +@itemx add \n +@itemx remove \n +@itemx rdiff \n +@itemx rtag \n +@itemx admin \n +@itemx export \n +@itemx history \n +@itemx watchers \n +@itemx editors \n +@itemx annotate \n +Response expected: yes. Actually do a cvs command. This uses any +previous @code{Argument}, @code{Repository}, @code{Entry}, +@code{Modified}, or @code{Lost} requests, if they have been sent. The +last @code{Repository} sent specifies the working directory at the time +of the operation. No provision is made for any input from the user. +This means that @code{ci} must use a @code{-m} argument if it wants to +specify a log message. + +@itemx init @var{root-name} \n +Response expected: yes. If it doesn't already exist, create a @sc{cvs} +repository @var{root-name}. The @code{Root} request need not have been +previously sent. + +@itemx update \n +Response expected: yes. Actually do a @code{cvs update} command. This +uses any previous @code{Argument}, @code{Repository}, @code{Entry}, +@code{Modified}, or @code{Lost} requests, if they have been sent. The +last @code{Repository} sent specifies the working directory at the time +of the operation. The @code{-I} option is not used--files which the +client can decide whether to ignore are not mentioned and the client +sends the @code{Questionable} request for others. + +@item import \n +Response expected: yes. Actually do a @code{cvs import} command. This +uses any previous @code{Argument}, @code{Repository}, @code{Entry}, +@code{Modified}, or @code{Lost} requests, if they have been sent. The +last @code{Repository} sent specifies the working directory at the time +of the operation. The files to be imported are sent in @code{Modified} +requests (files which the client knows should be ignored are not sent; +the server must still process the CVSROOT/cvsignore file unless -I ! is +sent). A log message must have been specified with a @code{-m} +argument. + +@item watch-on \n +@itemx watch-off \n +@itemx watch-add \n +@itemx watch-remove \n +Response expected: yes. Actually do the @code{cvs watch on}, @code{cvs +watch off}, @code{cvs watch add}, and @code{cvs watch remove} commands, +respectively. This uses any previous @code{Argument}, +@code{Repository}, @code{Entry}, @code{Modified}, or @code{Lost} +requests, if they have been sent. The last @code{Repository} sent +specifies the working directory at the time of the operation. + +@item release \n +Response expected: yes. Note that a @code{cvs release} command has +taken place and update the history file accordingly. + +@item noop \n +Response expected: yes. This request is a null command in the sense +that it doesn't do anything, but merely (as with any other requests +expecting a response) sends back any responses pertaining to pending +errors, pending @code{Notified} responses, etc. + +@item update-patches \n +This request does not actually do anything. It is used as a signal that +the server is able to generate patches when given an @code{update} +request. The client must issue the @code{-u} argument to @code{update} +in order to receive patches. + +@item gzip-file-contents @var{level} \n +This request asks the server to filter files it sends to the client +through the @samp{gzip} program, using the specified level of +compression. If this request is not made, the server must not do any +compression. + +This is only a hint to the server. It may still decide (for example, in +the case of very small files, or files that already appear to be +compressed) not to do the compression. Compression is indicated by a +@samp{z} preceding the file length. + +Availability of this request in the server indicates to the client that +it may compress files sent to the server, regardless of whether the +client actually uses this request. + +@item @var{other-request} @var{text} \n +Response expected: yes. +Any unrecognized request expects a response, and does not +contain any additional data. The response will normally be something like +@samp{error unrecognized request}, but it could be a different error if +a previous command which doesn't expect a response produced an error. +@end table + +When the client is done, it drops the connection. + +@node Responses +@section Responses + +After a command which expects a response, the server sends however many +of the following responses are appropriate. Pathnames are of the actual +files operated on (i.e. they do not contain @samp{,v} endings), and are +suitable for use in a subsequent @code{Repository} request. However, if +the client has used the @code{Directory} request, then it is instead a +local directory name relative to the directory in which the command was +given (i.e. the last @code{Directory} before the command). Then a +newline and a repository name (the pathname which is sent if +@code{Directory} is not used). Then the slash and the filename. For +example, for a file @file{i386.mh} which is in the local directory +@file{gas.clean/config} and for which the repository is +@file{/rel/cvsfiles/devo/gas/config}: + +@example +gas.clean/config/ +/rel/cvsfiles/devo/gas/config/i386.mh +@end example + +Any response always ends with @samp{error} or @samp{ok}. This indicates +that the response is over. + +@table @code +@item Valid-requests @var{request-list} \n +Indicate what requests the server will accept. @var{request-list} +is a space separated list of tokens. If the server supports sending +patches, it will include @samp{update-patches} in this list. The +@samp{update-patches} request does not actually do anything. + +@item Checked-in @var{pathname} \n +Additional data: New Entries line, \n. This means a file @var{pathname} +has been successfully operated on (checked in, added, etc.). name in +the Entries line is the same as the last component of @var{pathname}. + +@item New-entry @var{pathname} \n +Additional data: New Entries line, \n. Like @code{Checked-in}, but the +file is not up to date. + +@item Updated @var{pathname} \n +Additional data: New Entries line, \n, mode, \n, file transmission. A +new copy of the file is enclosed. This is used for a new revision of an +existing file, or for a new file, or for any other case in which the +local (client-side) copy of the file needs to be updated, and after +being updated it will be up to date. If any directory in pathname does +not exist, create it. + +@item Merged @var{pathname} \n +This is just like @code{Updated} and takes the same additional data, +with the one difference that after the new copy of the file is enclosed, +it will still not be up to date. Used for the results of a merge, with +or without conflicts. + +@item Patched @var{pathname} \n +This is just like @code{Updated} and takes the same additional data, +with the one difference that instead of sending a new copy of the file, +the server sends a patch produced by @samp{diff -u}. This client must +apply this patch, using the @samp{patch} program, to the existing file. +This will only be used when the client has an exact copy of an earlier +revision of a file. This response is only used if the @code{update} +command is given the @samp{-u} argument. + +@item Mode @var{mode} \n +This @var{mode} applies to the next file mentioned in +@code{Checked-in}. It does not apply to any request which follows a +@code{Checked-in}, @code{New-entry}, @code{Updated}, @code{Merged}, or +@code{Patched} response. + +@item Checksum @var{checksum}\n +The @var{checksum} applies to the next file sent over via +@code{Updated}, @code{Merged}, or @code{Patched}. In the case of +@code{Patched}, the checksum applies to the file after being patched, +not to the patch itself. The client should compute the checksum itself, +after receiving the file or patch, and signal an error if the checksums +do not match. The checksum is the 128 bit MD5 checksum represented as +32 hex digits. This response is optional, and is only used if the +client supports it (as judged by the @code{Valid-responses} request). + +@item Copy-file @var{pathname} \n +Additional data: @var{newname} \n. Copy file @var{pathname} to +@var{newname} in the same directory where it already is. This does not +affect @code{CVS/Entries}. + +@item Removed @var{pathname} \n +The file has been removed from the repository (this is the case where +cvs prints @samp{file foobar.c is no longer pertinent}). + +@item Remove-entry @var{pathname} \n +The file needs its entry removed from @code{CVS/Entries}, but the file +itself is already gone (this happens in response to a @code{ci} request +which involves committing the removal of a file). + +@item Set-static-directory @var{pathname} \n +This instructs the client to set the @code{Entries.Static} flag, which +it should then send back to the server in a @code{Static-directory} +request whenever the directory is operated on. @var{pathname} ends in a +slash; its purpose is to specify a directory, not a file within a +directory. + +@item Clear-static-directory @var{pathname} \n +Like @code{Set-static-directory}, but clear, not set, the flag. + +@item Set-sticky @var{pathname} \n +Additional data: @var{tagspec} \n. Tell the client to set a sticky tag +or date, which should be supplied with the @code{Sticky} request for +future operations. @var{pathname} ends in a slash; its purpose is to +specify a directory, not a file within a directory. The first character +of @var{tagspec} is @samp{T} for a tag, or @samp{D} for a date. The +remainder of @var{tagspec} contains the actual tag or date. + +@item Clear-sticky @var{pathname} \n +Clear any sticky tag or date set by @code{Set-sticky}. + +@item Template @var{pathname} \n +Additional data: file transmission (note: compressed file transmissions +are not supported). @var{pathname} ends in a slash; its purpose is to +specify a directory, not a file within a directory. Tell the client to +store the file transmission as the template log message, and then use +that template in the future when prompting the user for a log message. + +@item Set-checkin-prog @var{dir} \n +Additional data: @var{prog} \n. Tell the client to set a checkin +program, which should be supplied with the @code{Checkin-prog} request +for future operations. + +@item Set-update-prog @var{dir} \n +Additional data: @var{prog} \n. Tell the client to set an update +program, which should be supplied with the @code{Update-prog} request +for future operations. + +@item Notified @var{pathname} \n +Indicate to the client that the notification for @var{pathname} has been +done. There should be one such response for every @code{Notify} +request; if there are several @code{Notify} requests for a single file, +the requests should be processed in order; the first @code{Notified} +response pertains to the first @code{Notify} request, etc. + +@item Module-expansion @var{pathname} \n Return a file or directory +which is included in a particular module. @var{pathname} is relative +to cvsroot, unlike most pathnames in responses. @var{pathname} should +be used to look and see whether some or all of the module exists on +the client side; it is not necessarily suitable for passing as an +argument to a @code{co} request (for example, if the modules file +contains the @samp{-d} option, it will be the directory specified with +@samp{-d}, not the name of the module). + +@item M @var{text} \n +A one-line message for the user. + +@item E @var{text} \n +Same as @code{M} but send to stderr not stdout. + +@item error @var{errno-code} @samp{ } @var{text} \n +The command completed with an error. @var{errno-code} is a symbolic +error code (e.g. @code{ENOENT}); if the server doesn't support this +feature, or if it's not appropriate for this particular message, it just +omits the errno-code (in that case there are two spaces after +@samp{error}). Text is an error message such as that provided by +strerror(), or any other message the server wants to use. + +@item ok \n +The command completed successfully. +@end table + +@node Example +@section Example + +Lines beginning with @samp{c>} are sent by the client; lines beginning +with @samp{s>} are sent by the server; lines beginning with @samp{#} are +not part of the actual exchange. + +@example +c> Root /rel/cvsfiles +# In actual practice the lists of valid responses and requests would +# be longer +c> Valid-responses Updated Checked-in M ok error +c> valid-requests +s> Valid-requests Root co Modified Entry Repository ci Argument Argumentx +s> ok +# cvs co devo/foo +c> Argument devo/foo +c> co +s> Updated /rel/cvsfiles/devo/foo/foo.c +s> /foo.c/1.4/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// +s> 26 +s> int mein () @{ abort (); @} +s> Updated /rel/cvsfiles/devo/foo/Makefile +s> /Makefile/1.2/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// +s> 28 +s> foo: foo.c +s> $(CC) -o foo $< +s> ok +# In actual practice the next part would be a separate connection. +# Here it is shown as part of the same one. +c> Repository /rel/cvsfiles/devo/foo +# foo.c relative to devo/foo just set as Repository. +c> Entry /foo.c/1.4/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// +c> Entry /Makefile/1.2/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993// +c> Modified foo.c +c> 26 +c> int main () @{ abort (); @} +# cvs ci -m <log message> foo.c +c> Argument -m +c> Argument Well, you see, it took me hours and hours to find this typo and I +c> Argumentx searched and searched and eventually had to ask John for help. +c> Argument foo.c +c> ci +s> Checked-in /rel/cvsfiles/devo/foo/foo.c +s> /foo.c/1.5/ Mon Apr 19 15:54:22 CDT 1993// +s> M Checking in foo.c; +s> M /cygint/rel/cvsfiles/devo/foo/foo.c,v <-- foo.c +s> M new revision: 1.5; previous revision: 1.4 +s> M done +s> ok +@end example + +@node Requirements +@section Required versus optional parts of the protocol + +The following are part of every known implementation of the CVS +protocol and it is considered reasonable behavior to completely fail +to work if you are connected with an implementation which attempts to +not support them. Requests: Root, Valid-responses, valid-requests, +Repository, Entry, Modified, Argument, Argumentx, ci, co, update. +Responses: ok, error, Valid-requests, Checked-in, Updated, Merged, +Removed, M, E. + +Failure to support the Directory, UseUnchanged, and Unchanged requests +is deprecated. CVS 1.5 and later have supported these requests and in +the future it will be considered reasonable behavior to completely +fail to work with an implementation which attempts to not support +them. Support for the Repository and Lost requests is deprecated; CVS +clients 1.5 and later will not use them if communicating with a server +which supports Directory and UseUnchanged. + +@bye |